# yt-dj-mcp

Local YouTube Music DJ crate MCP server.

The server syncs liked songs from YouTube Music, stores approximate DJ metadata
such as BPM, key, Camelot key, and genre, then creates playlists only from saved
previews.

## Who This Is For

Use this if you have a large YouTube Music liked-song library and want a local,
agent-friendly way to turn it into DJ crates. The workflow is deliberately
preview-first: inspect candidates locally, then create playlists only after you
approve a saved preview.

## What It Can Do

- Sync YouTube Music liked songs into local SQLite.
- Analyze short local audio sections with `yt-dlp`, `ffmpeg`, and Essentia.
- Store BPM, musical key, Camelot key, confidence, and source.
- Search tracks by BPM/key/genre.
- Save playlist previews before writing to YouTube Music.
- Create YouTube Music playlists from reviewed previews.

## Safety

- Uses OAuth by default.
- Stores secrets in `~/.config/yt-dj-mcp/`.
- Never prints credential file contents.
- Creates playlists only from saved previews.
- Browser/HAR auth is an explicit fallback and stores session headers in
  `browser.json`; keep it local and never commit it.
- Runtime state is local-only. Do not publish `library.sqlite`, HAR files,
  browser headers, OAuth tokens, or downloaded audio.

## Quick Start

```bash
git clone https://github.com/YOUR_USERNAME/yt-dj-mcp.git
cd yt-dj-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e ".[dev,audio]"
pytest -q
```

Add the MCP server to your client:

```toml
[mcp_servers.yt_dj_mcp]
command = "/absolute/path/to/yt-dj-mcp/.venv/bin/yt-dj-mcp"
args = ["serve"]
```

## OAuth Setup

Create a Google Cloud OAuth client that can be used by `ytmusicapi`, then run:

```bash
yt-dj-mcp setup-auth
yt-dj-mcp auth-status
```

If OAuth token creation succeeds but YouTube Music requests return HTTP 400, use the explicit local browser fallback:

```bash
ytmusicapi browser --file ~/.config/yt-dj-mcp/browser.json
chmod 600 ~/.config/yt-dj-mcp/browser.json
yt-dj-mcp auth-status
```

If copying request headers from DevTools is unreliable, export a Chrome Network
HAR and import it:

```bash
yt-dj-mcp import-har /path/to/music.youtube.com.har
yt-dj-mcp auth-status
```

`browser.json` contains browser session headers. Keep it local and never commit it.

## Commands

```bash
yt-dj-mcp setup-auth
yt-dj-mcp auth-status
yt-dj-mcp import-har /path/to/music.youtube.com.har
yt-dj-mcp enrich-tracks --limit 25
yt-dj-mcp reset-auth
yt-dj-mcp serve
```

MCP tools exposed by the server:

- `auth_status`
- `setup_auth_instructions`
- `sync_liked_songs`
- `list_liked_songs`
- `enrich_tracks`
- `find_dj_candidates`
- `create_playlist_preview`
- `get_playlist_preview`
- `create_youtube_music_playlist`
- `update_track_metadata`

## Audio Metadata Enrichment

`enrich-tracks` fills missing BPM/key/Camelot metadata by downloading a short
audio section with `yt-dlp`, analyzing it with Essentia, then caching the
analysis under `~/.config/yt-dj-mcp/audio-metadata-cache/`.

Required local commands/packages:

```bash
ffmpeg -version
python -m yt_dlp --version
python -c "import essentia; print(essentia.__version__)"
```

The command is best run in small batches:

```bash
yt-dj-mcp enrich-tracks --limit 10
yt-dj-mcp enrich-tracks --limit 50
```

If `yt-dlp` or Essentia is missing, enrichment will leave tracks in the
`missing` count instead of crashing the server. Use this only for music you are
allowed to process locally; downloading streamed audio may be restricted by the
service's terms.

## First Crate Workflow

1. Run `yt-dj-mcp setup-auth`.
2. Run `yt-dj-mcp auth-status`.
3. Add the MCP server to Codex or Claude.
4. Call `sync_liked_songs`.
5. Run `yt-dj-mcp enrich-tracks --limit 25` or call MCP `enrich_tracks`.
6. Call `find_dj_candidates`.
7. Call `create_playlist_preview`.
8. Review with `get_playlist_preview`.
9. Create the YouTube Music playlist with `create_youtube_music_playlist`.

## Suggested Agent Prompt

After installing the MCP server, try:

```text
Sync my YouTube Music liked songs, enrich 50 tracks with BPM/key metadata, then
create 12-track DJ playlist previews grouped by compatible BPM and Camelot key.
```

Review previews before asking the agent to create real YouTube Music playlists.

## Limitations

- BPM/key values are estimates. Use your ears before playing out.
- YouTube Music auth can be brittle. OAuth is preferred, while browser/HAR auth
  is a local fallback when OAuth does not work.
- Audio analysis depends on `ffmpeg`, `yt-dlp`, and Essentia availability.
- This project does not manage playback and does not provide destructive
  library operations.

## License

MIT