HeadBridge

HeadBridge brings AirPods-style system controls to third-party Bluetooth headphones on macOS. It is a native menu-bar app with independently implemented providers for recent Bowers & Wilkins RPC devices and Sony MDR V1 headphones.

Warning

HeadBridge is an early beta. Hardware validation currently covers Bowers & Wilkins Px7 S3 and Sony WH-1000XM3. Recognition of another model is not a guarantee that every control is compatible. Public builds use a project-owned self-signed identity, not an Apple Developer ID, and are not notarized; read Self-signed builds and security before installing.

Install

HeadBridge requires macOS 14 or newer. The optional Control Center extension requires macOS 26.

Install the latest release directly into /Applications:

curl -fsSL https://github.com/herenickname/HeadBridge/releases/latest/download/install.sh | bash

The command downloads and executes the installer attached to the latest GitHub Release. Because HeadBridge is not notarized, the installer removes Apple's quarantine attribute from the installed HeadBridge.app only. That bypasses Gatekeeper for this app. If you do not want to run a remote script unseen, inspect it first:

curl -fsSL https://github.com/herenickname/HeadBridge/releases/latest/download/install.sh \
  -o /tmp/headbridge-install.sh
less /tmp/headbridge-install.sh
bash /tmp/headbridge-install.sh

Manual installation

1. Download the app archive from the latest GitHub Release.

2. Extract it and move HeadBridge.app to /Applications.

3. Review the source and release workflow to the degree appropriate for your threat model.

4. If macOS blocks the app because it is from an unidentified developer, remove quarantine from this bundle explicitly:

   sudo xattr -dr com.apple.quarantine /Applications/HeadBridge.app
   open /Applications/HeadBridge.app

5. Allow Bluetooth access and connect the headphones as a macOS audio output.

HeadBridge has no Dock icon. Open its headphones icon in the menu bar, then choose HeadBridge Settings… for the full settings window.

Updating

Use HeadBridge Settings… → Check for Updates… for in-app updates, or run the install command again. Sparkle verifies update archives using the public key embedded in the app; this update signature is separate from Apple Developer ID signing and notarization.

Compatibility

Provider family	Hardware validation	Status
Bowers & Wilkins RPC	Px7 S3, firmware 3.17.4.17	Validated
Recent PX/PI models exposing the same RPC service	Not yet tested	Experimental and capability-probed
Sony MDR V1	WH-1000XM3	Validated on hardware
Other Sony MDR V1 models	Not yet tested	Experimental common controls
Sony MDR V2 / Link2	Service generation is detected	Not supported yet

Firmware updates can change behavior. Please include the exact model, firmware, macOS version, and working/broken controls in a device-support report.

Add support for your headphones

The maintainer physically owns and tests only a Bowers & Wilkins Px7 S3 and a Sony WH-1000XM3. I can review code for another model, but I cannot honestly claim that it works without somebody testing it on that exact hardware.

If you want HeadBridge to support another device, the fastest path is:

1. Fork or clone this repository.
2. Open the checkout in Codex or Claude Code and select the latest capable coding model available to you.
3. Ask it to read CONTRIBUTING.md and docs/PROVIDERS.md, then adapt the closest provider or add a new one. Give it the exact model, firmware, and observations from your headphones; do not let it guess unknown protocol behavior.
4. Build HeadBridge and exercise every exposed control on the real device, including disconnect/reconnect and restore-on-connect.
5. Run the repository checks and open a GitHub Pull Request with the hardware results. A device-support issue by itself cannot make an untested model validated.

AI assistance is welcome, but the Pull Request author is responsible for reviewing the resulting code and confirming its behavior on hardware. See the contributor workflow for the full checklist.

Features

macOS integration

• Output selection and immediately observed Core Audio volume.
• Input devices on Option-click.
• Sticky Input, which restores a user-selected microphone if macOS switches it after a headset connects.
• Active-headphone battery in the menu bar: never, only below 20%, or always.
• Per-headset 24-hour, 7-day, and 30-day battery charts. While connected, one lightweight sample is stored every five minutes and retained locally for 90 days.
• Optional Launch at Login and cryptographically verified Sparkle updates from GitHub Releases.
• Per-provider restore-on-connect profiles that reapply settings after another source, such as a phone, changes them.
• macOS 26 Control Center controls for active-headphone noise mode and Sticky Input.
• No continuous vendor scan while a matching Bluetooth audio output is absent.

Bowers & Wilkins RPC

The provider targets a protocol family rather than one model. Device capabilities and command replies determine which controls are shown. Px7 S3 validation currently covers:

• ANC, pass-through, and off;
• five-band EQ and bypass;
• battery, charging state, source, codec, and sample rate;
• wear sensor, sensitivity, standby timer, quick-action button, voice prompts, and local name;
• True Immersion modes;
• optional advanced RPC values/log diagnostics, disabled by default.

Destructive operations such as factory reset, pairing-list mutation, firmware update, and DFU are intentionally not exposed.

See the independent Bowers & Wilkins RPC wire notes for transport discovery, message framing, capability probing, and contributor safety boundaries.

Sony MDR V1

The pure-Swift V1 stack uses IOBluetooth RFCOMM, incremental framing, an ACK/retry queue, and model capability profiles. WH-1000XM3 validation currently covers:

• noise cancellation, ambient sound, wind reduction, off, and ambient level where applicable;
• all WH-1000XM3 EQ presets and six manual bands, including Clear Bass;
• Surround (VPT), sound position, DSEE HX, and touch-sensor control;
• NC optimizer state and atmospheric-pressure readback;
• automatic power-off and sound-quality/stable-connection modes;
• battery, codec, and independent headset volume;
• optional one-way macOS → headphones volume synchronization (0...30).

See the independent Sony MDR V1 wire notes and V2 adapter notes.

Known limitations

• Only the two models listed as validated above have been tested on hardware.
• Sony MDR V2/Link2 is recognized but not implemented.
• Sony volume synchronization currently flows from macOS to the headphones, not in both directions.
• Changing Sony sound-quality mode reconnects Bluetooth audio.
• The macOS Control Center extension requires macOS 26; the menu-bar app supports macOS 14 and newer.
• A provider currently owns one active control session for its protocol family. Simultaneously controlling two headphones from the same family is not yet supported.
• Common battery, connection, and noise controls flow through HeadphoneProvider; richer vendor controls still require a small UI registration in HeadBridge.

Privacy

HeadBridge has no account, analytics, telemetry, or cloud sync. Headphone control happens locally over Bluetooth. Battery history includes a stable local device identifier and is stored for 90 days in ~/Library/Application Support/HeadBridge/BatteryHistory.plist; it can be cleared from each device's settings.

Sparkle contacts GitHub Releases when update checks are enabled. Advanced diagnostic views remain local unless the user exports their contents. See PRIVACY.md for details.

Self-signed builds and security

Current public builds use the stable, project-owned HeadBridge Self-Signed Release identity. It is not connected to an Apple developer account, has no Apple Team Identifier, and is not notarized by Apple. The stable identity lets macOS recognize later HeadBridge builds as updates of the same app, so Bluetooth consent is not reset merely because the executable changed. It does not make the app Apple-trusted: macOS still quarantines a downloaded build and may refuse to launch it until quarantine is removed.

The installer verifies the ZIP checksum, bundle identifier, universal architectures, and exact public release-certificate fingerprint. It then installs HeadBridge.app into /Applications and removes quarantine from that exact bundle so macOS can launch it. This still does not establish Apple trust. Piping a network response into a shell and bypassing Gatekeeper both carry risk. The installer, public certificate, release workflow, source, and build instructions are available for inspection.

HeadBridge needs Bluetooth permission to open vendor control channels. It has no account, analytics, advertising SDK, or cloud sync. Update checks are the only routine network access; device control and battery history remain local. Security issues should be reported according to SECURITY.md.

Build from source

Requirements: macOS 14+ and Xcode 26 for the Control Center extension.

swift test
HEADBRIDGE_SKIP_REGISTRATION=1 ./Scripts/build-app.sh
open "dist/HeadBridge.app"

Omit HEADBRIDGE_SKIP_REGISTRATION=1 when you want the local build script to register the Control Center extension. Generated products live under .build/ and dist/.

The build script uses the exact HeadBridge self-signed identity when its private half is available in the maintainer's Keychain. Otherwise it deliberately falls back to an ad-hoc contributor build. It never selects an Apple Development, Distribution, or Developer ID identity.

Architecture and contributing

Every integration conforms to HeadphoneProvider: it matches Core Audio devices, owns its vendor transport, publishes runtime capabilities, and implements only the commands the connected device supports. Model-specific behavior belongs in capability profiles or protocol-generation adapters, not in provider names.

Common UI is provider-driven and unknown providers receive a generic settings screen. A provider with richer controls adds its provider-owned settings/menu view through a small registration step. See CONTRIBUTING.md and docs/PROVIDERS.md before opening a pull request.

Protocol contributions must be clean-room: document independently observed wire facts and captures, but do not copy vendor or third-party source code, assets, or decompiled implementation. Research credits are in THIRD_PARTY_NOTICES.md.

Updates and releases

Sparkle 2 is exact-pinned through Swift Package Manager. Tagged releases are built by GitHub Actions, published to GitHub Releases, and accompanied by a signed Sparkle appcast for automatic updates. The application uses the stable HeadBridge self-signed identity and remains unnotarized; the release workflow never imports or uses an Apple signing identity.

See docs/RELEASING.md and the release checklist for the maintainer flow.

License

HeadBridge is available under the MIT License. Third-party notices, including the Sparkle license shipped with binary distributions, are listed in THIRD_PARTY_NOTICES.md.