deezer-playlist-creator

name	deezer-playlist-creator
description	>-

Deezer Playlist Creator

End-to-end Deezer playlist creation. Three data sources, one pipeline: discover tracks → build tracklist → push to Deezer.

Data Pipeline Architecture

Every playlist request flows through a three-tier data sourcing strategy:

Tier 1: Deezer Public REST API (no auth)

Primary source for structured music discovery. Fast, rate-limited to ~50 req/5s, no credentials needed. Load the deezer skill before using these endpoints — it has the full reference.

Query type	API call	Returns
"Artists similar to X"	GET /artist/{id}/related	Up to 100 related artists with IDs
"Top tracks by X"	GET /artist/{id}/top?limit=N	Ranked top tracks (max 50)
"Discography of X"	GET /artist/{id}/albums	All albums by artist
"What's trending"	GET /chart/0/tracks	Worldwide chart
"New releases"	GET /editorial/0/releases	This week's new albums
"Genre exploration"	GET /genre/{id}/artists	Artists in a genre
"Search anything"	GET /search?q=QUERY&order=RANKING	Tracks, albums, artists
"Album tracklist"	GET /album/{id}/tracks	All tracks in an album

Full workflow example: "playlist of artists similar to Nirvana"

1. Public API: GET /search/artist?q=Nirvana          → artist ID: 543
2. Public API: GET /artist/543/related                → [Pearl Jam, Soundgarden, Alice in Chains, ...]
3. Public API: GET /artist/{id}/top?limit=3           → top 3 tracks per related artist
4. Build JSON tracklist from all those tracks
5. Pipe to deezer_create_playlist.py                  → playlist URL

Every step uses the public REST API for discovery. The GQL API only enters at the final step to create the playlist.

Tier 1.5: Last.fm API (API key)

Supplementary source for artist similarity and scrobble-ranked tracks. Last.fm's data is crowd-sourced from real listening behavior across millions of users — often better quality than algorithmic recommendations.

Load the new-music-digest skill for the full Last.fm endpoint reference and API key.

Query type	API call	Returns	Why use over Deezer
"Artists similar to X"	artist.getsimilar&artist=NAME&limit=10	Scrobble-based similar artists	Real fan overlap, not algorithmic
"Top tracks by X (by plays)"	artist.gettoptracks&artist=NAME&limit=10	Tracks ranked by scrobble count	Fan play counts, not stream counts
"My most-played artists"	user.gettopartists&user=USERNAME&period=3month	Personal top artists by scrobble	Personalizes playlists from your history

When to use Last.fm:

• Established artists (pre-2020) — Last.fm has deeper listening history
• Niche/subgenre artists — fan communities create better similarity signals
• "Make me a playlist from my library" — user.gettopartists seeds from your actual listening
• Cross-referencing Deezer's related results — pick artists that appear in both

When to skip Last.fm:

• Brand new artists (minimal scrobble history)
• The Deezer public API returns good results quickly — try it first, supplement with Last.fm if the results seem off

Integration pattern:

1. Deezer: GET /search/artist?q=X → Deezer artist ID
2. Last.fm: GET artist.getsimilar&artist=X → similar artists
3. For each similar artist: Deezer GET /search/artist?q=Y → Deezer artist ID → GET /artist/{id}/top
4. Build JSON and pipe

Tier 2: Deezer GQL Pipe API (ARL auth)

Adds algorithmic personalization. Use these when the public API can't answer the question.

Method	What it gives	Use when	Response shape
get_artist_mix(artist_id)	Algorithmic mix based on artist	"Deep cuts similar to X"	tracks.edges[].node
get_track_mix(track_ids, limit, start_with_input_track)	Mix from seed track(s)	"Songs like this one"	tracks[].track ⚠️ flat list, not edges
get_similar_tracks(track_id)	Similar to one track	"More tracks in this vein"	tracks.edges[].node
get_recommendations()	Personalized "you might like"	"Surprise me"	varies
get_flow()	Deezer's infinite Flow radio	"Put on something I'll like"	tracks.edges[].node
get_charts()	Current chart data	"What's hot right now"	varies
search(query)	Authenticated search	Better results than public API	results.tracks.edges[].node

Common genre IDs for public API: 0=All, 132=Pop, 116=Rap/Hip Hop, 152=Rock, 113=Dance, 129=Jazz, 98=Classical, 85=Alternative, 106=Electro

Tier 3: Web search (last resort)

For subjective or human-curated questions APIs can't answer:

• "Best deep cuts by The Cure"
• "Underrated 90s shoegaze albums"
• "Songs that feel like autumn in New England"
• Festival lineups, music blog picks, Reddit threads

Always prefer Tier 1 or Tier 2 first — web search is for when the API endpoints don't exist for the question being asked.

Script: deezer_create_playlist.py

Located at scripts/deezer_create_playlist.py in this skill directory.

The final step in every pipeline. Takes a JSON tracklist, searches Deezer for each track, creates a playlist, and populates it.

Usage

# With Infisical injection (preferred)
echo '{"title":"Name","description":"","tracks":[...]}' | \
  infisical run --projectId af3b8a09-35ab-4acc-b0ea-c4ef2201eb29 --env dev -- \
  python3.14 scripts/deezer_create_playlist.py

# From a file
python3.14 scripts/deezer_create_playlist.py --input /tmp/playlist.json

Input format

{
  "title": "Playlist name",
  "description": "Optional description",
  "tracks": [
    {"title": "Track Title", "artist": "Artist Name"},
    ...
  ]
}

Output

{
  "playlist_url": "https://www.deezer.com/playlist/15515468061",
  "playlist_id": "15515468061",
  "matched": 15,
  "missed": 2,
  "missed_tracks": [{"title": "...", "artist": "..."}],
  "tracks": [{"title": "...", "artist": "...", "link": "..."}]
}

How it works

1. Search — Each track searched via GQL search(), returns up to 20 candidates
2. Score — Python SequenceMatcher (0.7 title + 0.3 artist weight), score ≥ 0.5 = match
3. Create — create_playlist() → public, non-collaborative
4. Populate — add_tracks_to_playlist() in batches of 50

Match scoring details

• Extracts artist via contributors.edges[].node.name (not a flat artists array)
• Sorts all candidates by score, takes the highest
• Score < 0.5 → track is skipped and reported in missed_tracks

Full Workflow Examples

"Make me a playlist of artists similar to Nirvana"

1. Load deezer skill
2. GET /search/artist?q=Nirvana → artist ID 543
3. GET /artist/543/related → [Pearl Jam, Soundgarden, Alice in Chains, Stone Temple Pilots, ...]
4. For each related artist: GET /artist/{id}/top?limit=3
5. Build JSON: {title: "Artists Like Nirvana", tracks: [...]}
6. Pipe to deezer_create_playlist.py

"Make me a 90s trip-hop playlist"

1. GET /search?q=trip-hop 90s&order=RANKING&limit=50 (public API)
2. Filter results for quality/relevance
3. For top artists found: GET /artist/{id}/top?limit=3
4. Build JSON and pipe to script

"What's trending in electronic music right now?"

1. GET /genre/106/artists (electronic genre)
2. For each artist: GET /artist/{id}/top?limit=2
3. OR: GET /chart/0/tracks (worldwide chart, filter by genre)
4. Build JSON and pipe

"Surprise me with something I'll like"

1. Use GQL get_recommendations() or get_flow()
2. Extract tracks
3. Build JSON and pipe

"Make me a playlist from my Last.fm library"

1. Load new-music-digest skill (for Last.fm key and endpoint reference)
2. GET Last.fm: user.gettopartists&user=USERNAME&period=3month&limit=20
3. For each artist: Deezer GET /search/artist?q=NAME → artist ID → GET /artist/{id}/top?limit=3
4. (Optional) GET Last.fm: artist.gettoptracks for scrobble-ranked picks instead
5. Build JSON and pipe

Decision Tree

When the user asks for a playlist, follow this order:

1. Is this a personal "from my library" request? → Use Last.fm user.gettopartists to seed, then Deezer to resolve tracks
2. Can the public REST API answer this directly? (similar artists, top tracks, genre, charts, search) → Use Tier 1
3. Would scrobble data improve similarity? (established artists, niche genres, pre-2020 acts) → Supplement Tier 1 with Last.fm artist.getsimilar
4. Does it need algorithmic smarts? (track-based mixes, personal recommendations, flow) → Use Tier 2
5. Is it subjective or requires human cultural knowledge? (vibes, deep cuts, "best of" lists, festival lineups) → Use Tier 3 (web search)

Never use web search when the public API has a direct endpoint for the query. Never use the GQL API for simple searches the public API handles faster.

Pitfalls

• ARL expires ~3 months. If auth fails, re-extract from browser and update Infisical
• Null nodes in search edges — Some GQL track search results contain edge.node = None. The script skips these silently, but if all edges for a query are null the track is reported as missed. This is a Deezer API quirk, not a script bug.
• 0.5 scoring threshold is generous — It catches nearly everything (103/103 in testing) but produces false matches on ambiguous track names. Example failures: Amira Elfeky's "Paradise" → I Prevail (0.79), Novelists' "WHERE TO FIND ME" → Bilmuri (0.77). These all scored well above 0.5 but got the wrong artist. Raise the threshold near line 117 in deezer_create_playlist.py if you prefer fewer false matches at the cost of more misses.
• get_track_mix has a different response shape than search — Returns mix.tracks[i].track (flat list of {track: ...} objects), not mix.tracks.edges[i].node. Iterate with for item in mix.tracks: node = item.track. Also takes 3 required args: track_ids (list), limit (int), and start_with_input_track (bool).
• search returns results.tracks.edges[].node — Not tracks.edges directly. Access via results.results.tracks.edges.
• Search errors in stderr — The GQL API logs non-critical errors (album not found, playlist owner access denied) but search still returns results. Ignore the noise; check for actual data, not error messages.
• contributors not artists — Track nodes use contributors.edges[].node.name, not a flat artists array
• create_playlist returns {playlist: {id}} — Need result.playlist.id, not result.id
• Requires python3.14 — The script uses asyncio features from Python 3.14
• Rate limiting — 0.2s delay between searches. Large playlists (50+ tracks) take a few minutes.
• Public API limit is 50 req/5s — Add delays in bulk artist/track fetching loops
• Some tracks won't match — ~5-10% miss rate is normal. Less common tracks, regional releases, or tracks with special characters in the title are the usual culprits. The script reports misses so the user can manually add them.
• Genre IDs are Deezer-specific — Use the list above; don't guess
• /radio/top is unreliable — Use /radio/genres + /radio/lists instead

Troubleshooting

Issue	Fix
DEEZER_ARL not found	Run with infisical run -- or export the var
All tracks return "No match found"	ARL may be expired; re-extract from browser
Object of type ... is not JSON serializable	Check .playlist.id extraction and track ID types
GQL search returns 0 results	Fall back to public REST API search (deezer skill)
Public API returns 0 for related artists	Some artists have empty related lists; try web search
Playlist created but empty	add_tracks_to_playlist may have failed silently; check stderr
Tracks matching wrong artists (high recall, low precision)	Raise the score threshold near line 117 in the script; 0.5 is tuned for recall, 0.8+ for precision