yubal：自托管 YouTube 音乐下载器技术分析

一、概述

1. 项目背景

yubal 是一个自托管应用，用于从 YouTube Music 下载专辑和播放列表，并自动处理元数据标签和封面艺术。该项目解决了音乐爱好者构建本地音乐库的痛点需求。

2. 核心功能

• Web UI 界面，支持实时进度显示和任务队列
• 智能标签系统，从 YouTube Music 获取元数据并使用模糊匹配
• 支持专辑和播放列表下载，自动生成 M3U 播放列表文件
• 智能去重机制，基于路径索引，避免重复下载
• 支持多种音频格式：opus（原生最佳质量）、mp3、m4a
• 与主流媒体服务器兼容（Navidrome、Jellyfin、Gonic）

3. 项目架构

graph TB
    User[用户] -->|YouTube Music URL| WebUI[Web UI]
    WebUI -->|提交任务| Queue[任务队列]
    Queue -->|yt-dlp| YTDLP[YouTube下载]
    Queue -->|ytmusicapi| YTMAPI[元数据获取]
    YTDLP -->|音频流| Downloader[下载器]
    YTMAPI -->|专辑信息| Tagging[标签处理]
    Downloader --> Tagging
    Tagging -->|Artist/Year-Album/| Storage[存储]
    Storage -->|M3U引用| Playlist[播放列表]

二、技术架构

1. 技术栈

2. 核心依赖

• yt-dlp：YouTube 内容下载，支持 age-restricted 内容和 Premium 高码率
• ytmusicapi：YouTube Music API 封装，获取专辑元数据和曲目信息

3. 数据流架构

sequenceDiagram
    participant U as 用户
    participant W as Web UI
    participant Q as 任务队列
    participant Y as yt-dlp
    participant M as ytmusicapi
    participant F as 文件系统

    U->>W: 粘贴专辑/播放列表URL
    W->>Q: 创建下载任务
    Q->>M: 获取专辑元数据
    M-->>Q: 返回曲目列表
    Q->>Y: 下载音频流
    Y-->>F: 写入音频文件
    Q->>F: 写入元数据标签
    Q->>F: 下载封面艺术
    Q->>F: 生成M3U文件
    F-->>U: 按Artist/Year-Album组织

三、文件组织结构

1. 默认目录结构

data/
├── Pink Floyd/
│   └── 1973 - The Dark Side of the Moon/
│       ├── 01 - Speak to Me.opus
│       ├── 02 - Breathe.opus
│       └── cover.jpg
│
├── Radiohead/
│   └── 1997 - OK Computer/
│       ├── 01 - Airbag.opus
│       ├── 02 - Paranoid Android.opus
│       └── cover.jpg
│
└── Playlists/
    ├── My Favorites.m3u
    └── My Favorites.jpg

2. 组织逻辑

• 专辑：按 Artist/Year - Album 组织
• 播放列表：生成 M3U 文件，引用现有专辑文件，不创建副本
• 智能去重：基于文件路径索引，避免跨播放列表重复下载

3. M3U 播放列表格式

#EXTM3U
#EXTINF:239,Pink Floyd - Breathe
../Pink Floyd/1973 - The Dark Side of the Moon/02 - Breathe.opus
#EXTINF:386,Radiohead - Paranoid Android
../Radiohead/1997 - OK Computer/02 - Paranoid Android.opus

四、配置与部署

1. 环境变量配置

2. Docker Compose 部署

services:
  yubal:
    image: ghcr.io/guillevc/yubal:latest
    ports:
      - 8000:8000
    environment:
      YUBAL_TZ: UTC
    volumes:
      - ./data:/app/data
      - ./config:/app/config
    restart: unless-stopped

3. Cookie 配置（可选）

适用于年龄限制内容、私人播放列表或 Premium 高码率：

1. 使用浏览器扩展导出 Cookie
2. 放置在 config/ytdlp/cookies.txt
3. 或通过 Web UI 上传

五、媒体服务器集成

1. 标签系统

yubal 为所有音频格式写入：

• ARTIST：斜杠分隔的单值标签
• ARTISTS：多值标签（支持多位艺术家）

2. 兼容性对比

3. 配置建议

Navidrome：无需配置，可选设置播放列表公开可见

Jellyfin：启用非标准艺术家标签

• Dashboard → Libraries → Music Library → Manage Library
• 勾选 Use non-standard artists tags

Gonic：配置多值标签支持

GONIC_MULTI_VALUE_ARTIST=multi
GONIC_MULTI_VALUE_ALBUM_ARTIST=multi

六、技术亮点

1. 智能去重机制

基于文件路径索引，确保同一曲目不会在不同播放列表中重复下载：

graph LR
    A[新任务URL] --> B{检查路径索引}
    B -->|已存在| C[跳过下载]
    B -->|不存在| D[下载并索引]
    D --> E[写入文件]

2. 模糊匹配算法

使用模糊匹配算法将 YouTube Music 元数据与本地文件对应，提高标签准确性。

3. 任务队列系统

Web UI 支持实时进度显示和任务队列管理，提供良好的用户体验。

4. 多格式支持

• opus：原生格式，最佳质量
• mp3/m4a：转码选项，兼容老旧设备

七、使用场景与限制

1. 适用场景

• 个人音乐收藏归档
• 构建本地音乐服务器库
• 播放列表备份

2. 使用限制

• 需遵守 YouTube 服务条款
• Cookie 使用可能触发更严格的速率限制
• 仅供个人归档使用

3. 注意事项

Cookie 使用可能导致账户风险，建议仅在必要时使用。

八、项目发展

1. 已实现功能

• Cookie 通过 Web UI 上传
• 多架构 Docker 镜像（amd64/arm64）
• 可配置音频格式
• 播放列表支持与 M3U 生成

2. 路线图

• 扁平文件夹结构模式
• 浏览器扩展
• 批量导入（多个 URL）
• 导入后 Webhook 通知

参考资料

1. yubal GitHub Repository