Web 播放器
默认地址为 http://服务器IP:9527/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，并尝试写入音频文件 USLT 标签。 - 自动获取和嵌入专辑封面。
- 歌词卡片可设置比例、色彩和行数后导出。
并非所有容器都支持写入歌词或封面。系统会保留外置歌词作为兼容方案；“有封面”状态以实际可读取的图片数据为准，而不是只检查标签字段存在。
主题与显示
设置页面按系统、显示、逻辑和日志分类；默认音质、自定义源和主要播放选项都在此管理。
- 多套主题、深色和浅色模式。
- 播放器详情页、封面、歌词和底栏显示控制。
- 底栏波形及详情页多种可视化效果。
- 桌面和移动浏览器响应式布局。
- PWA 安装及弱网缓存。
缓存层级
播放器按以下顺序尝试播放：
/music/<用户名>中已下载且匹配的本地文件。/cache/<用户名>中已缓存的文件。- 浏览器中尚未过期的播放链接。
- 调用自定义源重新解析在线地址。
命中本地文件时不应再次在线换源。若文件缺少平台 ID 或元数据无法匹配，系统可能无法把它与在线歌曲识别为同一首，处理方法见故障排查。
访问保护
可以通过管理后台或环境变量增加播放器入口密码：
ENABLE_WEBPLAYER_AUTH=true
WEBPLAYER_PASSWORD=your-password此密码只保护 /music 页面入口。用户数据仍由同步账户隔离，管理后台仍使用独立管理密码。