Web 播放器

默认地址为 http://服务器IP:9527/。播放器能够搜索在线音乐、播放本地曲库、管理歌单并把歌曲下载到浏览器或服务器。管理后台位于 /admin；v1.5.0 起旧 /music 网页入口已删除。

登录与音源

使用同步账户登录后，播放器会加载当前账户的歌单、收藏、设置和自定义源。自定义源按用户隔离；管理员共享的源会显示共享来源，但接收用户不能修改源脚本。

首次使用先进入 设置 -> 自定义源 导入可信脚本。没有可用源时，在线歌曲可能只能浏览元数据，无法获取播放地址。

搜索与浏览

搜索结果同时展示平台、可用音质、歌手、专辑和操作入口，底部播放栏保持常驻。

• 支持网易 wy、腾讯 tx、酷我 kw、酷狗 kg、咪咕 mg。
• 支持歌曲、歌手、专辑、歌单、排行榜和热搜。
• 搜索歌手后可查看热门、最新、全部歌曲及全部专辑。
• 专辑卡片可以直接下载整张专辑，无需先进入详情。
• 可收藏歌曲、歌手、专辑并管理自建歌单。

在线平台接口会变化，搜索结果存在但无法播放通常表示当前音源无法解析该歌曲，需要更新音源、配置平台凭据或允许换源。

音质

默认音质为 无损音质。播放器会请求目标音质，当前平台不可用时按设置尝试同歌曲换源或向下兼容。

标识	显示名称
128k	标准音质
320k	高音质
flac	无损音质
flac24bit	24bit 无损
hires	高解析度
atmos	空间音频
atmos_plus	增强空间音频
master	母带音质

音质名称表示音源接口返回的规格，不应仅用文件扩展名判断。某些平台的 Hi-Res 资源可能经过平台专有封装或返回与标签不一致的容器，最终以文件探测结果和播放器实际解码信息为准。

下载音质选择框会探测实际文件大小，并在大小后显示最终解析平台。探测结果可能因临时链接过期重新请求；显示未知大小不代表一定无法下载，但应先检查音源是否支持 HEAD/Range 请求。

同一首歌曲的不同音质可能来自不同平台，选择前以弹窗显示的大小和平台为准。

播放队列与控制

• 播放、暂停、上一曲、下一曲、进度和音量。
• 列表循环、单曲循环、随机与顺序播放。
• 0.5x 至 2.0x 倍速和睡眠定时。
• 播放队列拖拽排序、批量移除和定位当前歌曲。
• 自动记录播放进度，重新打开后恢复。
• Media Session 支持系统媒体面板、锁屏控制和进度拖动。
• 淡入淡出、均衡器、音效与音频可视化。

歌词与封面

• 原词、翻译、罗马音和逐字歌词。
• 字体、字号、对齐与显示轨道设置。
• 歌词本地缓存和服务器歌词缓存。
• 外置歌词与内嵌歌词可分别选择逐行 LRC、逐字 LRC 或增强型 LRC（ESLyric）。TX 优先获取 QRC 逐字歌词；不可用时只降级到同平台逐行歌词。
• 下载时保存 .lrc，并尝试写入音频文件 USLT 标签。
• 自动获取和嵌入专辑封面。
• 歌词卡片可设置比例、色彩和行数后导出。

并非所有容器都支持写入歌词或封面。系统会保留外置歌词作为兼容方案；“有封面”状态以实际可读取的图片数据为准，而不是只检查标签字段存在。

主题与显示

设置页面按系统、显示、逻辑和日志分类；默认音质、自定义源和主要播放选项都在此管理。

• 多套主题、深色和浅色模式。
• 播放器详情页、封面、歌词和底栏显示控制。
• 底栏波形及详情页多种可视化效果。
• 桌面和移动浏览器响应式布局。
• PWA 安装及弱网缓存。

缓存层级

播放器按以下顺序尝试播放：

1. /music/<用户名> 中已下载且匹配的本地文件。
2. /cache/<用户名> 中已缓存的文件。
3. 浏览器中尚未过期的播放链接。
4. 调用自定义源重新解析在线地址。

命中本地文件时不应再次在线换源。若文件缺少平台 ID 或元数据无法匹配，系统可能无法把它与在线歌曲识别为同一首，处理方法见故障排查。

账户与访问保护

Web 播放器使用同步账户加载并隔离歌单、自定义源、下载与个人设置。管理后台使用独立的管理员密码；通过公网访问时，建议在反向代理层启用 HTTPS 和额外访问控制。