Skip to content
Back to search

SpotifyScraper

Extract public Spotify data — tracks, albums, artists, playlists, podcasts & lyrics — without the official API. Sync + async, typed models, one dependency.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aliakhtari78--spotifyscraper/badge.svg)](/listings/aliakhtari78--spotifyscraper)

HTML

<a href="/listings/aliakhtari78--spotifyscraper"><img src="/api/listings/aliakhtari78--spotifyscraper/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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+.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 351 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SpotifyScraper
  2. [![Live demo](https://img.shields.io/badge/Live_demo-try_it_now-1DB954?logo=spotify&logoColor=white)](https://aliakhtari.com/spotify/)
  3. [![PyPI version](https://img.shields.io/pypi/v/spotifyscraper.svg)](https://pypi.org/project/spotifyscraper/)
  4. [![Python versions](https://img.shields.io/pypi/pyversions/spotifyscraper.svg)](https://pypi.org/project/spotifyscraper/)
  5. [![Downloads](https://static.pepy.tech/badge/spotifyscraper/month)](https://pepy.tech/project/spotifyscraper)
  6. [![CI](https://github.com/AliAkhtari78/SpotifyScraper/actions/workflows/ci.yml/badge.svg)](https://github.com/AliAkhtari78/SpotifyScraper/actions/workflows/ci.yml)
  7. [![Docs](https://readthedocs.org/projects/spotifyscraper/badge/?version=latest)](https://spotifyscraper.readthedocs.io)
  8. [![Container](https://img.shields.io/badge/ghcr.io-container-2496ED?logo=docker&logoColor=white)](https://github.com/AliAkhtari78/SpotifyScraper/pkgs/container/spotifyscraper)
  9. [![Maintained with Claude Code](https://img.shields.io/badge/maintained%20with-Claude%20Code-d97757?logo=anthropic&logoColor=white)](https://github.com/AliAkhtari78/SpotifyScraper#reliability--maintenance)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/AliAkhtari78/SpotifyScraper/blob/master/LICENSE)
  11. [![GitHub stars](https://img.shields.io/github/stars/AliAkhtari78/SpotifyScraper?style=flat&logo=github&color=1DB954)](https://github.com/AliAkhtari78/SpotifyScraper/stargazers)
  12. **Extract public Spotify data — tracks, albums, artists, playlists, and podcasts — without the official API or an API key.**
  13. > 🎧 **[Try it live in your browser →](https://aliakhtari.com/spotify/)** — 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](https://aliakhtari.com/work/spotify-scraper/).)
  14. SpotifyScraper bootstraps an anonymous token from Spotify's own public embed
  15. pages and reads the same JSON endpoints the web player uses, returning typed,
  16. immutable models. v3 is a ground-up rewrite focused on reliability and a clean,
  17. modern API. Public data needs no login; the opt-in **logged-in** features
  18. (lyrics, podcast transcripts, and account info) add your own Spotify `sp_dc`
  19. cookie — never a password or an API key.
  20. > **Upgrading from v2?** See the [migration guide](https://spotifyscraper.readthedocs.io/en/latest/migration/). The previous line lives on the [`v2.x` branch](https://github.com/AliAkhtari78/SpotifyScraper/tree/v2.x).
  21. ## SpotifyScraper vs. the official API ([spotipy](https://github.com/spotipy-dev/spotipy))
  22. `spotipy` wraps Spotify's **official Web API** — the right choice when you need to
  23. write to a user's account or read private/library data. SpotifyScraper reads the
  24. **public** data the web player already exposes, so it skips the setup entirely.
  25. | | **SpotifyScraper** | **spotipy** (official API) |
  26. | --------------------------------- | :----------------: | :------------------------: |
  27. | API key / app registration | ❌ not needed | ✅ required |
  28. | OAuth flow | ❌ not needed | ✅ required for most data |
  29. | Rate-limit quota / billing | none | Spotify quota |
  30. | Sync **and** async | ✅ | sync only |
  31. | Fully typed, immutable models | ✅ | partial |
  32. | Lyrics & podcast transcripts | ✅ (cookie) | ❌ |
  33. | MCP server for Claude / LLM agents | ✅ | ❌ |
  34. | Write / playback / private data | ❌ (read-only public) | ✅ |
  35. Use **spotipy** for authenticated writes and private, market-accurate data; use
  36. **SpotifyScraper** for fast, key-free access to public metadata, lyrics, and
  37. previews — plus a drop-in **MCP server** for AI agents.
  38. > **Hit by the official-API deprecations?** Spotify's `audio-features`,
  39. > `recommendations`, and `related-artists` endpoints have returned `403` for new
  40. > apps since Nov 2024. SpotifyScraper still returns **related artists and
  41. > recommendations** with no API key. (It can't bring back `audio-features` —
  42. > Spotify removed that data entirely, from every tool.)
  43. ## Install
  44. ```bash
  45. pip install spotifyscraper # core (only depends on httpx)
  46. pip install "spotifyscraper[media]" # + cover/preview embedding (mutagen)
  47. pip install "spotifyscraper[browser]" # + Playwright browser fallback & login
  48. pip install "spotifyscraper[cli]" # + the spotifyscraper command-line tool
  49. pip install "spotifyscraper[keyring]" # + store the login cookie in the OS keyring
  50. pip install "spotifyscraper[mcp]" # + the spotifyscraper-mcp MCP server for LLM hosts
  51. pip install "spotifyscraper[all]" # everything
  52. ```
  53. Python 3.10+.
  54. ## Quickstart
  55. ```python
  56. from spotify_scraper import SpotifyClient
  57. with SpotifyClient() as client:
  58. track = client.get_track("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
  59. print(track.name, "—", track.artists[0].name)
  60. print(track.duration_ms, "ms |", track.preview_url)
  61. print(track.to_dict()) # JSON-safe dict, if you prefer dicts
  62. ```
  63. Every entity has its own method — `get_track`, `get_album`, `get_artist`,
  64. `get_playlist`, `get_episode`, `get_show` — each accepting a URL, URI, or bare
  65. ID.
  66. ### Async
  67. ```python
  68. import asyncio
  69. from spotify_scraper import AsyncSpotifyClient
  70. async def main():
  71. async with AsyncSpotifyClient() as client:
  72. track, album = await asyncio.gather(
  73. client.get_track("4uLU6hMCjMI75M1A2tKUQC"),
  74. client.get_album("6N9PS4QXF1D0OWPk0Sxtb4"),
  75. )
  76. print(track.name, "|", album.name)
  77. asyncio.run(main())
  78. ```
  79. ### Download a cover and preview
  80. ```python
  81. from spotify_scraper import SpotifyClient
  82. with SpotifyClient() as client:
  83. track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
  84. client.download_cover(track, dest="covers/")
  85. client.download_preview(track, dest="previews/", embed_cover=True) # needs [media]
  86. ```
  87. ### Localized display names
  88. Pass `locale` — a BCP-47 **language** tag: a bare language subtag (`"de"`,
  89. `"ja"`) or a language-region tag (`"ja-JP"`) — to localize the *language* of
  90. display names. Set it per client or override it per call:
  91. ```python
  92. with SpotifyClient(locale="ja-JP") as client: # default for every call
  93. track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
  94. other = client.get_track("4uLU6hMCjMI75M1A2tKUQC", locale="de-DE") # per-call wins
  95. ```
  96. It is sent as the `Accept-Language` header and changes only how names are
  97. *spelled*. It is **not** a country/market code — a bare `"US"` is meaningless as
  98. a language and is ignored — and it does **not** filter regional **availability**
  99. or vary **preview URLs**: anonymous Spotify resolves country from the request IP,
  100. and its pathfinder silently ignores a `market` variable. True market/availability
  101. filtering requires the authenticated Web API, which this library does not
  102. implement; for region-specific results, point the client's `proxy` at the target
  103. region. See the
  104. [localization guide](https://spotifyscraper.readthedocs.io/en/latest/guides/localization/).
  105. ## Features
  106. - **All core entities + podcasts** — tracks, albums, artists, playlists, shows, episodes.
  107. - **Search** across every entity type, returning one typed `SearchResults`.
  108. - **Charts & discovery** — editorial charts, related artists, full paginated discography, and album recommendations.
  109. - **Cover colors & Canvas** — extract an artwork's theming palette and download a track's looping Canvas video.
  110. - **Credits & concerts** — performers/writers/producers and an artist's upcoming live events.
  111. - **Public user profiles** — `get_user()` (name, follower counts, public playlists).
  112. - **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.
  113. - **Localized display names** — pass a BCP-47 language tag (`locale`) to set the language of names.
  114. - **Lyrics & podcast transcripts** — cookie-authenticated, time-synced, one token for both.
  115. - **Browser-assisted login + session persistence** — log in once, then run headless (no stored passwords).
  116. - **Account-aware** — `get_account()` / `is_premium()`, plus cookie-free `session_info()`.
  117. - **Batch helpers** — plural `get_*s([...])` with partial-failure-safe results and managed concurrency.
  118. - **Sync & async** clients sharing one sans-io core.
  119. - **Typed, frozen models** with JSON-safe `to_dict()` / `from_dict()`.
  120. - **Two-tier resilience** — Spotify's GraphQL API with automatic fallback to the embed page.
  121. - **One core dependency** (`httpx`); media and browser support are optional extras.
  122. - **Optional response cache** — opt-in, persistent, token-safe (only token-free pathfinder GETs).
  123. - **Anti-ban built in** — per-host rate limiting, retries with backoff, UA rotation, proxies.
  124. - **Browser fallback** via Playwright when you need a real browser.
  125. ## Command line
  126. With the `cli` extra installed, a `spotifyscraper` command is available:
  127. ```bash
  128. spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC # entity metadata as JSON
  129. spotifyscraper playlist <id> --max-tracks 50 --pretty
  130. spotifyscraper download preview <id> -o ./previews --embed-cover
  131. ```
  132. Every command emits JSON, so it composes with tools like `jq`. See the
  133. [CLI guide](https://spotifyscraper.readthedocs.io/en/latest/guides/cli/).
  134. ## Batch helpers
  135. Each getter has a plural sibling (`get_tracks`, `get_albums`, …) that fetches
  136. many inputs and returns one `BatchItem` per input — index-aligned, and a dead
  137. input never aborts the rest:
  138. ```python
  139. items = client.get_tracks(["4uLU6hMCjMI75M1A2tKUQC", "bad-id"])
  140. ok = [i.result for i in items if i.ok]
  141. failed = {i.value: i.error for i in items if not i.ok}
  142. ```
  143. The async client runs them concurrently, bounded by `max_concurrency` (default
  144. 5). See the [batch guide](https://spotifyscraper.readthedocs.io/en/latest/guides/batch/).
  145. ## Response caching
  146. For repeated lookups, enable an opt-in persistent cache. It only stores
  147. **token-free** pathfinder responses — never the embed pages that carry the
  148. anonymous token — so no credential is ever written to disk:
  149. ```python
  150. from spotify_scraper import SpotifyClient, CacheConfig, FileCache
  151. with SpotifyClient(cache=CacheConfig(store=FileCache())) as client:
  152. client.get_track("4uLU6hMCjMI75M1A2tKUQC") # first call hits the network
  153. client.get_track("4uLU6hMCjMI75M1A2tKUQC") # served from the cache
  154. ```
  155. Default TTL is 24h; the `FileCache` is stdlib-only and the backend is pluggable.
  156. See the [caching guide](https://spotifyscraper.readthedocs.io/en/latest/guides/caching/).
  157. ## Search
  158. `search()` runs one anonymous, aggregate query across every entity type and
  159. returns a typed `SearchResults`:
  160. ```python
  161. from spotify_scraper import SpotifyClient
  162. with SpotifyClient() as client:
  163. results = client.search("daft punk", types=("track", "artist"), limit=5)
  164. print(results.total, "track matches")
  165. for track in results.tracks:
  166. print(track.name, "—", track.artists[0].name)
  167. ```
  168. Hits are sparse (pass an `id` to `get_album()`/`get_show()` for the full entity);
  169. `total` is the track-match count. See the
  170. [search guide](https://spotifyscraper.readthedocs.io/en/latest/guides/search/).
  171. ## Lyrics & transcripts
  172. Lyrics and podcast transcripts need a Spotify account cookie (`sp_dc`); the
  173. library handles the token handshake for you, and one cookie powers both:
  174. ```python
  175. from spotify_scraper import SpotifyClient
  176. with SpotifyClient(cookies="cookies.txt") as client: # or cookies={"sp_dc": "..."}
  177. lyrics = client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC")
  178. for line in lyrics.lines:
  179. print(line.start_ms, line.text)
  180. transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS") # a podcast episode
  181. for line in transcript.lines:
  182. print(line.start_ms, line.text)
  183. ```
  184. Your cookie is sent only to Spotify and never logged. An episode with no
  185. transcript raises `NotFoundError`. See the
  186. [lyrics & cookies guide](https://spotifyscraper.readthedocs.io/en/latest/guides/lyrics-and-cookies/).
  187. ## Browser-assisted login
  188. Don't want to copy a cookie by hand? `login()` opens a real browser, you sign in
  189. once, and the captured `sp_dc` is persisted (no password is ever collected or
  190. stored). Later runs reconnect headlessly — ideal for servers:
  191. ```python
  192. from spotify_scraper import SpotifyClient
  193. with SpotifyClient() as client:
  194. client.login() # reuse a valid session, else open a browser
  195. print(client.get_lyrics("4uLU6hMCjMI75M1A2tKUQC").sync_type)
  196. # A later, headless run — no browser needed:
  197. with SpotifyClient.from_saved_session() as client:
  198. account = client.get_account() # who am I?
  199. print(account.product, account.country, client.is_premium())
  200. transcript = client.get_transcript("07gKzPFkbvGF0cHoeG7ARS")
  201. ```
  202. `login()` reuses a valid saved session by default (browser only the first time);
  203. `from_saved_session()` never needs the `browser` extra. The cookie is stored in
  204. an owner-only file, or the OS keyring with `store="keyring"` (the `keyring`
  205. extra). `get_account()`/`is_premium()` report the logged-in account, and
  206. `SpotifyClient.session_info()` checks a saved session without exposing the
  207. cookie. See the
  208. [authenticated sessions guide](https://spotifyscraper.readthedocs.io/en/latest/guides/authentication/).
  209. ## Roadmap
  210. **Shipped**
  211. | Version | Scope |
  212. |---------|-------|
  213. | **3.0** | The library: all entities, pagination, media downloads, browser fallback, docs |
  214. | **3.1** | Command-line interface |
  215. | **3.2** | Cookie-authenticated lyrics |
  216. | **3.3** | Cookie-authenticated podcast transcripts (`get_transcript`); browser-assisted login, session persistence & account-awareness (`get_account`/`is_premium`) |
  217. | **3.4** | [Search](https://github.com/AliAkhtari78/SpotifyScraper/issues/129) across every entity type (`search()`) · display-language [localization](https://github.com/AliAkhtari78/SpotifyScraper/issues/130) (`locale`) |
  218. | **3.5** | Optional [response cache](https://github.com/AliAkhtari78/SpotifyScraper/issues/131) (`cache=CacheConfig(...)`) · [batch helpers](https://github.com/AliAkhtari78/SpotifyScraper/issues/132) with managed concurrency |
  219. | **3.6** | **Visual & discovery**: cover colors, Canvas videos, charts, related artists, paginated discography, recommendations, public profiles, track credits, concerts · a best-in-class **MCP server** + container image |
  220. | **3.7** | MCP **batch tools** (`get_tracks`/`get_albums`/…) · `get_track_visuals` convenience tool for visual front-ends |
  221. | **3.8** | Maintenance: dependency, toolchain & CI modernization (all Actions on current majors, SHA-pinned) · docs & PyPI backlinks |
  222. | **3.9** | Official **MCP registry** publishing (+ Glama/mcp.so/PulseMCP/Smithery discovery) · "vs spotipy" comparison · one-time, opt-out CLI star hint |
  223. **What's next** — future ideas are tracked in the GitHub
  224. [milestones](https://github.com/AliAkhtari78/SpotifyScraper/milestones) and
  225. [issues](https://github.com/AliAkhtari78/SpotifyScraper/issues) — 👍 or weigh in
  226. on the ones that matter most to you. Scope is subject to change.
  227. ## Reliability & maintenance
  228. This library rides Spotify's own public endpoints, so it can break when Spotify
  229. changes them. To keep it dependable:
  230. - A **daily canary** runs the live test suite against Spotify. When an endpoint
  231. shifts, it automatically opens a `spotify-breakage` issue (and closes it on
  232. recovery), so regressions surface before they reach you.
  233. - Breakages are triaged and fixed promptly with the help of **[Claude Code](https://claude.com/claude-code)**
  234. (Anthropic's coding agent), under the maintainer's review — the same
  235. agent-assisted workflow that keeps this project moving. Persisted-query hashes
  236. live in a single file (`api/pathfinder.py`), so a Spotify rotation is a
  237. one-line update.
  238. - Every change runs through `ruff` + `mypy --strict` + a hermetic test suite
  239. (85% coverage floor) across Python 3.10–3.13 on Linux, macOS, and Windows.
  240. If something is broken for you, please
  241. [open an issue](https://github.com/AliAkhtari78/SpotifyScraper/issues) — the
  242. monitoring has often caught it already.
  243. ## Documentation
  244. Full docs, guides, and the API reference: **<https://spotifyscraper.readthedocs.io>**
  245. The MCP server also ships as a container:
  246. `docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper` (set `SPOTIFY_SP_DC`
  247. to enable the authenticated tools).
  248. ## Legal
  249. SpotifyScraper is an unofficial, independent project, not affiliated with
  250. Spotify. It reads publicly available data and the ~30-second previews Spotify
  251. publishes; it does not download full tracks or circumvent DRM. Use it for
  252. educational and personal purposes, and in line with Spotify's Terms of Service.
  253. See the [legal notice](https://spotifyscraper.readthedocs.io/en/latest/legal/).
  254. ## Contributing
  255. Contributions are welcome — see [CONTRIBUTING.md](https://github.com/AliAkhtari78/SpotifyScraper/blob/master/CONTRIBUTING.md). The project
  256. is developed spec-first with [OpenSpec](https://github.com/Fission-AI/OpenSpec);
  257. specs live in [`openspec/`](https://github.com/AliAkhtari78/SpotifyScraper/tree/master/openspec).
  258. ## Star history
  259. If SpotifyScraper saved you the official-API OAuth dance, a ⭐ helps other
  260. developers find it — and tells me which features to keep building.
  261. <a href="https://star-history.com/#AliAkhtari78/SpotifyScraper&Date">
  262. <picture>
  263. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=AliAkhtari78/SpotifyScraper&type=Date&theme=dark" />
  264. <img alt="Star history of AliAkhtari78/SpotifyScraper" src="https://api.star-history.com/svg?repos=AliAkhtari78/SpotifyScraper&type=Date" width="600" />
  265. </picture>
  266. </a>
  267. ## License
  268. [MIT](https://github.com/AliAkhtari78/SpotifyScraper/blob/master/LICENSE) © [Ali Akhtari](https://aliakhtari.com) — full-stack AI engineer ([aliakhtari.com](https://aliakhtari.com)).
  269. <!-- mcp-name: io.github.AliAkhtari78/spotifyscraper -->

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.