home / skills / openclaw / skills / apple-music

apple-music skill

safe

This skill lets you search Apple Music, manage playlists, and control playback and AirPlay using MusicKit and AppleScript.

npx playbooks add skill openclaw/skills --skill apple-music

Review the files below or copy the command above to add this skill to your agents.

Files (7)

SKILL.md

1.7 KB

---
name: apple-music
description: Search Apple Music, add songs to library, manage playlists, control playback and AirPlay.
metadata: {"clawdbot":{"emoji":"🎵","os":["darwin"],"requires":{"bins":["node","curl"]}}}
---

# Apple Music

Control Apple Music via MusicKit API and AppleScript. Path: `~/.clawdbot/skills/apple-music/`

## 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:**
1. developer.apple.com → Keys → Create MusicKit key → Download .p8
2. Note your Key ID and Team ID

**Then run setup:**
```bash
./launch-setup.sh  # Opens Terminal for interactive setup
```

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.

### Errors

- 401: Token expired, re-run setup
- 403: Check Apple Music subscription
- 404: Invalid ID or region-locked

### Setup Issues

- **404 on auth page:** Setup script auto-fixes with HTTP server verification
- **No token in browser:** Restart setup.sh
- **Browser won't open:** Manually open printed URL (Chrome recommended)

Overview

This skill lets you search Apple Music, add songs to your library, manage playlists, and control playback and AirPlay from the command line or via the Apple Music API. It supports local AppleScript-based playback controls and an API mode that uses MusicKit for advanced actions like library and playlist management. The API mode requires an Apple Developer account and a MusicKit key for full functionality.

How this skill works

Local mode runs a shell script that sends AppleScript commands to the Music app for playback, song selection, and AirPlay device management. API mode uses MusicKit tokens generated from a .p8 key (Key ID and Team ID) to call Apple Music endpoints for search, library changes, and playlist operations. A setup launcher opens Terminal for interactive authorization and stores short-lived tokens in config.json.

When to use it

Quickly control playback or AirPlay on your Mac without opening the Music app.
Search Apple Music and add tracks to your library programmatically.
Create or update playlists using MusicKit-backed API calls.
Automate music tasks in scripts or local agents where interactive authentication is possible.
When you have an Apple Developer account and need authenticated access to the Apple Music catalog.

Best practices

Use ./apple-music.sh for local playback and AirPlay actions to avoid manual AppleScript calls.
Run ./launch-setup.sh in Terminal for API setup; the process requires interactive browser authorization.
Store your .p8, Key ID, and Team ID securely and regenerate tokens every 6 months as needed.
Handle 401/403/404 errors by re-running setup or checking subscription/region restrictions.
Prefer Chrome if the browser does not open automatically; paste the printed URL manually if required.

Example use cases

Add a specific song to your library during a playlist curation workflow using library add <song-id>.
Automate switching AirPlay speakers when starting a focus session with airplay select N.
Search for artist tracks and batch-add to a playlist via search and playlists add commands.
Control playback (play, pause, next, volume) from a custom hotkey script on your Mac.
Recover or re-authorize tokens after the 6-month expiry by running the interactive setup.

FAQ

Do I need an Apple Developer account?

Yes. API mode requires a paid Apple Developer account and a MusicKit .p8 key for authenticated actions.

What if I get a 401 or 403 error?

401 usually means the token expired—re-run setup. 403 can indicate missing Apple Music subscription or permission issues.