ytdl-sub：自动下载并整理视频与元数据的命令行工具

如果你经常收藏 YouTube 频道、音乐视频、网络课程或其他在线媒体，手动逐个下载、重命名文件、整理封面和元数据，很容易让本地媒体库变得杂乱。尤其当视频数量不断增加后，仅仅完成“下载”并不能解决后续管理问题，还需要考虑目录结构、文件名称、封面、NFO 信息以及媒体播放器的兼容性。
ytdl-sub针对的正是这类需求。它基于 yt-dlp 工作，通过 YAML 配置文件定义订阅内容和处理方式，可以按照预设规则自动下载媒体、整理文件并生成相应元数据，再将结果放入适合媒体库使用的目录中。它支持 Jellyfin、Plex、Emby、Kodi 等媒体软件，也能处理音乐、音乐视频等内容。对于习惯使用命令行、Docker或自建媒体服务器的用户来说，这种方式能够减少重复整理工作，让视频收藏流程更加系统化。

ytdl-sub是什么？

ytdl-sub是一款基于命令行的视频下载与媒体库整理工具，本身负责配置、调度和整理流程，并调用 yt-dlp 完成媒体下载。与只提供单次下载功能的工具不同，它采用声明式 YAML 配置方式，把“下载什么”“使用什么格式”“如何命名”“保存到哪里”以及“生成哪些元数据”等规则集中管理。
它提供了多种预构建 Preset，可以针对不同媒体播放器和内容类型使用对应配置。例如，YouTube 频道可以按照电视节目形式整理，也可以处理音乐、音乐视频等内容。下载完成后，工具还能生成封面、NFO、音乐标签等媒体库需要的信息，使文件更容易被媒体服务器识别和管理。

核心功能

ytdl-sub的重点并不只是下载视频，而是把下载、格式处理、文件整理和元数据生成组合起来。对于拥有个人媒体库、家庭服务器或大量订阅内容的用户，它可以减少重复的手工整理工作。熟悉 YAML 和命令行的用户，还可以继续修改预设，建立符合自己目录结构的下载规则。

• 自动下载——通过订阅文件批量定义频道、播放列表等内容，并按照规则执行下载。
• 元数据生成——为媒体文件准备标题、封面、NFO及其他媒体库所需信息。
• 订阅管理——使用 YAML 文件集中管理多个下载来源，并通过层级结构复用配置。
• 预构建预设——提供面向 Jellyfin、Plex、Emby、Kodi 等媒体软件的预设，减少重复配置。
• 画质与格式控制——可以通过预设控制视频分辨率、音频质量以及 yt-dlp 的相关下载选项。
• 文件自动整理——按照预设规则处理文件名称、目录结构和媒体类型，让下载内容更容易纳入本地媒体库。
• 自定义配置——支持自定义 Preset、变量和插件配置，方便高级用户建立自己的媒体管理流程。
• 多种部署方式——支持 Docker Compose、Docker CLI、Windows、Linux、Linux ARM、Unraid、PIP 和本地安装等方式。

使用场景

ytdl-sub更适合需要持续管理大量媒体内容的用户。它的优势建立在自动化配置和媒体库整理之上，因此相比临时下载单个视频，更适合长期收藏、家庭媒体服务器以及有固定内容来源的下载任务。

操作指南

新手可以先使用官方提供的 Docker GUI 方案，按照媒体库路径、播放器类型和订阅地址进行配置。官方快速入门流程建议先选择媒体库软件，再设置保存路径和订阅内容，确认预览结果后再正式执行下载。

1. 打开 ytdl-sub 官方项目页面，查看安装方式和最新文档。
2. 根据自己的环境选择 Docker、Windows、Linux、Unraid 或 PIP 等安装方式。
3. 创建 subscriptions.yaml，在「preset」和「overrides」中设置媒体库目录。
4. 选择对应的「Plex」「Jellyfin」「Emby」或「Kodi」预设。
5. 填写需要订阅的频道、播放列表或其他媒体来源。
6. 根据需求设置画质、音频质量、下载范围等选项。
7. 使用预览或检查功能确认目录、文件名和元数据配置，再运行 ytdl-sub sub subscriptions.yaml。
8. 确认文件已经进入媒体库后，再设置周期性运行，实现持续更新。
   （注意：下载网络视频时应遵守来源网站的服务条款以及相关版权规定；如果使用 Cookies 处理需要登录的内容，也应妥善保护相关文件。）

支持平台

ytdl-sub并不是传统意义上的手机应用，而是面向电脑、服务器和自建媒体环境的命令行工具。目前官方项目列出的安装方式包括 Docker Compose、Docker CLI、Windows、Linux、Linux ARM、Unraid、PIP 和本地安装，其中 Docker Compose 还提供 Web-GUI 与无界面运行方式。
如果主要使用 NAS、家庭服务器或 Linux 环境，Docker 会比较适合长期部署；Windows 用户可以直接采用对应安装方式。由于它本身偏向媒体库自动化管理，因此并不适合作为手机端直接操作的视频下载 App。

产品定价

ytdl-sub属于开源软件，项目采用 GPL-3.0 许可证，官方代码仓库没有设置软件订阅费用或商业版功能分层。用户可以自行安装和运行软件，实际使用成本主要来自运行环境、存储空间、网络以及服务器等基础资源。

常见问题

ytdl-sub是否安全？

ytdl-sub是公开源代码项目，核心下载流程建立在 yt-dlp 之上，用户可以查看项目代码、配置和发布记录。使用时仍应从官方项目获取软件，并谨慎处理 Cookies、账号凭据等敏感信息。

ytdl-sub需要收费或注册吗？

软件本身不需要购买订阅，也不要求通过在线账户才能运行。它属于本地部署型工具，用户主要通过配置文件和命令行完成操作。

ytdl-sub需要把视频上传到第三方服务器吗？

它的主要工作方式是在用户自己的运行环境中调用 yt-dlp 下载媒体，并将整理后的文件放入本地媒体库。实际数据流向还会受到所下载平台、Cookies配置以及用户自身部署环境影响，因此处理私人内容时应检查自己的配置。

跳跳兔小结

ytdl-sub适合希望建立长期视频收藏和媒体库管理流程的用户。它把下载、文件整理、元数据生成以及媒体播放器适配放在同一套配置体系中，尤其适合 Jellyfin、Plex、Emby、Kodi 用户以及使用 NAS、Linux 或 Docker 的家庭服务器用户。对于只想偶尔输入一个网址、下载一个视频的普通用户来说，它的 YAML 配置和命令行操作会增加一定学习成本，使用前需要先理解订阅、Preset 和媒体目录之间的关系。整体来看，ytdl-sub更偏向“自动化媒体归档工具”，而不是简单的视频下载器。