YouTube ダウンローダー
概要
yt-dlpとffmpegを使用して、YouTubeやHLSストリーミングプラットフォーム(Mux、Vimeoなど)からの動画・音声ダウンロードを信頼性高く実現します。このスキルは以下のワークフローを提供します:
- POトークンプロバイダーまたはブラウザクッキーを使用したYouTubeダウンロード(最大4K)
- 認証ヘッダーを使用したHLSストリームダウンロード
- 保護されたコンテンツの処理と一般的なダウンロード失敗のトラブルシューティング
このスキルを使用するタイミング
このスキルは、ユーザーが以下のような場合に呼び出すべきです:
- 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アクセスのために、POトークンプロバイダープラグインをyt-dlpのPython環境にインストールします:
# yt-dlpのPythonパスを確認
head -1 $(which yt-dlp)
# プラグインをインストール(yt-dlpのバージョンに合わせてパスを調整)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/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
代替手段: ブラウザクッキー方式
POトークンプロバイダーのセットアップが難しい場合は、ブラウザクッキーを使用します:
# 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にログインしている必要があります。
一般的なタスク
音声のみのダウンロード
音声を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参照)
- またはブラウザクッキー方式を使用
nsig抽出失敗
症状:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解決策:
- yt-dlpを最新バージョンに更新
- POトークンプロバイダーをインストール
- それでも失敗する場合、Androidクライアントを使用:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
ダウンロードが遅い、またはネットワークエラー
中国内や制限的なプロキシの背後にいるユーザーの場合:
- ネットワーク状況によりダウンロードが遅くなる可能性があります
- 完了まで十分な時間を確保してください
- yt-dlpは一時的な失敗時に自動的に再試行します
POトークン警告(無害)
WARNING: android client https formats require a GVS PO Token
対応: ダウンロードが成功した場合は無視してください。これは、AndroidクライアントがPOトークンなしでは限られたフォーマットアクセスしか持たないことを示します。
バンドルスクリプトリファレンス
scripts/download_video.py
デフォルトでAndroidクライアント回避策を適用する便利なラッパー:
基本的な使い方:
scripts/download_video.py "VIDEO_URL"
引数:
url- YouTube動画URL(必須)-o, --output-dir- 出力ディレクトリ-f, --format- フォーマット指定-a, --audio-only- 音声をMP3として抽出-F, --list-formats- 利用可能なフォーマットを一覧表示--no-android-client- Androidクライアント回避策を無効化
注意: このスクリプトはAndroidクライアントを使用します(POトークンなしでは360pのみ)。高画質の場合は、POトークンプロバイダーと共にyt-dlpを直接使用してください。
品質期待値
| セットアップ | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| セットアップなし(デフォルト) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Androidクライアントのみ | ✓ | ✗ | ✗ | ✗ | ✗ |
| POトークンプロバイダー | ✓ | ✓ | ✓ | ✓ | ✓ |
| ブラウザクッキー | ✓ | ✓ | ✓ | ✓ | ✓ |
HLSストリームダウンロード(m3u8)
Mux、Vimeo、その他のHLSベースのサービスのようなストリーミングプラットフォームでは、主要なツールとしてffmpegを使用します。これらのストリームはyt-dlpが正しく処理できない認証ヘッダーを必要とすることがよくあります。
HLSストリームの識別
HLSストリームは .m3u8 プレイリストファイルを使用します:
- マスタープレイリスト: 複数の画質オプションを一覧表示
- レンディションプレイリスト: 実際の動画/音声セグメントのURLを含む
ダウンロードワークフロー
ステップ1: ストリームURLを取得
動画ソースからm3u8 URLを取得します。保護されたストリームの場合:
- ブラウザのDevTools → Networkタブを開く
- 動画を再生
- 「m3u8」でフィルタリングしてプレイリストURLを見つける
- レンディションURLをコピーする(通常「rendition.m3u8」のように品質情報を含む)
ステップ2: 必要なヘッダーを特定
多くのCDNは認証ヘッダーを必要とします:
- Referer: 元のWebサイト(例:
https://maven.com/) - Origin: CORSのためにRefererと同じ
- User-Agent: ブラウザの識別情報
Networkタブでブラウザが送信するヘッダーを確認します。
ステップ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など)は音声と動画を別々に配信します:
- 音声ストリームをダウンロード:
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
- 動画ストリームをダウンロード:
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
- ストリームを結合:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
HLSダウンロードのトラブルシューティング
403 Forbiddenエラー
原因: 認証ヘッダーが欠落しているか、間違っています。
解決策:
- Refererヘッダーが動画ソースのWebサイトと一致しているか確認
- 追加のヘッダー(Origin、User-Agent)が必要かどうか確認
- m3u8 URLにブラウザからのすべてのクエリパラメータが含まれていることを確認
yt-dlpがクッキー抽出で停止
症状: 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内の署名が期限切れ。
解決策:
- ブラウザのDevToolsから新しいURLを取得
- URL取得後すぐにダウンロード
- 更新された署名パラメータを持つレンディション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