用途与实际影响
这项功能怎样使用
为什么需要它
旁白是视频节奏的基准。只看文件是否存在，会让改过的脚本继续使用旧声音，或让新声音沿用旧时间轴，后面所有画面都可能错位。身份文件把内容和会改变结果的配置一起绑定，变更时先停下来。
举个实际例子
我可以说：“把三段已确认文案生成旁白和词级时间；第二段刚改过，只重做它，别把旧时间位置套回来。”系统只复用仍与当前输入一致的声音和时间轴。
最后我会得到什么
每场得到旁白音频、实际时长和逐词位置；画面能跟着读到的词出现。旧声音或词轴只有仍与当前文案对应时才继续使用。
正常时
旁白、时长和逐词位置属于同一份已确认脚本，场次一一对应。
发现问题时
脚本、声线或声音变了，就说明哪一层旧结果不能再用，保留原文件等待本人决定是否重做。
入口不可用或证据不足时
外部配音不可用就停在配音；若已有可靠的配音时间信息，本地对齐工具缺失不必让它失效。损坏的旧词轴会报错。
从哪里开始
在新视频工程把已确认旁白写为 script_NN.txt，再运行 run.ps1 tts 和 timing；已有音频先核对身份，不匹配时审阅后明确 force。
需要准备什么
- 按场编号并审阅过的旁白
- 旧音频不匹配时是否明确重做
- 需要何种配音效果
从开始到拿到结果
- 1
先检查旁白和旧音频
工具核对每场脚本非空、编号一致，并确认旧音频是否属于当前文案；不匹配就请人决定是否重做。
- 2
生成声音和时长
工具按确认后的脚本生成语音、场间停顿及时间记录；可复用的旧音频保持原样。
- 3
检查逐词位置
优先用可用原生词轴，必要时共享对齐；听到错位再修，估算时间不当成精确发音。
技术实现与依据
这里保留实现、关键条件、精确入口、历史记录和验证结果。
Fish 原生时间与 ChineseASR 按需对齐已实现；本轮未发云请求或加载模型关键规则与设计选择
标准配音会把旁白文本发给 Fish Audio，不能称完全离线。
已有音频不因文件非空自动可信；身份匹配才复用。
重复词用 data-cue-index 指定次数，词轴重建不要求 tts 重配音；模型时间仍要听音确认。
本模块用到的名词
- reference voice（参考声线）
- Fish 配音使用的公开配置标识；它不是 API 密钥，也不证明服务当前可用。
- word timestamp（词级时间）
- 每个识别词的开始和结束秒数，精度服务画面触发，但仍受识别结果影响。
- --force（明确重建）
- 确认脚本、音频或识别需要变化后才重生成，防止普通重跑改掉已验收节奏。
专业定义
优先用配音自带的时间；缺少时本地对齐，不重复配音或再养一套语音模型。
解决什么
防止脚本、旁白与时间轴三者漂移，以及将配置存在误写为真实网络或识别成功。
当前怎样实现
- fish_tts.py 把脚本文本、端点、模型、声线、格式和 0.2 秒尾静音写入 audio_NN.identity.json，并回验 MP3 SHA-256。
- Fish 合成按当前模型、声线、格式和原生时间请求处理；密钥仅在明确 TTS 或相关配置探针时解析，非空本地值优先，空示例不会覆盖环境变量，秘密不进入身份记录。
- durations.py 用 ffprobe 读取每段音频秒数，durations.json.identity.json 绑定顺序音频名称、SHA-256 和输出哈希。
- transcribe.py 在 auto 模式优先保留绑定有效的旧词轴，再读取同音频 Fish 原生时间；确需对齐才调用已登记 ChineseASR 的 Qwen3-ForcedAligner-0.6B。传入已确认文案与音频，每场上限 300 秒，模型和依赖不属于视频工程。
- workflow 在后续读取 durations.json 前再次核对当前音频身份；Fish 需要生成而失败时直接抛错，旧文件不能让 stage_tts 假绿。
执行流程
- 1
按规范编号读取非空脚本。
- 2
普通运行先核对现有音频身份；不匹配则要求审阅并 force。
- 3
成功配音后加入场间停顿并原子记录身份。
- 4
独立读取时长，选择原生时间或必要的共享对齐；不因改词轴重做已接受的音频。
- 5
后续阶段再次确认时长表仍属于当前音频。
边界
- 情绪与停顿标记用于 Fish 配音；共享对齐使用适配后已确认文案，不把这些标记当作实际发音。
- 词轴不默认烧录字幕，也不验证文案真伪；超 300 秒的单场对齐要求按已审阅分镜拆场，不能把时间估计当逐音素真值。
- 本轮只读源码、登记与静态 doctor，没有发送旁白或加载模型。旧配音 v1 身份和有效 Whisper 词轴可继续读取，不伪造新来源。
失败与恢复
- 旧音频没有身份或脚本变了
- 拒绝复用，保留旧文件并提示审阅后运行 tts --force。
- Fish 返回错误或空内容
- 当前阶段硬失败，即使旧 MP3 仍在也不能通过。
- 音频、文案或对齐来源改变
- 拒绝过期词轴；明确 timing --source chinese-asr --force 可只重建时间位置，保持原配音，随后重建受影响场景。
真实入口
E:\Projects\Archives\video-scaffold\pipeline\fish_tts.py外部旁白、尾静音与音频身份
E:\Projects\Archives\video-scaffold\pipeline\durations.py真实时长与音频身份
E:\Projects\Archives\video-scaffold\pipeline\transcribe.py词轴复用、Fish 原生时间与共享 ChineseASR 对齐适配
E:\Projects\Archives\video-scaffold\pipeline\artifact_identity.pySHA-256 与原子伴随记录
如何验证
- 2026-09-03 历史 33 项回归覆盖旧脚本/音频身份；当前 test_speech_linkage.py 扩展原生词轴和共享对齐合同，本轮未重跑源全套。
- 本轮静态 doctor 证明路由和适配入口存在，不证明实际 API、声线或本地语音推理成功。
- 本轮没有生成 audio_NN.mp3 或 srt_NN.json 的真实样例。
与其他模块的关系
本模块给场景提供声音、总时长和可 cue 词；场景创作负责如何使用这些时间，渲染负责逐帧执行。