SonixLatencyCalibration

Measures the residual playback-out latency this device leaves after the OS-timestamp presentation clock (ADR-021 follow-up): how far the playback presentation clock still leads the truly-audible output. Measured through a SonixMixer with the probe as its reference track — the same clock the live-eval scorer anchors through in practice; the bare single-track player can have a different DAC sink, so calibrating it would mis-compensate real takes.

Method — a speaker→mic loopback in the exact audio path scoring uses, with a frequency sweep (chirp) as the probe, not a bare click. A chirp cross-correlated with itself gives one sharp, unambiguous peak, so the arrival survives room noise, reverb, and the phone speaker's uneven response — the production-grade signal for latency calibration (a bare tone + amplitude threshold gets lost in a real living room). Each chirp is authored at a known player time; cross-correlating the chirp template against the recording finds its arrival sample. The mixer's presentation clock (audibleTimeMsAtWallNanos) only reports while the track is playing, so it is sampled live per recorded buffer during playback and mapped to the arrival offline:

leadMs = playerClockMsAt(arrivalCaptureTs) - chirpPlayerTimeMs

is exactly the playback-out latency the scorer's contour anchoring suffers. Median over several chirps; a consistent lead self-validates the matching.

Constraints:

• Speaker output only (no headphones/BT): the mic can't hear those routes, so this measures the speaker/wired media path — the device constant. Bluetooth's extra remainder is left to the scorer's graceful-slip handling. Before reaching for a way to measure or default the Bluetooth remainder, read docs/android-bluetooth-latency.md: there is no public Android API for a route's latency, codec does not predict it, and the measured remainder is a different quantity from the totals headphone review labs publish.

• Measures with compensation forced to 0, then restores it, so it reports the raw lead regardless of any value already set.

Fail-safe: returns 0 (no compensation) if no chirps are detected.