Skip to content

Align playback to the proxy's own time line: no added delay with typical client buffers, plus underrun recovery - #80

Open
androbot9000 wants to merge 1 commit into
briankendall:masterfrom
androbot9000:low-latency-alignment
Open

androbot9000 wants to merge 1 commit into
briankendall:masterfrom
androbot9000:low-latency-alignment

Conversation

@androbot9000

Copy link
Copy Markdown

Disclosure: this change was written with Claude (Anthropic's AI coding assistant) and tested on one machine, described below. Happy to split it up or rework anything.

Summary

The proxy currently delays audio by two output buffers, two safety offsets, and a random extra of up to one client buffer. This PR makes each target-device IO cycle play the frames that the proxy's own time line schedules for that moment, so audio comes out when the application's time stamps say it will. With a 512-frame client the measured added delay is 0.

Where the delay came from

anchorInputOutputSampleDelta() placed the read position at

lastInputFrameTime - lastInputBufferFrameSize - outputBufferFrameSize - safetyOffset

lastInputFrameTime is somewhere within one client buffer ahead of the proxy clock's "now", depending on when the anchor happens within the client's cycle. Working that through, the audio is presented 2 * (outputBuffer + safetyOffset) + e frames after the time the client scheduled it for, with e anywhere in [0, clientBuffer). At the old defaults (512-frame output buffer, 512-frame client, a USB device with a safety offset of about 50 frames) that is roughly 23–34 ms at 48 kHz, and it differs from one anchor to the next. That figure is from reading the code; I did not measure the unmodified driver.

What changes

  • Alignment. The read position is anchored at proxyTime(outputTime.mHostTime) - backoff. backoff is 0 when the HAL has already written the frames the cycle needs.
  • Measured write lead. On every WriteMix the driver records how far ahead of the proxy clock's "now" the buffer being written starts, and keeps the minimum over two rolling windows. The HAL writes a full client buffer ahead (I measured a lead of 497–508 frames with a 512-frame client), which is what makes a backoff of 0 safe.
  • Backoff when the lead is short. backoff = presentationLead + frames + margin - leadMin, clamped at 0. With small client buffers playback is held back by just the missing amount.
  • Glitch-free adjustment. The clock servo's set point moves towards the required backoff at 200 ppm, so the delay shrinks or grows without dropping or repeating audio.
  • Underrun recovery. On an underrun the jitter margin is widened and the read position is moved back immediately; the margin is given back after clean windows.
  • Latency reporting. kAudioDevicePropertyLatency now returns the target device's presentation latency instead of 0.
  • Realtime thread. The target IO proc reads volume, mute and sample rate through atomics, so it no longer takes stateMutex.
  • Frame count. Fetch and the copy loop both use the number of frames the HAL asks for in that cycle (previously Fetch used the configured buffer size and the copy loop used the buffer's byte size).
  • Gain ramp. The gain is ramped across each cycle so volume changes don't click.
  • Default output buffer is 64 frames instead of 512. Zero backoff needs roughly 2 * outputBuffer + safetyOffset + 48 <= clientBuffer, so a 512-frame output buffer would still add about 13 ms with a 512-frame client.
  • Diagnostics. A ProxyAudio: stats line is logged while audio is flowing (every 15 s for the first 10 minutes after load, then every 10 minutes), and the driver logs when a marker click from tools/latency-test is written and presented.
  • Small fixes. The box name was read from the box acquired storage key; delete buffer on an array is now delete[].
  • Tools. tools/latency-test.swift and tools/proxyctl.swift (command-line settings, same channel as the Settings app).

The volume curve is not touched here, since #76 covers it.

Measurements

MacBook Air (M2), macOS 27.2.1, target: a class-compliant USB S/PDIF adapter at 48 kHz, output buffer 64 frames. latency-test plays single-sample clicks; the delay is the driver-logged presentation host time minus the host time of the client's inOutputTime for that sample.

Client buffer Added delay Clicks
512 frames within ±3 µs of 0 10/10
128 frames 2.30 ms 8/8
32 frames 4.11 ms 8/8

A 36-second playback run through the default output reported an added delay of 0.9 frames, 0 underruns, 0 re-anchors and a clock trim of −0.1 ppm.

Not tested

  • Intel Macs, and any macOS version other than 27.2.1.
  • Sample rates other than 48 kHz, and sample-rate changes while playing.
  • HDMI/DisplayPort or Bluetooth targets, and targets with more than two channels.
  • Sleep/wake, display wake, and unplugging the target.
  • Runs longer than a few minutes.
  • The Settings app (I built only the driver target and configured it with proxyctl).

Related

🤖 Generated with Claude Code

…ver from underruns

The read position in the ring buffer used to be anchored two output buffers
plus two safety offsets behind the newest input, plus wherever the anchor
happened to fall within the client's IO cycle (up to one client buffer).

Each target device IO cycle now plays the frames the proxy device's own time
line schedules for the moment the target presents that cycle, so the proxy
adds no delay as long as the HAL has already written those frames. How far
ahead of "now" the HAL writes is measured on every WriteMix; when that lead
is too short (small client buffers), playback is held back by the missing
amount plus a jitter margin. The clock servo's set point follows the
required amount at 200 ppm, so the delay shrinks or grows without dropping
or repeating audio.

Also:
- On an underrun, widen the jitter margin and move the read position back
  at once, then give the margin back after clean windows.
- Report the target device's presentation latency as the proxy's latency
  (it was hard-coded to 0).
- Read volume, mute and sample rate through atomics in the target IO proc
  so the realtime thread never waits on stateMutex.
- Fetch and copy the number of frames the HAL asks for in each cycle rather
  than the configured buffer size.
- Ramp the gain across each cycle so volume changes don't click.
- Default output buffer 64 frames instead of 512.
- Log alignment statistics while audio is flowing, and trace marker clicks
  played by tools/latency-test for measuring the added delay.
- Read the box name from its own storage key; delete[] an array.
- Add tools/proxyctl (command-line settings) and tools/latency-test.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant