| name | channel-spotify |
| description | Spotify entity capture — playlists, shows, episodes, audiobooks. Metadata via the Web API; audio only from openly-distributed podcast RSS feeds; DRM catalog audio stays reference-only. |
| argument-hint | --stage harvest --capture-dir <dir> [--url <url>] |
| user-invocable | false |
Channel: Spotify
You capture Spotify entities — playlists, shows (podcasts), episodes,
albums, tracks, audiobooks — for this wiki. This file is authoritative for how
the venue is resolved and captured. The job already carries the resolved
config (assets, transcript policy) — honor it; never re-ask the operator.
This unit is platform-general — nothing in it is specific to any one
show or playlist. Once installed, the copy is wiki-owned: record your
wiki's watched entities and venue observations in it, and skills list
reporting it as diverged is provenance, not a problem. Chaining to another
unit means invoking it through the Skill tool — never read a sibling's
SKILL.md and improvise its behavior.
Authored 2026-08-01 in a working wiki (first target: the $100M Money Models
audiobook playlist, 9/9 episodes captured end to end), then promoted here.
The boundary this unit is built around
Spotify catalog audio (music tracks, Spotify-exclusive shows, audiobook
chapters) is DRM-protected. This unit never rips it — same contract as
the rest of the pipeline: DRM items are recorded as drm_protected
references (full metadata + player_url), and you move on. What it DOES
download is openly-distributed audio: most podcasts on Spotify also
publish a public RSS feed with plain MP3 enclosures; the unit resolves that
feed (keyless iTunes Search API) and hands the enclosures to the normal
asset download. A "Spotify capture" is therefore always full metadata, and
audio exactly when the creator distributes it openly.
Stages
--stage harvest — a claimed job carries skill: channel-spotify.
Run scripts/spotify.py capture <url> --capture-dir <dir>, then the
standard asset flow (below). Exit 4 = entity captured but no audio was
resolvable (all-DRM or no feed match) — that is a metadata-only capture,
not a failure; complete the job.--stage process — not declared. The capture ships a ready page.md
(title, creator, description, item table with per-item audio route), so the
generic scaffolder has everything; there is no HTML and no extract block.
Fingerprints
- URLs:
open.spotify.com/<type>/<id> where type ∈ playlist | show |
episode | album | track | audiobook | artist; spotify:<type>:<id> URIs;
/intl-xx/ locale prefixes appear and are tolerated.
- oEmbed at
open.spotify.com/oembed?url=… (keyless, title + thumbnail).
- Embed pages at
open.spotify.com/embed/<type>/<id> carry __NEXT_DATA__
JSON with the entity and a possibly truncated item list (keyless).
Discovery
One watch = one entity URL (scope: page). Enumeration happens inside
the capture, via the Web API with full pagination — playlists → items,
shows → episodes, albums → tracks, audiobooks → chapters. There is no link
crawling; discovered-URL queueing is not used.
Search-driven adds. When the operator names content instead of pasting a
URL ("add the Lex Fridman podcast episode 400"), resolve it first:
llm-wiki-ops run ops/skills/channel-spotify/scripts/spotify.py search "lex fridman #400" --type episode
JSON rows come back with name/by/date/duration/url — confirm the match with
the operator, then watch the chosen URL. Search requires API credentials.
Dates
Episodes, albums and audiobooks carry release_date (day precision).
Playlist items carry each item's own release date; the playlist itself has
none. capture --min-date YYYY-MM-DD drops older items, which is how a
show watch with max_age should be run. Keyless captures have no dates.
release_date is this venue's published. capture prints it as
published in its summary, already gated to day precision — copy that value
straight into capture.json, and scaffold stamps the note's published:
from it. Do not translate release_date yourself, and do not fall back to a
bare year: Spotify's release_date honors its release_date_precision, so
an album can return "1979", which names no publication day. An empty
published in the summary means the entity declared none — leave the key out
of capture.json entirely. The listing table keeps its own release_date
column as is; that is display, not frontmatter.
Access / auth
- API credentials (client-credentials flow; public catalog only):
stored as the
spotify credential ({"client_id": …, "client_secret": …})
— machine-local, never synced. Set up once per machine:
llm-wiki-ops run ops/skills/channel-spotify/scripts/spotify.py auth --client-id … --client-secret …
(creates + tests). The operator gets credentials from
developer.spotify.com → create an app; no user login is involved.
- Keyless degradation: with no credentials,
meta/capture fall back to
the public embed endpoint — entity name and a possibly truncated item
list, "keyless": true in the output, and a warning callout in page.md.
Good enough to probe; re-capture with credentials for the real thing.
- Out of scope: private playlists and the user library (would need user
OAuth, which nothing here implements). Search needs credentials.
Media
- Podcast episodes — the open route. The show's public RSS is resolved
via the keyless iTunes Search API (show name →
feedUrl), episodes matched
by normalized-title overlap + duration window (±150 s, score ≥ 1.0). A
match yields a plain MP3 enclosure as a pending audio entry in
assets.json; the match score and feed are recorded in the entry's note.
- Tracks / audiobook chapters / unmatched episodes — DRM or exclusive:
recorded in
meta.json drm_refs (id, name, url, status: drm_protected, preview_url when the API offers a 30 s preview) and
merged into capture.json's asset list by the worker. Never fed to
yt-dlp, never in assets.json.
- No captions anywhere on this venue's open route (RSS rarely carries
transcripts) — the transcript policy is what produces text from downloaded
episodes.
Capture flow (harvest worker)
llm-wiki-ops run ops/skills/channel-spotify/scripts/spotify.py capture <url> \
--capture-dir <job.capture_dir> # writes:
# meta.json entity + items + feeds + drm_refs + counts
# items.json normalized item list
# page.md ready for stage 2 (no HTML exists for this venue)
# assets.json pending entries: cover image + matched MP3 enclosures
llm-wiki-ops run scripts/assets.py download <cap>/assets.json \
--dest <job.dirs.assets> --referer <url>
# capture.json: assemble as usual; assets = assets.json entries (now
# downloaded) + meta.json drm_refs verbatim. tool: "spotify-api".
# published: copy the capture summary's `published` when non-empty (Dates).
# transcript: enqueue per job policy — audio type is what transcribe expects.
--no-audio captures metadata + cover only (fast probe). --keyless forces
the embed fallback. A verdict of partial is right only when the API
item list itself was truncated (keyless) — an all-DRM capture with complete
metadata is complete, with the reasons naming the DRM route.
Scripts
All in scripts/spotify.py (PEP 723; run from the wiki root):
auth --client-id … --client-secret … — store + test credentials.search <query> [--type …] [--limit N] [--market US] — catalog search,
JSON rows out; the add flow's resolver for non-URL requests.meta <url> [--keyless] — normalized entity JSON, full item pagination.resolve-feed <show-or-episode-url> | --show-name <name> — public RSS
feed + episode list, no credentials needed.capture <url> --capture-dir <dir> [--market US] [--min-date D] [--keyless] [--no-audio] — the whole capture; exit 4 = no audio resolved.
Quirks log
- 2026-08-01 — A playlist labeled "audiobook" may actually be podcast
episodes: the $100M Money Models playlist (
4rprjH5cIR72vskqa6RhpC)
is 9 episodes of the openly-distributed "The Game with Alex Hormozi", so
its audio was fully downloadable via the open feed. Check item URIs
(spotify:episode: vs spotify:track:) before assuming DRM.
- 2026-08-01 — Feed episode titles may embed a subtitle after a pipe
("Part 2: … | $100M Money Models Audiobook"); escape
| when rendering
markdown tables (the capture script does).
- 2026-08-01 — The embed endpoint's
trackList showed all 9 playlist
items, but treat keyless item lists as possibly truncated on larger
entities (the embed player paginates around ~100).
