playback

Playback

Playback has two independent public surfaces: MasterTransport for the block clock, and immutable compiled playback programs. Build a ProgramCompileRequest from one captured immutable Project snapshot, an external monotonically increasing document revision, a shared precompiled tempo map, an explicit sample rate, and an explicit DirtyTrackSet. The request rate is invalid by default; set ProgramCompileRequest::sample_rate from the engine configuration and compile the tempo map at that same exact RationalRate. Submission normalizes both and fails synchronously if the request rate is invalid, above the compiled-rate ceiling, or differs from the map, preventing one program from mixing sample domains. Drive it with DeferredCompileExecutor::run_for() on threadless/UI hosts or use WorkerCompileExecutor on native threaded hosts. The compiler is the sole publisher to its PlaybackProgramStore. Use sparse TrackCompilePolicy deltas when a track changes provider selection or adoption policy. The compiler validates availability, forces that track through the dirty path, retains omitted published policies, and coalesces pending deltas with latest-track wins. For this phase, only ProviderKind::Arrangement with the arrangement-only availability mask is valid; reject launcher or external-input claims until their provider payloads are compiled.

For MediaRef clips, prepare a DecodedAudioAssetPool off the audio thread. Use DecodedAudioAssetPool::decode_wav() for bounded in-memory WAV bytes, then pass the immutable pool in ProgramCompileRequest::audio_assets. The existing compiler incrementally lowers media clips into each TrackProgram; do not build a second playback-program model. TimeConform::None uses the existing bounded native-rate source mapping after sample-rate conversion. TimeConform::Resample uses bounded stateless varispeed: map each rendered musical tick to the same fraction of the referenced source range and derive the effective source step for anti-aliasing. Use the compiled tempo map's analytic fractional sample-to-tick inverse for ordinary playback and precise host ticks for host beat mapping; sample-fraction interpolation across a tempo ramp is not musical phase. TimeConform::Stretch is compiled off the audio thread: slice the source, fixed-SRC it into the compiled timeline-rate domain, drive the finite stretcher with an analysis-boundary tempo schedule, and publish only an immutable artifact with exactly the authored timeline frame count. Use the scalar double finite builder for deterministic offline compilation, then convert its exact result to the public float artifact in bounded blocks. Document-tempo playback consumes that artifact 1:1. For live host-tempo projection, prepare a complete RealtimeStretchProgramRuntime off the audio thread and stream the artifact through its preallocated low-latency processor; the audio callback may stretch but must never allocate, lock, or prepare DSP. The runtime publishes one fixed causal latency for all parallel audio and MIDI paths and resets coherently on transport/program epochs. Keep source/tempo/algorithm semantic identity in the artifact cache key and document revision/program generation in separate provenance. Compiler work-block size is scheduling only and must change neither key nor output. Never route Stretch through Resample, pad/trim a length mismatch, or fall back to None. Gain and anchor-native fade durations live on the immutable Clip. Missing, mismatched, or over-capacity assets fail compilation instead of creating a silent placeholder. When sequence lowering flattens a complete nested media clip, preserve its authored TimeConform value. Reject a nested source window that trims a Resample or Stretch clip with NestedSequenceUnsupported; advancing a raw source-frame offset is valid only for unconformed media and would corrupt the authored phase until playback owns a conform-aware source-range mapping.

When host beat mapping intentionally makes musical material follow the host tempo, keep absolute clips, take-comp segments, and frozen artifacts on TransportRange::timeline_sample_start; those sources are sample-domain content and must not inherit the beat projection. Carry precise fractional host tick endpoints through every callback and nested ProcessContext projection; integer timeline_tick_* fields remain compatibility metadata and must not drive host-mapped interpolation, loop admission, note scheduling, automation refinement, MIDI clock, or metronome enumeration. A precise host-mapping rejection must not fall back to document-tempo placement. For musical audio, derive the effective source-position step per output frame. A converter prepared only for the asset-rate/timeline-rate ratio cannot anti-alias faster host playback, so prepare and share a per-MediaRef-range multiresolution audio pyramid off the audio thread. Build it incrementally inside the compiler work budget, count it against both converter-count and aggregate prepared-byte limits, including persistent sinc tables and container storage, and seed unchanged programs back into the cache. Clamp every pyramid level to the exact referenced source range so neighboring asset frames cannot bleed into a clip. Fixed-rate and variable-rate kernel construction are part of that same incremental budget: initializing a converter must not synchronously populate every sinc phase before yielding. Use fixed-size, incrementally allocated prepared chunks whose persistent footprint is computable; implementation-defined container bookkeeping cannot sit outside the byte cap. Each 2:1 stage must low-pass before decimation; select the coarsest level that leaves a bounded residual step, then use its prebuilt reconstruction kernel. Do not approximate extreme ratios by clamping a tiny cutoff onto a fixed-width source-rate kernel: once the sinc support contains too few zero crossings, normalization turns it into a short moving average and aliases despite the nominal cutoff. The fixed asset-rate/timeline-rate path therefore fails compilation beyond its honest kernel range, while host-tempo playback uses the prepared pyramid to retain its wider bounded contract.