airfoil

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 by Rogue Amoeba
Price	$35 (free trial available)

Installation

1. Install Airfoil:

   # 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

./airfoil.sh list

Output:

Computer, Andy's M5 Macbook, Sonos Move, Living Room TV

---

connect <speaker> — Connect to Speaker

./airfoil.sh connect "Sonos Move"

Output:

Connected: Sonos Move

💡 Speaker name must match exactly (case-sensitive!)

---

disconnect <speaker> — Disconnect Speaker

./airfoil.sh disconnect "Sonos Move"

Output:

Disconnected: Sonos Move

---

volume <speaker> <0-100> — Set Volume

# 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

./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"

./airfoil.sh connect "Sonos Move"
./airfoil.sh volume "Sonos Move" 50
# → Now fire up Spotify/Apple Music and enjoy!

🎬 "Movie Night Setup"

./airfoil.sh connect "Living Room TV"
./airfoil.sh volume "Living Room TV" 70
./airfoil.sh disconnect "Sonos Move"  # If still connected

🌙 "All Off"

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:

# Start Airfoil
open -a Airfoil

# Or install it
brew install --cask airfoil

---

❌ "bc: command not found"

Problem: Volume calculation fails

Solution:

# 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 by Rogue Amoeba
Part of: Clawdbot Skills Collection

---

Made with 💚 for the Clawdbot Community

Ribbit! 🐸