| name | apple-music |
| description | Search Apple Music, add songs to library, manage playlists, control playback and AirPlay. |
| author | G-HunterAi |
| license | MIT |
| version | 1.0.0 |
| tags | ["music","macos","apple","playback"] |
| platforms | ["macos"] |
| category | integration |
| emoji | 🎵 |
| metadata | {"clawdbot":{"emoji":"🎵","os":["darwin"],"requires":{"bins":["node","curl"]}}} |
Apple Music
Control Apple Music via MusicKit API and AppleScript. Path: ~/.clawdbot/skills/apple-music/
When to Use
- Controlling playback without interrupting current app
- Searching for and adding songs to your library
- Managing playlists
- Viewing current playback status
- Controlling AirPlay devices
When NOT to Use
- Accessing Apple Music without active subscription
- Operating on token that has expired (requires re-setup)
- Region-locked content outside supported areas
Local (No Setup)
Playback: ./apple-music.sh player [now|play|pause|toggle|next|prev|shuffle|repeat|volume N|song "name"]
AirPlay: ./apple-music.sh airplay [list|select N|add N|remove N]
API (Setup Required)
Requires Apple Developer account ($99/yr) + MusicKit key.
Setup
Portal steps first:
- developer.apple.com → Keys → Create MusicKit key → Download .p8
- Note your Key ID and Team ID
Then run setup:
./launch-setup.sh
The launcher opens Terminal.app and runs the setup script there. Enter your .p8 path, Key ID, Team ID, then authorize in browser and paste the token.
⚠️ Agents: Always use ./launch-setup.sh to open Terminal. Don't run setup.sh through chat (requires interactive input).
Commands
search "query" [--type songs|albums|artists] [--limit N]library add <song-id>playlists [list|create "Name"|add <playlist-id> <song-id>]
Config
config.json stores tokens (valid ~6 months). Re-run ./setup.sh if auth fails.
Error Handling
| Error | Cause | Solution |
|---|
401 Unauthorized | Token expired or invalid | Re-run ./launch-setup.sh to refresh token |
403 Forbidden | Missing Apple Music subscription or regional restriction | Verify subscription is active in Settings; check region availability |
404 Not Found | Song/playlist/ID doesn't exist or is unavailable | Verify ID is correct; check if content is available in your region |
HTTP server verification failed | Setup page won't load | Restart setup.sh; try different browser (Chrome recommended) |
Works Well With
- spotify — Switch between Apple Music and Spotify playback
- music-generation — Generate music and add to Apple Music library
- elevenlabs-music — Create audio and queue for playback
Notes
- Read-only playback works without setup (uses AppleScript)
- API-based search and library management requires MusicKit key
- Tokens auto-refresh, but re-setup is needed after ~6 months
- Token stored in
config.json (keep secure)
