### Development Setup

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/CONTRIBUTING.md

Clone the repository, install dependencies using uv, and set up pre-commit hooks and commit message templates.

```bash
git clone https://github.com/AliAkhtari78/SpotifyScraper.git
cd SpotifyScraper
make dev                     # uv sync + macOS .pth repair (see note below)
uv run pre-commit install --hook-type pre-commit --hook-type commit-msg
git config commit.template .gitmessage
```

--------------------------------

### Install Extras with uv

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Install optional extras for SpotifyScraper using uv. Examples include 'media', 'cli', 'mcp', and 'all'. Remember to quote extras in shells like zsh.

```bash
uv add "spotifyscraper[media]"
```

```bash
uv add "spotifyscraper[cli]"
```

```bash
uv add "spotifyscraper[mcp]"
```

```bash
uv add "spotifyscraper[all]"
```

--------------------------------

### Quickstart: Get Track Information

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/README.md

Fetch track details like name, artists, duration, and preview URL using the synchronous SpotifyClient. The client can be used as a context manager.

```python
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

```

--------------------------------

### Install and Use SpotifyScraper CLI

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/index.md

Shows how to install the `cli` extra for SpotifyScraper and use the command-line interface to fetch track data and process it with `jq`. This requires `pip` and `jq` to be installed.

```bash
pip install "spotifyscraper[cli]"
spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC | jq -r '.name'
```

--------------------------------

### Install SpotifyScraper with All Extras

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Install the SpotifyScraper library with the 'all' extra to include all optional dependencies and functionalities.

```bash
pip install "spotifyscraper[all]"
```

--------------------------------

### Install SpotifyScraper

Source: https://github.com/aliakhtari78/spotifyscraper/wiki/Home

Install the SpotifyScraper library using pip. This is the first step before using the library.

```bash
pip install spotifyscraper
```

--------------------------------

### Install Keyring Extra

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/authentication.md

Install the 'keyring' extra for the spotify-scraper library to enable storing authentication secrets in the OS keyring.

```bash
pip install "spotifyscraper[keyring]"
```

--------------------------------

### Install and Run MCP Server

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/index.md

Install the spotifyscraper library with MCP support using pip and run the MCP server. Alternatively, use Docker to run the server.

```bash
pip install "spotifyscraper[mcp]"
spotifyscraper-mcp        # or: docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper
```

--------------------------------

### Install spotifyscraper with extras

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/README.md

Install the core library or with optional dependencies for media embedding, browser fallback, CLI tool, keyring integration, MCP server, or all features.

```bash
pip install spotifyscraper                 # core (only depends on httpx)

```

```bash
pip install "spotifyscraper[media]"        # + cover/preview embedding (mutagen)

```

```bash
pip install "spotifyscraper[browser]"      # + Playwright browser fallback & login

```

```bash
pip install "spotifyscraper[cli]"          # + the spotifyscraper command-line tool

```

```bash
pip install "spotifyscraper[keyring]"      # + store the login cookie in the OS keyring

```

```bash
pip install "spotifyscraper[mcp]"          # + the spotifyscraper-mcp MCP server for LLM hosts

```

```bash
pip install "spotifyscraper[all]"          # everything

```

--------------------------------

### Install SpotifyScraper with CLI and Media Tagging

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/cli.md

Install SpotifyScraper with both the CLI and media tagging extras for features like embedding cover art in previews.

```bash
pip install "spotifyscraper[cli,media]"
```

--------------------------------

### Install Core Library with uv

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Use this command to install the core SpotifyScraper library using uv. This is the basic installation for fetching tracks, albums, artists, playlists, episodes, and shows.

```bash
uv add spotifyscraper
```

--------------------------------

### Install SpotifyScraper with MCP Extra

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Install the SpotifyScraper library with the 'mcp' extra to enable the Model Context Protocol server for LLM hosts.

```bash
pip install "spotifyscraper[mcp]"
```

--------------------------------

### Install spotifyscraper

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/index.md

Install the spotifyscraper library using pip. Additional extras can be installed to include features like media tagging, browser automation, CLI tools, and more.

```bash
pip install spotifyscraper
```

```bash
pip install spotifyscraper[media]
```

```bash
pip install spotifyscraper[browser]
```

```bash
pip install spotifyscraper[cli]
```

```bash
pip install spotifyscraper[keyring]
```

```bash
pip install spotifyscraper[mcp]
```

```bash
pip install spotifyscraper[all]
```

--------------------------------

### Install SpotifyScraper with CLI Extra

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Install the SpotifyScraper library with the 'cli' extra to enable the command-line tool functionality using the typer library.

```bash
pip install "spotifyscraper[cli]"
```

--------------------------------

### Install SpotifyScraper with Media Extra

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Install the SpotifyScraper library with the 'media' extra to enable embedding cover art and ID3 tags into downloaded previews using the mutagen library.

```bash
pip install "spotifyscraper[media]"
```

--------------------------------

### Install and Use Spotifyscraper CLI

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/migration.md

Install the Spotifyscraper command-line interface with the 'cli' extra and use it to fetch track information. The --pretty flag formats the output.

```bash
pip install "spotifyscraper[cli]"
spotifyscraper track 4uLU6hMCjMI75M1A2tKUQC --pretty
```

--------------------------------

### Discoverability Commands

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-cli-framework/specs/command-line-interface/spec.md

Use '--help' for application and command-specific usage information. '--version' prints the installed package version.

```bash
spotifyscraper --help
```

```bash
spotifyscraper track --help
```

```bash
spotifyscraper --version
```

--------------------------------

### Verify SpotifyScraper CLI Installation

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/cli.md

Check if the SpotifyScraper CLI was installed correctly by running the version and help commands.

```bash
spotifyscraper --version
```

```bash
spotifyscraper --help
```

--------------------------------

### Awesome Python Entry Example

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/extras/growth/awesome-lists.md

Example of how to format an entry for the 'awesome-python' list, specifically for the 'hidden gem' category. Ensure the format matches exactly.

```markdown
* [SpotifyScraper](https://github.com/AliAkhtari78/SpotifyScraper) - Extract public Spotify metadata, lyrics and podcasts without the official API or an API key.
```

--------------------------------

### Documentation Example Fix - Missing Artist Fields

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/CHANGELOG.md

These snippets show corrected documentation examples for artist data, addressing the incorrect use of `artist['genres']`, `artist['followers']`, and `artist['popularity']` which may not always be available.

```python
# 'genres', 'followers', 'popularity' fields may not be available
```

--------------------------------

### Awesome Web Scraping Entry Example

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/extras/growth/awesome-lists.md

Example of how to format an entry for the 'awesome-web-scraping' list. This entry highlights the project's features, including API-free operation and async support.

```markdown
* [SpotifyScraper](https://github.com/AliAkhtari78/SpotifyScraper) - Scrape public Spotify data (tracks, albums, artists, playlists, podcasts, lyrics) with no API key; sync + async, typed.
```

--------------------------------

### Spotify Lyrics API Request Example

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-cookie-auth-lyrics/design.md

Example of an HTTP GET request to fetch lyrics for a specific track. Includes required headers and parameters.

```http
GET https://spclient.wg.spotify.com/color-lyrics/v2/track/<id>?format=json&vocalRemoval=false&market=from_token
Headers: Authorization: Bearer <user token>, app-platform: WebPlayer, User-Agent: <transport UA>
```

--------------------------------

### Code Example Discipline

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-docs-site/design.md

Requirement for all code examples within the guides to be runnable as-is, using a doctest-style approach with canonical fixture entities for maintainability and testability.

```markdown
Every code example in the guides MUST be runnable as written (doctest-style discipline; examples use the canonical fixture entities so maintainers can paste-run them).
```

--------------------------------

### CLI Testing Setup

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-cli-framework/design.md

Outlines the strategy for testing the CLI using 'typer.testing.CliRunner'. It involves mocking the SpotifyClient and verifying command outputs, file writes, and error handling.

```python
from typer.testing import CliRunner

# ... (test setup using CliRunner)
```

--------------------------------

### CLI Entry Point Initialization

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-cli-framework/design.md

Illustrates how the CLI entry point 'spotify_scraper.cli:app' is initialized. It includes lazy loading of the Typer app and graceful handling of missing 'typer' installations.

```python
from spotify_scraper.cli.main import app
```

--------------------------------

### Verify SpotifyScraper Installation

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/installation.md

Run this Python code snippet to verify that the SpotifyScraper library has been installed correctly by printing its version number.

```python
import spotify_scraper

print(spotify_scraper.__version__)
```

--------------------------------

### Async Teaser with AsyncSpotifyClient

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/quickstart.md

Basic example of using the asynchronous client. All sync API calls are mirrored and can be awaited. Use `async with` for client management.

```python
import asyncio
from spotify_scraper import AsyncSpotifyClient

async def main() -> None:
    async with AsyncSpotifyClient() as client:
        track = await client.get_track("4uLU6hMCjMI75M1A2tKUQC")
        print(track.name)

asyncio.run(main())
```

--------------------------------

### Get Playlist with Max Tracks

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/entities.md

Fetches a playlist and limits the number of tracks collected. Use `max_tracks=None` to get all tracks. Requires `SpotifyClient`.

```python
from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    # First 50 tracks
    playlist = client.get_playlist(
        "37i9dQZF1DXcBWIGoYBM5M", max_tracks=50
    )

print(playlist.name)
print(playlist.total_tracks, "tracks in total")
print(len(playlist.tracks), "tracks loaded")

for entry in playlist.tracks:
    print(entry.track.name)              # entry is a PlaylistTrack
    if entry.added_by is not None:
        print("  added by", entry.added_by.name)
```

--------------------------------

### Full Code Migration for Upgrade (Recommended)

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/CHANGELOG.md

Recommended approach for upgrading. Refactor your code to use the new SpotifyClient and its methods.

```python
# Old
from SpotifyScraper.scraper import Scraper, Request
req = Request().request()
scraper = Scraper(session=req)
track = scraper.get_track_url_info(url="...")

# New 
from spotify_scraper import SpotifyClient
client = SpotifyClient()
track = client.get_track("...")
```

--------------------------------

### Install Browser Transport and Playwright

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/browser-fallback.md

Install the 'browser' extra for SpotifyScraper and download the Chromium binary using Playwright. This is required before using the browser transport.

```bash
pip install "spotifyscraper[browser]"
playwright install chromium
```

--------------------------------

### v3 SpotifyClient Initialization and Track Fetch using Context Manager

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/migration.md

This snippet demonstrates the modern v3 approach using a context manager for automatic client closing and fetching track data by ID.

```python
from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6hMCjMI75M1A2tKUQC")
    print(track.name)
```

--------------------------------

### Initialize SpotifyClient with Context Manager

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/getting-started/quickstart.md

Use SpotifyClient as a context manager for automatic cleanup.

```python
from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    track = client.get_track("4uLU6htMCjMI75M1A2tKUQC")
    print(track.name)
```

--------------------------------

### Browser Transport Import Guard

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-browser-fallback/design.md

Ensures that the 'browser' extra is installed when importing browser transport modules. Raises an ImportError with installation instructions if playwright is not found.

```python
from spotify_scraper.browser.playwright import PlaywrightTransport, AsyncPlaywrightTransport
```

--------------------------------

### List and Get Spotify Charts (Python)

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/charts.md

Demonstrates how to list available chart keys and retrieve tracks from a specific chart. Ensure SpotifyClient is imported.

```python
from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    for chart in client.list_charts():
        print(chart.key, "—", chart.name)     # e.g. top-50-global — Top 50 - Global

    playlist = client.get_chart("todays-top-hits", max_tracks=20)
    for entry in playlist.tracks:
        print(entry.track.name)
```

--------------------------------

### Run SpotifyScraper MCP Server (sse)

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/mcp.md

Start the MCP server using the SSE (Server-Sent Events) transport. This is a legacy option for compatible hosts.

```bash
spotifyscraper-mcp --transport sse
```

--------------------------------

### Build and Run SpotifyScraper MCP Server in Python

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/mcp.md

Programmatically build and run the SpotifyScraper MCP server using Python. This example shows how to initialize the server with an optional sp_dc cookie and run it with the stdio transport.

```python
from spotify_scraper.mcp import build_server

server = build_server(sp_dc="<your sp_dc cookie>")
server.run(transport="stdio")
```

--------------------------------

### Documentation Example Fix - Missing Label

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/CHANGELOG.md

This snippet addresses a fix in documentation examples where `album['label']` was incorrectly used. The 'label' field is not available via web scraping and should not be accessed.

```python
# 'label' field is not available via web scraping
```

--------------------------------

### Start SpotifyScraper MCP Server

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/extras/growth/seo/no-api-key-spotify-python.md

Launch the SpotifyScraper MCP server. This allows public Spotify data to be accessed by LLM agents. Alternatively, a Docker command is provided.

```bash
spotifyscraper-mcp           # or: docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper
```

--------------------------------

### Configure AsyncSpotifyClient with Rate Limiting and Proxies

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/guides/async.md

Demonstrates how to configure the AsyncSpotifyClient with custom rate limiting, retry policies, and proxy settings.

```python
from spotify_scraper import AsyncSpotifyClient, RateLimit, RetryPolicy

client = AsyncSpotifyClient(
    rate_limit=RateLimit(per_second=2.0, burst=5),
    retry=RetryPolicy(max_attempts=4),
    proxy="http://user:pass@proxy.example:8080",
)
```

--------------------------------

### Add SpotifyScraper to awesome-mcp-servers

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/extras/growth/mcp-directories.md

Example of how to format an entry for the awesome-mcp-servers repository. Ensure you use the correct repository legend for emojis and follow the specified format.

```markdown
- [AliAkhtari78/SpotifyScraper](https://github.com/AliAkhtari78/SpotifyScraper) 🐍 🏠 - Public Spotify metadata, lyrics & podcasts with no API key or OAuth (sync+async, typed).
```

--------------------------------

### Handle HTTP GET Request with Caching

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/openspec/changes/archive/2026-06-16-add-response-cache/tasks.md

Implements the GET method for CachingTransport. It first checks if the URL is cacheable. If so, it attempts to retrieve the response from the cache. If not cached or stale, it fetches from the inner transport, stores successful responses, and returns the original response.

```python
    def get(self, url: str, *, headers=None) -> httpx.Response:
        if not self._is_cacheable(url):
            return self._inner.get(url, headers=headers)

        key = self._key(url, headers)
        entry = self._config.store.get(key)

        if entry and time.time() - entry.stored_at < self._config.ttl_seconds:
            # Cache hit and not stale
            return httpx.Response(
                entry.status_code,
                content=entry.content,
                headers=entry.headers
            )

        # Cache miss or stale entry
        response = self._inner.get(url, headers=headers)

        if response.status_code == 200:
            try:
                cache_entry = CacheEntry(
                    status_code=response.status_code,
                    headers=response.headers,
                    stored_at=time.time(),
                    content=response.content
                )
                self._config.store.set(key, cache_entry)
            except Exception as e:
                # Log error but don't prevent response return
                logging.getLogger("spotify_scraper").warning(f"Failed to store cache for {url}: {e}")

        return response

```

--------------------------------

### Get Playlist

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/README.md

Retrieves playlist information using a URL, URI, or ID.

```APIDOC
## GET PLAYLIST

### Description
Retrieves detailed information about a specific playlist from Spotify.

### Method
`SpotifyClient.get_playlist(url_or_uri_or_id, locale=None)`
`AsyncSpotifyClient.get_playlist(url_or_uri_or_id, locale=None)`

### Parameters
#### Path Parameters
None

#### Query Parameters
- **locale** (str) - Optional - A BCP-47 language tag to localize display names.

#### Request Body
None

### Request Example
```python
from spotify_scraper import SpotifyClient

with SpotifyClient() as client:
    playlist = client.get_playlist("37i9dQZF1DXcBWIGoYBM5M")
    print(playlist.name)
```

### Response
#### Success Response (200)
- **playlist** (object) - An object containing playlist details like name and description.

#### Response Example
```json
{
  "name": "Example Playlist Name",
  "description": "A curated list of songs."
}
```
```

--------------------------------

### v2 SpotifyClient Initialization and Track Info Fetch

Source: https://github.com/aliakhtari78/spotifyscraper/blob/master/docs/migration.md

This snippet shows the traditional way of initializing the SpotifyClient in v2 and fetching track information using a URL.

```python
from spotify_scraper import SpotifyClient

client = SpotifyClient(cookie_file="cookies.txt")
info = client.get_track_info("https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC")
print(info["name"])
client.close()
```