Expose AudioContext.baseLatency / outputLatency (Web Audio spec) for latency compensation

[akinadebowale]

Description

The Web Audio API specifies AudioContext.baseLatency and AudioContext.outputLatency. Neither is exposed by react-native-audio-api at 0.12.2 — not natively, and the web wrapper doesn't pass the browser's values through either (no baseLatency/outputLatency anywhere in the published types).

Why it matters

Any app that records against playing audio (overdub recording, call-and-response, rhythm games) needs recording latency compensation: a take performed in time lands outputLatency + inputLatency late on the timeline unless the app shifts it back. Right now there is no API surface to get those numbers, so apps must ship their own native module or a loopback-calibration flow. For scale: on an iPhone 16 speaker route (playAndRecord), I measure a ~188 ms end-to-end record round-trip through the library — all of it invisible to JS today.

The platform data already exists:

• iOS: AVAudioSession.{outputLatency, inputLatency, ioBufferDuration} map directly (outputLatency → spec outputLatency; ioBufferDuration-derived term → baseLatency).
• Android: the library owns the Oboe streams — AudioStream::calculateLatencyMillis() and stream timestamps are available on the open stream.
• Web: pass through the browser's own properties.

Proposal

1. context.baseLatency / context.outputLatency per spec (getters, snapshot per call).
2. Bonus for the recording side: an equivalent input figure (e.g. AudioRecorder.inputLatency or a field on the onAudioReady event) — the spec has nothing here, but AVAudioSession.inputLatency and the Oboe input stream both report it.

Together with #1103 (populate the recorder when), this would make sample-accurate overdub placement possible without any app-side native code.

Environment

react-native-audio-api 0.12.2, iOS + Android + web, new architecture.

[mdydek]

how exactly did you measured latency?

[akinadebowale]

Acoustic loopback through the library's own playback + record paths, end to end:

1. An AudioContext schedules short metronome clicks at known context-clock times (a beat grid at 120 BPM), playing out the speaker.
2. Simultaneously an AudioRecorder captures (iOS playAndRecord, speaker route), so the clicks bleed acoustically speaker → mic and travel the full output + input path.
3. Capture frame 0 is anchored to the context clock by back-extrapolating from the early onAudioReady deliveries: candidate = context.currentTime(at delivery) − framesDelivered/sampleRate, minimum over the first ~0.5 s of candidates (delivery delay is one-sided — buffers arrive late, never early).
4. Onset-detect the clicks in the captured PCM and measure each one's offset from its scheduled grid time. With no compensation applied, the median offset is the end-to-end round-trip.

Result on the iPhone speaker route: p50 187.9 ms, p95 188.7 ms / sub-millisecond spread across clicks, i.e. constant for a given device + route. Cross-check: applying the measured value as a placement offset and re-running the same loopback leaves a ~2.9 ms residual, so the number is the real placement error, not an artifact of the harness.

Reason I made the issue: AVAudioSession.outputLatency + inputLatency sampled at the same moment summed to only a few tens of ms, so most of the 188 ms is buffering inside the pipeline that no OS API reports.