# AI DJ · Velvet Deck

A two-deck web DJ that really mixes: the next song swells in while the current one melts away. Equal-power crossfades on two hidden decks, an Auto DJ that blends the set forever, a live crossfade meter, equalizer ring and DJ chatter. Single-file HTML with background-tab-safe fades, served from the cluster.

**Status:** Live · Projects · 2026

- **Local checkout:** `/Users/simon/Developer/ai-dj` (branch `main`, last commit 00e2c6f, 2026-11-06 — AI DJ 2.0: hub with play-anything (yt-dlp), request queue, other-audio ducking (Mac players + Fedora), CLI, native macOS app, single-active-client)
- **Uncommitted changes:** 41 file(s) at brief generation time
- **Repository:** https://github.com/ShimonNavon/ai-dj
- **On another machine:** `git clone https://github.com/ShimonNavon/ai-dj` — the paths below are Simon's Mac
- **Listen (tailnet):** http://ubuntu03:30119/
- **Where it runs:** hub daemon on the Mac serves the player and owns the set; native app and phone web players are clients

## Stack

SwiftUI + AVFoundation native app, Higgsfield Sonilo Music (generated originals), Single-file HTML web player served by the hub, Python stdlib hub daemon (loopback) + SQLite, librosa analyzer venv (ffmpeg fallback), yt-dlp resolution + 2GB media cache, OpenRouter text + TTS, Tailscale serve + nginx landing page on Kubernetes, MCP Streamable HTTP (/mcp) + tailnet MCP registry gateway

## Start here

- `server/hub.py` — hub v3: SSE commands with ack/retry, claim+lease, fast /state, ducking, requests, media/voice Range serving, /advance
- `server/generator.py` — generated originals via Higgsfield Sonilo Music: six rotating sound palettes, per-track lead instrument/texture variation, background buffer, generated/mixed/library modes
- `server/db.py` — SQLite schema and persistence for items, analysis, queue, history, taste, clients, caches
- `server/music_app.py` — read-only Apple Music import: SQLite when available, hfma fail-soft + AppleScript only if Music is already running
- `server/analysis.py + tools/audio_analyzer/` — local BPM/beat/key/LUFS analysis, hash-keyed cache, librosa venv with a pure-Python fallback
- `server/transitions.py` — compatibility scoring, phrase-aligned cue/rate/EQ plans, ±8% rate clamp, epsilon-greedy template bandit
- `server/selector.py + library.py + taste.py` — adaptive pool and scoring from taste, context, mood and no-repeat memory
- `server/context.py + mood.py` — bundle-ID-only coding detection and bounded mood steering
- `server/ai.py + voice.py` — Velvet text via OpenRouter and cached TTS with privacy limits and fallbacks
- `server/resolver.py + media.py` — single yt-dlp worker, download cache and Range/LRU serving
- `index.html` — hub v3 web player: SSE, claim/lease, two-deck transition executor, queue/history, mood, voice, mobile
- `macos/AIDJ.swift` — native hub v3 client: two AVPlayer decks, rate/volume blends, ducking, voice, queue/history/mood
- `bin/ai-dj + tools/dj_mcp.py` — CLI and MCP surfaces, old commands kept and new ask/chat/say/focus/mood/feedback/taste/history/doctor added
- `tests/` — pytest suite with temp state, fake yt-dlp/osascript/ssh/analyzer and synthetic click tracks
- `deploy/deploy.sh + deploy/landing.html` — cluster landing page at ubuntu03:30119 linking to the Tailscale player
- `deploy/com.simon.ai-dj.plist` — launchd agent keeping the hub alive
- `brand/` — Velvet Station master icon SVG/PNG, compact favicon, web sizes; embed.py embeds icons and the header mark into the player and landing page
- `macos/make-icon.sh + AppIcon.icns` — builds and bundles the macOS app icon; Info.plist declares it and the native header shows it
- `web + native Generate controls` — Generate a track and source mode picker; generated-status chip; Dock menu generate item
- `server/hub.py /mcp + tools/dj_mcp.py` — 27-tool MCP over Streamable HTTP and stdio; dj_station changes mode, palette, mood and starts a generated track in one call

## Commands

- **Smoke:** `python3 test_smoke.py`
- **Tests:** `python3 -m pytest -q`
- **Swift typecheck:** `swiftc -typecheck -parse-as-library -target arm64-apple-macosx14.0 macos/AIDJ.swift`
- **Build app:** `macos/build.sh`
- **Hub (restart):** `launchctl kickstart -k gui/$(id -u)/com.simon.ai-dj`
- **Doctor:** `ai-dj doctor`
- **CLI:** `ai-dj ask "something calm" | chat | say | mood calm | focus on | taste | history`
- **Deploy landing:** `./deploy/deploy.sh`

## Deploy and where it runs

- Player: served by the hub on the Mac over Tailscale at https://simons-macbook-pro.tail32418c.ts.net/ (tailscale serve --bg 8765)
- Landing page: namespace ai-dj on ubuntu03/ubuntu04, nginx + ConfigMap, NodePort 30119 (tailnet only)
- Hub: launchd on the Mac (com.simon.ai-dj), loopback 127.0.0.1:8765
- App: ~/Developer/ai-dj/macos/AIDJ.app (ad-hoc signed)

## Current state

3.3 generated originals + agent MCP live 2026-11-06: six rotating sound palettes, per-track lead/texture, 27-tool MCP at /mcp registered in the tailnet gateway as ai-dj; station change via ai-dj__dj_station; 61 pytest tests + smoke + Swift typecheck green

## Watch out

- launchd PATH has no Homebrew: find yt-dlp/ffmpeg via explicit fallback paths (server/config.py find_binary)
- current macOS Music libraries are hfma, not SQLite: the importer fails soft and uses AppleScript only when Music is already running
- the analyzer venv must be Python 3.9 (system) on this Mac; Python 3.15 has no numba/librosa wheels
- the hub owns item_id/title; client state reports only update playback fields
- only the controller receives commands; the 20s lease is refreshed by /state reports; a claim re-delivers pending play_item
- SSE commands are retried every 2s until acked and expire after 15s; polling /cmd is the fallback
- rate is clamped to ±8%; low-confidence analysis and live streams use equal-power fades
- Music.app is never launched and DRM files are never played
- Tailscale CLI is only at /Applications/Tailscale.app/Contents/MacOS/Tailscale, not on PATH
- branding: edit brand/icon.svg, render brand/icon-1024.png, run macos/make-icon.sh and brand/embed.py; the player must keep icons inline (data URIs)
- generated mode falls back to the real pool until the first original is ready; library mode excludes generated items
- generator prompts use genres/BPM/energy/coding only, never artist names or local paths
- generation rotates palettes after rotation_tracks (4) or rotation_minutes (15); each palette changes instruments, rhythm, production and tempo
- Shift sound / ai-dj shift / dj_generation_shift forces the next palette immediately
- the MCP gateway pod cannot resolve MagicDNS; the ai-dj registry entry uses the Mac tailnet IP 100.125.119.73:8766
- tailscale serve --bg --tcp 8766 tcp://127.0.0.1:8765 exposes the hub to the gateway; the hub itself stays loopback
- ai-dj__dj_station {mode, mood, shifts, generate} is the one-call station change; dj_generation_shift only moves the palette

## Secrets — locations only, never print values

- O
- p
- e
- n
- R
- o
- u
- t
- e
- r
-  
- k
- e
- y
-  
- a
- t
-  
- ~
- /
- .
- c
- o
- n
- f
- i
- g
- /
- a
- i
- -
- d
- j
- /
- l
- l
- m
- .
- k
- e
- y
-  
- (
- m
- o
- d
- e
-  
- 6
- 0
- 0
- )
-  
- o
- r
-  
- O
- P
- E
- N
- R
- O
- U
- T
- E
- R
- _
- A
- P
- I
- _
- K
- E
- Y
- ;
-  
- n
- e
- v
- e
- r
-  
- p
- r
- i
- n
- t
- .
-  
- N
- o
-  
- o
- t
- h
- e
- r
-  
- s
- e
- c
- r
- e
- t
- s
- .

## Tags

Two-deck crossfade, Auto DJ, Single-file HTML, Kubernetes

---

Brief generated 2026-11-08 from `~/Developer/my-projects/context/`. Canonical URL: https://projects.navonsimon.com/context/ai-dj.md
