Navidrome / OpenSubsonic

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

不只是 Navidrome

Folia 这一块用的是 Subsonic / OpenSubsonic API，不是 Navidrome 的私有接口。任何实现了 Subsonic API 的服务端都可以尝试连接——设置项写作 Navidrome 只是因为它是最常见的那个实现。

它到底连的是什么

Folia 只通过标准的 Subsonic REST 接口和服务端通信：

项目	值
接口路径	`<服务器地址>/rest/<方法>`
声明的 API 版本	`1.16.1`
客户端标识	`Folia`
响应格式	JSON（`f=json`）
认证方式	Subsonic 标准的 salt + token（`t = md5(密码 + salt)`），每次请求随机 salt

因此，只要服务端实现了 Subsonic API 1.16.1 的常用方法，理论上都能接上。常见的可用实现包括 Navidrome、Gonic、Astiga、Airsonic / Airsonic-Advanced、Ampache（Subsonic 兼容层）、LMS 等。

兼容性说明

不同实现覆盖的方法和扩展并不一致。Folia 的能力上限取决于你的服务端实现了什么——同样的界面，在不同服务端上能用的功能可能不同。Navidrome 是开发和测试时的主要参照实现。

密码是明文保存的

Subsonic 的 token 认证要求客户端持有明文密码来现算 md5(密码 + salt)，无法预先哈希。因此 Folia 必须在本地保存明文密码。

建议：

在服务端单独建一个只读账号给 Folia 用，不要用管理员账号。
不要在公用设备上保存凭据。
服务端尽量走 HTTPS。

需要准备什么

一个可访问的服务器地址（含协议和端口，例如 http://localhost:4533）
用户名
密码

在 Folia 中配置

打开 设置 > 选项 > 连接与集成 > Navidrome 设置（命令面板搜索 Navidrome 服务器 可直达）。
启用 连接Navidrome (实验性)。
填写 服务器地址、用户名、密码。
点 测试连接。
连接成功后保存并返回主页，顶部会多出 Navidrome 标签。

连接成功后 Folia 会做什么

第一次连接成功时，Folia 会同时探测服务端能力并缓存下来，之后的体验会更顺：

探测项	用途
`ping`	服务端类型、服务端版本、API 版本、是否声明 OpenSubsonic
`getOpenSubsonicExtensions`	服务端支持哪些 OpenSubsonic 扩展
`getUser`	当前账号的权限
`getMusicFolders`	这个账号能访问哪些音乐库
`getLicense`	授权状态

设置页里的服务器信息区域会显示这些结果，包括 OpenSubsonic 一行的已启用 / 不可用。这是判断“为什么某个功能没有”的第一现场。

Folia 关心的 OpenSubsonic 扩展

扩展	影响
`songLyrics`	能否从服务端取到歌词，尤其是带时间轴的结构化歌词
`playbackReport`	服务端的扩展播放上报能力（基础的 `scrobble` 方法属于 Subsonic 标准，不依赖这个扩展）
`transcoding`	服务端转码能力
`apiKeyAuthentication`	API Key 认证
`formPost`	用 POST 表单提交请求

服务端没有声明的扩展，对应功能就不会生效——这不是 Folia 的开关，改不了。

接入后能做什么

能力	说明
浏览专辑	支持按名称、艺人、最新加入、最近播放、播放频次、随机等排序
浏览歌手与歌手下的专辑
搜索曲库	主页顶部搜索框会自动切到 Navidrome 来源
浏览播放列表
创建、更新、删除播放列表	取决于账号权限
随机歌曲	即时生成的随机播放列表
收藏 / 取消收藏	对应服务端的 star / unstar
读取流媒体地址与封面
读取完整歌曲信息	包括服务端支持时的 ReplayGain 数据
播放记录上报	一次播放会先报 now-playing，播放达到阈值后再报一次 submission。阈值是「歌曲时长的一半」和「60 秒」中较小的那个
读取服务端歌词	通过 OpenSubsonic `getLyricsBySongId`

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

歌词策略

服务器歌曲常见有两类歌词来源：

服务端返回的歌词（OpenSubsonic songLyrics）
Folia 通过在线匹配拿到的歌词

最推荐的做法：把歌词嵌进音频标签

这样通常最稳定，因为：

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

Navidrome v0.63 及以上会通过 OpenSubsonic 的 songLyrics v2 结构化歌词暴露逐字时间轴，Folia 会完整解析它，包括主歌词、翻译和罗马音轨道。这是服务器侧能拿到的最好效果。

在线匹配什么时候有价值

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

在意歌词质量的话，建议在 设置 > 选项 > 播放控制 > 歌词 里打开自动使用最佳歌词，并按偏好设置歌词匹配优先级。

播放服务器歌曲时，播放页右侧面板会出现 Navidrome 标签，可以查看当前用的是服务器歌词还是在线匹配结果、手动重新匹配，以及调节单曲时间偏移。

无法解码的音频（桌面端）

服务器里存的是 Chromium 解不了的格式时（某些 DSD、APE、部分 WavPack 等），桌面端会用内置 FFmpeg 把它临时转成兼容的无损格式再播放：

不改动服务器上的原文件。
转换结果进本地缓存目录。
Automix 的节拍分析也会走转换后的音频。
可在 设置 > 选项 > 播放控制 > 播放设备 > 自动转换无法播放的音频 关闭。

这个能力只有桌面版有；Web 版遇到浏览器解不了的格式仍然会失败。

它和本地音乐有什么区别

两者都能播你自己的曲库，但侧重点不同。