3.8 KiB
3.8 KiB
02 - 音频格式智能处理
1. 功能概述
- 功能名称：音频格式智能处理
- 后端服务：
ConvertService - 前端组件：
ConvertTab.vue
主要用途：
- 针对无损音频格式（如 WAV/APE 等）智能转换为 FLAC，提高兼容性和标签支持能力；
- 对于有损格式和已为 FLAC 的文件自动跳过，避免无意义的二次压缩。
2. 智能分类策略
- 无损格式转 FLAC：
- 支持：
WAV,APE,AIFF,WV,TTA等 - 统一转换为
FLAC，保证后续工具（如标签编辑器、Navidrome）有良好兼容性
- 支持：
- 有损格式自动跳过：
- 包括：
MP3,M4A,AAC,OGG,OPUS,WMA等 - 保持原样，不做任何处理
- 包括：
- 已是 FLAC 的文件直接跳过：
- 避免重复转换和无意义的文件改动
3. FFmpeg 集成方案
- 使用
ProcessBuilder调用系统中的ffmpeg命令行进行转码：- 典型命令示例（伪代码）：
ffmpeg -i input.wav -compression_level 5 output.flac
- 典型命令示例（伪代码）：
- 转码参数约定：
- 压缩级别：
5（在压缩率与速度之间做平衡） - 保留原始采样率、声道数和位深度，确保音质无损
- 压缩级别：
- 错误处理：
- 转码失败时记录日志，并在进度信息中体现失败计数
4. 任务模式（移动 / 复制）
- 移动模式：
- 转换成功后删除源文件，仅保留 FLAC 文件
- 适用于已经确认不再需要原始无损格式的场景
- 复制模式：
- 保留源文件，在目标目录生成 FLAC 副本
- 适合试运行或希望保留源文件做长期归档的场景
5. 前端交互流程
- 用户在前端选择：
- 输入目录（待扫描的音频文件目录）
- 输出目录（FLAC 目标目录，可与输入目录相同或独立）
- 模式（移动 / 复制）
- 点击开始任务后，前端调用后端
/convert类接口 - 后端创建异步任务并开始遍历、分类、转码
- 通过 WebSocket 周期性推送进度：
- 总文件数、已处理数量、成功/失败数
- 当前处理文件路径
- 前端组件展示进度条与当前文件，并在任务完成时弹出结果摘要
6. 与其他模块的配合
- 常与 01-音频文件汇聚 搭配:先汇聚到一个扁平目录,再执行智能转码
- 转码完成后通常交由 05-音乐整理 进行目录重组和标签检查
- 在 06-整理入库 前确保所有无损源文件已经统一为 FLAC,减少后续维护成本
7. 测试用例需求
7.1 后端测试
单元测试:
- 测试音频格式分类逻辑(无损/有损/FLAC)
- 测试 FFmpeg 命令构建的正确性
- 测试转码参数配置(压缩级别、采样率保留等)
- 测试转码失败时的错误处理与日志记录
- 测试文件删除逻辑(移动模式下的源文件清理)
集成测试:
- 准备各种格式的测试音频文件(WAV、APE、FLAC、MP3、M4A 等)
- 测试完整的转码任务执行流程
- 验证转码后的 FLAC 文件音质无损(采样率、位深度、声道数)
- 测试混合格式目录的智能分类与跳过逻辑
- 测试异常场景:FFmpeg 未安装、损坏的音频文件、磁盘空间不足
7.2 前端测试
单元测试:
- 测试输入/输出目录的路径校验
- 测试模式选择的状态管理
- 测试进度信息展示(成功/失败/跳过计数)
集成测试:
- 测试完整的用户操作流程
- 测试任务进度的实时更新
- 测试结果摘要的准确性
测试数据:
- 纯无损文件目录:WAV、APE、AIFF 混合
- 纯有损文件目录:MP3、M4A、OGG 混合
- 混合格式目录:包含无损、有损、FLAC
- 边界场景:超大文件(>1GB)、损坏文件、无效文件扩展名
性能测试:
- 测试批量转码任务的并发性能
- 测试大文件转码的内存占用
- 测试 WebSocket 进度推送的频率与性能影响