HeadsetControl-MacOSTray

HeadsetControl-MacOSTray

HeadsetControl-MacOSTray is a macOS background application that uses the headsetcontrol library to talk directly to supported headsets. It provides a convenient status bar menu to display headset battery, chatmix, and device information, and allows quick access to settings and refresh actions.

Visit the project homepage. See the GitHub Pages publishing notes to preview or deploy it.

Preconditions

1. macOS 14.0 (Sonoma) or later, on Apple Silicon or Intel
2. Homebrew only if you install the app with Homebrew Cask or want the optional standalone HeadsetControl CLI

Current release builds are self-contained: they statically embed the pinned HeadsetControl and HIDAPI versions recorded in build-contract.json. Neither library needs to be installed separately for the tray app to run.

Installation

1. Optional: Install the standalone HeadsetControl CLI if you also want to use it outside the tray app:

   brew tap sapd/headsetcontrol
   brew trust --formula sapd/headsetcontrol/headsetcontrol
   brew install sapd/headsetcontrol/headsetcontrol
   

2. Install HeadsetControl-MacOSTray via Homebrew:

   brew tap ChrisLauinger77/cask
   brew trust --cask chrislauinger77/cask/headsetcontrol-macostray
   brew install --cask chrislauinger77/cask/headsetcontrol-macostray
   

3. Follow the first-launch instructions below if macOS blocks the app.

The Cask installs only the self-contained tray app and does not install the standalone headsetcontrol command. Install the official HeadsetControl formula in step 1 only if you want to use that CLI separately. If you install the app directly from GitHub Releases, you can also skip step 1 entirely.

macOS Security Notice

The universal macOS build supports Apple Silicon and Intel. It is ad-hoc signed but cannot be notarized without a paid Apple Developer Program membership. The Homebrew Cask automatically clears the quarantine attribute after installation. If macOS still blocks the app, or if you installed it directly from GitHub Releases:

1. Control-click HeadsetControl-MacOSTray.app in Finder and choose Open.
2. Confirm Open in the security dialog.

If macOS still blocks the app, open System Settings → Privacy & Security, find the HeadsetControl-MacOSTray message, and choose Open Anyway. As a final option, clear extended attributes from a build you downloaded from this repository and trust:

xattr -cr "/Applications/HeadsetControl-MacOSTray.app"

Update

Update the app through Homebrew Cask:

brew upgrade --cask headsetcontrol-macostray

New headset support and native-library fixes reach users through a new app release built with updated pinned HeadsetControl or HIDAPI revisions. Updating the standalone HeadsetControl formula does not update the versions embedded in an already-built app. Current builds load no Homebrew HeadsetControl or HIDAPI library on either architecture. See the build contract for exact inputs and compatibility validation. The application bundle includes HIDAPI’s BSD-style redistribution notice.

Screenshots

Tray

Settings

Features

• Status bar integration for headset battery and chatmix
• Microphone mute and boom-mic attachment status where supported, with an optional mute indicator in the menu bar
• Settings panel for configuration
• Refresh button to manually update headset status
• Automatic periodic updates
• Direct integration with libheadsetcontrol through the headsetcontrol C API
• Test mode for checking menu and battery states without a connected headset

Dynamic Capability Menu

• The tray menu dynamically displays controls based on the capabilities reported by your headset. If a capability is available, a corresponding submenu or action is shown:

• Sidetone: Choose from the configured Off, Low, Medium, High and Maximum levels. Sets the sidetone level through the headsetcontrol library.

• Headset volume, Microphone Volume, Bluetooth Call Volume: Choose from the configured level presets.

• Noise cancelling: Choose Off, Noise cancelling or Ambient sound. The power-on mode and button modes are set in Settings.

• Microphone Noise Filter: Choose Off, Low or High.

• Mic Mute LED Brightness: Choose Off, Low, Medium or High.

• Volume Limiter, Bluetooth on at Power-On: Toggle on or off.

• Lights: Toggle headset lights on or off. On headsets that support light color, the same submenu also lists four configurable colors; choosing one turns the lights on in that color.

• Inactive Time: Choose the headset idle timeout from the configured options.

• Voice Prompts: Toggle headset voice prompts on or off.

• Rotate to Mute: Toggle rotate-to-mute on or off.

• Equalizer: Offers the device’s built-in presets and compatible saved graphic or parametric curves. Edit Equalizer… opens Settings. Preset fallback names apply only to supported indices without a device-reported name.

These menu items only appear if the headset reports the corresponding capability through libheadsetcontrol. Selecting an option immediately applies the setting through the library; V2.x no longer launches the headsetcontrol command line tool as a subprocess.

Support

If you like my work, please consider supporting me !

Build with Xcode

1. Clone this repository:

   git clone https://github.com/ChrisLauinger77/HeadsetControl-MacOSTray.git
   

2. For the same native dependency inputs as CI and release, install Xcode 27.2 (build 27B52) or newer and CMake, then run the shared build helper. It fetches the revisions pinned in build-contract.json, builds static HeadsetControl and HIDAPI archives for the macOS 14.0 floor, runs Debug and Release tests, and creates a validated app archive. This path does not use Homebrew-provided HeadsetControl or HIDAPI headers and libraries.
3. The project uses Xcode’s JSON project.xcproj format and requires Xcode 27 or later to open; Xcode 27.2 supports converting and writing this format. For quick local development, opening the project directly in Xcode still intentionally supports HeadsetControl and HIDAPI headers/libraries installed through Homebrew. Install the official HeadsetControl formula when using this path. These direct builds are not release artifacts and do not establish the pinned dependency contract. SwiftPM source compilation requires Swift 6.1 or later. CI and release enforce the Xcode minimum separately.

Usage

• The app runs in the background and places an icon in the macOS status bar.
• Click the icon to view headset data.
• Access settings via the dialog to configure the update interval, language, menu bar mute indicator, sidetone and volume levels, light colors, noise-cancelling power-on and button modes, inactive-time options, equalizer preset names, low-battery notifications, and test mode.
• In Equalizer settings, select a headset and edit a graphic curve or parametric bands where supported. Save Curve stores it locally; Apply explicitly sends the complete curve and saves it after success. Editing, copying a preset, resetting, startup, and reconnecting never apply a curve automatically.
• Curves are shared by USB model (vendor/product ID), with separate graphic and parametric configurations. Applying requires a current, uniquely addressable connection. A changed band layout requires review or a reset. The editor shows saved or new values, not device readback; graphic band frequencies are unavailable. Devices that cannot yet report EQ metadata retain their preset controls.
• Use the Refresh button in the settings panel to manually update headset status.

Troubleshooting

• No headset data appears: Check that your headset is supported by the headsetcontrol version embedded in this app release. Updating the app may be necessary.
• The pinned build helper fails while preparing native dependencies: Use the exact Xcode and CMake prerequisites above and follow the diagnostics from the helper. Installing a Homebrew library is not a substitute for its pinned input.
• A direct local Xcode build fails with headsetcontrol_c.h not found: Install the official HeadsetControl formula and make sure its headers are available in /opt/homebrew/include or /usr/local/include. This applies only to the direct development path, not to released app bundles or the pinned build helper.

License

See LICENSE for details.

Credits

• Sapd for HeadsetControl