yt-dlp-direct

yt-dlp Direct

このスキルは、次の1つのことだけを担当します。

• ローカルにインストール済みの yt-dlp CLI を直接使って、オンライン動画や音声のダウンロードタスクを処理します

担当しないこと：

• 著作権コンプライアンスポリシーの説明
• プラットフォームの DRM の回避
• ダウンロードの代わりにブラウザーで手動録画すること
• yt-dlp の再インストール

一言で言えば、ユーザーがダウンロード、音声の抽出、字幕の取得、フォーマットの確認、プレイリストの取得を求めている場合は、まず yt-dlp を直接使い、先に大量のスクリプトを書かないでください。

使用する場面

適用する場面：

• ユーザーが「yt-dlp でこの動画をダウンロードして」と言っている
• ユーザーが「mp3 / m4a に変換して」と言っている
• ユーザーが「字幕も一緒にダウンロードして」と言っている
• ユーザーが「まず利用可能なフォーマットを確認して」と言っている
• ユーザーが「プレイリスト全体 / チャンネル / 検索結果をダウンロードして」と言っている
• ユーザーが「このサイトは yt-dlp で使える？」と言っている

適用しない場面：

• ユーザーが yt-dlp とは何かを知りたいだけの場合
• ユーザーが DRM や保護されたストリームの解除を求めている場合
• ユーザーが複雑なメディア編集を求めており、本来使うべきツールが ffmpeg の場合

前提条件

開始前に、次の点を確認してください。

1. yt-dlp が PATH にある
2. 現在のディレクトリまたは出力先ディレクトリに書き込み可能である
3. 動画と音声の結合、トランスコード、サムネイルの埋め込みを行う場合は、ffmpeg がインストール済みであることが望ましい

優先して確認します。

which yt-dlp
yt-dlp --version

ffmpeg が利用可能かどうかを判断する必要がある場合は、次も確認します。

ffmpeg -version
ffprobe -version

作業ルール

• デフォルトでは、まず読み取り専用の調査を行い、その後に実際のダウンロードを開始します
• フォーマットが不明な場合は、まず -F を使います
• ユーザーが保存先のルールを指定していない場合は、安全な出力テンプレートを優先します
• プレイリストについては、デフォルトで件数と容量のリスクを伝えます
• ログイン状態が必要な場合は、--cookies-from-browser を優先します
• YouTube の対応をより安定させるには、JavaScript runtime / ejs の依存関係も忘れずに確認します
• 大量のファイルを勝手に上書きしないでください。必要に応じて出力先を明示的に指定します

基本的なワークフロー

1. まず確認する

リンクが extractor に認識されるかどうかを確認します。

yt-dlp --simulate --print "%(title)s" "<url>"

ダウンロードせずにメタデータだけを確認する場合：

yt-dlp --dump-single-json "<url>"

2. ダウンロード前にフォーマットを確認する

ユーザーが画質、エンコード、音声トラックを指定する場合は、まずフォーマットを確認します。

yt-dlp -F "<url>"

ユーザーから明確な指定がない場合は、通常、次を優先します。

yt-dlp -f "bv*+ba/b" "<url>"

これが現在の yt-dlp のデフォルトの優先方針でもあります。

3. 単一動画を安全にダウンロードする

デフォルトでは、出力テンプレートを付けることをおすすめします。

yt-dlp -o "%(title)s [%(id)s].%(ext)s" "<url>"

出力先ディレクトリを固定する場合：

yt-dlp -P "/target/dir" -o "%(title)s [%(id)s].%(ext)s" "<url>"

4. 音声を抽出する

ユーザーが音声を求めている場合は、次を優先します。

yt-dlp -x --audio-format mp3 "<url>"

高音質の音声フォーマットをより確実に保持する場合：

yt-dlp -x --audio-format m4a "<url>"

5. 字幕をダウンロードする

動画をダウンロードせず、字幕だけをダウンロードします。

yt-dlp --write-subs --write-auto-subs --skip-download "<url>"

ユーザーが特定の言語だけを必要としている場合：

yt-dlp --write-subs --sub-langs "en,zh-Hans,zh-Hant" --skip-download "<url>"

6. プレイリストとチャンネル

ユーザーからプレイリストが提示された場合は、まず規模について伝えます。よく使うコマンド：

yt-dlp --flat-playlist "<playlist-url>"
yt-dlp -I 1:10 "<playlist-url>"
yt-dlp -o "%(playlist_index)s - %(title)s [%(id)s].%(ext)s" "<playlist-url>"

まず --flat-playlist で項目を確認し、その後、すべてダウンロードするかどうかを決めます。

7. 検索のショートカット

ユーザーが直接リンクではなくキーワードだけを提示した場合は、検索用のプレフィックスを使えます。

yt-dlp "ytsearch5:Claude Code skills"

結果を取得するだけで、すぐにはダウンロードしない場合：

yt-dlp --simulate --print "%(title)s | %(webpage_url)s" "ytsearch5:Claude Code skills"

認証と Cookie

多くのサイトやプライベートコンテンツでは、ログイン状態が必要です。次の順で優先します。

1. --cookies-from-browser
2. --cookies <file>
3. ユーザー名 / パスワードまたは netrc

よく使う方法：

yt-dlp --cookies-from-browser chrome "<url>"
yt-dlp --cookies-from-browser safari "<url>"
yt-dlp --cookies cookies.txt "<url>"

サイトがブラウザーフィンガープリントや TLS のシミュレーションを要求する場合は、次を検討できます。

yt-dlp --impersonate chrome "<url>"

出力テンプレート

デフォルトでおすすめするテンプレート：

%(title)s [%(id)s].%(ext)s

プレイリストでよく使うもの：

%(playlist_index)s - %(title)s [%(id)s].%(ext)s

アップロード者ごとに整理する場合：

%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s

フォーマットと後処理に関する注意

• 音声と動画の結合、高度なトランスコード、サムネイルの埋め込みには、通常 ffmpeg が必要です
• -x は音声を抽出するものであり、音声トラックをそのままコピーするものではありません
• コンテナやエンコードを制御する場合は、-f、-S、--remux-video、--recode-video を明示することを優先します

よくある例：

yt-dlp -S "res:1080,ext:mp4:m4a" "<url>"
yt-dlp --remux-video mp4 "<url>"
yt-dlp --embed-thumbnail --add-metadata "<url>"

対応サイト

yt-dlp は多くのサイトに対応していますが、「一覧に載っている」からといって、今日必ず使えるとは限りません。

確認する順序：

1. まず --simulate を試します
2. 次に、エラーがログイン、地域、フォーマット、サイトの変更のどれに関するものか確認します
3. extractor 名を確認する必要がある場合は、対応サイトの一覧を確認します

必要に応じて、次を参照します。

• references/high-frequency-patterns.md

出力時の要件

実行後の返信では、最低限次の点を説明します。

1. 実行したコマンド
2. 調査に成功したのか、フォーマットを一覧表示したのか、実際にダウンロードしたのか
3. ファイルの保存先
4. 失敗した場合、原因が extractor、認証、フォーマット、ネットワーク、ローカルの依存関係のどれなのか

安全性と制限事項

• ユーザーのために DRM を回避することはしません
• 保護されたサイトから必ずダウンロードできるとは約束しません
• 大規模なプレイリストやチャンネルを取得する前に、容量と件数について注意を促します
• 既存ファイルを上書きする前に注意を促します
• Cookie を含むコマンドの出力から、機密情報を返信に転載しないでください

トラブルシューティング

YouTube またはサイトの変更

まずバージョンを確認します。

yt-dlp --version

古すぎる場合は、ユーザーに更新を促します。

フォーマットの結合に関する問題

まず次を確認します。

ffmpeg -version

ログイン必須のコンテンツ

まず次を試します。

yt-dlp --cookies-from-browser <browser> "<url>"

extractor は動作するがダウンロードに失敗する

まず詳細ログを有効にします。

yt-dlp -v "<url>"

大規模なプレイリストのリスク

まず次を使います。

yt-dlp --flat-playlist "<url>"

参考資料

• よく使うコマンド：references/high-frequency-patterns.md を参照してください
• サイトの対応状況：references/supported-sites-notes.md を参照してください