基本のダウンロード
オプションを何も付けなければ、yt-dlp は結合できる中で最良の組み合わせを選び、タイトルからファイル名を付けます。意外なほど多くの場合、これが正解のコマンドです。
yt-dlp URL
大きなものを落とす前に、実際に何が提供されているかを見ておく価値があります。これはフォーマット一覧を表示して、何もダウンロードせずに終了します。
yt-dlp -F URL
その表の左の列がフォーマット id で、あとから直接指定できます。id を二つ + でつなぐと「両方落として結合する」という意味になります。
yt-dlp -f 137+140 URL
画質とフォーマットの選択
べた書きのフォーマット id は、サイトがエンコードの構成を変えた途端に壊れます。セレクター式のほうが長持ちします。ほしい性質を指定して、最良の一致を探すのは yt-dlp に任せる書き方です。
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]" URL
読み方はこうです。高さ 1080 以下で最良の映像ストリームと最良の音声、その組み合わせが存在しなければ高さ 1080 以下で最良の単一ファイル。スラッシュのあとのこの代替こそが、プログレッシブなストリームしか公開していないサイトでコマンドが失敗するのを防ぎます。
二つのストリームを結合すると、yt-dlp はコンテナを選ばなければなりません。MP4 はどこでも再生でき、MKV は何でも受け入れます。字幕やチャプターが絡んでくると後者が効いてきます。
yt-dlp -f "bv*+ba" --merge-output-format mp4 URL
厳しい上限ではなく好みを表したいなら、絞り込みではなく並べ替えを使います。これは 1080p と MP4 を優先しますが、どちらもないときでも何かはダウンロードします。
yt-dlp -S "res:1080,ext:mp4" URL
音声と MP3
音声の抽出には ffmpeg が必要です。入れたばかりの環境で下のコマンドが失敗する理由は、圧倒的にこれです。
yt-dlp -x --audio-format mp3 URL
ジャケット画像とタグの追加はフラグ二つで済み、結果を「名前のないファイルの入ったフォルダ」ではなく音楽ライブラリで使えるものにしてくれます。
yt-dlp -x --audio-format mp3 --audio-quality 0 --embed-thumbnail --embed-metadata URL
--audio-quality 0 は「品質ゼロ」ではなく、可変ビットレートの最良設定という意味です。固定ビットレートが必要なら数値で指定します: --audio-quality 320K。
元がすでに AAC や Opus なら、MP3 に変換するのは再エンコードであり、意味なく品質を落とすだけです。元のまま保つほうが速くて良い結果になります。
yt-dlp -x --audio-format best URL
字幕
埋め込んだ字幕はファイルと一緒に移動します。別ファイルの .srt は編集や他のツールへの受け渡しが楽です。
yt-dlp --embed-subs --sub-langs en URL yt-dlp --write-subs --sub-langs en,vi --convert-subs srt URL
自動生成の字幕は別のスイッチです。付けないと、人手の字幕がない動画では何も出力されず、エラーも出ません。
yt-dlp --write-auto-subs --sub-langs en --convert-subs srt --skip-download URL
プレイリストとチャンネル
YouTube の URL は動画とプレイリストの両方に属していることが多く、yt-dlp はどちらのつもりかを推測することになります。明示してください。
yt-dlp --no-playlist URL yt-dlp --yes-playlist URL
長いものを扱うなら、ここにある他のどのオプションよりもアーカイブファイルが重要です。何をダウンロード済みかを記録するので、やり直しても最初からではなく止まったところから続きます。
yt-dlp --yes-playlist -i \ --download-archive archive.txt \ -o "%(playlist_index)02d - %(title)s.%(ext)s" \ URL
-i と組み合わせれば、地域制限や削除された動画が一本あっても残り二百本を巻き込んで止まることはありません。全部ではなく一部だけ取るなら、-I が範囲とリストを受け取ります: -I 1:10、-I "1,3,7-10"。
切り出し、チャプター、スポンサー区間
動画全体ではなく一部だけをダウンロードできます。先頭のアスタリスクはチャプター名ではなくタイムスタンプであることを表し、引用符は必須です。裸の * は bash があなたのファイル名に展開してしまいます。
yt-dlp --download-sections "*00:01:30-00:03:00" URL
SponsorBlock はコミュニティが投稿したマーカーを使って、区間をまるごと切り落とすか、自分で飛ばせるチャプターとして残すかを選べます。
yt-dlp --sponsorblock-remove default URL yt-dlp --sponsorblock-mark all --embed-chapters URL
ファイル名とフォルダ
出力テンプレートが両方を決めます。スラッシュはディレクトリを作るので、テンプレート一つでアーカイブ全体の構成を組めます。
yt-dlp -o "%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s.%(ext)s" URL
タイトルには、ファイルシステムによっては受け付けない文字がしばしば入っています。--restrict-filenames はすべてを素の ASCII に落とします。マシン間を移動させるものなら、それだけの価値があります。
Windows の .bat ファイルでは % をすべて二重にする必要があります（%%(title)s）。さもないとバッチの解釈側が、yt-dlp に届く前にテンプレートを食べてしまいます。.bat をダウンロードするときは、ジェネレーターがこれをやっておきます。
実際に遭遇するエラー
ffmpeg not found
結合・変換・埋め込み・切り出しをするものはすべて、PATH の通った ffmpeg を必要とします。インストールしてから ffmpeg -version で確認してください。
Sign in to confirm you are not a bot
まず --impersonate chrome、次に --cookies-from-browser を試してください。どちらも駄目なら yt-dlp を更新します。この判定はとくに頻繁に変わり、修正はたいてい数日のうちにリリースされます。
Unable to extract player response
ほぼ確実に yt-dlp が古いだけです。他を触る前にまず更新してください: yt-dlp -U、パッケージマネージャーで入れたならそちらで。
Requested format is not available
セレクターが何にも一致しませんでした。-F で存在するものを確認し、厳しい絞り込みよりも並べ替え（-S）を選べば、代替が常に残ります。
HTTP Error 403
その URL は別のセッションか別の地域向けに署名されています。新しい Cookie で実行し直すか、--impersonate chrome を足すか、--geo-bypass を試してください。
yt-dlp を最新に保つ
報告される不具合は、どのフラグよりも更新によって直る数のほうが多いです。単体のバイナリを入れた場合:
yt-dlp -U
パッケージマネージャー経由で入れたなら、入れたのと同じ方法で更新してください。-U は拒否しますが、それが正しい振る舞いです。