← Back to Skills Marketplace
macos-audio
by
Wout Vossen
· GitHub ↗
· v1.0.0
· MIT-0
358
Downloads
0
Stars
1
Active Installs
1
Versions
Install in OpenClaw
/install macos-audio
Description
Manage macOS audio output and Bluetooth devices via the macos-audio CLI. Use when scanning paired devices, connecting or disconnecting Bluetooth, switching a...
README (SKILL.md)
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 \x3Cname|mac>
macos-audio connect airplay
macos-audio connect local \x3Cname>
macos-audio disconnect \x3Ctarget> # disconnect bluetooth and switch to local output
Volume
macos-audio volume set \x3C0-100> # set system output volume
macos-audio volume get # print output volume, input volume, mute state
Playback
macos-audio play \x3Cfile> # play a local audio file
macos-audio play \x3Cfile> --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 \x3Cname|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 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
Usage Guidance
This skill appears to do what it says (control macOS audio), but be cautious before installing: 1) Ensure you only use it on a macOS machine with Homebrew available — the metadata doesn't declare the OS requirement but the instructions assume macOS. 2) Inspect and verify the Homebrew tap (vossenwout/tap) and its formula source before running brew install — third‑party taps can install arbitrary code. 3) Prefer installing from a known official project page or GitHub repo; ask the publisher for a homepage or source link if you need to validate the software. 4) Because the agent can invoke the CLI, consider whether you want it to run system-level commands autonomously in your environment. If you are unsure about the tap's origin, do not install it on sensitive systems.
Capability Analysis
Type: OpenClaw Skill
Name: macos-audio
Version: 1.0.0
The skill bundle provides instructions for managing macOS audio and Bluetooth devices using a CLI tool. It relies on legitimate third-party utilities (blueutil, switchaudio-osx) and a specific Homebrew tap (vossenwout/tap/macos-audio-cli). The commands and workflow described in SKILL.md are consistent with the stated purpose and show no signs of malicious intent, data exfiltration, or prompt injection.
Capability Assessment
Purpose & Capability
The SKILL.md describes a macOS-only CLI for switching audio and Bluetooth devices which is coherent with the name and description. However the skill metadata does not declare an OS restriction or required binaries even though the instructions require Homebrew and macOS-specific tools (switchaudio-osx, blueutil and a brew formula). This mismatch (metadata says 'none' but instructions require macOS and Homebrew) is unexpected.
Instruction Scope
The instructions stay within the stated scope: they tell the agent how to install the CLI via brew and how to run the CLI commands to scan/connect/adjust volume and play files. They do not instruct the agent to read unrelated files or exfiltrate data. They do assume interactive/local capability (notes that it doesn't work over ssh).
Install Mechanism
Although this is an instruction-only skill (no code included), the SKILL.md instructs installing Homebrew packages and a third‑party tap (brew install vossenwout/tap/macos-audio-cli). Installing from an external/third‑party tap is higher risk than using only well-known official packages; the brew formula will download and install code onto the machine. The skill does not provide a homepage or source URL to verify the tap/formula contents.
Credentials
The skill requests no environment variables or credentials, which is proportionate for the stated functionality (local audio control).
Persistence & Privilege
The skill is not marked always:true and does not request special persistent privileges. It allows autonomous invocation (default), which is normal for skills; this combined with the install instructions means an agent could run these system commands autonomously if invoked.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install macos-audio - After installation, invoke the skill by name or use
/macos-audio - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
- Initial release of the macos-audio skill.
- Provides CLI management for macOS audio output and Bluetooth devices.
- Supports scanning devices, connecting/disconnecting Bluetooth and AirPlay, switching audio outputs, adjusting volume, and playing audio files.
- Includes commands for status checks (including JSON output) and precise exit codes for troubleshooting.
- Requires installation of brew dependencies: switchaudio-osx and blueutil.
- Documents known limitations, such as lack of SSH support and experimental AirPlay features.
Metadata
Frequently Asked Questions
What is macos-audio?
Manage macOS audio output and Bluetooth devices via the macos-audio CLI. Use when scanning paired devices, connecting or disconnecting Bluetooth, switching a... It is an AI Agent Skill for Claude Code / OpenClaw, with 358 downloads so far.
How do I install macos-audio?
Run "/install macos-audio" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is macos-audio free?
Yes, macos-audio is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does macos-audio support?
macos-audio is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created macos-audio?
It is built and maintained by Wout Vossen (@vossenwout); the current version is v1.0.0.
More Skills