Spotube 搜索与发现——跨插件搜索、分类热门榜、推荐系统
Spotube 搜索的核心机制
Spotube 的搜索不是调"某一个"API——它会并行调用所有已启用的 MetadataSearchAPI 插件，把结果合并后显示在一个页面里：
- 用户输入搜索词 → 按回车
- Spotube UI 并行发送到每个启用的 MetadataSearchAPI 插件
- Spotify Metadata、MusicBrainz、JioSaavn、Spotube 聚合插件等同时返回结果
- Spotube 做去重（如果多个插件返回了同一首歌的不同版本）
- 结果按类别分区显示：曲目 / 专辑 / 艺人 / 播放列表
这就是插件架构最直接的好处——搜一次，所有来源都覆盖。
搜索结果的去重
Spotube 用多个维度判断两条结果是不是同一首歌：
- MusicBrainz ID（最准，如果有）
- Spotify track ID
- artist + title + duration 三字段的模糊匹配（fuzzywuzzy 包）
- 相似率超过阈值（默认 0.9）就合并，保留数据最完整的那条
搜索类别切换
搜索结果页顶部有 Tab 切换：
| Tab | 说明 |
|---|---|
| All | 默认，按曲目 → 专辑 → 艺人 → 播放列表 顺序混合显示 |
| Tracks | 只显示单曲 |
| Albums | 只显示专辑 |
| Artists | 只显示艺人（点进去看该艺人的专辑和曲目） |
| Playlists | 只显示播放列表（Spotify 分类歌单、官方编辑精选） |
高级搜索语法
Spotube 目前不支持 artist:, album: 等高级搜索语法，但插件层可以扩展——如果你用第三方插件，可以在插件内部实现更精确的搜索。Spotube 宿主只做原始字符串传递。
分类热门榜
Spotube 首页或侧边栏提供分类浏览：
Spotify 分类
Spotify Metadata 插件可以拉 Spotify 的分类歌单：
- Spotify 官方榜单（全球 Top 50 / Viral / New Music Friday）
- 情绪分类（Chill / Workout / Party / Study / Focus）
- 地域分类（印度、日本、韩国、美国、英国、拉丁美洲）
- 类型分类（Rock / Hip-Hop / Pop / Electronic / Classical）
这些分类直接来自 Spotify Web API 的 /v1/browse/categories/{category_id}/playlists endpoint，Spotube 原样展示。
YouTube Music 热门榜
Spotube 也可以拉 YouTube Music 的 Top 榜（通过 youtube_explode_dart）：
- 全球 Top 100 / 本地 Top 100（根据你的 YouTube 地区设置）
- Trending（热门趋势）
- Music（音乐分类趋势）
JioSaavn 印度分类
JioSaavn 插件可以拉印度本地的：
- 宝莱坞热门榜
- 区域语言热门榜（印地语、泰米尔语等）
- 新兴艺人
个性化推荐
Spotube 自己不做推荐算法（Spotube 作者的原则：Spotube 只是播放器，推荐交给插件）。但可以借助连接的外部服务获得个性化推荐：
Spotify Discover Weekly / Release Radar
连接 Spotify 账号后：
- Discover Weekly：每周一更新的 30 首个性化推荐（Spotify 算法）
- Release Radar：每周五更新的 30 首你关注艺人的新歌
- 这两个都在 Spotube 的 Spotify 分类里作为独立播放列表出现
ListenBrainz 推荐
连接 ListenBrainz Scrobble 后：
- ListenBrainz 基于你的播放记录生成 "Recommended artists" 列表
- Spotube 可以把这个列表拉进来作为一个播放列表
本地文件搜索
Local Files 插件同时实现了 MetadataSearchAPI——Spotube 搜索时本地库也会被搜：
- 搜索词匹配到本地 MP3 的 artist/title/album → 出现在结果里
- 本地和在线结果混在一起显示
- 已下载的曲目会显示绿色向下箭头图标
搜索异常排查
搜不到明显存在的曲目
可能原因：
- 元数据插件没启用 → 插件管理页确认
- 被"跳过"了——Spotube 搜索有个"隐藏结果太少的插件"选项，关掉
- 音乐本身太冷门 → 试 MusicBrainz（社区贡献更广）
结果里同名曲目多
Spotube 默认去重阈值是 0.9（模糊匹配相似度），阈值可以在高级设置里调（调低会合并更多，调高会显示更多候选）。或在播放列表里手动筛选。
本地文件搜到但播放失败
Local Files 插件返回的是本地路径。如果文件被移动或删除了，Spotube 会报错。重新扫描本地目录即可。