#transcode #music #readme #document #guide #mp3 #wav #flac #ffmpeg #cue 
# `transcode_music.py` 使用手册

批量将无损音乐（FLAC / WAV / DSF / DFF / APE）转码为 MP3 320k CBR 的 Python 脚本，支持断点续跑、错误恢复、CUE 整轨检测、DSD 转码。

---

## 目录

- [1. 简介](#1-简介)
- [2. 系统要求](#2-系统要求)
- [3. 快速上手](#3-快速上手)
- [4. 命令行参数详解](#4-命令行参数详解)
- [5. 常用使用场景](#5-常用使用场景)
- [6. Manifest 文件说明](#6-manifest-文件说明)
- [7. 文件分类规则](#7-文件分类规则)
- [8. CUE 整轨检测逻辑](#8-cue-整轨检测逻辑)
- [9. 采样率与 DSD 处理](#9-采样率与-dsd-处理)
- [10. 错误处理与恢复](#10-错误处理与恢复)
- [11. 已知局限](#11-已知局限)
- [12. FAQ](#12-faq)

---

## 1. 简介

**这个工具解决什么问题？**

你有一大堆无损音乐（比如 `/mnt/z/` 网盘上几百 GB 的 FLAC / WAV / DSF），想批量转成体积更小的 MP3 320k 存到手机/车载/移动设备，同时**保持原有的目录结构和文件名**，并且要能**中途暂停、下次继续**。

**核心特性**：

| 特性 | 说明 |
|---|---|
| 保持目录结构 | 目标目录树与源目录一一对应，多碟专辑 (CD1/CD2) 分开处理 |
| 保留所有资源 | 封面图片 (jpg/png/…)、说明 TXT、EAC log、CUE 都会复制过去 |
| 断点续跑 | 转码状态记录在源目录的 `.transcode_manifest.json`，任意时刻中断都能从上次位置继续 |
| CUE 整轨检测 | 分析阶段自动识别 "CUE + 单个大 flac 未分轨" 的专辑，报警并跳过等你手动 split |
| CUE 已分轨识别 | 若 CUE 引用的是整轨但同时存在分轨文件，自动跳过冗余的整轨文件 |
| 高采样率处理 | 24bit / 96kHz / 192kHz 输入自动重采样到 44.1kHz (符合 MP3 规范) |
| DSD 支持 | DSF/DFF (DSD64 / DSD128) 自动解码降采样后编码 MP3 |
| 保留封面 | 内嵌于 FLAC/DSF 的封面会写入 MP3 的 ID3v2 tag |
| 错误隔离 | 单个文件失败不中断整体流程，错误写入 manifest 供后续排查 |
| 幂等 | 已完成的文件/专辑，再次运行时秒跳过 |

---

## 2. 系统要求

| 组件 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 只用标准库，无需 pip install 任何依赖 |
| ffmpeg | 6.0+ | 需支持 `libmp3lame` 编码器，`dsd_lsbf/msbf` 解码器 (DSD 用) |
| ffprobe | 6.0+ | 通常随 ffmpeg 一起安装 |

**检查环境**：

```bash
python3 --version
ffmpeg -version | head -1
ffprobe -version | head -1
# 确认支持 mp3 编码
ffmpeg -codecs 2>/dev/null | grep libmp3lame
# 确认支持 DSD 解码 (如果你有 DSF 文件)
ffmpeg -codecs 2>/dev/null | grep -i dsd
```

**安装 ffmpeg**（如果没有）：

```bash
# Ubuntu/Debian/WSL
sudo apt install ffmpeg

# macOS
brew install ffmpeg
```

---

## 3. 快速上手

**最常用的三个命令**：

```bash
# 1. 先分析看看有没有问题 (不实际转码)
python3 transcode_music.py /mnt/z/我的音乐 /mnt/x/mp3输出 --analyze-only

# 2. 确认没问题后, 正式转码 (中断可再跑, 自动 resume)
python3 transcode_music.py /mnt/z/我的音乐 /mnt/x/mp3输出
python3 transcode_music.py /mnt/d/music/ /mnt/x/music/20260823

# 3. 后来加了新专辑, 再跑一次 (已完成的会自动跳过, 只处理新加的)
python3 transcode_music.py /mnt/z/我的音乐 /mnt/x/mp3输出
```

``` shell
# 4. Macmini上的命令路径(NAS上 /volume2/navidrome已经成功mount)：
python3 transcode_music.py ~/MyMusic ~/mnt/volume2/navidrome/music/20260823

```
[[Mac Mini NAS 挂载配置指南]]

就这么简单。下面是完整的参数说明和更多用法。

---

## 4. 命令行参数详解

### 完整语法

```
transcode_music.py [SOURCE] [TARGET] [选项...]
```

或

```
transcode_music.py --source SOURCE --target TARGET [选项...]
```

### 参数列表

| 参数 | 短选项 | 类型 | 是否必需 | 默认 | 说明 |
|---|---|---|---|---|---|
| `SOURCE` | — | 位置参数 | 必需¹ | — | 源目录，无损音乐所在位置 |
| `TARGET` | — | 位置参数 | 必需¹ | — | 目标目录，MP3 输出位置 |
| `--source` | `-s` | 字符串 | 必需¹ | — | 源目录（与位置参数 SOURCE 等价） |
| `--target` | `-t` | 字符串 | 必需¹ | — | 目标目录（与位置参数 TARGET 等价） |
| `--bitrate` | `-b` | 字符串 | 可选 | `320k` | MP3 CBR 比特率。可选 `320k` / `256k` / `192k` / `128k` 等 |
| `--analyze-only` | — | 开关 | 可选 | 关 | 只分析生成 manifest，不实际转码 |
| `--force` | — | 开关 | 可选 | 关 | 忽略现有 manifest，全部重新分析并转码 |
| `--verbose` | `-v` | 开关 | 可选 | 关 | 显示 debug 级别日志（包括跳过的项） |
| `--ffmpeg` | — | 字符串 | 可选 | `ffmpeg` | ffmpeg 可执行文件路径（默认从 PATH 查找） |
| `--ffprobe` | — | 字符串 | 可选 | `ffprobe` | ffprobe 可执行文件路径 |
| `--timeout` | — | 整数 | 可选 | `3600` | 单文件转码超时秒数（超时算失败） |
| `--sample-rate-when-high` | — | 整数 | 可选 | `44100` | 输入采样率 > 48kHz 时的输出采样率，可选 `44100` / `48000` |
| `--help` | `-h` | 开关 | — | — | 显示帮助并退出 |

¹ **源目录 和 目标目录 必须提供，但可以用位置参数或 flag 两种形式之一**：

```bash
# 位置参数 (更简洁, 推荐)
transcode_music.py /mnt/z/music /mnt/x/mp3

# flag 长形式
transcode_music.py --source /mnt/z/music --target /mnt/x/mp3

# flag 短形式
transcode_music.py -s /mnt/z/music -t /mnt/x/mp3

# 混合也可以
transcode_music.py /mnt/z/music -t /mnt/x/mp3
```

### 参数详细说明

#### `SOURCE` / `--source` / `-s`

**源目录**。脚本会递归扫描此目录下所有子目录，对每个包含无损音频的子目录识别为一个"专辑单元"处理。

- 支持含空格、中文、特殊字符的路径
- 网盘挂载（`/mnt/z/`、`/mnt/x/` 等）都可以
- Manifest 文件 `.transcode_manifest.json` 会写入此目录

#### `TARGET` / `--target` / `-t`

**目标目录**。MP3 输出位置。目录结构会与源目录保持一致。

- 目录会自动创建（含中间层）
- 已存在的目标文件如果 manifest 记录 `completed` 会自动跳过

#### `--bitrate` / `-b`

MP3 输出比特率（CBR，Constant Bit Rate）。默认 `320k`。

**推荐取值**：

| 值 | 说明 |
|---|---|
| `320k` | 最高质量，几乎无损感知，推荐（默认） |
| `256k` | 高质量，体积减小约 20% |
| `192k` | 良好质量，体积减小约 40% |
| `128k` | 一般质量，仅在存储极度紧张时使用 |

**注意**: 一旦确定比特率跑过一次，配置写入 manifest。**中途改比特率**不会导致已完成的文件重新转码（脚本以文件 completed 状态为准）。想改需配合 `--force`。

#### `--analyze-only`

**只分析，不转码**。用途：

- 首次跑一个新的大目录时，先看看总专辑数、CUE 整轨的有没有
- 探测有没有解析错误的文件
- 生成 manifest 后可以手动查看/编辑

**推荐**每次对新目录都先跑一次 `--analyze-only`。

#### `--force`

**强制重跑**。忽略源目录现有的 manifest，重新分析并转码所有文件。

**什么时候用**：
- 换了比特率想全部重新转
- 怀疑之前的输出有问题
- 想清理并重新开始

**警告**：会覆盖已存在的 MP3。之前的 manifest 不会删除但会被覆盖。

#### `--verbose` / `-v`

打开 DEBUG 级别日志。默认 INFO 级别只显示正在处理和错误。加上 `-v` 会额外显示：

- `[SKIP (已完成): ...]` 每个跳过的专辑
- `[SKIP (空目录): ...]` 跳过的空目录
- ffprobe/ffmpeg 的调试信息

大量输出，通常只在排查问题时用。

#### `--ffmpeg` / `--ffprobe`

指定 ffmpeg / ffprobe 的路径。默认从 `PATH` 查找。

**什么时候用**：
- 系统装了多个 ffmpeg 版本，想指定用哪个
- ffmpeg 不在标准 PATH 里
  
示例：

```bash
transcode_music.py /src /dst --ffmpeg /opt/ffmpeg-6.1/bin/ffmpeg
```

#### `--timeout`

单个文件转码的超时时间（秒），默认 3600（1 小时）。超时算失败，写入 manifest 后继续处理下一个。

**通常不需要调整**。除非你有超长的音频文件（比如整轨 3 小时的 wav）在慢网盘上转码，可以调大。

#### `--sample-rate-when-high`

高采样率输入（> 48kHz）降到多少 kHz。默认 `44100`（CD 标准）。

- `44100`：CD 标准，最兼容
- `48000`：视频/DVD 标准

对于 24bit/96kHz、24bit/192kHz、DSD（352.8k / 705.6k）等高采样率源，MP3 编码器不支持 > 48kHz，必须降采样。默认 44.1kHz 是 CD 标准，兼容性最好。

如果你的音乐主要来源是从视频/电影音轨提取的，用 48000 可能更保留原有采样率。

---

## 5. 常用使用场景

### 场景 1: 第一次处理新目录（推荐流程）

假设你刚下载了一大堆音乐到 `/mnt/z/新收藏/`，想转到 `/mnt/x/music/新收藏/`。

**第一步：先分析**

```bash
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏 --analyze-only
```

输出会告诉你：
- 总共多少个专辑
- 多少个音频文件、多少资源
- **有没有需要 CUE split 的专辑（`needs_cue_split`）**

**第二步：处理 needs_cue_split 的专辑**（如果有）

对于报警的整轨专辑，你需要用别的工具（比如 `shntool`、`CUETools`、`XLD`）手动 split 成分轨，然后再回来跑脚本。

**第三步：正式转码**

```bash
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏
```

已经 `analyzed` 的专辑会开始转码，`needs_cue_split` 的会自动跳过（不影响其他）。

### 场景 2: 中断后恢复

假设转到一半按 Ctrl+C 中断了（或者断电、脚本崩溃了）。

只需要**再跑同样的命令**：

```bash
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏
```

脚本会读取 manifest，跳过所有 `completed` 状态的文件和专辑，从上次中断的地方继续。**不需要任何特殊参数**。

### 场景 3: 增量同步（新增了专辑）

以后你又下载了几个新专辑到 `/mnt/z/新收藏/`，直接跑：

```bash
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏
```

已完成的专辑秒跳过，只有新目录会被分析和转码。这是最舒服的用法。

### 场景 4: 修复失败的文件

如果某个专辑因为源文件损坏等原因失败了（`status: failed`），你修复源文件后：

```bash
# 直接再跑一次, failed 的会被自动重试
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏
```

已成功的不会重跑，只有失败的会重试。

### 场景 5: 换比特率重新转码

想把之前的 320k 全部改成 256k：

```bash
# 加 --force 强制重跑
python3 transcode_music.py /mnt/z/新收藏 /mnt/x/music/新收藏 -b 256k --force
```

### 场景 6: 只转一小部分做质量测试

比如你想先转一个专辑试听下音质，别一下转几百 GB。

**方法一**：直接指定那个专辑的父目录

```bash
# 只处理 "李宗盛精选" 这一个专辑
python3 transcode_music.py "/mnt/z/新收藏/李宗盛精选" /mnt/x/music/李宗盛精选
```

**方法二**：跑 `--analyze-only` 看总数，觉得数量能接受再跑正式的。

### 场景 7: 只想复制资源不想转码

不太常见。可以用位置参数让源和目标一致（虽然实际上 target 是别的，但 --analyze-only 后手动处理）：

```bash
# 只分析生成 manifest, 不转码
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --analyze-only
```

然后手动编辑 manifest 把所有音频状态改成 `skipped` 再跑。**不推荐**，通常你就是想转码。

### 场景 8: 排查某个专辑的问题

某个专辑失败了或者行为奇怪，用 verbose 模式跑：

```bash
python3 transcode_music.py "/mnt/z/新收藏/有问题的专辑" /mnt/x/music/test -v
```

输出会更详细，包括 ffprobe 探测细节、跳过原因等。

### 场景 9: 用不同 ffmpeg 版本

```bash
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 \
    --ffmpeg /opt/ffmpeg-7.0/bin/ffmpeg \
    --ffprobe /opt/ffmpeg-7.0/bin/ffprobe
```

---

## 6. Manifest 文件说明

### 位置

Manifest 保存在**源目录**下，文件名 `.transcode_manifest.json`（隐藏文件，前缀有点）。

### 顶层结构

```json
{
  "manifest_version": 1,
  "created_at": "2026-08-16T15:05:03+08:00",
  "updated_at": "2026-08-16T15:19:06+08:00",
  "source_root": "/mnt/z/test",
  "target_root": "/mnt/x/music/test",
  "config": {
    "bitrate": "320k",
    "id3v2_version": "3",
    "output_sample_rate_when_high": 44100
  },
  "stats": {
    "total_albums": 5,
    "by_album_status": {"completed": 5},
    "by_audio_status": {"completed": 50},
    "by_asset_status": {"completed": 7},
    "total_audio_files": 50,
    "total_asset_files": 7
  },
  "albums": {
    "专辑相对路径1": { ... },
    "专辑相对路径2": { ... }
  }
}
```

### 单个专辑 (album) 结构

```json
{
  "status": "completed",
  "issues": [],
  "audio_files": {
    "01 - 北风.flac": {
      "type": "flac",
      "size": 29671831,
      "sample_rate": 44100,
      "channels": 2,
      "duration_sec": 297.36,
      "bits_per_sample": 16,
      "codec": "flac",
      "status": "completed",
      "target_rel": "01 - 北风.mp3",
      "error": null,
      "converted_at": "2026-08-16T15:18:04+08:00"
    }
  },
  "asset_files": {
    "cover.jpg": {
      "type": "image",
      "size": 234567,
      "status": "completed",
      "target_rel": "cover.jpg",
      "error": null,
      "copied_at": "2026-08-16T15:18:05+08:00"
    }
  },
  "ignored_files": ["Thumbs.db"],
  "has_audio": true,
  "started_at": "2026-08-16T15:18:04+08:00",
  "completed_at": "2026-08-16T15:18:06+08:00",
  "error": null
}
```

### 状态值 (status)

**专辑级状态**：

| status | 说明 | 下次运行时行为 |
|---|---|---|
| `pending` | 初始状态（一般用不到） | 会重新分析 |
| `analyzed` | 已分析，等待转码 | 继续转码 |
| `processing` | 正在处理（若看到，说明上次中断了） | 会重新处理未完成部分 |
| `needs_cue_split` | 是 CUE + 整轨大文件，需先手动 split | **跳过**，不处理 |
| `completed` | 所有文件都成功了 | **秒跳过** |
| `failed` | 有文件失败 | 会重试失败的部分 |
| `skipped` | 空目录，无音频且无资源 | 跳过 |

**文件级状态**（audio_files 和 asset_files 里）：

| status | 说明 |
|---|---|
| `pending` | 待处理 |
| `completed` | 已完成 |
| `failed` | 失败（`error` 字段有原因） |
| `skipped` | 主动跳过（如 CUE 引用的整轨已有分轨） |

### 手动干预 manifest

Manifest 是纯 JSON，你可以用文本编辑器直接改：

**例子 1：让某个专辑重新处理**
```json
"status": "completed"  →  "status": "analyzed"
```
把该专辑内的音频文件也改成：
```json
"status": "completed"  →  "status": "pending"
```

**例子 2：跳过某个损坏的文件**
```json
"01 - 有问题.flac": {
  ...
  "status": "skipped",
  "error": "手动跳过，源文件有损坏"
}
```

**例子 3：删除某个专辑的记录，让它从头分析**
删除对应的 album 条目，下次运行会自动重新扫描添加。

**改完保存直接跑**：

```bash
python3 transcode_music.py /mnt/z/music /mnt/x/mp3
```

### Manifest 损坏怎么办？

如果 JSON 损坏（编辑错了、盘故障），脚本启动时会自动检测，将坏 manifest 重命名为 `.transcode_manifest.json.corrupt-<时间戳>`，然后**重新生成新的 manifest**。已完成的 MP3 文件不会丢，但脚本会重新扫描所有文件（对已有 MP3 的处理由目标文件是否存在来判断，见"文件级幂等"）。

**手动恢复方法**：如果损坏的 manifest 里有大量已完成状态，可以试着修复 JSON 语法后重命名回去。

---

## 7. 文件分类规则

脚本会根据扩展名把文件分到几类：

### 无损音频（会转码为 MP3）

`.flac` `.wav` `.dsf` `.dff` `.ape`

### 有损音频（当作资源直接复制，不转码）

`.mp3` `.m4a` `.aac` `.ogg` `.opus` `.wma` `.mp2`

**为什么不再压？** 因为它们已经是有损，再压一次损失更多。

### 图片（复制）

`.jpg` `.jpeg` `.png` `.bmp` `.gif` `.webp` `.tif` `.tiff`

### 文档（复制）

`.txt` `.log` `.pdf` `.md` `.nfo` `.doc` `.docx` `.rtf`

### CUE（复制）

`.cue`

### 忽略的文件（不处理）

- `.ds_store`、`thumbs.db`、`desktop.ini`、`.directory`（系统文件）
- 以 `._` 开头的（macOS resource fork）
- `.transcode_manifest.json` 及其 tmp 中间文件

### 其他扩展名

未列出的扩展名会被当作"other"资源直接复制，不会丢。

---

## 8. CUE 整轨检测逻辑

CUE 文件常见有三种搭配：

### 情况 A：CUE + 单个整轨大文件（需先 split）

```
album.cue        (指向 album.flac, 里面 12 个 TRACK 条目)
album.flac       (整张 CD 打包成一个大文件)
```

**处理**：脚本标记专辑状态为 `needs_cue_split`，跳过转码，在报告里警告：

```
[!] 1 个专辑需先手动 CUE split (已跳过转码):
    • album名
        album.cue: 整轨型 (单文件 'album.flac', 12 轨) — 需先手动 CUE split 再转码
```

**处理方式**：用其他工具（`shntool split`、`CUETools`、`XLD`、`foobar2000`）split 成分轨 flac 后，删除大整轨文件（或保留但用 CUE 引用改指向分轨），然后再跑脚本。

### 情况 B：CUE + 分轨文件（已 split，直接转码）

```
album.cue                    (指向 track01.flac, track02.flac...)
track01.flac
track02.flac
...
```

**处理**：脚本正常转码所有分轨 flac，CUE 文件也作为资源复制过去。

### 情况 C：CUE 引用整轨 + 但同时存在分轨（跳过冗余）

```
CDImage.cue         (指向 CDImage.flac)
CDImage.flac        (整轨大文件, 冗余)
(01) 曲名.flac       (已经手动 split 出来的分轨)
(02) 曲名.flac
...
```

**处理**：脚本自动跳过 `CDImage.flac`（避免重复转码），只转分轨，同时复制 CUE。报告里会说明：

```
CDImage.cue: 引用 'CDImage.flac' 但存在 20 个分轨 → 跳过 'CDImage.flac' 只转分轨
```

### 检测算法（技术细节）

对每个 CUE 文件：
1. 解析出所有 `FILE "xxx" WAVE` 条目（可能有多个）
2. 解析出所有 `TRACK NN AUDIO` 条目
3. 判断：
   - 若 CUE 只引用 1 个文件，且这个文件是目录里唯一的音频 → 情况 A（整轨）
   - 若 CUE 只引用 1 个文件，但目录里还有其他分轨音频 → 情况 C（跳过整轨）
   - 若 CUE 引用多个文件（>= 2）→ 情况 B（分轨）

CUE 文件的编码会尝试多种（`utf-8-sig` / `utf-8` / `gbk` / `big5` / `shift_jis` / `cp936` / `latin1`），中日韩音源基本都能识别。

---

## 9. 采样率与 DSD 处理

### MP3 采样率约束

MP3 规范只允许这些采样率：8 / 11.025 / 12 / 16 / 22.05 / 24 / 32 / 44.1 / 48 kHz。

超过 48kHz 的输入**必须重采样**，脚本自动处理。

### 具体规则

| 输入采样率 | 输出采样率 | 备注 |
|---|---|---|
| 44100 Hz | 44100 Hz | 透传，CD 标准 |
| 48000 Hz | 48000 Hz | 透传 |
| 32000 Hz 及其他 MP3 支持值 | 保持不变 | 透传 |
| 88200 / 96000 Hz | 44100 Hz | 降采样（默认，可通过 `--sample-rate-when-high` 改为 48000） |
| 176400 / 192000 Hz | 44100 Hz | 降采样 |
| 352800 Hz (DSD64 解码后) | 44100 Hz | 精确 8:1 降采样（DSD64 特性）|
| 705600 Hz (DSD128 解码后) | 44100 Hz | 精确 16:1 降采样 |

### DSD (DSF / DFF) 处理

DSD 是 1-bit 高频（2.8 或 5.6 MHz）采样格式，与传统 PCM 不同。脚本流程：

1. **ffprobe** 探测：报告 `codec_name=dsd_lsbf_planar` 或 `dsd_msbf_planar`，`sample_rate=352800` 或 `705600`
2. **ffmpeg 解码**：DSD → 高采样率 PCM（自带低通滤波器，96 tap，通带平坦到 48kHz，阻带抑制 ~160dB）
3. **重采样**：降到 44100 Hz
4. **编码**：libmp3lame 320k CBR

DSD 内嵌的封面（通常是 mjpeg）会被识别为视频流并保留到 MP3 的 ID3v2 tag。

### 位深处理

- 16-bit 输入：直接编码
- 24-bit 输入：libmp3lame 内部用 32-bit float 处理，等效于 24-bit 精度参与编码
- DSD (1-bit)：解码为 24-bit PCM 后编码

---

## 10. 错误处理与恢复

### 错误捕获原则

**单个文件失败不影响其他**。转码或复制某个文件出错时：

1. 该文件状态设为 `failed`，错误消息写入 `error` 字段
2. 该专辑状态设为 `failed`
3. **继续处理**下一个文件、下一个专辑
4. 最后报告里列出所有失败项

### 再次运行时

`failed` 状态的文件会**自动重试**。已经 `completed` 的不会重跑。

```bash
# 修好源文件后, 直接再跑
python3 transcode_music.py /mnt/z/music /mnt/x/mp3
```

### 常见错误

**"Error opening output files: Invalid argument"**

通常是 ffmpeg 无法识别输出格式或权限问题。脚本内部已加 `-f mp3` 强制指定 muxer 避免此问题。若仍出现：
- 检查目标目录是否可写
- 检查文件名是否有极端特殊字符

**"Operation not permitted"（复制时）**

网盘挂载（9p / SMB / NFS）不允许改文件权限。脚本已经改用 `copyfile` + best-effort `utime`，通常应该没问题。若出现：
- 检查目标目录挂载参数
- 尝试 `mount -o rw,noatime ...` 之类的选项

**ffprobe 失败 / 无法探测采样率**

源文件可能损坏。检查 `manifest.audio_files.<文件>.error` 里的具体消息。

**ffmpeg 超时**

默认 3600 秒。若真有超大文件慢网盘的组合，用 `--timeout 7200` 调大。

### 中断（Ctrl+C）

脚本捕获 SIGINT，会保存 manifest 后退出。**中断后当前正在转的那个文件的 `.mp3.tmp` 中间文件会被清理**，不会留下坏的 MP3。

### 用什么方法查看失败列表

```bash
# 用 jq 快速查看失败的专辑
jq -r '.albums | to_entries[] | select(.value.status=="failed") | .key' \
    /mnt/z/music/.transcode_manifest.json

# 查看某个专辑里失败的文件
jq '.albums["专辑名"].audio_files | with_entries(select(.value.status=="failed"))' \
    /mnt/z/music/.transcode_manifest.json
```

### 关于 needs_cue_split

`needs_cue_split` 状态的专辑**不算失败**，是主动跳过等你手动处理。若不需要转这些，可以：

**选项 1：修 manifest 忽略它们**

把状态改成 `skipped`：

```json
"status": "needs_cue_split"  →  "status": "skipped"
```

**选项 2：手动 CUE split**

用其他工具 split 成分轨，然后：

```bash
# 让脚本重新分析
rm /mnt/z/music/.transcode_manifest.json
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --analyze-only
```

---

## 11. 已知局限

- **不支持并行转码**。是单进程顺序处理。CPU 密集型（LAME 编码）加网盘 IO 是主要瓶颈。多进程可以显著加速，但为保证 manifest 状态一致性没有实现。若性能是问题，可以对不同子目录同时跑多个脚本实例。
- **不支持 VBR MP3**。只做 CBR。原因：CBR 兼容性更好，且 320k CBR 与 V0 VBR 音质差异对绝大多数人不可闻。
- **不做 replaygain / ID3v1 补齐 / 章节标记**。只做基本的 ID3v2.3 元数据映射。
- **CUE split 不会自动做**。检测出整轨专辑后只是报警跳过，不代替你调用外部工具去 split。设计如此以避免不可控的副作用。
- **不支持 ALAC (.m4a) 转 MP3**。因为 `.m4a` 容器里既可能是 ALAC 无损也可能是 AAC 有损，无法从扩展名区分。这些文件会被当作有损直接复制。若你有确定是 ALAC 的 `.m4a`，需要先用 ffmpeg 手动转成 flac。
- **网盘 mtime 不能保留**。9p / SMB 挂载不允许改 mtime，所以复制后的资源文件时间戳是当下时间（内容完全一致）。转码后的 MP3 也是同样情况。
- **不做重复检测**。若源目录有两个不同路径下的同名同内容文件，会各自转码两份。

---

## 12. FAQ

**Q: 我可以中途改比特率吗？**

A: 已经 `completed` 的文件不会重转，即使你改了 `-b`。想全部按新比特率重跑就加 `--force`。

**Q: 手机不支持 320k 会怎样？**

A: 所有正常的 MP3 播放器都支持 320k CBR，几十年的老设备也没问题。

**Q: 转码后 MP3 音质怎么样？**

A: LAME 320k CBR 是"透明比特率"级别，即绝大多数听者在双盲测试中无法区分 320k MP3 和原始 FLAC。除非你有非常好的耳机和听音训练，几乎听不出差别。

**Q: DSD 转 MP3 有没有意义？**

A: DSD 主要意义在于极高频响应（超过人耳范围）和低失真。转成 MP3 后这些优势基本没了。但 MP3 320k 仍能保留 DSD 音源的音乐性和大部分动态。若你就是想要个手机能播的版本，DSD → MP3 是合理的。想要"无损感"应该保留 FLAC。

**Q: 支持 Windows 直接跑吗？**

A: 脚本用了 POSIX 的 `os.fsync(dir_fd)` 做原子写，Windows 上会 best-effort（fsync dir 会 fail 但不影响正确性）。理论上可以跑，但没实测。**推荐 Linux / WSL2 / macOS**。

**Q: 网盘断连了怎么办？**

A: 单文件失败会记录到 manifest 并继续。重新连上后再跑一次，失败的会自动重试。

**Q: 生成的 manifest 会不会很大？**

A: 一般不大。50 个专辑（我的测试目录）的 manifest 约 26 KB。上千个专辑估计几 MB。不影响使用。

**Q: 我想只转某几个专辑怎么办？**

A: 最简单的办法是让 SOURCE 指向那个专辑的父目录：

```bash
python3 transcode_music.py "/mnt/z/music/张学友精选" /mnt/x/mp3/张学友精选
```

或者临时把想转的目录复制/软链接到一个专用目录，跑完再删。

**Q: 能不能顺便做元数据整理（比如加艺人、专辑年份）？**

A: 目前不做。脚本只做 `-map_metadata 0` 把源文件的 tag 原样映射过去。想批量整理元数据推荐 `beets`、`Picard`。

**Q: 转码完想验证质量怎么办？**

A: 抽几首用 `ffprobe` 看输出的 `bit_rate` 应该是 320000 左右，`sample_rate` 是 44100 或 48000。

```bash
ffprobe -v error -show_entries "stream=codec_name,sample_rate,bit_rate" \
    -show_entries "format=bit_rate,duration" \
    "/mnt/x/mp3/xxx.mp3"
```

或用播放器听一下确认。

---

## 附录 A：完整命令示例集

```bash
# 分析（不转码）
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --analyze-only

# 正式转码（自动 resume）
python3 transcode_music.py /mnt/z/music /mnt/x/mp3

# 详细日志
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 -v

# 使用 256k 比特率
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 -b 256k

# 强制重跑
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --force

# 使用 48kHz 输出（视频 / DVD 场景）
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --sample-rate-when-high 48000

# 使用长参数
python3 transcode_music.py --source /mnt/z/music --target /mnt/x/mp3

# 使用短参数
python3 transcode_music.py -s /mnt/z/music -t /mnt/x/mp3

# 组合：位置 + 选项
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 -b 256k -v --force

# 单独指定 ffmpeg 路径
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 \
    --ffmpeg /opt/ffmpeg-7/bin/ffmpeg \
    --ffprobe /opt/ffmpeg-7/bin/ffprobe

# 单文件超长的场景，加大超时
python3 transcode_music.py /mnt/z/music /mnt/x/mp3 --timeout 7200
```

## 附录 B：文件结构示例

**源目录**（真实的音乐盘结构示例）：

```
/mnt/z/新收藏/
├── 张学友精选/
│   ├── 01 - 吻别.flac              ← 转成 mp3
│   ├── 02 - 一路上有你.flac         ← 转成 mp3
│   ├── cover.jpg                   ← 复制
│   └── 专辑说明.txt                ← 复制
├── 王菲 - 天空 (24bit-192kHz)/
│   ├── 01. 天空.flac               ← 24/192 → 降采样后转 mp3
│   ├── 02. 誓言.flac
│   └── booklet.jpg
├── 蔡琴 2CD 精选/
│   ├── back.jpg                    ← 顶层封面, 复制
│   ├── cover.jpg
│   ├── 目录.txt
│   ├── CD1/                        ← 独立处理
│   │   ├── 01 恰似你的温柔.wav      ← 转成 mp3
│   │   └── 02 你的眼神.wav
│   └── CD2/
│       └── 01 出塞曲.wav
├── DSD 专辑/
│   └── 谭咏麟-一生中最爱.dsf         ← DSD 解码后转 mp3
└── 整轨专辑 [FLAC+CUE]/            ← ⚠ needs_cue_split
    ├── CDImage.flac                ← 整个 CD 一个大文件
    └── CDImage.cue                 ← CUE 索引
```

**目标目录**（脚本处理后）：

```
/mnt/x/mp3/新收藏/
├── 张学友精选/
│   ├── 01 - 吻别.mp3               ← 320k CBR
│   ├── 02 - 一路上有你.mp3
│   ├── cover.jpg
│   └── 专辑说明.txt
├── 王菲 - 天空 (24bit-192kHz)/
│   ├── 01. 天空.mp3                ← 44.1kHz 320k
│   ├── 02. 誓言.mp3
│   └── booklet.jpg
├── 蔡琴 2CD 精选/
│   ├── back.jpg
│   ├── cover.jpg
│   ├── 目录.txt
│   ├── CD1/
│   │   ├── 01 恰似你的温柔.mp3
│   │   └── 02 你的眼神.mp3
│   └── CD2/
│       └── 01 出塞曲.mp3
├── DSD 专辑/
│   └── 谭咏麟-一生中最爱.mp3        ← 320k
└── 整轨专辑 [FLAC+CUE]/            ← 空（因为 needs_cue_split 被跳过）
```

**Manifest**（在源目录）：

```
/mnt/z/新收藏/.transcode_manifest.json
```