本地曲库与下载

V1 将临时播放缓存与长期下载曲库分开保存：

容器目录	用途	是否长期保留
/server/cache/<用户名>	为播放加速的临时歌曲、歌词和链接数据	可清理
/server/music/<用户名>	用户明确下载的曲库和手动放入的歌曲	应备份

清理缓存只应删除 /cache，不会删除 /music。部署时务必将两者映射到不同的 NAS 目录。

本地音乐页面展示实际音质、采样信息、来源平台、文件大小和元数据完整状态。

两种下载模式

下载到浏览器

文件由浏览器保存到电脑或手机的下载目录。任务依赖当前页面，关闭浏览器后不能由服务器继续执行。

下载到服务器

文件写入 /music/<用户名>。服务器保存下载队列，因此：

• 关闭浏览器后仍继续下载。
• 重新打开并登录同一账户后可恢复原队列。
• 并发数使用该用户在播放器设置中的值，并持久化到服务器。
• 支持暂停全部、继续全部、重试、移除和清理已完成任务。

下载范围

• 单首歌曲。
• 搜索结果、歌单或本地选择项批量下载。
• 专辑详情内全部歌曲。
• 歌手或收藏专辑页面中的单张专辑一键下载。

批量任务会先收集完整歌曲列表再加入服务端队列，页面只负责提交和显示状态，不应因大量任务阻塞浏览器。

音质与文件大小

单曲下载会读取全部可选音质，并探测每档音质的实际大小和最终平台。所选音质不可用时，是否降级或换源取决于播放器设置及音源能力。

音质从低到高显示为：标准、高音质、无损、24bit 无损、高解析度、空间音频、增强空间音频、母带。

“未知大小”的常见原因：

• 音源没有返回文件长度。
• 临时 URL 已过期。
• 平台拒绝 HEAD 或 Range 探测。
• 所选音质实际不存在。

系统会在重新打开下载弹窗时再次探测，不应把一次失败结果永久缓存。

弹窗中的平台是该档音质最终解析到的平台，不一定与搜索结果的初始平台相同。

文件名与元数据

默认简洁命名：

歌名 - 歌手 - 音质 - 专辑名.扩展名

平台和平台歌曲 ID 记录在音频元数据及服务器索引中，不再追加到可见文件名。下载时可写入：

• 歌名、歌手、专辑和音质。
• 实际解析平台与平台歌曲 ID。
• 封面图片。
• 内嵌歌词，并同时保留外置 .lrc。

批量重命名只改变文件名；批量更新元数据用于修复旧文件的来源、封面和歌词识别。

扫描手动加入的歌曲

将音频放入 NAS 映射的 music/<用户名> 后，在播放器打开 本地音乐 并刷新扫描。扫描支持多层目录，不要求所有文件位于同一级。

大规模曲库首次扫描需要读取文件和标签。数万首歌曲会明显变慢，应：

1. 保持目录映射在本地 NAS 文件系统，避免高延迟网络挂载。
2. 分批放入并等待一次扫描完成。
3. 避免扫描期间同时批量写入或移动文件。
4. 查看服务端日志，区分仍在扫描、文件格式不支持和权限错误。

本地音乐搜索与筛选

支持歌名、歌手、专辑搜索，以及音质、来源和元数据状态筛选。打开本地音乐页面时会恢复默认筛选，避免上一次条件导致列表看似为空。

布尔运算符支持中英文和全角符号：

逻辑	写法
与	AND、与、&、＆
或	OR、或、`
非	NOT、非、!、！
括号	()、（）

运算符后输入英文或中文冒号进行激活，冒号本身不会保留。例如排除王力宏：

!:王力宏

排除王力宏和徐良：

!:王力宏 &: !:徐良

查找周杰伦或蔡依林但排除 Live：

(:周杰伦 |: 蔡依林 ): &: !:Live

快速搜索和高级搜索使用同一表达式规则。全选只选择当前筛选结果，不选择被表达式排除的歌曲。

批量管理

本地音乐支持选择当前页、全选筛选结果、反选和清空选择，并可执行：

• 加入自建歌单。
• 删除文件。
• 批量重命名。
• 更新音频元数据。
• 补全封面、补全歌词和嵌入歌词。
• 进入歌曲洗版。

没有平台 ID 的手动文件无法加入可跨客户端同步的歌单，但不影响本地播放和文件管理。