Add a native CoreAudio sink and drop PortAudio from the macOS build by chrisuthe · Pull Request #66 · Sendspin/sendspin-cpp-cli

chrisuthe · 2026-09-17T21:38:31Z

The released macOS binary aborts at launch on any Mac without Homebrew's PortAudio:

dyld[38468]: Library not loaded: /opt/homebrew/opt/portaudio/lib/libportaudio.2.dylib
Referenced from: /usr/local/bin/sendspin-cli

CI brewed portaudio on the macos-14 runner and then smoke-tested the .pkg on that
same runner, so the one host that could have caught it was the one host guaranteed not to.

The fix is not to bundle the dylib but to stop needing it. CoreAudio and AudioToolbox ship
with macOS, so the binary now links only what every Mac already has. PortAudio stays in the
tree and stays ON everywhere but the macOS release leg.

The sink

src/coreaudio_sink.{h,cpp}, an AudioSink over AUHAL, modelled on portaudio_sink.{h,cpp}
and reusing PcmRingBuffer, pcm_volume and SinkRecovery/OutageGapHandoff rather than
reimplementing them. The four invariants portaudio_sink.h writes down come from the
AudioSink contract, not from PortAudio, so they carry across unchanged.

Sync feedback from the render callback's AudioTimeStamp, converted through
mach_timebase_info(). That timestamp is when the hardware consumes the buffer rather than
when it reaches the speaker, so kAudioDevicePropertyLatency, kAudioStreamPropertyLatency
and the unit's converter latency go on top — unlike PortAudio, where outputBufferDacTime
already carries them. kAudioDevicePropertySafetyOffset is deliberately not in that sum:
it is the margin the HAL schedules ahead by, so it is already in how far in the future the
timestamp sits. (It was in the sum at first; Apple's own description of the timestamp on
coreaudio-api, and cubeb — also AUHAL, same structure — settled it. A whole-path latency
figure like mpv's, which also folds in kAudioDevicePropertyBufferFrameSize, is the wrong
thing to add to a per-buffer timestamp.)
8/16/24/32-bit through a packed signed little-endian ASBD on the unit's input scope,
letting the AU convert. capabilities() probes the three ladders by setting each candidate
format on a scratch unit — the same question a stream asks.
-o coreaudio[:<device>], with PortAudio's device grammar exactly, re-resolved per stream.
In-place recovery without item 14's rescan cycle: an AudioDeviceID is stable and
AudioObjectAddPropertyListener reports kAudioDevicePropertyDeviceIsAlive directly, so
there is no Pa_Terminate()/Pa_Initialize() and no index renumbering.
A moved system default is followed, deliberately outside SinkRecovery's budget: a move is
an ordinary event, and spending the reopen on it would leave a real outage in the same
track with nothing left.

CI

with_portaudio joins the matrix on every leg (a key missing from one reads as false),
OFF on macos-arm64 only. That leg's brew install portaudio pkgconf is gone — nothing
left on it needs pkg-config — its expect_backends is null, stdout, coreaudio, and its
runtime_packages is the fact that there are none.

And the guard that would have caught this: a macOS step running otool -L over the staged
binary and failing on any load command outside /usr/lib and /System. Worth having
whatever the backend is. Proven by hand against both a clean listing and a Homebrew-tainted
one; no deliberately broken commit is left behind.

What is and is not proven

Linux is unchanged and green: 437/439 (the two failures are a local path-length quirk of the
task worktree, not a regression — they resolve a relative socket path against a cwd that
overflows sun_path, and pass from a short cwd). scripts/smoke_test.sh,
scripts/format.sh --check and shellcheck scripts/*.sh are clean, and
tests/device_spec_test.cpp covers the -o coreaudio[:...] forms and the Linux
reserved-backend refusal on every leg.

This was written on Linux, where it is not built, so CI's macos-arm64 leg was the first
compiler to see it — and it compiles clean there under -Werror. That leg's otool -L guard
reports only CoreAudio, AudioToolbox, CoreFoundation, libc++ and libSystem: no
/opt/homebrew path, no bundled dylib. 425/425 ctest on macOS, and no brew step left.

The hardware pass is done — three rounds on a MacBook Pro (M5 Pro, macOS 26.6.2) against
built-in speakers, a USB interface and a DisplayPort monitor. It plays.

Clean tone at 48 kHz/16-bit, 44.1 kHz/24-bit and 44.1 kHz/32-bit; otool -L clean on a machine
that has Homebrew, which is what makes that result mean anything.
on_frames_played does not accumulate error: −35 ppm over five minutes.
DAC offset 37.95 ms mean against a reported 15.6 ms device latency, and it held on a second
device (23.40 ms against 1.0 ms). Resampling 44.1→48 kHz added +0.72 ms, which is the audio
unit's converter latency appearing exactly where it should and nowhere else.
Recovery: the system default was moved five times mid-stream and followed every time without a
restart; a USB device was unplugged and replugged and reopened itself in 190 ms, where the
backoff ladder alone would have waited another 11.5 s.
A real Music Assistant server drove it end to end, and a second player in the same group was
in phase — the only real test the DAC offset has.

Two things the pass turned up are recorded rather than fixed here:

A second outage in one stream never recovers — split out as roadmap item 28 and its own
task. It predates this backend (39cf29b, item 14) and lives in shared SinkRecovery, so it
changes all four device-backed sinks and wants its own hardware pass per backend.
A single pop as the unit starts, on two different DACs and through both harness commands.
The data path was ruled out by reading it, so it points at the device un-muting rather than at
anything here.

The released macOS binary inherited Homebrew's absolute install name for libportaudio.2.dylib and aborted under dyld on any Mac without it. CI could never see it: the runner brewed portaudio, then smoke-tested the .pkg on that same runner. CoreAudio and AudioToolbox ship with macOS, so the binary now links only what every Mac already has. PortAudio stays in the tree, built OFF on the macOS release leg alone. Also add the guard that would have caught this: a macOS CI step failing on any load command outside /usr/lib and /System.

A lost device does not stop the render callback -- the HAL keeps pulling until the unit does. So clear() asking unit_alive_() took the ring_.drop() branch while the callback was inside read(), writing both positions from the producer side and leaving the next read a whole ring of stale audio to play. clear() now asks callback_running_(), which is liveness alone. configure() and write() keep unit_alive_(), which is the question they actually have.

The render timestamp is when the hardware consumes the buffer, so the presentation latency belongs on top of it -- but the safety offset does not. That is the margin the HAL schedules ahead by, so it is already in how far in the future the timestamp sits, and adding it biased every DAC time by the device's offset, typically 33-64 frames. Leaves kAudioDevicePropertyLatency + kAudioStreamPropertyLatency + the unit's converter latency, which is what cubeb adds to the same AUHAL timestamp.

The sink plays: clean tone at all three formats, no accumulating drift, a DAC offset that holds across two devices, recovery from both a default move and an unplug, and a second player in phase over a real server. Two things came back open. The volume ramp was heard as a step on full->half, which is a 12.9 ms ramp rather than the 20 ms a full-scale change takes -- so open_unit_() now logs the step, since a fast ramp and a snap sound alike but only one of them is a bug. The outage-gap figure is still owed: the test harness lost frames of its own and swamped it.

A dying device reports itself through kAudioDevicePropertyDeviceIsAlive, but a returning one has nothing to report, so a replugged named device was found only by SinkRecovery's 2->30 s ladder. The hardware pass measured the cost: a device physically back at 21 s was not reopened until 41 s, because the ladder had already doubled past it. Listen on kAudioHardwarePropertyDevices too, and give SinkRecovery a rescan_soon() that brings an owed rescan forward to the next tick. It arms nothing that is not already owed and the attempt still counts, so a burst of plug events cannot spin.

The device-list listener is confirmed on hardware at 190 ms from replug to reopen, where the backoff ladder would have waited another 11.5 s. The pass also turned up a second outage in one stream never recovering. That one predates this backend and sits in shared SinkRecovery, so it gets item 28 and a task of its own rather than widening this branch.

Copilot

Copilot review overview

🟡 Changes recommended

Listener lifetime and ring-tail races can cause use-after-free behavior and incorrect playback accounting.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1 · 2 · 2

Open (5)

Prevent listener callback use-after-free during teardown · New
Synchronize render callback before measuring tail · New
Handle required liveness listener registration failure · New
Reconcile contradictory hardware validation status · New
Shorten rationale to essential latency invariant · New

What changed in this PR

Adds a native CoreAudio backend so macOS releases no longer depend on Homebrew’s PortAudio library.

Changes:

Implements CoreAudio playback, device selection, latency reporting, and recovery.
Integrates CoreAudio into CLI parsing, CMake, tests, and documentation.
Disables PortAudio for macOS releases and adds a system-library dependency check.

File	Description
`src/coreaudio_sink.h`	Defines the CoreAudio sink interface and state.
`src/coreaudio_sink.cpp`	Implements AUHAL playback, probing, recovery, and synchronization.
`src/audio_sink.h`	Adds the CoreAudio backend identifier.
`src/audio_sink.cpp`	Registers, constructs, and lists CoreAudio devices.
`src/cli.h`	Makes CoreAudio the macOS default output.
`src/sink_recovery.h`	Adds immediate rescan support.
`src/sink_recovery.cpp`	Implements notification-triggered rescans.
`tests/device_spec_test.cpp`	Tests CoreAudio output syntax and availability.
`tests/sink_recovery_test.cpp`	Tests immediate rescan behavior and limits.
`CMakeLists.txt`	Builds and links CoreAudio on Apple platforms.
`.github/workflows/build.yml`	Removes macOS PortAudio and checks dynamic dependencies.
`.github/workflows/build-armv6.yml`	Explicitly retains PortAudio for ARMv6.
`docs/wiki/Advanced-Usage.md`	Documents CoreAudio device syntax.
`docs/wiki/Configuration.md`	Documents the new default and examples.
`docs/wiki/Home.md`	Lists CoreAudio among supported backends.
`docs/wiki/Installation.md`	Clarifies dependency-free macOS installation.
`docs/wiki/Troubleshooting.md`	Includes CoreAudio buffering behavior.
`docs/ROADMAP.md`	Records the CoreAudio implementation and validation.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

chrisuthe · 2026-09-18T23:36:34Z

+    this->recovery_.discard_frames(
+        static_cast<uint32_t>(this->ring_.available() / this->bytes_per_frame_));


Fixed in c35e82b.

Confirmed and worth catching — it fires on every default-output move and every reopen, not just the unlikely path. discard_ring_tail_() now stops the unit before it counts, so the window between the ring_.available() snapshot and close_unit_()'s stop is gone. close_unit_() sees running_ == false and skips its own stop.

Magnitude was up to one device buffer (~10 ms at 48 kHz) double-counted per recovery event.

chrisuthe · 2026-09-18T23:36:37Z

 - **`SENDSPIN_SERVER_URL` is answered only for the server_id the dial chose.** `LastDial` has
  no "literal URL, taken at its word" case left; a dial with no id answers nothing.
+
+### 27. Native CoreAudio backend — *shipped (hardware pass still owed)*


Fixed in c35e82b.

Genuine contradiction and mine. The heading still read shipped (hardware pass still owed) three rounds after the pass was actually run; it is now shipped. The PR description is updated to match.

Stop the render callback before counting the ring tail: a callback draining between the count and close_unit_()'s own stop reported those frames as played on top of the outage gap they had just been charged to. Up to one device buffer per recovery, on every default move and every reopen. Warn when the liveness listener will not register -- nothing else sets device_lost_, so a death would go unnoticed and recovery would never run. Item 27's heading still said the hardware pass was owed, three rounds after it was done, and the DAC-time comment had grown into the rationale essay AGENTS.md forbids; the reasoning is in the roadmap where it belongs.

Item 28 shipped on main while this was in review, so SinkRecovery now refills the budget on a recovered rescan and has rescan_abandoned(). Kept both that and rescan_soon() from here; refill_() clears rescan_immediate_, so a refill from either side starts the ladder clean. Restores item 28's roadmap entry, which 74d94c0 deleted while rewriting the tail of the file for item 26 -- the code shipped, the entry did not survive.

Native CoreAudio on macOS in place of PortAudio (Sendspin#66), the second-outage recovery fix that every device-backed sink needed (Sendspin#67), and direct-address dialling restored to -s beside mdns: discovery (Sendspin#68).

chrisuthe added 7 commits September 17, 2026 16:33

Record what CI proved about the CoreAudio sink in item 27

b5930e3

chrisuthe marked this pull request as ready for review September 18, 2026 20:52

chrisuthe mentioned this pull request Sep 18, 2026

Recover from a second device outage in the same stream #67

Merged

chrisuthe requested a balanced review from Copilot September 18, 2026 23:02

Copilot started reviewing on behalf of chrisuthe September 18, 2026 23:02 View session

Copilot AI reviewed Sep 18, 2026

View reviewed changes

chrisuthe added 2 commits September 18, 2026 18:36

chrisuthe merged commit c4c5f82 into main Sep 19, 2026
17 checks passed

chrisuthe mentioned this pull request Sep 19, 2026

Release 0 3 0 #69

Merged

Navigation Menu

Add a native CoreAudio sink and drop PortAudio from the macOS build - #66

Add a native CoreAudio sink and drop PortAudio from the macOS build#66
chrisuthe merged 9 commits into
mainfrom
chrisuthe/task/replace-portaudio-with-a-native-coreaudio-sink-on

chrisuthe commented Sep 17, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

chrisuthe Sep 18, 2026

Uh oh!

Uh oh!

chrisuthe Sep 18, 2026

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		this->recovery_.discard_frames(
		static_cast<uint32_t>(this->ring_.available() / this->bytes_per_frame_));

Conversation

chrisuthe commented Sep 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

The sink

CI

What is and is not proven

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Copilot review overview

🟡 Changes recommended

Uh oh!

Uh oh!

chrisuthe Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chrisuthe Sep 18, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

chrisuthe commented Sep 17, 2026 •

edited

Loading