Timing and scheduling

Use integer output audio frames as authoritative session time, paired with an explicit sample rate. Transport source positions, beat positions, and output frames are different coordinates. BPM changes, loops, seeks, and time stretching require explicit mappings between them.

In real-time virtual playback, the audio device's consumed-frame timeline governs progress. A control scheduler prepares commands ahead of the callback. The renderer applies scheduled changes at exact frame offsets, splitting processing blocks when necessary. UI ticks and Tokio timers never advance deck transport.

The new distributed club prototype has no hardware output device inside Docker. Its dedicated mixer owns an integer 48 kHz timeline, pulls 960 frames from every CDJ and paces output every 20 ms. CDJs advance only in response to those pulls; repeated pulls are idempotent. HTTP controls execute at block boundaries. The prototype therefore has a shared software sample clock, not measured sound-card presentation timing. Device-clock bridging, arbitrary sample-offset commands and deadline recovery remain future work. The optional local CPAL mode instead advances from its output callback.

In offline rendering, the render loop advances the same timeline as quickly as computation permits. Pausing stops that timeline. A faster-than-real-time factor describes achieved throughput; it does not alter pitch or skip DSP work.

The historical metadata playground uses an injected fixed-step clock and remains labelled no audio. The audible B2B renderer uses its integer 48 kHz output-frame counter as authoritative time; the metadata playground clock does not drive that renderer.

External clocks

Hardware observations carry source timestamps when available, local monotonic receive time, and estimated uncertainty. Clock synchronization and drift correction are adapter responsibilities; late packets never rewind session time. Keep the requested action time separate from the observed outcome time.

Musical quantization needs a beatgrid with confidence and provenance. Do not infer phrase boundaries solely from a constant BPM. Missing or ambiguous beatgrids disable exact phrase metrics.

Late work

Initially reject commands whose requested execution frame is already past. Interactive commands without an explicit frame execute at the next safe boundary. Actor computation runs outside the audio thread and has a deadline; missing it leaves the current mix running and emits a diagnostic. Policy changes require an RFC.