xtc/docs/decisions/0005-preloaded-audio-and-recording.md

# 0005: Preloaded WAV Clips and Control-Thread Recording Consumer

Status: accepted.

Use a small bounded C99 WAV decoder/writer for PCM16/24/32 and IEEE float32,
mono/stereo, instead of adding libsndfile in this milestone. This avoids a new
build/runtime/license dependency, keeps the supported format surface explicit,
and enables malformed-input tests. It also limits format coverage; a future
codec library needs its own dependency and licensing review.

Compile musical clip ranges and decoded, shared-per-path mono buffers while
stopped. The callback renders the timeline into a preallocated buffer consumed
by an explicit graph source node, preserving graph routing rather than mixing
outside the graph. The old snapshot remains until candidate preparation
succeeds. All track clips currently share one source; per-track routing/mixing
is deferred.

Use a bounded SPSC ring for callback input capture, with release/acquire index
publication and a GUI/control-thread consumer. This adds no worker-thread
dependency; a two-second ring tolerates normal 100 ms polling but exposes
overflow if the GUI or disk stalls. Sticky errors prevent silent time
compression. Finalization requires callback quiescence. Future
long-session/background I/O work can reuse the ring contract with a dedicated
consumer.

Store external absolute paths in version 2 metadata and retain version 1 loads.
Missing/unreadable assets are reported silence, with explicit relinking;
portable bundles and content-addressed assets are deferred. See AUDIO_FILES.md
for limits.