QQ音乐转 MP3（Audio → MP3）

将QQ音乐下载的音频文件（.ogg、.flac、.m4a、.wav、.aac、.opus 等）转换为通用 MP3 格式，保留元数据（标题、艺术家、专辑等），支持单文件与整目录批处理。

使用时机

✅ 使用此技能当： 需要将QQ音乐下载的 OGG/FLAC/M4A 等音频转为 MP3，使其能在更多设备/软件上播放；需要批量转换一整个目录的音频文件。 ❌ 不要用当： 文件已经是 MP3 且无需转码；文件为 QQ音乐加密格式（.qmc0、.mflac 等，需先用解密工具处理）。

前置依赖

• ffmpeg（含 libmp3lame 编码器）— 转码核心工具
• 检查方式：ffmpeg -version，确认输出含 --enable-libmp3lame

支持的输入格式

⚠️ 加密格式（.qmc0 .qmc2 .qmc3 .qmcflac .qmcmp3 .mflac .mmp3）需要先用 qmcdump 或 Unlock Music 解密后再用本技能转码。

铁律

1. 保留元数据 — 转码时使用 ffmpeg 默认的 metadata copy，不主动剥离标题/艺术家/专辑信息。
2. 不覆盖原文件 — 输出 MP3 与源文件同目录、同文件名（仅扩展名改为 .mp3）；若已存在同名 .mp3 则跳过并提示。
3. VBR 优先 — 使用 -q:a 2（VBR，约 170-210 kbps），在音质与体积间取得最佳平衡。
4. 错误不中断（批量模式）— 单个文件转码失败时记录错误并继续处理下一个，最终汇总报告。

单文件转码

ffmpeg -y -i "INPUT.ogg" -vn -acodec libmp3lame -q:a 2 "OUTPUT.mp3"

• -y：覆盖已存在输出（单文件模式由 agent 控制，默认加 -y）
• -vn：丢弃视频轨（如有），只保留音频
• -q:a 2：VBR 质量 2（约 190 kbps，接近透明）
• 元数据（TITLE、ARTIST、ALBUM 等）自动保留

质量档位参考

批量转码

使用本技能附带的脚本 scripts/qq_to_mp3.sh：

# 转换整个目录（递归）
bash scripts/qq_to_mp3.sh /path/to/music/

# 转换单个文件
bash scripts/qq_to_mp3.sh /path/to/song.ogg

# 指定质量档位（0-6，默认 2）
bash scripts/qq_to_mp3.sh /path/to/music/ -q 0

# 指定输出目录
bash scripts/qq_to_mp3.sh /path/to/music/ -o /path/to/output/

脚本行为：

• 自动检测 ffmpeg 是否可用
• 递归扫描 .ogg .flac .m4a .aac .wav .opus .wma .aiff .aif 文件
• 同名 .mp3 已存在时跳过
• 单文件失败不中断，最终输出汇总（成功/失败/跳过计数）
• 保留原始目录结构到输出目录

标准流程

1. 确认输入 — 用户提供文件路径或目录路径；确认格式是否为本技能支持的类型。
2. 检测环境 — 运行 ffmpeg -version 确认可用；若不可用，提示安装方式：
   • macOS：brew install ffmpeg
   • Ubuntu/Debian：sudo apt install ffmpeg
   • Windows：从 ffmpeg.org 下载
3. 执行转码：
   • 单文件 → 直接 ffmpeg 命令
   • 多文件/目录 → 使用 scripts/qq_to_mp3.sh 脚本
4. 汇报结果 — 输出每个文件的转码信息（源格式 → MP3、时长、码率、文件大小对比）。
5. 可选：清理 — 询问用户是否删除源文件（默认保留，不自动删除）。

反模式（禁止）

• ❌ 删除或覆盖原始音频文件
• ❌ 使用固定 CBR 320k 处理语音文件（浪费空间）
• ❌ 不检查 ffmpeg 是否可用就执行
• ❌ 批量转码中某个文件失败就全部中止
• ❌ 对已经是 MP3 的文件重复转码（有损 → 有损，音质下降）

核心原则

保留元数据 · 不覆盖原文件 · VBR 优先 · 批量容错。 音频转码是格式迁移，不是音质升级——源文件质量是上限。