小ki的听力录音（小学英语单元作业听力 mp3 合成）
Overview
为小学英语教师把单元作业听力材料自动合成为可直接用于考试的 mp3 听力音频。下游是固定的、经过试听确认的声音规范，不每次重新问，直接套用；唯一随单元变化的是听力材料内容和时间线编排（听几遍、停顿几秒、叮的位置）。
已确认的最终声音规范（默认，不要改除非用户要求）：
| 角色 | 嗓音 | 说明 |
|---|---|---|
| 中文女声 | zh-CN-XiaoxiaoNeural（晓晓·温暖） |
开头公告、请看第X题、结尾公告 |
| 中文男声 | zh-CN-YunyangNeural（云阳·专业稳重） |
7 条大题指令、"听第X段对话"提示 |
| 英文男声 | en-GB-RyanNeural（英音） |
听力正文男声朗读 |
| 英文女声 | en-GB-SoniaNeural（英音） |
听力正文女声朗读 |
| 中文语速 | --rate=-15% |
放慢一点点 |
| 英文语速 | --rate=-20% |
放慢（适合小学五年级学生听，比原速从容） |
| "叮"提示音 | 合成钟声（见下） | 每题【叮】一下，峰值约 -6.8dB（与语音持平，不能太小声） |
| 20秒轻音乐 | 用户自备 wav（无版权） | 开头公告后插入，给学生浏览题目；本包不含内置音乐 |
| 成品格式 | 192kbps / 44100Hz / 立体声 mp3 | — |
工作流程
1. 取材料并转文本
用户给的是 .doc（旧版二进制）或 .docx。先转纯文本再读：
- .doc：textutil -convert txt 文件.doc -output /tmp/m.txt（macOS 自带）
- .docx：用 venv 里的 python -c "import docx..." 或 textutil 也行
- 读出的文本确认：共有几个大题、每题听几遍、男女声怎么安排、每遍之间/每题之间停顿几秒、叮的位置。
2. 准备工具链（只需装依赖包，路径脚本自动探测）
python3 -m pip install -q edge-tts imageio-ffmpeg
- 脚本启动会自动定位 ffmpeg（系统 PATH 或 WorkBuddy 内置）和 python，老师无需改任何路径。
- 缺 edge-tts 时脚本会直接报错提示安装，照着装即可。
3. 用模板生成
把本 skill 的 scripts/build_audio.py 复制到单元工作目录，按材料改这几处：
- CONFIG 区：BASE（工作目录，必改）、MUSIC_WAV（20秒轻音乐路径，自备无版权音乐）、OUTPUT_NAME（成品名）。
- CONTENT + TIMELINE 区（脚本里标了 ===== 单元专属：按需替换 =====）：填 OPENING / ENDING / look[] / ins[] / 各题正文；并在 TIMELINE 区按材料排好男女声、叮、停顿。
- 嗓音常量、语速、叮声、拼接逻辑不要动。
然后运行（用任意 python，脚本自动找 ffmpeg）：
cd <工作目录> && python3 build_audio.py 2>&1 | tail -20
4. 验证并交付
- 确认
DONE. segments=... duration=...零报错。 - 抽查：开头是女声晓晓→20秒音乐；叮声峰值约 -6dB（不淹没）；英文放慢20%（听感比原速从容）。
- 用
present_files交付 mp3，并口头给时长与结构速览。
时间线编排范式（按材料提示，常见题型）
题号必读：材料里每题前的 No.X 要读出来，用 num(n) 生成英文 Number 1 … Number 20，紧跟【叮】之后、正文之前（题号音色=该题第一遍正文音色）。
- 听两遍题（句子/问句/描述）：
【叮】→题号→男声英文→X秒→女声英文→5秒(题间)；X 通常 2 秒。注意材料若标"A指女声、B指男声"（如问句题），则第一遍女声、第二遍男声。 - 对话题（分音色，关键）：材料里
--表示一个人、下一行--表示另一个人，必须分男女音色（第一人男声、第二人女声，或按材料人物标注如 Sam男/Mum女/Amy女/Tom男）。用read_dialogue(lines, gap)，lines每项是("M"/"F", 台词)，整段读两遍（遍间 gap 秒）、两人之间 0.4 秒。 - 听三遍短文：
【叮】→男声→8秒→女声→8秒→男声（材料常写"男、女声各一遍，男声读第三遍"）。 - 开头：女声公告单遍 → 20秒轻音乐。结尾：6秒静音 → 女声"听力到此结束，请继续作答读写部分。"
> 材料里写"每两遍之间停2秒、每题之间停5秒"等，严格照做。只要出现对话，就要分音色（不同说话人用不同嗓音），不要用单一音色读完整段对话。
⚠️ 关键坑（务必照做，否则失败或音质差）
- edge_tts 语速必须用等号形式：
--rate=-15%。写成--rate -15%（空格）会被 argparse 当成选项报错expected one argument。脚本里已用cmd += ["--rate=" + rate]。 - 本机 ffmpeg 的
sine默认幅度只有约 0.125（纯音峰值实测 -18dB 而非 0dB），且不支持amplitude=参数。所以"叮"要用volume=4.0 / 2.0增益，目标峰值约 -6.8dB（与语音持平）；别用amplitude=。 - macOS 系统
say没有自然男声中文（未知嗓音名会静默回退成女声婷婷），所以中文必须用 Edge TTS，别用say。 - 联网：Edge TTS 需联网；生成约 70 段语音会较慢（单单元 2–3 分钟），放后台跑，完成再汇报。
- 每次
speech()都会重新生成覆盖同名 clip，所以改内容后直接重跑整脚本即可，无需手删 clips。
References
scripts/build_audio.py— 合成模板（Unit 1 实测约 15 分钟 / 零报错）。复制到单元目录，改 BASE + MUSIC_WAV + CONTENT/TIMELINE。
