rbouschery Spotify Mac Skill
This skill provides commands to control Spotify on macOS via AppleScript.
Available Scripts
All scripts are in the ./scripts/ directory (relative to this file). Execute them via bash from the plugin root.
Playback Control
| Script | Purpose | Arguments |
|---|---|---|
play.sh |
Resume playback | none |
pause.sh |
Pause playback | none |
toggle-playback.sh |
Toggle play/pause | none |
next-track.sh |
Skip to next track | none |
previous-track.sh |
Go to previous track | none |
play-uri.sh |
Play specific URI | <spotify_uri> [context_uri] |
Search
| Script | Purpose | Arguments |
|---|---|---|
search.sh |
Open Spotify search visually | <query> |
Agent-Assisted Search (Recommended): To search and play automatically, use web search to find Spotify URLs:
- Search:
site:open.spotify.com [query](e.g., "site:open.spotify.com bohemian rhapsody") - Get the URL from results (e.g.,
https://open.spotify.com/track/6l8GvAyoUZwWDgF1e4822w) - Play it:
play-uri.sh "https://open.spotify.com/track/..."
This works for tracks, albums, playlists, and artists.
Track Information
| Script | Purpose | Arguments |
|---|---|---|
get-current-track.sh |
Get current track info | none |
get-player-state.sh |
Get player state | none |
Volume Control
| Script | Purpose | Arguments |
|---|---|---|
get-volume.sh |
Get current volume | none |
set-volume.sh |
Set volume level | <volume 0-100> |
volume-up.sh |
Increase volume by 10 | none |
volume-down.sh |
Decrease volume by 10 | none |
Position Control
| Script | Purpose | Arguments |
|---|---|---|
get-position.sh |
Get current position | none |
set-position.sh |
Seek to position | <seconds> |
fast-forward.sh |
Forward 10 seconds | none |
rewind.sh |
Rewind 10 seconds | none |
Mode Control
| Script | Purpose | Arguments |
|---|---|---|
toggle-shuffle.sh |
Toggle shuffle mode | none |
toggle-repeat.sh |
Toggle repeat mode | none |
get-modes.sh |
Get shuffle/repeat status | none |
Utility
| Script | Purpose | Arguments |
|---|---|---|
is-running.sh |
Check if Spotify is running | none |
launch.sh |
Launch Spotify app | none |
quit.sh |
Quit Spotify | none |
Output Format
Scripts use delimiters for structured output:
<<>>separates fields within a recordERROR:prefix indicates an error message
Track Record Format
name<<>>artist<<>>album<<>>albumArtist<<>>duration<<>>position<<>>trackNumber<<>>discNumber<<>>id<<>>spotifyUrl<<>>artworkUrl<<>>popularity
Player State Format
state<<>>position<<>>volume<<>>shuffling<<>>repeating
Modes Format
shuffling<<>>repeating
Usage Examples
Basic Playback
# Play/pause
./scripts/play.sh
./scripts/pause.sh
./scripts/toggle-playback.sh
# Navigation
./scripts/next-track.sh
./scripts/previous-track.sh
Search and Play (Agent-Assisted)
# Agent searches web for: site:open.spotify.com bohemian rhapsody
# Gets URL from results, then plays:
./scripts/play-uri.sh "https://open.spotify.com/track/6l8GvAyoUZwWDgF1e4822w"
# Works for any content type:
./scripts/play-uri.sh "https://open.spotify.com/playlist/37i9dQZF1DXaXB8fQg7xif"
./scripts/play-uri.sh "https://open.spotify.com/album/3BHe7LbW5yRjyqXNJ3A6mW"
Visual Search (Opens Spotify App)
./scripts/search.sh "bohemian rhapsody"
./scripts/search.sh "artist:queen"
./scripts/search.sh "playlist:hot country"
Play Specific Content
# Play a track
./scripts/play-uri.sh "spotify:track:4uLU6hMCjMI75M1A2tKUQC"
# Play an album
./scripts/play-uri.sh "spotify:album:7ppypgQppMf3mkRbZxYIFM"
# Play a playlist
./scripts/play-uri.sh "spotify:playlist:37i9dQZF1DXcBWIGoYBM5M"
# Play track in album context (enables album queue)
./scripts/play-uri.sh "spotify:track:xxx" "spotify:album:yyy"
Get Track Information
# Get current track details
./scripts/get-current-track.sh
# Output: Song Name<<>>Artist<<>>Album<<>>Album Artist<<>>180<<>>45<<>>1<<>>1<<>>spotify:track:xxx<<>>https://open.spotify.com/track/xxx<<>>https://i.scdn.co/image/xxx<<>>75
# Get player state
./scripts/get-player-state.sh
# Output: playing<<>>45.5<<>>75<<>>false<<>>true
Volume Control
# Get current volume
./scripts/get-volume.sh
# Set specific volume
./scripts/set-volume.sh 50
# Adjust volume
./scripts/volume-up.sh
./scripts/volume-down.sh
Seeking
# Get current position
./scripts/get-position.sh
# Jump to 30 seconds
./scripts/set-position.sh 30
# Skip forward/backward 10 seconds
./scripts/fast-forward.sh
./scripts/rewind.sh
Shuffle and Repeat
# Toggle modes
./scripts/toggle-shuffle.sh
./scripts/toggle-repeat.sh
# Check current modes
./scripts/get-modes.sh
# Output: true<<>>false
App Control
# Check if running
./scripts/is-running.sh
# Launch/quit
./scripts/launch.sh
./scripts/quit.sh
Parsing Output
When receiving track info, parse like this:
- Split by
<<>>to get fields - Fields are: name, artist, album, albumArtist, duration, position, trackNumber, discNumber, id, spotifyUrl, artworkUrl, popularity
Example parsing in bash:
IFS='<<>>' read -ra fields <<< "$output"
name="${fields[0]}"
artist="${fields[1]}"
album="${fields[2]}"
# ... etc
Spotify URI Format
Spotify uses URIs to identify content:
- Tracks:
spotify:track:<track_id> - Albums:
spotify:album:<album_id> - Playlists:
spotify:playlist:<playlist_id> - Artists:
spotify:artist:<artist_id>
You can get URIs from:
- Spotify desktop: Right-click > Share > Copy Spotify URI
- Spotify web: Copy from URL (e.g.,
https://open.spotify.com/track/xxx->spotify:track:xxx)
Notes
- Scripts require macOS with Spotify Desktop app installed
- Works with free or premium Spotify accounts
- No authentication or API keys required
- First run may trigger macOS permission prompts for automation
- Duration is returned in seconds (converted from milliseconds)
- Position is in seconds
Limitations
AppleScript API does NOT support:
- Adding to playlists
- Viewing or managing queue
- Liking/saving tracks
- Browsing library
- Searching private/personal playlists (use play-uri.sh with the playlist URI instead)
For these features, use the Spotify Web API (requires Premium + OAuth).
Reference
For advanced AppleScript patterns and customization, see ./reference/applescript-patterns.md.