---
slug: audio-converter-zh
displayName: 音频转换
name: 音频转换
version: 1.0.0
summary: 音频格式转换与处理技能：用本机 ffmpeg 在 mp3、wav、m4a、aac、flac、ogg、opus、wma 等格式之间互转，支持剪切、拼接、响度归一与响度测量，不设参数时自动使用 ffmpeg 默认值。
description: 音频格式转换与处理技能：调用本机 ffmpeg，在 mp3、wav、m4a、aac、flac、ogg、opus、wma、aiff、mp2 等格式之间互转，并支持剪切、拼接、EBU R128 响度归一（两遍法）、响度测量、元数据写入，以及从视频里抽取音轨。码率、采样率、声道数、质量模式都可以显式指定；**不指定时一律使用 ffmpeg 默认值**，并在回执的「默认」一栏逐条标注用了哪些默认参数，不静默替用户做决定。每次执行都会回显完整 ffmpeg 命令与产物时长、码率、采样率、声道，结果可用 ffprobe 复核；跨 Windows 与 macOS 命令行行为一致。当用户说『把 wav 转成 mp3』『音频转格式』『mp3 转 m4a』『改音频码率/采样率』『剪辑音频、截取一段』『把几段音频拼起来』『响度统一、音量标准化』『测一下这段音频多大声』『从视频里提取音频』『压缩音频体积』时使用。
license: proprietary
tags: [音频转换, 格式转换, ffmpeg, 音频剪辑, 音频拼接, 响度归一, wav转mp3, 提取音轨]
---

# 音频转换

用**本机 ffmpeg** 做音频格式转换与处理，产出真实音频文件，并可被 `ffprobe` 复核。

## 一、何时用 / 何时不用

**用**：格式互转、改码率/采样率/声道、剪切、拼接、响度归一、响度测量、从视频抽音轨、压缩体积。

**不用**：
- 视频剪辑、加字幕、转码画面 → 本技能只处理音频轨（会主动丢弃视频轨）。
- 语音转文字 → 用 OCR/转写类能力，本技能不做识别。
- 生成音乐、变声、去人声 → 需要模型，不属于本技能。

## 二、先确认 ffmpeg 在不在

```bash
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py check
```

> 桌面安装包另附 `run.sh` / `run.cmd` 启动器（自动探测 Python），参数与上面一致。

`check` 会打印 ffmpeg / ffprobe 的路径、版本、以及支持的输出格式表。
找不到时**不要继续**，直接把当前平台的安装方式告诉用户：

| 平台 | 安装 ffmpeg |
|---|---|
| macOS | `brew install ffmpeg` |
| Windows | `winget install Gyan.FFmpeg` 或 `choco install ffmpeg`，也可到 ffmpeg.org 下载后把 `bin` 加进 PATH |
| Linux | `sudo apt install ffmpeg`（Debian/Ubuntu）或 `sudo dnf install ffmpeg` |

## 三、命令清单

> 路径统一用 `${CODEBUDDY_SKILL_DIR}` 表示技能安装目录，不要写死绝对路径。
> 桌面安装包附带 `run.sh` / `run.cmd`（会自动找可用的 Python）；平台侧直接用 `python3` 调用即可。

### 1) 格式转换

```bash
# 全默认参数（码率/采样率/声道都交给 ffmpeg 默认值）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 录音.wav --to mp3

# 指定码率、采样率、声道
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 录音.wav --to mp3 \
  --bitrate 192k --ar 44100 --ac 2

# 质量模式（VBR，与码率互斥）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 录音.wav --to mp3 --quality 2

# 从视频里抽音轨（自动 -vn 丢弃画面）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 会议录像.mp4 --to m4a

# 边转边裁剪，并写入元数据
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 访谈.wav --to mp3 \
  --start 00:02:00 --duration 00:05:00 --metadata artist=某某 --metadata album=访谈集

# 转换同时做响度归一
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py convert 录音.wav --to mp3 --normalize
```

### 2) 剪切

```bash
# 重编码剪切（精确到采样点）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py trim 长录音.mp3 --start 00:00:30 --end 00:01:10

# 流复制剪切（秒级完成、无损，但切点会对齐到最近的关键帧）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py trim 长录音.mp3 --start 00:00:30 --duration 40 --copy
```

### 3) 拼接

```bash
# 默认流复制（要求各文件编码/采样率/声道一致，快且无损）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py merge 上集.mp3 下集.mp3 --out 合集.mp3

# 格式不一致时必须重编码
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py merge a.wav b.mp3 --out 合集.m4a --re-encode --bitrate 192k
```

### 4) 响度归一与测量

```bash
# 两遍法归一（先测量再按测量值精确归一，默认 I=-16 LUFS / TP=-1.5 dBTP / LRA=11）
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py normalize 录音.mp3 --out 归一后.mp3

# 改成播客常用的 -16 LUFS 之外的规格
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py normalize 录音.mp3 --lufs -14 --tp -1.0

# 只测量不修改
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py loudness 录音.mp3
```

### 5) 读取信息

```bash
python3 ${CODEBUDDY_SKILL_DIR}/scripts/audioconv.py probe 录音.mp3
```

## 四、默认参数必须让用户看见

参数策略只有一条：**用户没给的，就不写进命令，交给 ffmpeg 默认值；同时在回执里逐条标注。**

回执示例（这条「默认」栏就是给用户看的）：

```
默认：未指定码率（-b:a）→ 使用 ffmpeg 默认码率
默认：未指定采样率（-ar）→ 沿用源采样率
默认：未指定声道数（-ac）→ 沿用源声道
说明：目标格式 mp3 默认编码器 libmp3lame
```

**不要**因为用户没说码率就追问三轮，也不要自己挑一个码率却不告知。跑完把「用了默认」说清楚即可。

| 参数 | 不指定时的行为 |
|---|---|
| `--bitrate` | ffmpeg 默认码率（按编码器） |
| `--ar` | 沿用源采样率 |
| `--ac` | 沿用源声道数 |
| `--quality` | 不使用 VBR 质量模式 |
| 编码器 | 按目标格式选默认编码器（mp3→libmp3lame，m4a→aac，opus→libopus …） |

## 五、执行流程（带确认门）

1. **确认输入**：文件存在；用 `probe` 看一眼真实格式、时长、采样率、是否带视频轨——**不要只看扩展名**（扩展名常常是错的）。
2. **确认目标**：要什么格式、要不要改码率/采样率/声道、要不要裁剪或归一。
3. **确认覆盖**：目标已存在时会拒绝执行，需用户明确要覆盖（去掉 `--no-overwrite`）。
4. **执行**：一条命令只做一个文件；多文件时逐个执行并汇总。
5. **交付**：回显真实产物路径、文件大小、**产物时长/码率/采样率/声道**，以及完整 ffmpeg 命令（便于复现）。

## 六、产出物规格与校验

- 每次成功执行后自动用 ffprobe 复核产物并写入回执的 `data.result`：`duration` / `bitRate` / `sampleRate` / `channels` / `codec`。
- 交付时必须报出**产物时长**，与源时长对照；不一致要说明原因（裁剪、拼接、容器补帧）。
- 拼接用流复制时：若各文件参数不一致，ffmpeg 可能产出时长异常的文件——此时应改用 `--re-encode`。
- 退出码：`0` 成功、`1` 运行时失败、`2` 参数错误、`3` 缺外部依赖、`4` 输入不可读。

## 七、质量红线（禁止事项）

- **不得谎报成功**：ffmpeg 非零退出或产物不存在时必须报失败，并给出命令与错误关键行。
- **不得悄悄用默认值**：用了默认参数必须在回执里列出来。
- **不得对视频做画面处理**：本技能只取音频；用户要剪视频要明确说"这不属于本技能"。
- **不得编造音频参数**：没有探测到的信息（如损坏文件的时长）就写"未知"，不要猜。
- **不得忽视覆盖**：默认不覆盖；覆盖必须是用户的显式选择。
- **不得在无 ffmpeg 时硬跑**：先 `check`，缺就停下来给安装方式。

## 八、参考文件索引

- `references/formats-and-codecs.md` —— 各格式与编码器特性、码率建议、体积/质量权衡。
- `references/loudness.md` —— EBU R128 口径、平台响度目标（短视频/播客/广播）、两遍法与单遍法的差别。
- `references/troubleshooting.md` —— 常见失败：拼接时长异常、中文路径、覆盖冲突、amr 不支持、视频无音轨。
- `scripts/audioconv.py` —— 命令行入口（convert / trim / merge / normalize / probe / loudness / check）。
- `scripts/audio.py` —— ffmpeg 封装与命令构造（默认参数策略的唯一来源）。