Spotube 本地音乐库——扫描、管理、与在线来源合并

两种音乐来源的合并

Spotube 天生支持本地音频文件 + 在线流式内容的混合使用。这两种来源共享同一个 Spotube 界面：

• 左边导航栏同时出现 "Spotify 播放列表"、"YouTube 热门榜"、"本地音乐"、"收藏"
• 搜索时本地和在线来源一起搜
• 播放时 MPV 不区分是本地文件还是流式音频，统一处理

Local Files 插件

Spotube 官方在 v5.x 里提供了 Local Files 插件（AudioAPI + MetadataSearchAPI + LyricsAPI 三合一）：

• 实现 AudioAPI：返回本地文件的 file:// 路径
• 实现 MetadataSearchAPI：从 ID3 标签读取元数据
• 实现 LyricsAPI：查找同名 .lrc 文件

扫描本地目录

设置 → Library → Local Files：

1. 添加一个或多个扫描目录
2. Spotube 递归扫描子目录
3. 识别支持的格式 → 从 ID3 标签读取元数据 → 存入数据库
4. 之后任何对目录内文件的修改都会被 Spotube 下次扫描时检测到

支持的格式

Spotube / MPV 支持的音频格式几乎是全量：

与在线元数据混搭

本地文件的 ID3 标签可能不完整（比如没有封面、artist 字段写错）。Spotube 可以用在线元数据插件补全本地文件的信息：

1. 在本地曲目上右键 → "Refresh metadata"
2. Spotube 用 MetadataSearchAPI 插件搜索同名曲目
3. 找到匹配的 → 把新元数据（封面、正确 artist、专辑信息）覆盖到本地文件的 ID3 标签
4. 底层还是 metadata_god 包负责写入

这对整理早年下载的 MP3 非常有用——Spotify Metadata 或 MusicBrainz 能帮你自动补全封面和信息。

本地文件夹结构建议

Spotube 不强制任何目录结构。最实用的两种组织方式：

扁平文件夹

D:\Music\
├── Song1.mp3
├── Song2.mp3
└── Song3.mp3

缺点：全部堆在一起，Spotube 只能靠 ID3 标签分组。

Artist / Album 层级

D:\Music\
├── 歌手名\
│   ├── 专辑名\
│   │   ├── 01-曲目1.mp3
│   │   ├── 02-曲目2.mp3
│   │   └── cover.jpg
│   └── 另一个专辑\
└── 另一个歌手\

优点：Spotube 会自动按文件夹结构推断专辑信息，没有 ID3 标签也能整理。

元数据编辑

Spotube 内置轻量的元数据编辑器：

• 曲目 / 专辑 / 艺人 / 年份 / 流派：可以改文本
• 封面图：可以替换、拉伸、添加
• 修改后直接写入本地文件的 ID3 标签

完整编辑还是推荐 MP3tag（Windows）、Kid3（跨平台）或 foobar2000——Spotube 的编辑器够用但功能有限。

本地库与流式的无缝切换

Spotube 最强大的地方之一：你可以在播放列表里同时放本地曲目和流式曲目。比如：

• Spotify Discover Weekly 里选 5 首（流式）
• 加 2 首你本地 FLAC 收藏
• 这个混合播放列表下次还在
• 播放时 MPV 不区分，统一处理

本地库扫描异常

扫描不到文件

• 确认目录在 Spotube 扫描列表里
• 权限问题？Windows 某些系统目录需要给 Spotube 读取权限
• 文件被占用？关闭打开了这些文件的其他播放器后重试

扫描后只有文件名没有元数据

• 这些文件的 ID3 标签可能为空 → 用 "Refresh metadata" 让在线插件补
• 或在 MP3tag 里批量写入基础标签

扫描很慢

Spotube 默认在扫描时同时预览封面图。大目录（几万首）可以在设置里关闭封面预览，加速扫描。