macos-audio

Manage macOS audio output and Bluetooth devices via the macos-audio CLI. Use when scanning paired devices, connecting or disconnecting Bluetooth, switching audio output (including AirPlay), getting or setting volume, playing audio files, or checking audio status.

Control Bluetooth devices, audio output routing, and volume on macOS through the macos-audio CLI.

Installation

Brew dependencies

bash

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

Install the CLI

bash

brew install vossenwout/tap/macos-audio-cli

Commands

Scan & connect

bash

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

bash

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

Playback

bash

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

Status

bash

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

Code	Meaning
0	Success
1	Runtime error
2	Bad arguments
3	Target resolution error
4	Missing tool dependency (blueutil or SwitchAudioSource not installed)

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