youtube-downloader

YouTube Downloader

概要

yt-dlp と ffmpeg を使用して、YouTube や HLS ストリーミングプラットフォーム（Mux、Vimeo など）から動画や音声を安定してダウンロードできます。このスキルでは、以下のワークフローを提供します。

• 取得可能な画質での YouTube ダウンロード。必要に応じて、PO Token の利用や、認証済み Cookie による復旧にも対応します。
• 認証ヘッダーを使用した HLS ストリームのダウンロード
• 保護されたコンテンツへの対応と、一般的なダウンロード失敗のトラブルシューティング

目的の切り分け：ファイルかテキストか（最初に確認）

ダウンロードを始める前に、リクエストを分類してください。

• ユーザーが動画／音声ファイルそのものを求めている（保存、編集、オフライン視聴など）→ 以下のダウンロード手順を変更せずに続行します。
• ユーザーが発話内容のテキストを求めている（文字起こし、字幕、議事録、アーカイブ、「何と言ったか」など）→ まず references/text-first.md に従ってください。既存のアーカイブ済み文字起こし → プラットフォームの文字起こし API → yt-dlp の字幕のみの取得 → 認証済み音声トラックと ASR の順に進めます。テキストを取得するだけの目的で、動画全体をダウンロードしないでください。

テキスト優先の手順は、ファイルのリクエストを妨げるものではありません。ユーザーがファイルを求めている場合は、以下の変更されていない手順でダウンロードしてください。

技術に詳しくないユーザー向けの対応（デフォルト）

ユーザーは技術に詳しくないものと想定してください。コマンドの実行を依頼せず、すべて自分で実行して、進捗をわかりやすい言葉で伝えてください。ユーザーから尋ねられない限り、ツールについて言及しないでください。

デフォルトの手順：

1. URL が提示されていない場合は、URL を尋ねます。
2. 動画のメタデータ（タイトル／投稿者／再生時間／サムネイル）を取得し、ユーザーの意図に合っていることを確認します。
   • yt-dlp が「ボットではないことを確認してください」というメッセージでブロックされた場合は、YouTube oEmbed に切り替えてタイトル／投稿者／サムネイルを取得します（再生時間は不明な場合があります）。
3. 簡単な選択肢を提示します（動画か音声のみか、画質、字幕、保存場所）。
4. ユーザーから指定がなければ、適切なデフォルトで進めます。
   • 最高画質で動画をダウンロード
   • MP4 に結合した出力
   • 動画は 1 本のみ（再生リストは対象外）
5. ダウンロードし、最終ファイルのパス、ファイルサイズ、解像度（動画の場合）を伝えます。

ユーザーにわかりやすい表現で選択肢を提示します。

• 「最高画質で動画をダウンロード（デフォルト）」
• 「音声のみをダウンロード（MP3）」
• 「画質を選択：1080p ／ 720p ／ 480p ／ 360p」
• 「字幕を付ける（利用可能な場合）」
• 「ダウンロードフォルダーに保存（デフォルト）、または別のフォルダーを指定」

利用可能な場合は、サムネイルを必ず表示します。

• メタデータにサムネイルの URL が含まれている場合は、Markdown の画像構文 ![Thumbnail](URL) を使って表示します。

追加作業を行う前に確認します。

• 再生リストのダウンロードは容量が大きくなる場合があるため、確認します。
• 依存関係が不足している場合、そのインストールやアップグレードを行う前に確認します。
• ブラウザーの Cookie を抽出する前に確認します。
• Cookie を使う場合、ユーザー向けの応答では Cookie の数や生の Cookie 情報には触れません。「Chrome のログインセッションを使用しました」と伝えます。
• PO Token ヘルパーの設定は、トークン診断を明示的に行った場合、またはユーザーから依頼された場合に限り、既存のインストール／サービスの権限の範囲内で行います。その権限がすでにある場合は、復旧を実行してダウンロードを再開します。権限がない場合は、不足している許可だけを求めます。代替策として Docker をインストールしないでください。適切な場合は、許可されたブラウザープロバイダーを使用してください。

法律と安全に関する注意（簡潔に）：

• ユーザーにコンテンツをダウンロードする権利または許可がある場合に限り、続行してください。

応答テンプレート（コマンドは使わず、わかりやすい言葉で）：

![Thumbnail](THUMBNAIL_URL)

Title: …
Channel: …
Duration: …

I can help you:
1) Download the video (best quality, MP4)
2) Download audio only (MP3)
3) Pick a specific quality (1080p/720p/480p/360p)
4) Include subtitles (if available)

Where should I save it? (Default: Downloads folder)

ユーザーが「ダウンロードするだけでいい」と言った場合：

• デフォルト設定で進め、ダウンロード完了後に伝えます。
  • ブロックされた場合は、SOP に従って実際の診断結果を分類し、許可された適切な復旧を実行します。

安定したダウンロードの SOP（内部用）

失敗を再試行する前に、ダウンロード SOP を読んでください。まず、現在の yt-dlp のデフォルトクライアントと既存のネットワーク設定を使用します。ダウンロードを開始するためだけにプロバイダーを必須としたり、Android に切り替えたり、ブラウザーの Cookie を抽出したりしないでください。

エージェント実行チェックリスト（内部用）

• メタデータを取得するには、scripts/download_video.py URL --info を実行します。プロバイダーは起動しません。抽出に失敗した場合、oEmbed によるフォールバックで取得できる項目は限られています。
• サムネイルが利用可能な場合は、表示します。指定されたファイル／音声、品質、字幕、保存先を使用し、すでに指定または暗黙に示されている項目にはデフォルトを使用します。
• 通常のダウンロードを最初に実行します。yt-dlp で必要な場合は、Node ランタイムがインストールされている状態で --js-runtimes node を指定します。ランタイムのインストールにも、引き続き依存関係の承認が必要です。
• 失敗した場合は、実際のエラーと -F の出力を確認します。指定した形式がないこと、画像のみの出力、403、または低解像度だけでは、トークンの問題とは判断できません。
• 失敗したリクエストで PO Token がない、または必要だと明示された場合は、プロバイダーのセットアップを確認します。既存のセットアップ承認の範囲内で --auto-po-token を実行し、元のダウンロードを完了します。ユーザーにコマンドを提示するだけで終わらせないでください。このオプションはまずネイティブの方法を試し、その後、制限付きのプロバイダー再試行と WPC による復旧を許可します。
• どちらかの Cookie オプションを使用する前に、ブラウザーの Cookie 使用許可を求めます。再試行中は、許可された Cookie セッションと互換性のあるクライアントを維持します。
• 403 またはフラグメントの単発の失敗では、ラッパーはプログレッシブ形式で品質プリセットを一度再試行できます。結果の解像度を確認してください。フォールバックでは品質が低下する場合があります。カスタム形式と音声のみのリクエストでは、明示された選択を維持します。
• ffprobe で最終ファイルを確認し、そのパス、サイズ、実際の解像度または音声のプロパティを報告します。プロバイダーの稼働状況や形式一覧を確認しただけでは、ダウンロードは完了していません。

このスキルを使用する場面

次の場合に、このスキルを呼び出してください。

• YouTube 動画またはプレイリストのダウンロードを依頼された場合
• YouTube 動画から音声を抽出したい場合
• yt-dlp のダウンロード失敗や、利用可能な形式の制限に困っている場合
• 形式の選択や品質オプションについてサポートが必要な場合
• 利用可能な形式が低品質（360p）のものだけだと報告された場合
• 特定の品質（1080p、4K など）で YouTube コンテンツをダウンロードしたい場合
• 互換性を高めるため、ダウンロードした WebM 動画を MP4 形式に変換する必要がある場合
• Mux、Vimeo などのプラットフォームや、その他のストリーミングサービスから HLS ストリーム（m3u8）をダウンロードしたい場合
• 認証ヘッダーが必要な保護されたストリームをダウンロードする必要がある場合

前提条件

1. yt-dlp のインストールを確認する（自分で実行）

which yt-dlp
yt-dlp --version

インストールされていない場合、または現在の抽出に関する診断で更新が必要な場合は、不足しているインストール／アップグレードの承認を取得してから、既存のインストール所有者を使用します。

brew upgrade yt-dlp  # macOS
# or
pip install --upgrade yt-dlp  # Cross-platform

インストールされているディストリビューションで必要な JavaScript ランタイムとチャレンジソルバーについては、最新の EJS セットアップガイドを確認してください。Node バイナリがインストールされていても、明示的に --js-runtimes node を指定する必要がある場合があります。EJS／nsig の失敗を PO Token の失敗とみなさないでください。

2. 現在の品質へのアクセスを確認する（自分で実行）

ダウンロードする前に、利用可能な形式を確認します。

yt-dlp -F "https://youtu.be/VIDEO_ID"

一覧に表示されたメディアストリームと、要求された品質を比較します。低解像度の形式しか表示されない場合は、復旧方法を選ぶ前に、抽出／ランタイムの警告とソースの提供状況を確認してください。

高品質ダウンロードのワークフロー

ステップ 1：ネイティブのクライアント選択を試す

特定の診断結果または明示的な依頼がない限り、player_client は未設定のままにします。公式の抽出ガイドでは、トークンを必要としないクライアントを使った yt-dlp のデフォルトの試行について説明しています。利用可能な形式は、動画、アカウント、クライアント、ネットワーク、および現在の YouTube の適用状況によって異なります。

ステップ 2：ダウンロードし、必要な場合にのみ段階的に対応する

# Download best quality up to 1080p
scripts/download_video.py "VIDEO_URL" --quality 1080p

# Download best available quality
scripts/download_video.py "VIDEO_URL"

# After an explicit token requirement, with setup already authorized
scripts/download_video.py "VIDEO_URL" --auto-po-token

インストールとプロバイダー固有の復旧については、PO Token のセットアップを読み込んでください。解像度だけからプロバイダーが必要だと判断しないでください。

ステップ 3：ダウンロード品質を確認する

# Check video resolution
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 を使用する方法

認証済みアカウントが必要なコンテンツ、またはボットチェックが続く場合は、Cookie の使用許可を得た後に Cookie を使用してください。Cookie はセッションを認証するものであり、不足している PO Token の代わりにはなりません：

# 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／プロキシを使用する必要があります。
• yt-dlp の Cookie に対応したデフォルトのクライアントを維持してください。web_safari は対象を絞った再試行に限って使用します。アカウント Cookie を、Cookie に対応していない Android／iOS クライアントと組み合わせないでください。

よくあるタスク

音声のみをダウンロードする（ご自身で実行してください）

音声を 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 に変換します：

# Check if ffmpeg is installed
which ffmpeg || brew install ffmpeg  # macOS

# Convert WebM to MP4 with good quality settings
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 の解像度が維持され、最新のハードウェアでは約 6 倍のエンコード速度が得られます。

トラブルシューティング早見表

品質が低い／画像のみ／要求した形式を利用できない

-F、選択した形式の式、現在の yt-dlp／EJS／ランタイムの警告、およびソースの利用可否を確認してください。これらのメッセージには複数の原因が考えられます。抽出またはメディアのリクエストが失敗し、不足または必須の PO Token も明示されている場合に限り、プロバイダーの設定に進んでください。要求した解像度または形式 ID がないという理由だけで、プロバイダーをインストールしないでください。

ボットではないことを確認するためにログインしてください

意図したプロキシ／ネットワークが使用されていることを確認してください。認証チェックが続き、Cookie が必要な場合は、Cookie の使用許可を得て、そのセッションを保持したまま再試行してください。許可が得られない場合は、不足している許可を正確に伝えて停止してください。ブラウザー Cookie を許可なく読み取ってはいけません。

nsig／JavaScript チャレンジの失敗

インストールされている yt-dlp のバージョンと、EJS ランタイムおよびソルバーの手順を確認してください。診断された前提条件の問題を、許可された範囲内で修正してください。Android または AndroidVR は、範囲を限定した診断のために明示的に選択できますが、どちらもデフォルトの復旧方法ではなく、解決を保証するものでもありません。

403／SSL EOF／フラグメントエラー

メディアの 403 と、TLS、タイムアウト、プロキシ、プロバイダーの稼働状況に関するエラーを区別してください。一般的な 403 は、Token が必要であることの証明にはなりません。SSL／タイムアウトエラーの場合は、まずネットワーク経路を確認してください。関連する変更を加えた後に限り、再試行してください。ラッパーによるプログレッシブ形式の単一回の再試行は、品質プリセットを使用した場合の 403／フラグメントエラーに適用され、品質が低下することがあります。

ダウンロードが遅い、またはネットワークエラーが発生する

中国国内のユーザー、または制限の厳しいプロキシを使用しているユーザーの場合：

• ネットワークの状況により、ダウンロードが遅くなることがあります
• 完了まで十分な時間を確保してください
• yt-dlp は一時的な失敗時に自動で再試行します

PO Token 警告（無害）

WARNING: android client https formats require a GVS PO Token

対応：成功が確認されたダウンロードでは、未使用クライアントに関する警告を解消する必要はありません。失敗した場合は、Token の分岐を選ぶ前に、診断情報の全文と実際の形式を確認してください。

同梱スクリプトのリファレンス

scripts/download_video.py

ネイティブクライアントでのダウンロードと、範囲を限定した診断後の復旧には、このラッパーを使用してください。プロバイダーのインストールや起動、Cookie の読み込みはデフォルトでは行いません。ご自身で実行し、確認済みのファイルを報告してください。

基本的な使い方：

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 - 明示的なトークン不足／必須の診断に失敗した後、プロバイダーのセットアップを許可します。まずネイティブクライアントを試し、その後 Docker bgutil またはブラウザー WPC を試します
• --no-auto-po-token - プロバイダーのセットアップを無効にします（デフォルト）。インストール済みの yt-dlp プラグインは無効になりません
• --proxy - yt-dlp および PO Token プロバイダー用のプロキシ URL（例：http://127.0.0.1:1082）
• --wpc-browser-path - WPC プロバイダー用のブラウザー実行ファイルのパス
• -F, --list-formats - 利用可能なフォーマットを一覧表示
• --merge-format - 出力コンテナーを結合（例：mp4、mkv）。デフォルト：mp4
• --playlist - プレイリストのダウンロードを許可（デフォルトでは単一動画のみ）
• --info - タイトル／アップロード者／再生時間／サムネイルを表示して終了
• --no-android-client - 互換性維持のためのオプションです。ラッパーはすでにネイティブクライアントの選択を変更しません
• --js-runtimes - インストール済みのランタイムを yt-dlp に渡します（例：node または node:/path/to/node）

品質に関する注意事項

プロバイダー、クライアント、Cookie の組み合わせに基づいて解像度を保証しないでください。希望する品質をリクエストし、利用可能なフォーマットを確認して、実際にダウンロードされたファイルを検証してください。新たなプロバイダーのセットアップなしで高解像度のダウンロードに成功しても、証明されるのはその入力と環境のみです。インストール済みのプラグインや設定が影響している可能性があります。ソースに存在しない解像度をプロバイダーが作り出すことはできません。

HLS ストリームのダウンロード（m3u8）

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

HLS ストリームの特定

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

• マスタープレイリスト：複数の品質オプションを一覧表示します
• レンディションプレイリスト：実際の動画／音声セグメント URL を含みます

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

ステップ 1：ストリーム URL の取得

動画ソースから m3u8 URL を取得します。保護されたストリームの場合：

1. ブラウザーの DevTools → Network タブを開きます
2. 動画を再生します
3. "m3u8" で絞り込み、プレイリスト URL を探します
4. レンディション URL（通常は "rendition.m3u8" のような品質情報を含みます）をコピーします

ステップ 2：必要なヘッダーの特定

多くの CDN では認証ヘッダーが必要です。

• Referer：オリジンのウェブサイト（例：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 音声の互換性を修正します

一般的なヘッダーのパターン：

# Single header
-headers "Referer: https://example.com/"

# Multiple headers
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."

# Alternative syntax
-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 ヘッダーが動画の配信元ウェブサイトと一致していることを確認します
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. 署名パラメーターが更新された rendition URL を探します

パフォーマンスのヒント

• HLS のダウンロードは通常、実時間の 10～15 倍の速度で実行されます
• -c copy を使うと再エンコードされません（最速）
• リアルタイムの進捗表示でダウンロード状況を確認します
• ディレクトリの混乱を避けるため、出力には絶対パスを使用します

参考資料

• PO Token の設定：詳しいインストール手順とトラブルシューティングについては、references/po-token-setup.md を参照してください
• 内部 SOP：references/internal-sop.md — 別の原因に見える yt-dlp のよくある失敗をまとめた短いリストです（zsh で URL を引用符で囲んでいない、プロキシが PO Token プロバイダーに接続できないなど）。理由がはっきりしないダウンロードの失敗が起きた場合は、まずこれを読んでください
• yt-dlp のドキュメント：https://github.com/yt-dlp/yt-dlp
• フォーマット選択ガイド：https://github.com/yt-dlp/yt-dlp#format-selection

次のステップ：動画からテキストを取得する

状況に応じて、2 つの方法があります。

• ユーザーの目的がテキストのみで、まだ何もダウンロードしていない場合：テキストを取得するためだけに動画をダウンロードしないでください。references/text-first.md のテキスト優先の手順（既存のアーカイブ済み文字起こし → プラットフォームの文字起こし API → yt-dlp の字幕のみの取得 → 許可された音声トラック + ASR）に従ってください。
• ユーザーがすでにファイルをダウンロードしていて、テキストも必要としている場合：既知のソース識別情報を使って、既存の文字起こしと元の字幕も確認します。使えるテキストが見つからない場合は、再度ダウンロードせず、レベル L4 でローカルファイルを再利用します。以下を積極的に提案してください。

Download complete: [filename]

If you need the spoken content as text, I can transcribe it for you.

Options:
A) Transcribe with /daymade-audio:asr-transcribe-to-text (Recommended for speech-to-text)
B) No thanks — I just needed the video file