universal-media-downloader

Universal Media Downloader（動画／ポッドキャスト汎用ダウンローダー）

対象範囲

優先対応（通常はそのまま利用できます）

• Douyinの動画：douyin.com、v.douyin.com などの動画リンク
• Douyinの画像・テキスト投稿：自動ダウンロードには未対応です（スクレイピング対策の制限）。手動でスクリーンショットを撮る必要があります
• Bilibili：bilibili.com、b23.tv など
• YouTube：youtube.com、youtu.be
• その他、yt-dlp が対応する多数のウェブサイト

ポッドキャストプラットフォーム

• 小宇宙（エピソード／番組ページ）：多くの場合、音声をそのままダウンロードできます（通常は yt-dlp を利用できます）
• その他のポッドキャストプラットフォーム：ページから音声の直リンクを解析できる場合は、通常ダウンロードできます

コンプライアンスに関する注意：ダウンロードは、保存する権利があるコンテンツ（ご自身がアップロードしたもの／著作権を所有するもの／許可を得たもの／プラットフォームがオフライン再生を許可しているものなど）のみにご利用ください。DRM／暗号化やプラットフォームによる制限がある場合、それらを回避しようとしないでください。

クイックスタート

1）動画をダウンロード（デフォルト）

• コマンド：

  • python scripts/download_media.py "<URL>"

• デフォルトの保存先：

  • ユーザーのホームディレクトリ内の ~/Downloads/（プロジェクト内には保存されません。日常的にアクセスしやすい場所です。DEC-004 を参照）
  • --out-dir パラメーターで出力先をカスタマイズできます

2）音声のみをダウンロード（ポッドキャスト向け／MP3 のみ必要な場合）

• コマンド：
  • python scripts/download_media.py --audio-only --audio-format mp3 "<URL>"

3）403／ログインが必要／リスク管理によるブロックが発生した場合：cookies を使って再試行

より手軽な方法（推奨）——ブラウザーの cookies を直接読み込みます：

• ユーザーがブラウザー（Chrome／Firefox／Safari／Edge）で対象サイトにログイン済みの場合、ブラウザーを指定するだけで利用できます。手動でエクスポートする必要はありません：
  • python scripts/download_media.py --cookies-from-browser chrome "<URL>"
  • 対象例：Bilibili の 412、YouTube の年齢制限、ログイン状態が必要な Douyin など

または、cookies.txt（Netscape 形式）を手動でエクスポートします：

• ユーザーに cookies.txt をエクスポートしてもらい、再試行します：
  • python scripts/download_media.py --cookies "/path/to/cookies.txt" "<URL>"

--cookies と --cookies-from-browser は同時に指定できません。どちらか一方を選んでください。Douyin の動画では cookie を手動で指定する必要はありません。スクリプトが自動で 3 段階のフォールバックを実行します（下記「プラットフォームごとの差異」を参照）。最後の段階では、この端末のブラウザーからゲスト cookie を自動取得して再試行します（Douyin へのログインは不要です）。

4）プロキシが必要な場合（任意）

• 例：
  • --proxy "socks5://127.0.0.1:7890"

5）ダウンロード先を指定

• ユーザーが自然言語で保存先を指定した場合、AI は --out-dir パラメーターに自動変換します
• 例：
  • ユーザーが「デスクトップにダウンロード」と指定 → --out-dir ~/Desktop
  • ユーザーが「Videos/bilibili に保存」と指定 → --out-dir "~/Videos/bilibili"
  • ユーザーが「このフォルダーにダウンロード」と指定（パスを指定）→ ユーザーが指定した絶対パスを使用
• 注意：対象ディレクトリが存在することを確認してください。存在しない場合は自動で作成できます

プラットフォームごとの差異と制限（重要）

• YouTube／Bilibili：

  • よくある失敗原因：年齢制限、地域制限、頻繁なリクエストによるリスク管理の発動、ログインが必要
  • 対処方法：cookies、プロキシを使用するか、並列処理を減らす／時間をおいてから再試行します
  • YouTube に関する補足：Signature solving failed / JS challenge の警告が表示された場合、yt-dlp の EJS ガイドに従ってチャレンジ解決コンポーネントを有効にしてください（例：--remote-components ejs:github を追加）。または、ユーザーに cookies の提供を依頼してください

• Douyinの動画（自動で 3 段階のフォールバック、v0.3.0 以降／v0.5.0 で強化）：

  • Douyin の www.douyin.com ビジネス API はすべて a_bogus／msToken の署名ウォールで保護されているため、yt-dlp で直接ダウンロードすると Fresh cookies are needed が発生します。
  • 「Douyin のドメインで、ユーザーが cookie を明示的に指定していない」場合に yt-dlp が失敗すると、次の順に自動で対処します：
    1. ログインなしで直接取得（v0.3.0、動画のみ）：短縮リンク → SSR 共有ページから video_id を取得 → aweme.snssdk.com/aweme/v1/play/ から 302 CDN 直リンクを取得 → referer を付けてダウンロードします。cookie／署名は不要です。
    2. ブラウザーのゲスト cookie で再試行（v0.5.0、音声・動画の両方に対応）：ローカルの chrome、safari からゲスト cookie（s_v_web_id などのアクセス用 cookie。Douyin へのログインは不要）を順に自動取得し、yt-dlp を再実行することで、"Fresh cookies are needed" の検証を通過できます。
  • 適用範囲：公開動画のみです。非公開／友達限定、削除済み、地域制限、ライブ配信／ライブ配信のアーカイブ、画像・テキスト投稿には対応していません（画像・テキスト投稿には download_douyin_note.py を使用します）。ブラウザー cookie の取得に失敗した場合（Chrome の実行中に使用中である、または対象ブラウザーがないなど）は、次のブラウザーに自動で切り替えます。すべて失敗した場合は、yt-dlp の元のエラーを表示します。
  • ログインなしの直リンクの有効期間は約 1～2 時間です。期限切れの場合は再実行してください。SSR 共有ページは 2026-08-30 以降、cookie なしのリクエストに対して play_addr のレンダリングを停止しました（監視シグナル #2 が検出され、リスク管理によりシェルページが返されます）。現在の主な経路はゲスト cookie です。経緯については references/douyin-nocookie-approach.md を参照してください。

• Spotify：

  • Spotify 上のコンテンツには DRM、アカウント権限／サブスクリプションによる制限が存在する場合があり、「ダウンロード」はプラットフォームの利用規約に違反する可能性があります。
  • このスキルは、Spotify のリンクが必ずダウンロードできることを保証しません。
  • 代替手段：
    • 公式のオフライン機能を使用する（プラットフォームが提供している場合）
    • 対象ポッドキャストの RSS／音声直リンク（ご自身が所有している、または入手できるもの）を指定し、このスクリプトでダウンロードする

同梱スクリプト

• scripts/download_media.py

  • yt-dlp をベースにした汎用ダウンローダー
  • 出力：成功時は最終行に SAVED_FILEPATH=... を出力
  • AI 向け使用ガイド：ユーザーが保存先を指定した場合、--out-dir パラメーターを自動的に使用します
  • パラメーター：
    • url（必須）
    • --audio-only / --audio-format
    • --subtitles（任意。字幕を自動ダウンロード）
    • --sub-lang（任意。字幕の言語。デフォルトは all）
    • --cookies（任意）
    • --cookies-from-browser（任意。chrome/firefox/safari/edge。--cookies とは併用できません）
    • --proxy（任意）
    • --out-dir（任意。出力先ディレクトリをカスタマイズ）

• scripts/download_douyin_note.py

  • Douyin の画像・テキスト投稿用画像ダウンローダー（動画ストリームのインターフェースでは画像・テキスト投稿に対して先頭画像しか返されないため、画像は個別に抽出します）
  • 注意：依存する旧版の iteminfo API は Douyin によって encrypt_data_miss でブロックされています。現在の抽出機能には制限があるため、必要に応じて手動でスクリーンショットを撮ってください

• scripts/download_douyin_video_nocookie.py

  • Douyin の動画をログインなしで直接ダウンロードするスクリプト（aweme.snssdk.com/v1/play。cookie／署名は不要）
  • download_media.py は Douyin の yt-dlp によるダウンロードが失敗した場合、このスクリプトを自動で呼び出します。単独での使用も可能です
  • 出力は同様に SAVED_FILEPATH= で終わり、下流のスクリプト（cubox/content-manager）で解析できます
  • パラメーター：url（必須）、--out-dir、--ratio（540p/720p/1080p。デフォルトは 540p）、--out-name
  • 仕組みと適用範囲については references/douyin-nocookie-approach.md を参照してください

依存関係

システム依存関係

依存関係	インストール方法
yt-dlp	pip install yt-dlp
ffmpeg（任意。字幕の抽出と音声の変換に使用）	macOS: brew install ffmpeg Linux: sudo apt-get install ffmpeg
aria2c（任意。Douyin のフォールバックでの大容量ファイルのマルチスレッド高速化とレジュームに使用。未インストールの場合は自動的にシングルスレッドに切り替え）	macOS: brew install aria2

Python 包

无需额外 Python 依赖，yt-dlp 已包含所需库。 抖音相关脚本（download_douyin_*.py）额外依赖 requests（pip install requests）。