bluetooth
Extra compensation, in milliseconds, added on top of outputLatencyCompensationMs when the track is routed to SonixOutputRoute.BLUETOOTH. Default 0 leaves behaviour unchanged on every route.
A Bluetooth sink adds a transport delay the speaker-measured constant cannot cover, and the consuming app has to supply the number because nothing else can:
The chirp loopback (SonixLatencyCalibration) can only measure the speaker — the mic cannot hear the user's earbuds, so the BT route is unmeasurable by construction.
No public Android API reports a route's (or a codec's) latency; the ones that exist are
@hide.Codec does not predict it: independent lab measurement finds ~90 ms of spread within SBC alone, from product category, so a codec-derived default would be wrong by the same order as the error it corrects.
That leaves a conservative constant, sized from measured clock under-report — how much later the audio is audible than the presentation clock claims. It is NOT the total acoustic latency headphone review sites publish: the OS clock already absorbs part of that, so a published total used here would badly over-compensate.
It must under-compensate. Over-compensating is the worse failure: it shifts the contour early and penalises a singer who was on time, with no way for them to correct it. Under-compensating just leaves some of the original error.
See docs/android-bluetooth-latency.md for the measurements, the dead ends, and how to measure the excess on a new device.