yt-dlp Expert

概要

yt-dlpは、youtube-dlから派生した強力なコマンドラインダウンローダーです。YouTube、ニコニコ動画、Twitter/X、TikTok、Instagram、Vimeo、Twitch、bilibiliなど1000以上のサイトから動画・音声・字幕をダウンロードできます。

主な特徴：

• 高速ダウンロード（並列接続、フラグメント処理）
• 柔軟なフォーマット選択（解像度、コーデック、ファイルサイズ）
• 字幕取得（自動生成・手動、多言語対応）
• メタデータ抽出（JSON出力、サムネイル）
• プレイリスト・チャンネル一括処理
• Cookie認証対応（メンバー限定・年齢制限コンテンツ）

このスキルを使うタイミング

以下のような場面で発動します：

発動トリガー例：

• 「YouTube動画をダウンロードしたい」
• 「動画から音声だけ抽出したい」
• 「字幕をダウンロードしたい」
• 「プレイリストを一括ダウンロードしたい」
• 「動画のメタデータを取得したい」
• 「yt-dlpのコマンドを教えて」
• 「最高画質でダウンロードするには？」
• 「Twitter/Xの動画を保存したい」

インストール

macOS (Homebrew)

brew install yt-dlp

Linux / macOS (pip)

pip install yt-dlp
# または
pip3 install yt-dlp

Windows (winget)

winget install yt-dlp

Windows (Scoop)

scoop install yt-dlp

直接ダウンロード

# Linux/macOS
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o ~/.local/bin/yt-dlp
chmod +x ~/.local/bin/yt-dlp

# Windows
# GitHubリリースページからyt-dlp.exeをダウンロード

更新

yt-dlp -U

ffmpegのインストール（推奨）

音声抽出や動画結合にはffmpegが必要です：

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (winget)
winget install ffmpeg

基本操作

単一動画のダウンロード

# 最もシンプルな使い方
yt-dlp "https://www.youtube.com/watch?v=VIDEO_ID"

# 保存先を指定
yt-dlp -P ~/Downloads "URL"

フォーマット確認

# 利用可能なフォーマット一覧を表示
yt-dlp -F "URL"

出力例：

ID      EXT   RESOLUTION FPS CH │   FILESIZE   TBR PROTO │ VCODEC          VBR ACODEC      ABR
─────────────────────────────────────────────────────────────────────────────────────────────
sb2     mhtml 48x27        0    │                  mhtml │ images
...
140     m4a   audio only       2 │   3.51MiB   130k https │ audio only          mp4a.40.2  130k
251     webm  audio only       2 │   3.75MiB   139k https │ audio only          opus       139k
136     mp4   1280x720    30    │   7.87MiB   292k https │ avc1.64001f    292k video only
137     mp4   1920x1080   30    │  14.25MiB   529k https │ avc1.640028    529k video only

フォーマット選択

# 特定のフォーマットIDを指定
yt-dlp -f 137+140 "URL"

# 最高画質（映像+音声を自動結合）
yt-dlp -f "bestvideo+bestaudio/best" "URL"

# 最高画質（MP4形式限定）
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" "URL"

# 解像度指定（1080p以下で最高）
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best[height<=1080]" "URL"

# 720p固定
yt-dlp -f "bestvideo[height=720]+bestaudio" "URL"

# ファイルサイズ制限（100MB以下）
yt-dlp -f "best[filesize<100M]" "URL"

音声のみ抽出

# 音声のみダウンロード（最高音質）
yt-dlp -f "bestaudio" "URL"

# MP3に変換（ffmpeg必要）
yt-dlp -x --audio-format mp3 "URL"

# 音質指定（0=最高、9=最低）
yt-dlp -x --audio-format mp3 --audio-quality 0 "URL"

# M4A形式
yt-dlp -x --audio-format m4a "URL"

# FLAC形式（ロスレス）
yt-dlp -x --audio-format flac "URL"

# Opus形式（高効率）
yt-dlp -x --audio-format opus "URL"

字幕のダウンロード

利用可能な字幕を確認

yt-dlp --list-subs "URL"

字幕をダウンロード

# 自動生成字幕を含めてダウンロード
yt-dlp --write-auto-sub "URL"

# 手動字幕をダウンロード
yt-dlp --write-sub "URL"

# 両方ダウンロード
yt-dlp --write-sub --write-auto-sub "URL"

# 字幕のみダウンロード（動画なし）
yt-dlp --skip-download --write-sub "URL"
yt-dlp --skip-download --write-auto-sub "URL"

言語を指定

# 日本語字幕
yt-dlp --write-sub --sub-lang ja "URL"

# 英語字幕
yt-dlp --write-sub --sub-lang en "URL"

# 複数言語
yt-dlp --write-sub --sub-lang "ja,en,ko" "URL"

# すべての言語
yt-dlp --write-sub --sub-lang all "URL"

字幕フォーマット指定

# SRT形式
yt-dlp --write-sub --sub-format srt "URL"

# VTT形式
yt-dlp --write-sub --sub-format vtt "URL"

# ASS形式
yt-dlp --write-sub --sub-format ass "URL"

# 自動変換（SRTがない場合VTTから変換）
yt-dlp --write-sub --sub-format "srt/vtt/best" --convert-subs srt "URL"

字幕を動画に埋め込む

# 字幕を動画ファイルに埋め込む
yt-dlp --embed-subs "URL"

# 日本語字幕のみ埋め込み
yt-dlp --embed-subs --sub-lang ja "URL"

メタデータの取得

動画情報をJSON出力

# 動画情報を標準出力
yt-dlp -j "URL"

# ファイルに保存
yt-dlp -j "URL" > video_info.json

# プレイリスト全体の情報
yt-dlp -J "URL" > playlist_info.json

# 整形して出力
yt-dlp -j "URL" | jq .

# 特定フィールドのみ
yt-dlp -j "URL" | jq '{title, duration, view_count}'

特定情報の抽出

# タイトルのみ
yt-dlp --print title "URL"

# タイトルと再生時間
yt-dlp --print "%(title)s - %(duration)s秒" "URL"

# サムネイルURL
yt-dlp --print thumbnail "URL"

# アップロード日
yt-dlp --print upload_date "URL"

サムネイル取得

# サムネイルをダウンロード
yt-dlp --write-thumbnail "URL"

# 動画なし、サムネイルのみ
yt-dlp --skip-download --write-thumbnail "URL"

# 動画にサムネイルを埋め込む
yt-dlp --embed-thumbnail "URL"

説明文の保存

# 説明文を.descriptionファイルに保存
yt-dlp --write-description "URL"

プレイリスト処理

プレイリスト全体をダウンロード

# プレイリスト全体
yt-dlp "https://www.youtube.com/playlist?list=PLAYLIST_ID"

# 並列ダウンロード（高速化）
yt-dlp -N 4 "PLAYLIST_URL"

範囲指定

# 最初の5本
yt-dlp --playlist-items 1:5 "PLAYLIST_URL"

# 10番目から15番目
yt-dlp --playlist-items 10:15 "PLAYLIST_URL"

# 特定のインデックス
yt-dlp --playlist-items 1,3,5,7 "PLAYLIST_URL"

# 最後の3本
yt-dlp --playlist-items -3: "PLAYLIST_URL"

# 最初と最後だけ
yt-dlp --playlist-items 1,-1 "PLAYLIST_URL"

プレイリスト処理オプション

# プレイリストを逆順で
yt-dlp --playlist-reverse "PLAYLIST_URL"

# ランダム順
yt-dlp --playlist-random "PLAYLIST_URL"

# 動画として扱う（プレイリストでなく）
yt-dlp --no-playlist "VIDEO_URL_WITH_LIST_PARAM"

# プレイリストとして扱う
yt-dlp --yes-playlist "URL"

ファイル名テンプレート

基本的なテンプレート

# タイトル（デフォルト）
yt-dlp -o "%(title)s.%(ext)s" "URL"

# タイトル_ID形式
yt-dlp -o "%(title)s_%(id)s.%(ext)s" "URL"

# 日付_タイトル形式
yt-dlp -o "%(upload_date)s_%(title)s.%(ext)s" "URL"

# チャンネル名/タイトル形式
yt-dlp -o "%(channel)s/%(title)s.%(ext)s" "URL"

プレイリスト用テンプレート

# プレイリスト名/番号_タイトル
yt-dlp -o "%(playlist)s/%(playlist_index)s_%(title)s.%(ext)s" "PLAYLIST_URL"

# 3桁ゼロパディング
yt-dlp -o "%(playlist)s/%(playlist_index)03d_%(title)s.%(ext)s" "PLAYLIST_URL"

よく使うテンプレート変数

変数	説明
%(title)s	動画タイトル
%(id)s	動画ID
%(ext)s	拡張子
%(channel)s	チャンネル名
%(upload_date)s	アップロード日 (YYYYMMDD)
%(upload_date>%Y-%m-%d)s	日付フォーマット指定
%(duration)s	再生時間（秒）
%(view_count)s	再生回数
%(playlist)s	プレイリスト名
%(playlist_index)s	プレイリスト内番号
%(playlist_count)s	プレイリスト内総数
%(resolution)s	解像度

ファイル名の安全処理

# 特殊文字を置換
yt-dlp -o "%(title)s.%(ext)s" --restrict-filenames "URL"

# Windowsで使えない文字を置換
yt-dlp -o "%(title)s.%(ext)s" --windows-filenames "URL"

認証・Cookie

ブラウザからCookieを使用

# Chrome
yt-dlp --cookies-from-browser chrome "URL"

# Firefox
yt-dlp --cookies-from-browser firefox "URL"

# Safari
yt-dlp --cookies-from-browser safari "URL"

# Edge
yt-dlp --cookies-from-browser edge "URL"

# Brave
yt-dlp --cookies-from-browser brave "URL"

Cookieファイルを使用

# Netscape形式のcookies.txtを使用
yt-dlp --cookies cookies.txt "URL"

認証が必要なケース

• メンバーシップ/有料コンテンツ
• 年齢制限動画
• 非公開プレイリスト
• ログインユーザー限定コンテンツ

ユーザー名・パスワード認証（一部サイト）

# ユーザー名とパスワード
yt-dlp -u USERNAME -p PASSWORD "URL"

# 対話的にパスワード入力
yt-dlp -u USERNAME "URL"

よく使うパターン

YouTube高画質ダウンロード

# 最高画質でMP4形式
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]" \
  --merge-output-format mp4 \
  -o "%(title)s.%(ext)s" \
  "URL"

YouTube音楽ダウンロード

# MP3最高音質
yt-dlp -x --audio-format mp3 --audio-quality 0 \
  --embed-thumbnail \
  -o "%(title)s.%(ext)s" \
  "URL"

プレイリスト一括処理

# 音声のみ、番号付きファイル名
yt-dlp -x --audio-format mp3 \
  -o "%(playlist)s/%(playlist_index)03d_%(title)s.%(ext)s" \
  "PLAYLIST_URL"

日本語字幕付きダウンロード

yt-dlp --write-sub --write-auto-sub \
  --sub-lang ja \
  --embed-subs \
  -f "bestvideo+bestaudio" \
  "URL"

Twitter/X動画保存

yt-dlp -o "%(uploader)s_%(id)s.%(ext)s" "TWITTER_URL"

ニコニコ動画

# Cookie認証が必要
yt-dlp --cookies-from-browser chrome "https://www.nicovideo.jp/watch/sm..."

TikTok

yt-dlp -o "%(uploader)s_%(id)s.%(ext)s" "TIKTOK_URL"

アーカイブ（重複回避）

# ダウンロード済みを記録
yt-dlp --download-archive downloaded.txt "URL"

# 次回実行時はスキップ
yt-dlp --download-archive downloaded.txt "PLAYLIST_URL"

トラブルシューティング

一般的な問題

「Video unavailable」エラー

# 年齢制限の可能性 → Cookie認証
yt-dlp --cookies-from-browser chrome "URL"

# 地域制限の可能性 → プロキシ使用
yt-dlp --proxy "socks5://127.0.0.1:1080" "URL"

「Unable to extract」エラー

# yt-dlpを最新版に更新
yt-dlp -U

# キャッシュをクリア
yt-dlp --rm-cache-dir

ダウンロードが遅い

# 並列接続数を増やす
yt-dlp -N 4 "URL"

# 別フォーマットを試す
yt-dlp -f "best" "URL"

ffmpegエラー

# ffmpegがインストールされているか確認
ffmpeg -version

# ffmpegのパスを明示的に指定
yt-dlp --ffmpeg-location /usr/local/bin/ffmpeg "URL"

Cookieが読み取れない

# ブラウザを閉じてから再試行
# または、別のブラウザを試す
yt-dlp --cookies-from-browser firefox "URL"

デバッグ

# 詳細なログを出力
yt-dlp -v "URL"

# さらに詳細
yt-dlp -v --print-traffic "URL"

# ドライラン（実際にはダウンロードしない）
yt-dlp -s "URL"

設定ファイル

よく使うオプションは設定ファイルに保存できます：

設定ファイルの場所

• Linux/macOS: ~/.config/yt-dlp/config
• Windows: %APPDATA%\yt-dlp\config.txt

設定例

# ~/.config/yt-dlp/config

# デフォルト出力先
-P ~/Downloads/yt-dlp

# ファイル名テンプレート
-o %(title)s.%(ext)s

# 最高画質
-f bestvideo+bestaudio/best

# 字幕を埋め込み
--embed-subs
--sub-lang ja,en

# サムネイル埋め込み
--embed-thumbnail

# アーカイブ
--download-archive ~/Downloads/yt-dlp/archive.txt

リソース

公式ドキュメント

• GitHub: https://github.com/yt-dlp/yt-dlp
• サポートサイト一覧: https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md

このスキルに含まれるリファレンス

• references/download_options.md - フォーマット選択の詳細ガイド
• references/subtitle_extraction.md - 字幕取得の完全ガイド
• references/authentication.md - Cookie認証の詳細設定