网页下载视频并自动整理接入媒体服务器，去广告高画质

方案简介

HomeTube 是一个自托管的通用视频下载器，为家庭媒体服务器（HomeLab）场景设计。它提供一个简单的 Web UI，用户粘贴 YouTube 等平台的单个视频或播放列表链接，即可以下载到的最高画质获取视频，并自动以规范命名移动到 Plex、Jellyfin、Emby 等媒体服务器管理的本地目录中，实现自动入库与观看体验。内置 SponsorBlock 支持，可原生屏蔽视频广告与赞助片段；支持 Cookies 认证以解锁受限内容并避免签名错误；还支持剪辑片段、嵌入字幕、格式转换等高级处理。整个方案无云依赖，一切在本地运行，通过 Docker Compose 一条命令即可部署，适合希望把 YouTube 等平台内容整合进家庭媒体库的自托管用户。

亮点与能力

• 🚫 无广告内容：原生屏蔽视频广告与赞助片段
• 🏆 最佳画质控制：高级最佳画质下载策略或手动覆盖
• 🎬 媒体服务器就绪：以明确命名和位置直接下载到 HomeLab 媒体服务器结构
• 📋 智能播放列表同步：弹性追踪，本地库与源保持完全同步
• 📱 网络访问：Web 界面可从网络内任意设备访问
• 🎯 一键下载：粘贴 URL → 得到完美整理的视频
• 🔐 Cookies 认证：解锁受限内容并防止签名错误
• 🎬 高级处理：剪辑片段、嵌入字幕、转换格式
• ⚙️ 高级配置：包括任意自定义 yt-dlp 参数（代理、max-filesize 等）
• 🎥 多视频源：YouTube、Reddit、Vimeo、Dailymotion、TikTok、Twitch、Facebook、Instagram 等 1800+ 平台

组成与分工

• yt-dlp：底层下载引擎，支持自定义参数（proxy、max-filesize 等）与 1800+ 平台
• SponsorBlock：众包数据库，自动检测并标记/跳过视频中的赞助与广告片段
• Plex / Jellyfin / Emby：媒体服务器，监控下载目标目录，自动入库提供观看
• Docker Compose：容器化一键部署
• Web UI：浏览器界面，从网络内任意设备粘贴链接发起下载、管理目标文件夹
• Cookies 认证：浏览器 Cookies 或 Cookies 文件，保证高画质与可靠性

前置要求

• Docker 与 Docker Compose（一条命令部署）
• 用于 Cookies 认证的浏览器（同机共享浏览器场景），或 HomeLab 场景下的 Cookies 文件
• 本地媒体服务器目录结构（Plex/Jellyfin/Emby 监看的路径）

实施步骤

1. 使用 Docker Compose 部署

项目支持一条命令通过 Docker Compose 完成部署（具体 compose 文件内容见仓库完整版）。

2. 配置 Cookies 认证

若在共享浏览器的机器上可直接使用浏览器 Cookies，否则在 HomeLab 环境使用 Cookies 文件方式，以解锁受限内容并避免下载失败。

3. 设置目标目录

在 UI 的 "Destination folder" 字段中选择媒体服务器监看的目录；必要时使用 "🆕 Create New Folder" 选项创建如 Tech/Python/Advanced 的层级结构。

4. 粘贴链接下载

粘贴视频或播放列表 URL，HomeTube 以最高可用画质下载，自动检测并处理赞助片段，按命名规范移动到目标位置供媒体服务器自动入库。

使用与配置要点

• 通过网络内任意设备的浏览器访问 Web UI 发起下载，验证方式为视频以正确命名出现在媒体服务器目录并可在 Plex/Jellyfin/Emby 中观看。
• 在 UI 中管理需要屏蔽或标记的赞助片段类型。
• 在高级配置中传入任意自定义 yt-dlp 参数，例如代理、max-filesize 等。

注意事项与常见问题

• 即使是公开 YouTube 视频，出于现代保护机制，Cookies 也越来越必要：涉及 n-sig 加密签名、反爬虫措施、限流等，缺少 Cookies 可能出现 "format unavailable" 或提取错误。
• Cookies 是获得最佳画质（AV1/Opus、高分辨率、高品质音频）与稳定下载的关键。
• SponsorBlock 对 YouTube 视频开箱即用，依赖众包数据库。

优缺点

• ✓ 本地运行无云依赖
• ✓ 一键下载自动整理
• ✕ cookies 配置较必要
• ✕ 依赖平台支持列表

出处

本方案挖掘自开源项目 EgalitarianMonkey/hometube，方案内容与实施命令均来自其 README 原文。