Repository navigation
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
Conversation
…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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 atlastInputFrameTimeis 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 presented2 * (outputBuffer + safetyOffset) + eframes after the time the client scheduled it for, witheanywhere 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
proxyTime(outputTime.mHostTime) - backoff.backoffis 0 when the HAL has already written the frames the cycle needs.WriteMixthe 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 = presentationLead + frames + margin - leadMin, clamped at 0. With small client buffers playback is held back by just the missing amount.kAudioDevicePropertyLatencynow returns the target device's presentation latency instead of 0.stateMutex.Fetchand the copy loop both use the number of frames the HAL asks for in that cycle (previouslyFetchused the configured buffer size and the copy loop used the buffer's byte size).2 * outputBuffer + safetyOffset + 48 <= clientBuffer, so a 512-frame output buffer would still add about 13 ms with a 512-frame client.ProxyAudio: statsline 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 fromtools/latency-testis written and presented.box acquiredstorage key;delete bufferon an array is nowdelete[].tools/latency-test.swiftandtools/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-testplays single-sample clicks; the delay is the driver-logged presentation host time minus the host time of the client'sinOutputTimefor that sample.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
proxyctl).Related
🤖 Generated with Claude Code