SpotifyScraper

SpotifyScraper

Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — without the official API or an API key.

🎧 Try it live in your browser → — paste any Spotify link and watch SpotifyScraper pull typed data, cover art, and a preview, with the exact Python that does it. (How it was built.)

SpotifyScraper bootstraps an anonymous token from Spotify's own public embedpages and reads the same JSON endpoints the web player uses, returning typed,immutable models. v3 is a ground-up rewrite focused on reliability and a clean,modern API. Public data needs no login; the opt-in logged-in features(lyrics, podcast transcripts, and account info) add your own Spotify sp_dccookie — never a password or an API key.

Upgrading from v2? See the migration guide. The previous line lives on the v2.x branch.

SpotifyScraper vs. the official API (spotipy)

spotipy wraps Spotify's official Web API — the right choice when you need towrite to a user's account or read private/library data. SpotifyScraper reads thepublic data the web player already exposes, so it skips the setup entirely.

Use spotipy for authenticated writes and private, market-accurate data; useSpotifyScraper for fast, key-free access to public metadata, lyrics, andpreviews — plus a drop-in MCP server for AI agents.

Hit by the official-API deprecations? Spotify's audio-features,recommendations, and related-artists endpoints have returned 403 for newapps since Nov 2024. SpotifyScraper still returns related artists andrecommendations with no API key. (It can't bring back audio-features —Spotify removed that data entirely, from every tool.)

Install

pip install spotifyscraper                 # core (only depends on httpx)
pip install "spotifyscraper[media]"        # + cover/preview embedding (mutagen)
pip install "spotifyscraper[browser]"      # + Playwright browser fallback & login
pip install "spotifyscraper[cli]"          # + the spotifyscraper command-line tool
pip install "spotifyscraper[keyring]"      # + store the login cookie in the OS keyring
pip install "spotifyscraper[mcp]"          # + the spotifyscraper-mcp MCP server for LLM hosts
pip install "spotifyscraper[all]"          # everything

Python 3.10+.

Quickstart

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
    print(track.name, "—", track.artists[0].name)
    print(track.duration_ms, "ms |", track.preview_url)

    print(track.to_dict())          # JSON-safe dict, if you prefer dicts

Every entity has its own method — get_track, get_album, get_artist,get_playlist, get_episode, get_show — each accepting a URL, URI, or bareID.

Async

import asyncio
from spotify_scraper import AsyncSpotifyClient

async def main():
    async with AsyncSpotifyClient() as client:
        track, album = await asyncio.gather(
            client.get_track("4uLU6hMCjMI75M1A2tKUQC"),
            client.get_album("6N9PS4QXF1D0OWPk0Sxtb4"),
        )
        print(track.name, "|", album.name)

asyncio.run(main())

Download a cover and preview

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    client.download_cover(track, dest="covers/")
    client.download_preview(track, dest="previews/", embed_cover=True)  # needs [media]

Localized display names

Pass locale — a BCP-47 language tag: a bare language subtag ("de","ja") or a language-region tag ("ja-JP") — to localize the language ofdisplay names. Set it per client or override it per call:

with SpotifyClient(locale="ja-JP") as client:        # default for every call
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    other = client.get_track("4uLU6hMCjMI75M1A2tKUQC", locale="de-DE")  # per-call wins

It is sent as the Accept-Language header and changes only how names arespelled. It is not a country/market code — a bare "US" is meaningless asa language and is ignored — and it does not filter regional availabilityor vary preview URLs: anonymous Spotify resolves country from the request IP,and its pathfinder silently ignores a market variable. True market/availabilityfiltering requires the authenticated Web API, which this library does notimplement; for region-specific results, point the client's proxy at the targetregion. See thelocalization guide.

Features

• All core entities + podcasts — tracks, albums, artists, playlists, shows, episodes.
• Search across every entity type, returning one typed SearchResults.
• Charts & discovery — editorial charts, related artists, full paginated discography, and album recommendations.
• Cover colors & Canvas — extract an artwork's theming palette and download a track's looping Canvas video.
• Credits & concerts — performers/writers/producers and an artist's upcoming live events.
• Public user profiles — get_user() (name, follower counts, public playlists).
• MCP server — expose everything to Claude/LLMs via spotifyscraper-mcp (batch tools + a one-call get_track_visuals); also ships as a container on ghcr.io.
• Localized display names — pass a BCP-47 language tag (locale) to set the language of names.
• Lyrics & podcast transcripts — cookie-authenticated, time-synced, one token for both.
• Browser-assisted login + session persistence — log in once, then run headless (no stored passwords).
• Account-aware — get_account() / is_premium(), plus cookie-free session_info().
• Batch helpers — plural get_*s([...]) with partial-failure-safe results and managed concurrency.
• Sync & async clients sharing one sans-io core.
• Typed, frozen models with JSON-safe to_dict() / from_dict().
• Two-tier resilience — Spotify's GraphQL API with automatic fallback to the embed page.
• One core dependency (httpx); media and browser support are optional extras.
• Optional response cache — opt-in, persistent, token-safe (only token-free pathfinder GETs).
• Anti-ban built in — per-host rate limiting, retries with backoff, UA rotation, proxies.
• Browser fallback via Playwright when you need a real browser.

Command line

With the cli extra installed, a spotifyscraper command is available:

spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC          # entity metadata as JSON
spotifyscraper playlist <id> --max-tracks 50 --pretty
spotifyscraper download preview <id> -o ./previews --embed-cover

Every command emits JSON, so it composes with tools like jq. See theCLI guide.

Batch helpers

Each getter has a plural sibling (get_tracks, get_albums, …) that fetchesmany inputs and returns one BatchItem per input — index-aligned, and a deadinput never aborts the rest:

items = client.get_tracks(["4uLU6hMCjMI75M1A2tKUQC", "bad-id"])
ok = [i.result for i in items if i.ok]
failed = {i.value: i.error for i in items if not i.ok}

The async client runs them concurrently, bounded by max_concurrency (default5). See the batch guide.

Response caching

For repeated lookups, enable an opt-in persistent cache. It only storestoken-free pathfinder responses — never the embed pages that carry theanonymous token — so no credential is ever written to disk:

from spotify_scraper import SpotifyClient, CacheConfig, FileCache

with SpotifyClient(cache=CacheConfig(store=FileCache())) as client:
    client.get_track("4uLU6hMCjMI75M1A2tKUQC")   # first call hits the network
    client.get_track("4uLU6hMCjMI75M1A2tKUQC")   # served from the cache

Default TTL is 24h; the FileCache is stdlib-only and the backend is pluggable.See the caching guide.

Search

search() runs one anonymous, aggregate query across every entity type andreturns a typed SearchResults:

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    results = client.search("daft punk", types=("track", "artist"), limit=5)
    print(results.total, "track matches")
    for track in results.tracks:
        print(track.name, "—", track.artists[0].name)

Hits are sparse (pass an id to get_album()/get_show() for the full entity);total is the track-match count. See thesearch guide.

Lyrics & transcripts

Lyrics and podcast transcripts need a Spotify account cookie (sp_dc); thelibrary handles the token handshake for you, and one cookie powers both:

from spotify_scraper import SpotifyClient

with SpotifyClient(cookies="cookies.txt") as client:   # or cookies={"sp_dc": "..."}
    lyrics = client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC")
    for line in lyrics.lines:
        print(line.start_ms, line.text)

    transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS")   # a podcast episode
    for line in transcript.lines:
        print(line.start_ms, line.text)

Your cookie is sent only to Spotify and never logged. An episode with notranscript raises NotFoundError. See thelyrics & cookies guide.

Browser-assisted login

Don't want to copy a cookie by hand? login() opens a real browser, you sign inonce, and the captured sp_dc is persisted (no password is ever collected orstored). Later runs reconnect headlessly — ideal for servers:

from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    client.login()                              # reuse a valid session, else open a browser
    print(client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC").sync_type)

# A later, headless run — no browser needed:
with SpotifyClient.from_saved_session() as client:
    account = client.get_account()              # who am I?
    print(account.product, account.country, client.is_premium())
    transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS")

login() reuses a valid saved session by default (browser only the first time);from_saved_session() never needs the browser extra. The cookie is stored inan owner-only file, or the OS keyring with store="keyring" (the keyringextra). get_account()/is_premium() report the logged-in account, andSpotifyClient.session_info() checks a saved session without exposing thecookie. See theauthenticated sessions guide.

Roadmap

Shipped

What's next — future ideas are tracked in the GitHubmilestones andissues — 👍 or weigh inon the ones that matter most to you. Scope is subject to change.

Reliability & maintenance

This library rides Spotify's own public endpoints, so it can break when Spotifychanges them. To keep it dependable:

• A daily canary runs the live test suite against Spotify. When an endpointshifts, it automatically opens a spotify-breakage issue (and closes it onrecovery), so regressions surface before they reach you.
• Breakages are triaged and fixed promptly with the help of Claude Code(Anthropic's coding agent), under the maintainer's review — the sameagent-assisted workflow that keeps this project moving. Persisted-query hasheslive in a single file (api/pathfinder.py), so a Spotify rotation is aone-line update.
• Every change runs through ruff + mypy --strict + a hermetic test suite(85% coverage floor) across Python 3.10–3.13 on Linux, macOS, and Windows.

If something is broken for you, pleaseopen an issue — themonitoring has often caught it already.

Documentation

Full docs, guides, and the API reference: https://spotifyscraper.readthedocs.io

The MCP server also ships as a container:docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper (set SPOTIFY_SP_DCto enable the authenticated tools).

Legal

SpotifyScraper is an unofficial, independent project, not affiliated withSpotify. It reads publicly available data and the ~30-second previews Spotifypublishes; it does not download full tracks or circumvent DRM. Use it foreducational and personal purposes, and in line with Spotify's Terms of Service.See the legal notice.

Contributing

Contributions are welcome — see CONTRIBUTING.md. The projectis developed spec-first with OpenSpec;specs live in openspec/.

Star history

If SpotifyScraper saved you the official-API OAuth dance, a ⭐ helps otherdevelopers find it — and tells me which features to keep building.

License

MIT © Ali Akhtari — full-stack AI engineer (aliakhtari.com).