152 lines
5.1 KiB
Markdown
152 lines
5.1 KiB
Markdown
## 05 - 音乐整理
|
||
|
||
### 1. 功能概述
|
||
|
||
- **功能名称**：音乐整理
|
||
- **后端服务**：`RenameService` + `OrganizeService`
|
||
- **前端组件**：`RenameTab.vue`
|
||
|
||
**主要用途**：
|
||
|
||
- 将已整理好标签的音频文件按 Navidrome 标准目录结构重命名、分组，并生成封面、歌词与整理报告。
|
||
|
||
### 2. 目标目录结构规范
|
||
|
||
- 标准结构示例：
|
||
- `艺术家/专辑(年份)/曲号 - 标题.ext`
|
||
- 示例：
|
||
- `周杰伦/七里香(2004)/01 - 七里香.flac`
|
||
- `Adele/21(2011)/01 - Rolling In The Deep.flac`
|
||
|
||
### 3. A-Z 索引分组策略
|
||
|
||
- **正常艺术家**：
|
||
- 中文艺术家：按拼音首字母分组（如“周杰伦” → `Z/周杰伦/...`）
|
||
- 英文艺术家：按首字母分组（如“Adele” → `A/Adele/...`）
|
||
- **合辑**：
|
||
- 统一归入 `Various Artists` 目录，不参与 A-Z 分组
|
||
- **特殊字符开头**：
|
||
- 数字或特殊符号开头的艺术家统一归入 `#/` 分组
|
||
- **多音字处理**：
|
||
- 使用 Pinyin4j 默认取第一个读音，绝大多数场景可以接受
|
||
|
||
### 4. 质量隔离机制
|
||
|
||
- 根据标签完整度对文件进行分层处理：
|
||
- **严格模式**：必须同时包含 `Title + Artist + Album` 才参与整理
|
||
- **宽松模式**：只要有 `Title` 即可参与整理
|
||
- 对于缺少必要标签的文件：
|
||
- 自动移动到 `_Manual_Fix_Required_/Missing_XXX/` 等目录
|
||
- 便于后续集中使用标签工具（如 MusicBrainz Picard）修复
|
||
|
||
### 5. 附加功能
|
||
|
||
#### 5.1 封面提取
|
||
|
||
- 从音频文件内嵌封面中提取 `cover.jpg` 到专辑目录
|
||
- 按专辑粒度判断：
|
||
- 只要专辑中任一文件含有封面，即视为该专辑有封面，并提取一次
|
||
|
||
#### 5.2 歌词提取
|
||
|
||
- 从音频文件中提取内嵌歌词到 `.lrc` 文件
|
||
- 按单曲粒度判断：
|
||
- 每个文件独立检查是否含有歌词
|
||
|
||
#### 5.3 整理报告生成
|
||
|
||
- 整理结束后自动生成报告文件：
|
||
- 文件名：`report_YYYYMMDD_HHMMSS.txt`
|
||
- 位置：目标目录下 `_Reports/` 子目录
|
||
- 报告内容包括：
|
||
- 生成时间、扫描文件数
|
||
- 缺失封面的专辑列表
|
||
- 缺失歌词的文件列表
|
||
- 统计摘要（总专辑数、无封面专辑数及百分比、无歌词文件数及百分比）
|
||
|
||
### 6. 前端交互流程
|
||
|
||
1. 用户选择“源目录”（通常是经过汇聚、转码、去重后的 staging 目录）
|
||
2. 选择“目标目录”（正式库或 staging 输出目录）
|
||
3. 配置：
|
||
- 严格 / 宽松 模式
|
||
- 是否提取封面
|
||
- 是否提取歌词
|
||
- 是否生成报告
|
||
4. 执行任务，通过 WebSocket 订阅进度与当前处理文件
|
||
5. 整理完成后，可在 `_Reports/` 中查看整理报告，对问题文件做二次处理。
|
||
|
||
### 7. 建议使用顺序
|
||
|
||
- 推荐整体流水线：
|
||
1. 01-音频文件汇聚
|
||
2. 02-音频格式智能处理
|
||
3. 03-音乐去重
|
||
4. 04-音乐元数据繁体转简体
|
||
5. **05-音乐整理（本模块）**
|
||
6. 06-整理入库
|
||
|
||
- 这样可以保证进入主库前,目录结构、文件命名、标签内容和资源(封面/歌词)都已基本规范。
|
||
|
||
### 8. 测试用例需求
|
||
|
||
#### 8.1 后端测试
|
||
|
||
**单元测试**:
|
||
- 测试中文拼音首字母提取的准确性(含多音字)
|
||
- 测试英文首字母分组逻辑
|
||
- 测试特殊字符处理(数字、符号归入"#"分组)
|
||
- 测试合辑识别与 Various Artists 归类
|
||
- 测试标签完整度检查(严格/宽松模式)
|
||
- 测试目录结构生成:"艺术家/专辑(年份)/曲号 - 标题.ext"
|
||
- 测试封面提取逻辑(按专辑粒度)
|
||
- 测试歌词提取逻辑(按单曲粒度)
|
||
- 测试整理报告生成(缺失封面/歌词统计)
|
||
|
||
**集成测试**:
|
||
- 准备测试音频文件:
|
||
- 完整标签的文件(中文/英文/日文艺术家)
|
||
- 标签不完整的文件(缺 Title/Artist/Album)
|
||
- 含内嵌封面的文件
|
||
- 含内嵌歌词的文件
|
||
- 合辑文件(AlbumArtist = Various Artists)
|
||
- 测试严格模式:缺标签文件移动到 _Manual_Fix_Required_/
|
||
- 测试宽松模式:只要有 Title 即可整理
|
||
- 测试 A-Z 分组的正确性
|
||
- 验证生成的目录结构符合 Navidrome 规范
|
||
- 验证封面与歌词文件的提取与命名
|
||
- 验证整理报告的准确性
|
||
- 测试异常场景:无效标签、特殊字符、超长文件名
|
||
|
||
#### 8.2 前端测试
|
||
|
||
**单元测试**:
|
||
- 测试源目录与目标目录的路径校验
|
||
- 测试模式选择(严格/宽松)的状态管理
|
||
- 测试功能开关(提取封面/歌词/生成报告)的状态管理
|
||
- 测试进度信息的实时更新
|
||
|
||
**集成测试**:
|
||
- 测试完整的用户操作流程
|
||
- 测试整理报告的查看与下载
|
||
- 测试不同配置组合的效果
|
||
|
||
**测试数据**:
|
||
- 小规模场景:50 首歌曲,5 个艺术家,10 个专辑
|
||
- 中等规模场景:5000 首歌曲,200 个艺术家,500 个专辑
|
||
- 大规模场景:50000+ 首歌曲,测试性能与报告生成
|
||
- 边界场景:
|
||
- 中英日混合艺术家
|
||
- 多音字艺术家(如:曲婉婷、单依纯)
|
||
- 特殊字符开头的艺术家
|
||
- 合辑专辑
|
||
- 缺失各种标签的文件
|
||
- 超长文件名与路径
|
||
|
||
**质量验证**:
|
||
- 验证生成的目录结构在 Navidrome 中的兼容性
|
||
- 抽查 A-Z 分组的准确性
|
||
- 验证封面图片的完整性与格式
|
||
- 验证歌词文件的格式与内容
|
||
- 验证整理报告的统计准确性
|