┌─────────────────────────────────────────────────────────────┐
│             LLM / Agent (LM Studio, Claude, Codex)           │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP Protocol (stdio / sse)
┌──────────────────────────────▼──────────────────────────────┐
│                      DJ-MCP Server Layer                    │
│   - Strict Pydantic Schemas   - Structured Error Responses  │
│   - Actionable Next Steps     - Sequential Workflows        │
├─────────────────────────────────────────────────────────────┤
│                      Session & Project                      │
│   - Non-Destructive Timeline  - Decks & Crossfader State    │
│   - Mixer Channels & Sends    - Snapshot / Rollback Journal │
├──────────────────────────────┬──────────────────────────────┤
│               Core Audio & Analysis Engines                 │
│   ┌──────────────────────────┼──────────────────────────┐   │
│   │   Spotify Pedalboard     │         Librosa          │   │
│   │   (JUCE C++ Native DSP)  │  (BPM, Key, Transients)  │   │
│   ├──────────────────────────┼──────────────────────────┤   │
│   │      PyLoudnorm          │      Meta AI Demucs      │   │
│   │  (ITU-R BS.1770-4 LUFS)  │ (Neural Stem Separation) │   │
│   ├──────────────────────────┼──────────────────────────┤   │
│   │   Rubber Band / Soxr     │     FFmpeg & Soundfile   │   │
│   │ (Time-Stretch & Pitch)   │   (Lossless Audio I/O)   │   │
│   └──────────────────────────┴──────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

git clone https://github.com/antigravity-audio/dj-mcp.git
cd dj-mcp
pip install -e .

dj-mcp download-models

dj-mcp doctor

============================================================
DJ-MCP SYSTEM DOCTOR DIAGNOSTIC REPORT
============================================================
Overall Status   : HEALTHY
Operating System : Linux (x86_64)
Python Version   : 3.13.12
CPU Cores        : 12
RAM Total/Avail  : 15.28 GB / 11.1 GB
GPU Available    : True (cuda)
------------------------------------------------------------
ENGINES & DSP:
  [✓ INSTALLED ] ffmpeg         : Audio container decoding, encoding, format conversion
  [✓ INSTALLED ] soundfile      : Sample-accurate uncompressed PCM and lossless I/O
  [✓ INSTALLED ] pedalboard     : Native C++ JUCE DSP effects (EQ, filters, compressor, limiter, reverb, delay)
  [✓ INSTALLED ] librosa        : BPM, beat-grid, onset/transient, chroma and key detection
  [✓ INSTALLED ] pyloudnorm     : ITU-R BS.1770-4 / EBU R128 integrated and momentary LUFS loudness analysis
  [✓ INSTALLED ] demucs         : High-fidelity neural source separation (vocals, drums, bass, other)
  [✓ INSTALLED ] rubberband     : High-quality time-stretching and pitch shifting
------------------------------------------------------------
CODECS & FORMATS:
  [✓ SUPPORTED   ] WAV
  [✓ SUPPORTED   ] FLAC
  [✓ SUPPORTED   ] AIFF
  [✓ SUPPORTED   ] OGG
  [✓ SUPPORTED   ] MP3
  [✓ SUPPORTED   ] AAC
------------------------------------------------------------
Disk Free Space  : 94441 MB
Cache Directory  : /home/igris/dj-mcp/.dj_cache (Writable: True)
Temp Directory   : /home/igris/dj-mcp/.dj_temp (Writable: True)
============================================================

dj-mcp doctor --json

dj-mcp.server

dj-mcp server --transport stdio

dj-mcp server --transport sse --host 0.0.0.0 --port 8080

{
  "mcpServers": {
    "dj-mcp": {
      "command": "dj-mcp.server",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "mcpServers": {
    "dj-mcp": {
      "command": "dj-mcp.server",
      "args": ["--transport", "stdio"]
    }
  }
}

{
  "servers": {
    "dj-mcp": {
      "command": "dj-mcp.server"
    }
  }
}

from pathlib import Path
from ai_dj import (
    Session,
    AudioClip,
    Track,
    MasteringProcessor,
    get_default_config,
)
from ai_dj.export import export_audio_to_file

# 1. Initialize session and project
config = get_default_config()
session = Session(config)
project = session.create_project(project_id="quickstart", name="Quickstart Project", sample_rate=44100)

# 2. Import and analyze audio
track_file = Path("samples/drop.wav")
lib_track = session.library.import_track(track_file, track_id="drop")
analysis = session.library.analyze_track("drop")

print(f"BPM: {analysis['bpm']}, Key: {analysis['key']} ({analysis['camelot']})")
print(f"Loudness: {analysis['loudness']['integrated_lufs']} LUFS")

# 3. Create a timeline track and non-destructive clip
track = Track(track_id="t_lead", name="Lead Track", channel_id="ch_lead")
clip = AudioClip(
    clip_id="c_lead_1",
    name="Lead Drop",
    source_file=track_file,
    source_offset_sec=0.0,
    timeline_position_sec=0.0,
    duration_sec=16.0,
    gain_db=-1.5,
    fade_in_sec=0.05,
    fade_out_sec=0.5,
)
track.add_clip(clip)
project.timeline.add_track(track)

# 4. Render unmastered timeline mix
raw_mix = session.renderer.render_timeline(
    project.timeline,
    project.mixer,
    start_sec=0.0,
    end_sec=16.0,
)

# 5. Master to Spotify/Apple Music streaming standards (-14 LUFS, -1.0 dBTP ceiling)
masterer = MasteringProcessor(profile="streaming", target_lufs=-14.0, true_peak_ceiling_db=-1.0)
mastered_audio, stats = masterer.process_audio(raw_mix, sample_rate=44100)

print(f"Mastered Loudness: {stats['final_lufs']} LUFS, Peak: {stats['final_peak_dbfs']} dBFS")

# 6. Export lossless FLAC
out_path = Path("exports/mastered_drop.flac")
export_audio_to_file(mastered_audio, out_path, sample_rate=44100, bit_depth=24, audio_format="flac")
print(f"Exported to: {out_path}")

from ai_dj import get_active_session
from ai_dj.mcp.tools import (
    tool_project_create,
    tool_library_import,
    tool_track_analyze,
    tool_create_beatgrid,
    tool_deck_load,
    tool_deck_play,
    tool_deck_sync,
    tool_loop_create,
    tool_mixer_crossfade,
    tool_render_project,
)

# 1. Create project
tool_project_create(project_id="dj_mix", name="Club Set", sample_rate=44100, num_decks=2)

# 2. Import tracks
tool_library_import(file_path="music/house_a.wav", track_id="track_a")
tool_library_import(file_path="music/house_b.wav", track_id="track_b")

# 3. Analyze BPM and generate beatgrids
res_a = tool_track_analyze(track_id="track_a")["result"]
res_b = tool_track_analyze(track_id="track_b")["result"]

tool_create_beatgrid(track_id="track_a", bpm=res_a["bpm"], first_beat_sec=res_a["first_beat_sec"])
tool_create_beatgrid(track_id="track_b", bpm=res_b["bpm"], first_beat_sec=res_b["first_beat_sec"])

# 4. Load Deck A and Deck B
tool_deck_load(deck_id="deck_a", track_id="track_a")
tool_deck_load(deck_id="deck_b", track_id="track_b")

# 5. Sync Deck B to Deck A's tempo and phase
tool_deck_sync(deck_id="deck_b", master_deck_id="deck_a")

# 6. Establish a 4-beat transition loop on Deck A
tool_loop_create(deck_id="deck_a", length_beats=4.0, start_sec=16.0)

# 7. Start playback and crossfade from Deck A to Deck B
tool_deck_play(deck_id="deck_a")
tool_deck_play(deck_id="deck_b")

# Move crossfader from Left (-1.0) to Center (0.0) to Right (+1.0)
tool_mixer_crossfade(position=0.0, curve="equal_power")
tool_mixer_crossfade(position=1.0, curve="smooth")

from ai_dj.mcp.tools import (
    tool_clip_create,
    tool_clip_split,
    tool_clip_move,
    tool_clip_time_stretch,
    tool_clip_pitch,
    tool_clip_fade,
)

# 1. Place a 30-second source segment onto timeline at 0.0s
tool_clip_create(
    track_id="t_vocal",
    clip_id="vocal_hook",
    source_file="vocals.wav",
    timeline_position_sec=0.0,
    source_offset_sec=10.0,
    duration_sec=8.0,
)

# 2. Split into two 4-second clips
tool_clip_split(
    track_id="t_vocal",
    clip_id="vocal_hook",
    split_offset_sec=4.0,
    new_clip_id="vocal_hook_pt2",
)

# 3. Time stretch second half by 1.25x and shift pitch up +2 semitones
tool_clip_time_stretch(track_id="t_vocal", clip_id="vocal_hook_pt2", rate=1.25)
tool_clip_pitch(track_id="t_vocal", clip_id="vocal_hook_pt2", semitones=2.0)

# 4. Apply a 50ms fade-in to eliminate clicks
tool_clip_fade(track_id="t_vocal", clip_id="vocal_hook_pt2", fade_in_sec=0.05, fade_out_sec=0.2)

from ai_dj.mcp.tools import (
    tool_separate_stems,
    tool_job_status,
    tool_stem_mute,
    tool_stem_solo,
    tool_stem_gain,
    tool_stem_export,
)

# 1. Launch stem separation as a background job
job_resp = tool_separate_stems(audio_path="song.wav", output_dir="stems/song_stems", model_name="htdemucs")
job_id = job_resp["job_id"]
print(f"Background Job ID: {job_id}")

# 2. Check job progress
status = tool_job_status(job_id=job_id)
print(f"Status: {status['result']['status']}, Progress: {status['result']['progress']}%")

# 3. Once complete, adjust individual stem levels (e.g. acapella extract)
tool_stem_mute(set_id="song_stems", stem_name="drums", mute=True)
tool_stem_mute(set_id="song_stems", stem_name="bass", mute=True)
tool_stem_mute(set_id="song_stems", stem_name="other", mute=True)
tool_stem_solo(set_id="song_stems", stem_name="vocals", solo=True)
tool_stem_gain(set_id="song_stems", stem_name="vocals", gain_db=2.5)

# 4. Recombine and export the isolated vocal track
tool_stem_export(set_id="song_stems", output_path="exports/isolated_vocals.wav")

from ai_dj.mcp.tools import (
    tool_master_process,
    tool_master_validate,
)

# Option A: Streaming Profile (-14.0 LUFS, -1.0 dBTP ceiling)
stream_res = tool_master_process(
    input_file="mixdown.wav",
    output_file="masters/streaming_master.wav",
    profile="streaming",
)
print("Streaming Master Stats:", stream_res["result"]["stats"])

# Validate against standard
val_stream = tool_master_validate(file_path="masters/streaming_master.wav", target_profile="streaming")
assert val_stream["result"]["is_compliant"] is True

# Option B: High-Energy Club/DJ Master (-9.0 LUFS, -0.3 dBTP ceiling)
club_res = tool_master_process(
    input_file="mixdown.wav",
    output_file="masters/club_master.wav",
    profile="dj_master",
    true_peak_ceiling_db=-0.3,
)
print("Club Master Stats:", club_res["result"]["stats"])

{
  "success": false,
  "error": {
    "code": "DECK_NOT_FOUND",
    "message": "Deck 'deck_c' does not exist in current session.",
    "reason": "resource_not_found",
    "required_action": "deck_create",
    "suggested_tool": "deck_create",
    "suggested_arguments": {
      "deck_id": "deck_c"
    },
    "recoverable": true
  },
  "next_actions": [
    {
      "action": "deck_create",
      "tool": "deck_create",
      "arguments": {
        "deck_id": "deck_c"
      }
    }
  ]
}

from ai_dj.mcp.tools import (
    tool_workflow_create,
    tool_workflow_add_step,
    tool_workflow_execute,
)

# 1. Create a sequential workflow
tool_workflow_create(workflow_id="prep_track", name="Track Import & Prep Pipeline")

# Step 1: Import Track
tool_workflow_add_step(
    workflow_id="prep_track",
    tool_name="library_import",
    arguments={"file_path": "audio/track.wav", "track_id": "my_song"},
    on_failure="stop",
)

# Step 2: Analyze BPM and Key
tool_workflow_add_step(
    workflow_id="prep_track",
    tool_name="track_analyze",
    arguments={"track_id": "my_song"},
    on_failure="rollback",
)

# Step 3: Load into Deck A only if analysis succeeds
tool_workflow_add_step(
    workflow_id="prep_track",
    tool_name="deck_load",
    arguments={"deck_id": "deck_a", "track_id": "my_song"},
    condition_field="bpm",
    condition_operator="is_not_none",
    on_failure="stop",
)

# 2. Execute the entire pipeline atomically
result = tool_workflow_execute(workflow_id="prep_track")
print("Workflow Result:", result)

pytest -v tests

============================= test session starts ==============================
platform linux -- Python 3.13.12, pytest-9.1.1, pluggy-1.6.0
rootdir: /home/igris/dj-mcp
collected 24 items

tests/test_analysis_and_beatgrid.py::test_key_detection_and_camelot_compatibility PASSED [  4%]
tests/test_analysis_and_beatgrid.py::test_beatgrid_quantization PASSED   [  8%]
tests/test_analysis_and_beatgrid.py::test_audio_analysis_on_fixture PASSED [ 12%]
tests/test_capabilities.py::test_system_capabilities_structure PASSED    [ 16%]
tests/test_capabilities.py::test_doctor_execution PASSED                 [ 20%]
tests/test_decks_and_dj.py::test_deck_lifecycle PASSED                   [ 25%]
tests/test_decks_and_dj.py::test_deck_sync_and_pitch PASSED              [ 29%]
tests/test_decks_and_dj.py::test_cues_and_loops PASSED                   [ 33%]
tests/test_decks_and_dj.py::test_crossfader_curves PASSED                [ 37%]
tests/test_dsp_and_audio.py::test_stereo_panning PASSED                  [ 41%]
tests/test_dsp_and_audio.py::test_stereo_width_and_correlation PASSED    [ 45%]
tests/test_dsp_and_audio.py::test_dc_offset_removal PASSED               [ 50%]
tests/test_dsp_and_audio.py::test_pedalboard_effect_chain PASSED         [ 54%]
tests/test_dsp_and_audio.py::test_rubberband_pitch_and_time_stretch PASSED [ 58%]
tests/test_editing_and_timeline.py::test_clip_trim_and_split PASSED      [ 62%]
tests/test_editing_and_timeline.py::test_track_and_timeline_rendering PASSED [ 66%]
tests/test_errors_and_recovery.py::test_structured_error_dict PASSED     [ 70%]
tests/test_errors_and_recovery.py::test_atomic_write PASSED              [ 75%]
tests/test_errors_and_recovery.py::test_undo_redo_stack PASSED           [ 79%]
tests/test_jobs_and_workflows.py::test_job_manager_execution PASSED      [ 83%]
tests/test_jobs_and_workflows.py::test_sequential_workflow_execution PASSED [ 87%]
tests/test_mastering_and_rendering.py::test_mastering_processor PASSED   [ 91%]
tests/test_mastering_and_rendering.py::test_project_rendering_and_export PASSED [ 95%]
tests/test_mcp_tools.py::test_end_to_end_mcp_tool_workflow PASSED        [100%]

======================== 24 passed in 7.71s ========================