English | 简体中文
A macOS menu bar audio bridge for HDMI / DisplayPort displays.
SoundBridge creates a virtual output device, gives it native macOS volume and mute controls, applies EQ and spatial processing, and forwards the result to a physical display output. It is built as a HAL (AudioServerPlugIn) driver plus a Swift menu bar app and engine.
Personal project, not affiliated with SpeakerAmp. SpeakerAmp was used only as an A/B reference while tuning the spatial effect.
macOS does not expose a volume control for most HDMI / DisplayPort audio
endpoints. A virtual output device can provide one, but a naive virtual driver
loses sound after clamshell sleep/wake because the physical endpoint is
destroyed and recreated with a new AudioObjectID (the UID stays the same).
SoundBridge follows the same general architecture as SpeakerAmp, but the
physical route is resolved by UID, never by a cached AudioObjectID.
- Virtual output device
SoundBridgewith nativeVolumeScalar/Muteproperties - System volume keys, native OSD, Control Center and mute key work without Accessibility permissions or media-key interception
- 10-band peaking EQ (50 Hz – 15 kHz, ±12 dB)
- Pre-amp gain −15…+15 dB, applied before the EQ and protected by the limiter
- Configurable global shortcuts for volume up, volume down and mute
(Carbon
RegisterEventHotKey, no Accessibility permission) - Spatial effect: M/S widening, crossfeed, early reflections and Apple
AUMatrixReverb(Large Hall), calibrated against SpeakerAmp Hall 50% - Look-ahead limiter
- UID-based wake rebinding with debounce, backoff and silent standby
- Sleep-safe:
willSleeppauses the watchdog; ring backlog is bounded after wake - Shared-memory audio transport between plugin and engine: no microphone permission, no orange microphone indicator
- Menu bar icon with volume-following sound waves, control panel with Spatial / Equalizer / Shortcuts / About tabs
- Chinese and English UI, following the system language or selectable manually
- Optional launch at login
macOS applications
│
▼
SoundBridge virtual output device (HAL plugin, /Library/Audio/Plug-Ins/HAL)
│ native Volume / Mute properties
▼
shared-memory ring (/tmp/soundbridge_ring_v1)
│
▼
engine (menu bar app)
EQ → spatial → limiter
│
▼
physical display output, resolved by UID (HDMI / DisplayPort)
The HAL plugin only publishes the device, implements volume/mute, keeps a loopback ring, and writes the post-volume mix into shared memory. DSP, forwarding, clock-drift compensation and wake rebinding live in the engine.
The engine:
- resolves the physical output by
kAudioDevicePropertyDeviceUIDevery time - listens to
kAudioHardwarePropertyDevices,kAudioDevicePropertyDeviceIsAlive,didWakeandscreensDidWake - survives the common “device rebuilt twice” sequence
- keeps the virtual device running while the physical endpoint is absent
- retries with backoff and a 1 s watchdog
- resets a large ring backlog with a short fade after wake to keep latency low
- macOS 13.0 or newer (Ventura+)
- Universal build: Apple Silicon (
arm64) and Intel (x86_64) - Xcode 15/16 command line tools (
swiftc,clang,codesign,pkgbuild) - A physical HDMI / DisplayPort output. Tested with:
- MacBook Air M3, macOS 14.6
- LECOO M3221PL, DisplayPort, 2ch / 48 kHz
SpeakerAmp is not required. It can remain installed as a fallback.
Build the two local packages:
git clone https://github.com/jerryforgit/SoundBridge.git
cd SoundBridge
./packaging/build.shThis produces:
packaging/build/SoundBridge.pkg # app + HAL plugin
packaging/build/Uninstall.SoundBridge.pkg # clean uninstall
Install:
open "packaging/build/SoundBridge.pkg"
# or
sudo installer -pkg "packaging/build/SoundBridge.pkg" -target /The installer copies:
/Applications/SoundBridge.app/Library/Audio/Plug-Ins/HAL/SoundBridge.driver
and restarts coreaudiod (audio is interrupted for 2–3 seconds).
./driver/build.sh
./app/build.sh
./scripts/install.sh # sudo; installs the HAL plugin only
open app/build/SoundBridge.appscripts/install.sh and scripts/uninstall.sh only manage the HAL plugin.
They do not touch the app bundle.
Open SoundBridge.app. The menu bar shows a speaker icon and a percentage.
Clicking the icon opens the status menu and, like SpeakerAmp, switches the
system default output to SoundBridge (can be disabled in the menu).
No microphone permission is requested. If an older build left a stale grant:
tccutil reset Microphone com.jerry.soundbridge- Status menu: volume slider, mute, control panel, spatial/EQ bypass, output device, default-output toggle, launch at login, language, engine log
- Control panel (
Control panel…):- Spatial: preset, width, depth, reverb, pre-amp gain, A/B bypass, limiter
- Equalizer: 10 vertical bands, presets, bypass, Flat reset
- Shortcuts: volume up, volume down and mute
- About: project/architecture notes
- Volume keys / OSD: native, because the virtual device implements the standard volume properties
- Output device: choose another HDMI/DisplayPort/USB/built-in output in the status menu. The engine rebinds by UID.
- Language: system default, 中文 or English. The control panel is recreated when the language changes.
- Launch at login:
SMAppService, so it appears under System Settings → General → Login Items → Open at Login. The installer unregisters the old build's item before replacing the app, and the new build re-registers on first launch when the preference is on.
Hall— AppleAUMatrixReverbLarge Hall, wet 50 (×0.5 calibrated to SpeakerAmp's Hall 50%)SpeakerAmp (Medium Hall)— same AU, Medium Hall, for A/BHall (Schroeder)— earlier built-in approximation- Standard / Movie / Music / Night — lighter built-in spatial settings
- Volume Up, Volume Down (1/16 = 6.25% per press) and Mute
- click a recorder button, then press the key combination
Deleteclears the shortcut,Esccancels recording- shortcuts are off by default; native volume keys/OSD still work unchanged
- registered with Carbon
RegisterEventHotKey, so no Accessibility permission is needed - custom shortcuts do not trigger the system OSD; the menu bar percentage updates instead
open "packaging/build/Uninstall.SoundBridge.pkg"
# or
sudo installer -pkg "packaging/build/Uninstall.SoundBridge.pkg" -target /It quits the app, unregisters its login item, removes the app, HAL plugin,
shared memory, preferences and logs, then restarts coreaudiod and Dock.
SpeakerAmp / BlackHole / MAXHUB are untouched.
./scripts/uninstall.sh # removes the HAL plugin
# then quit the app and move /Applications/SoundBridge.app to the Trash
sudo rm -f /tmp/soundbridge_ring_v1| Path | Contents |
|---|---|
driver/SoundBridge |
C++ AudioServerPlugIn (libASPL-based) |
driver/third_party/libASPL |
vendored MIT-licensed AudioServerPlugIn helper |
engine/ |
Swift engine: CoreAudio routing, wake rebinding, DSP, shared memory |
app/ |
AppKit menu bar app, control panel, icon generator |
packaging/ |
pkgbuild scripts for install/uninstall packages |
scripts/ |
developer install/uninstall for the HAL plugin |
wakespike/ |
standalone UID-rebind wake-test harness |
tools/ |
small CoreAudio device/default-output tools |
docs/ |
environment, test results and reference notes |
SPEC.md |
original design brief and acceptance criteria |
No sound
- Check that the system default output is
SoundBridge. - Pause/play the video or music once. Some browsers keep an old audio stream after the default output changes.
- Check the status menu: the engine should say “running”.
- Tail the log:
tail -f ~/Library/Logs/SoundBridge/engine.logA healthy start looks like:
shared memory: available
reconcile: input=shared output=...
OUTPUT STARTED ...
The HAL plugin is not loaded
ls /Library/Audio/Plug-Ins/HAL/SoundBridge.driver
sudo killall coreaudiodWake recovery
Look for:
output REBIND: old id=... -> new id=... (uid unchanged)
OUTPUT STARTED ...
Gatekeeper / PKG
The app and plugin use ad-hoc signatures; the PKGs are unsigned. For local use,
right-click the package and choose Open, or use sudo installer.
- Ad-hoc signed / not notarized; intended for personal use
- CPU around 2.5% on an M3 with AUMatrixReverb enabled (slightly above the 2% original target); the reverb is the dominant cost
- The spatial effect is calibrated by ear against SpeakerAmp; it is not bit-identical to SpeakerAmp's processing
- The shared-memory ring is a local file in
/tmp; all audio stays on the machine - No App Store distribution
- 10/10 clamshell sleep/wake recoveries with the shared-memory transport
- 2-hour continuous playback: RSS stable at ~20 MB, no errors, ring median 512 frames
- Pre-amp gain: −6 dB measured 0.5012×, +6 dB measured 1.9953×; +15 dB is limited to −1 dBFS by the look-ahead limiter
- Shortcuts: recording, Carbon registration, volume ±/mute actions and persistence verified; no Accessibility permission requested
- Login item appears under Open at Login and is removed on uninstall
- Universal app: arm64 native and x86_64 under Rosetta; the x86_64 HAL driver still needs verification on Intel hardware
- Uninstall removes driver/device/process and restores system audio
- No microphone permission or orange microphone indicator
See docs/TEST-RESULTS.md and
docs/ENVIRONMENT.md.
MIT. See LICENSE and
THIRD_PARTY_NOTICES.md.

