YouTubeダウンローダー
概要
yt-dlpとffmpegを使用して、YouTubeやHLSストリーミングプラットフォーム(Mux、Vimeoなど)からの信頼性の高い動画・音声ダウンロードを実現します。このスキルは以下のワークフローを提供します:
- POトークンプロバイダーまたはブラウザCookieを使用したYouTubeダウンロード(最大4K)
- 認証ヘッダーを使用したHLSストリームダウンロード
- 保護されたコンテンツの処理と一般的なダウンロード失敗のトラブルシューティング
非技術ユーザー向けエクスペリエンス(デフォルト)
ユーザーは非技術者であると想定してください。コマンドを実行するようユーザーに依頼しないでください。すべてを自分で実行し、平易な言葉で進捗を報告してください。ユーザーが尋ねない限り、ツールについて言及しないでください。
デフォルトのフロー:
- URLを尋ねます(提供されていない場合)。
- 動画のメタデータ(タイトル/アップローダー/長さ/サムネイル)を取得し、ユーザーの意図と一致することを確認します。
- yt-dlpが「あなたがボットでないことを確認してください」でブロックされた場合、YouTube oEmbedにフォールバックしてタイトル/アップローダー/サムネイルを取得します(長さは不明な場合があります)。
- 簡単な選択肢を提供します(動画 vs. 音声のみ、品質、字幕、保存場所)。
- ユーザーが指定しない場合は、適切なデフォルトで進めます:
- 最高品質での動画ダウンロード
- MP4マージ出力
- 単一動画のみ(プレイリストは不可)
- ダウンロードし、最終的なファイルパス、ファイルサイズ、解像度(動画の場合)を報告します。
ユーザーフレンドリーな用語で選択肢を提供します:
- 「動画を最高品質でダウンロード(デフォルト)」
- 「音声のみをダウンロード(MP3)」
- 「品質を選択:1080p / 720p / 480p / 360p」
- 「字幕を含める(利用可能な場合)」
- 「ダウンロードフォルダ(デフォルト)または別のフォルダを指定して保存」
サムネイルが利用可能な場合は常にレンダリングします:
- メタデータにサムネイルURLが含まれている場合は、Markdown画像構文を使用して含めます:

追加作業の前に確認を求めます:
- プレイリストのダウンロードを確認します(大容量になる可能性があります)。
- 依存関係が不足している場合、インストール/アップグレードを確認します。
- ブラウザCookieを抽出する前に確認を求めます。
- Cookieを使用する場合、ユーザー向けの応答でCookieの数や生のCookieの詳細を決して言及しないでください。「あなたのChromeログインセッションを使用しました」と言います。
- 確認が必要な場合は、ローカルPOトークンヘルパーを自動的にセットアップします(ユーザーの操作は不要)。Dockerがないか失敗した場合は、Dockerをインストールしようとせず、代わりにブラウザベースのPOトークンプロバイダーに切り替えます。
法的/安全性の注意(簡潔に):
- ユーザーがコンテンツをダウンロードする権利または許可を持っている場合にのみ進めてください。
応答テンプレート(平易な言葉を使用し、コマンドは含めない):

タイトル:…
チャンネル:…
長さ:…
次のことができます:
1) 動画をダウンロード(最高品質、MP4)
2) 音声のみをダウンロード(MP3)
3) 特定の品質を選択(1080p/720p/480p/360p)
4) 字幕を含める(利用可能な場合)
どこに保存しますか?(デフォルト:ダウンロードフォルダ)
ユーザーが「ただダウンロードして」と言った場合:
- デフォルトで進め、ダウンロードが完了したら確認します。
- 403でブロックされた場合は、自動的に確認ヘルパーをセットアップして再試行します。
信頼性の高いダウンロードSOP(内部用)
以下のSOPに従って、一般的な失敗や混乱を回避します:
- シェルコマンドではURLを引用符で囲みます(zshは
?をグロブとして扱います)。例:'https://www.youtube.com/watch?v=VIDEO_ID' - yt-dlpとPOトークンプロバイダーの両方にプロキシがアクティブであることを確認します(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
- 「サインインしてボットでないことを確認してください」が表示された場合は、許可を求め、ブラウザCookieを使用します。Cookieなしで進めないでください。
- ダウンロード前にPOトークンプロバイダーを開始します(起動できない場合は速やかに失敗します)。
- Docker bgutilプロバイダーが利用可能な場合はそれを使用します。
- Dockerがないか失敗した場合は、ブラウザベースのWPCプロバイダーに切り替えます。
- Cookieを使用している場合は、
web_safariプレイヤークライアントを優先します。それ以外の場合は、POトークンにはmwebを優先します。 - WPCがトークンを発行している間、ブラウザウィンドウを開いたままにします。Chromeが同じプロキシを介してYouTubeに到達できることを確認します。
- 「画像のみ利用可能」または「要求された形式は利用できません」が表示された場合は、POトークンの失敗として扱い、トークンプロバイダー/ブラウザの状態を修正して再試行します。
- SSL EOFまたはフラグメントエラーが発生した場合は、プロキシ/ネットワークの問題として扱います。プログレッシブ形式および/またはより適切なプロキシで再試行します。
エージェント実行チェックリスト(内部用)
scripts/download_video.py URL --infoを実行します(許可があれば--cookies-from-browser chromeを追加)してメタデータとサムネイルを取得します。- yt-dlpのメタデータが失敗した場合は、タイトル/アップローダー/サムネイルについてスクリプトのoEmbedフォールバックに依存し、長さが利用できない可能性があることに注意します。
- サムネイルURLが存在する場合は、Markdown画像構文を使用して応答にレンダリングします。
- ユーザーに動画か音声のみかを選択させ、(オプションで)品質プリセットを選択させます。
- ユーザーがフォルダを指定しない限り、デフォルトの保存場所(ダウンロードフォルダ)を使用します。
- 字幕の場合、
--subtitlesと要求された--sub-langを指定して実行します。 - ダウンロード後、ファイル名、サイズ、解像度(動画の場合)を平易な言葉で報告します。
- ダウンロードが403/フラグメントエラーで失敗した場合は、非m3u8プログレッシブ形式で1回再試行します。
- 「サインインしてボットでないことを確認してください」が表示された場合は、Cookieアクセスを要求し、Cookie +
web_safariで再試行します。 - 「画像のみ利用可能」が表示された場合は、POトークンの失敗として扱い、プロバイダー/ブラウザの状態を修正して再試行します。
- ダウンロード前にPOトークンプロバイダーを開始します(
--auto-po-tokenデフォルト)。起動できない場合は速やかに失敗します。 - Dockerベースのプロバイダーが失敗した場合(中国では一般的)、自動的にブラウザベースのWPCプロバイダーにフォールバックします(ブラウザウィンドウが一時的に開く場合があります)。
- WPCプロバイダーが使用されている場合、ダウンロードが開始されるまでブラウザウィンドウを開いたままにします。ブラウザの起動に失敗した場合は、Chromeのパスを明示的に設定します。
- POトークンプロバイダーがタイムアウトした場合は、1回再起動して再試行します。
- システムプロキシが設定されている場合は、プロバイダーコンテナに渡します。プロキシが127.0.0.1/localhostを指している場合は、Docker用に
host.docker.internalに書き換えます。
このスキルを使用するタイミング
このスキルは、ユーザーが以下の場合に呼び出す必要があります:
- YouTube動画またはプレイリストのダウンロードをリクエストする
- YouTube動画から音声を抽出したい
- yt-dlpのダウンロード失敗または限られた形式の可用性が発生している
- 形式選択や品質オプションについて支援が必要
- 低品質(360p)の形式のみが利用可能と報告する
- 特定の品質(1080p、4Kなど)でのYouTubeコンテンツのダウンロードについて尋ねる
- ダウンロードしたWebM動画をより広い互換性のためにMP4形式に変換する必要がある
- Mux、Vimeo、またはその他のストリーミングサービスなどのプラットフォームからのHLSストリーム(m3u8)のダウンロードをリクエストする
- 認証ヘッダーを必要とする保護ストリームをダウンロードする必要がある
前提条件
1. yt-dlpのインストールを確認する(自分で実行)
which yt-dlp
yt-dlp --version
インストールされていないか、古い場合(< 2025.10.22):
brew upgrade yt-dlp # macOS
# または
pip install --upgrade yt-dlp # クロスプラットフォーム
重要:古いyt-dlpバージョンは、nsig抽出失敗や形式の欠落を引き起こします。
2. 現在の品質アクセスを確認する(自分で実行)
ダウンロード前に、利用可能な形式を確認します:
yt-dlp -F "https://youtu.be/VIDEO_ID"
形式18(360p)のみが表示される場合:高品質アクセスにはPOトークンプロバイダーのセットアップが必要です。
高品質ダウンロードワークフロー
ステップ1:POトークンプロバイダーをインストールする(1回限りのセットアップ)
1080p/1440p/4Kアクセスのために、yt-dlpのPython環境にPOトークンプロバイダープラグインをインストールします:
# yt-dlpのPythonパスを見つける(yt-dlpが使用するインタプリタ)
head -1 $(which yt-dlp)
# 上記の行のインタプリタを使用してプラグインをインストール
<YTDLP_PYTHON> -m pip install bgutil-ytdlp-pot-provider
確認:yt-dlp -F "VIDEO_URL"を再度実行します。形式137(1080p)、271(1440p)、または313(4K)を探します。
詳細なセットアップ手順とトラブルシューティングについては、references/po-token-setup.mdを参照してください。
ステップ2:最高品質でダウンロードする
POトークンプロバイダーがインストールされたら:
# 1080pまでの最高品質をダウンロード
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# 利用可能な最高品質をダウンロード(4Kが利用可能な場合)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
ステップ3:ダウンロード品質を確認する
# 動画解像度を確認
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
1080pの期待される出力:
codec_name=vp9
width=1920
height=1080
代替方法:ブラウザCookie方式
POトークンプロバイダーのセットアップが問題がある場合は、ブラウザCookieを使用します:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
利点:年齢制限付きコンテンツやメンバー限定コンテンツへのアクセス。 要件:
- 指定されたブラウザでYouTubeにログインしている必要があります。
- ブラウザとyt-dlpは同じIP/プロキシを使用する必要があります。
- Cookieと一緒にAndroidクライアントを使用しないでください(AndroidクライアントはCookieをサポートしていません)。
一般的なタスク
音声のみのダウンロード(自分で実行)
音声をMP3として抽出:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
カスタム出力ディレクトリ(自分で実行)
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
字幕付きダウンロード(自分で実行)
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
プレイリストのダウンロード(自分で実行)
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
WebMをMP4に変換する(自分で実行)
YouTubeの高品質ダウンロードは、多くの場合WebM形式(VP9コーデック)を使用します。より広い互換性のためにMP4に変換します:
# ffmpegがインストールされているか確認
which ffmpeg || brew install ffmpeg # macOS
# 適切な品質設定でWebMをMP4に変換
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
パラメータの説明:
-c:v libx264:H.264ビデオコーデックを使用(広く互換性があります)-preset medium:エンコード速度とファイルサイズのバランス-crf 23:品質のためのConstant Rate Factor(18-28の範囲、低いほど高品質)-c:a aac:AACオーディオコーデックを使用-b:a 128k:オーディオビットレート128kbps
ヒント:変換により1080p解像度が維持され、最新のハードウェアで約6倍のエンコード速度を提供します。
トラブルシューティングクイックリファレンス
360pのみ利用可能(形式18)
原因:POトークンプロバイダーの欠落またはyt-dlpの古さ。
解決策:
- yt-dlpを更新:
brew upgrade yt-dlp - POトークンプロバイダーをインストール(上記ステップ1を参照)
- またはブラウザCookie方式を使用
サインインしてボットでないことを確認
原因:続行するためにYouTubeが認証を要求しています。
解決策:
- 許可を求め、ブラウザCookieを使用します(
--cookies-from-browser chrome)。 - ブラウザとyt-dlpが同じIP/プロキシを使用していることを確認します。
- 必要に応じて
web_safariクライアントで再試行します。
画像のみ利用可能 / 要求された形式は利用できません
原因:POトークンが適用されていないか、プロバイダー/ブラウザの確認に失敗しました。
解決策:
- ダウンロード前にPOトークンプロバイダーが実行されていることを確認します。
- WPCを使用している場合は、ブラウザウィンドウを開いたままにします。
- Cookieを使用している場合は、
web_safariクライアントを優先して再試行します。
nsig抽出失敗
症状:
警告:[youtube] nsig抽出失敗:一部の形式が欠落している可能性があります
解決策:
- yt-dlpを最新バージョンに更新
- POトークンプロバイダーをインストール
- それでも失敗し、POトークンが無効になっている場合は、Androidクライアントを使用:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / フラグメントエラー
原因:プロキシまたはネットワークの不安定性。
解決策:
- プログレッシブ形式(非m3u8)で再試行します。
- より安定したプロキシ/ノードに切り替えます。
- ダウンロード中にPOトークンブラウザウィンドウを閉じないようにします。
ダウンロードが遅い、またはネットワークエラー
中国または制限的なプロキシの背後にいるユーザーの場合:
- ネットワーク状況によりダウンロードが遅くなる場合があります
- 完了には十分な時間を確保してください
- yt-dlpは一時的な障害に対して自動的に再試行します
POトークン警告(無害)
警告:androidクライアントのhttps形式にはGVS POトークンが必要です
対応:ダウンロードが成功した場合は無視します。これは、AndroidクライアントがPOトークンなしでは形式アクセスが制限されていることを示します。
バンドルスクリプトリファレンス
scripts/download_video.py
この便利なラッパーを使用して、高品質ダウンロードのためにデフォルトでPOトークンプロバイダーを自動起動します。自分で使用し、ユーザーにコマンドを実行するよう依頼せずに結果を報告します。
基本的な使い方:
scripts/download_video.py "VIDEO_URL"
引数:
url- YouTube動画URL(必須)-o, --output-dir- 出力ディレクトリ--output-template- 出力ファイル名テンプレート(yt-dlp構文)-f, --format- 形式指定-q, --quality- 品質プリセット(best、1080p、720p、480p、360p、worst)。デフォルト:best(--audio-onlyの場合はスキップ)-a, --audio-only- 音声をMP3として抽出--subtitles- 利用可能な場合、字幕をダウンロード--sub-lang- 字幕言語(カンマ区切り、デフォルト:en)--cookies-from-browser- ブラウザからCookieを読み込む(例:chrome、firefox)--cookies-file- cookies.txtファイルからCookieを読み込む--player-client- 特定のYouTubeプレイヤークライアントを使用(例:web_safari)--auto-po-token- POトークンプロバイダーを自動起動(デフォルト;利用可能な場合はDockerを使用、それ以外の場合はブラウザベースのプロバイダーに切り替え)--no-auto-po-token- 自動POトークンセットアップを無効化--proxy- yt-dlpとPOトークンプロバイダーのプロキシURL(例:http://127.0.0.1:1082)--wpc-browser-path- WPCプロバイダーのブラウザ実行可能パス-F, --list-formats- 利用可能な形式を一覧表示--merge-format- マージ出力コンテナ(例:mp4、mkv)。デフォルト:mp4--playlist- プレイリストのダウンロードを許可(デフォルト:単一動画のみ)--info- タイトル/アップローダー/長さ/サムネイルを表示して終了--no-android-client- Androidクライアントのフォールバックを無効化
注意:AndroidクライアントはPOトークンが無効になっている場合にのみ使用します。高品質を維持するためにPOトークンを有効にしておきます。
品質期待値
| セットアップ | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 自動POトークン(デフォルト) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Androidクライアントのみ | ✓ | ✗ | ✗ | ✗ | ✗ |
| POトークンプロバイダー(手動) | ✓ | ✓ | ✓ | ✓ | ✓ |
| ブラウザCookie | ✓ | ✓ | ✓ | ✓ | ✓ |