Spotube 的同步歌词——LRCLib 插件与时间轴对齐
歌词从哪来
Spotube 的歌词获取逻辑完全插件化：LyricsAPI 接口由歌词插件实现。Spotube 官方提供的 LRCLib 插件是默认选择。
[LRCLib] 是一个公开的同步歌词数据库，类似 Musixmatch，但完全开放和免费：
- CC0 协议，数据可自由使用
- 覆盖约 200 万首曲目
- 每条记录包含：曲目名、艺术家、专辑、时长、LRC 格式歌词
- 由社区贡献和维护
Spotube 的 LRCLib 插件调用它的公开 REST API（GET /api/get），根据曲目元信息搜索匹配。
Spotube 歌词匹配流程
- 用户播放某首歌 → Track 对象带 artist + title + duration + musicBrainzId
- LyricsAPI 被调用，插件传入这些参数
- LRCLib 返回匹配的候选列表，Spotube 按以下优先级选一条：
- 优先匹配 musicBrainzId（如果 Track 来自 MusicBrainz 插件）
- 其次 artist + title + duration 完全一致
- 最后 artist + title 模糊匹配（可能选错同名曲目）
- 拿到 LRC 格式字符串 → 解析成时间戳列表 → 交给 Spotube UI 渲染
时间轴对齐
Spotube UI 里的歌词滚动是本地时间驱动的——Spotube 从 libmpv 的当前播放进度拿时间戳，和 LRC 解析出的时间戳比对，高亮当前行并滚动到中心。
这个对齐完全在本地完成，不依赖网络。所以即使你离线下载了曲目和歌词，滚动也能正常工作。
跨插件歌词匹配失败
一个常见场景：用 Spotify Metadata 插件搜到某首歌（带 Spotify track ID），但 LRCLib 里可能没有这条精确的记录。Spotube 的匹配会退到 artist + title 模糊匹配，可能返回同名但不同版本的歌词。
解决方法
- 换用 MusicBrainz 元数据插件搜到的曲目（带 MusicBrainz ID，LRCLib 也记录了 MBID，匹配更准）
- 在 Spotube 设置里开启"手动选择歌词"——当自动匹配不唯一时，Spotube 弹出候选列表让你挑
- 自己上传 LRC 文件（见下）
本地 LRC 文件
Spotube 支持从本地加载 LRC 文件：
- 把
.lrc文件放在和音频文件同名同目录（比如Song.mp3→Song.lrc） - Spotube 检测到自动加载
- 适用于 LRCLib 没有覆盖的曲目，或你有自己的翻译歌词
歌词显示设置
Spotube 设置里可配置：
| 选项 | 说明 |
|---|---|
| 自动滚动 | 当前歌词行保持在屏幕中央，其余向上/向下滚动 |
| 字号 | 歌词区独立的字号设置，随主题切换 |
| 翻译行 | 有些 LRC 文件带翻译行（[ti:translated]），Spotube 可以同时显示两行 |
| 点击歌词跳时间 | 点某行歌词 → libmpv seek 到对应时间戳 |
插件架构的好处
如果 LRCLib 未来关闭或换了 API，Spotube 只需要更新 LRCLib 插件（或换一个社区歌词插件），Spotube 本体不需要改一行代码。UI 层完全不关心歌词从哪来——它只拿到 LRC 解析结果来渲染。