xtc/docs/AUDIO_FILES.md

Audio clips and recording (Phase 6)

Import and playback

File/Import WAV (Ctrl+I) loads a WAV into the selected track at the playhead. With no selected track it creates an Audio track. Add region still creates a silent placeholder. Imported clips use the existing move/trim controls. Import stops playback, validates a candidate project, and commits only after successful backend preparation (or locally when disconnected).

Supported input: little-endian RIFF/WAVE, PCM16/24/32 and IEEE float32, one or two channels, 1..768000 Hz. Stereo is averaged to mono. Compressed WAV, RF64, WAVE_FORMAT_EXTENSIBLE, PCM8, other containers and multichannel files are unsupported. Nonfinite float data and malformed/truncated files are rejected. There is no new dependency: the bounded C decoder/writer is covered by known sample, truncation and invalid-codec tests. See decision 0005.

Audio is preloaded before playback: maximum 64 distinct paths per plan, 16777216 mono frames per asset (64 MiB), 67108864 total frames (256 MiB). Import rejects files over 256 MiB or over 4096 chunks. No streaming decoder, waveform cache, peak drawing or background load worker exists yet. Preloading can briefly block the GUI. Candidate compilation retains the old plan until success; temporary build memory can include both old and candidate buffers.

The callback renders only overlapping clip ranges from memory. Clips on all tracks are summed through their mix/automation settings into the graph's Audio clips source node. Import creates that source and connects it to an existing/new output if no audio source exists. Subsequent routing is explicit: disconnect it or route it through gain/meter nodes in Modular Graph. Removing the output silences editor graphs. This source does not monitor JACK input; unconnected ordinary graph inputs retain their earlier external-input behavior. Track faders/pan/mute are implemented by the Phase 8 track mixer (see MIXER.md); individual track graph routing remains deferred.

Linear interpolation converts source sample rate to backend rate. There is no antialiasing filter, time stretching, looping or fades. Musical durations round up to a tick on import; playback boundaries and trims use floor tick-to-sample conversion. A rounded tail pads with silence past the source, and a recording's placement can differ by less than one tick from the capture start sample. Changing tempo changes the musical span, not the source playback rate.

Arrange edits stop playback. Play preloads and adopts the current arrangement; Stop pauses the sample clock. Graph-only edits can still be submitted during playback. Graph recompilation can reset oscillator phase as before. Playback does not stop automatically at the arrangement end.

Assets and recovery

Version 2 projects store external absolute canonical paths, not sample data. Save the project AND keep its referenced WAV files. Save As changes only the metadata path; it does not copy assets. Moving/deleting a WAV makes its regions silent, preserves their IDs/positions and reports the path and unique issue count on Open/Play. An already loaded plan keeps playing even if its file is removed; the next preparation detects it. Unreadable, malformed and unsupported assets are also reported, rather than substituted with unrelated files. Capacity/OOM is a preparation failure and retains the old plans.

Select the affected clip, then File/Relink selected audio to choose a replacement. Relinking retains its original timeline/source bounds. The replacement is validated on the next Play; a shorter replacement pads beyond its end with silence. Saving retains unresolved references for later repair. Missing assets are also checked on Open without a working backend, using a temporary plan. Automatic asset search, content hashes and portable project bundles are deferred.

Recording

Record (or Audio/Record WAV, Shift+F5) opens a destination chooser, stops playback, prepares the project, opens a temporary mono float32 WAV and starts JACK. Connect a source to xtc's JACK input using an external patchbay; no physical or software route is created automatically. Without a route the take contains silence. Recording captures raw mono JACK input, not the output/effect mix.

A preallocated two-second SPSC ring transfers complete callback blocks to the GUI/control thread, which drains it every 100 ms. The producer uses verified lock-free atomics and bounded copies only. It never allocates, logs, takes a mutex, opens/writes files or calls FLTK. A slow disk/blocked GUI can overflow the ring; capture then stops accepting input with a sticky, visible capacity error rather than hiding gaps or compressing time.

Stop first synchronizes the callback, detaches the recorder, drains remaining samples, writes the final WAV header, flushes/fsyncs/closes and renames the same-directory temporary using an atomic no-clobber link; an existing destination is refused. A successful nonempty take is imported at its capture position on the selected track (or a new Recording track), then the document becomes unsaved. Save the project after Stop. Seeking back to the take and pressing Play auditions it. Recording continues existing arrangement playback, but there is no automatic input monitoring, punch, loop, latency compensation, multitrack arming or overdub alignment compensation.

Graph/arrangement edits, project file actions, reconnect and close are blocked until Stop finishes the take. Deactivation failure retains the recorder for a safe retry. On overflow a finalized partial WAV is retained for manual recovery and is not automatically added. On import/preparation failure the completed take remains at its chosen path with an explicit recovery message. I/O errors are reported; failed temporary data is retained and its recovery path is reported. Recordings are RIFF-limited to 1073741814 frames, but the smaller playback/import asset limit still applies: longer takes may need external splitting before import. There is no crash-recovery journal. The file is mode 0600; parent-directory fsync and preservation of previous permissions are not implemented.

Verification

make test includes deterministic WAV/graph samples, resampling/overlap/trim, malformed inputs, missing/relinked assets, SPSC concurrency/overflow/cleanup, and record -> save/reopen -> exact playback through the backend callback. make test-gui covers the workflow and rollback with a fake backend. make test-gui-jack records/reopens a silent take using real JACK callbacks. make test-jack-audio routes only two software clients: known source -> recorded WAV -> saved/reopened project -> graph playback -> capture assertion. Physical input/output, device latency, slow-disk endurance and server loss during a real recording remain unverified.

Phase 13 recording protection

The default recorder and GUI require a new destination, including rejecting symlinks. Publication also refuses files created during recording. The explicit xtc_recorder_create_replace API retains authorized replacement for callers that deliberately need it; the GUI never uses it. After a failed finish, copy xtc_recorder_recovery_path before destruction. Disk-write/finalization failures retain the temporary. Destruction after producer quiescence attempts to drain and finalize accepted data; normal code should call finish and inspect errors. The GUI refuses closure while recording and prints the retained/finalized path on exceptional destruction.

Use xtc-check --recover-recording TEMP NEW.wav to copy complete float32 frames from an interrupted xtc WAV into a new WAV. Source and existing destinations are never modified. A trailing partial frame is ignored. This handles xtc's canonical 44-byte mono float32 header only, not arbitrary damaged WAVs. Recovery is explicit and control-thread only; no orphan scan runs during playback.

make test-recording simulates 30 minutes at 8 kHz with repeated ring wrapping and draining, destination races/symlinks, a child-local disk-size limit, prefix recovery and incomplete/missing asset reopening. test-recovery retains process kill coverage; test_audio covers saturation and concurrent drain. This is virtual-duration testing, not a wall-clock hardware endurance qualification. Recordings remain RIFF mono float32, bounded to roughly 4 GiB; the preloaded player still limits each asset to 16M frames. Longer valid takes may require external splitting before import. No directory fsync/power-loss guarantee is claimed. WAV destinations are chosen explicitly by the user.