如何安装和使用yt-dlp？

星河书院
,
1

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

安装

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

您可以使用二进制文件、pip或第三方包管理器来安装yt-dlp。请参阅维基以获取详细说明。

发布文件

推荐

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

替代方案

文件 描述
yt-dlp_x86.exe Windows（Win8+）独立x86（32位）二进制文件
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安装，只需重新运行用于安装程序的相同命令。

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

目前有三个发布通道用于二进制文件：stable、nightly和master。

  • stable是默认通道，其许多更改已由nightly和master通道的用户测试。
  • nightly通道计划每天在UTC午夜左右构建，以获取项目的新补丁和更改的快照。这是yt-dlp的推荐通道。nightly版本可从yt-dlp/yt-dlp-nightly-builds或作为yt-dlp PyPI包的开发版本（可以使用pip的--pre标志安装）获取。
  • 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 [email protected] 升级/降级到stable通道标签2023.07.06
  • yt-dlp --update-to 2023.10.07 升级/降级到当前通道上的标签2023.10.07（如果存在）
  • yt-dlp --update-to example/[email protected] 升级/降级到example/yt-dlp存储库的版本，标签2023.09.24

重要：任何在stable版本上遇到问题的用户应在提交错误报告前安装或更新到nightly版本：

# 从stable可执行文件/二进制文件更新到nightly：
yt-dlp --update-to nightly

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

依赖

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

虽然所有其他依赖都是可选的，但强烈推荐ffmpeg和ffprobe。

强烈推荐

网络

  • [certifi]
    –recode-video FORMAT 如有必要，将视频重新编码为其他格式。语法和支持的格式与–remux-video相同。
    –postprocessor-args NAME:ARGS 将这些参数传递给后处理器。指定后处理器/可执行文件名称和参数，用冒号“:”分隔，以便将参数传递给指定的后处理器/可执行文件。支持的后处理器包括：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|)q。此选项可以多次使用。
    –no-exec 移除之前定义的–exec。
    –convert-subs FORMAT 将字幕转换为其他格式（当前支持：ass、lrc、srt、vtt）。使用“–convert-subs none”禁用转换（默认）（别名：–convert-subtitles）。
    –convert-thumbnails FORMAT 将缩略图转换为其他格式（当前支持：jpg、png、webp）。您可以使用与“–remux-video”类似的语法指定多个规则。使用“–convert-thumbnails none”禁用转换（默认）。
    –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类别，用逗号分隔。如果一个类别同时存在于mark和remove中，则remove优先。语法和可用的类别与--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。配置从以下位置加载：

  1. 主要配置：
    • 传递给–config-location的文件。
  2. 便携配置：（推荐用于便携安装）
    • 如果使用二进制文件，则与二进制文件相同的目录中的yt-dlp.conf。
    • 如果从源代码运行，则yt_dlp父目录中的yt-dlp.conf。
  3. 家庭配置：
    • 传递给-P的家庭路径中的yt-dlp.conf。
    • 如果未给出-P，则搜索当前目录。
  4. 用户配置：
    • ${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请参阅：关于环境变量的说明
  5. 系统配置：
    • /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（如果存在）进行解码，否则根据系统区域设置的编码进行解码。

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

使用netrc进行身份验证

您可能还希望为支持身份验证的提取器配置自动凭据存储（通过提供–username和–password），以便在每次yt-dlp执行时不必将凭据作为命令行参数传递，并防止在shell命令历史记录中跟踪纯文本密码。您可以通过在–netrc-location中创建一个.netrc文件来实现这一点，并将权限限制为仅您可以读写：

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

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

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

例如：

machine youtube login [email protected] 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选项用于指定每种文件类型应保存的路径。

简而言之：查看示例。

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

然而，它也可以包含在下载每个视频时会被替换的特殊序列。这些特殊序列可以根据Python字符串格式化操作进行格式化，例如%(NAME)s或%(NAME)05d。需要澄清的是，这是一个百分号后跟括号内的名称，再后跟格式化操作。

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

  1. 对象遍历：可以通过使用点.分隔符来遍历元数据中的字典和列表；例如%(tags.0)s，%(subtitles.en.-1.ext)s。你可以使用冒号:进行Python切片；例如%(id.3:7)s，%(id.6:2:-1)s，%(formats.:.format_id)s。可以使用大括号{}构建仅包含特定键的字典；例如%(formats.:.{format_id,height})#j。空字段名称%()s指的是整个信息字典；例如%(.{id,title})s。请注意，使用这种方法可用的所有字段都不会在下文列出。使用-j查看此类字段
  2. 算术运算：可以对数值字段进行简单的算术运算，使用+，-和*。例如%(playlist_index+10)03d，%(n_entries+1-playlist_index)d
  3. 日期/时间格式化：日期/时间字段可以根据strftime格式化进行格式化，通过使用>与字段名称分隔。例如%(duration>%H-%M-%S)s，%(upload_date>%Y-%m-%d)s，%(epoch-3600>%H-%M-%S)s
  4. 替代字段：可以使用,分隔指定替代字段。例如%(release_date>%Y,upload_date>%Y|Unknown)s
  5. 替换：可以使用&分隔符根据str.format迷你语言指定替换值。如果字段非空，则使用此替换值代替实际字段内容。这在考虑替代字段后进行；因此，如果任何替代字段非空，则使用替换值。例如%(chapters&has chapters|no chapters)s，%(title&TITLE={:>20}|NO TITLE)s
  6. 默认值：可以使用|分隔符为字段为空时指定一个字面默认值。这将覆盖--output-na-placeholder。例如%(uploader|Unknown)s
  7. 更多转换：除了常规格式类型diouxXeEfFgGcrs外，yt-dlp还支持转换为B = 字节，j = json（标志#用于美化输出，+用于Unicode），h = HTML转义，l = 逗号分隔的列表（标志#用于\n换行分隔），q = 终端引用的字符串（标志#用于将列表拆分为不同的参数），D = 添加十进制后缀（例如10M）（标志#使用1024作为因子），以及S = 文件名净化（标志#用于受限）
  8. 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开始，填充前导零至5位
  • video_autonumber（数值）：每次视频增加的数字
  • n_entries（数值）：播放列表中提取的总项目数
  • playlist_id（字符串）：包含视频的播放列表的标识符
  • playlist_title（字符串）：包含视频的播放列表的名称
  • playlist（字符串）：如果可用，则为playlist_title，否则为playlist_id
  • playlist_count（数值）：播放列表中的总项目数。如果未提取整个播放列表，可能无法得知
  • playlist_index（数值）：视频在播放列表中的索引，根据最终索引填充前导零
  • playlist_autonumber（数值）：视频在播放列表下载队列中的位置，根据播放列表的总长度填充前导零
  • playlist_uploader（字符串）：播放列表上传者的全名
  • playlist_uploader_id（字符串）：播放列表上传者的昵称或ID
  • playlist_channel（字符串）：上传播放列表的频道的显示名称
  • playlist_channel_id（字符串）：上传播放列表的频道的标识符
  • playlist_webpage_url（字符串）：播放列表网页的URL
  • 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 test video、ID为BaW_jenozKc的mp4视频，这将在当前目录中创建一个yt-dlp test video-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_jenozKc --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将视频流式传输到stdout（-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 or 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 将选择第2个最佳组合格式。同样，bv*.3 将选择包含视频流的第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）来更改被视为 best 的标准。其一般格式为 --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 > 其他）
  • acodec：音频编解码器（flac/alac > wav/aiff > opus > vorbis > aac > mp4a > mp3 > ac4 > eac3 > ac3 > dts > 其他）
  • codec：相当于 vcodec,acodec
  • vext：视频扩展名（mp4 > mov > webm > flv > 其他）。如果使用 --prefer-free-formats，则优先考虑 webm。
  • aext：音频扩展名（m4a > aac > mp3 > ogg > opus > webm > 其他）。如果使用 --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：音频采样率，单位为 Hz

弃用警告：这些字段中的许多具有（目前未记录的）别名，这些别名可能会在未来版本中被移除。建议仅使用已记录的字段名称。

除非另有说明，所有字段均按降序排序。要反转此顺序，请在字段前加上 +。例如，+res 优先选择分辨率最小的格式。此外，您可以为字段添加首选值，用 : 分隔。例如，res:720 优先选择较大的视频，但不超过 720p，如果没有低于 720p 的视频，则选择最小的视频。对于 codec 和 ext，您可以提供两个首选值，第一个用于视频，第二个用于音频。例如，+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,channels,acodec,size,br,asr,proto,ext,hasaud,source,id。提取器可以覆盖此默认顺序，但它们无法覆盖用户提供的顺序。

请注意，hdr 的默认值为 hdr:12；即不优先考虑杜比视界（Dolby Vision）。做出此选择是因为 DV 格式尚未与大多数设备完全兼容。这可能会在未来更改。

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

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

格式选择示例

下载并合并最佳仅视频格式和最佳仅音频格式，或如果没有仅视频格式，则下载最佳组合格式

$ yt-dlp -f “bv+ba/b”

下载包含视频的最佳格式，如果它没有音频流，则与最佳仅音频格式合并

$ yt-dlp -f “bv*+ba/b”

与上述相同

$ yt-dlp

下载最佳仅视频格式和最佳仅音频格式而不合并它们

对于这种情况，应使用输出模板，因为

默认情况下，最佳视频和最佳音频将具有相同的文件名。

$ yt-dlp -f “bv,ba” -o “%(title)s.f%(format_id)s.%(ext)s”

下载并合并具有视频流的最佳格式，

并将所有仅音频格式合并到一个文件中

$ yt-dlp -f “bv*+mergeall[vcodec=none]” --audio-multistreams

下载并合并具有视频流的最佳格式，

并将最佳两个仅音频格式合并到一个文件中

$ 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 的一般语法是给出要从中提取数据的字段名称或 输出模板，以及解释它的格式，用冒号 : 分隔。TO 可以使用带有命名捕获组的 Python 正则表达式、单个字段名称，或与 输出模板 类似的语法（仅支持 %(field)s 格式化）。该选项可以多次使用，以解析和修改各种字段。

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

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

  • 您可以根据当前下载视频的元数据下载额外的 URL。为此，将字段 additional_urls 设置为您想要下载的 URL。例如，--parse-metadata "description:(?P<additional_urls>https?://www\.vimeo\.com/\d+)" 将下载描述中找到的第一个 vimeo 视频
  • 您可以使用此选项更改嵌入在媒体文件中的元数据。为此，使用 meta_ 前缀设置相应字段的值。例如，您设置到 meta_description 字段的任何值都将添加到文件的 description 字段中 - 您可以使用此功能设置不同的“描述”和“概要”。要修改单个流的元数据，请使用 meta<n>_ 前缀（例如 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
language of each stream 格式的 language

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

修改元数据示例

将标题解释为“艺术家 - 标题”

$ yt-dlp --parse-metadata “title:%(artist)s - %(title)s”

正则表达式示例

$ yt-dlp --parse-metadata “description:Artist - (?P.+)”

将标题设置为“系列名称 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

使用描述而不是网页 URL 设置视频元数据中的“评论”字段，

正确处理多行

$ yt-dlp --parse-metadata “description:(?s)(?P<meta_comment>.+)” --embed-metadata

在视频元数据中不设置任何“概要”

$ yt-dlp --parse-metadata “:(?P<meta_synopsis>)”

通过将其设置为空字符串，从 infojson 中移除“formats”字段

$ yt-dlp --parse-metadata “video::(?P)” --write-info-json

将标题和上传者中的所有空格和“_”替换为“-”

$ yt-dlp --replace-in-metadata “title,uploader” “[ _]” “-”

提取器参数

一些提取器接受额外的参数，可以使用 --extractor-args KEY:ARGS 传递。ARGS 是 ;（分号）分隔的字符串，格式为 ARG=VAL1,VAL2。例如，--extractor-args "youtube:player-client=tv,mweb;formats=incomplete" --extractor-args "twitter:api=syndication"

注意：在命令行界面中，ARG 可以使用 - 代替 _；例如 youtube:player-client" 变为 youtube:player_client"

以下提取器使用此功能：

YouTube

  • lang：优先考虑此语言代码（区分大小写）的翻译元数据（title，description 等）。默认情况下，优先考虑视频的主要语言元数据，并回退到 en 翻译。请参阅 youtube.py 以获取支持的内容语言代码列表
  • skip：一个或多个 hls，dash 或 translated_subs，分别跳过 m3u8 清单、dash 清单和 自动翻译字幕 的提取
  • player_client：从中提取视频数据的客户端。目前可用的客户端包括 web，web_safari，web_embedded，web_music，web_creator，mweb，ios，android，android_vr，tv 和 tv_embedded。默认使用 tv,ios,web，或者在使用 cookies 进行身份验证时使用 tv,web。对于 music.youtube.com URL，当使用登录 cookies 时，会添加 web_music 客户端。如果需要账户年龄验证，则对于年龄受限的视频会添加 tv_embedded 和 web_creator 客户端。某些客户端，例如 web 和 web_music，需要 po_token 才能下载其格式。某些客户端，例如 web_creator，仅在使用身份验证时工作。并非所有客户端都支持通过 cookies 进行身份验证。您可以使用 default 表示默认客户端，或者使用 all 表示所有客户端（不推荐）。您可以使用 - 前缀排除某个客户端，例如 youtube:player_client=default,-iOS
  • 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），missing_pot（包括需要 PO Token 但缺少一个的格式）
  • innertube_host：用于所有 API 请求的 Innertube API 主机；例如 studio.youtube.com，youtubei.googleapis.com。请注意，从一个子域导出的 cookies 在其他子域上不起作用
  • innertube_key：用于所有 API 请求的 Innertube API 密钥。默认情况下，不使用 API 密钥
  • raise_incomplete_data：Incomplete Data Received 引发错误而不是报告警告
  • data_sync_id：覆盖在 Innertube API 请求中使用的账户数据同步 ID。这可能在您使用带有 youtube:player_skip=webpage,configs 或 youtubetab:skip=webpage 的账户时需要
  • visitor_data：覆盖在 Innertube API 请求中使用的访问者数据。这应该与 player_skip=webpage,configs 一起使用，并且不使用 cookies。注意：如果使用不当，可能会产生不利影响。如果需要浏览器会话，您应该传递 cookies（其中包含访问者 ID）
  • po_token：使用的证明来源（PO）Token(s)。以 CLIENT.CONTEXT+PO_TOKEN 格式的逗号分隔的 PO Token 列表，例如 youtube:po_token=web.gvs+XXX,web.player=XXX,web_safari.gvs+YYY。上下文可以是 gvs（Google 视频服务器 URL）或 player（Innertube 播放器请求）

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

  • skip：一个或多个 webpage（跳过初始网页下载），authcheck（允许在没有初始网页下载时下载需要身份验证的播放列表。这可能导致不必要的行为，请参阅 #1122 以获取更多详细信息）
  • approximate_date：在平面播放列表中提取近似的 upload_date 和 timestamp。这可能导致基于日期的过滤器略有偏差

通用

  • fragment_query：如果未提供值，则将mpd/m3u8清单URL中的任何查询传递到其片段中；否则，应用给定的查询字符串fragment_query=VALUE。请注意，如果流具有HLS AES-128密钥，则查询参数也将传递到密钥URI，除非传递了key_query提取器参数，或者通过hls_key提取器参数提供了外部密钥URI。不适用于ffmpeg。
  • variant_query：如果未提供值，则将主m3u8 URL查询传递到其变体播放列表URL；否则，应用给定的查询字符串variant_query=VALUE。
  • key_query：如果未提供值，则将主m3u8 URL查询传递到其HLS AES-128解密密钥URI；否则，应用给定的查询字符串key_query=VALUE。请注意，如果通过hls_key提取器参数提供了密钥URI，则此操作将无效。不适用于ffmpeg。
  • hls_key：HLS AES-128密钥URI或密钥（十六进制格式），以及可选的IV（十六进制格式），形式为(URI|KEY)[,IV]；例如generic:hls_key=ABCDEF1234567980,0xFEDCBA0987654321。传递这些值中的任何一个将强制使用原生HLS下载器，并覆盖在m3u8播放列表中找到的相应值。
  • is_live：绕过实时HLS检测并手动设置live_status - 值为false将设置为not_live，任何其他值（或无值）将设置为is_live。
  • impersonate：尝试在初始网页请求中冒充的目标；例如generic:impersonate=safari,chrome-110。使用generic:impersonate来冒充任何可用的目标，使用generic:impersonate=false来禁用冒充（默认）。

vikichannel

  • video_types：要下载的视频类型 - 可以是episodes、movies、clips、trailers中的一个或多个。

niconico

  • segment_duration：HLS-DMC格式的片段持续时间，以毫秒为单位。使用此功能需自担风险，因为此功能可能导致您的账户被终止。

youtubewebarchive

  • check_all：尝试以更多请求为代价检查更多内容。可以是thumbnails、captures中的一个或多个。

gamejolt

  • comment_sort：hot（默认）、you（需要cookies）、top、new - 选择评论排序模式（在GameJolt端）。

hotstar

  • res：要忽略的分辨率 - 可以是sd、hd、fhd中的一个或多个。
  • vcodec：要忽略的视频编码 - 可以是h264、h265、dvh265中的一个或多个。
  • dr：要忽略的动态范围 - 可以是sdr、hdr10、dv中的一个或多个。

instagram

  • app_id：用于API请求的X-IG-App-ID头部的值。默认是Web应用ID，936619743392459。

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提取，使用一个或多个应用信息字符串，格式为<iid>/[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可以传递，以在使用token作为用户名和浏览器本地存储中的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}_{codec}格式，例如hls_opus,http_aac。*字符作为通配符，例如*_mp3，可以单独传递以请求所有格式。已知协议包括http、hls和hls-aes；已知编解码器包括aac、opus和mp3。原始download格式始终被提取。默认值为http_aac,hls_aac,http_opus,hls_opus,http_mp3,hls_mp3。

orfon（orf:on）

  • prefer_segments_playlist：在可用时，优先选择程序片段的播放列表而不是单个完整视频。如果需要单独的片段，请使用--concat-playlist never --extractor-args "orfon:prefer_segments_playlist"。

bilibili

  • prefer_multi_flv：对于仍提供旧格式的老视频，优先提取flv格式而不是mp4格式。

sonylivseries

  • sort_order：系列提取的剧集排序顺序 - 可以是asc（升序，最旧的在前）或desc（降序，最新的在前）。默认值为asc。

tver

  • backend：用于提取的后端API - 可以是streaks（默认）或brightcove（已弃用）。

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

插件

请注意，所有插件即使未被调用也会被导入，且对插件代码不进行任何检查。使用插件需自担风险，且仅在您信任代码的情况下使用！

插件可以是<type>类型中的extractor或postprocessor。

  • 提取器插件无需从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命名空间文件夹，并从所有这些位置加载插件。将环境变量YTDLP_NO_PLUGINS设置为非空值以完全禁用加载插件。

请参阅维基上的一些已知插件。

安装插件

插件可以通过多种方法和位置安装。

  1. 配置目录：包含yt_dlp_plugins命名空间文件夹的插件包可以放入以下标准配置位置：
    • 用户插件
      • ${XDG_CONFIG_HOME}/yt-dlp/plugins/<package name>/yt_dlp_plugins/（在Linux/macOS上推荐）
      • ${XDG_CONFIG_HOME}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
      • ${APPDATA}/yt-dlp/plugins/<package name>/yt_dlp_plugins/（在Windows上推荐）
      • ${APPDATA}/yt-dlp-plugins/<package name>/yt_dlp_plugins/
      • ~/.yt-dlp/plugins/<package name>/yt_dlp_plugins/
      • ~/yt-dlp-plugins/<package name>/yt_dlp_plugins/
    • 系统插件
      • /etc/yt-dlp/plugins/<package name>/yt_dlp_plugins/
      • /etc/yt-dlp-plugins/<package name>/yt_dlp_plugins/
  2. 可执行文件位置：插件包同样可以安装在可执行文件位置下的yt-dlp-plugins目录中（推荐用于便携式安装）：
    • 二进制文件：在<root-dir>/yt-dlp.exe，<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/
    • 源代码：在<root-dir>/yt_dlp/__main__.py，<root-dir>/yt-dlp-plugins/<package name>/yt_dlp_plugins/
  3. pip和其他PYTHONPATH中的位置
    • 插件包可以使用pip安装和管理。请参阅yt-dlp-sample-plugins以获取示例。
      • 注意：通过pip安装的插件包之间的插件文件必须具有唯一的文件名。
    • PYTHONPATH中的任何路径都会被搜索以寻找yt_dlp_plugins命名空间文件夹。
      • 注意：这不适用于Pyinstaller构建。

.zip、.egg和.whl存档中包含根目录下的yt_dlp_plugins命名空间文件夹也被支持为插件包。

  • 例如${XDG_CONFIG_HOME}/yt-dlp/plugins/mypluginpkg.zip，其中mypluginpkg.zip包含yt_dlp_plugins/<type>/myplugin.py。

运行yt-dlp并使用--verbose来检查插件是否已被加载。

开发插件

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

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

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

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

请参阅开发者指南以了解如何编写和测试提取器。

嵌入YT-DLP

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

您的程序应避免解析正常的stdout，因为它们在未来版本中可能会更改。相反，它们应使用诸如-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)

很可能，您会希望使用各种选项。要查看可用的选项列表，请查看yt_dlp/YoutubeDL.py或在Python shell中输入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)
# ℹ️ 请查看help(yt_dlp.YoutubeDL)中的"progress_hooks"
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的变化

新功能

请参阅变更日志或提交记录以获取完整的变更列表。

标有*****的功能已回溯到youtube-dl。

默认行为的差异

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

  • yt-dlp仅支持Python 3.9+，并将在版本生命周期结束时移除对更多版本的支持；而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的排序顺序。早期版本的yt-dlp更倾向于VP9，因为其更广泛的兼容性；您可以使用--compat-options prefer-vp9-sort来恢复到该格式排序偏好。这两个兼容选项不能同时使用。
  • 默认的格式选择器为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除了写入元数据外，还将infojson附加到mkv文件中，当与--write-info-json一起使用时。使用--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。如果频道未显示请求的标签，将会引发错误。此外，/liveURL在没有实时视频时会引发错误，而不是静默下载整个频道。您可以使用--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来恢复此设置。
  • 在mp4中嵌入缩略图时，如果可能，使用mutagen。使用--compat-options embed-thumbnail-atomicparsley来强制使用AtomicParsley。
  • 默认情况下，从infojson中移除了一些内部元数据，如文件名。使用--no-clean-infojson或--compat-options no-clean-infojson来恢复此设置。
  • 当--embed-subs和--write-subs一起使用时，字幕将写入磁盘并嵌入到媒体文件中。您可以仅使用--embed-subs来嵌入字幕并自动删除单独的文件。详见#630 (评论)。--compat-options no-keep-subs可用于恢复此设置。
  • 如果已安装，certifi将用于SSL根证书。如果您想使用系统证书（例如自签名证书），请使用--compat-options no-certifi。
  • yt-dlp对文件名中无效字符的清理与youtube-dl不同/更智能。您可以使用--compat-options filename-sanitization来恢复到youtube-dl的行为。
  • yt-dlp版本在2021.09.01至2023.01.02之间将--match-filters应用于嵌套播放列表。这是8f18ac的意外副作用，并在d7b460中修复。使用--compat-options playlist-match-filter来恢复此设置。
  • yt-dlp版本在2021.11.10至2023.06.21之间为碎片化/清单格式估计filesize_approx值。这是为了方便在f2fe69中添加的，但由于估计值可能极度不准确，在0dff8e中被撤销。使用--compat-options manifest-filesize-approx来继续提取估计值。
  • yt-dlp使用现代http客户端后端，如requests。使用--compat-options prefer-legacy-http-handler来优先使用旧的http处理程序（urllib）来处理标准http请求。
  • 子模块swfinterp、casefold已被移除。
  • 传递--simulate（或调用extract_info时使用download=False）不再更改默认格式选择。详见#9843。

为了便于使用，还提供了几个兼容选项：

  • --compat-options all：使用所有兼容选项（请勿使用此选项！）
  • --compat-options youtube-dl：与--compat-options all,-multistreams,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort相同
  • --compat-options youtube-dlc：与--compat-options all,-no-live-chat,-no-youtube-channel-redirect,-playlist-match-filter,-manifest-filesize-approx,-allow-unsafe-ext,-prefer-vp9-sort相同
  • --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：与--compat-options 2024,prefer-vp9-sort相同
  • --compat-options 2024：当前无效。使用此选项来启用所有未来的兼容选项

以下兼容选项恢复了安全补丁前的易受攻击行为：

  • --compat-options allow-unsafe-ext：允许下载任何扩展名的文件（包括不安全的扩展名）(GHSA-79w7-vh3h-8g4j)

:warning: 仅在有效文件下载因其扩展名被检测为不常见而被拒绝时使用

此选项可能启用远程代码执行！请考虑提交问题！

已废弃选项

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

几乎冗余的选项

虽然这些选项几乎与其新对应选项相同，但有一些差异阻止它们成为冗余的

-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
--get-filename                   --print filename
--get-format                     --print format
--get-id                         --print id
--get-thumbnail                  --print thumbnail
-e, --get-title                  --print title
-g, --get-url                    --print urls
--match-title REGEX              --match-filters "title ~= (?i)REGEX"
--reject-title REGEX             --match-filters "title !~= (?i)REGEX"
--min-views COUNT                --match-filters "view_count >=? COUNT"
--max-views COUNT                --match-filters "view_count <=? COUNT"
--break-on-reject                使用 --break-match-filters
--user-agent UA                  --add-headers "User-Agent:UA"
--referer URL                    --add-headers "Referer:URL"
--playlist-start NUMBER          -I NUMBER:
--playlist-end NUMBER            -I :NUMBER
--playlist-reverse               -I ::-1
--no-playlist-reverse            默认
--no-colors                      --color no_color

不推荐使用

虽然这些选项仍然有效，但不推荐使用，因为有其他替代方案可以实现相同效果

--force-generic-extractor        --ies generic,default
--exec-before-download CMD       --exec "before_dl:CMD"
--no-exec-before-download        --no-exec
--all-formats                    -f all
--all-subs                       --sub-langs all --write-subs
--print-json                     -j --no-simulate
--autonumber-size NUMBER         使用字符串格式化，例如 %(autonumber)03d
--autonumber-start NUMBER        使用内部字段格式化，如 %(autonumber+NUMBER)s
--id                             -o "%(id)s.%(ext)s"
--metadata-from-title FORMAT     --parse-metadata "%(title)s:FORMAT"
--hls-prefer-native              --downloader "m3u8:native"
--hls-prefer-ffmpeg              --downloader "m3u8:ffmpeg"
--list-formats-old               --compat-options list-formats（别名：--no-list-formats-as-table）
--list-formats-as-table          --compat-options -list-formats [默认]（别名：--no-list-formats-old）
--youtube-skip-dash-manifest     --extractor-args "youtube:skip=dash"（别名：--no-youtube-include-dash-manifest）
--youtube-skip-hls-manifest      --extractor-args "youtube:skip=hls"（别名：--no-youtube-include-hls-manifest）
--youtube-include-dash-manifest  默认（别名：--no-youtube-skip-dash-manifest）
--youtube-include-hls-manifest   默认（别名：--no-youtube-skip-hls-manifest）
--geo-bypass                     --xff "default"
--no-geo-bypass                  --xff "never"
--geo-bypass-country CODE        --xff CODE
--geo-bypass-ip-block IP_BLOCK   --xff IP_BLOCK

开发者选项

这些选项不打算由最终用户使用

--test                           仅下载视频的一部分以测试提取器
--load-pages                     加载由 --write-pages 转储的页面
--youtube-print-sig-code         用于测试YouTube签名
--allow-unplayable-formats       也列出无法播放的格式
--no-allow-unplayable-formats    默认

旧别名

这些别名由于各种原因不再被记录

--avconv-location                --ffmpeg-location
--clean-infojson                 --clean-info-json
--cn-verification-proxy URL      --geo-verification-proxy URL
--dump-headers                   --print-traffic
--dump-intermediate-pages        --dump-pages
--force-write-download-archive   --force-write-archive
--load-info                      --load-info-json
--no-clean-infojson              --no-clean-info-json
--no-split-tracks                --no-split-chapters
--no-write-srt                   --no-write-subs
--prefer-unsecure                --prefer-insecure
--rate-limit RATE                --limit-rate RATE
--split-tracks                   --split-chapters
--srt-lang LANGS                 --sub-langs LANGS
--trim-file-names LENGTH         --trim-filenames LENGTH
--write-srt                      --write-subs
--yes-overwrites                 --force-overwrites

Sponskrub选项

对SponSkrub的支持已被废弃，取而代之的是--sponsorblock选项

--sponskrub                      --sponsorblock-mark all
--no-sponskrub                   --no-sponsorblock
--sponskrub-cut                  --sponsorblock-remove all
--no-sponskrub-cut               --sponsorblock-remove -all
--sponskrub-force                不适用
--no-sponskrub-force             不适用
--sponskrub-location             不适用
--sponskrub-args                 不适用

不再支持

这些选项可能不再按预期工作

--prefer-avconv                  avconv不再被yt-dlp官方支持（别名：--no-prefer-ffmpeg）
--prefer-ffmpeg                  默认（别名：--no-prefer-avconv）
-C, --call-home                  未实现
--no-call-home                   默认
--include-ads                    不再支持
--no-include-ads                 默认
--write-annotations              现在没有支持的站点有注释
--no-write-annotations           默认
--compat-options seperate-video-versions  不再需要
--compat-options no-youtube-prefer-utc-upload-date  不再支持

已移除

这些选项自2014年以来已被废弃，现在已完全移除

-A, --auto-number                -o "%(autonumber)s-%(id)s.%(ext)s"
-t, -l, --title, --literal       -o "%(title)s-%(id)s.%(ext)s"

贡献

请参阅CONTRIBUTING.md以获取提交问题和为项目贡献代码的说明

维基

请参阅维基以获取更多信息