spotifyscraper

SpotifyScraper

公式 API や API キーを使わずに、トラック、アルバム、アーティスト、プレイリスト、ポッドキャストなどの公開 Spotify データを抽出できます。

🎧 ブラウザーでライブデモをお試しください → — Spotify のリンクを貼り付けると、SpotifyScraper が型付きデータ、カバーアート、プレビューを取得する様子と、それを実現する正確な Python コードをご覧いただけます。（構築方法。）

SpotifyScraper は Spotify 自身の公開埋め込みページから匿名トークンを取得し、ウェブプレーヤーと同じ JSON エンドポイントを読み込んで、型付きの不変モデルを返します。v3 は信頼性とすっきりとした最新の API に重点を置いて、一から書き直されました。公開データの取得にログインは不要です。オプトインのログイン済み機能（歌詞、ポッドキャストの文字起こし、アカウント情報）を利用する場合は、Spotify の sp_dc Cookie をご自身で追加してください。パスワードや API キーは必要ありません。

v2 からアップグレードしますか？ 移行ガイドをご覧ください。以前の系列はv2.xブランチで引き続き公開されています。

SpotifyScraper と公式 API（spotipy）

spotipy は Spotify の公式 Web APIをラップします。ユーザーのアカウントへの書き込みや、非公開データ／ライブラリデータの読み取りが必要な場合に適しています。SpotifyScraper は、Web プレーヤーがすでに公開している公開データを読み取るため、セットアップは一切不要です。

	SpotifyScraper	spotipy（公式 API）
API キー／アプリ登録	❌ 不要	✅ 必須
OAuth フロー	❌ 不要	✅ ほとんどのデータで必須
レート制限の割り当て／課金	なし	Spotify の割り当て
同期・非同期	✅	同期のみ
完全に型付けされた不変モデル	✅	一部対応
歌詞とポッドキャストの文字起こし	✅（Cookie）	❌
Claude／LLM エージェント向け MCP サーバー	✅	❌
書き込み／再生／非公開データ	❌（公開データの読み取り専用）	✅

認証済みの書き込みや、マーケットに正確に対応した非公開データにはspotipyをお使いください。公開メタデータ、歌詞、プレビューにキーなしですばやくアクセスする場合や、AI エージェント向けのドロップインMCP サーバーには、SpotifyScraperをお使いください。

公式 API の廃止の影響を受けていますか？ Spotify の audio-features、recommendations、related-artists エンドポイントは、2024 年 11 月以降、新しいアプリに対して 403 を返しています。SpotifyScraper では API キーなしで、引き続き関連アーティストとおすすめを取得できます（audio-features を復活させることはできません。Spotify はすべてのツールから、このデータを完全に削除しました）。

インストール

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 以降。

クイックスタート

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

各エンティティには専用のメソッドがあります。get_track、get_album、get_artist、get_playlist、get_episode、get_show があり、それぞれ URL、URI、または ID のみを受け取ります。

非同期

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())

カバーとプレビューをダウンロード

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]

表示名のローカライズ

locale に BCP-47 の言語タグを渡すと、表示名の言語をローカライズできます。言語のサブタグのみ（"de"、"ja"）または言語と地域のタグ（"ja-JP"）を指定できます。クライアントごとに設定するか、呼び出しごとに上書きできます。

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

これは Accept-Language ヘッダーとして送信され、名前の表記のみを変更します。国／マーケットコードではありません。言語として単独の "US" を指定しても意味がないため、無視されます。また、地域ごとの利用可能状況を絞り込んだり、プレビュー URLを変えたりすることはありません。匿名アクセス時の Spotify はリクエスト IP から国を判定し、pathfinder は market 変数を黙って無視します。マーケット／利用可能状況を正確に絞り込むには認証済み Web API が必要ですが、このライブラリでは実装されていません。地域に応じた結果を取得するには、クライアントの proxy に対象地域を指定してください。ローカライズガイドをご覧ください。

機能

• すべての主要エンティティとポッドキャスト — トラック、アルバム、アーティスト、プレイリスト、番組、エピソードに対応します。
• 検索 — すべてのエンティティタイプを横断して検索し、型付きの SearchResults を返します。
• チャートと新しい音楽の発見 — エディトリアルチャート、関連アーティスト、ページネーション対応の完全なディスコグラフィー、アルバムのおすすめに対応します。
• カバー画像の色と Canvas — アートワークのテーマパレットを抽出し、トラックのループする Canvas 動画をダウンロードします。
• クレジットとコンサート — 演奏者／作詞・作曲者／プロデューサー、およびアーティストの今後のライブイベントを取得します。
• 公開ユーザープロフィール — get_user() で、名前、フォロワー数、公開プレイリストを取得します。
• MCP サーバー — spotifyscraper-mcp を使ってすべての機能を Claude／LLM に公開します（バッチツールと、1 回の呼び出しで使える get_track_visuals を提供）。ghcr.io のコンテナとしても配布されています。
• ローカライズされた表示名 — BCP-47 言語タグ（locale）を渡すと、名前の表示言語を設定できます。
• 歌詞とポッドキャストの文字起こし — Cookie 認証に対応し、時間同期されます。どちらにも同じトークンを使用します。
• ブラウザーを使ったログインとセッションの永続化 — 1 回ログインすれば、その後はヘッドレスで実行できます（パスワードは保存されません）。
• アカウント情報に対応 — get_account()／is_premium() に加え、Cookie 不要の session_info() を利用できます。
• バッチヘルパー — 複数形の get_*s([...]) で、一部の失敗に影響されない結果と管理された並行処理を利用できます。
• 同期クライアントと非同期クライアント — 1 つの sans-io コアを共有します。
• 型付きの不変モデル — JSON に安全な to_dict()／from_dict() を備えています。
• 2 段階の耐障害性 — Spotify の GraphQL API を使い、自動的に埋め込みページへフォールバックします。
• コア依存関係は 1 つ（httpx）。メディアとブラウザーのサポートはオプションの追加機能です。
• オプションのレスポンスキャッシュ — オプトイン方式で永続化され、トークンを安全に扱います（トークンを含まない pathfinder の GET リクエストのみ）。
• BAN 対策を標準搭載 — ホストごとのレート制限、バックオフ付きリトライ、UA ローテーション、プロキシに対応します。
• ブラウザーによるフォールバック — 実際のブラウザーが必要な場合は Playwright を使用します。

コマンドライン

cli 追加機能をインストールすると、spotifyscraper コマンドを利用できます。

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

すべてのコマンドは JSON を出力するため、jq などのツールと組み合わせて使えます。CLI ガイドを参照してください。

バッチヘルパー

各ゲッターには複数形の対応関数（get_tracks、get_albums など）があり、複数の入力を取得して、入力ごとに 1 つの BatchItem を返します。入力とのインデックスが対応しているため、無効な入力があっても残りの処理は中断されません。

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}

非同期クライアントは、max_concurrency（デフォルトは 5）で上限を設定して、これらを並行実行します。バッチガイドを参照してください。

レスポンスキャッシュ

同じデータを繰り返し取得する場合は、オプトイン方式の永続キャッシュを有効にできます。キャッシュされるのはトークンを含まない pathfinder のレスポンスのみです。匿名トークンを含む埋め込みページはキャッシュされないため、認証情報がディスクに書き込まれることはありません。

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

デフォルトの TTL は 24 時間です。FileCache は標準ライブラリのみで構成され、バックエンドは差し替え可能です。キャッシュガイドを参照してください。

検索

search() は、すべてのエンティティタイプを横断する 1 回の匿名集約クエリを実行し、型付きの 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)

検索結果は簡略形式です（完全なエンティティを取得するには、get_album()／get_show() に id を渡してください）。total はトラックの一致件数です。検索ガイドを参照してください。

歌詞と文字起こし

歌詞とポッドキャストの文字起こしには、Spotify アカウントの Cookie（sp_dc）が必要です。ライブラリがトークンのハンドシェイクを処理するため、同じ Cookie で両方を利用できます。

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)

Cookie は Spotify にのみ送信され、ログに記録されることはありません。文字起こしがないエピソードでは NotFoundError が発生します。歌詞と Cookie のガイドを参照してください。

ブラウザーを使ったログイン

Cookie を手動でコピーしたくない場合は、login() を使うと実際のブラウザーが開き、一度サインインするだけで、取得した sp_dc が保存されます（パスワードは収集も保存もされません）。以降の実行ではヘッドレスで再接続するため、サーバーに最適です。

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() はデフォルトで有効な保存済みセッションを再利用します（ブラウザーを使うのは初回のみです）。from_saved_session() では browser エクストラは不要です。Cookie は所有者のみがアクセスできるファイル、または store="keyring" を指定して OS のキーチェーンに保存されます（keyring エクストラ）。get_account()／is_premium() はログイン中のアカウントを返し、SpotifyClient.session_info() は Cookie を公開せずに保存済みセッションを確認します。詳しくは 認証済みセッションのガイドをご覧ください。

ロードマップ

リリース済み

バージョン	対象範囲
3.0	ライブラリー：すべてのエンティティ、ページネーション、メディアのダウンロード、ブラウザーのフォールバック、ドキュメント
3.1	コマンドラインインターフェース
3.2	Cookie 認証による歌詞取得
3.3	Cookie 認証によるポッドキャストの文字起こし（get_transcript）；ブラウザーを使ったログイン、セッションの永続化、アカウント認識（get_account／is_premium）
3.4	すべてのエンティティタイプを対象とする検索（search()）・表示言語のローカライズ（locale）
3.5	任意のレスポンスキャッシュ（cache=CacheConfig(...)）・並行処理を管理するバッチヘルパー
3.6	ビジュアルとディスカバリー：カバーの色、Canvas 動画、チャート、関連アーティスト、ページネーション対応のディスコグラフィー、おすすめ、公開プロフィール、トラックのクレジット、コンサート · クラス最高の MCP サーバー とコンテナーイメージ
3.7	MCP バッチツール（get_tracks／get_albums／…） · ビジュアル系フロントエンド向けの便利なツール get_track_visuals
3.8	メンテナンス：依存関係、ツールチェーン、CI の最新化（すべての Actions を現行のメジャーバージョンに更新し、SHA で固定） · ドキュメントと PyPI へのバックリンク
3.9	公式 MCP レジストリへの公開（および Glama／mcp.so／PulseMCP／Smithery での発見性向上） · 「vs spotipy」比較 · 一度だけ表示される、オプトアウト可能な CLI のスター促進メッセージ

今後の予定 — 今後のアイデアは GitHub の マイルストーンと イシューで管理しています。👍 を付けるか、特に重要だと思うものについて意見をお寄せください。対象範囲は変更される場合があります。

信頼性とメンテナンス

このライブラリーは Spotify 自身の公開エンドポイントを利用しているため、Spotify が変更を加えると動作しなくなることがあります。信頼性を保つため、次のような取り組みを行っています。

• 毎日のカナリアテストで、Spotify に対してライブテストスイートを実行しています。エンドポイントに変更があると、spotify-breakage イシューが自動で作成され（復旧時にはクローズされるため）、リグレッションをユーザーに影響する前に把握できます。
• 不具合はメンテナーのレビューのもと、Claude Code（Anthropic のコーディングエージェント）の協力を得て、迅速に優先順位を付けて修正しています。これは、このプロジェクトを前進させているエージェント支援ワークフローと同じものです。永続クエリーのハッシュは単一ファイル（api/pathfinder.py）にまとめているため、Spotify のローテーションにも 1 行の更新で対応できます。
• すべての変更に対して、Linux、macOS、Windows 上の Python 3.10–3.13 で、ruff、mypy --strict、および隔離されたテストスイート（カバレッジの下限は 85%）を実行します。

問題が発生した場合は、イシューを作成してください。監視システムがすでに検出していることもよくあります。

ドキュメント

完全なドキュメント、ガイド、API リファレンス：https://spotifyscraper.readthedocs.io

MCP サーバーはコンテナーとしても提供しています： docker run -p 8000:8000 ghcr.io/aliakhtari78/spotifyscraper（認証が必要なツールを有効にするには SPOTIFY_SP_DC を設定してください）。

法的事項

SpotifyScraper は非公式の独立したプロジェクトであり、Spotify とは無関係です。公開されているデータと、Spotify が公開している約 30 秒のプレビューを読み取りますが、フルトラックのダウンロードや DRM の回避は行いません。教育および個人利用を目的とし、Spotify の利用規約に従って使用してください。法的通知をご覧ください。

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.mdをご覧ください。このプロジェクトは OpenSpec を使用した仕様主導で開発されており、仕様は openspec/ にあります。

スター履歴

SpotifyScraper によって公式 API の OAuth 手続きを省けたなら、⭐を付けていただけると、ほかの開発者が見つけやすくなります。また、今後どの機能の開発を続けるべきかを教えてくれます。

ライセンス

MIT © Ali Akhtari — フルスタック AI エンジニア（aliakhtari.com）。