- “What playlists do I have?”
- “Build a 45-minute late-night indie folk playlist.”
- “Add Nirvana to my road-trip playlist.”
add_artist_to_playlist
Add every track by artist to playlist (skipping duplicates). Creates the playlist if it doesn’t already exist. Returns the number of tracks actually added.
string
required
Playlist name (created if missing).
string
required
Artist name (exact match).
add_tracks_to_playlist
Append specific tracks to a saved playlist, preserving the given order. Creates the playlist if it doesn’t exist. Tracks already in the playlist, FLAC files, and files flagged missing on disk are silently skipped. Returns the number of tracks actually added.
string
required
Playlist name (created if missing).
string[]
required
Absolute file paths from the library, in the order they should be appended. Get these from list_tracks_by_album, list_playlist_tracks, or search_tracks. Never invent paths.
create_playlist
Create a new named playlist with the given track paths. Errors if one with the same name already exists; use update_playlist to replace contents instead.
string
required
New playlist name (must not exist).
string[]
required
Absolute file paths from the library. Get these from list_tracks_by_album or search_tracks. Never invent paths.
any
Optional free-text description. Shown in playlist listings and carried over to Plex as the playlist summary when synced via sync_playlist_to_plex.
delete_playlist
Permanently delete a saved playlist. Cannot be undone. The playlist record is removed; the underlying music files are untouched.
string
required
Playlist name.
get_playlist
Summary of one playlist: total track count, total size, and the artist breakdown (with track count + size per artist). Does NOT return the full track list. Use list_playlist_tracks to page through tracks.
string
required
Playlist name.
heal_playlist
Drop references in a playlist to tracks whose files are no longer on disk (flagged missing by clickwheel scan). Returns the number dropped, the number remaining, and the list of removed track records.
string
required
Playlist name.
list_playlist_tracks
Paginated list of tracks in a saved playlist, in playlist order. Returns full track records (artist, title, album, path, duration, file_size, format). The path values are needed if you’re going to pass them to update_playlist.
string
required
Playlist name.
integer
default:"50"
Max tracks to return.
integer
Pagination offset (0 = first page).
list_playlists
All saved playlists with track counts, total size in bytes, and last-updated timestamps.
remove_artist_from_playlist
Remove every track by artist from playlist. Returns the number of tracks removed (0 if the artist wasn’t in the playlist).
string
required
Playlist name.
string
required
Artist name (exact match).
remove_tracks_from_playlist
Remove specific tracks from a saved playlist by path. Returns the number of references removed (0 if none of the paths were in the playlist). The playlist record stays even if it ends up empty.
string
required
Playlist name.
string[]
required
Absolute file paths to remove. Get these from list_playlist_tracks. Never invent paths.
set_playlist_description
Set a saved playlist’s description without touching its track list.
string
required
Playlist name.
string
required
Free-text description to set. Replaces any existing description; pass an empty string to clear it.
update_playlist
Replace a playlist’s contents wholesale (or create it if it doesn’t exist). Returns the new track count and replaced (True if a playlist by this name already existed).
string
required
Playlist name (created if missing).
string[]
required
Absolute file paths from the library.
any
Optional free-text description. Omit to leave any existing description untouched; pass a string to set it.