跳转到正文
中文
获取 API 密钥
浏览文档

指南

如何使用 yt-dlp

以 Linux 为主的日常下载指南,涵盖 nightly 版安装、格式、字幕、数据集与可续跑的批量采集。

本页内容

安装日常下载所需的工具

先准备 nightly 版、Deno 和 FFmpeg。 在项目的虚拟环境中安装 yt-dlp,并使用 --impersonate="" 启用浏览器模拟。下方展示 Linux 安装步骤,也可以切换到 macOS 或 Windows。

以下示例适用于使用 Python 3.11+ 的 Ubuntu / Debian。安装系统工具并创建项目虚拟环境,再安装当前的 nightly 版本和所需的可选依赖。使用运行下载进程的同一用户执行 Deno 安装程序。

Linux 下载环境
sudo apt-get update
sudo apt-get install -y python3 python3-venv ffmpeg aria2 curl unzip
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
curl -fsSL https://deno.land/install.sh -o /tmp/install-deno.sh
sh /tmp/install-deno.sh
export PATH="$HOME/.deno/bin:$PATH"
deno --version
python -m yt_dlp --version
工具它做什么检查项
Python 3.11+运行 Python 包和示例在这个系列。python --version
最新的 yt-dlp nightly 版及 default,curl-cffi 可选依赖提供最新的 YouTube 提取器、匹配的 EJS 求解器以及浏览器模拟功能。python -m yt_dlp --version
FFmpeg 和 ffprobe合并流、转换音频、截取片段并检查保存的媒体文件。ffmpeg -version / ffprobe -version
Deno 2.3+(此流程需要)执行 YouTube 挑战脚本。每个下载环境都需要安装,开发机上的安装不会覆盖其他环境。deno --version

安装执行器也。 [default] 提供 EJS 脚本; Deno 是分开的。 FFmpeg 和 ffprobe 也必须在下载进程的 PATH 上。

查看完整的基线
deno --version
ffmpeg -version
ffprobe -version
python -m pip show yt-dlp yt-dlp-ejs curl-cffi
python -m yt_dlp --list-impersonate-targets
最终命令应列出可用的浏览器目标。 如果目标不可用,请确保 curl-cffi 安装在这个准确的虚拟环境中。
测试提取与Deno和浏览器的定义
python -m yt_dlp --ignore-config --js-runtimes deno --impersonate="" --verbose \
  --simulate "https://www.youtube.com/watch?v=jNQXAC9IVRw"
检查 JS 运行时间和请求经销线。 一个模拟测试提取;跟随它与一个真实的转换。

FlashData 的操作基础包含 --impersonate=":它允许 curl-cffi 选择可用的浏览器指纹。此改变请求指纹;它不提供登录cookies,解决JavaScript挑战或更改输出IP。如果此选项减缓工作路径或引入错误,请重复同一视频测试,而无需此,并保持工作配置。

检查释放之前将其放在下载进程身上

从官方项目发布页面获取执行,或者从其发布的包源安装Python包。如果下载一个单独的二进制,将其 SHA-256 与该版本的 SHA2-256SUMS 相匹配的字符号进行比较。记录释放和检查,用你的下载进程的图像,以便你可以确定什么是正确的。

查询下载文件
sha256sum yt-dlp

支票比较仅在预期值来自可靠发布时是有用的,而不是与可执行相同的未知镜子。如果安全软件标志着文件,请在做例外之前调查其来源和报告。单独的开源可用性并不是任何下载的二进制或第三方插件都是安全的证据。

将共享配置文件作为编码进行审查:选项如 --exec 可以启动命令,并插件添加代码到下载过程。

下载一张视频

使用一个短视频首先. 引用URL,添加 --no-playlist,并以视频 ID 命名文件。

一张视频,一张输出文件夹
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -P downloads \
  -o "%(id)s.%(ext)s" --print after_move:filepath \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
打印的路径是合并后和后处理的文件。 打开该路径;不要假设文件将以 .mp4 结束。

没有格式过度, yt-dlp 选择其偏好可用的流。高品质的来源往往有单独的视频和音频流,因此由FFmpeg合并跟随的两个传输是正常的。中间文件和 .part 文件可能在工作运行时出现。

选择质量和代码

查看此视频的格式
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -F "https://www.youtube.com/watch?v=jNQXAC9IVRw"

选择一个政策,而不是复制格式 ID. 查看分辨率、编码和单独的 audio/video 轨道。

选择或选项含义什么时候使用它
二V + 二B选择一个视频单流和一个音频单流; FFmpeg将它们结合起来。你需要两条路线,可以合并当地。
A/B试试选 A 然后 B 如果 A 不可用。定义一个明确的落后,而不是假设每个来源都有相同的格式。
[height<=1080]排除高于 1080 像素的流量。硬上方是要求。
-S res:1080偏好分辨率高达 1080;可以选择较大的分辨率,如果没有下面的分辨率可用。1080p 是偏好而不是硬天花板。
--merge-output-format mp4选择集装箱,当将单独的流合合并时。您已经选择了兼容的流,它不提供过代码编码器。
保持源代码器,硬 1080p 天花板
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" -P downloads \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
它可以产生 WebM、MP4 或其他支持的容器,如果没有格式满足天花板,则会失败;它不会沉默地下载 4K。

对于需要 H.264 视频和 AAC 音频的编辑或播放插件,请过滤这些编码器并将其合并到 MP4。MP4 是容器:一个 MP4 容器中的流量仍然可以包含一个编码器,您的应用程序无法解码。

要求 H.264 + AAC,高达 1080p
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bv[vcodec^=avc1][height<=1080]+ba[acodec^=mp4a]/b[vcodec^=avc1][acodec^=mp4a][height<=1080]" \
  --merge-output-format mp4 -P downloads "https://www.youtube.com/watch?v=jNQXAC9IVRw"
如果所需的代码不可用,则这个严格的选择器失败;决定是否接受不同的源代码或转代码;不要意外删除要求。

Remuxing 重新包装流量,而不重新编码它们。转编码会改变代码器,并消耗CPU,同时潜在地改变质量。使用 --remux-video 当流量已经适合目标容器时;使用故意的 FFmpeg 转换,当下流的解码器需要不同的编码器。

保存音频或 MP3

如果您的转换管道接受源音频编码器,下载该流直接。避免不必要的损失转换。MP3是有用的,当消费者具体要求它;高 MP3 比特率不能恢复已经在源中丢失的细节。

保持最佳可用的音频流
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -P audio \
  -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
等待源容器和编码器,通常是 M4A/AAC 或 WebM/Opus.
将音频转换为 MP3
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist -f ba -x \
  --audio-format mp3 --audio-quality 0 -P audio -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
需要 FFmpeg. --audio-quality 0 选择其最佳变量质量设置;使用像 192K 这样的比特率,当您的下流规格需要一个。

保存字符和代码

一个有用的收藏需要更多的名字。保持视频 ID、源 URL、标题、时间和可用的字符串,以便您可以搜索收藏品并跟踪资产返回源。开始列出标题轨道;请求 en 不意味着每个视频都有一个英语轨道。

检查捕捉,然后保存英语轨道没有媒体
python -m yt_dlp --list-subs "https://www.youtube.com/watch?v=jNQXAC9IVRw"
python -m yt_dlp --skip-download --write-subs --write-auto-subs --sub-langs "en.*" \
  --sub-format "vtt/best" -P captions -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"
--write-subs 选择提供的字幕; --write-auto-subs 也允许自动捕捉,这将恢复现有轨道,并且不会转写没有视频。
媒體與甲板和小說
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist --write-info-json \
  --write-thumbnail -P downloads -o "%(id)s.%(ext)s" \
  "https://www.youtube.com/watch?v=jNQXAC9IVRw"

.info.json 文件是详细的操作数据,而不是清洁的公共 API 响应。它可以包括终止的媒体URL和请求相关的字段。保持完整的侧面与收藏,并出口只有您的下流系统需要的领域。如果您需要 SRT 而不是 VTT,请添加 --convert-subs srt 并确保 FFmpeg 可用。

创建一个 AI 数据集项目

对于培训收藏,决定媒体和文本输出。一个常见的要求是最好的可用的视频和音频,合并到 MP4,与时间表的捕捉和提取数据保持在相同的视频ID。预览的可用的分辨率天花板通常是源质量数据集的错误默认。

下载一个完整的数据集项目
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  -f "bestvideo+bestaudio/best" \
  --merge-output-format mp4 --remux-video mp4 \
  --write-info-json --write-subs --write-auto-subs \
  --sub-langs "en" --sub-format "vtt/best" \
  --sleep-subtitles 5 --concurrent-fragments 1 \
  -P dataset -o "%(id)s/%(id)s.%(ext)s" \
  --print after_move:filepath "https://www.youtube.com/watch?v=jNQXAC9IVRw"
巴斯的例子。FFmpeg合并分开的流; --remux-video也覆盖了组合流落。使用从 --list-subs 的准确语言标签;用您的数据集需要的语言取代。

首先,用一个准确的字母语言开始。在我们的直播检查中,en*选择了en、en-en 和en-de;第三行在媒体下载开始之前返回了 429。一个标签错误可以阻止该项目在这个阶段。冷却后,只退出所需的轨道,或者分散媒体和标签工作,如果您的收藏必须保持媒体输入移动。

/best fallback 允许结合 video/audio 流,当单独的轨道不可用时。删除此落后,如果收集合同需要单独的最佳视频和 bestaudio 来源。MP4 不意味着 H.264:此命令示例保留所选择的源代码。使用上面的严格的 H.264/AAC 选项,如果您的训练解码器需要这些编码器,或者作为一个单独的,记录的步骤转码。

预期文件,当英语标签轨道存在时
dataset/VIDEO_ID/
  VIDEO_ID.mp4
  VIDEO_ID.info.json
  VIDEO_ID.en.vtt
没有标签文件创建,当所要求的轨道不可用时;不要标记文本覆盖完整,因为 MP4 完成。
要求收藏决议
可用的最高源质使用 bestvideo+bestaudio,保持源代码,并用 ffprobe 验证合并流。
时间文本保持 VTT/SRT 分区和语言在视频 ID 旁边 平板文本显示了需要剪辑调整的时间。
缺少字幕记录错过的文本明确:如果文本是强制性的,将保存的音频转移到您的翻译阶段。
多种语言的口号只要求所需的语言。 每条额外的路径都会添加请求,并且可以与媒体独立地查找 429。
简介 + 文本交付使用单独的数据集档案和媒体、代数据和标签状态的存储库。

不要重复使用由此前媒体创建的档案,仅适用于此新政策:存档的视频可能会在收集失踪的录像之前被删除。要么用自己的档案运行数据集政策,要么为错过的文本ID进行单独的标签修复通道。存储原始字符串;如果您的模型需要清洁的翻译文本,则将其衍生在版本处理步骤。

改善转移通道,而不超过IP

aria2c 可以帮助一个单一的连接下载不信任或高缓慢的链接。它不能修复拒绝的播放器请求或标志出输IP。首先,在一个来源上进行原始下载器工作,然后将传输时间和错误与少数 aria2 连接进行比较。

每 HTTP 转换的两个连接开始
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --downloader aria2c --downloader "dash,m3u8:native" \
  --downloader-args "aria2c:-x 2 -s 2 -j 1" \
  --concurrent-fragments 1 \
  -P downloads -o "%(id)s.%(ext)s" "https://www.youtube.com/watch?v=jNQXAC9IVRw"
首先安装 aria2. 保持 DASH/HLS 与本地下载器在这里,以便部分竞争保持明确。
控制什么是限制
aria2c -x 2连接到一个服务器下载。
aria2c -s 2要求分成一个文件;分成也取决于文件大小和服务器支持。
aria2c -j 1相似的物品在这个 aria2 引用,而不是其他 yt-dlp 下载进程。
--concurrent-fragments 1部分下载在原住民 DASH/HLS 下载器内。
你的工作 ⁇共享相同的主机或proxy 输出 IP 的总活跃视频。

curl-cffi的定义属于 yt-dlp的要求;它不设置 aria2的 TLS 指纹。如果原始下载工作,但 aria2 得到 403,返回原始之前更改与未相关的提取器设置。保持抽出和外部转移在同一次预算会议。

在FlashData的操作中,过于攻击性地提高竞争力可能会使工作路线立即开始返回403。如果发生了,停止其他工作,回到一个下载进程和一个连接,然后重新测试。不要通过添加更多的 aria2 分裂或平行退出同一被拒绝的流量来补偿。如果 IP 仍然在低负载下被拒绝,则使用 403 IP 替换工作流。

保守的原住民转移与比较
python -m yt_dlp --js-runtimes deno --impersonate="" --no-playlist \
  --downloader native --concurrent-fragments 1 --limit-rate 2M \
  --sleep-requests 2 --sleep-interval 5 --max-sleep-interval 10 \
  -P diagnostics "https://www.youtube.com/watch?v=jNQXAC9IVRw"
2M 是诊断带宽封,而不是普遍的YouTube边界。

准备一系列

对于一个小已知的集合,创建一个 UTF-8 urls.txt 与一个观看 URL 每行。对于YouTube播放列表,首先将其ID列入一个显明。平板提取检查播放列表,而不为每个视频进行完整提取;它对范围审查有用,但其输入可能缺乏时间、格式和可用性细节。

创建YouTube播放列表的显现
python -m yt_dlp --flat-playlist --print "https://www.youtube.com/watch?v=%(id)s" \
  "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID" > urls.txt
更换 YOUR_PLAYLIST_ID. 在开始媒体转移之前检查 urls.txt. 如果您重新运行,则将此显示更换为重新导向。

若要尝试一系列,请选择几个播放列表输入,其中有 --playlist-items 1:5。频道的 /video 选项卡比一个模糊的频道主页更为清晰的上传视频的起点。不要将播放列表订单视为身份:项目可以输入、重新订单或删除。

过滤器用途结果
--playlist-items 1:5目前列表中的第五个输入。用於小測試,而不是持久的檢查點。
--dateafter 20260101保持登录日期为2026年1月1日或之后。日期过滤可能仍然需要视频提取。
--match-filters "!is_live & duration <= 1800"需要一个未活的项目,已知的持续时间最多为 30 分钟。未知的输入不符合此严格的过滤器。
--download-archive archive.txt滑动源代码已记录在以前的下载。工作在改变的标题和播放列表位置。

安全地重新收集

在您的收藏文件夹中保存下列作为 yt-dlp-work.conf,除了 urls.txt 之外。它定义出售政策一次,给收藏自己的档案,限制退款。将输出文件和此档案保持在一起:一个档案记录由提取器和ID取得成功,而不是当前文件的检查号或位置。

yt-dlp-work.conf
# YouTube worker baseline
--js-runtimes deno
--impersonate=""
--concurrent-fragments 1

# Output policy
--no-playlist
-f "bv*[height<=1080]+ba/b[height<=1080]"
-P downloads
-o "%(channel_id)s/%(id)s.%(ext)s"
--write-info-json

# Resume and remember completed media
--continue
--download-archive archive.txt
--no-abort-on-error

# Bound each attempt and spread out work
--retries 5
--fragment-retries 5
--socket-timeout 30
--sleep-requests 1
--sleep-interval 5
--max-sleep-interval 10

# Append paths only after the final move
--print-to-file after_move:filepath completed-paths.txt
平板文本配置,每行一个选项。 此示例中的路径与工作目录相似。 使用绝对路径,当一个日程表可能在其他地方开始时。
运行收藏
python -m yt_dlp --ignore-config --config-locations yt-dlp-work.conf --batch-file urls.txt
--ignore-config 删除默认的 user/system 配置;明确提供的 --config-locations 文件仍然被加载。

停止停止后,同样的命令。完成的 ID 被删除,可重复的部分转让在支持的地方继续。抽取故障可以在下一行重新审查。默认的 .part 文件是有用的状态;不要将它们作为一个日常退出步骤删除。

--no-abort-on-error 继续过去不存在的输入,但一个运行仍然可以出不零,后处理错误需要注意。避免添加 --ignore-errors 只是为了获得绿色工作:它可以将处理后失败作为成功的下载。查看日志和完成的输出,在宣布收藏完成之前。

查看完成文件

completed-paths.txt 文件是一个有用的开始记录。测试实际的最终输出而不是暂时的视频仅流。 ffprobe 阅读容器和流量代数据;一个单独的解码通道捕获问题,只有一个可读的标题会错过。

查看完成的文件
ffprobe -v error -show_entries format=duration,size:stream=codec_type,codec_name,width,height -of json "downloads/CHANNEL_ID/VIDEO_ID.mp4"
用 completed-paths.txt 的路径取代,检查预期的时间,需要 audio/video 流量和可解码兼容的编码器。
可选的完整的DECODE检查
ffmpeg -v error -i "downloads/CHANNEL_ID/VIDEO_ID.mp4" -f null -
阅读和解码整个文件,而不创建新的媒体输出。 检查输出状态以及消息;需要更长时间,而不是 ffprobe。
寻找处理方法
只剩下一个 .part 或单独流的文件检查 transfer/merge 错误并重新启动原始工作;不要标记中间文件完整。
视频播放无音检查所选格式和 ffprobe 流量。 视频单格式需要音频选择和合并。
MP4 不会在您的编辑中打开检查编码器,而不仅仅是扩展;选择兼容的流或转码明确。
存档 ID 但没有本地文件查看文件是否是 moved/deleted. 将存储库重新编辑,然后更改存档输入。

9、将已验证的命令转移到计划工作中

完成完整的命令,在预订之前成功地手动执行。一个编程通常以不同的PATH和工作目录开始。给它虚拟环境的完整Python路径,完整的配置路径和明确的工作目录;也为这个过程提供 FFmpeg 和 JavaScript 运行时间。

  • 使用一个下载进程为一个 collection/archive. 不要让昨天的运行超过今天的运行与相同的输出。
  • 在Linux上,使用一个 timer/service 或 cron 输入,其中包含一个工作目录和一个锁,如集。
  • 在 macOS 上,使用启动,具有绝对可执行和工作导向路径。
  • 在 Windows 任务日程中,设置程序到环境的 python.exe、论点到 -m yt_dlp 以及配置和包装选项,并启动到收集文件夹。
  • 记录 start/end 时间,可执行版本,源显示,输出状态和 completed/failed 计算。
  • 将 Cookie 文件和目的地认证从共享配置存储库中保持。

睡眠选项在一个过程内运作。使用相同设置的十名下载进程仍然产生十个过度流的请求。增加 --concurrent-fragments 改变下载中的片段竞争,而不是工作线上的视频数量。

选择正确的错误指南

更新此 Python 环境
python -m pip install -U --pre "yt-dlp[default,curl-cffi]"
python -m yt_dlp --version

当以前工作源断开时,更新到最新的夜间,包括匹配额外。為獨立的二元使用 yt-dlp --update-to 夜間; -U 單獨留在目前的渠道。每次更新后运行一个小峡谷,然后重建下载进程并记录修订,以免海军沉默地混合发布。

症状从这里开始
Requested format is not available列出格式,并在更改退款之前检查您的严格过滤器。
ffmpeg not found / ffprobe and ffmpeg not found检查从实际的下载进程或日程表账户的PATH。
JavaScript 挑战 / 失去运行时间警告检查运行时间检测和匹配的 EJS 包。
HTTP 403 转移期间识别拒绝的主机和阶段;从媒体转移中分开提取。
HTTP 429停止受影响的 IP,允许冷却和低 extraction/caption 请求频率。
Sign in to confirm you’re not a bot休息包,并诊断一个源、会议和网络。

当产量属于云管道时

如果您想要拥有下载器,上述工作流将为您提供对文件、格式和处理的控制权。如果您的应用程序需要完成的存储媒体,FlashData提供跟踪的YouTube下载工作,机器人处理,代理路由和退出。您的申请提交源和输出设置,然后保留工作身份证和交付记录。

参考材料

升级选项参考是您安装的版本的真相来源。 使用这些部分,当更改收集政策或更新下载进程图像时。