Music Player
Play, queue, and search music on your device with DJ-style playlist building.
Installation
- Make sure Claude is on your device and in your terminal.
Skills load from
~/.claude/skills/when Claude Code starts up β so you need it on your machine first. If you don't have it yet, install it once with the command below, then runclaudein any terminal to verify.One-time setupnpm i -g @anthropic-ai/claude-codeAlready have it? Skip ahead.
- Paste into Claude Code or into your terminal.
This copies the whole skill folder into
~/.claude/skills/music-player-tsirysndr/β the SKILL.md plus any scripts, reference docs, or templates the skill ships with. Works for every skill.What this command does
- Makes a new, empty temporary folder.
- Downloads the skill's folder,
skills/music-player, fromgithub.com/tsirysndr/music-player(branchmaster), the GitHub repository it's listed from. You get the version that is there now, not a copy we keep. - Copies that folder to
~/.claude/skills/music-player-tsirysndr/. - Deletes the temporary folder.
Installing runs none of the skill's files; it only downloads and copies them. When you later use the skill, Claude follows its SKILL.md and may run scripts that come with it. Read them first.
Faster alternative (instruction-only skills)
Skips the clone and grabs only the SKILL.md file. Don't use this if the skill ships Python scripts, reference markdowns, or asset templates β they won't be downloaded and the skill will fail when it tries to load them.
Quick install (SKILL.md only)Sign up to copy - Restart Claude Code.
Quit and reopen Claude Code (or any other agent that loads from
~/.claude/skills/). New skills are picked up on startup. - Just ask Claude.
Skills auto-activate when your request matches the skill's description β no slash command needed. Trigger phrases live in the skill's own frontmatter; you can read them in the βWhat this skill doesβ section above.
Prefer to read the source first? Open on GitHub.
When Claude uses it
Play, queue and search music on the user's music-player daemon, and DJ for them β building a set that fits a mood, an activity or a request. Use whenever the user asks to play or queue something, asks what is playing, wants the volume or transport changed, or asks for a set, a mix or a playlist to be put on.
What this skill does
Playing music
You are driving a real audio player on the user's machine. Everything you do is
heard immediately, by whoever is in the room. That is the whole reason this is
worth being careful about: a wrong play_tracks does not produce a wrong
answer, it cuts off the song someone was enjoying.
Before anything else
Check that the tools are there. If now_playing and the rest are not available,
the MCP server is not connected β see Setting it up and tell
the user what to run. Do not fall back to guessing.
If the tools are there but every call reports no daemon at host:port, the CLI
is installed but nothing is running. Tell the user to start it:
music-player # foreground; add & to keep the shell
How to work
Find, then play. Ids are the currency. search takes free text and hands
back track, album and artist ids; browse_library pages through everything when
there is nothing specific to look for. Both feed play_tracks and
queue_tracks.
Queue rather than replace. queue_tracks adds without touching what is
playing. play_tracks wipes the queue and starts over β right when the user
says "play X", wrong when they say "add some more like this". When in doubt,
queue: an unwanted queue entry is skipped, an unwanted interruption is not
recoverable.
Look before you change. Call now_playing first when the request depends on
context β "something like this", "more of the same", "after this one". It also
tells you whether anything is playing at all, which changes whether you should
queue or start.
Say what you did. "Queued 8 tracks" is not an answer. Name a few of them β the user cannot see your tool calls, and the point of asking an agent rather than clicking is that you can say why those tracks.
Knowing what a track sounds like
search and browse_library only know titles. track_analysis knows how a
track actually sounds β its tempo, its energy (0 calm to 1 driving), its
brightness (-1 dark to 1 bright), and how loud it is. similar_tracks uses all
of that to answer "what goes after this?" without needing genres or anyone
else's listening history.
None of it works until tracks have been analysed, because analysis means
decoding the audio. analyze_library starts a background pass and returns
immediately; call it with no arguments to see how far it has got. Run it once
for a library, and check it before promising a mood-based set:
analyze_librarywith no arguments β{"analyzed": 0, "running": false}means nothing is analysed andsimilar_trackswill fail. Say so, and offer to start a pass rather than silently falling back to searching by name.- A pass takes roughly a second per local track and longer for a remote server, since each one has to be fetched. Start it, tell the user it is running, and get on with building a set from what is already there.
Handing over to auto-DJ
auto_dj turns the daemon's own DJ on: it keeps the queue five tracks deep,
each one chosen to follow the last by tempo and mood, never repeating and never
playing the same artist twice in a row. It never interrupts what is playing.
Steer it rather than micromanaging it. energy, brightness and bpm are a
direction, not a filter β the set leans that way over the next few tracks
instead of jumping:
- "wind things down" β
auto_djwithenabled: true, energy: 0.25 - "keep it going but pick it up" β
energy: 0.8 - "something more upbeat and brighter" β
energy: 0.75, brightness: 0.6 - "just keep playing" β
enabled: truewith no target at all - "stop choosing for me" β
enabled: false
Prefer auto-DJ over queueing thirty tracks yourself when the user wants music to keep going indefinitely: it reacts to skips and to a changed target, which a queue you built half an hour ago cannot.
DJing
When asked for a set β "put on something for cooking", "build me an hour of focus music", "DJ for the party" β the work is selection, not tool calls.
- Search around the request, not just inside it. A request for "something upbeat" is not a search query. Look for the artists, genres and albums that would satisfy it, several searches if needed, then choose from what the library actually holds.
- Sequence deliberately. Order is the DJ's contribution: open in the mood
asked for, build, and do not put the two most similar tracks back to back.
play_tracksandqueue_tracksboth play in the order given. - Keep it to a set, not a dump. Ten to twenty well-chosen tracks beats a hundred filtered ones. If the user wants it endless, queue a set and offer to extend it when it runs low.
- Work from their library. You can only play what is there. If the request cannot be met β no jazz in the library at all β say so plainly and offer the nearest thing, rather than queueing something that merely matched a word.
- Use the analysis when the request is about feel. "Something calm", "more
energy", "something for running" are questions about tempo and energy, not
about titles. Find one track that fits, then
similar_tracksfrom it β that is a far better set than guessing from names.
The tools
| Tool | For |
|---|---|
now_playing | Current track, position, volume, how much is queued |
playback_control | play, pause, next, previous, stop |
seek | Jump to a position in the current track |
set_volume | 0β100 |
search | Tracks, albums and artists matching free text |
browse_library | Page through albums, artists or tracks |
get_album | An album with its tracks, in order |
get_artist | An artist with their albums and tracks |
list_playlists / get_playlist | The user's saved playlists |
play_tracks | Replace the queue and start β interrupts |
queue_tracks | Add to the queue, next or end β does not interrupt |
view_queue | What has played, what is coming |
clear_queue | Empty it and stop |
set_playback_mode | Shuffle on/off, repeat off/queue/track |
list_servers / connect_server | Switch which library is being read |
track_analysis | Tempo, energy, brightness, loudness of one track |
similar_tracks | What sounds good after a given track |
analyze_library | Analyse tracks in the background, and check progress |
auto_dj | Hand the queue over to the daemon, and steer it |
connect_server changes where music is browsed from, not where it comes out;
it never interrupts playback. Only use it if the user asks for a different
server β their library is otherwise whatever is already connected.
Things to get right
- Never clear or replace the queue without being asked. "Play some jazz" while something is on is ambiguous: prefer queueing and say that you queued rather than replaced, so the user can ask for the other thing.
- Volume is heard by people, not read by them. Do not raise it beyond what was asked, and do not set it at all unless asked.
playback_controlwithplayresumes what is loaded. It starts nothing on an empty queue β useplay_tracksfor that.- A tool that returns
isErrorhas failed and changed nothing. Read the message and tell the user; do not retry the same call.
Setting it up
Only needed once, and only if the tools are missing.
1. Install the CLI
macOS or Linux, prebuilt binary:
curl -fsSL https://raw.githubusercontent.com/tsirysndr/music-player/master/install.sh | sh
Homebrew (macOS/Linux):
brew install tsirysndr/tap/musicplayer
npm:
npm install -g @tsiry/music-player
Debian, Ubuntu and other APT systems:
echo "deb [trusted=yes] https://apt.fury.io/tsiry/ /" \
| sudo tee /etc/apt/sources.list.d/music-player.list
sudo apt-get update && sudo apt-get install music-player
Fedora, RHEL, Rocky, AlmaLinux and other DNF systems:
sudo tee /etc/yum.repos.d/music-player.repo <<'EOF'
[music-player]
name=Music Player
baseurl=https://yum.fury.io/tsiry/
enabled=1
gpgcheck=0
EOF
sudo dnf install music-player
Check it worked with music-player --version.
2. Point it at some music
The daemon reads ~/Music by default; set music_directory in
~/.config/music-player/settings.toml for anywhere else. Then:
music-player scan # index the library
music-player # start the daemon
A remote library β Navidrome, Subsonic, Jellyfin, Plex, Kodi β is added in the desktop or web UI under Servers, and needs no scan.
3. Register the MCP server
Claude Code:
claude mcp add music-player -- music-player mcp
Codex (~/.codex/config.toml):
[mcp_servers.music-player]
command = "music-player"
args = ["mcp"]
Claude Desktop, and other hosts that use the same file
(~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
%APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"music-player": {
"command": "music-player",
"args": ["mcp"]
}
}
}
Restart the host afterwards. music-player mcp speaks JSON-RPC on stdin and
stdout and is not meant to be run by hand β running it in a terminal looks like
a hang, because it is waiting for a client.
Related skills
Word Document Editor
anthropics
Create, edit, and format Word documents with tables, images, and tracked changes.
Skill Template
anthropics
A template for creating and configuring new Claude skills.
Kanban TUI
Zaloog
Manage tasks, boards, and workflows in your terminal with a CLI kanban tool.
AgentPostage
AgentPostage
Send PDFs as physical US mail for bank disputes, cancellations and notices. Free skill, paid mailing with your own API key.