Navidrome

Folia 支持把 Navidrome 作为独立音乐来源接入。接入后，你可以继续用自己的私人曲库，但播放页、歌词动画、主题和展示能力仍然走 Folia 这一套体验。

需要准备什么

• 一个可访问的 Navidrome 服务器地址
• 用户名
• 密码

Folia 走的是 Subsonic / OpenSubsonic 风格接口，所以常规 Navidrome 部署通常都能接入。

在 Folia 中配置

1. 打开 设置说明 里的“集成设置”。
2. 启用 Navidrome。
3. 输入：
   • Server URL
   • Username
   • Password
4. 点击测试连接。
5. 连接成功后保存并返回主页。

代码里这一块除了保存账号信息，也会缓存服务端 profile 和能力信息，所以第一次连接成功后，后续体验通常会更顺一点。

接入后能做什么

根据当前实现，Navidrome 相关能力不只是“能播歌”，还包括：

• 浏览专辑列表
• 浏览歌手和歌手下专辑
• 搜索曲库
• 浏览播放列表
• 创建、更新、删除播放列表
• 随机歌曲
• 收藏 / 取消收藏歌曲
• 读取流媒体地址与封面
• 同步部分收藏与播放状态

如果你已经把曲库整理在 Navidrome 里，Folia 更像是它的“沉浸式歌词前端”。

歌词策略

Navidrome 歌曲常见有两类歌词来源：

• Navidrome / OpenSubsonic 返回的歌词
• Folia 通过在线匹配拿到的歌词

最推荐的做法

把带时间轴的歌词直接嵌入音频文件标签里。

这样通常能获得更稳定的体验，因为：

• Navidrome 端更容易直接返回这份歌词
• Folia 不需要额外在线匹配
• 歌曲换设备、换前端时，歌词也更容易保持一致

在线匹配什么时候有价值

在线匹配通常适合这些情况：

• Navidrome 只返回纯文本歌词
• 返回的歌词没有时间轴
• 你想尝试拿到更完整的逐字歌词
• 你想把 Navidrome 歌曲也接入网易云 / QQ 音乐 / 酷狗等备选歌词源

如果你比较在意歌词质量，建议同时在播放控制里启用：

• 更多歌词源
• 自动使用最佳歌词

它和本地音乐有什么区别

Navidrome 和“本地音乐导入”都能播放你自己的曲库，但使用感受不太一样。

Navidrome 更适合

• 你的曲库已经在服务器上管理好了
• 你有多设备访问需求
• 你希望歌单、收藏、搜索都围绕服务端统一管理

本地音乐更适合

• 你只在当前设备使用
• 你希望直接按文件夹导入
• 你依赖同目录歌词文件、封面文件和本地扫描重建

如果你只是想快速导入本机文件，优先看 本地音乐。

常见问题排查方向

连接能通但看不到内容

优先检查：

• Server URL 是否包含正确协议和端口
• 用户是否有可访问的 music folders
• Navidrome 侧是否允许对应账号访问曲库

能播歌但歌词不理想

优先检查：

• 音频标签里是否真的嵌入了歌词
• Navidrome 返回的是纯文本还是时间轴歌词
• Folia 是否启用了在线备选歌词源

收藏或歌单行为不符合预期

这一类通常更接近服务端能力、账号权限或 OpenSubsonic 扩展支持范围，建议先确认 Navidrome 服务器本身状态。