听力材料 TTS（waiyan-listening）
音频来源决策链（先判断，再动手）
对任何听力需求，按顺序判断：
- 课本自带音频的听力文本（课本录音原文）→ 不重新生成。按以下顺序检索素材：
- 百度网盘（本地素材库）：路径/我的资源/外研社七上04官方音频——用 baidu-netdisk 连接器按此目录检索（关键词：单元号+听力/模块名）。注意：此目录里部分是旧版音频，可能与 2024 新版教材内容不完全匹配，使用前需与课文文本核对
- 国家中小学智慧教育平台（官方对版）：basic.smartedu.cn，用 smartedu-downloader 技能下载对应教材的听力音频（MP3）——内容与教材版本严格对齐，网盘音频对不上时优先用这里的
- 找到原音频直接用，音质和朗读者都优于 TTS - 无课本音频的课文/对话（教师自编材料、改编文本）→ 用本技能 TTS，默认读一遍
- 模拟考式听力训练（听后选择/填空/判断）→ 用本技能 TTS，材料读两遍（指令语→第一遍→停顿→"Now listen again."→第二遍）
生成流程
第 1 步：确认材料与模式
- 用户提供文本，或从研读语篇/教案中提取
- 与用户确认：模式（读一遍 / 读两遍）、角色分配（对话体）、语速（默认 -12%，初一学生舒适区；毕业班备考可提到 -10%）
第 2 步：写 listening-manifest.json
{
"title": "七上 Starter · 听力训练",
"mode": "exam", // once=读一遍 | exam=读两遍
"rate": "-12%",
"pause_between": 3, // exam 模式两遍之间停顿秒数
"pause_speaker": 0.4, // 对话角色间停顿秒数
"segments": [
{"speaker": "narrator", "text": "Listen to the passage and choose the best answer.", "kind": "instruction"},
{"speaker": "teacher", "text": "正文第一段…", "kind": "body"},
{"speaker": "student", "text": "对话句…", "kind": "body"}
]
}
kind:instruction（指令语，读一遍）/body（正文，exam 模式重复）/transition（穿插提示语，读一遍）- exam 模式自动在两遍之间插 TTS 过渡句 "Now listen again."，无需手写
第 3 步：运行生成脚本
# python：本机可用的 Python 3（WorkBuddy 托管运行时即可）
python scripts/make_listening.py --manifest listening-manifest.json --out 输出.mp3
- 脚本内部：edge-tts 逐段合成 → ffmpeg 生成静音段 → 拼接成单个 mp3
- 依赖自愈：edge-tts 缺失时自动 pip install；ffmpeg/ffprobe 自动探测（PATH →
~/.workbuddy/binaries/ffmpeg/*/bin/），都没有时按提示安装 ffmpeg
第 4 步：校验与交付
- 用 ffprobe 确认时长合理（正文秒数×2+停顿 ≈ exam 模式总时长）
- 交付 mp3，附听力材料文本稿（题目+答案给教师版）
音色映射（speaker → edge-tts）
| speaker | 音色 | 适用 |
|---|---|---|
| narrator | en-US-GuyNeural | 指令语、旁白 |
| teacher | en-US-GuyNeural | 教师、Mr Pan 类角色 |
| student | en-US-AnaNeural | 童声，初一学生角色 |
| girl / female | en-US-AriaNeural | 年轻女声 |
| boy / male | en-US-ChristopherNeural | 年轻男声 |
| narrator-gb | en-GB-RyanNeural | 英式旁白 |
| female-gb | en-GB-SoniaNeural | 英式女声 |
| male-gb | en-GB-RyanNeural | 英式男声 |
外研版课文多英式语境，正式课文朗读建议 -gb 音色；日常训练用美式即可。
衔接关系
- 上游：
waiyan-lesson-plan（教案技能，含语篇研读）的研读语篇可直接作为听力正文 - 动画视频形式：课文/对话要做成动画时，走 english-learning-animation 工作流（Remotion，ela-test 模板），音频仍由 edge-tts 生成——本技能只出音频，动画是另一条产线
- 下游：听力训练文本稿+答案 → 可交给 k12-smart-teacher 出配套题目
注意事项
- edge-tts 需联网（微软免费接口），离线时会失败——报错清晰，重试即可
- 语速参数必须用等号：
--rate=-12%（argparse 限制）；manifest 里 rate 缺省时脚本用 -12% - 中文指令（如"听下面一段材料"）用 zh-CN 音色时在 manifest 段里加
"voice": "zh-CN-XiaoxiaoNeural"覆盖 - 一段材料一气呵成拼接，不要生成一堆零散 mp3 给课堂连播
