Subsonic 本地音乐库

Subsonic 本地曲库使用当前账号的持久化存储设置，并叠加已启用的自定义音乐目录。

• 存储选择为 data：读取数据目录下该账号的 music 和 cache。
• 存储选择为 root：读取程序根目录下该账号的 music 和 cache。
• 自定义目录启用且可访问时，同时收录其中歌曲。与主目录重复的实际文件只收录一次。
• 网页文件浏览中的临时根目录/数据目录切换不影响 Subsonic。
• 改变账号的存储设置或关闭自定义目录后，后续请求会重新选择曲库；旧目录歌曲的保存 ID 也不能绕过范围限制。

使用

后台“Subsonic 协议配置 → 本地歌曲歌单 → 返回本地歌曲歌单”控制只读的“本地歌曲(用户名)”歌单，默认开启。设置通过现有后台配置接口保存到服务器配置（subsonic.localPlaylist），关闭后列表和详情均不返回此歌单。开启时服务端在歌单列表首位返回；客户端自行排序时以客户端设置为准。

此歌单汇总当前账号所选存储目录中的歌曲。父开关开启时显示“返回自定义目录歌曲”子开关（subsonic.customPlaylist，默认开启），开启后在本地歌单之后单独返回“自定义目录(用户名)”歌单；账号还需启用自定义音乐目录。关闭父开关时两个歌单均隐藏，子开关的选择保留。两种歌曲分开显示，子开关关闭时不会将自定义歌曲混入本地歌单。

空曲库时保留已启用的入口。切换存储设置后歌单内容同步变化；不会写入 LX 原生歌单或同步到官方客户端。歌曲及专辑时长按协议返回整数秒，内部保留文件的精确时长。

默认推荐页的“最新专辑”“随机专辑”保持在线推荐池及其分页逻辑，不把 NAS 专辑插入推荐池。明确选择 NAS 本地音乐文件夹时，专辑接口才使用本地曲库分支。

客户端选择“NAS 本地音乐（存储目录＋自定义目录）”音乐文件夹，可浏览本地专辑、艺术家、流派和随机歌曲。目录模式也有 NAS 本地音乐入口。搜索 local:关键词 仅搜索本地文件；普通搜索会包括本地文件，显式在线搜索仍按在线模式处理。

支持扫描和扫描状态、歌曲/专辑/艺术家详情、封面、外置及内嵌歌词、播放、下载、Range 请求、收藏、评分，以及现有播放记录、队列和书签的本地歌曲解析。开启现有服务端转码配置且安装 ffmpeg 后，本地播放可使用格式转换、码率限制和时间偏移。

歌词按非空外置同名 LRC、内嵌歌词、网页端服务器歌词缓存、已关联平台在线接口的顺序获取。在线回退仅使用已关联平台 ID，不按歌名猜测其他歌曲；请求有超时限制，并按账号复用并发请求、短暂缓存成功结果。外置及内嵌歌词复用网页端扩展歌词解码，结构化接口返回原文、翻译和音译；普通歌词接口按现有翻译配置合并。支持多时间标签、整数秒标签及 offset。逐字内容没有额外转换为 OpenSubsonic 逐字格式。

本地封面支持客户端附加的 al-/ar-/tr-/sg-/mg- 前缀，仍按当前账号可访问的本地文件读取内嵌或目录封面。

普通用户歌单的列表和详情返回统一的封面令牌。获取时优先用歌单自身的网络封面；关联网络歌单未保存封面时尝试从原平台补取；没有则用第一首歌曲的封面（含本地文件封面）。空歌单且无网络封面时返回空内容。封面解析按账号隔离，并兼容客户端附加的前缀。

扫描复用现有文件索引，额外读取曲序、碟号、专辑艺术家、年份、流派。目录不变时曲库结果缓存 30 秒；startScan 可主动刷新。getScanStatus 返回扫描状态、歌曲数量及失败原因。

标记与身份

文件获得独立的 local_<UUID>，在线关联不改变此 ID。响应保留原始歌名，使用 lxStorage=local、lxLinked 和 comment 表达本地身份及关联状态，不改写音频标签。第三方客户端是否显示这些说明取决于客户端支持；不会自动出现通用徽章。

本地歌曲不会按歌名与在线歌曲自动合并，以保留原版、重录版和不同文件版本。专辑按所在目录、专辑名及专辑艺术家分组，避免不同目录中的版本混在一起。

目前身份登记按实际文件路径保存：关联平台及在原路径更新文件会保留 ID；外部移动或重命名文件尚不做指纹追踪，会视为新文件。停止显示不在当前目录范围的歌曲时，原歌单引用和收藏仍保留，切回目录后可恢复。

歌单同步

纯本地歌单只保存在服务端，不进入 LX 官方客户端同步。混合歌单的在线歌曲写入原生歌单，本地歌曲及混排顺序独立保存。在线歌单重新同步时，删除/新增的在线成员随之更新，本地成员保留；新增在线成员默认追加到合成列表末尾。

Subsonic 的按位置删除针对客户端看到的混合列表解析。删除混合歌单会删除其原生在线歌单和本地附加信息，不删除音频文件。若原生歌单被其他同步操作删除，本地附加歌曲仍可以作为服务端歌单查看。

本地歌曲收藏通过 star/unstar 管理。直接向内置“我的喜爱”歌单添加本地成员会提示使用收藏接口。

用户目录中的持久化文件：

• subsonic-local-registry.json：文件身份和元数据，不属于可随意清理的缓存。
• subsonic-local-state.json：本地收藏、纯本地歌单及混合歌单附加信息。

验证

音流的歌单封面加载受歌曲 size 影响：同一歌单、同一网络歌曲，size=0 不加载封面，改为正数后加载。网络歌曲优先返回音源提供的字节数；缺失时用码率 × 时长 ÷ 8 估算，估算值不是精确文件大小。未知时长且无已知大小时仍返回 0。本地歌曲返回真实大小；音频响应的 Content-Length / Range 不使用估算值。

node scripts/subsonic-local.test.cjs 使用隔离临时文件、模拟索引/标签读取和本机 HTTP 服务，覆盖目录选择、账号隔离、播放范围、JSON/XML、歌词、收藏和歌单同步。不会读取生产账号配置或修改真实音乐文件。

真实 NAS 大曲库扫描性能、原生标签库在部署架构上的表现、ffmpeg 实际转码和音流/箭头/Feishin 客户端显示，仍需在对应环境进行集成验证。