xtc/docs/AUDIO_QUALITY.md

# Timing, transitions and audio quality

Phase 12 adds deterministic transition processing and tests. Musical time still
uses a single constant tempo, 960 ticks per quarter note and fixed 4/4 meter;
it does not introduce a tempo map, meter editor or JACK transport following.
Project format remains v4 (reads v1–v3).

## Timing policy

`xtc_project_set_tempo` accepts 20000–300000 milli-BPM and changes the editable
model only. Build new audio/MIDI/mixer plans while stopped to adopt it. Existing
plans keep their prepared sample positions and mix snapshots. The backend retains
its absolute sample counter through preparation; explicitly seek if the caller
wants to preserve a particular musical tick after changing tempo. The GUI has no
tempo-change command yet. Meter is always 4/4, has no setter and does not vary
within a project.

Every musical boundary is converted from its **absolute** tick:

```
sample = floor(tick * rate * 60000 / (tempo_milli_bpm * 960))
```

Conversions use bounded unsigned integer arithmetic, not accumulated floating
beat durations. The inverse also floors; a sample-to-tick roundtrip can lose a
tick because of quantization. At very low supported rates several ticks can map
to one sample. Collapsed note spans are silent. Automation uses the last point
in tick order at a shared sample. Clip/note intervals are half-open `[start,end)`;
a boundary exactly at the next block belongs to that next block. The MIDI input
array preserves caller order for equal offsets (for example on/off versus off/on).
A discontinuous MIDI render position resets live voices before rendering.

Changing tempo shifts musical boundaries, including source offsets, on newly
compiled plans. WAV samples keep their original playback speed with linear rate
conversion; this is not audio time stretching. Scheduled note phase comes from
absolute note age, so seeks and block partitions reproduce the same waveform.
The graph oscillator/native graph clock is plan-local, rather than project time.

## Boundary fades and smoothing

The GUI configures `xtc_backend_set_transition_frames(rate/200)`: approximately
5 ms at the current rate (integer frames, floor). Configuration is control-thread
only while stopped, before project preparation. The low-level backend and
source-plan APIs default to zero transition frames for source compatibility.
Call `xtc_audio_plan_set_fade_frames` and `xtc_midi_plan_set_fade_frames` before
publication to enable the same behavior in an offline/custom host.

Each audio region and scheduled note gets an independent linear boundary
envelope. Its first and last audible samples are zero. At distance `d` from the
nearer boundary the factor is `min(1, d/fade_frames)`. For audio, the end is the
earlier of the clip end and the actual loaded media end after source offset/rate
conversion; rounded-up imported duration does not expose an unfaded last sample.
The envelope is computed from absolute sample position: render partitioning,
seeks, overlapping regions and mono/stereo calls do not advance shared envelope
state. Very short regions are attenuated throughout; a one-sample region becomes
silent. Adjacent regions each fade independently, so this is not a crossfade or
seamless-loop implementation. Fade configuration is a host policy, not persisted
per-clip editing metadata.

`xtc_gain_ramp` in `xtc_dsp.h` is a single-owner C primitive for smooth gain and
parameter changes. Initialize with reset, set a finite target and length, then
process preallocated mono/stereo buffers. It reaches the exact target on the Nth
sample, with the first sample one step toward the target. Retargeting starts from
the current gain; zero frames changes it immediately. Stereo shares one gain and
advances once per frame. Invalid calls leave buffers/state intact. It allocates
nothing. Mixer automation already interpolates gain/pan per sample; the ramp
primitive does not add a second smoothing delay to that timeline. Static mixer
edits stop playback and use the master ramp on restart. Live native parameter
updates and live graph replacements have no automatic crossfade.

## Graceful and immediate stopping

GUI Play fades the master from zero to unity. Ordinary GUI Pause/Stop request a
fade to zero using `xtc_backend_request_stop`; repeated requests do not restart
the fade. The callback publishes completion with a release atomic, then outputs
silence and holds the sample position. `xtc_backend_collect` on the control thread
acquires completion and calls JACK deactivate, which establishes quiescence.
Until then, status reports `running` and `stopping`, and the GUI displays that it
is fading. The 100 ms GUI timer completes deactivation; it does not control fade
timing. If deactivation fails, context/ownership remains intact, silence
continues, the error is reported and later collection retries.

The ramp length is sample-counted, but the last callback processes a whole block
and advances the sample position by that block, including its zero-valued tail.
A stop request starts at the next observed block boundary. Therefore Pause/Stop
can consume up to approximately `fade_frames + block_frames` after the request,
plus server scheduling; this is not an immediate sample-exact stop command.
Play resumes at the retained block-end sample position with a fresh start ramp.
No callback waits for control or performs deactivation/allocation/I/O.

`xtc_backend_stop`/close remain synchronous immediate operations. Recording Stop
uses immediate deactivation before draining/finalizing the input take; recording
samples are never faded by the output master. Graceful requests refuse attached
recorders. Home/seek, project installation, recording start, panic, errors and
server loss retain immediate semantics. Those transitions can click; safety and
material preservation take priority. If callbacks cease, use immediate stop or
close rather than waiting for fade acknowledgement. Live note-off/panic remains
immediate with no release tail; scheduled notes use the boundary envelope.

## Numerical and channel policy

Core graph, native output, audio and MIDI rendering canonicalize nonfinite values
and float subnormals to zero at output boundaries; graph node buffers also use
this policy. Native callbacks remain trusted and may have their own internal
denormal behavior. No process-wide FTZ/DAZ flags are modified. Normal values as
small as `FLT_MIN` are retained. The raw constant-gain helper is unchanged;
`xtc_gain_ramp_process` applies the canonical output policy.

Finite values above unity are preserved for mixing headroom. There is no limiter,
soft clipping or dither. The physical device/downstream system may clip; lower
track gains if meters exceed unity. Ports remain mono with paired stereo passes;
external mono input is duplicated. Audio assets are downmixed on import, so
stereo assets do not retain stereo image. Output buffers must not overlap each
other; graph sources may alias outputs because both source passes finish first.
Supported render sizes are 0–65536 frames within the prepared graph maximum.

## Latency and synchronization limits

Backend status reports sample rate and current buffer frames, not measured
end-to-end device latency. `buffer_frames/sample_rate` is one process quantum,
not capture-to-speaker latency. JACK owns hardware/graph scheduling and external
port latencies; xtc currently does not query/display JACK latency ranges or
publish an explicit per-node latency model. Fades shape amplitude without a
lookahead/delay buffer, so they add no timeline delay; they do attenuate attacks.

Built-in gain/meter/output, preloaded sources and the sine instrument have no
algorithmic delay to compensate between tracks. The graph has no delay inserts,
external plugins or parallel compensated processing paths. Native extensions can
introduce unknown delay, which is neither reported nor compensated. A latency/
tail contract and compensation are required before claiming synchronized delayed
inserts or external hosting. JACK transport sync, external MIDI clock, tempo
maps and physical recording-offset calibration remain unsupported.

## Verification and listening

```
make all test gui test-reliability test-workflow test-gui test-gui-jack
make test-jack test-jack-audio test-jack-midi test-performance
make test-sanitize analyze
make quality-preview
```

`test_quality` is part of `make test`. It covers a sample-rate/tempo matrix up to
768 kHz and the maximum project tick, conversion errors, old/new tempo snapshots
for both audio and MIDI, exact offset/on/off order, sample boundary behavior,
raw versus faded endpoints, media ends shorter than rounded clip ends, split/
whole equivalence, seeks, ramps, stereo parity, overload, NaN/infinity/subnormals
and block sizes 1, 2, 3, 17, 257, 4097, 65535 and 65536. Backend fault tests check
exact master ramps, repeated stop requests, held position/silence after completion,
deactivation failure/retry, immediate escape and recording guards. The workflow
render comparison now enables the GUI source fade policy before/after reopening.

Phase 12 automated checks pass warning-enabled core/GUI and no-JACK builds,
ASan/UBSan/leak checks, static analysis, pthread TSan tests, mock and live GUI,
software JACK audio/MIDI tests and staged installation. GUI leak checks retain
the existing fontconfig-only suppression; core leak checks are unsuppressed.
Physical-device listening and human listening acceptance are **not yet verified**.

`make quality-preview` writes ignored build artifacts `quality-raw.wav` and
`quality-smooth.wav` in BUILD_DIR using `examples/quality_preview.c`. Compare at
moderate playback level: first listen to the three-note phrase endings, then the
constant clip at two seconds, then a mid-period tone stop near three seconds.
Check that fades reduce edge clicks, do not add noise and do not unexpectedly
change pitch/timing. Also listen to the saved MIDI/audio workflow project with
repeated Play/Pause/Stop, Home/seek and representative gain/pan automation on the
actual target device. Record device, rate, block size and observations before
marking human listening acceptance complete. Generated previews are reproducible
test material, not a claim that anyone has listened to them.