本地音乐使用指南
一、文档概述
- 文档目的： 指导用户在 Ceru Music 中管理并播放存储在本地磁盘上的音乐文件。
- 功能简介： 本地音乐功能支持添加本地目录并自动扫描音频文件，提供本地歌曲的搜索过滤、编辑标签、在线音频匹配（获取封面与歌词）等能力。
- 适用平台： Windows、macOS 桌面客户端
- 适用用户： 持有本地音乐收藏的普通用户
二、使用前提
- 已安装 Ceru Music（澜音）最新版本。
- 本地磁盘上存有音频文件（支持 mp3、flac、wav、ogg 等常见格式）。
- 应用拥有对目标目录的读取权限。
三、功能说明
| 功能 | 说明 |
|---|---|
| 添加音乐目录 | 指定一个或多个本地文件夹，应用将扫描其中的音频文件 |
| 扫描本地音乐 | 对已添加目录进行扫描，识别音频文件并读取元数据 |
| 播放本地音乐 | 将本地歌曲加入播放列表并播放 |
| 本地搜索 | 在本地音乐列表中按歌曲名、歌手、专辑名过滤 |
| 标签编辑 | 修改本地音频文件的 ID3/元数据标签（名称、歌手、专辑等） |
| 音频匹配 | 通过在线音源识别本地歌曲，自动填充封面和歌词 |
| 多选操作 | 批量选中歌曲执行统一操作 |
四、操作步骤
4.1 添加音乐目录
- 点击左侧导航栏中的「本地」，进入本地音乐页面。
- 如果尚未添加任何目录，页面中央会显示引导提示，点击「添加目录」。
- 在弹出的系统文件选择对话框中，选择存放音乐的文件夹，点击「确定」。
- 重复以上步骤可以添加多个目录。
注意： 添加目录后，应用将自动开始扫描，扫描过程中页面上方会显示扫描进度。
4.2 扫描与刷新本地音乐
扫描目录后，歌曲将显示在列表中。如果后续在目录中新增或删除了文件，可以手动刷新：
- 在本地音乐页面右上角，点击「刷新」（↺）图标。
- 应用将重新扫描已添加的全部目录并更新列表。
4.3 播放本地音乐
| 操作 | 方式 |
|---|---|
| 添加到播放列表末尾并播放 | 双击列表中的歌曲名称 |
| 插入列表开头并立即播放 | 点击歌曲左侧的 ▶ 图标 |
| 右键歌曲 | 弹出上下文菜单，可选择播放方式、编辑标签、匹配音频等操作 |
4.4 搜索本地音乐
- 在本地音乐页面顶部的搜索框中输入关键词。
- 列表将实时过滤，仅显示名称、歌手或专辑中包含该关键词的歌曲。
- 清空搜索框后自动恢复显示全部本地歌曲。
4.5 编辑本地歌曲标签
标签编辑可修改存储在音频文件中的元数据（ID3 标签），包括歌曲名、歌手、专辑等。
- 右键单击目标歌曲，在上下文菜单中选择「编辑标签」。
- 在弹出的标签编辑器中修改相应字段。
- 点击「保存」确认修改，修改将写入原音频文件。
注意： 标签修改直接写入原文件，操作不可撤销，请谨慎修改。
4.6 音频匹配（获取封面与歌词）
音频匹配功能通过向在线音源发起查询，将本地歌曲与在线数据关联，从而获取专辑封面和歌词。
单首匹配：
- 右键单击目标歌曲，选择「匹配音频」（或相关选项）。
- 应用将以歌曲名和歌手名为关键词查询在线音源，返回候选匹配结果。
- 在结果列表中选择最匹配的条目，点击确认。
- 匹配成功后，该歌曲将使用对应的在线封面和歌词。
批量匹配：
- 在列表右上角启用「多选」模式。
- 勾选需要匹配的多首歌曲。
- 点击「批量匹配」，应用将自动对每首歌曲按名称和歌手查询并应用最佳匹配。
- 批量匹配进度会在页面上方显示（已处理数/总数）。
五、操作结果
- 目录添加成功：扫描完成后，歌曲列表中出现对应的音频文件条目。
- 音频匹配成功：歌曲封面更新为在线专辑图片，播放时歌词同步显示。
- 标签编辑成功：修改保存后，列表中歌曲信息实时更新。
六、注意事项
- 扫描结果只包含应用能识别的音频格式文件，不支持的格式将被忽略。
- 音频匹配需要网络连接，且依赖已安装的在线音源插件。
- 批量匹配会按文件名自动选取最佳结果，准确率不能保证，建议针对匹配错误的歌曲手动重新匹配。
- 删除已添加目录不会删除本地磁盘上的音频文件。
- 本地歌曲导出播放列表时，本地音源歌曲会被自动筛除（仅导出在线音源歌曲），以保证播放列表在其他设备上的兼容性。
七、常见问题
Q1：添加目录后列表没有显示任何歌曲，怎么办？
A：确认所选目录下存在受支持的音频文件（mp3、flac、wav 等）。如果目录层级较深，等待扫描完成后再查看。若仍为空，点击刷新按钮重新扫描。
Q2：本地音乐无法播放，提示格式不支持？
A：部分较少见的音频格式（如 APE、TTA）可能不受支持，可尝试将文件转换为常见格式（如 FLAC、MP3）后重新扫描。
Q3：音频匹配后封面显示为默认图，没有变化？
A：查询结果中可能没有找到匹配项，或匹配结果没有可用封面。可尝试手动修改歌曲名与歌手名后重新匹配，或通过「编辑标签」手动指定封面。
Q4：批量匹配时进度卡住不动？
A：网络请求超时或音源接口响应慢可能导致进度停滞，等待一段时间后若仍无响应，可退出当前页面后重新进入并对未成功匹配的歌曲单独操作。
Q5：编辑标签保存后，歌曲名变成乱码？
A：可能是文件编码与应用读取方式不匹配，常见于旧版 MP3 文件的 GBK 编码标签。尝试使用第三方工具（如 Mp3tag）将标签编码转换为 UTF-8 后再在应用中编辑。