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.
- macOS 14.0 (Sonoma) or later, on Apple Silicon or Intel
- 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.
- 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
- Install HeadsetControl-MacOSTray via Homebrew:
brew tap ChrisLauinger77/cask brew trust --cask chrislauinger77/cask/headsetcontrol-macostray brew install --cask chrislauinger77/cask/headsetcontrol-macostray
- Follow the first-launch instructions below if macOS blocks the app.
The current Cask also installs the official HeadsetControl formula. That formula
provides the standalone headsetcontrol command and its own dependencies; the
tray app does not load them at runtime. No separate formula installation is
required for the app. If you install the app directly from
GitHub Releases,
you can skip step 1 entirely.
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. On first launch:
- Control-click
HeadsetControl-MacOSTray.appin Finder and choose Open. - 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, remove the quarantine attribute from a build you downloaded from this repository and trust:
xattr -dr com.apple.quarantine "/Applications/HeadsetControl-MacOSTray.app"Update the app through Homebrew Cask:
brew upgrade --cask headsetcontrol-macostrayNew 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.
Tray
Settings
- Status bar integration for headset battery and chatmix
- 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
-
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 Off, Low, Mid, High, Max. Sets the sidetone level through the headsetcontrol library.
-
Lights: Toggle headset lights on or off.
-
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 Preset: If available, shows preset names from the device; otherwise, shows the configured generic presets.
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.
If you like my work, please consider supporting me !
- Clone this repository:
git clone https://github.com/ChrisLauinger77/HeadsetControl-MacOSTray.git
- For the same native inputs as CI and release, install Xcode 26.3 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. - 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; the release toolchain is fixed separately.
- 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 update interval, sidetone levels, inactive-time options, equalizer preset names, low-battery notifications, and test mode.
- Use the Refresh button in the settings panel to manually update headset status.
- 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/includeor/usr/local/include. This applies only to the direct development path, not to released app bundles or the pinned build helper.
See LICENSE for details.
- Sapd for HeadsetControl