# Music > Apple Music in your terminal. Play tracks, route to AirPlay speakers and AirPods, search 100 million songs, build playlists, play radio stations, discover new music, favorite tracks, seek within a song, browse your listening history, browse your library by artist, album, or track. This is the plugin's only entry point — there are no separate slash commands, so EVERY music request comes here: tran… - **Type:** Skill - **Install:** `agentstack add skill-anthonymaley-apple-music-music` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [anthonymaley](https://agentstack.voostack.com/s/anthonymaley) - **Installs:** 0 - **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [anthonymaley](https://github.com/anthonymaley) - **Source:** https://github.com/anthonymaley/MusicTUI/tree/main/skills/music - **Website:** https://musictui.com/ ## Install ```sh agentstack add skill-anthonymaley-apple-music-music ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Apple Music Controller Control Apple Music from the terminal via the `music` CLI. All commands run as bash — use `music` for structured operations, with `--json` for machine-readable output. ## If the CLI is not installed If `command -v music` fails, do NOT improvise AppleScript fallbacks. Tell the user the CLI needs a one-time build and point them at the install script, then retry after they run it: ```bash bash "${CLAUDE_PLUGIN_ROOT}/scripts/install.sh" # from the plugin # or, in the repo: scripts/install.sh ``` ## Fast path: play requests For any request shaped like "play X [on/in speakers] [at volume%] [shuffle]", forward the user's words to `music play` in ONE bash call — strip only the leading "play" and any % sign. The CLI's parser deterministically extracts speaker names (including several at once), volume, filler words ("in", "the", "and", "at", "on"), and a trailing "shuffle": ```bash music play kid a in the kitchen and living room at 60 music play jazz for cooking kitchen 40 shuffle ``` Naming speakers routes playback to exactly those speakers (it deselects the rest). Don't pre-chain `music speaker` + `music volume` for simple play requests — `music play` does all three. If the query itself contains a speaker-like word, use the explicit flags (`--song`, `--album`, `--playlist`) instead. Named-speaker plays are verified automatically once playback starts (`✓ verified (…)`); an unestablished route triggers an automatic heal before an honest failure message. ## Architecture The music CLI has two backends: - **AppleScript** — playback, speakers, volume, now playing (no auth needed) - **REST API** — catalog search, library writes, playlists via API, discovery (needs auth) ## Playback (no auth) ```bash music play # resume (shows now playing + speakers) music play "Working Vibes" # play a playlist by name music play "Working Vibes" shuffle # play with shuffle music play 3 # play result #3 from last search music play "Working Vibes" kitchen 20 # play on Kitchen speaker (only) at vol 20 music play "Working Vibes" kitchen 20 shuffle # routed + shuffled music play kid a in the kitchen and living room at 60 # multi-room: filler words OK, group volume music play deck and pool # resume on Deck + Pool (exactly those) music play "Gypsy Woman" "Tom Misch" # song + artist; catalog fallback if authenticated music play "https://music.apple.com/...?...i=1581424482" # catalog song URL; quote it in zsh music play --playlist "Working Vibes" # explicit playlist flag music play "Gypsy Woman (Quarantine Sessions)" # play matching local Library album/song music play --album "Kid A" --artist "Radiohead" # explicit local Library album + artist music play --song "Get It Done" --artist "Fouk" # search library + play music play --verbose # diagnostic output on stderr music pause music skip # next track music back # previous track music stop music now # what's playing + speakers music now --json # structured: track, artist, album, speakers, state music seek +30|-30|90|1:30 # seek within the current track music shuffle # toggle (or: music shuffle on|off) music repeat off|one|all music love # favorite the current track music unlove # unfavorite ``` ## Speakers (no auth) ```bash music speaker list # all AirPlay devices + status (writes to cache) music speaker list --json # structured device list music speaker kitchen # add kitchen (prefix match) music speaker kitchen 40 # add kitchen at volume 40 music speaker kitchen stop # remove kitchen from group music speaker airpods only # deselect all, select airpods only music speaker 1 2 5 # add speakers by index from last list music speaker wake # verify all active speakers, reset only the broken ones music speaker wake kitchen # verify + wake a specific speaker music speaker verify # network-truth verdict for all selected speakers music speaker verify kitchen # verify one speaker (--json for structured output) music speaker set "Kitchen" # hidden alias (skill compat) music speaker add "Bedroom" # hidden alias music speaker remove "Bedroom" # hidden alias ``` `music speaker ` (add), `set`, and `only` verify the route automatically while playing — output gains a `✓ verified (…)` line, and an unverified route triggers an automatic heal (away-and-back reroute, then a transport-cycle reset) before falling back to an honest failure naming the manual fix. While paused, routing can't be network-verified — it prints `Route set; will verify on next play.` and re-checks when playback starts. Scripting's own claims (`selected`, `active`) are shown as advisory only, not trusted, because they can lie. Routing to the Mac's own output is never "verified" — local output has no AirPlay session. ## Volume (no auth) ```bash music volume # show current volume per speaker music volume 60 # set all active speakers to 60 music volume up # +10 on all active speakers music volume down # -10 on all active speakers music volume kitchen 80 # set Kitchen to 80 (name resolved) ``` ## Equalizer (no auth) Real Music.app EQ control. Venue presets are created on first selection and persist as real presets (visible in Music's own EQ window). Live EQ control drives the Equalizer window via UI scripting (Music's scripting API for live EQ state is broken): it needs Accessibility permission for the terminal and opens the Equalizer window. On a permission error, relay the command's hint — it names the exact System Settings toggle. | Request | Command | |---|---| | "make it sound like a dungeon" / "nightclub mode" | `music eq dungeon` / `music eq nightclub` | | "more bass" | `music eq "Bass Booster"` | | "flat" / "turn off the EQ" | `music eq flat` / `music eq off` | | "what's the EQ?" | `music eq` | | "remove the venue presets" | `music eq remove-pack` | Venue pack: Nightclub, Dungeon, Open Air, Concert Hall, Jazz Club, Stadium, Cathedral, Late Night. Any other name forwards verbatim — Music's built-in presets (Acoustic, Hip-Hop, Loudness, …) all resolve. Unknown names print near-matches. ## Visualizer (no auth) `music visualizer [on|off]` toggles Music's on-screen visualizer (the Cmd-T visuals). Same UI-scripting + Accessibility requirement as the equalizer. GUI-only: the visuals render in the Music window on the Mac's display (not on AirPlay outputs), and turning it on brings Music to the front. ## Radio (favorites/URL: no auth · search: developer token) ```bash music radio list # your favorite stations music radio play "bbc radio 1" # play a favorite by name (fuzzy match) music radio play "https://music.apple.com/us/station/apple-music-1/ra.978194965" # play a URL directly music radio add "https://music.apple.com/us/station/apple-music-1/ra.978194965" # favorite a station by URL music radio search "deep house" # search catalog stations ``` `music radio play ` is the entry point for casual requests — "put on BBC Radio 1", "play Apple Music 1", "put on some radio". It checks favorites first (no network), then treats the argument as a URL if it looks like one, then falls back to catalog search — which needs a developer token. A station plays via its share URL with the scheme swapped from `https://` to `music://`; no AppleScript, no MusicKit, and the current AirPlay route survives. **Apple's station search is shallow and unreliable** — roughly 5-7 results, no pagination, and it misses real stations outright. It can't find BBC Radio 1 at all, not even by its own catalog id, though the station plays fine once you have its URL. When `music radio search` or `music radio play ` comes back empty, do NOT tell the user the station doesn't exist — ask them for the station's share URL from music.apple.com (or the Music app's share menu) and play or favorite that instead: ```bash music radio play "https://music.apple.com/us/station//" music radio add "https://music.apple.com/us/station//" ``` Favorites are stored locally at `~/.config/music/stations.json` and don't sync to other devices. ## Search (catalog: developer token · library: + user token) ```bash music search "Bohemian Rhapsody Queen" # search songs (writes to cache) music search "Fouk" --limit 20 # control result count music search "house" --types songs,albums,artists,playlists # multi-type catalog search music search "The Smiths" --library # search YOUR library (needs user token) music search "kid a" --library --types playlists # library, specific types music search --artist "Radiohead" # narrow the query text by artist music search --album "OK Computer" # narrow the query text by album music search "query" --json # structured results with catalog IDs ``` `--types` accepts any of `songs,albums,artists,playlists` (default `songs`). Only songs are numbered/cached for index-based `add`/quick-pick; albums, artists, and playlists print with their catalog/library ids. ## Add to Library (requires user token) ```bash music add "Get It Done" "Fouk" # search + add top result music add 3 # add result #3 from last search music add --id 1844648631 # add by catalog ID music add --to "House" # add current song to playlist music add --to "House" --to "Chill" # add current song to multiple playlists music add 3 --to "House" # add result #3 to playlist ``` ## Remove from Playlist (requires user token) ```bash music remove # remove current song from current playlist music remove "House" # remove current song from "House" music remove all # remove current song from all playlists ``` ## Playlists (requires user token for API, AppleScript fallback for local) ```bash music playlist list # list all playlists music playlist tracks "Working Vibes" # list tracks in playlist music playlist create "New Playlist" # create empty playlist music playlist create "New Playlist" 1 3 5 # create from result indices music playlist add "House" 1 3 5 # add result indices to existing playlist music playlist add "Working Vibes" "Song" "Artist" # add track by name music playlist delete "Old Playlist" # delete (via AppleScript) music playlist remove "Playlist" "Song" # remove track music playlist share "Playlist" --imessage "+1234567890" # share via iMessage music playlist share "Playlist" --email "a@b.com" # share via email music playlist temp "Song1" "Artist1" "Song2" "Artist2" # temp playlist, play, cleanup later music playlist create-from "Song1" "Artist1" "Song2" "Artist2" --name "My Mix" # create + populate music playlist cleanup # delete all __temp__ playlists ``` ## Discovery (requires user token) ```bash music similar # similar to now playing music similar Hotel California # similar to a specific track (--artist to narrow) music recent # recently played tracks (cached for `play N`) music rotation # your heavy-rotation music music suggest # suggest tracks from now playing music suggest 10 --from "Working Vibes" # suggest from playlist vibe music new-releases --like-current # new releases from current artist music new-releases --artist "Fouk" # new releases from specific artist music mix --artists "Fouk,Floating Points" --count 20 --name "Friday Mix" # mixed playlist ``` ## Interactive TUI (requires real terminal, not Claude Code) ```bash music # unified shell: Now / Library / Playlists / Radio / Speakers tabs ``` Bare `music` is the main interactive surface — a tabbed shell with **Now**, **Playlists**, **Speakers**, **Library**, and **Radio** tabs. (`music now` / `music now --json` and `music playlist ` are non-interactive CLI commands, documented above.) Four one-shot quick pickers also exist for terminal/slash-command use: bare `music speaker` (AirPlay picker), bare `music volume` (mixer), and the `music similar` / `music suggest` result pickers. TUI behavior: the Now tab shows the current album context; selecting a playlist on the Playlists tab pins it on the Now tab. Cursor movement is local and fast. On the Speakers tab, toggling a speaker on while playing verifies the route and toasts if it couldn't be verified. The Library tab (needs the Apple Music user token) browses your library in three sub-views — Artists, Albums, Songs (opens on Artists) — switched with `[`/`]`; Enter opens an album's tracks (or drills Artist → their albums → tracks), `p` plays and `s` shuffles the item in focus. On the Artists list, `a` cycles a track-count filter — All → 12″/EP (artists with a 2–5 track release) → Albums (artists with a 6+ track album) — separating 12″s/EPs from full-album deep cuts; the raw list otherwise includes every artist with any library track (even one pulled in by a single playlist song). Library and Playlists heroes show real cover art (fetched once, disk-cached; gradient placeholder while loading or signed out). The Radio tab browses **Favorites · Live · Personal** stations, switched with `[`/`]` (Favorites needs no token; Live and Personal need a developer token). `Enter`/`→` plays, `f` favorites/unfavorites, `/` opens a catalog search (hits land in the list, `Esc` clears back to the sub-view), `a` opens an add-by-URL field — paste a station URL to favorite it directly; anything that isn't a URL redirects to `/` instead of being guessed at. Only `↑↓`/`j`/`k` and `Enter`/`→`/`l` are wired — no page/home/end jumps. TUI controls: `1/2/3/4/5` switch tabs (Now / Library / Playlists / Radio / Speakers), `Tab`/`Shift-Tab` cycle tabs, `[`/`]` switch Library sub-view or Radio Favorites/Live/Personal, `↑↓` navigate (`PgUp/PgDn/Home/End` for long lists, Now/Playlists/Speakers/Library only), `Enter` play/open selected, `←→` seek (Now) or volume (Speakers), `Space` pause, `` previous/next track (full up/down through the playlist), `z`/`r` shuffle, `l` favorite (Now), `f` favorite (Radio), `+/-` volume, `n` next-up options (Now), `/` filter playlists (arrows navigate while typing) or search the Radio catalog (Enter runs the search), `Esc` back, `q` quit. Playlist track-play requires Music's Autoplay (∞) turned OFF — it drives playback track-by-track and needs each track to stop at its end. ## Result Cache Search, similar, suggest, new-releases, and playlist tracks write results to `~/.config/music/last-songs.json`. Speaker list writes to `last-speakers.json`. Follow-up commands reference results by index: ```bash music search "house" # results cached as 1, 2, 3... music play 3 # play result #3 music add 3 # add #3 to library music add 3 --to "House" # add #3 to playlist music playlist create "House" 1 3 5 # create playlist from results ``` ## Auth Management ```bash music auth statu … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [anthonymaley](https://github.com/anthonymaley) - **Source:** [anthonymaley/MusicTUI](https://github.com/anthonymaley/MusicTUI) - **License:** MIT - **Homepage:** https://musictui.com/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-anthonymaley-apple-music-music - Seller: https://agentstack.voostack.com/s/anthonymaley - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.