/apple-music

name: apple-music
description: Control Apple Music playback, inspect now playing, start playlists, and automate the macOS Music app.
user-invocable: true
requires:
  os:
    - darwin
metadata:
  hybridclaw:
    category: apple
    short_description: "Apple Music playback."
    tags:
      - apple
      - music
      - media
      - macos

Apple Music

Use this skill for the macOS Music app and Apple Music playback workflows.

Scope

• play, pause, skip, or resume playback
• inspect what is currently playing
• open the Music app or a music URL
• trigger simple host-side playback actions on the Mac

Default Strategy

1. Confirm whether the user wants local Mac playback control or just information about Apple Music content. 2. Distinguish generic transport requests from content-specific requests. 3. For content-specific requests such as an artist radio, station, playlist, album, or song, resolve a directly playable target first and hand that target to the Music app itself. 4. For generic playback control on macOS, prefer small `osascript` actions against the Music app. 5. Do not modify playlists or library state unless the user asks. 6. If the user already asked you to play, pause, skip, or open something in Music, do not ask for a separate "yes" just to be safe. Attempt the host-side action and rely on the runtime approval flow if the command needs approval. 7. When you already have an exact Apple Music URL for playback, prefer the bundled `play-url.sh` helper instead of inventing a new `open` or UI-automation sequence. 8. If you need to resolve a content target from a plain-language query first, use the bundled `search.sh` helper. Do not invent additional helper names.

Core Commands

Open the app:

open -a Music

Playback controls:

osascript -e 'tell application "Music" to playpause'
osascript -e 'tell application "Music" to pause'
osascript -e 'tell application "Music" to next track'
osascript -e 'tell application "Music" to previous track'

Now playing:

osascript -e 'tell application "Music" to get player state'
osascript -e 'tell application "Music" to if player state is playing then get {name of current track, artist of current track, album of current track}'

Use these only for generic transport actions like "play", "pause", "resume", "next", or "what is playing". Do not use them to satisfy a request for specific content such as "Play Phil Collins Radio".

URL Workflow

Open Music directly only for app launch or page-view requests:

open -a Music
open "music://"

Use this when the user asked to open Music or show a page. Do not use plain shell `open "https://music.apple.com/..."` for a playback request, because that opens the default browser instead of issuing an in-app playback command.

Targeted Content Workflow

For content-specific requests like "Play Phil Collins Radio on Apple Music":

1. Resolve the exact Apple Music target first. 2. For artist-only requests like "Play Phil Collins", prefer an artist radio or other directly playable station/song/album/playlist URL. Do not use the artist profile page itself as the playback target. 3. If the user already provided an Apple Music URL, hand that URL to Music with AppleScript `open location`. 4. Otherwise, find the best matching Apple Music station, album, playlist, or track URL. 5. For playback, hand the resolved URL to Music with AppleScript `open location`, then trigger playback in Music. 6. Verify playback state before claiming success. 7. Only fall back to generic `play` or `playpause` if the user asked for generic playback and there is no content target to resolve.

Shipped helpers in this skill:

• `skills/apple-music/scripts/play-url.sh`
• `skills/apple-music/scripts/search.sh`

No other helper filenames are shipped here. Do not guess names like `lookup.sh`, `radio.sh`, or any other sibling script that you have not actually read or listed.

Preferred playback helper:

bash skills/apple-music/scripts/play-url.sh "https://music.apple.com/us/station/bruce-springsteen/ra.1691955673"

The helper launches Music first when the app is not already running, opens the resolved URL inside Music, nudges playback once, and prints verification fields. For `music.apple.com` links it rewrites the handoff to a native `music://...` deep link before asking Music to open it. Treat exit code `0` as success. If it exits nonzero or prints `ok=false`, playback did not start cleanly and you should not claim that music is playing. The helper rejects Apple Music browse pages such as `/artist/...` or `/search...` because those are not direct playback targets.

Preferred query-resolution helper when you do not already have a directly playable URL:

bash skills/apple-music/scripts/search.sh "Phil Collins"

The search helper resolves a best-effort playable Apple Music target from the query and, by default, immediately hands that URL to `play-url.sh` so playback starts within the same approved action. Use `--resolve-only` only when you need the resolved URL without playback:

bash skills/apple-music/scripts/search.sh --resolve-only "Phil Collins Radio"

Use read-only verification after a station or stream handoff when helpful:

osascript <<'APPLESCRIPT'
tell application "Music"
  get {player state, current stream title, current stream URL}
end tell
APPLESCRIPT

Working Rules

• Confirm before starting playback if the user may already be in a call or

focused work session.

• Do not add a second confirmation step when the user already explicitly asked

for playback control; let the runtime approval prompt handle host-side approval if needed.

• For `play ...` requests, success means Music started playback, not merely that

a page, search results, or the app window opened.

• For exact URL playback, prefer `bash skills/apple-music/scripts/play-url.sh

"<resolved-url>"` over hand