媒体资讯视频数据采集-yt-dlp 使用指南 (中文版)

yt-dlp 使用指南 (中文版)

开源项目地址 https://github.com/yt-dlp/yt-dlp

yt-dlp 是一款功能丰富的命令行音视频下载器，支持数千个网站。该项目是基于已停止维护的 youtube-dlc 项目的 youtube-dl 的分支。

yt-dlp可以下载多家流媒体平台的音视频资源，仓库地址为：yt-dlp/yt-dlp: A feature-rich command-line audio/video downloader (github.com)

安装

Windows Unix MacOS PyPi 源代码压缩包 其他变体 所有版本

您可以使用二进制文件、pip 或第三方包管理器安装 yt-dlp。有关详细说明，请参阅 wiki。

发布文件

推荐

文件	描述
yt-dlp	平台无关的 zipimport 二进制文件。需要 Python（推荐用于 Linux/BSD）
yt-dlp.exe	Windows (Win7 SP1+) 独立 x64 二进制文件（推荐用于 Windows）
yt-dlp_macos	通用 MacOS (10.15+) 独立可执行文件（推荐用于 MacOS）

替代方案

文件	描述
yt-dlp_x86.exe	Windows (Win7 SP1+) 独立 x86 (32 位) 二进制文件
yt-dlp_min.exe	使用 py2exe 构建的 Windows (Win7 SP1+) 独立 x64 二进制文件

(不推荐)

文件	描述
yt-dlp_linux	Linux 独立 x64 二进制文件
yt-dlp_linux_armv7l	Linux 独立 armv7l (32 位) 二进制文件
yt-dlp_linux_aarch64	Linux 独立 aarch64 (64 位) 二进制文件
yt-dlp_win.zip	未打包的 Windows 可执行文件（无自动更新）
yt-dlp_macos.zip	未打包的 MacOS (10.15+) 可执行文件（无自动更新）
yt-dlp_macos_legacy	MacOS (10.9+) 独立 x64 可执行文件

其他

文件	描述
yt-dlp.tar.gz	源代码压缩包
SHA2-512SUMS	GNU 风格的 SHA512 校验和
SHA2-512SUMS.sig	SHA512 校验和的 GPG 签名文件
SHA2-256SUMS	GNU 风格的 SHA256 校验和
SHA2-256SUMS.sig	SHA256 校验和的 GPG 签名文件

可用于验证 GPG 签名的公钥可在此处获取。示例用法：

curl -L https://github.com/yt-dlp/yt-dlp/raw/master/public.key | gpg --import
gpg --verify SHA2-256SUMS.sig SHA2-256SUMS
gpg --verify SHA2-512SUMS.sig SHA2-512SUMS

注意：联机帮助页、shell 补全（自动完成）文件等可在源代码压缩包中找到。

更新

如果您使用的是发布的二进制文件，可以使用 yt-dlp -U 更新。

如果您使用 pip 安装，只需重新运行用于安装程序的相同命令。

对于其他第三方包管理器，请参阅 wiki 或参考其文档。

二进制文件目前有三个发布渠道：稳定版、夜间版和主线版。

• stable 是默认渠道，其许多更改已由 nightly 和 master 渠道的用户测试过。
• nightly 渠道每天大约在 UTC 午夜构建发布，以获取项目的最新补丁和更改的快照。这是推荐给 yt-dlp 常规用户的渠道。夜间版可从 yt-dlp/yt-dlp-nightly-builds 或作为 yt-dlp PyPI 包的开发版获取（可以使用 pip 的 --pre 标志安装）。
• master 渠道的功能是在每次推送到 master 分支后构建的版本，这些版本将包含最新的修复和添加，但也更容易出现回归。它们可从 yt-dlp/yt-dlp-master-builds 获取。

使用 --update/-U 时，发布的二进制文件只会更新到其当前渠道。当有更新版本可用时，可以使用 --update-to CHANNEL 切换到不同的渠道。--update-to [CHANNEL@]TAG 也可用于从渠道升级或降级到特定标签。

您还可以使用 --update-to <repository> (<owner>/<repository>) 更新到完全不同的存储库上的渠道。不过，请注意您要更新到的存储库，因为不同存储库的二进制文件不会进行验证。

示例用法：

• yt-dlp --update-to master 切换到 master 渠道并更新到其最新版本
• yt-dlp --update-to stable@2023.07.06 升级/降级到稳定版渠道标签 2023.07.06 的版本
• yt-dlp --update-to 2023.10.07 如果当前渠道存在标签 2023.10.07，则升级/降级到该标签
• yt-dlp --update-to example/yt-dlp@2023.09.24 升级/降级到 example/yt-dlp 存储库的版本，标签为 2023.09.24

重要提示：任何遇到稳定版问题的用户应在提交错误报告之前安装或更新到夜间版：

# 从稳定版可执行文件/二进制文件更新到夜间版：
yt-dlp --update-to nightly

# 使用 pip 安装夜间版：
python3 -m pip install -U --pre "yt-dlp[default]"

依赖项

支持 Python 版本 3.8+（CPython 和 PyPy）。其他版本和实现可能无法正常工作。

虽然所有其他依赖项都是可选的，但强烈建议使用 ffmpeg 和 ffprobe。

强烈推荐

• ffmpeg 和 ffprobe - 合并单独的视频和音频文件以及各种后期处理任务所需。许可证取决于构建。

ffmpeg 中存在一些错误，与 yt-dlp 一起使用时会导致各种问题。由于 ffmpeg 是如此重要的依赖项，我们在 yt-dlp/FFmpeg-Builds 中提供了针对其中一些问题的补丁的自定义构建。有关这些构建解决的特定问题的详细信息，请参阅自述文件。

重要提示：您需要的是 ffmpeg 二进制文件，而不是同名的 Python 包。

网络

• certifi* - 提供 Mozilla 的根证书包。根据 MPLv2 授权。
• brotli* 或 brotlicffi - Brotli 内容编码支持。两者均根据 MIT 1 2 授权。
• websockets* - 用于通过 websocket 下载。根据 BSD-3-Clause 授权。
• requests* - HTTP 库。用于 HTTPS 代理和持久连接支持。根据 Apache-2.0 授权。

模拟

以下内容提供对模拟浏览器请求的支持。这对于某些使用 TLS 指纹识别的网站可能是必需的。

• curl_cffi（推荐） - 用于 curl-impersonate 的 Python 绑定。提供 Chrome、Edge 和 Safari 的模拟目标。根据 MIT 授权。 可以使用 curl-cffi 组安装，例如 pip install "yt-dlp[default,curl-cffi]" 目前仅包含在 yt-dlp.exe 和 yt-dlp_macos 构建中

元数据

• mutagen* - 用于某些格式的 --embed-thumbnail。根据 GPLv2+ 授权。
• AtomicParsley - 当 mutagen/ffmpeg 无法使用时，用于 mp4/m4a 文件中的 --embed-thumbnail。根据 GPLv2+ 授权。
• xattr、pyxattr 或 setfattr - 用于在 Mac 和 BSD 上写入 xattr 元数据 (--xattr)。分别根据 MIT、LGPL2.1 和 GPLv2+ 授权。

其他

• pycryptodomex* - 用于解密 AES-128 HLS 流和各种其他数据。根据 BSD-2-Clause 授权。
• phantomjs - 用于需要运行 javascript 的提取器。根据 BSD-3-Clause 授权。
• secretstorage* - 用于 --cookies-from-browser 在 Linux 上解密基于 Chromium 的浏览器的 cookie 时访问 Gnome 密钥环。根据 BSD-3-Clause 授权。
• 任何您想与 --downloader 一起使用的外部下载器

已弃用

• avconv 和 avprobe - 现在已弃用，替代 ffmpeg。许可证取决于构建。
• sponskrub - 用于使用现已弃用的 sponskrub 选项。根据 GPLv3+ 授权。
• rtmpdump - 用于下载 rtmp 流。可以使用 ffmpeg 代替，并使用 --downloader ffmpeg。根据 GPLv2+ 授权。
• mplayer 或 mpv - 用于下载 rstp/mms 流。可以使用 ffmpeg 代替，并使用 --downloader ffmpeg。根据 GPLv2+ 授权。

要使用或重新分发依赖项，您必须同意其各自的许可条款。

独立的发布二进制文件是用 Python 解释器和包含*标记的包构建的。

如果您没有执行任务所需的必要依赖项，yt-dlp 将会警告您。所有当前可用的依赖项都显示在 --verbose 输出的顶部。

编译

独立的 PyInstaller 构建

要构建独立的可执行文件，您必须拥有 Python 和 pyinstaller（如果需要，还需要 yt-dlp 的任何可选依赖项）。可执行文件将针对与所使用的 Python 相同的 CPU 架构构建。

您可以运行以下命令：

python3 devscripts/install_deps.py --include pyinstaller
python3 devscripts/make_lazy_extractors.py
python3 -m bundle.pyinstaller

在某些系统上，您可能需要使用 py 或 python 代替 python3。

python -m bundle.pyinstaller 接受可以传递给 pyinstaller 的任何参数，例如 --onefile/-F 或 --onedir/-D，这些参数在此处有详细说明。

注意：低于 4.4 的 Pyinstaller 版本不支持从 Windows 商店安装的 Python，除非使用虚拟环境。

重要提示：直接运行 pyinstaller 而不是使用 python -m bundle.pyinstaller 不受官方支持。这可能无法正常工作。

平台无关的二进制文件 (UNIX)

您将需要构建工具 python (3.8+)、zip、make (GNU)、pandoc* 和 pytest*。

安装这些工具后，只需运行 make。

您还可以运行 make yt-dlp 来仅编译二进制文件，而不更新任何其他文件。（这不需要*标记的构建工具）

独立的 Py2Exe 构建 (Windows)

虽然我们提供了使用 py2exe 构建的选项，但建议使用 PyInstaller 构建，因为 py2exe 构建不能包含 pycryptodomex/certifi，并且需要目标计算机上的 VC++14 才能运行。

如果您仍然希望构建它，请安装 Python（如果尚未安装），然后您可以运行以下命令：

py devscripts/install_deps.py --include py2exe
py devscripts/make_lazy_extractors.py
py -m bundle.py2exe

相关脚本

• devscripts/install_deps.py - 安装 yt-dlp 的依赖项。
• devscripts/update-version.py - 根据当前日期更新版本号。
• devscripts/set-variant.py - 设置可执行文件的构建变体。
• devscripts/make_changelog.py - 使用简短的提交消息创建 markdown 更改日志并更新 CONTRIBUTORS 文件。
• devscripts/make_lazy_extractors.py - 创建延迟加载的提取器。在构建二进制文件（任何变体）之前运行此脚本将提高其启动性能。如果您希望强制禁用延迟加载的提取器，请设置环境变量 YTDLP_NO_LAZY_EXTRACTORS=1。

注意：有关更多信息，请参阅它们的 --help。

Fork 项目

如果您在 GitHub 上 fork 项目，可以运行 fork 的构建工作流以自动构建所选版本作为工件。或者，您可以运行发布工作流或启用夜间工作流来创建完整的（预）发布版本。

使用和选项

yt-dlp [选项] [--] 网址 [网址...]

Ctrl+F 是您的朋友 😄

通用选项：

选项	描述
-h, --help	打印此帮助文本并退出
--version	打印程序版本并退出
-U, --update	将此程序更新到最新版本
--no-update	不检查更新（默认）
--update-to [CHANNEL]@[TAG]	升级/降级到特定版本。CHANNEL 也可以是存储库。如果省略，CHANNEL 和 TAG 默认为“stable”和“latest”；有关详细信息，请参阅“更新”。支持的渠道：stable、nightly、master
-i, --ignore-errors	忽略下载和后处理错误。即使后处理失败，下载也将被视为成功
--no-abort-on-error	下载错误时继续下一个视频；例如，跳过播放列表中不可用的视频（默认）
--abort-on-error	如果发生错误，则中止进一步视频的下载（别名：--no-ignore-errors）
--dump-user-agent	显示当前用户代理并退出
--list-extractors	列出所有支持的提取器并退出
--extractor-descriptions	输出所有支持的提取器的描述并退出
--use-extractors NAMES	要使用的提取器名称，以逗号分隔。您还可以使用正则表达式、“all”、“default”和“end”（结束 URL 匹配）；例如，--ies "holodex.*,end,youtube"。在名称前添加“-”以排除它，例如 --ies default,-generic。使用 --list-extractors 获取提取器名称列表。（别名：--ies）
--default-search PREFIX	对不合格的 URL 使用此前缀。例如，“gvsearch2:python”从 google 视频下载两个搜索词为“python”的视频。使用值“auto”让 yt-dlp 猜测（“auto_warning”在猜测时发出警告）。“error”只会抛出错误。默认值“fixup_error”修复损坏的 URL，但如果无法修复则发出错误，而不是搜索
--ignore-config	除提供给 --config-locations 的配置文件外，不再加载任何配置文件。为了向后兼容，如果在系统配置文件中找到此选项，则不加载用户配置。（别名：--no-config）
--no-config-locations	不加载任何自定义配置文件（默认）。在配置文件中给出时，忽略当前文件中定义的所有先前 --config-locations
--config-locations PATH	主配置文件的位置；配置文件的路径或其包含的目录（“-”表示 stdin）。可以多次使用，也可以在其他配置文件中使用
--flat-playlist	不提取播放列表的视频，仅列出它们
--no-flat-playlist	完全提取播放列表的视频（默认）
--live-from-start	从一开始就下载直播。目前仅支持 YouTube（实验性）
--no-live-from-start	从当前时间下载直播（默认）
--wait-for-video MIN[-MAX]	等待预定的流变为可用。传递最小等待秒数（或范围）以在重试之间等待
--no-wait-for-video	不等待预定的流（默认）
--mark-watched	标记已观看的视频（即使使用 --simulate）
--no-mark-watched	不标记已观看的视频（默认）
--color [STREAM:]POLICY	是否在输出中发出颜色代码，可选地以要应用设置的 STREAM（stdout 或 stderr）为前缀。可以是“always”、“auto”（默认）、“never”或“no_color”（使用非彩色终端序列）之一。可以多次使用
--compat-options OPTS	通过恢复 yt-dlp 中所做的一些更改，可以帮助与 youtube-dl 或 youtube-dlc 配置保持兼容的选项。有关详细信息，请参阅“默认行为的差异”
--alias ALIASES OPTIONS	为选项字符串创建别名。除非别名以破折号“-”开头，否则它以“–”为前缀。参数根据 Python 字符串格式化迷你语言进行解析。例如，--alias get-audio,-X "-S=aext:{0},abr -x --audio-format {0}" 创建选项“–get-audio”和“-X”，它们接受一个参数 (ARG0) 并扩展为“-S=aext:ARG0,abr -x --audio-format ARG0”。所有定义的别名都列在 --help 输出中。别名选项可以触发更多别名；因此请注意避免定义递归选项。作为一项安全措施，每个别名最多可以触发 100 次。此选项可以多次使用

网络选项：

选项	描述
--proxy URL	使用指定的 HTTP/HTTPS/SOCKS 代理。要启用 SOCKS 代理，请指定正确的方案，例如 socks5://user:pass@127.0.0.1:1080/。传入空字符串 (--proxy "") 以进行直接连接
--socket-timeout SECONDS	放弃之前的等待时间，以秒为单位
--source-address IP	要绑定到的客户端 IP 地址
--impersonate CLIENT[:OS]	要模拟请求的客户端。例如，chrome、chrome-110、chrome:windows-10。传递 --impersonate="" 以模拟任何客户端。请注意，强制模拟所有请求可能会对下载速度和稳定性产生不利影响
--list-impersonate-targets	列出可模拟的可用客户端。
-4, --force-ipv4	通过 IPv4 建立所有连接
-6, --force-ipv6	通过 IPv6 建立所有连接
--enable-file-urls	启用 file:// URL。出于安全原因，默认情况下禁用此功能。

地理限制：

选项	描述
--geo-verification-proxy URL	使用此代理验证某些受地理限制网站的 IP 地址。--proxy 指定的默认代理（如果不存在该选项，则为无）用于实际下载
--xff VALUE	如何伪造 X-Forwarded-For HTTP 标头以尝试绕过地理限制。CIDR 表示法中的“default”（仅在已知有用时）、“never”、IP 块或两位 ISO 3166-2 国家/地区代码之一

视频选择：

选项	描述
-I, --playlist-items ITEM_SPEC	要下载的项目的逗号分隔的 playlist_index。您可以使用“[START]:[STOP][:STEP]”指定范围。为了向后兼容，也支持 START-STOP。使用负索引从右侧计数，使用负 STEP 以相反顺序下载。例如，“-I 1:3,7,-5::2”用于大小为 15 的播放列表将下载索引为 1,2,3,7,11,13,15 的项目
--min-filesize SIZE	如果文件大小小于 SIZE，则中止下载，例如 50k 或 44.6M
--max-filesize SIZE	如果文件大小大于 SIZE，则中止下载，例如 50k 或 44.6M
--date DATE	仅下载在此日期上传的视频。日期可以是“YYYYMMDD”或格式为 [now
--datebefore DATE	仅下载在此日期或之前上传的视频。接受的日期格式与 --date 相同
--dateafter DATE	仅下载在此日期或之后上传的视频。接受的日期格式与 --date 相同
--match-filters FILTER	通用视频过滤器。任何“输出模板”字段都可以使用“过滤格式”中定义的运算符与数字或字符串进行比较。您还可以简单地指定要匹配的字段（如果该字段存在），使用“!field”检查该字段是否存在，并使用“&”检查多个条件。如果需要，请使用“\”转义“&”或引号。如果多次使用，则至少满足其中一个条件时，过滤器匹配。例如，--match-filter !is_live --match-filter "like_count>?100 & description~='(?i)\bcats \& dogs\b'" 仅匹配不是直播的视频或点赞数超过 100 的视频（或点赞字段不可用），并且还包含短语“cats & dogs”（不区分大小写）的描述。使用“--match-filter -”以交互方式询问是否下载每个视频
--no-match-filters	不使用任何 --match-filter（默认）
--break-match-filters FILTER	与“--match-filters”相同，但在视频被拒绝时停止下载过程
--no-break-match-filters	不使用任何 --break-match-filters（默认）
--no-playlist	如果 URL 引用了视频和播放列表，则仅下载视频
--yes-playlist	如果 URL 引用了视频和播放列表，则下载播放列表
--age-limit YEARS	仅下载适合给定年龄的视频
--download-archive FILE	仅下载未在存档文件中列出的视频。记录其中所有下载视频的 ID
--no-download-archive	不使用存档文件（默认）
--max-downloads NUMBER	下载 NUMBER 文件后中止
--break-on-existing	遇到存档中的文件时停止下载过程
--no-break-on-existing	遇到存档中的文件时不要停止下载过程（默认）
--break-per-input	更改 --max-downloads、--break-on-existing、--break-match-filter 和自动编号以重置每个输入 URL
--no-break-per-input	--break-on-existing 和类似选项终止整个下载队列
--skip-playlist-after-errors N	允许失败的次数，直到跳过播放列表的其余部分

下载选项：

选项	描述
-N, --concurrent-fragments N	应同时下载的 dash/hlsnative 视频片段数（默认值为 1）
-r, --limit-rate RATE	最大下载速率，以每秒字节数为单位，例如 50K 或 4.2M
--throttled-rate RATE	假设节流的最小下载速率（以每秒字节数为单位），并将重新提取视频数据，例如 100K
-R, --retries RETRIES	重试次数（默认值为 10），或“infinite”
--file-access-retries RETRIES	文件访问错误的重试次数（默认值为 3），或“infinite”
--fragment-retries RETRIES	片段的重试次数（默认值为 10），或“infinite”（DASH、hlsnative 和 ISM）
--retry-sleep [TYPE:]EXPR	重试之间休眠的时间（以秒为单位）（可选）以重试类型为前缀（http（默认）、fragment、file_access、extractor）以应用休眠。EXPR 可以是数字、linear=START[:END[:STEP=1]] 或 exp=START[:END[:BASE=2]]。此选项可以多次使用以设置不同重试类型的休眠时间，例如 --retry-sleep linear=1::2 --retry-sleep fragment:exp=1:20
--skip-unavailable-fragments	跳过 DASH、hlsnative 和 ISM 下载中不可用的片段（默认）（别名：--no-abort-on-unavailable-fragments）
--abort-on-unavailable-fragments	如果片段不可用，则中止下载（别名：--no-skip-unavailable-fragments）
--keep-fragments	下载完成后将下载的片段保留在磁盘上
--no-keep-fragments	下载完成后删除下载的片段（默认）
--buffer-size SIZE	下载缓冲区的大小，例如 1024 或 16K（默认值为 1024）
--resize-buffer	缓冲区大小从 --buffer-size 的初始值自动调整大小（默认）
--no-resize-buffer	不要自动调整缓冲区大小
--http-chunk-size SIZE	基于块的 HTTP 下载的块大小，例如 10485760 或 10M（默认情况下禁用）。可能有助于绕过 Web 服务器施加的带宽限制（实验性）
--playlist-random	以随机顺序下载播放列表视频
--lazy-playlist	在收到播放列表中的条目时处理它们。这将禁用 n_entries、--playlist-random 和 --playlist-reverse
--no-lazy-playlist	仅在解析完整个播放列表后才处理播放列表中的视频（默认）
--xattr-set-filesize	设置文件 xattribute ytdl.filesize，其中包含预期的文件大小
--hls-use-mpegts	对 HLS 视频使用 mpegts 容器；允许某些播放器在下载时播放视频，并减少下载中断时文件损坏的可能性。默认情况下，这对直播流启用
--no-hls-use-mpegts	对 HLS 视频不使用 mpegts 容器。在不下载直播流时，这是默认设置
--download-sections REGEX	仅下载与正则表达式匹配的章节。“ ”前缀表示时间范围而不是章节。负时间戳是从结尾计算的。“ from-url”可用于下载从 URL 提取的“start_time”和“end_time”之间。需要 ffmpeg。此选项可以多次使用以下载多个部分，例如 --download-sections "*10:15-inf" --download-sections "intro"
--downloader [PROTO:]NAME	要使用的外部下载器的名称或路径（可选）以要使用的协议（http、ftp、m3u8、dash、rstp、rtmp、mms）为前缀。目前支持 native、aria2c、avconv、axel、curl、ffmpeg、httpie、wget。您可以多次使用此选项为不同的协议设置不同的下载器。例如，--downloader aria2c --downloader "dash,m3u8:native" 将使用 aria2c 进行 http/ftp 下载，并使用原生下载器进行 dash/m3u8 下载（别名：--external-downloader）
--downloader-args NAME:ARGS	将这些参数提供给外部下载器。指定下载器名称和以冒号“:”分隔的参数。对于 ffmpeg，可以使用与 --postprocessor-args 相同的语法将参数传递到不同的位置。您可以多次使用此选项向不同的下载器提供不同的参数（别名：--external-downloader-args）

文件系统选项：

选项	描述
-a, --batch-file FILE	包含要下载的 URL 的文件（“-”表示 stdin），每行一个 URL。以“#”、“;”或“]”开头的行被视为注释并被忽略
--no-batch-file	不从批处理文件读取 URL（默认）
-P, --paths [TYPES:]PATH	应下载文件的路径。指定文件类型和以冒号“:”分隔的路径。支持与 --output 相同的所有类型。此外，您还可以提供“home”（默认）和“temp”路径。所有中间文件首先下载到临时路径，然后在下载完成后将最终文件移动到主路径。如果 --output 是绝对路径，则忽略此选项
-o, --output [TYPES:]TEMPLATE	输出文件名模板；有关详细信息，请参阅“输出模板”
--output-na-placeholder TEXT	--output 中不可用字段的占位符（默认值：“NA”）
--restrict-filenames	将文件名限制为仅 ASCII 字符，并避免在文件名中使用“&”和空格
--no-restrict-filenames	允许在文件名中使用 Unicode 字符、“&”和空格（默认）
--windows-filenames	强制文件名与 Windows 兼容
--no-windows-filenames	仅在使用 Windows 时使文件名与 Windows 兼容（默认）
--trim-filenames LENGTH	将文件名长度（不包括扩展名）限制为指定的字符数
-w, --no-overwrites	不要覆盖任何文件
--force-overwrites	覆盖所有视频和元数据文件。此选项包括 --no-continue
--no-force-overwrites	不要覆盖视频，但覆盖相关文件（默认）
-c, --continue	恢复部分下载的文件/片段（默认）
--no-continue	不要恢复部分下载的片段。如果文件没有碎片，则重新开始下载整个文件
--part	使用 .part 文件而不是直接写入输出文件（默认）
--no-part	不使用 .part 文件 - 直接写入输出文件
--mtime	使用 Last-modified 标头设置文件修改时间（默认）
--no-mtime	不要使用 Last-modified 标头设置文件修改时间
--write-description	将视频描述写入 .description 文件
--no-write-description	不要写入视频描述（默认）
--write-info-json	将视频元数据写入 .info.json 文件（这可能包含个人信息）
--no-write-info-json	不要写入视频元数据（默认）
--write-playlist-metafiles	使用 --write-info-json、--write-description 等时，除了视频元数据之外还写入播放列表元数据。（默认）
--no-write-playlist-metafiles	使用 --write-info-json、--write-description 等时不要写入播放列表元数据。
--clean-info-json	从 infojson 中删除一些内部元数据，例如文件名（默认）
--no-clean-info-json	将所有字段写入 infojson
--write-comments	检索视频评论以放置在 infojson 中。即使没有此选项，如果提取已知很快，也会获取评论（别名：--get-comments）
--no-write-comments	除非提取已知很快，否则不要检索视频评论（别名：--no-get-comments）
--load-info-json FILE	包含视频信息的 JSON 文件（使用“--write-info-json”选项创建）
--cookies FILE	Netscape 格式的文件，用于从中读取 cookie 并转储 cookie jar
--no-cookies	不要从/向文件读取/转储 cookie（默认）
--cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER]	要从中加载 cookie 的浏览器名称。当前支持的浏览器有：brave、chrome、chromium、edge、firefox、opera、safari、vivaldi、whale。可选地，可以使用它们各自的分隔符给出用于在 Linux 上解密 Chromium cookie 的密钥环、要从中加载 cookie 的配置文件的名称/路径以及容器名称（如果为 Firefox）（“none”表示没有容器）。默认情况下，使用最近访问的配置文件的所有容器。当前支持的密钥环是：basictext、gnomekeyring、kwallet、kwallet5、kwallet6
--no-cookies-from-browser	不要从浏览器加载 cookie（默认）
--cache-dir DIR	文件系统中的位置，yt-dlp 可以在其中永久存储一些下载的信息（例如客户端 ID 和签名）。默认情况下，${XDG_CACHE_HOME}/yt-dlp
--no-cache-dir	禁用文件系统缓存
--rm-cache-dir	删除所有文件系统缓存文件

缩略图选项：

选项	描述
--write-thumbnail	将缩略图写入磁盘
--no-write-thumbnail	不要将缩略图写入磁盘（默认）
--write-all-thumbnails	将所有缩略图格式写入磁盘
--list-thumbnails	列出每个视频的可用缩略图。除非使用 --no-simulate，否则模拟

互联网快捷方式选项：

选项	描述
--write-link	写入互联网快捷方式文件，具体取决于当前平台（.url、.webloc 或 .desktop）。URL 可能会被操作系统缓存
--write-url-link	写入 .url Windows 互联网快捷方式。操作系统根据文件路径缓存 URL
--write-webloc-link	写入 .webloc macOS 互联网快捷方式
--write-desktop-link	写入 .desktop Linux 互联网快捷方式

详细程度和模拟选项：

选项	描述
-q, --quiet	激活静默模式。如果与 --verbose 一起使用，则将日志打印到 stderr
--no-quiet	取消激活静默模式。（默认）
--no-warnings	忽略警告
-s, --simulate	不要下载视频，也不要将任何内容写入磁盘
--no-simulate	即使使用打印/列出选项也下载视频
--ignore-no-formats-error	忽略“没有视频格式”错误。即使视频实际上不可供下载，也用于提取元数据（实验性）
--no-ignore-no-formats-error	找不到可下载视频格式时抛出错误（默认）
--skip-download	不要下载视频，但写入所有相关文件（别名：--no-download）
-O, --print [WHEN:]TEMPLATE	字段名称或输出模板以打印到屏幕，可选地以何时打印它的前缀为前缀，以“:”分隔。支持的“WHEN”值与 --use-postprocessor 的值相同（默认值：video）。暗示 --quiet。除非使用 --no-simulate 或 WHEN 的后期阶段，否则暗示 --simulate。此选项可以多次使用
--print-to-file [WHEN:]TEMPLATE FILE	将给定的模板附加到文件。WHEN 和 TEMPLATE 的值与 --print 的值相同。FILE 使用与输出模板相同的语法。此选项可以多次使用
-j, --dump-json	静默，但为每个视频打印 JSON 信息。除非使用 --no-simulate，否则模拟。有关可用键的描述，请参阅“输出模板”
-J, --dump-single-json	静默，但为每个传递的 url 或 infojson 打印 JSON 信息。除非使用 --no-simulate，否则模拟。如果 URL 引用了播放列表，则整个播放列表信息将转储在一行中
--force-write-archive	强制下载存档条目尽可能写入，只要没有错误发生，即使使用了 -s 或其他模拟选项（别名：--force-download-archive）
--newline	将进度条输出为新行
--no-progress	不要打印进度条
--progress	显示进度条，即使处于静默模式
--console-title	在控制台标题栏中显示进度
--progress-template [TYPES:]TEMPLATE	进度输出的模板，可选地以“download:”（默认）、“download-title:”（控制台标题）、“postprocess:”或“postprocess-title:”之一为前缀。视频的字段可在“info”键下访问，进度属性可在“progress”键下访问。例如，--console-title --progress-template "download-title:%(info.id)s-%(progress.eta)s"
--progress-delta SECONDS	进度输出之间的时间（默认值：0）
-v, --verbose	打印各种调试信息
--dump-pages	打印使用 base64 编码的下载页面以调试问题（非常详细）
--write-pages	将下载的中间页面写入当前目录中的文件以调试问题
--print-traffic	显示发送和读取的 HTTP 流量

解决方法：

选项	描述
--encoding ENCODING	强制使用指定的编码（实验性）
--legacy-server-connect	显式允许与不支持 RFC 5746 安全重新协商的服务器建立 HTTPS 连接
--no-check-certificates	禁止 HTTPS 证书验证
--prefer-insecure	使用未加密的连接来检索有关视频的信息（目前仅支持 YouTube）
--add-headers FIELD:VALUE	指定自定义 HTTP 标头及其值，以冒号“:”分隔。您可以多次使用此选项
--bidi-workaround	缺少双向文本支持的终端的解决方法。需要 PATH 中的 bidiv 或 fribidi 可执行文件
--sleep-requests SECONDS	数据提取期间请求之间休眠的秒数
--sleep-interval SECONDS	每次下载前休眠的秒数。这是与 --max-sleep-interval 一起使用时的最小休眠时间（别名：--min-sleep-interval）
--max-sleep-interval SECONDS	最大休眠秒数。只能与 --min-sleep-interval 一起使用
--sleep-subtitles SECONDS	每个字幕下载前休眠的秒数

视频格式选项：

选项	描述
-f, --format FORMAT	视频格式代码，有关更多详细信息，请参阅“格式选择”
-S, --format-sort SORTORDER	按给定的字段对格式进行排序，有关更多详细信息，请参阅“排序格式”
--format-sort-force	强制用户指定的排序顺序优先于所有字段，有关更多详细信息，请参阅“排序格式”（别名：--S-force）
--no-format-sort-force	某些字段优先于用户指定的排序顺序（默认）
--video-multistreams	允许多个视频流合并到一个文件中
--no-video-multistreams	每个输出文件只下载一个视频流（默认）
--audio-multistreams	允许多个音频流合并到一个文件中
--no-audio-multistreams	每个输出文件只下载一个音频流（默认）
--prefer-free-formats	在相同质量的情况下，优先使用免费容器的视频格式而不是非免费容器。与“-S ext”一起使用以严格优先使用免费容器，而不考虑质量
--no-prefer-free-formats	不对免费容器给予任何特殊偏好（默认）
--check-formats	确保仅从实际可下载的格式中选择格式
--check-all-formats	检查所有格式是否实际可下载
--no-check-formats	不要检查格式是否实际可下载
-F, --list-formats	列出每个视频的可用格式。除非使用 --no-simulate，否则模拟
--merge-output-format FORMAT	合并格式时可以使用的容器，以“/”分隔，例如“mp4/mkv”。如果不需要合并，则忽略。（当前支持：avi、flv、mkv、mov、mp4、webm）

字幕选项：

选项	描述
--write-subs	写入字幕文件
--no-write-subs	不要写入字幕文件（默认）
--write-auto-subs	写入自动生成的字幕文件（别名：--write-automatic-subs）
--no-write-auto-subs	不要写入自动生成的字幕（默认）（别名：--no-write-automatic-subs）
--list-subs	列出每个视频的可用字幕。除非使用 --no-simulate，否则模拟
--sub-format FORMAT	字幕格式；接受格式首选项，例如“srt”或“ass/srt/best”
--sub-langs LANGS	要下载的字幕语言（可以是正则表达式）或以逗号分隔的“all”，例如 --sub-langs "en.*,ja"。您可以在语言代码前添加“-”以将其从请求的语言中排除，例如 --sub-langs all,-live_chat。使用 --list-subs 获取可用语言标签列表

身份验证选项：

选项	描述
-u, --username USERNAME	使用此帐户 ID 登录
-p, --password PASSWORD	帐户密码。如果省略此选项，yt-dlp 将以交互方式询问
-2, --twofactor TWOFACTOR	双重身份验证代码
-n, --netrc	使用 .netrc 身份验证数据
--netrc-location PATH	.netrc 身份验证数据的位置；路径或其包含的目录。默认为 ~/.netrc
--netrc-cmd NETRC_CMD	要执行以获取提取器凭据的命令。
--video-password PASSWORD	视频特定密码
--ap-mso MSO	Adobe Pass 多系统运营商（电视提供商）标识符，使用 --ap-list-mso 获取可用 MSO 列表
--ap-username USERNAME	多系统运营商帐户登录名
--ap-password PASSWORD	多系统运营商帐户密码。如果省略此选项，yt-dlp 将以交互方式询问
--ap-list-mso	列出所有支持的多系统运营商
--client-certificate CERTFILE	客户端证书文件路径（PEM 格式）。可能包括私钥
--client-certificate-key KEYFILE	客户端证书私钥文件路径
--client-certificate-password PASSWORD	客户端证书私钥的密码（如果已加密）。如果未提供，并且密钥已加密，yt-dlp 将以交互方式询问

后期处理选项：

选项	描述
-x, --extract-audio	将视频文件转换为仅音频文件（需要 ffmpeg 和 ffprobe）
--audio-format FORMAT	使用 -x 时要将音频转换为的格式。（当前支持：best（默认）、aac、alac、flac、m4a、mp3、opus、vorbis、wav）。您可以使用与 --remux-video 类似的语法指定多个规则
--audio-quality QUALITY	指定使用 -x 转换音频时要使用的 ffmpeg 音频质量。插入 0（最佳）和 10（最差）之间的值以获得 VBR 或特定的比特率（例如 128K）（默认值 5）
--remux-video FORMAT	如果需要，将视频重新混合到另一个容器中（当前支持：avi、flv、gif、mkv、mov、mp4、webm、aac、aiff、alac、flac、m4a、mka、mp3、ogg、opus、vorbis、wav）。如果目标容器不支持视频/音频编解码器，则重新混合将失败。您可以指定多个规则；例如，“aac>m4a/mov>mp4/mkv”将 aac 重新混合为 m4a，将 mov 重新混合为 mp4，将任何其他内容重新混合为 mkv
--recode-video FORMAT	如果需要，将视频重新编码为另一种格式。语法和支持的格式与 --remux-video 相同
--postprocessor-args NAME:ARGS	将这些参数提供给后期处理器。指定后期处理器/可执行文件名称和以冒号“:”分隔的参数，以将参数提供给指定的后期处理器/可执行文件。支持的 PP 是：Merger、ModifyChapters、SplitChapters、ExtractAudio、VideoRemuxer、VideoConvertor、Metadata、EmbedSubtitle、EmbedThumbnail、SubtitlesConvertor、ThumbnailsConvertor、FixupStretched、FixupM4a、FixupM3u8、FixupTimestamp 和 FixupDuration。支持的可执行文件是：AtomicParsley、FFmpeg 和 FFprobe。您还可以指定“PP+EXE:ARGS”以仅在指定的后期处理器使用时将参数提供给指定的可执行文件。此外，对于 ffmpeg/ffprobe，“_i”/“_o”可以附加到前缀，可选地后跟一个数字，以在指定的输入/输出文件之前传递参数，例如 --ppa "Merger+ffmpeg_i1:-v quiet"。您可以多次使用此选项向不同的后期处理器提供不同的参数。（别名：--ppa）
-k, --keep-video	后期处理后将中间视频文件保留在磁盘上
--no-keep-video	后期处理后删除中间视频文件（默认）
--post-overwrites	覆盖后处理文件（默认）
--no-post-overwrites	不要覆盖后处理文件
--embed-subs	将字幕嵌入视频中（仅适用于 mp4、webm 和 mkv 视频）
--no-embed-subs	不要嵌入字幕（默认）
--embed-thumbnail	将缩略图作为封面嵌入视频中
--no-embed-thumbnail	不要嵌入缩略图（默认）
--embed-metadata	将元数据嵌入到视频文件中。除非使用 --no-embed-chapters/--no-embed-info-json，否则还会嵌入章节/infojson（别名：--add-metadata）
--no-embed-metadata	不要将元数据添加到文件（默认）（别名：--no-add-metadata）
--embed-chapters	将章节标记添加到视频文件（别名：--add-chapters）
--no-embed-chapters	不要添加章节标记（默认）（别名：--no-add-chapters）
--embed-info-json	将 infojson 作为附件嵌入到 mkv/mka 视频文件中
--no-embed-info-json	不要将 infojson 作为附件嵌入到视频文件中
--parse-metadata [WHEN:]FROM:TO	从其他字段解析其他元数据，例如标题/艺术家；有关详细信息，请参阅“修改元数据”。支持的“WHEN”值与 --use-postprocessor 的值相同（默认值：pre_process）
--replace-in-metadata [WHEN:]FIELDS REGEX REPLACE	使用给定的正则表达式替换元数据字段中的文本。此选项可以多次使用。支持的“WHEN”值与 --use-postprocessor 的值相同（默认值：pre_process）
--xattrs	将元数据写入视频文件的 xattrs（使用都柏林核心和 xdg 标准）
--concat-playlist POLICY	连接播放列表中的视频。“never”、“always”或“multi_video”（默认；仅当视频构成单个节目时）之一。所有视频文件必须具有相同的编解码器和流数才能连接。“pl_video:”前缀可以与“--paths”和“--output”一起使用来设置连接文件的输出文件名。有关详细信息，请参阅“输出模板”
--fixup POLICY	自动更正文件的已知故障。never（不执行任何操作）、warn（仅发出警告）、detect_or_warn（默认；如果可以则修复文件，否则警告）、force（即使文件已存在也尝试修复）之一
--ffmpeg-location PATH	ffmpeg 二进制文件的位置；二进制文件的路径或其包含的目录
--exec [WHEN:]CMD	执行命令，可选地以何时执行它的前缀为前缀，以“:”分隔。支持的“WHEN”值与 --use-postprocessor 的值相同（默认值：after_move）。可以使用与输出模板相同的语法将任何字段作为参数传递给命令。如果未传递任何字段，则 %(filepath,_filename
--no-exec	删除任何先前定义的 --exec
--convert-subs FORMAT	将字幕转换为另一种格式（当前支持：ass、lrc、srt、vtt）（别名：--convert-subtitles）
--convert-thumbnails FORMAT	将缩略图转换为另一种格式（当前支持：jpg、png、webp）。您可以使用与 --remux-video 类似的语法指定多个规则
--split-chapters	根据内部章节将视频拆分为多个文件。“chapter:”前缀可以与“--paths”和“--output”一起使用来设置拆分文件的输出文件名。有关详细信息，请参阅“输出模板”
--no-split-chapters	不要根据章节拆分视频（默认）
--remove-chapters REGEX	删除标题与给定正则表达式匹配的章节。语法与 --download-sections 相同。此选项可以多次使用
--no-remove-chapters	不要从文件中删除任何章节（默认）
--force-keyframes-at-cuts	在下载/拆分/删除部分时在剪切处强制使用关键帧。由于需要重新编码，因此速度很慢，但生成的视频在剪切处可能具有更少的伪影
--no-force-keyframes-at-cuts	在剪切/拆分时不要在章节周围强制使用关键帧（默认）
--use-postprocessor NAME[:ARGS]	要启用的插件后期处理器的（区分大小写）名称，以及（可选）要传递给它的参数，以冒号“:”分隔。ARGS 是以分号“;”分隔的 NAME=VALUE 列表。“when”参数决定何时调用后期处理器。它可以是“pre_process”（视频提取后）、“after_filter”（视频通过过滤器后）、“video”（--format 之后；--print/--output 之前）、“before_dl”（每个视频下载之前）、“post_process”（每个视频下载之后；默认）、“after_move”（将视频文件移动到其最终位置之后）、“after_video”（下载和处理完视频的所有格式之后）或“playlist”（播放列表结束时）之一。此选项可以多次使用以添加不同的后期处理器

SponsorBlock 选项：

使用 SponsorBlock API 为下载的 YouTube 视频创建章节条目或删除各种片段（赞助、介绍等）

选项	描述
--sponsorblock-mark CATS	要为其创建章节的 SponsorBlock 类别，以逗号分隔。可用的类别是 sponsor、intro、outro、selfpromo、preview、filler、interaction、music_offtopic、poi_highlight、chapter、all 和 default (=all)。您可以在类别前添加“-”以将其排除在外。有关类别的描述，请参阅 [1]。例如，--sponsorblock-mark all,-preview [1] https://wiki.sponsor.ajay.app/w/Segment_Categories
--sponsorblock-remove CATS	要从视频文件中删除的 SponsorBlock 类别，以逗号分隔。如果某个类别同时出现在标记和删除中，则删除优先。语法和可用类别与 --sponsorblock-mark 相同，只是“default”指的是“all,-filler”，并且 poi_highlight、chapter 不可用
--sponsorblock-chapter-title TEMPLATE	由 --sponsorblock-mark 创建的 SponsorBlock 章节标题的输出模板。唯一可用的字段是 start_time、end_time、category、categories、name、category_names。默认为“[SponsorBlock]: %(category_names)l”
--no-sponsorblock	禁用 --sponsorblock-mark 和 --sponsorblock-remove
--sponsorblock-api URL	SponsorBlock API 位置，默认为 https://sponsor.ajay.app

提取器选项：

选项	描述
--extractor-retries RETRIES	已知提取器错误的重试次数（默认值为 3），或“infinite”
--allow-dynamic-mpd	处理动态 DASH 清单（默认）（别名：--no-ignore-dynamic-mpd）
--ignore-dynamic-mpd	不要处理动态 DASH 清单（别名：--no-allow-dynamic-mpd）
--hls-split-discontinuity	在不连续处（例如广告中断）将 HLS 播放列表拆分为不同的格式
--no-hls-split-discontinuity	不要在不连续处（例如广告中断）将 HLS 播放列表拆分为不同的格式（默认）
--extractor-args IE_KEY:ARGS	将 ARGS 参数传递给 IE_KEY 提取器。有关详细信息，请参阅“提取器参数”。您可以多次使用此选项为不同的提取器提供参数

配置

您可以通过将任何支持的命令行选项放置到配置文件中来配置 yt-dlp。配置从以下位置加载：

主配置：

• 提供给 --config-location 的文件

便携式配置： （推荐用于便携式安装）

• 如果使用二进制文件，则与二进制文件位于同一目录中的 yt-dlp.conf
• 如果从源代码运行，则 yt_dlp 父目录中的 yt-dlp.conf

家庭配置：

• -P 提供的主路径中的 yt-dlp.conf
• 如果未提供 -P，则搜索当前目录

用户配置：

• ${XDG_CONFIG_HOME}/yt-dlp.conf
• ${XDG_CONFIG_HOME}/yt-dlp/config（推荐用于 Linux/macOS）
• ${XDG_CONFIG_HOME}/yt-dlp/config.txt
• ${APPDATA}/yt-dlp.conf
• ${APPDATA}/yt-dlp/config（推荐用于 Windows）
• ${APPDATA}/yt-dlp/config.txt
• ~/yt-dlp.conf
• ~/yt-dlp.conf.txt
• ~/.yt-dlp/config
• ~/.yt-dlp/config.txt

另请参阅：关于环境变量的说明

系统配置：

• /etc/yt-dlp.conf
• /etc/yt-dlp/config
• /etc/yt-dlp/config.txt

例如，使用以下配置文件 yt-dlp 将始终提取音频，不复制 mtime，使用代理并将所有视频保存在您主目录的 YouTube 目录下：

# 以 # 开头的行是注释

# 始终提取音频
-x

# 不要复制 mtime
--no-mtime

# 使用此代理
--proxy 127.0.0.1:3128

# 将所有视频保存在您主目录的 YouTube 目录下
-o ~/YouTube/%(title)s.%(ext)s

注意：配置文件中的选项与常规命令行调用中使用的选项（也称为开关）相同；因此 - 或 – 之后不能有空格，例如 -o 或 --proxy，但不能是 - o 或 -- proxy。必要时还必须引用它们，就好像它是一个 UNIX shell 一样。

如果您想为特定的 yt-dlp 运行禁用所有配置文件，可以使用 --ignore-config。如果在任何配置文件中找到 --ignore-config，则不会加载进一步的配置。例如，在便携式配置文件中包含该选项会阻止加载家庭、用户和系统配置。此外，（为了向后兼容）如果在系统配置文件中找到 --ignore-config，则不会加载用户配置。

配置文件编码

如果存在 UTF BOM，则配置文件将根据 UTF BOM 进行解码，否则将根据系统区域设置中的编码进行解码。

如果您希望以不同的方式解码文件，请在文件开头添加 # coding: ENCODING（例如 # coding: shift-jis）。在此之前不能有任何字符，即使是空格或 BOM 也不行。

使用 netrc 进行身份验证

您可能还想为支持身份验证的提取器（通过使用 --username 和 --password 提供登录名和密码）配置自动凭据存储，以便不在每次 yt-dlp 执行时都将凭据作为命令行参数传递，并防止在 shell 命令历史记录中跟踪纯文本密码。您可以通过在每个提取器的基础上使用 .netrc 文件来实现此目的。为此，您需要在 --netrc-location 中创建一个 .netrc 文件，并将权限限制为仅由您读取/写入：

touch ${HOME}/.netrc
chmod a-rwx,u+rw ${HOME}/.netrc

之后，您可以添加提取器的凭据，格式如下，其中 extractor 是提取器的小写名称：

machine <extractor> login <username> password <password>

例如

machine youtube login myaccount@gmail.com password my_youtube_password
machine twitch login my_twitch_account_name password my_twitch_password

要使用 .netrc 文件激活身份验证，您应该将 --netrc 传递给 yt-dlp 或将其放在配置文件中。

.netrc 文件的默认位置是 ~（见下文）。

作为使用 .netrc 文件的替代方法（缺点是将您的密码保存在纯文本文件中），您可以配置自定义 shell 命令以提供提取器的凭据。这是通过提供 --netrc-cmd 参数来完成的，它应以 netrc 格式输出凭据并在成功时返回 0，其他值将被视为错误。命令中的 {} 将替换为提取器的名称，以便可以选择正确提取器的凭据。

例如，要使用存储为 .authinfo.gpg 的加密 .netrc 文件

yt-dlp --netrc-cmd 'gpg --decrypt ~/.authinfo.gpg' https://www.youtube.com/watch?v=BaW_jenozKc

关于环境变量的说明

• 环境变量在 UNIX 系统中通常表示为 ${VARIABLE} 或 $VARIABLE，而在 Windows 中则表示为 %VARIABLE%；但在本文档中始终以 ${VARIABLE} 的形式显示。
• yt-dlp 还允许在 Windows 上使用 UNIX 风格的变量用于路径选项，例如 --output 和 --config-location。
• 如果未设置，${XDG_CONFIG_HOME} 默认为 ~/.config，而 ${XDG_CACHE_HOME} 默认为 ~/.cache。
• 在 Windows 上，如果存在 ~，它指向 ${HOME}；否则指向 ${USERPROFILE} 或 $HOMEDRIVE${HOMEPATH}。
• 在 Windows 上，${USERPROFILE} 通常指向 C:\Users<用户名>，而 ${APPDATA} 指向 ${USERPROFILE}\AppData\Roaming。

输出模板

-o 选项用于在下载单个文件时指示输出文件名的模板，而 -P 选项用于指定应保存每种文件的路径。

tl;dr：导航我到示例。

-o 最简单的用法是在下载单个文件时不设置任何模板参数，如 yt-dlp -o funny_video.flv "https://some/video"（不建议像这样硬编码文件扩展名，并且可能会破坏一些后处理）。

但是，它也可能包含特殊序列，这些序列将在下载每个视频时被替换。特殊序列可以根据 Python 字符串格式化操作进行格式化，例如 %(NAME)s 或 %(NAME)05d。为了清楚起见，这是一个百分号，后跟括号中的名称，后跟格式化操作。

字段名称本身（括号内的部分）也可以具有一些特殊格式：

• 对象遍历： 可以使用点 . 分隔符遍历元数据中可用的字典和列表；例如 %(tags.0)s、%(subtitles.en.-1.ext)s。您可以使用冒号 : 进行 Python 切片；例如 %(id.3:7:-1)s、%(formats.:.format_id)s。花括号 {} 可用于构建仅包含特定键的字典；例如 %(formats.:.{format_id,height})#j。空字段名称 %()s 指的是整个信息字典；例如 %(.{id,title})s。请注意，并非所有使用此方法可用的字段都在下面列出。使用 -j 查看此类字段
• 算术： 可以使用 +、- 和 * 对数字字段进行简单算术运算。例如 %(playlist_index+10)03d、%(n_entries+1-playlist_index)d
• 日期/时间格式化： 日期/时间字段可以根据 strftime 格式化进行格式化，方法是使用 > 将其与字段名称分开指定。例如 %(duration>%H-%M-%S)s、%(upload_date>%Y-%m-%d)s、%(epoch-3600>%H-%M-%S)s
• 替代方案： 可以使用 , 分隔指定备用字段。例如 %(release_date>%Y,upload_date>%Y|Unknown)s
• 替换： 可以使用 & 分隔符根据 str.format 迷你语言指定替换值。如果字段不为空，则将使用此替换值而不是实际字段内容。这是在考虑备用字段之后完成的；因此，如果任何备用字段不为空，则使用替换。例如 %(chapters&has chapters|no chapters)s、%(title&TITLE={:>20}|NO TITLE)s
• 默认值： 可以使用 | 分隔符为字段为空时指定文字默认值。这将覆盖 --output-na-placeholder。例如 %(uploader|Unknown)s
• 更多转换： 除了正常的格式类型 diouxXeEfFgGcrs 之外，yt-dlp 还支持转换为 B = 字节、j = json（标志 # 用于漂亮打印，+ 用于 Unicode）、h = HTML 转义、l = 逗号分隔列表（标志 # 用于 \n 换行符分隔）、q = 为终端引用的字符串（标志 # 将列表拆分为不同的参数）、D = 添加十进制后缀（例如 10M）（标志 # 使用 1024 作为因子）和 S = 净化为文件名（标志 # 用于限制）
• Unicode 规范化： 格式类型 U 可用于 NFC Unicode 规范化。备用形式标志 (#) 将规范化更改为 NFD，转换标志 + 可用于 NFKC/NFKD 兼容性等效规范化。例如 %(title)+.100U 是 NFKC

总而言之，字段的通用语法是：

%(name[.keys][addition][>strf][,alternate][&replacement][|default])[flags][width][.precision][length]type

此外，您可以通过指定文件类型，后跟以冒号 : 分隔的模板，为各种元数据文件分别设置不同的输出模板，与通用输出模板分开。支持的不同文件类型是 subtitle、thumbnail、description、annotation（已弃用）、infojson、link、pl_thumbnail、pl_description、pl_infojson、chapter、pl_video。例如，-o "%(title)s.%(ext)s" -o "thumbnail:%(title)s\%(title)s.%(ext)s" 会将缩略图放在与视频同名的文件夹中。如果任何模板为空，则不会写入该类型的文件。例如，--write-thumbnail -o "thumbnail:" 将仅为播放列表写入缩略图，而不为视频写入缩略图。

注意：由于后处理（即合并等），实际的输出文件名可能有所不同。使用 --print after_move:filepath 获取所有后处理完成后

可用的字段是：

字段	描述
id (字符串)	视频标识符
title (字符串)	视频标题
fulltitle (字符串)	忽略直播时间戳和通用标题的视频标题
ext (字符串)	视频文件名扩展名
alt_title (字符串)	视频的辅助标题
description (字符串)	视频的描述
display_id (字符串)	视频的替代标识符
uploader (字符串)	视频上传者的全名
uploader_id (字符串)	视频上传者的昵称或 ID
uploader_url (字符串)	指向视频上传者个人资料的 URL
license (字符串)	视频获得许可的许可证名称
creators (列表)	视频的创作者
creator (字符串)	视频的创作者；逗号分隔
timestamp (数字)	视频可用时的 UNIX 时间戳
upload_date (字符串)	UTC 中的视频上传日期 (YYYYMMDD)
release_timestamp (数字)	视频发布时的 UNIX 时间戳
release_date (字符串)	UTC 中视频发布的日期 (YYYYMMDD)
release_year (数字)	视频或专辑发布的年份 (YYYY)
modified_timestamp (数字)	视频上次修改时的 UNIX 时间戳
modified_date (字符串)	UTC 中视频上次修改的日期 (YYYYMMDD)
channel (字符串)	上传视频的频道的全名
channel_id (字符串)	频道的 ID
channel_url (字符串)	频道的 URL
channel_follower_count (数字)	频道粉丝数
channel_is_verified (布尔值)	频道是否在平台上经过验证
location (字符串)	拍摄视频的实际位置
duration (数字)	视频长度（以秒为单位）
duration_string (字符串)	视频长度 (HH:mm:ss)
view_count (数字)	平台上有多少用户观看了该视频
concurrent_view_count (数字)	当前有多少用户在平台上观看该视频
like_count (数字)	视频的正面评价数
dislike_count (数字)	视频的负面评价数
repost_count (数字)	视频的转发次数
average_rating (数字)	用户给出的平均评分，使用的比例取决于网页
comment_count (数字)	视频评论数（对于某些提取器，评论仅在最后下载，因此无法使用此字段）
age_limit (数字)	视频的年龄限制（以年为单位）
live_status (字符串)	“not_live”、“is_live”、“is_upcoming”、“was_live”、“post_live”（曾直播，但 VOD 尚未处理）之一
is_live (布尔值)	此视频是直播还是固定长度视频
was_live (布尔值)	此视频最初是否是直播
playable_in_embed (字符串)	是否允许此视频在其他网站的嵌入式播放器中播放
availability (字符串)	视频是“private”、“premium_only”、“subscriber_only”、“needs_auth”、“unlisted”还是“public”
media_type (字符串)	网站分类的媒体类型，例如“episode”、“clip”、“trailer”
start_time (数字)	URL 中指定的应开始播放的时间（以秒为单位）
end_time (数字)	URL 中指定的应结束播放的时间（以秒为单位）
extractor (字符串)	提取器的名称
extractor_key (字符串)	提取器的键名
epoch (数字)	完成信息提取时的 Unix 纪元
autonumber (数字)	从 --autonumber-start 开始，每次下载都会增加的数字，用前导零填充
video_autonumber (数字)	每次视频都会增加的数字
n_entries (数字)	播放列表中提取的项目总数
playlist_id (字符串)	包含视频的播放列表的标识符
playlist_title (字符串)	包含视频的播放列表的名称
playlist (字符串)	playlist_id 或 playlist_title
playlist_count (数字)	播放列表中的项目总数。如果未提取整个播放列表，则可能未知
playlist_index (数字)	播放列表中视频的索引，根据最终索引用前导零填充
playlist_autonumber (数字)	播放列表下载队列中视频的位置，根据播放列表的总长度用前导零填充
playlist_uploader (字符串)	播放列表上传者的全名
playlist_uploader_id (字符串)	播放列表上传者的昵称或 ID
webpage_url (字符串)	指向视频网页的 URL，如果提供给 yt-dlp，则应再次获得相同的结果
webpage_url_basename (字符串)	网页 URL 的基本名称
webpage_url_domain (字符串)	网页 URL 的域名
original_url (字符串)	用户提供的 URL（或与播放列表条目的 webpage_url 相同）
categories (列表)	视频所属的类别列表
tags (列表)	分配给视频的标签列表
cast (列表)	演职人员名单

“过滤格式”中的所有字段也可以使用

适用于属于某些逻辑章节或部分的视频：

字段	描述
chapter (字符串)	视频所属章节的名称或标题
chapter_number (数字)	视频所属章节的编号
chapter_id (字符串)	视频所属章节的 ID

适用于作为某些系列或节目剧集的视频：

字段	描述
series (字符串)	视频剧集所属的系列或节目的标题
series_id (字符串)	视频剧集所属的系列或节目的 ID
season (字符串)	视频剧集所属的季的标题
season_number (数字)	视频剧集所属的季的编号
season_id (字符串)	视频剧集所属的季的 ID
episode (字符串)	视频剧集的标题
episode_number (数字)	一季中视频剧集的编号
episode_id (字符串)	视频剧集的 ID

适用于作为音乐专辑曲目或一部分的媒体：

字段	描述
track (字符串)	曲目的标题
track_number (数字)	专辑或光盘中曲目的编号
track_id (字符串)	曲目的 ID
artists (列表)	曲目的艺术家
artist (字符串)	曲目的艺术家；逗号分隔
genres (列表)	曲目的流派
genre (字符串)	曲目的流派；逗号分隔
composers (列表)	作品的作曲家
composer (字符串)	作品的作曲家；逗号分隔
album (字符串)	曲目所属专辑的标题
album_type (字符串)	专辑类型
album_artists (列表)	出现在专辑中的所有艺术家
album_artist (字符串)	出现在专辑中的所有艺术家；逗号分隔
disc_number (数字)	曲目所属的光盘或其他物理介质的编号

仅在使用 --download-sections 时可用，以及在使用 --split-chapters 时用于 chapter: 前缀（适用于具有内部章节的视频）：

字段	描述
section_title (字符串)	章节标题
section_number (数字)	文件中章节的编号
section_start (数字)	章节的开始时间（以秒为单位）
section_end (数字)	章节的结束时间（以秒为单位）

仅在 --print 中使用时可用：

字段	描述
urls (字符串)	所有请求格式的 URL，每行一个
filename (字符串)	视频文件的名称。请注意，实际文件名可能有所不同
formats_table (表)	--list-formats 打印的视频格式表
thumbnails_table (表)	--list-thumbnails 打印的缩略图格式表
subtitles_table (表)	--list-subs 打印的字幕格式表
automatic_captions_table (表)	--list-subs 打印的自动字幕格式表

仅在视频下载后可用 (post_process/after_move)：

字段	描述
filepath	下载的视频文件的实际路径

仅在 --sponsorblock-chapter-title 中可用：

字段	描述
start_time (数字)	章节的开始时间（以秒为单位）
end_time (数字)	章节的结束时间（以秒为单位）
categories (列表)	章节所属的 SponsorBlock 类别
category (字符串)	章节所属的最小 SponsorBlock 类别
category_names (列表)	类别的友好名称
name (字符串)	最小类别的友好名称
type (字符串)	章节的 SponsorBlock 操作类型

在输出模板中引用时，上述每个序列都将替换为与序列名称相对应的实际值。例如，对于 -o %(title)s-%(id)s.%(ext)s 和标题为“yt-dlp 测试视频”且 ID 为 BaW_jenozKc 的 mp4 视频，这将在当前目录中创建一个名为“yt-dlp 测试视频-BaW_jenozKc.mp4”的文件。

注意：某些序列不能保证存在，因为它们取决于特定提取器获取的元数据。此类序列将替换为 --output-na-placeholder 提供的占位符值（默认为 NA）。

提示：查看 -j 输出以确定特定 URL 可用的字段

对于数字序列，您可以使用数字相关的格式；例如 %(view_count)05d 将生成一个用零填充到 5 个字符的查看次数的字符串，例如 00042。

输出模板还可以包含任意分层路径，例如 -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s"，这将导致将每个视频下载到与该路径模板相对应的目录中。任何缺失的目录都将自动为您创建。

要在输出模板中使用百分号文字，请使用 %%。要输出到标准输出，请使用 -o -。

当前默认模板是 %(title)s [%(id)s].%(ext)s。

在某些情况下，您不希望使用特殊字符（例如 中、空格或 &），例如将下载的文件名传输到 Windows 系统或通过 8 位不安全通道传输文件名时。在这些情况下，添加 --restrict-filenames 标志以获取更短的标题。

输出模板示例

$ yt-dlp --print filename -o "test video.%(ext)s" BaW_jenozKc
test video.webm    # 带有正确扩展名的文字名称

$ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc
youtube-dl test video ''_ä↭.webm    # 各种奇怪的字符

$ yt-dlp --print filename -o "%(title)s.%(ext)s" BaW_jenozKc --restrict-filenames
youtube-dl_test_video_.webm    # 受限文件名

# 在单独的目录中下载 YouTube 播放列表视频，按播放列表中的视频顺序索引
$ yt-dlp -o "%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# 根据上传年份在单独的目录中下载 YouTube 播放列表视频
$ yt-dlp -o "%(upload_date>%Y)s/%(title)s.%(ext)s" "https://www.youtube.com/playlist?list=PLwiyx1dc3P2JR9N8gQaQN_BCvlSlap7re"

# 使用“ - ”分隔符为播放列表索引添加前缀，但仅当它可用时
$ yt-dlp -o "%(playlist_index&{} - |)s%(title)s.%(ext)s" BaW_jenozKc "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# 下载 YouTube 频道/用户的所有播放列表，将每个播放列表保存在单独的目录中：
$ yt-dlp -o "%(uploader)s/%(playlist)s/%(playlist_index)s - %(title)s.%(ext)s" "https://www.youtube.com/user/TheLinuxFoundation/playlists"

# 下载 Udemy 课程，将每个章节保存在您主目录的 MyVideos 目录下的单独目录中
$ yt-dlp -u user -p password -P "~/MyVideos" -o "%(playlist)s/%(chapter_number)s - %(chapter)s/%(title)s.%(ext)s" "https://www.udemy.com/java-tutorial"

# 下载整个系列季，将每个系列和每个季保存在 C:/MyVideos 下的单独目录中
$ yt-dlp -P "C:/MyVideos" -o "%(series)s/%(season_number)s - %(season)s/%(episode_number)s - %(episode)s.%(ext)s" "https://videomore.ru/kino_v_detalayah/5_sezon/367617"

# 将视频下载为“C:\MyVideos\uploader\title.ext”，将字幕下载为“C:\MyVideos\subs\uploader\title.ext”
# 并将所有临时文件放在“C:\MyVideos\tmp”中
$ yt-dlp -P "C:/MyVideos" -P "temp:tmp" -P "subtitle:subs" -o "%(uploader)s/%(title)s.%(ext)s" BaW_jenoz --write-subs

# 将视频下载为“C:\MyVideos\uploader\title.ext”，将字幕下载为“C:\MyVideos\uploader\subs\title.ext”
$ yt-dlp -P "C:/MyVideos" -o "%(uploader)s/%(title)s.%(ext)s" -o "subtitle:%(uploader)s/subs/%(title)s.%(ext)s" BaW_jenozKc --write-subs

# 将正在下载的视频流式传输到标准输出
$ yt-dlp -o - BaW_jenozKc

格式选择

默认情况下，如果您不传递任何选项，yt-dlp 会尝试下载最佳可用质量。这通常相当于使用 -f bestvideo*+bestaudio/best。但是，如果启用了多个音频流 (--audio-multistreams)，则默认格式更改为 -f bestvideo+bestaudio/best。同样，如果 ffmpeg 不可用，或者如果您使用 yt-dlp 流式传输到标准输出 (-o -)，则默认值变为 -f best/bestvideo+bestaudio。

弃用警告：最新版本的 yt-dlp 可以使用 ffmpeg 同时将多种格式流式传输到标准输出。因此，在未来的版本中，此默认值将设置为 -f bv*+ba/b，类似于正常的下载。如果您想保留 -f b/bv+ba 设置，建议在配置选项中明确指定它。

格式选择的通用语法是 -f FORMAT（或 --format FORMAT），其中 FORMAT 是选择器表达式，即描述您要下载的一种或多种格式的表达式。

tl;dr：导航我到示例。

最简单的情况是请求特定格式；例如，使用 -f 22，您可以下载格式代码等于 22 的格式。您可以使用 --list-formats 或 -F 获取特定视频的可用格式代码列表。请注意，这些格式代码是特定于提取器的。

您还可以使用文件扩展名（当前支持 3gp、aac、flv、m4a、mp3、mp4、ogg、wav、webm）以下载作为单个文件提供的特定文件扩展名的最佳质量格式，例如 -f webm 将下载作为单个文件提供的具有 webm 扩展名的最佳质量格式。

您可以使用 -f - 以交互方式为每个视频提供格式选择器

您还可以使用特殊名称来选择特定的边缘情况格式：

代码	描述
all	单独选择所有格式
mergeall	选择并合并所有格式（必须与 --audio-multistreams、--video-multistreams 或两者一起使用）
b*、best*	选择包含视频或音频或两者（即；vcodec!=none 或 acodec!=none）的最佳质量格式
b、best	选择包含视频和音频的最佳质量格式。等效于 best*[vcodec!=none][acodec!=none]
bv、bestvideo	选择最佳质量的纯视频格式。等效于 best*[acodec=none]
bv*、bestvideo*	选择包含视频的最佳质量格式。它也可能包含音频。等效于 best*[vcodec!=none]
ba、bestaudio	选择最佳质量的纯音频格式。等效于 best*[vcodec=none]
ba*、bestaudio*	选择包含音频的最佳质量格式。它也可能包含视频。等效于 best*[acodec!=none]（不要使用！）
w*、worst*	选择包含视频或音频的最差质量格式
w、worst	选择包含视频和音频的最差质量格式。等效于 worst*[vcodec!=none][acodec!=none]
wv、worstvideo	选择最差质量的纯视频格式。等效于 worst*[acodec=none]
wv*、worstvideo*	选择包含视频的最差质量格式。它也可能包含音频。等效于 worst*[vcodec!=none]
wa、worstaudio	选择最差质量的纯音频格式。等效于 worst*[vcodec=none]
wa*、worstaudio*	选择包含音频的最差质量格式。它也可能包含视频。等效于 worst*[acodec!=none]

例如，要下载最差质量的纯视频格式，您可以使用 -f worstvideo。但是，建议不要使用 worst 和相关选项。当您的格式选择器是 worst 时，将选择在所有方面都是最差的格式。大多数情况下，您实际想要的是文件大小最小的视频。因此，通常最好使用 -S +size 或更严格地使用 -S +size,+br,+res,+fps 而不是 -f worst。有关更多详细信息，请参阅排序格式。

您可以通过使用 best<type>.<n> 选择第 n 个最佳类型的格式。例如，best.2 将选择第二好的组合格式。类似地，bv*.3 将选择第三好的包含视频流的格式。

如果要下载多个视频，并且它们没有相同的可用格式，则可以使用斜杠指定首选项顺序。请注意，左侧的格式是首选的；例如，-f 22/17/18 将下载格式 22（如果可用），否则将下载格式 17（如果可用），否则将下载格式 18（如果可用），否则将抱怨没有合适的格式可供下载。

如果要下载同一视频的多种格式，请使用逗号作为分隔符，例如 -f 22,17,18 将下载所有这三种格式，当然如果它们可用的话。或者更复杂的示例与优先级功能相结合：-f 136/137/mp4/bestvideo,140/m4a/bestaudio。

您可以使用 -f <format1>+<format2>+... 将多种格式的视频和音频合并到一个文件中（需要安装 ffmpeg）；例如，-f bestvideo+bestaudio 将下载最佳的纯视频格式、最佳的纯音频格式，并使用 ffmpeg 将它们混合在一起。

弃用警告：由于下面描述的行为复杂且违反直觉，因此将在未来删除此行为，并默认启用多流。相反，将添加一个新的运算符来将格式限制为单个音频/视频

除非使用 --video-multistreams，否则将忽略除第一个之外的所有具有视频流的格式。类似地，除非使用 --audio-multistreams，否则将忽略除第一个之外的所有具有音频流的格式。例如，-f bestvideo+best+bestaudio --video-multistreams --audio-multistreams 将下载并合并所有 3 种给定格式。生成的文件将有 2 个视频流和 2 个音频流。但是 -f bestvideo+best+bestaudio --no-video-multistreams 将只下载并合并 bestvideo 和 bestaudio。best 被忽略，因为已经选择了另一个包含视频流的格式 (bestvideo)。因此，格式的顺序很重要。-f best+bestaudio --no-audio-multistreams 将只下载 best，而 -f bestaudio+best --no-audio-multistreams 将忽略 best 并只下载 bestaudio。

过滤格式

您还可以通过将条件放在括号中来过滤视频格式，如 -f "best[height=720]"（或 -f "[filesize>10M]"，因为没有选择器的过滤器被解释为 best）。

以下数字元字段可与比较 <、<=、>、>=、=（等于）、!=（不等于）一起使用：

字段	描述
filesize	字节数，如果事先知道
filesize_approx	字节数的估计值
width	视频宽度（如果已知）
height	视频高度（如果已知）
aspect_ratio	视频的纵横比，如果已知
tbr	音频和视频的平均比特率（以 kbps 为单位）
abr	平均音频比特率（以 kbps 为单位）
vbr	平均视频比特率（以 kbps 为单位）
asr	音频采样率（以赫兹为单位）
fps	帧速率
audio_channels	音频通道数
stretched_ratio	视频像素的宽高比，如果不是正方形

此外，过滤也适用于比较 =（等于）、^=（以…开头）、$=（以…结尾）、*=（包含）、~=（匹配正则表达式）和以下字符串元字段：

字段	描述
url	视频 URL
ext	文件扩展名
acodec	使用的音频编解码器的名称
vcodec	使用的视频编解码器的名称
container	容器格式的名称
protocol	将用于实际下载的协议，小写（http、https、rtsp、rtmp、rtmpe、mms、f4m、ism、http_dash_segments、m3u8 或 m3u8_native）
language	语言代码
dynamic_range	视频的动态范围
format_id	格式的简短描述
format	格式的人类可读描述
format_note	有关格式的其他信息
resolution	宽度和高度的文本描述

任何字符串比较都可以以否定 ! 为前缀，以产生相反的比较，例如 !*=（不包含）。如果字符串比较的比较对象包含空格或 ._-. 以外的特殊字符，则需要用双引号或单引号将其引起来。

注意：不能保证上述任何元字段都存在，因为这完全取决于特定提取器获取的元数据，即网站提供的元数据。提取器提供的任何其他字段也可以用于过滤。

除非您在运算符后放置一个问号 (?)，否则将排除未知值的格式。您可以组合格式过滤器，因此 -f "bv[height<=?720][tbr>500]" 选择高达 720p 的视频（或未知高度的视频），比特率至少为 500 kbps。您还可以将过滤器与 all 一起使用以下载满足过滤器的所有格式，例如 -f "all[vcodec=none]" 选择所有纯音频格式。

格式选择器也可以使用括号进行分组；例如 -f "(mp4,webm)[height<480]" 将下载高度低于 480 的最佳预合并 mp4 和 webm 格式。

排序格式

您可以使用 -S (--format-sort) 更改被视为最佳的标准。此操作的通用格式为 --format-sort field1,field2...。

可用的字段是：

字段	描述
hasvid	优先考虑具有视频流的格式
hasaud	优先考虑具有音频流的格式
ie_pref	格式首选项
lang	语言首选项
quality	格式的质量
source	来源的首选项
proto	用于下载的协议（https/ftps > http/ftp > m3u8_native/m3u8 > http_dash_segments> websocket_frag > mms/rtsp > f4f/f4m）
vcodec	视频编解码器 (av01 > vp9.2 > vp9 > h265 > h264 > vp8 > h263 > theora > other)
acodec	音频编解码器 (flac/alac > wav/aiff > opus > vorbis > aac > mp4a > mp3 > ac4 > eac3 > ac3 > dts > other)
codec	等效于 vcodec,acodec
vext	视频扩展名 (mp4 > mov > webm > flv > other)。如果使用 --prefer-free-formats，则首选 webm。
aext	音频扩展名 (m4a > aac > mp3 > ogg > opus > webm > other)。如果使用 --prefer-free-formats，则顺序更改为 ogg > opus > webm > mp3 > m4a > aac
ext	等效于 vext,aext
filesize	确切的文件大小，如果事先知道
fs_approx	大概的文件大小
size	如果可用，则为确切的文件大小，否则为大概的文件大小
height	视频高度
width	视频宽度
res	视频分辨率，计算为最小尺寸。
fps	视频的帧率
hdr	视频的动态范围（DV > HDR12 > HDR10+ > HDR10 > HLG > SDR）
channels	音频通道数
tbr	总平均比特率（以 kbps 为单位）
vbr	平均视频比特率（以 kbps 为单位）
abr	平均音频比特率（以 kbps 为单位）
br	平均比特率（以 kbps 为单位），tbr/vbr/abr
asr	音频采样率（以赫兹为单位）

弃用警告：其中许多字段都有（当前未记录的）别名，这些别名可能会在将来的版本中删除。建议仅使用记录的字段名称。

除非另有说明，否则所有字段都按降序排序。要反转此顺序，请在字段前添加 +。例如，+res 首选分辨率最小的格式。此外，您可以为字段添加一个首选值后缀，以 : 分隔。例如，res:720 首选较大的视频，但不超过 720p，如果没有小于 720p 的视频，则首选最小的视频。对于编解码器和扩展名，您可以提供两个首选值，第一个用于视频，第二个用于音频。例如，+codec:avc:m4a（等效于 +vcodec:avc,+acodec:m4a）将视频编解码器首选项设置为 h264 > h265 > vp9 > vp9.2 > av01 > vp8 > h263 > theora，将音频编解码器首选项设置为 mp4a > aac > vorbis > opus > mp3 > ac3 > dts。您还可以通过使用 ~ 作为分隔符来使排序首选与提供的最接近的值。例如，filesize~1G 首选文件大小最接近 1 GiB 的格式。

无论用户定义的顺序如何，字段 hasvid 和 ie_pref 在排序中始终具有最高优先级。可以使用 --format-sort-force 更改此行为。除此之外，使用的默认顺序是：lang,quality,res,fps,hdr:12,vcodec:vp9.2,channels,acodec,size,br,asr,proto,ext,hasaud,source,id。提取器可以覆盖此默认顺序，但它们不能覆盖用户提供的顺序。

请注意，默认值包含 vcodec:vp9.2；即不首选 av1。类似地，hdr 的默认值为 hdr:12；即不首选杜比视界。做出这些选择是因为 DV 和 AV1 格式尚不能与大多数设备完全兼容。随着更多设备能够流畅地播放这些格式，这种情况将来可能会发生变化。

如果您的格式选择器是 worst，则在排序后选择最后一个项目。这意味着它将选择在所有方面都是最差的格式。大多数情况下，您实际想要的是文件大小最小的视频。因此，通常最好使用 -f best -S +size,+br,+res,+fps。

提示：您可以使用 -v -F 查看格式的排序方式（从最差到最好）。

格式选择示例

# 下载并合并最佳的纯视频格式和最佳的纯音频格式，
# 或者如果纯视频格式不可用，则下载最佳的组合格式
$ yt-dlp -f "bv+ba/b"

# 下载包含视频的最佳格式，
# 如果它还没有音频流，则将其与最佳的纯音频格式合并
$ yt-dlp -f "bv*+ba/b"

# 与上面相同
$ yt-dlp

# 下载最佳的纯视频格式和最佳的纯音频格式，而不合并它们
# 在这种情况下，应该使用输出模板，因为
# 默认情况下，bestvideo 和 bestaudio 将具有相同的文件名。
$ yt-dlp -f "bv,ba" -o "%(title)s.f%(format_id)s.%(ext)s"

# 下载并合并具有视频流的最佳格式，
# 以及所有纯音频格式到一个文件中
$ yt-dlp -f "bv*+mergeall[vcodec=none]" --audio-multistreams

# 下载并合并具有视频流的最佳格式，
# 以及最好的 2 种纯音频格式到一个文件中
$ yt-dlp -f "bv*+ba+ba.2" --audio-multistreams


# 以下示例显示了旧的格式选择方法（不使用 -S）
# 以及如何使用 -S 来实现类似但（通常）更好的结果

# 下载可用的最差视频（旧方法）
$ yt-dlp -f "wv*+wa/w"

# 下载可用的最佳视频，但分辨率最小
$ yt-dlp -S "+res"

# 下载可用的最小视频
$ yt-dlp -S "+size,+br"



# 下载可用的最佳 mp4 视频，或者如果没有 mp4 可用，则下载最佳视频
$ yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4] / bv*+ba/b"

# 下载扩展名最好的最佳视频
# （对于视频，mp4 > mov > webm > flv。对于音频，m4a > aac > mp3 ...）
$ yt-dlp -S "ext"



# 下载可用的最佳视频，但不超过 480p，
# 或者如果没有低于 480p 的视频，则下载最差的视频
$ yt-dlp -f "bv*[height<=480]+ba/b[height<=480] / wv*+ba/w"

# 下载可用的高度最大但不超过 480p 的最佳视频，
# 或者如果没有低于 480p 的视频，则下载分辨率最小的最佳视频
$ yt-dlp -S "height:480"

# 下载分辨率最大但不超过 480p 的最佳视频，
# 或者如果没有低于 480p 的视频，则下载分辨率最小的最佳视频
# 分辨率是通过使用最小尺寸来确定的。
# 所以这也适用于垂直视频
$ yt-dlp -S "res:480"



# 下载不超过 50 MB 的最佳视频（也包含音频），
# 或者如果没有低于 50 MB 的视频，则下载最差的视频（也包含音频）
$ yt-dlp -f "b[filesize<50M] / w"

# 下载不超过 50 MB 的最大视频（也包含音频），
# 或者如果没有低于 50 MB 的视频，则下载最小的视频（也包含音频）
$ yt-dlp -f "b" -S "filesize:50M"

# 下载大小最接近 50 MB 的最佳视频（也包含音频）
$ yt-dlp -f "b" -S "filesize~50M"



# 通过 HTTP/HTTPS 协议上的直接链接下载可用的最佳视频，
# 或者如果没有这样的视频，则下载通过任何协议可用的最佳视频
$ yt-dlp -f "(bv*+ba/b)[protocol^=http][protocol!*=dash] / (bv*+ba/b)"

# 下载通过最佳协议可用的最佳视频
# (https/ftps > http/ftp > m3u8_native > m3u8 > http_dash_segments ...)
$ yt-dlp -S "proto"



# 下载具有 h264 或 h265 编解码器的最佳视频，
# 或者如果没有这样的视频，则下载最佳视频
$ yt-dlp -f "(bv*[vcodec~='^((he|a)vc|h26[45])']+ba) / (bv*+ba/b)"

# 下载编解码器不超过 h264 的最佳视频，
# 或者如果没有这样的视频，则下载编解码器最差的最佳视频
$ yt-dlp -S "codec:h264"

# 下载编解码器不低于 h264 的最差视频，
# 或者如果没有这样的视频，则下载编解码器最好的最佳视频
$ yt-dlp -S "+codec:h264"



# 更复杂的示例

# 下载不超过 720p 的最佳视频，首选帧率大于 30 的视频，
# 或者如果没有这样的视频，则下载最差的视频（仍然首选帧率大于 30 的视频）
$ yt-dlp -f "((bv*[fps>30]/bv*)[height<=720]/(wv*[fps>30]/wv*)) + ba / (b[fps>30]/b)[height<=720]/(w[fps>30]/w)"

# 下载分辨率最大但不超过 720p 的视频，
# 或者如果没有这样的视频，则下载可用的分辨率最小的视频，
# 对于具有相同分辨率的格式，首选较大的帧率
$ yt-dlp -S "res:720,fps"



# 下载分辨率最小但不低于 480p 的视频，
# 或者如果没有这样的视频，则下载可用的分辨率最大的视频，
# 对于相同分辨率的格式，首选更好的编解码器，然后是更大的总比特率
$ yt-dlp -S "+res:480,codec,br"

修改元数据

可以使用 --parse-metadata 和 --replace-in-metadata 修改提取器获取的元数据

--replace-in-metadata FIELDS REGEX REPLACE 用于使用 Python 正则表达式替换任何元数据字段中的文本。可以在替换字符串中使用反向引用以进行高级使用。

--parse-metadata FROM:TO 的通用语法是提供字段的名称或要从中提取数据的输出模板，以及要将其解释为的格式，以冒号 : 分隔。可以使用具有命名捕获组的 Python 正则表达式、单个字段名称或类似于输出模板的语法（仅支持 %(field)s 格式）作为 TO。该选项可以多次使用以解析和修改各种字段。

请注意，这些选项保留它们的相对顺序，允许在解析的字段中进行替换，反之亦然。此外，如此创建的任何字段都可以在输出模板中使用，并且还会影响使用 --embed-metadata 时添加到媒体文件的元数据。

此选项还有一些特殊用途：

• 您可以根据当前下载的视频的元数据下载额外的 URL。为此，请将 additional_urls 字段设置为要下载的 URL。例如，--parse-metadata "description:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" 将下载描述中找到的第一个 vimeo 视频
• 您可以使用此选项更改嵌入在媒体文件中的元数据。为此，请使用 meta_ 前缀设置相应字段的值。例如，您设置给 meta_description 字段的任何值都将添加到文件中的 description 字段 - 您可以使用此选项设置不同的“description”和“synopsis”。要修改单个流的元数据，请使用 meta_ 前缀（例如 meta1_language）。设置给 meta_ 字段的任何值都将覆盖所有默认值。

注意：元数据修改发生在格式选择、提取后和其他后处理操作之前。在这些步骤中可能会添加或更改某些字段，从而覆盖您的更改。

供参考，以下是 yt-dlp 默认添加到文件元数据中的字段：

元数据字段	来自
title	track 或 title
date	upload_date
description, synopsis	description
purl, comment	webpage_url
track	track_number
artist	artist、artists、creator、creators、uploader 或 uploader_id
composer	composer 或 composers
genre	genre 或 genres
album	album
album_artist	album_artist 或 album_artists
disc	disc_number
show	series
season_number	season_number
episode_id	episode 或 episode_id
episode_sort	episode_number
每个流的语言	格式的语言

注意：文件格式可能不支持其中一些字段

修改元数据示例

# 将标题解释为“艺术家 - 标题”
$ yt-dlp --parse-metadata "title:%(artist)s - %(title)s"

# 正则表达式示例
$ yt-dlp --parse-metadata "description:Artist - (?P<artist>.+)"

# 将标题设置为“系列名称 S01E05”
$ yt-dlp --parse-metadata "%(series)s S%(season_number)02dE%(episode_number)02d:%(title)s"

# 在视频元数据中优先使用上传者作为“艺术家”字段
$ yt-dlp --parse-metadata "%(uploader|)s:%(meta_artist)s" --embed-metadata

# 使用描述而不是 webpage_url 设置视频元数据中的“评论”字段，
# 正确处理多行
$ yt-dlp --parse-metadata "description:(?s)(?P<meta_comment>.+)" --embed-metadata

# 不要在视频元数据中设置任何“概要”
$ yt-dlp --parse-metadata ":(?P<meta_synopsis>)"

# 通过将其设置为空字符串从 infojson 中删除“格式”字段
$ yt-dlp --parse-metadata "video::(?P<formats>)" --write-info-json

# 将标题和上传者中的所有空格和“_”替换为“-”
$ yt-dlp --replace-in-metadata "title,uploader" "[ _]" "-"

提取器参数

某些提取器接受可以使用 --extractor-args KEY:ARGS 传递的附加参数。ARGS 是一个以 ;（分号）分隔的 ARG=VAL1,VAL2 字符串。例如，--extractor-args "youtube:player-client=android_embedded,web;formats=incomplete" --extractor-args "funimation:version=uncut"

注意：在 CLI 中，ARG 可以使用 - 而不是 _；例如 youtube:player-client 变为 youtube:player_client

以下提取器使用此功能：

youtube

参数	描述
lang	首选此语言代码的翻译元数据（标题、描述等）（区分大小写）。默认情况下，首选视频主要语言元数据，回退到英文翻译。有关支持的内容语言代码列表，请参阅 youtube.py
skip	hls、dash 或 translated_subs 中的一个或多个，以分别跳过 m3u8 清单、dash 清单和自动翻译的字幕的提取
player_client	要从中提取视频数据的客户端。主要客户端是 web、ios 和 android，具有变体 _music、_embedded、_embedscreen、_creator（例如 web_embedded）；以及没有变体的 mweb、mweb_embedscreen 和 tv_embedded（年龄门绕过）。默认情况下，使用 ios,web，但根据需要为年龄门控视频添加 tv_embedded 和 creator 变体。类似地，为 music.youtube.com 网址添加音乐变体。android 客户端始终具有最低优先级，因为它们的格式已损坏。您可以使用 all 来使用所有客户端，并使用 default 来使用默认客户端。
player_skip	跳过一些通常需要进行稳健提取的网络请求。configs（跳过客户端配置）、webpage（跳过初始网页）、js（跳过 js 播放器）中的一个或多个。虽然这些选项可以帮助减少所需的请求数量或避免某些速率限制，但它们可能会导致一些问题。有关更多详细信息，请参阅 #860
player_params	用于播放器请求的 YouTube 播放器参数。将覆盖 yt-dlp 设置的任何默认参数。
comment_sort	top 或 new（默认） - 选择评论排序模式（在 YouTube 端）
max_comments	限制要收集的评论数量。表示 max-comments、max-parents、max-replies、max-replies-per-thread 的逗号分隔的整数列表。默认值为 all,all,all,all 例如，all,all,1000,10 将最多获得 1000 个回复，每个线程最多 10 个回复。1000,all,100 将最多获得 1000 条评论，总共最多 100 条回复
formats	更改要返回的格式类型。dashy（将 HTTP 转换为 DASH）、duplicate（相同内容但不同的 URL 或协议；包括 dashy）、incomplete（无法完全下载 - 直播 dash 和直播后 m3u8）
innertube_host	用于所有 API 请求的 Innertube API 主机；例如 studio.youtube.com、youtubei.googleapis.com。请注意，从一个子域导出的 cookie 在其他子域上不起作用
innertube_key	用于所有 API 请求的 Innertube API 密钥
raise_incomplete_data	收到不完整数据会引发错误而不是报告警告

youtubetab（YouTube 播放列表、频道、订阅源等）

参数	描述
skip	webpage（跳过初始网页下载）、authcheck（在没有下载初始网页时允许下载需要身份验证的播放列表。这可能会导致不希望的行为，有关更多详细信息，请参阅 #1122）中的一个或多个
approximate_date	在 flat-playlist 中提取近似的 upload_date 和时间戳。这可能会导致基于日期的过滤器略有偏差

generic

参数	描述
fragment_query	如果没有提供任何值，则将 mpd/m3u8 清单 URL 中的任何查询传递到其片段，否则应用作为 fragment_query=VALUE 给出的查询字符串。不适用于 ffmpeg
variant_query	如果没有提供任何值，则将主 m3u8 URL 查询传递到其变体播放列表 URL，否则应用作为 variant_query=VALUE 给出的查询字符串。
hls_key	HLS AES-128 密钥 URI 或密钥（十六进制），以及可选的 IV（十六进制），格式为 (URI
is_live	绕过直播 HLS 检测并手动设置 live_status - false 值将设置 not_live，任何其他值（或没有值）将设置 is_live

funimation

参数	描述
language	要提取的音频语言，例如 funimation:language=english,japanese
version	要提取的视频版本 - uncut 或 simulcast

crunchyrollbeta（Crunchyroll）

参数	描述
hardsub	要提取的一个或多个硬字幕版本（按首选项顺序），或 all（默认值：None = 不会提取任何硬字幕），例如 crunchyrollbeta:hardsub=en-US,de-DE

vikichannel

参数	描述
video_types	要下载的视频类型 - episodes、movies、clips、trailers 中的一个或多个

niconico

参数	描述
segment_duration	HLS-DMC 格式的片段持续时间（以毫秒为单位）。使用它需要您自担风险，因为此功能可能会导致您的帐户被终止。

youtubewebarchive

参数	描述
check_all	尝试以更多请求为代价进行更多检查。缩略图、捕获中的一个或多个

gamejolt

参数	描述
comment_sort	hot（默认）、you（需要 cookie）、top、new - 选择评论排序模式（在 GameJolt 端）

hotstar

参数	描述
res	要忽略的分辨率 - sd、hd、fhd 中的一个或多个
vcodec	要忽略的视频编解码器 - h264、h265、dvh265 中的一个或多个
dr	要忽略的动态范围 - sdr、hdr10、dv 中的一个或多个

niconicochannelplus

参数	描述
max_comments	要提取的最大评论数 - 默认值为 120

tiktok

参数	描述
api_hostname	用于移动 API 调用的主机名，例如 api22-normal-c-alisg.tiktokv.com
app_name	用于移动 API 调用的默认应用程序名称，例如 trill
app_version	用于移动 API 调用的默认应用程序版本 - 应与 manifest_app_version 一起设置，例如 34.1.2
manifest_app_version	用于移动 API 调用的默认数字应用程序版本，例如 2023401020
aid	用于移动 API 调用的默认应用程序 ID，例如 1180
app_info	使用一种或多种应用程序信息字符串启用移动 API 提取，格式为 /[app_name]/[app_version]/[manifest_app_version]/[aid]，其中 iid 是唯一的应用程序安装 ID。iid 是唯一必需的值；所有其他值及其 / 分隔符都可以省略，例如 tiktok:app_info=1234567890123456789 或 tiktok:app_info=123,456/trill///1180,789//34.0.1/340001
device_id	使用用于移动 API 调用的真正设备 ID 启用移动 API 提取。默认值是一个随机的 19 位字符串

rokfinchannel

参数	描述
tab	要下载哪个选项卡 - new、top、videos、podcasts、streams、stacks 中的一个

twitter

参数	描述
api	选择 graphql（默认）、legacy 或 syndication 中的一个作为推特提取的 API。如果已登录，则无效

stacommu, wrestleuniverse

参数	描述
device_id	网站分配的 UUID 值，用于对付费直播内容强制执行设备限制。可以在浏览器本地存储中找到

twitch

参数	描述
client_id	要与 GraphQL 请求一起发送的客户端 ID 值，例如 twitch:client_id=kimne78kx3ncx6brgo4mv6wki5h1ko

nhkradirulive（NHK らじる★らじる LIVE）

参数	描述
area	要提取哪个区域变体。有效区域是：sapporo、sendai、tokyo、nagoya、osaka、hiroshima、matsuyama、fukuoka。默认为 tokyo

nflplusreplay

参数	描述
type	要提取的游戏重播类型。有效类型是：full_game、full_game_spanish、condensed_game 和 all_22。您可以使用 all 来提取所有可用的重播类型，这是默认设置

jiocinema

参数	描述
refresh_token	可以传递浏览器本地存储中的 refreshToken UUID，以便在使用令牌作为用户名和浏览器本地存储中的 accessToken 作为密码登录时延长登录会话的寿命

jiosaavn

参数	描述
bitrate	要请求的音频比特率。16、32、64、128、320 中的一个或多个。默认值为 128,320

afreecatvlive

参数	描述
cdn	要与流 URL 的 API 调用一起使用的一个或多个 CDN ID，例如 gcp_cdn、gs_cdn_pc_app、gs_cdn_mobile_web、gs_cdn_pc_web

soundcloud

参数	描述
formats	从 API 请求的格式。请求的值应采用 {protocol}_{extension} 的格式（省略比特率），例如 hls_opus、http_aac。* 字符用作通配符，例如 *_mp3，并且可以单独传递以请求所有格式。已知协议包括 http、hls 和 hls-aes；已知扩展名包括 aac、opus 和 mp3。始终提取原始下载格式。默认值为 http_aac,hls_aac,http_opus,hls_opus,http_mp3,hls_mp3

注意：将来可能会更改/删除这些选项，而无需考虑向后兼容性

插件

请注意，即使未调用，也会导入所有插件，并且不会对插件代码执行任何检查。使用插件需要您自担风险，并且仅在您信任代码时使用！

插件可以是 s 提取器或后期处理器。

• 提取器插件不需要从 CLI 启用，并且在输入 URL 适合时会自动调用。
• 提取器插件优先于内置提取器。
• 可以使用 --use-postprocessor NAME 调用后期处理器插件。

插件从命名空间包 yt_dlp_plugins.extractor 和 yt_dlp_plugins.postprocessor 加载。

换句话说，磁盘上的文件结构如下所示：

    yt_dlp_plugins/
        extractor/
            myplugin.py
        postprocessor/
            myplugin.py

yt-dlp 在许多位置（见下文）搜索这些 yt_dlp_plugins 命名空间文件夹，并从所有这些文件夹中加载插件。

有关一些已知插件，请参阅 wiki

安装插件

可以使用各种方法和位置安装插件。

配置目录： 插件包（包含 yt_dlp_plugins 命名空间文件夹）可以放入以下标准配置位置：

• 用户插件
  • ${XDG_CONFIG_HOME}/yt-dlp/plugins//yt_dlp_plugins/（推荐用于 Linux/macOS）
  • ${XDG_CONFIG_HOME}/yt-dlp-plugins//yt_dlp_plugins/
  • ${APPDATA}/yt-dlp/plugins//yt_dlp_plugins/（推荐用于 Windows）
  • ${APPDATA}/yt-dlp-plugins//yt_dlp_plugins/
  • ~/.yt-dlp/plugins//yt_dlp_plugins/
  • ~/yt-dlp-plugins//yt_dlp_plugins/
• 系统插件
  • /etc/yt-dlp/plugins//yt_dlp_plugins/
  • /etc/yt-dlp-plugins//yt_dlp_plugins/

可执行文件位置： 插件包可以类似地安装在可执行文件位置下的 yt-dlp-plugins 目录中（推荐用于便携式安装）：

• 二进制文件：其中 /yt-dlp.exe、/yt-dlp-plugins//yt_dlp_plugins/
• 源代码：其中 /yt_dlp/main.py、/yt-dlp-plugins//yt_dlp_plugins/

pip 和 PYTHONPATH 中的其他位置

• 可以使用 pip 安装和管理插件包。请参阅 yt-dlp-sample-plugins 作为示例。 注意：使用 pip 安装的插件包之间的插件文件必须具有唯一的文件名。
• 在 PYTHONPATH 中的任何路径中搜索 yt_dlp_plugins 命名空间文件夹。 注意：这不适用于 Pyinstaller/py2exe 构建。
• 还支持在其根目录中包含 yt_dlp_plugins 命名空间文件夹的 .zip、.egg 和 .whl 存档作为插件包。

例如 ${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip，其中 mypluginpkg.zip 包含 yt_dlp_plugins//myplugin.py 使用 --verbose 运行 yt-dlp 以检查插件是否已加载。

开发插件

请参阅 yt-dlp-sample-plugins 存储库以获取模板插件包，以及 wiki 的插件开发部分以获取插件开发指南。

所有名称以 IE/PP 结尾的公共类分别从每个文件导入提取器和后期处理器。这尊重下划线前缀（例如 _MyBasePluginIE 是私有的）和 all。模块可以通过在模块名称前添加下划线（例如 _myplugin.py）来类似地排除。

要使用一个的子类替换现有的提取器，请设置 plugin_name 类关键字参数（例如 class MyPluginIE(ABuiltInIE, plugin_name='myplugin') 将用 MyPluginIE 替换 ABuiltInIE）。由于提取器替换了父级，因此您应该通过使用上述方法之一将其设为私有来排除子类提取器被单独导入。

如果您是插件作者，请将 yt-dlp-plugins 添加为存储库的主题以提高可发现性。

有关如何编写和测试提取器的说明，请参阅开发人员说明。

嵌入 YT-DLP

yt-dlp 尽力成为一个好的命令行程序，因此应该可以从任何编程语言中调用。

您的程序应避免解析正常的标准输出，因为它们在将来的版本中可能会更改。相反，他们应该使用 -J、--print、--progress-template、--exec 等选项来创建您可以可靠地复制和解析的控制台输出。

从 Python 程序中，您可以以更强大的方式嵌入 yt-dlp，如下所示：

from yt_dlp import YoutubeDL

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']
with YoutubeDL() as ydl:
    ydl.download(URLS)

您很可能想要使用各种选项。有关可用选项的列表，请在 Python shell 中查看 yt_dlp/YoutubeDL.py 或 help(yt_dlp.YoutubeDL)。如果您已经熟悉 CLI，可以使用 devscripts/cli_to_api.py 将任何 CLI 开关转换为 YoutubeDL 参数。

提示：如果您要将代码从 youtube-dl 移植到 yt-dlp，需要注意的一点是，我们不保证 YoutubeDL.extract_info 的返回值是 json 可序列化的，甚至是一个字典。它将类似于字典，但如果您想确保它是一个可序列化的字典，请通过 YoutubeDL.sanitize_info 传递它，如下面的示例所示

嵌入示例

提取信息

import json
import yt_dlp

URL = 'https://www.youtube.com/watch?v=BaW_jenozKc'

# ℹ️ 有关可用选项和公共函数的列表，请参阅 help(yt_dlp.YoutubeDL)
ydl_opts = {}
with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    info = ydl.extract_info(URL, download=False)

    # ℹ️ ydl.sanitize_info 使信息 json 可序列化
    print(json.dumps(ydl.sanitize_info(info)))

使用 info-json 下载

import yt_dlp

INFO_FILE = 'path/to/video.info.json'

with yt_dlp.YoutubeDL() as ydl:
    error_code = ydl.download_with_info_file(INFO_FILE)

print('某些视频未能下载' if error_code
      else '所有视频均已成功下载')

提取音频

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

ydl_opts = {
    'format': 'm4a/bestaudio/best',
    # ℹ️ 有关可用后期处理器及其参数的列表，请参阅 help(yt_dlp.postprocessor)
    'postprocessors': [{  # 使用 ffmpeg 提取音频
        'key': 'FFmpegExtractAudio',
        'preferredcodec': 'm4a',
    }]
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)

过滤视频

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

def longer_than_a_minute(info, *, incomplete):
    """仅下载超过一分钟的视频（或持续时间未知的视频）"""
    duration = info.get('duration')
    if duration and duration < 60:
        return '视频太短'

ydl_opts = {
    'match_filter': longer_than_a_minute,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    error_code = ydl.download(URLS)

添加记录器和进度钩子

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

class MyLogger:
    def debug(self, msg):
        # 为了与 youtube-dl 兼容，debug 和 info 都传递给 debug
        # 您可以通过前缀“[debug]”来区分它们
        if msg.startswith('[debug] '):
            pass
        else:
            self.info(msg)

    def info(self, msg):
        pass

    def warning(self, msg):
        pass

    def error(self, msg):
        print(msg)


# ℹ️ 有关“progress_hooks”的更多信息，请参阅 help(yt_dlp.YoutubeDL)
def my_hook(d):
    if d['status'] == 'finished':
        print('下载完成，现在正在进行后期处理...')


ydl_opts = {
    'logger': MyLogger(),
    'progress_hooks': [my_hook],
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)

添加自定义后期处理器

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

# ℹ️ 有关更多信息，请参阅 help(yt_dlp.postprocessor.PostProcessor)
class MyCustomPP(yt_dlp.postprocessor.PostProcessor):
    def run(self, info):
        self.to_screen('正在做一些事情')
        return [], info


with yt_dlp.YoutubeDL() as ydl:
    # ℹ️ “when”可以采用 yt_dlp.utils.POSTPROCESS_WHEN 中的任何值
    ydl.add_post_processor(MyCustomPP(), when='pre_process')
    ydl.download(URLS)

使用自定义格式选择器

import yt_dlp

URLS = ['https://www.youtube.com/watch?v=BaW_jenozKc']

def format_selector(ctx):
    """ 选择不会导致 mkv 的最佳视频和最佳音频。
    注意：这只是一个示例，并不处理所有情况 """

    # 格式已经从最差到最好排序
    formats = ctx.get('formats')[::-1]

    # acodec='none' 表示没有音频
    best_video = next(f for f in formats
                      if f['vcodec'] != 'none' and f['acodec'] == 'none')

    # 找到兼容的音频扩展名
    audio_ext = {'mp4': 'm4a', 'webm': 'webm'}[best_video['ext']]
    # vcodec='none' 表示没有视频
    best_audio = next(f for f in formats if (
        f['acodec'] != 'none' and f['vcodec'] == 'none' and f['ext'] == audio_ext))

    # 这些是合并格式所需的最小字段
    yield {
        'format_id': f'{best_video["format_id"]}+{best_audio["format_id"]}',
        'ext': best_video['ext'],
        'requested_formats': [best_video, best_audio],
        # 必须是 + 分隔的协议列表
        'protocol': f'{best_video["protocol"]}+{best_audio["protocol"]}'
    }


ydl_opts = {
    'format': format_selector,
}

with yt_dlp.YoutubeDL(ydl_opts) as ydl:
    ydl.download(URLS)

与 YOUTUBE-DL 的区别

新功能

从 yt-dlc@f9401f2 分支并与 youtube-dl@a08f2b7 合并（例外）

• SponsorBlock 集成： 您可以利用 SponsorBlock API 标记/删除 YouTube 视频中的赞助部分
• 格式排序： 默认格式排序选项已更改，因此现在将首选更高分辨率和更好的编解码器，而不是简单地使用更大的比特率。此外，您现在可以使用 -S 指定排序顺序。这使得格式选择比仅使用 --format 容易得多（示例）
• 与 animelover1984/youtube-dl 合并： 您将获得 animelover1984/youtube-dl 中的大部分功能和改进，包括 --write-comments、BiliBiliSearch、BilibiliChannel、将缩略图嵌入 mp4/ogg/opus、播放列表 infojson 等。请注意，NicoNico 直播不可用。有关详细信息，请参阅 #31。
• YouTube 改进：
  • 支持剪辑、故事 (ytstories:)、搜索（包括过滤器） 、YouTube 音乐搜索、特定于频道的搜索、搜索前缀 (ytsearch:、ytsearchdate:) 、混音和订阅源 (:ytfav、:ytwatchlater、:ytsubs、:ythistory、:ytrec、:ytnotif)
  • 修复了基于 n-sig 的节流 *
  • 支持某些（但不是全部）年龄门控内容，无需 cookie
  • 使用 --live-from-start 从一开始就下载直播（实验性）
  • 频道 URL 下载频道的所有上传内容，包括短片和直播
• 浏览器中的 Cookie： 可以使用 --cookies-from-browser BROWSER[+KEYRING][:PROFILE][::CONTAINER] 从所有主要 Web 浏览器中自动提取 Cookie
• 下载时间范围： 可以使用 --download-sections 根据时间戳或章节部分下载视频
• 按章节拆分视频： 可以使用 --split-chapters 根据章节将视频拆分为多个文件
• 多线程片段下载： 并行下载 m3u8/mpd 视频的多个片段。使用 --concurrent-fragments (-N) 选项设置使用的线程数
• 带有 HLS/DASH 的 Aria2c： 您可以将 aria2c 用作 DASH(mpd) 和 HLS(m3u8) 格式的外部下载器
• 新的和修复的提取器： 添加了许多新的提取器，并修复了许多现有的提取器。请参阅更改日志或支持的网站列表
• 新的 MSO： Philo、Spectrum、SlingTV、Cablevision、RCN 等
• 从清单中提取字幕： 可以从流媒体清单中提取字幕。有关详细信息，请参阅 commit/be6202f
• 多路径和输出模板： 您可以为不同类型的文件提供不同的输出模板和下载路径。您还可以使用 --paths (-P) 设置下载中间文件的临时路径
• 便携式配置： 配置文件会自动从主目录和根目录加载。有关详细信息，请参阅配置
• 输出模板改进： 输出模板现在可以进行日期时间格式化、数字偏移、对象遍历等。有关详细信息，请参阅输出模板。借助 --parse-metadata 和 --replace-in-metadata，还可以执行更高级的操作
• 其他新选项： 添加了许多新选项，例如 --alias、--print、--concat-playlist、--wait-for-video、--retry-sleep、--sleep-requests、--convert-thumbnails、--force-download-archive、--force-overwrites、--break-match-filter 等
• 改进：--format/--match-filter 中的正则表达式和其他运算符、多个 --postprocessor-args 和 --downloader-args、更快的存档检查、更多格式选择选项、合并多视频/音频、多个 --config-locations、不同阶段的 --exec 等
• 插件： 可以从外部文件加载提取器和后期处理器。有关详细信息，请参阅插件
• 自动更新器： 可以使用 yt-dlp -U 更新版本，并在需要时使用 --update-to 降级
• 自动构建： 可以使用 --update-to nightly 和 --update-to master 使用夜间/主线构建

有关更改的完整列表，请参阅更改日志或提交

• 标记的特性已向后移植到 youtube-dl

默认行为的差异

yt-dlp 的某些默认选项与 youtube-dl 和 youtube-dlc 的默认选项不同：

• yt-dlp 仅支持 Python 3.8+，并且可能会在更多版本达到 EOL 时删除对它们的支持；而 youtube-dl 仍然支持 Python 2.6+ 和 3.2+
• 选项 --auto-number (-A)、--title (-t) 和 --literal (-l) 不再起作用。有关详细信息，请参阅已删除选项
• avconv 不受支持，不能替代 ffmpeg
• yt-dlp 将配置文件存储在与 youtube-dl 略有不同的位置。有关正确位置的列表，请参阅配置
• 默认输出模板是 %(title)s [%(id)s].%(ext)s。此更改没有真正的原因。这是在 yt-dlp 公开之前更改的，现在没有计划将其改回 %(title)s-%(id)s.%(ext)s。相反，您可以使用 --compat-options filename
• 默认格式排序与 youtube-dl 不同，它首选更高分辨率和更好的编解码器，而不是更高的比特率。您可以使用 --format-sort 选项将其更改为任何您喜欢的顺序，或使用 --compat-options format-sort 使用 youtube-dl 的排序顺序
• 默认格式选择器是 bv*+ba/b。这意味着如果找到比最佳纯视频格式更好的组合视频 + 音频格式，则首选前者。使用 -f bv+ba/b 或 --compat-options format-spec 恢复此设置
• 与 youtube-dlc 不同，默认情况下 yt-dlp 不允许将多个音频/视频流合并到一个文件中（因为这与 -f bv*+ba 的使用冲突）。如果需要，必须使用 --audio-multistreams 和 --video-multistreams 启用此功能。您还可以使用 --compat-options multistreams 启用两者
• 默认情况下启用 --no-abort-on-error。使用 --abort-on-error 或 --compat-options abort-on-error 在出错时中止
• 在写入元数据文件（例如缩略图、描述或 infojson）时，还会为播放列表写入相同的信息（如果可用）。使用 --no-write-playlist-metafiles 或 --compat-options no-playlist-metafiles 不写入这些文件
• --add-metadata 除了在与 --write-info-json 一起使用时写入元数据外，还会将 infojson 附加到 mkv 文件。使用 --no-embed-info-json 或 --compat-options no-attach-info-json 恢复此设置
• 使用 --add-metadata 时，与 youtube-dl 相比，某些元数据嵌入到不同的字段中。最值得注意的是，comment 字段包含 webpage_url，synopsis 包含 description。您可以使用 --parse-metadata 将其修改为您的喜好，或使用 --compat-options embed-metadata 恢复此设置
• playlist_index 在与 --playlist-reverse 和 --playlist-items 等选项一起使用时的行为有所不同。有关详细信息，请参阅 #302。如果您想保留之前的行为，可以使用 --compat-options playlist-index
• -F 的输出以新格式列出。使用 --compat-options list-formats 恢复此设置
• 直播聊天（如果可用）被视为字幕。使用 --sub-langs all,-live_chat 下载除直播聊天之外的所有字幕。您还可以使用 --compat-options no-live-chat 阻止下载任何直播聊天/弹幕
• YouTube 频道 URL 下载频道的所有上传内容。要仅下载特定标签中的视频，请传递标签的 URL。如果频道未显示请求的标签，则会引发错误。此外，如果没有任何直播视频，则 /live URL 会引发错误，而不是静默下载整个频道。您可以使用 --compat-options no-youtube-channel-redirect 恢复所有这些重定向
• YouTube 播放列表也会列出不可用的视频。使用 --compat-options no-youtube-unavailable-videos 删除此设置
• 从 YouTube 提取的上传日期在可用时为 UTC。使用 --compat-options no-youtube-prefer-utc-upload-date 首选非 UTC 上传日期。
• 如果 ffmpeg 用作下载器，则尽可能在单个步骤中完成格式的下载和合并。使用 --compat-options no-direct-merge 恢复此设置
• 如果可能，使用 mutagen 将缩略图嵌入 mp4 中。使用 --compat-options embed-thumbnail-atomicparsley 强制使用 AtomicParsley
• 默认情况下，某些内部元数据（例如文件名）会从 infojson 中删除。使用 --no-clean-infojson 或 --compat-options no-clean-infojson 恢复此设置
• 当 --embed-subs 和 --write-subs 一起使用时，字幕将写入磁盘并嵌入到媒体文件中。您可以仅使用 --embed-subs 来嵌入字幕并自动删除单独的文件。有关更多信息，请参阅 #630 (comment)。可以使用 --compat-options no-keep-subs 恢复此设置
• 如果安装了 certifi，则将使用 certifi 来获取 SSL 根证书。如果您想使用系统证书（例如自签名证书），请使用 --compat-options no-certifi
• yt-dlp 对文件名中无效字符的净化与 youtube-dl 中的不同/更智能。您可以使用 --compat-options filename-sanitization 恢复到 youtube-dl 的行为
• 如果可能，yt-dlp 会尝试将外部下载器输出解析为标准进度输出（当前已实现：aria2c）。您可以使用 --compat-options no-external-downloader-progress 按原样获取下载器输出
• 2021.09.01 和 2023.01.02 之间的 yt-dlp 版本将 --match-filter 应用于嵌套播放列表。这是 8f18ac 的意外副作用，并在 d7b460 中修复。使用 --compat-options playlist-match-filter 恢复此设置
• 2021.11.10 和 2023.06.21 之间的 yt-dlp 版本估计了分段/清单格式的 filesize_approx 值。这在 f2fe69 中是为了方便而添加的，但由于估计值可能极其不准确，因此在 0dff8e 中恢复。使用 --compat-options manifest-filesize-approx 继续提取估计值
• yt-dlp 使用现代 http 客户端后端，例如 requests。使用 --compat-options prefer-legacy-http-handler 首选将旧版 http 处理程序 (urllib) 用于标准 http 请求。
• 删除了子模块 swfinterp、casefold。

为了便于使用，还提供了一些其他兼容性选项：

• --compat-options all：使用所有兼容性选项（不要使用）
• --compat-options youtube-dl：与 --compat-options all,-multistreams,-playlist-match-filter,-manifest-filesize-approx 相同
• --compat-options youtube-dlc：与 --compat-options all,-no-live-chat,-no-youtube-channel-redirect,-playlist-match-filter,-manifest-filesize-approx 相同
• --compat-options 2021：与 --compat-options 2022,no-certifi,filename-sanitization,no-youtube-prefer-utc-upload-date 相同
• --compat-options 2022：与 --compat-options 2023,playlist-match-filter,no-external-downloader-progress,prefer-legacy-http-handler,manifest-filesize-approx 相同
• --compat-options 2023：当前不执行任何操作。使用此选项启用所有未来的兼容性选项

弃用选项

这些是所有已弃用的选项以及当前用于实现相同效果的替代方案

几乎多余的选项

虽然这些选项与其新的对应选项几乎相同，但存在一些差异，导致它们并非多余

选项	替代选项
-j, --dump-json	--print "%()j"
-F, --list-formats	--print formats_table
--list-thumbnails	--print thumbnails_table --print playlist:thumbnails_table
--list-subs	--print automatic_captions_table --print subtitles_table

多余的选项

虽然这些选项是多余的，但由于易于使用，因此仍然可以使用它们

选项	替代选项
--get-description	--print description
--get-duration	--print duration_string