- name
- macos-audio
- description
- >
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 controlInstall the CLI
brew install vossenwout/tap/macos-audio-cliCommands
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 outputVolume
macos-audio volume set <0-100> # set system output volume
macos-audio volume get # print output volume, input volume, mute statePlayback
macos-audio play <file> # play a local audio file
macos-audio play <file> --background # start playback and return immediatelyStatus
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 deviceExit 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 statusfirst 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 airplayuses the genericAirPlayroute; room names in scan are informational.- Bluetooth devices only appear in scan after manual pairing in macOS.
Limitations
- Doesn't work over ssh
connect airplayis known to be buggy and airplay functionality is still experimental