Perfect Playlist

Build the playlist you chose. Exactly as you chose it.

A deterministic CLI and Python package for exact Spotify playlists—preserving order, duplicates, and every deliberate choice.

Install from PyPI
Install the official 1.0.0 release python -m pip install perfect-playlist
perfect-playlist
# 1. search $ perfect-playlist search 'track:"Call On You" artist:"Corey Lingo"' --json Candidates returned for deliberate review.
# 2. inspect $ perfect-playlist inspect spotify:track:5Qamlcya1Hz5Z4AgzdQ5q8 --json Canonical track URI confirmed.
# 3. build $ perfect-playlist build tracks.yaml --name "My Perfect Playlist" ✓ Created a new public playlist from exact URIs.
# 4. verify $ perfect-playlist verify tracks.yaml spotify:playlist:PLAYLIST_ID ✓ Exact ordered match. Duplicates preserved.
Deterministic by design Exact order Duplicates preserved URI-accurate

Deterministic workflow

Discovery can be intelligent. The final write should be exact.

Perfect Playlist removes the last interpretive handoff between choosing tracks and writing them to Spotify.

  1. 1 Search Find candidates
  2. 2 Inspect Confirm the exact recording
  3. 3 Save exact URIs Preserve order + duplicates
  4. 4 Build Write once
  5. 5 Verify Read back and compare

Why Perfect Playlist exists

One dependable final-mile primitive.

  • No substitutionsEvery URI you save is the URI written.
  • No hidden reorderingYour order remains your order.
  • No silent skipsIf it cannot be written, you will know.
  • No destructive overwritesWrites are new-build or explicit append-only operations.
TrackSequence / YAML 
tracks:
  - spotify:track:5Qamlcya1Hz5Z4AgzdQ5q8
  - spotify:track:5irdISp39LC6kD10muguYh
  - spotify:track:5Qamlcya1Hz5Z4AgzdQ5q8

# order and duplicates stay intact
Verify output / exact match 
$ perfect-playlist verify source.yaml playlist.yaml

exact: true
expected_count: 3
actual_count: 3
first_difference: null

All tracks match exactly.

Give your agent the deterministic playlist tool.

One click copies a complete onboarding prompt with the official site, PyPI package, CLI, repository, and agent skill.

Learn and use Perfect Playlist for deterministic
Spotify playlist work.

Official site:     https://perfectplaylist.dev
PyPI package:      pypi.org/project/perfect-playlist
GitHub repository: github.com/devin-thomas/perfect-playlist
Agent skill:       perfectplaylist.dev/SKILL.md

Install: python -m pip install perfect-playlist
Then read SKILL.md before Spotify-backed work.
Open full prompt

Official distribution

Install the 1.0.0 release from PyPI.

The same package provides the perfect-playlist command and the importable Python API.

python -m pip install perfect-playlist