Web 播放器使用指南

LX Music Sync Server 在路由 /music 提供了一个现代化的 Web 音乐播放器。可以实现远程播放、搜索和多端同步交互。

核心功能清单

当前 Web 播放器支持的功能：

• 搜索与音源：支持五大音乐平台搜索，支持自定义上传 JS 脚本或导入 URL 扩展音源。
• 播放控制：多音质选择（128k/320k/FLAC/Hi-Res）与音质失败自动降级。支持调速（0.5x-2.0x）、淡入淡出、播放进度记忆。
• 用户交互：支持快捷键、PWA、歌曲评论、多种播放模式（单曲循环、列表循环、随机等）。
• 同步功能：支持读取和显示用户保存在服务端的收藏和歌单，支持热搜显示、批量下载操作。
• UI 体验：底部音频波形显示、内置 5 种主题、睡眠定时器。
• 歌词扩展：支持显示翻译及罗马音，支持卡拉OK逐字高亮渲染，支持分享歌词图片。

---

访问播放器

默认访问地址： 示例：http://IP:9527/music

如果管理员在服务器环境变量中设置了 ENABLE_WEBPLAYER_AUTH = true，则每次打开该页面时必须输入设定的 WEBPLAYER_PASSWORD 才能进入播放界面。

---

核心机制说明

Web 播放器对于请求和缓存采用了以下机制：

1. 音源脚本的账号隔离与管理机制

为了确保多用户之间互不干扰，特别是配置不同音源时，服务端对第三方音源脚本的存储、渲染和调度制定了完备的隔离策略：

• 分类保存（物理隔离）：如果你在登录账号后上传了对应的 JS 脚本源，文件会被独立保存在 data/users/source/{用户名} 文件夹下。如果没有登录而直接（或由管理员）上传，源文件会被放到全局公开目录 source/_open 中。
• 列表融合渲染：前端获取源列表时，系统会获取“公开目录”下的所有可用源，再加上“你当前专属目录”下的私有源，组合成你的最终可见音源库。
• 同源私有覆盖（屏蔽/去重）：如果在全局公开目录和你的专属目录下存在相同 ID 的音源，系统会绝对优先认准你的私有源，此时对应的公开源会被彻底屏蔽（在你的列表中去重隐藏）。特别注意： 即使你在面板上将自己上传的这款同名私有源设为“禁用”，系统也会认定“你明确拒绝/关闭了此源”，而绝不向下越级去调用其实默认处于开启状态的公开同名源。
• 公开源开关状态独立（偏好隔离）：当你在你自己的管理面板里，对别人（普通公开）的音源进行启用 / 禁用操作时，系统不会去全局库里修改它的真实状态影响他人。而是会在你专属目录下生成一个 states.json，只独立记录“你对这个公开源”的抵制或启用偏好。服务端抓取真实播放链接前，也会严格按照你的这个私人偏好来调度。
• 混合排序与容错机制（按状态分组）：拖拽音源列表进行排序时，系统会将当前混合列表的绝对顺序保存在你专属目录下的 order.json 中。
  • 顶级分组：“已启用”的源永远会被锁定分组在“已禁用”的源之前。
  • 组内绝对方位：在各自启/禁的组别内部，即使你的私有源和公开源随意混合，它们都会严格遵守你所保存的相对拖拽顺序。
  • 动态向下兼容：即使某个公开源随后被管理员全局删除，凭借上述记录机制，你列表中的其余源仍将严格保持相对顺序不变；如果你的专属排序配置意外清空或损坏，系统也会智能退回到读取公共大厅的默认排序数据作为备用，最大程度做到平滑、无感体验。

2. 音质自动降级

在前端选择了默认音质后（例如选了 320k），如果解析引擎在获取目标音质时失败： 系统会自动按照 flac -> 320k -> 192k -> 128k 的降级顺序往下尝试。直到成功获取到能够正常解析并播放的低一级音质为止，从而尽量避免无法播放的问题。

3. 数据层代理转发

为了避免浏览器直接获取在线音乐链接时可能遇到的跨域阻断（CORS）： 如果在设置中开启了播放音乐代理 或 下载音乐代理：

• 前端浏览器将不再直接请求真实的音乐直链，而是请求你搭建的这个 LX Node 服务端。
• 服务端在后台获取到真实的音乐数据流后，再直接分包转发给你的前端浏览器，以此绕开跨域限制。

此外，Web 播放器还支持自动代理 (Auto Proxy) 功能：

• 混合内容保护：当你将服务部署在 HTTPS 协议下时，浏览器出于安全考虑会默认阻断 HTTP 协议的媒体资源请求（即“混合内容”限制）。
• 智能识别：开启“自动代理”后，如果系统检测到当前身处 HTTPS 环境，而获取到的音源链接是 HTTP 协议，会自动将该请求转由服务端代理。这种模式既解决了 HTTPS 下的播放兼容性问题，又能在音源本身支持 HTTPS 时保留直连的响应速度。

4. 三级缓存播放机制

为减少重复网络请求，提高点播和进度条拖拽速度，播放请求进行了三级分层：

• 第一级 (文件缓存)：如果在设置里开启了“缓存歌曲文件”，音频会在第一次播放时下载并保存在服务器的 cache 物理文件夹内。第二次播放同一首歌时，服务端直接把这首本地文件传输给前端（支持 206 Partial Content 断点拉取），可以随时无延迟拖拽进度条。
• 第二级 (链接缓存)：系统会在浏览器的 LocalStorage 中保存最近解析成功过、且可能附带了时效 Token 的音乐直链 URL。如果在过期期限前该歌再次被触发，会优先尝试用这个已有链接进行加载。
• 第三级 (重新实时获取)：当本地服务端找不到缓存，并且浏览器保存的历史链接也失效报错时，系统会重新调用音源脚本向音乐平台发送请求并运算获得一个新的播放链接。

---

⚠️ 数据空间清理：播放器设置界面中的各分项“缓存清理”等按钮，在点击后会向服务端下发指定目录的清理指令（调用 fs.unlinkSync 等），真实删除存在硬盘或 LocalStorage 上的历史下载文件和链接记录。