Control AirPlay speakers via Airfoil from the command line. Connect, disconnect, set volume, and manage multi-room audio with simple CLI commands.
---
name: airfoil
description: Control AirPlay speakers via Airfoil from the command line. Connect, disconnect, set volume, and manage multi-room audio with simple CLI commands.
metadata: {"clawdbot":{"emoji":"๐","os":["darwin"],"requires":{"bins":["osascript"]}}}
---
# ๐ Airfoil Skill
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ โ
โ ๐ต A I R F O I L S P E A K E R C O N T R O L ๐ต โ
โ โ
โ Stream audio to any AirPlay speaker โ
โ from your Mac via CLI โ
โ โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
> *"Why hop to your Mac when you can croak at it?"* ๐ธ
---
## ๐ What Does This Skill Do?
The **Airfoil Skill** gives you full control over your AirPlay speakers directly from the terminal โ or through Clawd! Connect speakers, control volume, check status โ all without touching the mouse.
**Features:**
- ๐ก **List** โ Show all available speakers
- ๐ **Connect** โ Connect to a speaker
- ๐ **Disconnect** โ Disconnect from a speaker
- ๐ **Volume** โ Control volume (0-100%)
- ๐ **Status** โ Show connected speakers with volume levels
---
## โ๏ธ Requirements
| What | Details |
|------|---------|
| **OS** | macOS (uses AppleScript) |
| **App** | [Airfoil](https://rogueamoeba.com/airfoil/mac/) by Rogue Amoeba |
| **Price** | $35 (free trial available) |
### Installation
1. **Install Airfoil:**
```bash
# Via Homebrew
brew install --cask airfoil
# Or download from rogueamoeba.com/airfoil/mac/
```
2. **Launch Airfoil** and grant Accessibility permissions (System Settings โ Privacy & Security โ Accessibility)
3. **Skill is ready!** ๐
---
## ๐ ๏ธ Commands
### `list` โ Show All Speakers
```bash
./airfoil.sh list
```
**Output:**
```
Computer, Andy's M5 Macbook, Sonos Move, Living Room TV
```
---
### `connect <speaker>` โ Connect to Speaker
```bash
./airfoil.sh connect "Sonos Move"
```
**Output:**
```
Connected: Sonos Move
```
> ๐ก Speaker name must match exactly (case-sensitive!)
---
### `disconnect <speaker>` โ Disconnect Speaker
```bash
./airfoil.sh disconnect "Sonos Move"
```
**Output:**
```
Disconnected: Sonos Move
```
---
### `volume <speaker> <0-100>` โ Set Volume
```bash
# Set to 40%
./airfoil.sh volume "Sonos Move" 40
# Set to maximum
./airfoil.sh volume "Living Room TV" 100
# Quiet mode for night time
./airfoil.sh volume "Sonos Move" 15
```
**Output:**
```
Volume Sonos Move: 40%
```
---
### `status` โ Show Connected Speakers
```bash
./airfoil.sh status
```
**Output:**
```
Sonos Move: 40%
Living Room TV: 65%
```
Or if nothing is connected:
```
No speakers connected
```
---
## ๐ฏ Example Workflows
### ๐ "Music in the Living Room"
```bash
./airfoil.sh connect "Sonos Move"
./airfoil.sh volume "Sonos Move" 50
# โ Now fire up Spotify/Apple Music and enjoy!
```
### ๐ฌ "Movie Night Setup"
```bash
./airfoil.sh connect "Living Room TV"
./airfoil.sh volume "Living Room TV" 70
./airfoil.sh disconnect "Sonos Move" # If still connected
```
### ๐ "All Off"
```bash
for speaker in "Sonos Move" "Living Room TV"; do
./airfoil.sh disconnect "$speaker" 2>/dev/null
done
echo "All speakers disconnected ๐"
```
---
## ๐ง Troubleshooting
### โ "Speaker Not Found"
**Problem:** `execution error: Airfoil got an error: Can't get speaker...`
**Solutions:**
1. Check exact spelling: `./airfoil.sh list`
2. Speaker name is **case-sensitive** ("sonos move" โ "Sonos Move")
3. Speaker must be on the same network
4. Speaker must be powered on and reachable
---
### โ "Airfoil Won't Start / No Permission"
**Problem:** AppleScript can't control Airfoil
**Solutions:**
1. **System Settings โ Privacy & Security โ Accessibility**
2. Add Terminal (or iTerm)
3. Add Airfoil
4. Restart macOS (sometimes necessary ๐)
---
### โ "Volume Doesn't Work"
**Problem:** Volume command has no effect
**Solutions:**
1. Speaker must be **connected** before volume can be set
2. First `connect`, then `volume`
3. Some speakers have hardware-side limits
---
### โ "Airfoil Not Installed"
**Problem:** `execution error: Application isn't running`
**Solution:**
```bash
# Start Airfoil
open -a Airfoil
# Or install it
brew install --cask airfoil
```
---
### โ "bc: command not found"
**Problem:** Volume calculation fails
**Solution:**
```bash
# Install bc (should be standard on macOS)
brew install bc
```
---
## ๐ Known Speakers
These speakers have been tested:
| Speaker | Type | Notes |
|---------|------|-------|
| `Computer` | Local | Always available |
| `Andy's M5 Macbook` | Mac | When on the network |
| `Sonos Move` | Sonos | Bluetooth or WiFi |
| `Living Room TV` | Apple TV | Via AirPlay |
> ๐ก Use `./airfoil.sh list` to discover your own speakers!
---
## ๐ Integration with Clawd
This skill works perfectly with Clawd! Examples:
```
"Hey Clawd, connect the Sonos Move"
โ ./airfoil.sh connect "Sonos Move"
"Turn the music down"
โ ./airfoil.sh volume "Sonos Move" 30
"Which speakers are on?"
โ ./airfoil.sh status
```
---
## ๐ Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-01-25 | Initial release |
| 1.1.0 | 2025-06-10 | Documentation polished ๐ธ |
| 1.2.0 | 2025-06-26 | Translated to English, ClawdHub-ready! |
---
## ๐ธ Credits
```
@..@
(----)
( >__< ) "This skill was crafted with love
^^ ^^ by a frog and his human!"
```
**Author:** Andy Steinberger (with help from his Clawdbot Owen the Frog ๐ธ)
**Powered by:** [Airfoil](https://rogueamoeba.com/airfoil/mac/) by Rogue Amoeba
**Part of:** [Clawdbot](https://clawdhub.com) Skills Collection
---
<div align="center">
**Made with ๐ for the Clawdbot Community**
*Ribbit!* ๐ธ
</div>
don't have the plugin yet? install it then click "run inline in claude" again.