HomeTube 为家庭媒体服务器（如 Plex、Jellyfin）设计的友好型视频下载器 | 极客的赛博空间

🧭 核心功能与定位

HomeTube 旨在简化将网络视频（尤其是 YouTube）集成到本地媒体库的过程。其核心特点包括：

自动化流程：粘贴 URL → 自动下载最高质量（AV1/Opus）→ 移动到配置好的媒体服务器目录。
广告与赞助屏蔽：内置 SponsorBlock 支持，自动跳过视频中的赞助和广告片段。
媒体服务器就绪：视频按创作者/频道自动分类，文件名规范，可直接被 Plex、Jellyfin 等识别。
智能播放列表同步：能检测播放列表的增删改，保持本地库与源同步。
高级处理：支持剪辑片段、嵌入字幕、格式转换和音频提取。
Cookies 认证（重要）：强烈建议配置 Cookies，以访问高质量格式（如 AV1）并绕过签名错误。

📦 部署方式

HomeTube 推荐通过 Docker 部署，也支持本地 Python 环境运行。

方式一：Docker 部署（推荐）

1. 使用 Docker Compose（最便捷）

创建一个 docker-compose.yml 文件：

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    container_name: hometube
    environment:
      - TZ=Asia/Shanghai
      - UI_LANGUAGE=en
      - LANGUAGE_PRIMARY=en
      - VIDEOS_FOLDER=/data/videos
      - TMP_DOWNLOAD_FOLDER=/data/tmp
      - YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt
    volumes:
      - /path/to/your/videos:/data/videos
      - /path/to/temp/downloads:/data/tmp
      - /path/to/your/cookies.txt:/config/youtube_cookies.txt
    ports:
      - "8501:8501"

然后运行：

1	docker-compose up -d

访问 http://localhost:8501。

2. 使用 Docker 命令行

docker run -d \
  --name hometube \
  -p 8501:8501 \
  -e TZ=Asia/Shanghai \
  -v /path/to/your/videos:/data/videos \
  -v /path/to/temp:/data/tmp \
  -v /path/to/your/cookies.txt:/config/youtube_cookies.txt \
  ghcr.io/egalitarianmonkey/hometube:latest

方式二：本地 Python 运行

前提：Python 3.10+，FFmpeg。

# 克隆仓库
git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube

# 创建虚拟环境（推荐）
python -m venv hometube-env
source hometube-env/bin/activate  # Windows: hometube-env\Scripts\activate

# 安装依赖
pip install ".[local]"

# 运行
streamlit run app/main.py

访问 http://localhost:8501。

⚙️ 关键配置

所有配置通过环境变量或 .env 文件管理。强烈建议先复制 .env.sample 为 .env 并修改。

1. 核心路径（必须设置）

VIDEOS_FOLDER：最终视频存储目录（如你的 Jellyfin/Plex 媒体库路径）。
TMP_DOWNLOAD_FOLDER：临时下载目录。
YOUTUBE_COOKIES_FILE_PATH：强烈建议设置，指向你的 YouTube Cookies 文件（用于获取最佳质量和绕过限制）。你可以通过浏览器扩展（如 Get cookies.txt）导出。

2. 语言与质量

LANGUAGE_PRIMARY：首选音频语言（如 zh-CN, en）。
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES：是否嵌入首选语言字幕。
VIDEO_QUALITY_MAX：最大分辨率限制（如 2160 为 4K，max 为允许最高）。

3. 播放列表同步

PLAYLIST_KEEP_OLD_VIDEOS：设为 true 时，源播放列表移除的视频会被移到 Archives/ 文件夹而非删除。

4. 高级定制

YTDLP_CUSTOM_ARGS：可添加任意 yt-dlp 自定义参数（如 --proxy http://proxy:8080）。

🚀 使用指南

配置 Cookies（关键步骤）：
- 使用浏览器扩展导出 YouTube 的 cookies 为 cookies.txt。
- 将文件路径挂载到容器（如 /config/youtube_cookies.txt）或在环境变量中指定。
访问 Web 界面：打开 http://你的服务器IP:8501。
下载视频：
- 粘贴单个视频或播放列表 URL。
- （可选）选择质量策略（自动最佳、仅最佳等）。
- （可选）启用“剪辑片段”、“嵌入字幕”等高级选项。
- 点击下载。HomeTube 会自动处理并移动文件到 VIDEOS_FOLDER。
管理播放列表：
- 在界面中添加播放列表 URL，HomeTube 会持续跟踪并仅下载新增视频。
- 可自定义文件名格式（如 {idx} - {title}.{ext}）。
与媒体服务器集成：
- 设置 JELLYFIN_BASE_URL 和 JELLYFIN_API_KEY 后，HomeTube 可在下载完成后通知 Jellyfin 扫描新文件。

❓ 常见问题

为什么需要 Cookies？ 即使对于公开视频，Cookies 也能解锁 AV1/Opus 等最高质量格式，并避免 n-sig 签名错误。不配置 Cookies 可能导致下载失败或质量较低。
如何获取 Cookies 文件？ 安装浏览器扩展（如 “Get cookies.txt”），登录 YouTube 后导出。
Docker 中路径如何映射？ 需将宿主机的视频目录和 Cookie 目录挂载到容器内部路径（如 /data/videos, /config）。
支持哪些网站？ 通过 yt-dlp 支持 1800+ 网站，包括 YouTube、Twitch、Vimeo、TikTok 等。

总结

HomeTube 为希望自动化将网络视频纳入家庭媒体库的用户提供了理想的解决方案。强烈推荐使用 Docker Compose 方式部署，方便管理。部署的核心是正确配置 Cookies 和存储路径，以确保下载质量和自动化流程。其简洁的 Web 界面和强大的播放列表同步功能，使其成为个人媒体服务器生态的有力补充。项目采用 AGPL-3.0 许可证。

项目地址：https://github.com/EgalitarianMonkey/hometube