Web 播放器与本地音乐指南
默认播放器入口为 /，可通过 PLAYER_PATH 修改。访问密码用于进入播放器；个人账号用于自己的歌单、设置和目录权限。浏览器会话有效时通常无需重复输入播放器密码。
播放与界面
播放器提供播放队列、音质切换、倍速、睡眠定时、全屏歌词和主题设置。桌面和手机使用响应式布局；可以按自己的使用习惯选择主题、播放器背景和歌词展示方式。
页面会显示版本与构建指纹，例如 v2.1.4 · build 123abcd。版本来自 package.json，指纹由构建或启动脚本刷新，排查同一版本下的自定义改动时可以一并提供。
搜索、歌手与专辑
在线搜索使用酷我（kw）、酷狗（kg）、QQ 音乐（tx）、网易云（wy）和咪咕（mg）等平台数据。可以按单个平台搜索，也可以在支持的搜索类型中使用聚合模式。
单源歌曲搜索由服务端连续获取结果，前端在收到的列表中分页。平台可能限制结果深度，服务端也设有页数和耗时预算，因此页面显示的结果数不一定等于平台自报总数。歌手、专辑和歌单等搜索类型的支持情况随平台而异。
搜索到歌曲信息与取得可播放链接是两个步骤：前者来自音乐平台检索，后者由自定义音源解析。因此，能搜到歌曲但无法播放时，应先检查自定义源、音质和网络请求，而不是反复清空搜索结果。
歌单、收藏与播放队列
播放器支持个人歌单、收藏歌手与专辑、平台歌单、排行榜，以及播放队列调整。个人数据归属于登录账号；公开收藏是否显示和允许访问，由后台公共权限控制。
平台歌单与用户自己的同步歌单用途不同。对个人歌单的增删会影响同步数据；浏览平台榜单不会把整个榜单自动写入个人歌单。
本地音乐与下载
本地音乐页用于查看服务器上的音频文件，包括下载目录、缓存目录和已授权的自定义音乐目录。可查看音频规格、封面、歌词和关联状态，使用 &、|、! 组合条件筛选，并执行批量操作。
| 操作 | 文件保存位置 / 影响 |
|---|---|
| 浏览器下载 | 由浏览器保存到访问设备，受浏览器下载权限控制 |
| 服务端下载或缓存 | 保存到服务器目录，占用服务器磁盘和网络资源 |
| 关联在线歌曲、更新元数据 | 将本地文件与平台歌曲信息关联，相关操作可能改写音频标签 |
| 嵌入歌词 | 写入音频文件中的歌词标签，具体支持取决于格式 |
| 洗版 | 解析并下载其他可用音质来替换已关联文件，自定义目录操作需要额外权限；与播放时的转码是两套机制 |
服务端下载使用后台队列，支持查看进度、调整并发、恢复和移除任务。关闭网页与停止服务端任务不是同一件事；需要停止下载时应在任务界面操作。
自动匹配针对选中的未关联文件识别、检索并关联平台歌曲，保留逐曲结果，可查看进度或取消。默认并发为 2，可设置 1–4；服务重启后未完成任务标记为中断，需要重新选择剩余歌曲。相同歌名、现场版和重录版仍可能匹配错误，批量改写前先抽查结果。
洗版需要歌曲已有可用的平台来源与 ID。已是目标音质、目标文件已存在、没有获得符合方向的替换音质时会跳过；不能把它理解为把任意低码率文件转换成真正的无损音频。
已有 NAS 音乐目录可以挂载后分配给用户。例如容器挂载 /mnt/nas/music:/library:ro 后，后台填写 /library，不是宿主机路径 /mnt/nas/music。只读挂载适合浏览播放；需要写入标签、删除或洗版时，还要同时满足容器文件权限和账号操作权限。
自定义源、主题与歌词卡片
自定义源脚本负责解析在线歌曲的音频链接。导入后检查源是否启用、是否支持目标平台和音质；不同脚本的可用性、返回速度及链接有效期可能不同。
播放器还提供主题、深浅色模式、背景选择和歌词分享卡片。生成卡片时可以选择适合分享平台的比例，再保存图片。
音效、投屏与后台任务
播放器有均衡器和变调控制，处理能力取决于浏览器音频接口及资源访问条件。如果启用音效后需要恢复原生播放或 AirPlay，可使用音效面板中的恢复入口。
Chromecast 支持具备 Cast 能力的桌面/Android Chromium 浏览器，需要安全上下文，通常为 HTTPS。接收设备还必须能访问服务器和媒体资源；浏览器中的 blob: 或本地文件链接不能直接交给接收设备读取。投屏时由接收端播放，浏览器音效和倍速不会应用到接收端；iOS 保留原生 AirPlay 路径。
网络歌单定时检查、同步下载和普通歌单同步分别配置。可以在任务界面检查上次执行、下次执行和结果；启用歌单同步不会自动开启音频下载。更多操作步骤见 播放器指南。
账号音源与公开音源
源脚本保存在数据目录的 users/source/ 下，公开源使用 _open，个人源使用对应账号目录。登录用户可组合使用公开源与自己的源；同 ID 个人源优先。个人对公开源的启用偏好与排序独立保存，不应当作修改所有人的公开源配置。
个人源禁用后，不会自动回退到同 ID 的公开源。遇到列表里有源但不参与解析时，检查启用状态、平台支持和账号排序，而不只是检查公开目录有没有脚本。需要 VM 兼容模式的源还受全局 system.allowUnsafeVM 和该源自身选项共同控制，不要把开启兼容模式当作修复一切解析失败的办法。
本地音乐的建议操作顺序
- 登录目标账号，核对持久存储位置与临时浏览位置。
- 扫描目录，先检查少量文件的歌名、歌手、音质和时长。
- 对未关联歌曲手动选取候选或使用自动匹配，抽查版本是否正确。
- 需要时再执行元数据、封面或歌词写入；自定义目录必须允许写入。
- 洗版前核对替换方向和任务结果，保留不可替代的原文件备份。
自动匹配会保存逐曲状态，重启后未完成任务标记为中断，不承诺继续自动运行。取消也不撤销已完成的关联。洗版通过重新下载可用音质替换文件，不会凭空恢复有损文件已经丢失的信息；实际可获得音质可能低于请求值，查看每项结果。
音频代理与链接缓存
搜索数据、播放链接和音频字节是不同请求。播放器媒体代理让服务器转发音频；服务器出站代理决定服务如何访问平台或源脚本需要的地址，两者用途不同。HTTPS 页面遇到 HTTP 音频链接时，可检查自动代理设置。
音频是否来自本地文件取决于匹配结果、目录和播放设置。浏览器缓存的历史链接可能过期；重复使用失败时重新解析。清理链接记录、清理歌词和删除服务器音频不是同一个操作，应按界面提示确认范围。
PWA、移动端和后台播放
支持安装的浏览器可以将播放器添加到主屏幕。PWA 不等于自动离线保存全部歌曲，操作系统仍可能限制后台音频、网络请求和自动播放。锁屏控制、AirPlay 和设备发现受客户端环境影响；先在普通前台播放中确认歌曲本身可用。
推荐与不喜欢规则
收藏歌手/专辑与不喜欢规则分别保存。Subsonic 可按配置隐藏规则命中的歌曲，评分与不喜欢的双向联动也有独立开关；关闭联动时不能假定低评分会删除或屏蔽歌曲。合唱、跨平台同名匹配和推荐过滤存在单独设置，误命中时应检查规则范围。
后台任务不等于浏览器任务
服务端下载、同步下载和自动匹配由后台执行；浏览器下载由访问设备执行。关闭页面不会自动取消已经提交的服务端任务。查看任务状态并使用对应的停止/取消入口，不要依靠刷新页面终止操作。