Back to Details

yt-dlp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

yt-dlp

yt-dlp

CLI skill for yt-dlp: read-only URL probes, caption/transcript extraction, and optional media download. Follow the transcript-first protocol before any download.
Scope: Supported video/audio hosts via 
yt-dlp
, user-owned cookie files, playlist metadata, and local output under an explicit directory. NOT for: static page fetch (use Fetch MCP or 
curl
), broad multi-source research (
research
), ffmpeg transform recipes (
ffmpeg
), or bypassing platform Terms of Service.
用于yt-dlp的CLI技能：支持只读URL探测、字幕/转录文本提取，以及可选的媒体下载。在进行任何下载前，请遵循先转录协议。
适用范围： 通过
yt-dlp
支持的视频/音频平台、用户自有Cookie文件、播放列表元数据，以及指定目录下的本地输出。不适用场景： 静态页面抓取（使用Fetch MCP或
curl
）、多源广泛研究（使用
research
）、ffmpeg格式转换方案（使用
ffmpeg
），或违反平台服务条款的操作。

Canonical Vocabulary

标准术语表

TermMeaningNOT
probeRead-only metadata via 
--dump-json
; no media write		download
transcriptCaptions/subtitles to text files; prefer over full downloadaudio rip by default
downloadPersist media bytes after probe + user approvalsilent bulk grab
playlistMulti-entry URL; enumerate before selective downloadblind full-playlist download
cookiesUser-owned Netscape cookie file passed with 
--cookies
committed or skill-bundled secrets
doctorPreflight JSON report for binary, version, ffmpeglive URL smoke
format idyt-dlp 
format_id
from probe (e.g. 
251
, 
137+140
)		guessed extension
manual subCreator-uploaded captionsauto-generated only
auto subPlatform-generated captionsguaranteed accuracy
术语含义不包含
probe通过
--dump-json
获取只读元数据；不写入媒体文件		下载
transcript将字幕/副标题提取为文本文件；优先于完整下载默认音频提取
download完成探测并获得用户许可后，保存媒体文件静默批量抓取
playlist多条目URL；先枚举再选择性下载盲目下载完整播放列表
cookies用户自有Netscape格式Cookie文件，通过
--cookies
参数传入		已提交或技能内置的机密信息
doctor针对二进制文件、版本、ffmpeg的预检JSON报告实时URL测试
format id探测得到的yt-dlp 
format_id
（例如
251
、
137+140
）		猜测的文件扩展名
manual sub创作者上传的字幕仅自动生成字幕
auto sub平台生成的字幕保证准确性

Dispatch

命令调度

$ARGUMENTS
ModeAction
probe <url>
/ 
metadata <url>
/ 
info <url>
ProbeRun bundled 
probe_url.py
; summarize title, id, duration, subs
transcript <url>
/ 
subs <url>
/ 
captions <url>
TranscriptProbe first; extract best available subtitles without video download
download <url>
/ 
fetch <url>
/ 
save <url>
DownloadProbe first; confirm rights + format; download to explicit output dir
playlist <url>
PlaylistProbe with playlist allowed; list entries; selective download only with approval
cookies <path>
/ 
cookies check <path>
CookiesValidate user-owned cookie file path; never copy into repo
doctor
/ 
preflight
DoctorRun 
scripts/doctor.py --format json
Natural language: "what is this video", "get subtitles", "download this"AutoMap to probe → transcript → download per protocol below
(empty)HelpShow modes, protocol, ethics pointer, and examples
$ARGUMENTS
模式操作
probe <url>
/ 
metadata <url>
/ 
info <url>
Probe运行内置的
probe_url.py
；汇总标题、ID、时长、字幕信息
transcript <url>
/ 
subs <url>
/ 
captions <url>
Transcript先执行探测；无需下载视频即可提取最佳可用字幕
download <url>
/ 
fetch <url>
/ 
save <url>
Download先执行探测；确认权限和格式；下载至指定输出目录
playlist <url>
Playlist启用播放列表探测；列出条目；仅在获得许可后选择性下载
cookies <path>
/ 
cookies check <path>
Cookies验证用户自有Cookie文件路径；切勿复制到仓库中
doctor
/ 
preflight
Doctor运行
scripts/doctor.py --format json
自然语言指令："这个视频是什么内容"、"获取字幕"、"下载这个"自动模式根据下方协议映射为探测→转录→下载流程
(空参数)帮助显示模式说明、协议、伦理提示及示例

Auto-Detection Heuristic

自动检测规则

  1. URL + words like subtitle, caption, transcript, CC → Transcript (still probe first).
  2. URL + download, save, mp4, audio, rip → Download (still probe + approval first).
  3. URL + playlist, channel list, all videos → Playlist.
  4. Bare URL or "what is this link" → Probe.
  5. Path ending in 
    cookies.txt
    or mention of login/auth → Cookies guidance, then re-probe with 
    --cookies
    .
  6. Ambiguous → ask: metadata only, transcript, or download?
  1. URL + 包含subtitle、caption、transcript、CC等词汇 → Transcript（仍需先执行探测）。
  2. URL + 包含download、save、mp4、audio、rip等词汇 → Download（仍需先执行探测并获得许可）。
  3. URL + 包含playlist、channel list、all videos等词汇 → Playlist。
  4. 仅URL或询问"这个链接是什么" → Probe。
  5. 路径以
    cookies.txt
    结尾或提及login/auth → 提供Cookies指引，然后使用
    --cookies
    参数重新探测。
  6. 指令模糊 → 询问用户：仅需要元数据、转录文本，还是下载？

Transcript-First Protocol

先转录协议

Run these stages in order. Do not skip probe. Do not download until transcript needs are ruled out or the user explicitly wants media files.
按顺序执行以下步骤。不得跳过探测步骤。除非排除转录需求或用户明确要求媒体文件，否则不得下载。

Stage 1 — Doctor (once per session or after errors)

步骤1 — Doctor（每次会话或出错后执行一次）

bash
uv run python scripts/doctor.py --format json
Stop on 
ok: false
or any check with 
status: fail
(missing 
yt-dlp
binary).
bash
uv run python scripts/doctor.py --format json
如果返回
ok: false
或任何检查项
status: fail
（例如缺少
yt-dlp
二进制文件），则停止流程。

Stage 2 — Probe (mandatory before transcript or download)

步骤2 — Probe（转录或下载前必须执行）

bash
uv run python scripts/probe_url.py --url 'https://…' --format json
With user-owned cookies:
bash
uv run python scripts/probe_url.py --url 'https://…' --cookies "$HOME/.config/yt-dlp/cookies.txt" --format json
Playlist URL (enumerate entries; pass 
--allow-playlist
on probe):
bash
uv run python scripts/probe_url.py --url 'https://www.youtube.com/playlist?list=PL…' --allow-playlist --format json
From probe JSON, report: 
id
, 
title
, 
duration
, 
uploader
, 
availability
, 
subtitles
/ 
automatic_captions
languages, and recommended 
format_id
candidates. Load references/formats-and-quality.md when choosing formats.
bash
uv run python scripts/probe_url.py --url 'https://…' --format json
使用用户自有Cookie时：
bash
uv run python scripts/probe_url.py --url 'https://…' --cookies "$HOME/.config/yt-dlp/cookies.txt" --format json
播放列表URL（枚举条目；探测时需传入
--allow-playlist
）：
bash
uv run python scripts/probe_url.py --url 'https://www.youtube.com/playlist?list=PL…' --allow-playlist --format json
从探测返回的JSON中，汇报：
id
、
title
、
duration
、
uploader
、
availability
、
subtitles
/
automatic_captions
支持的语言，以及推荐的
format_id
候选值。选择格式时可参考references/formats-and-quality.md。

Stage 3 — Transcript (preferred over download)

步骤3 — Transcript（优先于下载）

When subtitles exist, extract text without downloading video:
bash
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs 'en.*,en' \
  --convert-subs srt --sub-format srt \
  -o '%(title).200B.%(ext)s' \
  --paths home:"$HOME/Downloads/yt-dlp/transcripts" \
  'URL'
Prefer manual subs over auto when both exist. Summarize path to 
.srt
/ 
.vtt
and offer to strip timing lines for plain text. If no subs: say so and ask before download-for-transcription (higher cost, rights-sensitive).
当存在字幕时，无需下载视频即可提取文本：
bash
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs 'en.*,en' \
  --convert-subs srt --sub-format srt \
  -o '%(title).200B.%(ext)s' \
  --paths home:"$HOME/Downloads/yt-dlp/transcripts" \
  'URL'
若同时存在manual字幕和auto字幕，优先选择manual字幕。汇总
.srt
/
.vtt
文件路径，并提供移除时间轴以生成纯文本的选项。如果没有字幕：告知用户，并在下载以提取转录文本前确认（成本更高，涉及权限问题）。

Stage 4 — Download (explicit approval required)

步骤4 — Download（需明确许可）

Before running:
  1. Confirm the user has rights to save the content (personal/archive/fair-use context per references/ethics-and-tos.md).
  2. Confirm output directory (default: 
    $HOME/Downloads/yt-dlp/media/
    ).
  3. Confirm format from probe (
    -f FORMAT
    or sensible default: 
    bv*+ba/b
    ).
bash
mkdir -p "$HOME/Downloads/yt-dlp/media"
yt-dlp -f 'bv*+ba/b' \
  --paths home:"$HOME/Downloads/yt-dlp/media" \
  -o '%(playlist_index)s-%(title).200B.%(ext)s' \
  'URL'
Report output path, format id, file size, and whether ffmpeg merge ran.
执行前需确认：
  1. 用户拥有保存内容的权限（个人/存档/合理使用场景，参考references/ethics-and-tos.md）。
  2. 输出目录（默认：
    $HOME/Downloads/yt-dlp/media/
    ）。
  3. 从探测结果中确认格式（
    -f FORMAT
    或合理默认值：
    bv*+ba/b
    ）。
bash
mkdir -p "$HOME/Downloads/yt-dlp/media"
yt-dlp -f 'bv*+ba/b' \
  --paths home:"$HOME/Downloads/yt-dlp/media" \
  -o '%(playlist_index)s-%(title).200B.%(ext)s' \
  'URL'
汇报输出路径、格式ID、文件大小，以及是否执行了ffmpeg合并操作。

Mode Details

模式详情

Probe mode

Probe模式

  • Use bundled 
    probe_url.py
    (wraps 
    yt-dlp --dump-json --no-download
    ).
  • Read-only: no writes under cwd or repo.
  • For age-gated or login-only content, stop and route to Cookies — do not guess credentials.
  • 使用内置的
    probe_url.py
    （封装
    yt-dlp --dump-json --no-download
    ）。
  • 只读模式：不在当前工作目录或仓库下写入文件。
  • 对于年龄限制或需登录的内容，停止流程并引导至Cookies模式——切勿猜测凭据。

Transcript

Transcript模式

  • Never default to downloading video/audio for text needs.
  • Use 
    --skip-download
    always.
  • If multiple languages, pick user-requested lang or 
    en
    with fallback list from probe.
  • 绝不默认下载视频/音频以满足文本需求。
  • 始终使用
    --skip-download
    参数。
  • 如果存在多种语言，选择用户指定的语言或探测结果中的
    en
    及备选语言。

Download

Download模式

  • Single URL default: 
    --no-playlist
    unless user asked for playlist.
  • No bulk channel/archival without explicit scope confirmation.
  • Do not embed cookies in commands in chat logs; reference 
    $COOKIES
    env or user path only.
  • 单URL默认：
    --no-playlist
    ，除非用户明确要求播放列表。
  • 未经明确范围确认，不得批量下载频道/存档内容。
  • 切勿在聊天日志的命令中嵌入Cookie；仅引用
    $COOKIES
    环境变量或用户提供的路径。

Playlist

Playlist模式

  1. Probe with playlist enabled:
bash
uv run python scripts/probe_url.py --url 'PLAYLIST_URL' --allow-playlist --format json
  1. Present numbered entries (index, title, duration).
  2. Download selected indices only (
    --playlist-items 1,3,5
    ) after approval — never blind full playlist.
  1. 启用播放列表探测：
bash
uv run python scripts/probe_url.py --url 'PLAYLIST_URL' --allow-playlist --format json
  1. 展示带编号的条目（索引、标题、时长）。
  2. 获得许可后仅下载选定索引（
    --playlist-items 1,3,5
    ）——绝不盲目下载完整播放列表。

Cookies

Cookies模式

  • User-owned cookie file only — path under user home or explicit user-provided path.
  • Never commit cookie files, never store in repo, never bundle in skill package.
  • Export guidance (browser extension → Netscape 
    cookies.txt
    ) lives in references/ethics-and-tos.md.
  • Validate readability:
bash
test -r "$HOME/.config/yt-dlp/cookies.txt" && echo readable
Pass 
--cookies PATH
only on probe/download when user supplied the path.
  • 仅使用用户自有Cookie文件——路径位于用户主目录或用户明确提供的路径。
  • 切勿提交Cookie文件、存储在仓库中或打包到技能包内。
  • 导出指引（浏览器扩展→Netscape格式
    cookies.txt
    ）见references/ethics-and-tos.md。
  • 验证可读性：
bash
test -r "$HOME/.config/yt-dlp/cookies.txt" && echo readable
仅当用户提供路径时，在探测/下载时传入
--cookies PATH
参数。

Doctor

Doctor模式

bash
uv run python scripts/doctor.py --format json
Parses JSON 
ok
, 
summary
, and per-check 
status
. Stop workflow on 
fail
. Treat 
warn
(e.g. missing ffmpeg) as advisory.
bash
uv run python scripts/doctor.py --format json
解析JSON中的
ok
、
summary
及各检查项的
status
。若出现
fail
则停止流程。将
warn
（例如缺少ffmpeg）视为提示信息。

Help

帮助模式

Show dispatch table, transcript-first protocol, default paths, and ethics reference link.
展示命令调度表、先转录协议、默认路径及伦理参考链接。

Gallery (Empty Arguments)

示例库（空参数时展示）

Present common invocations when 
$ARGUMENTS
is empty:
#TaskExample
1Preflight
/yt-dlp doctor
2Probe metadata
/yt-dlp probe https://www.youtube.com/watch?v=…
3Get subtitles
/yt-dlp transcript https://www.youtube.com/watch?v=…
4Download (after approval)
/yt-dlp download https://www.youtube.com/watch?v=…
5Playlist enumerate
/yt-dlp playlist https://www.youtube.com/playlist?list=…
6User-owned cookies
/yt-dlp cookies ~/.config/yt-dlp/cookies.txt
Pick a number, a mode from the dispatch table, or paste a URL and say whether you need metadata, subtitles, or a download.
当
$ARGUMENTS
为空时，展示常用调用示例：
#任务示例
1预检
/yt-dlp doctor
2探测元数据
/yt-dlp probe https://www.youtube.com/watch?v=…
3获取字幕
/yt-dlp transcript https://www.youtube.com/watch?v=…
4下载（获得许可后）
/yt-dlp download https://www.youtube.com/watch?v=…
5枚举播放列表
/yt-dlp playlist https://www.youtube.com/playlist?list=…
6用户自有Cookie
/yt-dlp cookies ~/.config/yt-dlp/cookies.txt
选择编号、调度表中的模式，或粘贴URL并说明需要元数据、字幕还是下载。

Critical Rules

关键规则

  1. Probe before transcript or download — always use 
    probe_url.py
    or equivalent 
    --dump-json --no-download
    .
  2. Transcript before download — prefer 
    --skip-download
    subtitle extraction when captions exist.
  3. Explicit approval for downloads — confirm rights, scope, output dir, and format.
  4. User-owned cookies only — never commit, copy into repo, or invent cookie paths.
  5. No ToS bypass coaching — see references/ethics-and-tos.md; refuse DRM circumvention or paywall evasion requests.
  6. Not Fetch MCP — static HTML, docs pages, and non-yt-dlp hosts → Fetch MCP or 
    curl
    , not this skill.
  7. Not ffmpeg skill — remux, transcode, clip, waveform → 
    /ffmpeg
    after download if needed.
  8. Least privilege output — write only under user-approved directories, never into the agents repo tree.
  9. Report provenance — title, URL, extractor, format id, and output paths in the final summary.
  1. 转录或下载前必须先探测——始终使用
    probe_url.py
    或等效的
    --dump-json --no-download
    命令。
  2. 下载前优先选择转录——若存在字幕，优先使用
    --skip-download
    参数提取字幕。
  3. 下载需明确许可——确认权限、范围、输出目录和格式。
  4. 仅使用用户自有Cookie——切勿提交、复制到仓库或伪造Cookie路径。
  5. 不指导违反服务条款的操作——参考references/ethics-and-tos.md；拒绝规避DRM或付费墙的请求。
  6. 替代Fetch MCP——静态HTML、文档页面和非yt-dlp支持的平台→使用Fetch MCP或
    curl
    ，而非本技能。
  7. 替代ffmpeg技能——重封装、转码、剪辑、波形处理→下载后使用
    /ffmpeg
    技能（若需要）。
  8. 最小权限输出——仅写入用户许可的目录，切勿写入代理仓库目录。
  9. 汇报来源信息——最终汇总中需包含标题、URL、提取器、格式ID和输出路径。

Troubleshooting

故障排除

See references/troubleshooting.md for extractor errors, geo blocks, signature failures, and ffmpeg merge issues.
提取器错误、地域限制、签名失败和ffmpeg合并问题，请参考references/troubleshooting.md。

References

参考文档

FileUse when
ethics-and-tos.mdRights, cookies, refusal boundaries
formats-and-quality.mdChoosing 
-f
format strings
troubleshooting.mdErrors after doctor passes
文件使用场景
ethics-and-tos.md权限、Cookie、拒绝边界
formats-and-quality.md选择
-f
格式字符串
troubleshooting.mdDoctor检查通过后的错误处理

Scripts

脚本说明

ScriptPurpose
scripts/doctor.py
JSON preflight: yt-dlp, version, ffmpeg
scripts/probe_url.py
Read-only 
--dump-json
wrapper
scripts/check.py
Validate skill manifest and evals
脚本用途
scripts/doctor.py
JSON格式预检：检查yt-dlp、版本、ffmpeg
scripts/probe_url.py
只读
--dump-json
封装脚本
scripts/check.py
验证技能清单和评估项

Examples

示例

bash
undefined
bash
undefined

Preflight

预检

uv run python scripts/doctor.py --format json
uv run python scripts/doctor.py --format json

Probe

探测

uv run python scripts/probe_url.py --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --format json
uv run python scripts/probe_url.py --url 'https://www.youtube.com/watch?v=dQw4w9WgXcQ' --format json

Transcript (after probe shows subs)

提取转录文本（探测显示存在字幕时）

yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs en -o '%(id)s'
--paths home:"$HOME/Downloads/yt-dlp/transcripts" 'URL'
yt-dlp --skip-download --write-subs --write-auto-subs --sub-langs en -o '%(id)s'
--paths home:"$HOME/Downloads/yt-dlp/transcripts" 'URL'

Download (after user approval)

下载（获得用户许可后）

yt-dlp -f 'bv*+ba/b' --paths home:"$HOME/Downloads/yt-dlp/media" -o '%(title).200B.%(ext)s' 'URL'
undefined
yt-dlp -f 'bv*+ba/b' --paths home:"$HOME/Downloads/yt-dlp/media" -o '%(title).200B.%(ext)s' 'URL'
undefined