YouTube Downloader

概要

yt-dlp と ffmpeg を使用して、YouTube および HLS ストリーミングプラットフォーム (Mux、Vimeo など) から確実にビデオとオーディオをダウンロードします。このスキルは以下のワークフローを提供します:

• PO トークンプロバイダーまたはブラウザCookieを使用した YouTube ダウンロード (最大 4K)
• 認証ヘッダー付きの HLS ストリームダウンロード
• 保護されたコンテンツの処理と一般的なダウンロード失敗のトラブルシューティング

非技術ユーザーの経験 (デフォルト)

ユーザーは非技術的であると想定してください。コマンドの実行をお願いしないでください。すべて自分で実行し、進捗を平文で報告してください。ユーザーが質問しない限り、ツールに言及してください。

デフォルトフロー:

1. URL を聞く (提供されていない場合)。
2. ビデオメタデータ (タイトル/アップローダー/デュレーション/サムネイル) を取得し、ユーザーの意図と一致することを確認します。
   • yt-dlp が「あなたはボットではないことを確認してください」でブロックされている場合は、タイトル/アップローダー/サムネイル用に YouTube oEmbed にフォールバックしてください (デュレーションは不明な場合があります)。
3. シンプルな選択肢を提供します (ビデオ vs オーディオのみ、品質、字幕、保存場所)。
4. ユーザーが指定しない場合は、合理的なデフォルトで進めます:
   • 最良の品質でのビデオダウンロード
   • MP4 マージ出力
   • 単一ビデオのみ (プレイリストなし)
5. ダウンロードして、最終ファイルパス、ファイルサイズ、解像度 (ビデオの場合) を報告します。

ユーザーフレンドリーな用語で選択肢を提供してください:

• 「最良の品質でビデオをダウンロード (デフォルト)」
• 「オーディオのみをダウンロード (MP3)」
• 「品質を選択: 1080p / 720p / 480p / 360p」
• 「字幕を含める (利用可能な場合)」
• 「ダウンロードフォルダに保存 (デフォルト) またはフォルダを指定してください」

利用可能な場合は常にサムネイルをレンダリング:

• メタデータにサムネイル URL が含まれている場合は、Markdown イメージ構文を使用して含めてください: ![Thumbnail](URL)。

追加作業を行う前に確認してください:

• プレイリストダウンロードを確認します (大きくなる可能性があります)。
• 依存関係が不足している場合はインストール/アップグレードを確認します。
• ブラウザ Cookie を抽出する前に確認してください。
• Cookie を使用している場合、ユーザー向けの応答で Cookie 数や生の Cookie 詳細について言及しないでください。「Chrome ログインセッションを使用」と言ってください。
• 検証が必要な場合は、ローカル PO トークンヘルパーを自動的に設定してください (ユーザーアクションなし)。Docker が不足しているか失敗した場合は、Docker をインストールしようとしないでください。代わりにブラウザベースの PO トークンプロバイダーに切り替えてください。

法的/安全性の注意 (簡潔):

• ユーザーがコンテンツをダウンロードする権利または許可を持っている場合にのみ進めてください。

応答テンプレート (平文を使用し、コマンドは使用しない):

![Thumbnail](THUMBNAIL_URL)

タイトル: …
チャンネル: …
デュレーション: …

以下のことをお手伝いできます:
1) ビデオをダウンロード (最良の品質、MP4)
2) オーディオのみをダウンロード (MP3)
3) 特定の品質を選択 (1080p/720p/480p/360p)
4) 字幕を含める (利用可能な場合)

どこに保存しますか? (デフォルト: ダウンロードフォルダ)

ユーザーが「ダウンロードするだけ」と言う場合:

• デフォルトで進めてダウンロードが終了したときに確認してください。
  • 403 でブロックされている場合は、自動的に検証ヘルパーを設定して再試行します。

信頼性の高いダウンロード SOP (内部)

一般的な失敗と混乱を避けるには、この SOP に従ってください:

1. シェルコマンドで URL をクォートしてください (zsh は ? をグロブとして扱います)。例: 'https://www.youtube.com/watch?v=VIDEO_ID'。
2. yt-dlp と PO トークンプロバイダー の両方でプロキシがアクティブであることを確認してください (HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
3. 「ボットではないことを確認してサインイン」と表示された場合は、許可をリクエストしてブラウザ Cookie を使用してください。Cookie なしでは進まないでください。
4. ダウンロード前に PO トークンプロバイダーを起動してください (起動できない場合は早期に失敗)。
   • 利用可能な場合は Docker bgutil プロバイダーを使用してください。
   • Docker が不足しているか失敗した場合は、ブラウザベース WPC プロバイダーに切り替えてください。
5. Cookie が使用されている場合は、web_safari プレイヤークライアントを優先してください。それ以外の場合は mweb を PO トークンに優先してください。
6. WPC がトークンを発行している間、ブラウザウィンドウを開いたままにしてください。Chrome が同じプロキシを通じて YouTube に到達できることを確認してください。
7. 「イメージのみが利用可能です」または「リクエストされたフォーマットは利用できません」と表示された場合は、PO トークン失敗として扱い、トークンプロバイダー/ブラウザの状態を修正した後に再試行してください。
8. SSL EOF またはフラグメントエラーが発生した場合は、プロキシ/ネットワークの問題として扱ってください。プログレッシブフォーマットや/より良いプロキシで再試行してください。

エージェント実行チェックリスト (内部)

• scripts/download_video.py URL --info を実行してください (許可が得られた場合は --cookies-from-browser chrome を追加)。メタデータとサムネイルを取得します。
• yt-dlp メタデータが失敗した場合は、スクリプトの oEmbed フォールバックに頼り、タイトル/アップローダー/サムネイルを取得し、デュレーションが利用できない可能性があることに注意してください。
• サムネイル URL が存在する場合は、Markdown イメージ構文を使用して応答でレンダリングしてください。
• ユーザーにビデオ vs オーディオのみを選択させ、(オプションで) 品質プリセットを選択させてください。
• ユーザーが指定しない限り、フレンドリーなデフォルト保存場所 (ダウンロードフォルダ) を使用してください。
• 字幕については、--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 アクセスの場合、PO トークンプロバイダープラグインを yt-dlp の Python 環境にインストールします:

# 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/プロキシを使用する必要があります。
• Android クライアントで Cookie を使用しないでください (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: 品質用の定率係数 (18-28 範囲、低いほど高品質)
• -c:a aac: AAC オーディオコーデックを使用
• -b:a 128k: オーディオビットレート 128 kbps

ヒント: 変換は 1080p 解像度を保持し、最新のハードウェアで約 6x のエンコード速度を提供します。

トラブルシューティング速報

360p のみが利用可能 (フォーマット 18)

原因: PO トークンプロバイダーが不足しているか、yt-dlp が古い。

解決:

1. yt-dlp を更新: brew upgrade yt-dlp
2. PO トークンプロバイダーをインストール (上記ステップ 1 を参照)
3. またはブラウザ Cookie メソッドを使用してください

ボットではないことを確認してサインイン

原因: YouTube は認証を要求します。

解決:

1. 許可をリクエストしてブラウザ Cookie を使用してください (--cookies-from-browser chrome)。
2. ブラウザと yt-dlp が同じ IP/プロキシを使用することを確認してください。
3. 必要に応じて web_safari クライアントで再試行してください。

イメージのみが利用可能 / リクエストされたフォーマットは利用できません

原因: PO トークンが適用されていないか、プロバイダー/ブラウザ検証が失敗しました。

解決:

1. ダウンロード前に PO トークンプロバイダーが実行されていることを確認してください。
2. WPC を使用している場合は、ブラウザウィンドウを開いたままにしてください。
3. Cookie が使用されている場合は、web_safari クライアントを優先して再試行してください。

nsig 抽出失敗

症状:

WARNING: [youtube] nsig extraction failed: Some formats may be missing

解決:

1. yt-dlp を最新バージョンに更新
2. PO トークンプロバイダーをインストール
3. PO トークンが無効で失敗が続く場合は、Android クライアントを使用: yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

SSL EOF / フラグメントエラー

原因: プロキシまたはネットワークの不安定性。

解決:

1. プログレッシブフォーマット (非 m3u8) で再試行
2. より安定したプロキシ/ノードに切り替え
3. ダウンロード中に 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	✓	✓	✓	✓	✓

HLS ストリームダウンロード (m3u8)

Mux、Vimeo、およびその他の HLS ベースのサービスなどのストリーミングプラットフォームの場合は、ffmpeg をプライマリツールとして使用してください。これらのストリームは、多くの場合、yt-dlp が正しく処理できない認証ヘッダーを必要とします。

HLS ストリームの識別

HLS ストリームは .m3u8 プレイリストファイルを使用します:

• マスタープレイリスト: 複数の品質オプションをリスト表示
• レンディションプレイリスト: 実際のビデオ/オーディオセグメント URL を含む

ダウンロードワークフロー

ステップ 1: ストリーム URL を取得

ビデオソースから m3u8 URL を取得してください。保護されたストリームの場合:

1. ブラウザ DevTools → ネットワークタブを開く
2. ビデオを再生
3. 「m3u8」でフィルタリングしてプレイリスト URL を探す
4. レンディション URL をコピー (通常は「rendition.m3u8」などの品質情報を含む)

ステップ 2: 必要なヘッダーを特定

多くの CDN は認証ヘッダーを必要とします:

• Referer: オリジン Web サイト (例: https://maven.com/)
• Origin: Referer と同じ (CORS の場合)
• User-Agent: ブラウザの識別

ブラウザがどのヘッダーを送信するかを確認するには、ネットワークタブを確認してください。

ステップ 3: ffmpeg でダウンロード

保護されたストリームの場合は、-headers フラグで ffmpeg を使用してください:

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/path/rendition.m3u8?params" \
  -c copy -bsf:a aac_adtstoasc \
  output.mp4

主要なパラメータ:

• -headers: HTTP ヘッダーを設定 (認証に重要)
• -protocol_whitelist: HLS に必要なプロトコルを有効化
• -c copy: ストリームコピー (再エンコードなし、高速)
• -bsf:a aac_adtstoasc: AAC オーディオ互換性を修正

一般的なヘッダーパターン:

# 単一ヘッダー
-headers "Referer: https://example.com/"

# 複数ヘッダー
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."

# 代替構文
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'

別個のオーディオ/ビデオストリーム処理

プラットフォーム (Mux など) はオーディオとビデオを別に配信します:

1. オーディオストリームをダウンロード:

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/audio/rendition.m3u8" \
  -c copy audio.m4a

2. ビデオストリームをダウンロード:

ffmpeg -headers "Referer: https://example.com/" \
  -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
  -i "https://cdn.example.com/video/rendition.m3u8" \
  -c copy video.mp4

3. ストリームをマージ:

ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

HLS ダウンロードのトラブルシューティング

403 Forbidden エラー

原因: 認証ヘッダーが不足しているか正しくない。

解決:

1. Referer ヘッダーがビデオソース Web サイトと一致することを確認
2. 追加のヘッダー (Origin、User-Agent) が必要かどうかを確認
3. m3u8 URL にブラウザの全てのクエリパラメータが含まれていることを確認

yt-dlp が Cookie 抽出でスタック

症状: Extracting cookies from chrome が無期限にハング。

解決: HLS ストリームについては yt-dlp の代わりに ffmpeg を直接使用してください。

プロトコルがホワイトリストにない

エラー: Protocol 'https' not on whitelist 'file,crypto,data'

解決: -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy を追加してください

空のセグメントまたはストリームなし

原因: m3u8 URL の署名が期限切れ。

解決:

1. ブラウザ DevTools から新しい URL を取得
2. URL を取得した直後にダウンロード
3. 更新された署名パラメータを持つレンディション URL を探す

パフォーマンスヒント

• HLS ダウンロードは通常、リアルタイムの 10-15 倍の速度で実行
• -c copy を使用した再エンコードなし (最速)
• リアルタイム進捗表示でダウンロードを監視
• ディレクトリの混乱を避けるために絶対パスを使用

参考文献

• PO トークンセットアップ: 詳細なインストールとトラブルシューティングについては references/po-token-setup.md を参照してください
• yt-dlp ドキュメンテーション: https://github.com/yt-dlp/yt-dlp
• フォーマット選択ガイド: https://github.com/yt-dlp/yt-dlp#format-selection

次のステップ: ダウンロードされたオーディオ/ビデオを文字起こし

ダウンロード後、ユーザーの目標がビデオからテキストを取得することに関わる場合 (文字起こし、字幕、会議ノート など)、プロアクティブに提案してください:

ダウンロード完了: [filename]

ビデオの音声内容をテキストとして必要な場合は、文字起こしできます。

オプション:
A) /asr-transcribe-to-text で文字起こし (音声認識に推奨)
B) 不要です — ビデオファイルだけが必要でした