fix: hold sync corrections while a cold output stream's delay settles

[CrazyDiam0nd-gh]

fix: hold sync corrections while a cold output stream's delay settles

Fixes an audible warble (pitch speeding up, then slowing down, for 5-10 s) after playback starts on a freshly opened output stream. Found while debugging the Music Assistant Companion app on Linux: music-assistant/desktop-app#203.

Problem

On some backends (observed with ALSA over PulseAudio/PipeWire) the output delay reported for a cold stream does not start at its resting value. It overshoots by a few hundred milliseconds in the first second (about 550 ms here) and then relaxes back (to about 250 ms) over several seconds. The audio plays gaplessly; only the estimate moves. raw_error is measured against that estimate and follows it almost 1:1 (with a roughly constant offset), so the planner sees a few hundred ms of "drift" that resolves by itself. It engages at the full 4% cap, then overshoots the other way and slows playback down. That is the warble.

Trace excerpt from two cold starts (callback, playback_delta, raw_error):

cb=119  delta=549.2ms  raw_error=358.4ms
cb=180  delta=440.3ms  raw_error=278.5ms
cb=321  delta=318.4ms  raw_error= 76.2ms
cb=579  delta=255.2ms  raw_error=-13.9ms

with Sync correction engaged: ... drop_every=25 (4%), later insert_every=54..70 (about 1.5%). No underruns, no gaps.

The existing SyncErrorFilter floor-filters one-sided period flapping, but a multi-second relaxation of several hundred milliseconds is a different shape and gets through.

Related

App-side change that removes the cold start for every play after the first:
music-assistant/desktop-app#204

This follows the same idea as #71 (don't treat the beginning of a stream as if it may have drifted, and trust the server's audio until the two clocks have had a chance to differ). #71 and the clock warm-up suppression cover the start of the clock; this covers the start of the output stream, whose reported delay is not in steady state for the first seconds on some backends. The two use the same shape: suppress corrections for a bounded period, then resume normal operation.

Change

• OutputDelaySettle (in sync_correction.rs): tracks the minimum reported delay over 50-callback windows and reports settled once the floor has stayed within 10 ms of the previous window for four consecutive windows. A plateau of a fraction of a second near the peak is not enough (an earlier version with two windows declared itself settled on exactly such a plateau, and the full-rate correction and warble came back at about 7-10 s).
• While the delay is unsettled and less than 10 s have passed since playback started, corrections are held back (including gross reanchors; the stream was only just anchored). When it settles, the all-time delta floor used for reanchors is re-seeded and the error filter and engage gate are reset, since earlier measurements describe the transient.
• For the first 20 s after playback starts, speed corrections are capped at 0.5% (under 9 cents) via CorrectionPlanner::with_max_speed_correction, so any residue of the transient that outlasts the grace period stays inaudible. Thresholds are unchanged.
• New debug line Output delay settled at ... and a trace line for suppressed corrections.

Testing

• cargo fmt --check, cargo clippy --all-targets, cargo test (346 passed). New unit tests: settles on a steady delay, ignores period flapping, rejects the cold-start ramp, rejects slow relaxation, rejects a plateau followed by more relaxation, un-settles when the delay moves again, reset, and the capped planner.
• Real playback on Pop!_OS (ALSA via PulseAudio/PipeWire, USB DAC). Before: a 358-391 ms initial error and a 4% correction on every cold start. After (applied to v0.3.5 for the Companion, which pins that version): the delay settled at 251 ms about 3 s after start, 169 corrections were suppressed during the transient, the strongest speed correction in the run was 0.5%, and by ear the cold first play is clean.

Caveats

• Only tested on Linux with this audio path. On backends whose delay is already steady (WASAPI, CoreAudio), the first correction after a start may be delayed by about 2-3 s while the tracker confirms the delay is steady. The engage gate already waits about 1 s, so this is a small change, but I haven't measured it there.
• The 10 s / 20 s / 0.5% / 4-window constants are tuned from one setup. Happy to adjust or make them configurable.
• Sync across multiple players is looser during the first few seconds of a cold start; the trade-off is no audible warble.

[teancom]

Lovely, thank you!