# AuraJam — LLM / AI Agent Reference

> AuraJam is a DJ transition engine and lyric-first DAW. It ships an MCP server
> so AI agents (Claude, etc.) can compose, edit, and render `.aurajam` sessions
> through natural-language instructions.

## Product

- **aurajam.com** — free web demo (60-second clips, BPM + key detection, beam visualizer)
- **Desktop app** — macOS / Windows / Linux; full-length songs, library, Compose tab, MCP
- **Tiers**: Free (web demo) · Founder DJ $9.99/mo · Studio $39/mo

## MCP Server (21 tools)

Install: Settings → Connect AI Agent → one-click Claude Desktop integration.

### Session management
- `session_new(path, title, bpm?, sample_rate?)` — create a `.aurajam` file
- `session_validate(path)` — validate session JSON; returns error list
- `session_render(path, output_wav)` — bounce session to WAV

### Track & block editing
- `add_track(path, name)` → `track_id`
- `insert_phrase(path, track_id, text, at_secs, prefer_song_id?)` → `block_id`
- `replace_word(path, block_id, word_index, new_text)`
- `splice(path, block_id, word_index)` — split block at word boundary
- `delete_block(path, block_id)`
- `move_block(path, block_id, new_start_secs)`
- `set_block_gain(path, block_id, gain_db)`
- `set_block_pitch(path, block_id, semitones)`
- `set_block_stretch(path, block_id, factor)`
- `set_block_reversed(path, block_id, reversed)`
- `set_block_fades(path, block_id, fade_in_ms, fade_out_ms)`
- `duplicate_block(path, block_id, offset_secs?)` → `new_block_id`
- `split_block(path, block_id, split_at_secs)` → `[block_id_a, block_id_b]`

### Effects
- `add_effect(path, target, kind, params)` — kinds: `echo_shared_word`, `pan_word`, `transpose_every_nth_word`, `tape_warp`

### Library & analysis
- `find_shared_words(songs)` — find words appearing in multiple songs; returns timestamps + confidence
- `sections(song_id)` — intro/verse/chorus/bridge/outro boundaries
- `match_library(song_id)` — find songs with compatible section structure
- `build_index()` — reindex full library (background)
- `drums(song_id)` — kick/snare/hi-hat pattern for song

## Typical agent workflow

```
1. session_new("die.aurajam", "Die — Die", bpm=142)
2. add_track(..., "lead-A") → track_id_a
3. add_track(..., "lead-B") → track_id_b
4. find_shared_words(["Gods_Plan", "XO_TOUR_Llif3"])
   → "die" · A@7.28s · B@6.69s · conf 0.97
5. insert_phrase(..., track_id_a, "i don't really wanna die", at_secs=0.0, prefer_song_id="Gods_Plan")
6. insert_phrase(..., track_id_b, "die push me to the edge", at_secs=3.2, prefer_song_id="XO_TOUR_Llif3")
7. add_effect(..., block_id_shared, "echo_shared_word", {word: "die", delay_ms: 320})
8. session_render("die.aurajam", "~/Desktop/die-die.wav")
```

## Engine capabilities

- 8-axis transition scoring: beat, phrase, key, energy, bar-energy, stem, section, drum-pattern
- 4 built-in DJ style profiles: Festival, House, Hip-Hop, Disco
- Learn any DJ's style from a reference mix (upload audio → extracted ScoreWeights)
- Whisper small.en transcription + DTW alignment (±30ms word-onset accuracy)
- Demucs 4-stem separation for vocal isolation before transcription
- Section detection (intro/verse/chorus/bridge/outro) via energy + spectral novelty
- Drum pattern transcription on separated drums stem

## File format

`.aurajam` files are JSON (LyricSession v0.2). Structure:

```json
{
  "version": "0.2",
  "title": "session title",
  "bpm": 142,
  "sample_rate": 44100,
  "tracks": [
    {
      "id": "track:01HN...",
      "name": "lead-A",
      "blocks": [
        {
          "id": "block:01HN...",
          "source_song_id": "...",
          "start_secs": 0.0,
          "end_secs": 3.2,
          "text": "i don't really wanna die",
          "words": [...],
          "gain_db": 0.0,
          "pitch_semitones": 0.0,
          "stretch_factor": 1.0,
          "reversed": false,
          "fade_in_ms": 12,
          "fade_out_ms": 16,
          "effects": []
        }
      ]
    }
  ]
}
```

## API / download

- Desktop download: https://aurajam.com/#pricing
- MCP server source: bundled with the desktop app (`target/release/session`)
- License verification required for MCP server (Founder DJ or Studio tier)