Skip to main content

MVP-0: two scripted DJs render five minutes

Status: next implementation milestone. No AI provider or hardware dependency is required.

Smallest useful path​

  1. Register a small local WAV library and validated analysis sidecars. Use generated/licensed fixtures with known BPM, beatgrid, phrase boundaries, key, duration, and cue positions. Manual annotations are acceptable initially; fabricated analysis is not.
  2. Add two scripted actor instances with distinct IDs, per-actor history, and alternating track choices. A dedicated B2B orchestrator grants deck 1 to A and deck 2 to B, and grants both channel controls to the transition executor for the bounded overlap.
  3. Implement the TransitionPlan contract, validation, and conversion from musical coordinates to integer output frames. Begin with a fixed-tempo fixture, then demonstrate tempo matching on a different-BPM pair before accepting the milestone.
  4. Implement offline WAV decode, deck transport/seek, tempo processing, gain, three-band EQ, filter, channel faders, stereo summing, master gain, and WAV writing. Creative FX are deferred. Variable-rate resampling changes pitch; if used temporarily, label it and do not claim independent key lock. Choose and test tempo/pitch behavior explicitly.
  5. Persist manifest, accepted decisions, ordered events, metrics, and WAV artifacts as the run proceeds. Record failure/cancellation state and incomplete files without overwriting an earlier session.
  6. Add a CLI render command first, then a background render-job API and the focused two-DJ UI. Offline throughput must not depend on WebSocket delivery or browser presence.
  7. Replay the recorded accepted plans against the same assets and pinned renderer; compare state and audio within a declared tolerance.

Audio and scheduling checks​

Use impulses to test exact action frames, tones to check EQ/filter/gain behavior, and beat-marked synthetic tracks to test alignment and tempo mapping. A bass swap needs complementary low-band gain envelopes, not just a label in the decision log. Crossfade envelopes must avoid unintended silence and clipping. Confirm stereo channel order, WAV sample format, sample rate, duration, and file finalization.

For a five-minute run, verify A → B → A → B alternation and at least three completed transitions. Analyze phrase-start error, beat-phase offset, peak level, unexpected silence, and discontinuities. Include an actual listening pass on appropriate audio fixtures.

Deadline and invalid-plan policy​

Plan early enough to leave a declared reserve before the outgoing track ends. If the actor times out or proposes an invalid plan, use a logged deterministic fallback selecting an eligible track and conservative transition. If no feasible track exists, finish or fade out with an explicit failed/incomplete status; do not claim a successful continuous set.

Required artifacts​

session-id/
  manifest.json
  decisions.jsonl
  events.jsonl
  metrics.json
  mix.wav

The manifest identifies every source asset by hash, analysis version, actor configuration, PRNG, engine build, DSP configuration, and output sample rate. Decision records link to resulting command/event IDs. Replay uses recorded decisions, not fresh model calls.

Completion requires a reproducible five-minute audible mix plus passing scheduler, DSP, replay, and orchestration tests. The audible local-planner demo now provides rendering and replay; real-music listening and model-backed acceptance remain separate gates.