Subsonic 客户端

V1 提供 Subsonic/OpenSubsonic 兼容接口，可连接音流、LMP、Feishin 等客户端。不同客户端实现的接口和搜索语法可能不同，出现客户端特有问题时应同时确认服务端日志和客户端支持情况。

连接参数

默认配置：

项目	值
服务器地址	http://服务器IP:9527
Subsonic 路径	/rest
用户名	音云同步账户用户名
密码	该账户同步密码

大多数客户端只需要填写服务器根地址，客户端会自动追加 /rest。如果客户端要求完整 API 地址，再填写包含 /rest 的地址。

反向代理必须支持 Range 请求，否则可能长时间缓冲、跳到下一首或无法拖动进度。

客户端能看到什么

• 当前账户的同步歌单和歌曲。
• /music/<用户名> 中已下载并被曲库识别的文件。
• 歌手、专辑、封面、歌词、随机歌曲和分类浏览。
• 开启在线搜索后，可搜索音源中的网络歌曲。

/cache 主要用于服务端播放复用，不等同于用户下载曲库。客户端缓存由音流、LMP 等应用自行管理，位置和保留时间取决于客户端设置。

在线与本地搜索

搜索前缀：

前缀	行为
tx:关键词	只搜索腾讯
wy:关键词	只搜索网易
kw:关键词	只搜索酷我
kg:关键词	只搜索酷狗
mg:关键词	只搜索咪咕
online:关键词	强制在线搜索
local:关键词	强制本地搜索

部分客户端会自行解析或过滤冒号，例如某些版本的 LMP 无法使用 tx:，而音流可以。这类输入兼容问题需要客户端修复，服务端在收到完整关键词时能够处理这些前缀。

服务端搜索模式：

• fallback：优先本地，无结果时在线搜索。
• merge：合并本地与在线结果。
• local_only：只搜索本地曲库。

播放与缓存

客户端请求歌曲时，服务端优先复用本地下载或缓存文件；没有可用文件时才解析在线地址。流接口支持 HTTP Range，以便客户端快速开始播放和跳转进度。

首次播放在线歌曲可能需要等待音源解析。后续命中缓存时应明显更快。如果每次都重新换源下载，通常是本地文件缺少平台 ID、来源标记错误或匹配信息不一致。

歌词

服务端支持传统 getLyrics、OpenSubsonic 的歌词接口，以及可选翻译歌词。客户端是否显示取决于其调用的接口：

• LMP 能显示而音流不能显示，可能是两个客户端请求的歌词接口不同。
• 服务端会尽量从外置 .lrc、内嵌歌词或在线源返回歌词。
• subsonic.lyricTranslation=true 时可包含翻译。

常见问题

歌单歌曲数量较少

确认歌单记录含有效平台 ID，且本地曲库扫描完成。无 ID 的手动音频不能稳定映射为同步歌单歌曲。

播放等待十秒以上

检查 Range 请求是否被反向代理破坏、音源是否首次解析、客户端是否先探测多个格式，以及服务端是否命中已有本地文件。

重复歌曲

通常是同一歌曲同时以歌单在线记录和本地文件记录出现，且两者 ID 未能归一。先批量更新本地元数据，再重新扫描曲库。

所有音质显示 999k

某些客户端只接受数字码率，而 FLAC、Hi-Res、Atmos 和母带没有可靠的固定 kbps。服务端可能使用兼容占位值；它不代表实际文件码率。实际规格以音频文件探测和音质标签为准。