macos-audio

Control Bluetooth devices, audio output routing, and volume on macOS through

the macos-audio CLI.

Installation

Brew dependencies

brew install switchaudio-osx   # required for output switching
brew install blueutil           # required for Bluetooth control

Install the CLI

brew install vossenwout/tap/macos-audio-cli

Commands

Scan & connect

macos-audio scan                # clean sections: Bluetooth, Local, AirPlay
macos-audio connect bt <name|mac>
macos-audio connect airplay
macos-audio connect local <name>
macos-audio disconnect <target> # disconnect bluetooth and switch to local output

Volume

macos-audio volume set <0-100>  # set system output volume
macos-audio volume get          # print output volume, input volume, mute state

Playback

macos-audio play <file>                    # play a local audio file
macos-audio play <file> --background       # start playback and return immediately

Status

macos-audio status                         # show output, volume, mute state
macos-audio status --json                  # same but machine-readable JSON
macos-audio status --device <name|mac>     # include bluetooth status for a specific device

Exit codes

Workflow guidance

• Always run macos-audio status first to understand the current state before making changes.
• If a command exits with code 4, the required brew dependency is missing — install it and retry.
• connect airplay uses the generic AirPlay route; room names in scan are informational.
• Bluetooth devices only appear in scan after manual pairing in macOS.

Limitations

• Doesn't work over ssh
• connect airplay is known to be buggy and airplay functionality is still experimental