开源项目其他开源工具类新手

HomeTube

HomeTube 是一个面向家庭媒体服务器的通用视频下载工具，提供友好的 Web 界面，可下载 YouTube 等 1800+ 平台的视频和播放列表，自动去除广告与赞助内容，并将视频以最佳质量保存到指定目录，与 Plex、Jellyfin、Emby 等媒体服务器无缝集成。

1 次阅读2026/08/17 发布

#视频下载 #yt-dlp #媒体服务器 #Docker #Streamlit #HomeLab #Plex #Jellyfin #SponsorBlock #播放列表同步 #其他开源工具类 #EgalitarianMonkey

社区作者 · zZz

它解决什么问题

HomeTube 是一个基于 Python/Streamlit 的自托管视频下载器，支持从 YouTube、Reddit、Vimeo、Dailymotion、TikTok、Twitch、Facebook、Instagram 等 1800+ 平台下载单个视频或播放列表。

核心特性包括：原生广告与赞助商内容屏蔽（集成 SponsorBlock）；智能质量检测与下载策略（优先 AV1/VP9/Opus，自动生成最佳和备用配置）；下载后自动按频道/创作者整理文件并移动到媒体服务器监听的目录；智能播放列表同步（基于 ID 跟踪、增量下载、重命名检测、归档模式）；支持 Cookies 认证以解锁受限内容并提高下载可靠性；内置视频处理功能（片段剪辑、字幕嵌入、格式转换、音频提取、移动端优化）；支持自定义 yt-dlp 参数（代理、文件大小限制、带宽控制等）；提供 Docker、Docker Compose、Portainer、本地运行等多种部署方式，并可通过环境变量进行丰富配置。

项目采用 AGPL-3.0 许可证，稳定且处于积极开发状态，测试覆盖率达 84%。

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。

安装 / 开始使用

快速开始

克隆仓库并准备配置文件

git clone https://github.com/EgalitarianMonkey/hometube.git
cd hometube
cp .env.sample .env

Docker 部署

使用 -e VARIABLE= 参数：

docker run -p 8501:8501 \
  -e TZ=America/New_York \
  -e VIDEOS_FOLDER=/data/videos \
  -e TMP_DOWNLOAD_FOLDER=/data/tmp \
  -e YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt \
  -v <VIDEOS_FOLDER_DOCKER_HOST>:/data/videos \
  -v <TMP_DOWNLOAD_FOLDER_DOCKER_HOST>:/data/tmp \
  -v <YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST>:/config \
  ghcr.io/egalitarianmonkey/hometube:latest

使用 --env-file .env：

docker run -p 8501:8501 \
  --env-file .env \
  -v <VIDEOS_FOLDER_DOCKER_HOST>:/data/videos \
  -v <TMP_DOWNLOAD_FOLDER_DOCKER_HOST>:/data/tmp \
  -v <YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST>:/config \
  ghcr.io/egalitarianmonkey/hometube:latest

Docker Compose 部署

.env 文件示例：

# --- PORT ---
PORT=8510

# --- Timezone ---
TZ=America/New_York

# --- Languages ---
UI_LANGUAGE=en
LANGUAGE_PRIMARY=en
LANGUAGE_PRIMARY_INCLUDE_SUBTITLES=true
LANGUAGES_SECONDARIES= # 可选，逗号分隔，如 fr,es

# --- Docker host paths ---
VIDEOS_FOLDER_DOCKER_HOST=/mnt/data/videos
TMP_DOWNLOAD_FOLDER_DOCKER_HOST=/mnt/data/hometube/tmp
YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=/opt/cookies/youtube.txt

# --- Paths ---
VIDEOS_FOLDER=/data/videos
TMP_DOWNLOAD_FOLDER=/data/tmp
YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt

docker-compose.yml：

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    env_file: .env
    volumes:
      - type: bind
        source: ${VIDEOS_FOLDER_DOCKER_HOST:?set VIDEOS_FOLDER_DOCKER_HOST}
        target: /data/videos
      - type: bind
        source: ${TMP_DOWNLOAD_FOLDER_DOCKER_HOST:?set TMP_DOWNLOAD_FOLDER_DOCKER_HOST}
        target: /data/tmp
      - "${YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST}:/config/youtube_cookies.txt"

启动后访问 http://localhost:8501。

也可使用 environment: 方式配置（需在环境变量中显式设置 Docker host 路径）。

Portainer 部署

Portainer 不支持 env_file，需在 UI 中手动输入环境变量。stack 示例如下：

services:
  hometube:
    image: ghcr.io/egalitarianmonkey/hometube:latest
    ports:
      - "${PORT:-8501}:8501"
    environment:
      TZ: "${TZ}"
      UI_LANGUAGE: en
      LANGUAGE_PRIMARY: en
      LANGUAGE_PRIMARY_INCLUDE_SUBTITLES: true
      LANGUAGES_SECONDARIES: ""  # 可选
      VIDEOS_FOLDER: /data/videos
      TMP_DOWNLOAD_FOLDER: /data/tmp
      YOUTUBE_COOKIES_FILE_PATH: "${YOUTUBE_COOKIES_FILE_PATH}"
    volumes:
      - type: bind
        source: ${VIDEOS_FOLDER_DOCKER_HOST:?set VIDEOS_FOLDER_DOCKER_HOST}
        target: /data/videos
      - type: bind
        source: ${TMP_DOWNLOAD_FOLDER_DOCKER_HOST:?set TMP_DOWNLOAD_FOLDER_DOCKER_HOST}
        target: /data/tmp
      - "${YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST}:/config/youtube_cookies.txt"

Portainer UI 中需设置的环境变量示例：VIDEOS_FOLDER_DOCKER_HOST=/mnt/data/videos、TMP_DOWNLOAD_FOLDER_DOCKER_HOST=/mnt/data/hometube/tmp、`YOUTUBE_COOKIES_FILE_PATH_DOCKER_HOST=/opt/cookies/youtube.

txt、TZ=America/New_York、PORT=8501、YOUTUBE_COOKIES_FILE_PATH=/config/youtube_cookies.txt`。

本地安装

环境变量优先级：已导出的 shell 变量 > .env 文件 > 默认值。

方式一：pip（推荐）

python -m venv hometube-env
source hometube-env/bin/activate  # Windows: hometube-env\Scripts\activate
pip install ".[local]"
streamlit run app/main.py
# 或
python run.py

方式二：conda

conda create -n hometube python=3.10
conda activate hometube
pip install ".[local]"
streamlit run app/main.py

方式三：uv（最快）

curl -LsSf https://astral.sh/uv/install.sh | sh
uv pip install ".[local]"
uv run streamlit run app/main.py

访问 http://localhost:8501。

配置验证

DEBUG=1 python -c "import app.main" 2>/dev/null

预期输出包含 HomeTube Configuration Summary 信息。

常见问题提示

Cookies 认证强烈推荐：即使下载公开 YouTube 视频，也需要设置 YOUTUBE_COOKIES_FILE_PATH 或 COOKIES_FROM_BROWSER 以避免签名错误、格式不可用等问题。

Docker 中浏览器 Cookies 提取

（COOKIES_FROM_BROWSER）不可用，需使用 Cookies 文件。

如需保留播放列表中已移除的旧视频，设置 PLAYLIST_KEEP_OLD_VIDEOS=true，被移除项将移到 Archives/ 文件夹。
自定义 yt-dlp 参数可通过 UI 或环境变量 YTDLP_CUSTOM_ARGS 设置。

来源教程配图

适用场景

从 YouTube 等平台下载单个视频并自动整理到媒体服务器目录

下载并同步 YouTube 播放列表

保持本地库与源同步

在家庭局域网中通过 Web 界面发起视频下载任务

自动屏蔽视频广告和赞助片段（SponsorBlock）

将下载的视频直接集成到 Plex

Jellyfin 或 Emby 媒体库

使用 Cookies 认证下载受限内容或规避签名错误

对视频进行片段剪辑

字幕嵌入

格式转换和音频提取

通过自定义 yt-dlp 参数实现代理