🎵 yubal：粘贴链接自动下载 YouTube Music 音乐库自动同步封面歌词

yubal 是一款自建 YouTube Music 音乐下载工具，支持粘贴链接自动下载并打好标签。智能去重、歌词自动补全、ReplayGain 音量均衡，配合 Navidrome/Jellyfin/Gonic 等媒体服务器使用，开源免费一键 Docker部署。

🎤 引言

你是不是受够了各大音乐平台的版权壁垒？喜欢的歌在这个平台有、在那个平台没有，开会员还不够、还要单独买专辑。更别提那些平台动不动就变灰下架，你的歌单随时可能消失。

今天安利一个开源项目 yubal，它能把你 YouTube Music 上的音乐全部搬下来，打好标签、配上歌词、自动去重，直接变成一个可以长期持有的私人音乐库。支持 Docker 一键部署，搭配 Navidrome、Jellyfin 这些媒体服务器，体验完全不输 Apple Music 和 Spotify，而且完全免费、版权自持。

⭐ 核心功能

yubal 的核心逻辑很简单：你给一个 YouTube Music 链接，它自动下载歌曲、匹配元数据、整理成干净的音乐文件夹。背后做的事情相当多：

智能标签与封面匹配
下载完成后自动从 metadata 数据库抓取歌曲标题、艺术家、专辑封面，写入音频文件的 ID3v2/Opus tags。封面自动下载并嵌入，不用手动一张张找。

歌词自动补全
内置 lrclib.net 歌词接口，下载时自动匹配时间轴歌词（LRC格式）。如果 lrclib 查不到，还会 fallback 回 YouTube Music 自身的歌词数据，双保险。

智能去重
同一首歌多次下载不会产生重复文件。它会根据文件名、时长、艺术家等特征做哈希去重，确保音乐库干净整洁。

ReplayGain 音量均衡
开启后自动给每首歌加上音量增益标签（track gain），专辑完整下载时还会加上 album gain。听起来最大的感受就是——专辑里各首歌音量基本一致，不用再被某首歌突然炸耳而某首歌几乎听不清折磨。

计划任务自动同步
可以配置 Cron 表达式，让 yubal 定期自动同步你的播放列表。新歌上线不用手动操作，它会自己蹲在后台更新。

浏览器插件
项目还提供了浏览器扩展（Firefox/Chrome），直接在 YouTube/YouTube Music 页面点一下就能把歌曲加入下载队列，不用复制链接再切换到 yubal 操作。

📥 安装与使用

Docker 快速部署

docker run -d \
  --name yubal \
  -p 8000:8000 \
  -v /path/to/music:/app/data \
  -v /path/to/config:/app/config \
  -e YUBAL_AUDIO_FORMAT=opus \
  -e YUBAL_FETCH_LYRICS=true \
  -e YUBAL_REPLAYGAIN=true \
  -e YUBAL_SCHEDULER_ENABLED=true \
  -e YUBAL_SCHEDULER_CRON="0 2 * * *" \
  guillevc/yubal

启动后访问 http://localhost:8000，粘贴 YouTube Music 链接就能开始下载。界面清爽，操作逻辑和下载工具类似，上手零门槛。

环境变量速查

参数	说明	默认值
`YUBAL_AUDIO_FORMAT`	音频格式：opus/mp3/m4a	opus
`YUBAL_AUDIO_QUALITY`	转码质量（0最优）	0
`YUBAL_FETCH_LYRICS`	自动抓取歌词	true
`YUBAL_REPLAYGAIN`	音量增益	true
`YUBAL_SCHEDULER_ENABLED`	定时同步开关	true
`YUBAL_SCHEDULER_CRON`	Cron 表达式	每天凌晨2点

媒体服务器对接

下载完成的音乐文件在 /app/data 目录，按艺术家/专辑分门别类，直接把文件夹路径指向 Navidrome、Jellyfin 或 Gonic 的媒体库路径即可自动扫描入库。实测 Navidrome 亲测可以完美识别专辑封面、艺术家信息和歌词。

🎯 适用场景

NAS 用户打造私人音乐库
在群晖、威联通或者 Unraid 上跑 Docker，把 YouTube Music 歌单同步到本地，搭配 Navidrome 打造自己的「流媒体平台」，手机、平板、电脑全平台访问，不依赖任何网络。

音乐收藏者长期存档
很多音乐在平台上随时可能被下架，尤其是一些小众专辑、独立音乐人作品。用 yubal 把喜欢的专辑下载到本地，永远不会丢失。

整理 YouTube Music 歌单
有时候 YouTube Music 的歌单管理很乱，yubal 会帮你把歌单整理成干净的文件夹结构，每首歌对应一个文件，方便其他工具进一步处理。

⚠️ 注意事项

仅支持 YouTube Music 链接，普通 YouTube 视频链接不适用。项目使用 yt-dlp 解析，底层依赖 YouTube Music 的音频源。
下载速度取决于网络条件，YouTube 对单个 IP 有请求频率限制，大列表批量下载建议加延迟或分段操作。
版权风险需自担，yubal 本身是技术工具，下载受版权保护的音乐请仅用于个人备份用途，请勿传播或商用。
部分歌曲可能无法匹配歌词，lrclib 歌词库覆盖率和歌曲热度强相关，小众曲目可能需要手动补充 LRC 文件。
存储空间预留，FLAC 无损或高品质 opus 单首歌10-30MB 不等，大歌单请确保 NAS/服务器有足够空间。

✅ 总结

yubal 解决的是一个很实在的痛点——你花钱买了会员、精心维护了歌单，但这些数据本质上不是你的。平台随时可以让你无法访问，而 yubal 帮你把「数据归属权」拿回来。

它的优势不在于花哨的功能，而在于稳：当你想下载，它稳定工作；当你想找歌词，它自动补全；当你同步歌单，它智能去重。你不需要盯着屏幕，一切都在后台有条不紊地运行。

推荐指数：⭐⭐⭐⭐⭐（适合有 NAS 或服务器、想打造个人音乐库的同学）

GitHub：https://github.com/guillevc/yubal