spotify-transcripts

Download the Read along transcript of any Spotify podcast episode.

This uses Spotify's internal transcript-read-along endpoint — the same one your Spotify desktop / web player calls to render the Read along panel. So if the Read along view shows text in your Spotify app for a given episode, this script can download it.

There is no official Spotify API for transcripts — the public Web API only exposes metadata. We piggyback on your own logged-in session (via the sp_dc cookie) so we're using the same auth your client already uses.

Quick start

git clone git@github.com:trustos/spotify-transcript.git
cd spotify-transcript
make install
spotify-transcript            # prompts for an episode URL

make install creates a local .venv, installs Python dependencies, and drops a spotify-transcript wrapper into /usr/local/bin. It only asks for your sudo password if that directory isn't already user-writable (Homebrew users typically own it).

Requirements: Python 3.9+ and a browser logged into Spotify so the script can auto-extract the sp_dc cookie on first run.

Per-user install (no sudo, no /usr/local writes — make sure ~/.local/bin is on your PATH):

PREFIX=$HOME/.local make install

Use it from any directory:

spotify-transcript                                          # prompts for URL
spotify-transcript "https://open.spotify.com/episode/<id>"  # one-shot
spotify-transcript <url> --format srt                       # subtitles
spotify-transcript <url> --format all                       # txt + srt + json
spotify-transcript <url> --out ~/Notes                      # custom output dir

Output is written to ./transcripts/<episode-title>_<id>.txt (or wherever --out points). First run on macOS may show a Keychain prompt asking permission to read Chrome/Arc/Brave cookies — click Always Allow once.

Update later:

git pull
make deps        # if requirements.txt changed

Make targets: install, uninstall, venv, deps, run, clean.

Install (manual — without Make)

Prefer not to use Make? You can run the script directly:

cd spotify-transcript
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python transcript.py "https://open.spotify.com/episode/<id>"

Everything below uses the installed spotify-transcript command. Substitute python transcript.py if you went the manual route.

Re-run auth setup

If your cookie expires (Spotify rotates them every ~year, or if you log out):

spotify-transcript --setup           # auto-extract from browser again
spotify-transcript --manual-setup    # force manual paste prompt

Bearer token mode (fallback if sp_dc doesn't work)

If you can't get sp_dc working — e.g. you only use Spotify on the desktop app, or your web browser session is unauthenticated — you can paste the bearer token directly from DevTools:

spotify-transcript --token

The script walks you through: open https://open.spotify.com → DevTools → Network → filter "spclient" → hit play on any episode → copy the Authorization: Bearer … header value → paste.

Bearer tokens last about an hour. After that, paste a fresh one. (The cookie-based flow auto-refreshes; the bearer-token flow does not.)

How auth works

The script needs your sp_dc cookie — the same cookie Spotify Web Player uses to authenticate. There are two ways it can get it:

Auto-extract (default)

The browser-cookie3 library reads cookies straight from your browser's local cookie database, decrypting via macOS Keychain when needed. Supported: Chrome, Arc, Brave, Edge, Opera, Vivaldi, Chromium, Firefox, Librewolf, Safari. The first time it runs on a Chromium browser, macOS shows a Keychain prompt — click Always Allow.

This is what runs automatically on first use. You just need to be logged in to https://open.spotify.com in at least one browser.

Manual paste (fallback)

If no browser session is available — or auto-extract fails — paste the cookie by hand:

1. Open https://open.spotify.com and log in. Verify you see your profile picture in the top-right (not the "Log in" button).
2. Open DevTools (Cmd+Opt+I).
3. Application/Storage → Cookies → click https://open.spotify.com in the left sidebar (this filters to Spotify cookies only — otherwise you'll see Google analytics cookies mixed in).
4. Find the cookie named sp_dc and copy its Value (~140 chars).
5. Run python transcript.py --manual-setup and paste when prompted.

Either way, the cookie ends up at ~/.spotify-transcripts/config.json with permission 0600. It is never sent anywhere except to Spotify itself.

Troubleshooting

Spotify returned an anonymous token — your cookie is invalid or expired. Re-run spotify-transcript --setup and paste a fresh sp_dc.

Spotify says this episode has no transcript — confirm the Read along panel actually shows text for this episode in your Spotify app. Not every podcast has one; transcript coverage varies by show and region.

401 Unauthorized — token rejected mid-call. Run --setup again.

spotify-transcript: command not found after make install — the install target uses $(PREFIX)/bin, default /usr/local/bin. Either that directory isn't on your PATH, or you used PREFIX=$HOME/.local and ~/.local/bin isn't on your PATH. Check with echo $PATH; add the missing dir to your ~/.zshrc if needed.

How it works

1. URL → 22-char base62 episode ID.
2. GET open.spotify.com/api/token with Cookie: sp_dc=… plus a TOTP code derived from a periodically-rotated secret → short-lived bearer token (~1 hour). Spotify added the TOTP requirement in 2024; the latest cipher secrets are auto-downloaded from https://github.com/xyloflake/spot-secrets-go and cached in ~/.spotify-transcripts/secrets.json (refreshed daily). Tokens are also cached locally so re-auth only happens once an hour.
3. GET spclient.wg.spotify.com/transcript-read-along/v2/episode/{id} with that token → JSON of timestamped cues.
4. Normalize cues → write .txt, .srt, or .json.

If Spotify rotates the cipher in a way that breaks decoding before the upstream secrets repo catches up, run python transcript.py --refresh-secrets to force an update.

Notes

• This is unofficial. Spotify could change the endpoint or response shape at any time. The script tries a few known shape variants and falls back to saving the raw JSON if parsing fails.
• Don't commit ~/.spotify-transcripts/config.json anywhere — it holds your authenticated session cookie.
• For episodes without a Read along transcript, this won't help. Fall back to running the MP3 (from the show's public RSS feed) through Whisper or a hosted service like SpotScribe.