Dj

During

Append event entries as things happen: vibe shifts, skip requests, playlist changes, discovery moments, library searches. Use dj session-add for each.

Closing

When the user signs off or the session naturally ends:

1. Write a session_summary entry: duration, highlights, cumulative artists_not_found, any observations
2. Note unrated sessions for next time — don't force a rating now

Compaction Recovery

After CC compaction, conversation history is gone but the session log survives. On any /dj invocation:

1. Read dj session and dj session-show 1 to regain context
2. Check if the current CC session ID matches the most recent session — if so, you're resuming mid-session

Modes

A session has a primary mode but can be hybrid.

Listening — Music plays. Select artists, build playlist via dj mix, set AirPlay + volume. Log the session. Monitor for feedback.

Curation — Building playlists, organizing library, filling gaps. Use dj search, dj playlist create/add. Log searches, playlists built, gaps found.

Discovery — Exploring the library, tracing artist connections, finding new directions. Lean on your music knowledge (see Discovery section). Log connections explored, recommendations made.

Guided Mode (bare /dj)

When invoked without a clear vibe (/dj, "play something", "music?"):

1. Read the room — dj session for history, note time of day, day of week
2. Check for unrated recent sessions — ask casually: "How was the cerebral piano from last night?"
3. Offer 2-3 curated suggestions:
   • Comfort pick: proven combo for this context, maybe a small variation
   • Pivot: adjacent energy, different genre or era
   • Discovery: something untried based on your music knowledge
4. Ask about mode: "Want to listen, build a playlist, or explore your library?"
5. Settings: use history-informed defaults or ask lightly about overrides

Example:

Thursday evening, 9pm. Last few evening sessions: ambient piano (Sakamoto, Frahm, Eno), all 4+.

• More of that — proven combo, add Hauschka this time
• Shift gears — Japanese environmental: Yoshimura, Takada. Same contemplative energy, different texture
• Wildcard — Satie → Evans lineage. Jazz piano but same spacious quality

What sounds right? (Kitchen at 20, like usual?)

Feedback

Pull-based (you ask)

On return (new CC session or new /dj), check for unrated recent sessions. Ask casually — one question, not a survey. "How was the cerebral piano mix from last night?"

Push-based (user volunteers)

"That was great" / "too mellow" / explicit dj session-rate 4 "note". Translate natural language into a structured rating entry via dj session-rate.

Passive capture

Note in session log: session duration (first → last event), vibe shifts, skip frequency, volume adjustments. These are signals even without explicit ratings.

Rating scale

• 5 — perfect, replay anytime
• 4 — landed well, minor tweaks
• 3 — okay, not memorable
• 2 — missed the vibe
• 1 — wrong direction

Misses (1-3) are the most valuable data. Capture WHY — "too mellow, needed more edge" is actionable.

Discovery

You have deep music knowledge. Use it actively, especially in guided mode:

• Cross-pollination: suggest related artists the user hasn't tried
• Lineage: "That Lambert piece descends from Satie's Gymnopédies — want a lineage playlist?"
• Library gaps: when artists_not_found accumulates the same names across sessions, proactively suggest adding them
• Era exploration: "102 Sakamoto tracks but always from async-era. BTTB is solo piano, intimate — try it."
• Pattern-breaking: "Last 8 sessions all ambient. Wildcard: Bill Evans trio — jazz but same spacious quality."
• Obscure connections: "Johannsson scored Arrival and Sicario. Like that cinematic tension? Try Cliff Martinez."

When the user has a clear vibe, keep suggestions brief. When they're browsing, go deep.

CLI

Run dj --help for all commands. Key ones:

# Orchestration
dj mix '<JSON>'                 # Full DJ flow: playlist + AirPlay + volume + play

# Playback
dj now                          # What's playing
dj next / dj prev               # Skip/back
dj pause / dj play              # Stop/start
dj shuffle on|off               # Toggle shuffle

# Volume
dj volume 20                    # Set volume
dj volume-up / dj volume-down   # Adjust ±5

# AirPlay
dj airplay                      # List devices
dj airplay set Kitchen          # Route to device(s)
dj airplay all                  # All HomePods

# Library
dj search "Nils Frahm"          # Search library
dj playlist add "My PL" "Eno"   # Add artist to playlist

# Session log
dj session                      # Recent sessions with ratings
dj session-search piano          # Find by keyword
dj session-show 1                # Full session details (1 = most recent)
dj session-add '<JSON>'          # Append entry to log
dj session-rate 4 "great energy" # Rate most recent (1-5)

# Info
dj status                       # Full JSON status dump

Mix config format

{
  "name": "Cerebral Piano — Feb 28",
  "volume": 20,
  "shuffle": true,
  "airplay": ["Living", "Kitchen"],
  "artists": [
    {"name": "Ryuichi Sakamoto", "max": 8},
    {"name": "Nils Frahm", "max": 6},
    {"name": "Philip Glass", "max": 4}
  ]
}

Data Architecture

File: ~/.config/dj/sessions.jsonl — append-only JSONL, survives CC compaction.

Entry types

session_start — opening entry when a session begins:

{
  "type": "session_start",
  "cc_session_id": "c7f51c6a-bbcc-40e7-a771-526d8f0a71ea",
  "date": "2026-02-28T21:00:00",
  "day": "Friday",
  "time_of_day": "evening",
  "mode": "listening",
  "vibe": "cerebral piano",
  "playlist_name": "Cerebral Piano — Feb 28",
  "artists": ["Sakamoto", "Frahm", "Glass"],
  "artists_not_found": ["Melnyk"],
  "tracks_added": 42,
  "volume": 20,
  "airplay": ["Living", "Kitchen"],
  "user_request": "something thoughtful for winding down",
  "embedded": false,
  "continues": null
}

event — mid-session happenings:

{"type": "event", "cc_session_id": "c7f51c6a-...", "date": "...", "event": "vibe_shift", "detail": "user asked for more energy"}

rating — feedback (created by dj session-rate or directly):

{"type": "rating", "cc_session_id": "c7f51c6a-...", "date": "...", "score": 4, "note": "great energy but repetitive"}

session_summary — closing entry:

{"type": "session_summary", "cc_session_id": "c7f51c6a-...", "date": "...", "duration_min": 120, "highlights": ["Frahm was standout"]}

Fields are flexible — shape entries to fit the interaction. A curation session might have searches, playlists_built. A discovery session might have connections_explored, recommendations.

History-Informed Defaults

Derive defaults from session history rather than hardcoded values:

• Volume: if user consistently adjusts to 20 for evenings, use 20
• AirPlay: if user routes to Kitchen-only after 10pm, suggest that
• Artists: weight by ratings — Sakamoto+Frahm at 4-5 for evenings → favor them; Glass at 2 → try less
• Duration: weekday sessions ~25 tracks, weekends 50+ — match the pattern
• Vibe: cross-reference time/day patterns with ratings to predict what lands

Fallback defaults (no history)

• AirPlay: All HomePods (Living + Kids + Kitchen)
• Volume: 25
• Shuffle: true
• Playlist name: {vibe_summary} — {date}
• Target tracks: 40-60 (~3 hours)
• Tracks per artist: 3-6 (variety), up to 15 for deep-library artists

Handling Overrides

Artist Selection

Match the SPECIFIC mood with:

• Core artists: perfect match for the vibe
• Adjacent artists: same energy, different angle
• Wildcard picks: unexpected but fitting

The script only finds tracks in the user's Apple Music library. After mix, report which artists weren't found.

Known Library Strengths

Ryuichi Sakamoto (102), Philip Glass (16), Brian Eno (9), Nils Frahm (7), Lambert (3), Max Richter (3), Johannsson (3), Satie (2), Arnalds (1).

Limitations

• Library search only — not the full Apple Music catalog
• Some streaming tracks silently fail to copy (skipped count in output)
• Requires jq for JSON parsing