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 に到達できることを確認します。
- 「Only images are available」または「Requested format is not available」が表示された場合、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でリトライします。 - 「Only images are available」が表示された場合、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 トークンプロバイダーのインストール(初回のみ)
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: オーディオビットレート 128 kbps
ヒント: 変換により 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クライアントでリトライします。
Only Images Available / Requested Format Not Available
原因: PO トークンが適用されていないか、プロバイダー/ブラウザの確認に失敗しました。
解決策:
- ダウンロード前に PO トークンプロバイダーが実行されていることを確認します。
- WPC を使用している場合、ブラウザウィンドウを開いたままにします。
- Cookie を使用している場合、
web_safariクライアントを優先してリトライします。
nsig 抽出失敗
症状:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解決策:
- yt-dlp を最新バージョンに更新
- PO トークンプロバイダーをインストール
- それでも失敗し、PO トークンが無効になっている場合は、Android クライアントを使用:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / フラグメントエラー
原因: プロキシまたはネットワークの不安定性。
解決策:
- プログレッシブフォーマット(m3u8 以外)でリトライします。
- より安定したプロキシ/ノードに切り替えます。
- ダウンロード中に PO トークンブラウザウィンドウを閉じないようにします。
ダウンロードが遅い、またはネットワークエラー
中国または制限の厳しいプロキシの背後にいるユーザーの場合:
- ネットワーク状況によりダウンロードが遅くなる場合があります
- 完了まで十分な時間を確保してください
- yt-dlp は一時的な障害時に自動的にリトライします
PO トークン警告(無害)
WARNING: android client https formats require a GVS PO Token
対応: ダウンロードが成功した場合は無視します。これは 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 | ✓ | ✓ | ✓ | ✓ | ✓ |