YT-DLP Web Player：自托管网页视频播放器

项目简介

YT-DLP Web Player 是一个由 yt-dlp 驱动的自托管网页视频播放器。粘贴视频链接、输入搜索关键词或从剪贴板自动粘贴，即可在浏览器里播放 yt-dlp 支持的站点视频。它提供 Docker 镜像、Python 本地运行、Windows/Linux 桌面程序以及 unraid 应用等多种部署方式，配合 HLS 转码与 ffmpeg 提升播放可靠性。

主要功能

• 每日自动更新 yt-dlp，及时支持新的编码格式与站点
• 支持直播流播放
• 加载速度快，大多数视频在 3 秒内完成加载
• 竖屏视频自动调整宽高比，全屏时可缩放填充
• 视频下载与循环播放，可选音乐可视化
• 极简 UI，主题颜色可配置
• 可安装为 PWA，手机上获得接近原生应用的体验
• 浏览器扩展：把允许域名下的原生播放器替换为 YT-DLP Player，并提供「Open in YT-DLP Player」右键菜单
• 支持 HTTP 代理并自动回退
• Media Session API 系统播放控制、SponsorBlock 集成
• FFmpeg 自动检测最佳硬件编码器，优先使用 NVIDIA NVENC，不可用或失败时回退到 CPU（libx264）

部分功能默认关闭，需要在 .env 中开启。

安装与使用

启动后应用可通过 http://localhost:5000 访问。

Docker

docker run -p 5000:5000 matszwe02/ytdlp_web_player:stable
docker run -p 5000:5000 matszwe02/ytdlp_web_player:latest

• stable：稳定版本，适合日常使用
• latest：最新版本，可能包含实验性功能

也可以使用 Docker Compose：克隆仓库后运行 docker compose up；需要自定义配置时，取消 compose.yml 中 env_file 的注释，并把 src/example.env 复制为 src/.env 进行修改。

本地运行（Python）

• 在 src/ 下创建并激活虚拟环境，安装 requirements.txt
• 可选安装 ffmpeg 与 node/deno，否则它们会被自动安装到虚拟环境中
• 运行 main.py

PC 应用（Windows / Linux）

从 Releases 页面下载并运行：YT-DLP Web Player（窗口化应用，同时开放 5000 端口供浏览器访问）或 YT-DLP Web Player CLI（纯终端版本）。自行构建需安装 python3 和 nodejs，激活虚拟环境后运行 /app/build_app.py，产物出现在 /dist。

浏览器扩展

扩展已在 Chrome Web Store 和 Firefox Add-ons 上架，也可克隆仓库后从 /extension 目录加载；在扩展设置里填入播放器地址，并按域名启用或临时开关。此外还可以从播放器下拉菜单安装 Tampermonkey 脚本，或临时把 extension.js 粘贴到开发者工具中运行。

配置

所有可配置项都是环境变量，写在 src/.env 中，完整列表见 src/example.env。Docker 下使用 NVIDIA GPU 加速需安装 NVIDIA Container Toolkit，并在 compose.yml 中启用使用 Dockerfile.hwaccel 的 build 块与 gpus: all，然后执行 docker compose up --build。

注意事项

• 只有 yt-dlp 支持的视频才能播放；加载失败时会先转码（约 10 秒），仍失败则完整下载后播放。
• 部分流媒体站点需要登录：可把 cookies 放进 src/cookies.txt 并在 compose.yml 中启用。cookies 等同于账号凭据，建议只使用一次性账号。
• 扩展、PWA 嵌入等功能需要 HTTPS。没有 HTTPS 代理时，可把 PUBLISH_WITH_CLOUDFLARE 设为 true，通过日志中生成的临时 Cloudflare 链接访问（每次启动都会变化）。
• 应用没有内置身份认证，会代替任何能访问它的人拉取并转码任意 URL。虽然会尽力拦截内网地址请求，但若暴露到公网，请自行做好网络隔离等安全措施。
• 可通过 /iframe?url=... 端点嵌入播放器，并支持 Open Graph 分享预览。

---

本作品整理自 GitHub 开源项目 Matszwe02/ytdlp_web_player，原作者 @Matszwe02，许可证 GPL-2.0。中文介绍由 AI 根据项目 README 整理，以原仓库为准。