让每段旁白有声音,也知道每个词在什么时候出现
现在
偶尔用
内容按 10 月 22 日 01:25 的提交核对,没有发配音请求
截至 10 月 22 日 · 项目源码和说明文档

回到项目 → 本地视频制作 私有 复制 AI 续作说明

video-scaffold · 功能说明

每段旁白都要有真实的声音、时长和每个词的开始/结束时间。画面不需要靠人手写“第 2.4 秒出现”,而是跟着旁白真正说出的词触发;脚本或音频变了,也不会把旧结果静默套进新视频。默认的图文页路线直接用本期已经定稿的配音、原文和词级时间,不必每次开工都重新配音;需要新配音时,分镜路线仍可请云端生成。现在云端配音有 Fish Audio 和 ElevenLabs 两家,一条命令切换,型号和音色各记各的;字幕永远照我的原稿显示,数字就是数字、英文就是英文。也可以直接放一段真实录音(比如通话录音),给出逐字稿,程序对出每个字的时刻。

当前情况:已有“用现成定稿配音”“真实录音按逐字稿对齐”“云端配音自带时间(Fish 或 ElevenLabs)”“本地按需对齐”几条路线。10 月 21 日用 ElevenLabs 免费账户的 Roger 音色真跑通过一次 10.04 秒的“配音 → 对时间 → 字幕”,只证明接口通了,音色还没定、听感没人审过;录音对齐只在自动测试里跑过。这次网页核对没有发配音请求,也没有运行对齐模型。

项目源码:私有仓库

让每段旁白有声音,也知道每个词在什么时候出现
现在
偶尔用
内容按 10 月 22 日 01:25 的提交核对,没有发配音请求
截至 10 月 22 日 · 项目源码和说明文档

回到项目 → 本地视频制作 私有 复制 AI 续作说明

video-scaffold · 功能说明

每段旁白都要有真实的声音、时长和每个词的开始/结束时间。画面不需要靠人手写“第 2.4 秒出现”,而是跟着旁白真正说出的词触发;脚本或音频变了,也不会把旧结果静默套进新视频。默认的图文页路线直接用本期已经定稿的配音、原文和词级时间,不必每次开工都重新配音;需要新配音时,分镜路线仍可请云端生成。现在云端配音有 Fish Audio 和 ElevenLabs 两家,一条命令切换,型号和音色各记各的;字幕永远照我的原稿显示,数字就是数字、英文就是英文。也可以直接放一段真实录音(比如通话录音),给出逐字稿,程序对出每个字的时刻。

当前情况:已有“用现成定稿配音”“真实录音按逐字稿对齐”“云端配音自带时间(Fish 或 ElevenLabs)”“本地按需对齐”几条路线。10 月 21 日用 ElevenLabs 免费账户的 Roger 音色真跑通过一次 10.04 秒的“配音 → 对时间 → 字幕”,只证明接口通了,音色还没定、听感没人审过;录音对齐只在自动测试里跑过。这次网页核对没有发配音请求,也没有运行对齐模型。

项目源码:私有仓库

这项功能怎样使用

用途与实际影响

为什么需要它

旁白是视频节奏的基准。只看文件在不在,会让改过的脚本继续用旧声音,或让新声音沿用旧时间轴,后面所有画面都可能错位。身份文件把内容和会改变结果的设置绑在一起,一变就先停下。换配音服务也一样:供应商、型号、音色、送去的表演稿或声音参数任何一项变了,旧配音都不能悄悄沿用。云端配音还会把“16GB”念成奇怪的中文,所以字幕看的原稿和送去配音的稿子要分开管。合成器还会把多音字读错,一读错就要重配一段:docfilm 在合成前先只读查一遍多音字,已知读错自动换说法,拿不准的列出来交 AI 改写。

举个实际例子

我可以说:“这一期的配音已经定稿了,直接用它和原文、词级时间做图文页;第二段原文里写的是数字,念的是中文读法,字幕照原文显示。”系统只播放和对齐本机已有的声音,不重新配音。

也可以说:“把这段通话录音 15.5 秒到 34.6 秒放进来,逐字稿在录音1.txt,每行标了‘对方’和‘我’;两段之间停一秒。”系统只裁出这一段、按逐字稿对齐,整句出字幕并标出说话人,停顿后面的声音和画面一起往后挪。

要新配音时:“这期换 ElevenLabs 配,这台 16GB、那台 32GB 那句加点好奇的语气。”AI 切到 ElevenLabs,原稿保持“16GB”,表演稿里加 [curious] 之类的标记,GB 送去时改成按字母读的音标。

做 docfilm 时:“合成前先查多音字,‘中牟’读 mù。”AI 先跑只读检查,把这个读法记进项目的多音字表,合成用的念法里换成同音字,字幕仍显示原文“中牟”。

最后我会得到什么

每段得到声音、实际时长和逐词位置,画面能跟着读到的词出现;原文写法和念法不同的地方,也能对到念出来的时间。旧声音或词轴只有仍和当前文案对应时才继续用。录音段得到对齐好的词轴缓存,录音本身原样,只是裁了一段。docfilm 得到一份全片配音 voice.wav 和全片时间线 timeline.json,镜头单里的锚点、字幕断句和段末字幕都按它对;另有一份多音字检查清单。

这项功能怎样使用

用途与实际影响

为什么需要它

旁白是视频节奏的基准。只看文件在不在,会让改过的脚本继续用旧声音,或让新声音沿用旧时间轴,后面所有画面都可能错位。身份文件把内容和会改变结果的设置绑在一起,一变就先停下。换配音服务也一样:供应商、型号、音色、送去的表演稿或声音参数任何一项变了,旧配音都不能悄悄沿用。云端配音还会把“16GB”念成奇怪的中文,所以字幕看的原稿和送去配音的稿子要分开管。合成器还会把多音字读错,一读错就要重配一段:docfilm 在合成前先只读查一遍多音字,已知读错自动换说法,拿不准的列出来交 AI 改写。

举个实际例子

我可以说:“这一期的配音已经定稿了,直接用它和原文、词级时间做图文页;第二段原文里写的是数字,念的是中文读法,字幕照原文显示。”系统只播放和对齐本机已有的声音,不重新配音。

也可以说:“把这段通话录音 15.5 秒到 34.6 秒放进来,逐字稿在录音1.txt,每行标了‘对方’和‘我’;两段之间停一秒。”系统只裁出这一段、按逐字稿对齐,整句出字幕并标出说话人,停顿后面的声音和画面一起往后挪。

要新配音时:“这期换 ElevenLabs 配,这台 16GB、那台 32GB 那句加点好奇的语气。”AI 切到 ElevenLabs,原稿保持“16GB”,表演稿里加 [curious] 之类的标记,GB 送去时改成按字母读的音标。

做 docfilm 时:“合成前先查多音字,‘中牟’读 mù。”AI 先跑只读检查,把这个读法记进项目的多音字表,合成用的念法里换成同音字,字幕仍显示原文“中牟”。

最后我会得到什么

每段得到声音、实际时长和逐词位置,画面能跟着读到的词出现;原文写法和念法不同的地方,也能对到念出来的时间。旧声音或词轴只有仍和当前文案对应时才继续用。录音段得到对齐好的词轴缓存,录音本身原样,只是裁了一段。docfilm 得到一份全片配音 voice.wav 和全片时间线 timeline.json,镜头单里的锚点、字幕断句和段末字幕都按它对;另有一份多音字检查清单。

结果怎么看
正常时

声音、时长和逐词位置属于同一份已确认的原文,段落一一对应。云端配音的字幕仍显示原稿里的数字、英文和空格;录音段的字幕整句出现,前面带“对方”或“我”。

发现问题时

脚本、表演稿、供应商、型号、音色或声音参数变了,就说明哪一层旧结果不能再用,保留原文件等本人决定是否重做;原文和念法对上的比例太低时直接报错。录音的逐字稿对不上、缓存失效时,先提示重新对齐,不去估计词的时刻,也不改配音。

入口不可用或证据不足时

云端配音不可用就停在配音这一步,上一份有效音频保留;网页上能试听的音色不等于账户能用接口调它(免费账户调 Jason 音色就被拒过)。已有可靠的配音时间时,本地对齐工具缺失不会让它失效;但录音段需要对齐时,对齐工具不在就直接报错。损坏的旧词轴会报错。

结果怎么看
正常时

声音、时长和逐词位置属于同一份已确认的原文,段落一一对应。云端配音的字幕仍显示原稿里的数字、英文和空格;录音段的字幕整句出现,前面带“对方”或“我”。

发现问题时

脚本、表演稿、供应商、型号、音色或声音参数变了,就说明哪一层旧结果不能再用,保留原文件等本人决定是否重做;原文和念法对上的比例太低时直接报错。录音的逐字稿对不上、缓存失效时,先提示重新对齐,不去估计词的时刻,也不改配音。

入口不可用或证据不足时

云端配音不可用就停在配音这一步,上一份有效音频保留;网页上能试听的音色不等于账户能用接口调它(免费账户调 Jason 音色就被拒过)。已有可靠的配音时间时,本地对齐工具缺失不会让它失效;但录音段需要对齐时,对齐工具不在就直接报错。损坏的旧词轴会报错。

从哪里开始

默认的图文页路线:在分镜表的 narration 里填已有音频,原文和时间文件随音频一起登记,可用 take 只取原文中的一段。需要新配音的分镜路线:把已确认旁白写成 script_NN.txt,再运行 run.ps1 tts 和 timing;已有音频先核对身份,不匹配时审阅后明确 force。现在每期配音怎么做也先判断,不按片子类型定默认。docfilm:先 python -X utf8 docfilm/narrate.py --check-polyphones <配音配置.json>(只读),处理待看项后再 narrate.py <配音配置.json> 合成全片。配音前先用 python -m pipeline.tts show 看当前选的供应商、型号和音色,要换就 configure --provider fish|elevenlabs;想加演绎再写一份 script_NN.tts.txt 表演稿。放真实录音:narration 里写录音文件、from/to 秒数和逐字稿,要说话人就加 speakers;两段之间插 {"pause": 1.0};先跑一次 align 对齐。

需要准备什么
  • 本期定稿的音频、原文和词级时间,或按段编号并审阅过的旁白
  • 用录音时:录音文件、要用的起止秒数、对应这一段的逐字稿(要标说话人就每行写“对方:”或“我:”)
  • 旧音频不匹配时是否明确重做
  • 用 docfilm 时:本期配音配置,每段 text 是字幕原文,可选 say 是合成用的念法
  • 需要新配音时想要的配音效果,以及用哪家、哪个音色(ElevenLabs 的音色必须自己选,账户要真有接口使用权)
从开始到拿到结果
1先检查旁白和旧音频
图文页路线核对音频、原文和时间文件是否成套;分镜路线核对每段脚本非空、编号一致,旧音频不属于当前文案就请人决定是否重做。docfilm 先只读查多音字,退出码 2 表示有待看项,处理完再合成。旧音频不属于当前配音设置(供应商、型号、音色、表演稿、选项)也一样;录音段核对起止秒数和逐字稿。
2拿到声音和时长
图文页直接用已有音频,不调用配音;录音只裁切、统一采样率和声道,不变速、不降噪、不改音色;分镜路线按确认后的表演稿(没有就用原稿)调当前供应商生成语音、段间停顿和时间记录,可复用的旧音频保持原样。
3检查逐词位置
优先用 Fish 或 ElevenLabs 返回的原生词轴,映射回原稿;映射不可靠或是录音时,才用共享对齐。听到错位再修,估算时间不当成精确发音。
从哪里开始

默认的图文页路线:在分镜表的 narration 里填已有音频,原文和时间文件随音频一起登记,可用 take 只取原文中的一段。需要新配音的分镜路线:把已确认旁白写成 script_NN.txt,再运行 run.ps1 tts 和 timing;已有音频先核对身份,不匹配时审阅后明确 force。现在每期配音怎么做也先判断,不按片子类型定默认。docfilm:先 python -X utf8 docfilm/narrate.py --check-polyphones <配音配置.json>(只读),处理待看项后再 narrate.py <配音配置.json> 合成全片。配音前先用 python -m pipeline.tts show 看当前选的供应商、型号和音色,要换就 configure --provider fish|elevenlabs;想加演绎再写一份 script_NN.tts.txt 表演稿。放真实录音:narration 里写录音文件、from/to 秒数和逐字稿,要说话人就加 speakers;两段之间插 {"pause": 1.0};先跑一次 align 对齐。

需要准备什么
  • 本期定稿的音频、原文和词级时间,或按段编号并审阅过的旁白
  • 用录音时:录音文件、要用的起止秒数、对应这一段的逐字稿(要标说话人就每行写“对方:”或“我:”)
  • 旧音频不匹配时是否明确重做
  • 用 docfilm 时:本期配音配置,每段 text 是字幕原文,可选 say 是合成用的念法
  • 需要新配音时想要的配音效果,以及用哪家、哪个音色(ElevenLabs 的音色必须自己选,账户要真有接口使用权)
从开始到拿到结果
1先检查旁白和旧音频
图文页路线核对音频、原文和时间文件是否成套;分镜路线核对每段脚本非空、编号一致,旧音频不属于当前文案就请人决定是否重做。docfilm 先只读查多音字,退出码 2 表示有待看项,处理完再合成。旧音频不属于当前配音设置(供应商、型号、音色、表演稿、选项)也一样;录音段核对起止秒数和逐字稿。
2拿到声音和时长
图文页直接用已有音频,不调用配音;录音只裁切、统一采样率和声道,不变速、不降噪、不改音色;分镜路线按确认后的表演稿(没有就用原稿)调当前供应商生成语音、段间停顿和时间记录,可复用的旧音频保持原样。
3检查逐词位置
优先用 Fish 或 ElevenLabs 返回的原生词轴,映射回原稿;映射不可靠或是录音时,才用共享对齐。听到错位再修,估算时间不当成精确发音。
技术实现与依据(一)

这里保留实现、关键条件、精确入口、历史记录和验证结果。

现成配音接入、Fish / ElevenLabs 双供应商与原生时间、录音裁段对齐和 ChineseASR 按需对齐都在源码中;本次未发云端请求、未加载模型(内容按北京时间 2026-10-22 01:25 最后一次提交 626774f 核对,10 月 22 日 06:47 读;10 月 21 日的 ElevenLabs 接口试跑沿用源文档 docs/VOICE.md 的记录,未重跑);docfilm 的旁白、多音字和全片时间线按 北京时间 10 月 30 日 01:43 最后一次提交 2dbab62 的说明补读,这次没有合成或检查

关键规则与设计选择
1
分镜路线的标准配音会把旁白文本发给 Fish Audio,不能称完全离线;图文页用现成配音和网页作品用本机音频预览时不调用云服务。10 月 21 日起选 ElevenLabs 时发给 ElevenLabs,有表演稿时发的是表演稿;图文页用真实录音也不调云服务,录音对齐用本机的 ChineseASR。
2
已有音频不因文件非空自动可信,身份匹配才复用;供应商、型号、音色、发送稿或声音选项变化都会使旧音频来源失效,普通 tts 拒绝复用,显式 tts --force 才重做,失败时保留上一份有效音频。图文页的 plan、stills、render 不调用配音,也不生成或改写正式词轴;plan 对录音也只读,缓存缺失或失效时提示先 align。
3
原稿(script_NN.txt)是字幕和画面的依据,数字、英文和空格按定稿保留;表演稿(script_NN.tts.txt)存在时只把它送给配音,可加当前型号支持的语气和停顿标记。独立的“GB”默认只在发送稿里改写:ElevenLabs eleven_v4 改成音标 /dʒiː biː/,其他型号和 Fish 改成“G B”,RGB、GBps 等不受影响;pronunciations 可按精确词覆盖,default_gb_pronunciation: false 可关闭。这只是发音引导,效果要听音确认。
4
重复词用 data-cue-index 指定第几次,重建词轴不要求重新配音;模型给的时间仍要听音确认。已知文案对齐只给时间位置,不能验证真实读音或录音内容是否真实。多音字检查同理:拼音词典只给候选,不能证明合成器实际读对,成片仍须试听。
当前怎样实现
  • pipeline.tts show/configure 读写本期 voice.json(已被 Git 忽略,不放密钥):provider 选 fish 或 elevenlabs,providers 下两家各存 model、voice、options;ElevenLabs 默认 eleven_v4、音色留空,必须填当前账户可用的音色 ID。10 月 22 日读这台电脑上的设置:当前选 elevenlabs / eleven_v4,Fish 那边保存的是 s2.1-pro-free。configure 成功只说明本地格式有效,不证明账户有权使用该型号或音色。
  • ElevenLabs 走官方带时间戳的接口(eleven_tts.py),按字符时间组装原生词轴;transport 为 direct(默认,读 ELEVENLABS_API_KEY)或 password-center(经已登记的密码中心调用入口,由 VIDEO_PASSWORD_CENTER_VENDOR 或机器适配 .video-machine.json 指定);付费结果不确定时不自动重试。Fish 读 FISH_API_KEY。各家 options 只接受自己的参数,不互相照搬。
  • 图文页的 load_timeline 读取 narration 登记的音频、原文和时间文件,可用 take 选原文中的一段,拼成当前影片的时间轴;录音项(transcript、from/to、speakers、volume)和 pause 项也在这里排进同一条时间轴。
  • transcribe.recording_words 对录音段做已知文案对齐:缓存位于该表 work/timing,绑定原录音字节、裁切区间、去掉说话人前缀后的文案、输出词轴和实际对齐来源;改前缀、颜色或标签不需重新对齐。录音项不混用 take、pad_end、words 或 text_file。
  • align_text 把原文显示和实际念法对上:数字等替换区间对应到说词时间。它不是“逐字完全一致才通过”——忽略空格和标点后,精确匹配比例低于 60% 才报错,没对上的字可能借用相邻词的时间,所以它不能当漏读、错读的绝对证明。
  • fish_tts.py 把脚本文本、端点、模型、声线、格式和 0.2 秒尾静音写入 audio_NN.identity.json,并回验 MP3 的 SHA-256。当前源码值:模型 s2.1-pro-free,端点 api.fish.audio/v1/tts,输出 MP3,原生时间默认开启;这些是源码设置,不代表账户此刻可用。
  • 密钥只在明确配音或 doctor-live 这类实测时解析,非空本地值优先,空示例不会覆盖环境变量,秘密不进身份记录。
  • durations.py 用 ffprobe 读取每段音频秒数,durations.json.identity.json 绑定顺序音频名称、SHA-256 和输出哈希。
  • docfilm narrate.py:用 ElevenLabs 合成全片旁白,输出 voice.wav 和全片 timeline.json;text 是字幕原文,say 是可选合成念法,字幕和逐字时间都映射回 text。--check-polyphones 只检查(不取密钥、不调接口、不建输出目录),--check 另校验配置、估时长;正常合成也先打印清单,但待看项不会自动拦住合成。
  • 多音字检查用 jieba 固定词典分词后查 pypinyin,先套项目的 polyphones.json:有可靠同音字的自动替换并生成整段 say,没有的进待看清单交 AI 改说法;自动 say 只写进配置副本和新生成的 timeline,不回写当期配置,已经手工改好的 say 和未命中替换的段不会因此重配。
技术实现与依据(一)

这里保留实现、关键条件、精确入口、历史记录和验证结果。

现成配音接入、Fish / ElevenLabs 双供应商与原生时间、录音裁段对齐和 ChineseASR 按需对齐都在源码中;本次未发云端请求、未加载模型(内容按北京时间 2026-10-22 01:25 最后一次提交 626774f 核对,10 月 22 日 06:47 读;10 月 21 日的 ElevenLabs 接口试跑沿用源文档 docs/VOICE.md 的记录,未重跑);docfilm 的旁白、多音字和全片时间线按 北京时间 10 月 30 日 01:43 最后一次提交 2dbab62 的说明补读,这次没有合成或检查

关键规则与设计选择
1
分镜路线的标准配音会把旁白文本发给 Fish Audio,不能称完全离线;图文页用现成配音和网页作品用本机音频预览时不调用云服务。10 月 21 日起选 ElevenLabs 时发给 ElevenLabs,有表演稿时发的是表演稿;图文页用真实录音也不调云服务,录音对齐用本机的 ChineseASR。
2
已有音频不因文件非空自动可信,身份匹配才复用;供应商、型号、音色、发送稿或声音选项变化都会使旧音频来源失效,普通 tts 拒绝复用,显式 tts --force 才重做,失败时保留上一份有效音频。图文页的 plan、stills、render 不调用配音,也不生成或改写正式词轴;plan 对录音也只读,缓存缺失或失效时提示先 align。
3
原稿(script_NN.txt)是字幕和画面的依据,数字、英文和空格按定稿保留;表演稿(script_NN.tts.txt)存在时只把它送给配音,可加当前型号支持的语气和停顿标记。独立的“GB”默认只在发送稿里改写:ElevenLabs eleven_v4 改成音标 /dʒiː biː/,其他型号和 Fish 改成“G B”,RGB、GBps 等不受影响;pronunciations 可按精确词覆盖,default_gb_pronunciation: false 可关闭。这只是发音引导,效果要听音确认。
4
重复词用 data-cue-index 指定第几次,重建词轴不要求重新配音;模型给的时间仍要听音确认。已知文案对齐只给时间位置,不能验证真实读音或录音内容是否真实。多音字检查同理:拼音词典只给候选,不能证明合成器实际读对,成片仍须试听。
当前怎样实现
  • pipeline.tts show/configure 读写本期 voice.json(已被 Git 忽略,不放密钥):provider 选 fish 或 elevenlabs,providers 下两家各存 model、voice、options;ElevenLabs 默认 eleven_v4、音色留空,必须填当前账户可用的音色 ID。10 月 22 日读这台电脑上的设置:当前选 elevenlabs / eleven_v4,Fish 那边保存的是 s2.1-pro-free。configure 成功只说明本地格式有效,不证明账户有权使用该型号或音色。
  • ElevenLabs 走官方带时间戳的接口(eleven_tts.py),按字符时间组装原生词轴;transport 为 direct(默认,读 ELEVENLABS_API_KEY)或 password-center(经已登记的密码中心调用入口,由 VIDEO_PASSWORD_CENTER_VENDOR 或机器适配 .video-machine.json 指定);付费结果不确定时不自动重试。Fish 读 FISH_API_KEY。各家 options 只接受自己的参数,不互相照搬。
  • 图文页的 load_timeline 读取 narration 登记的音频、原文和时间文件,可用 take 选原文中的一段,拼成当前影片的时间轴;录音项(transcript、from/to、speakers、volume)和 pause 项也在这里排进同一条时间轴。
  • transcribe.recording_words 对录音段做已知文案对齐:缓存位于该表 work/timing,绑定原录音字节、裁切区间、去掉说话人前缀后的文案、输出词轴和实际对齐来源;改前缀、颜色或标签不需重新对齐。录音项不混用 take、pad_end、words 或 text_file。
  • align_text 把原文显示和实际念法对上:数字等替换区间对应到说词时间。它不是“逐字完全一致才通过”——忽略空格和标点后,精确匹配比例低于 60% 才报错,没对上的字可能借用相邻词的时间,所以它不能当漏读、错读的绝对证明。
  • fish_tts.py 把脚本文本、端点、模型、声线、格式和 0.2 秒尾静音写入 audio_NN.identity.json,并回验 MP3 的 SHA-256。当前源码值:模型 s2.1-pro-free,端点 api.fish.audio/v1/tts,输出 MP3,原生时间默认开启;这些是源码设置,不代表账户此刻可用。
  • 密钥只在明确配音或 doctor-live 这类实测时解析,非空本地值优先,空示例不会覆盖环境变量,秘密不进身份记录。
  • durations.py 用 ffprobe 读取每段音频秒数,durations.json.identity.json 绑定顺序音频名称、SHA-256 和输出哈希。
  • docfilm narrate.py:用 ElevenLabs 合成全片旁白,输出 voice.wav 和全片 timeline.json;text 是字幕原文,say 是可选合成念法,字幕和逐字时间都映射回 text。--check-polyphones 只检查(不取密钥、不调接口、不建输出目录),--check 另校验配置、估时长;正常合成也先打印清单,但待看项不会自动拦住合成。
  • 多音字检查用 jieba 固定词典分词后查 pypinyin,先套项目的 polyphones.json:有可靠同音字的自动替换并生成整段 say,没有的进待看清单交 AI 改说法;自动 say 只写进配置副本和新生成的 timeline,不回写当期配置,已经手工改好的 say 和未命中替换的段不会因此重配。
技术实现与依据(二)
1
图文页读取已登记的音频与原文,录音项按起止秒数裁段;分镜路线按规范编号读取非空脚本(有表演稿则配音用表演稿)。
2
普通运行先核对现有音频身份(含供应商、型号、音色、发送稿和选项);不匹配则要求审阅并 force。
3
分镜路线配音成功后加入段间停顿并一次性记录身份。
4
独立读取时长,选择原生时间或必要的共享对齐;录音段先 align 成缓存;不因改词轴重做已接受的音频。
5
后续阶段再次确认时长表仍属于当前音频。
  • transcribe.py 在 auto 模式先保留绑定有效的旧词轴,再读同一音频的 Fish 原生时间;确需对齐才调用已登记 ChineseASR 的 Qwen3-ForcedAligner-0.6B,传入已确认文案与音频,每段上限 300 秒,模型和依赖不属于视频工程。10 月 21 日起也读 ElevenLabs 的原生时间,两家原生词轴都映射回原稿(保留数字、英文与空格),映射不可靠时才走共享对齐;切换时间来源不重做配音。
  • docfilm 全片一条时间线:镜头单锚点 "s12:某几个字" 按它找时刻;插删念白段时用 shotlist renumber 批量移段号。字幕默认按标点断句,个别段可指定断点,段末字幕在下一条字幕开始、下一个插入段开始减叠化、该段结束后 0.25 秒三者中取最早收掉。改了配音依次:改配置 → 多音字检查及合成 → 镜头单 check → plan → 只渲过期段 → 合并。
  • 段间 pause 按秒生成静音(须为有限正数,不放头尾、不连续插),画面与当时字幕保持,后面的音频、词轴和绑词一起顺延。
  • workflow 在后续读取 durations.json 前再次核对当前音频身份;需要生成却失败时直接报错,旧文件不能让配音阶段假装通过。
执行流程
技术实现与依据(二)
1
图文页读取已登记的音频与原文,录音项按起止秒数裁段;分镜路线按规范编号读取非空脚本(有表演稿则配音用表演稿)。
2
普通运行先核对现有音频身份(含供应商、型号、音色、发送稿和选项);不匹配则要求审阅并 force。
3
分镜路线配音成功后加入段间停顿并一次性记录身份。
4
独立读取时长,选择原生时间或必要的共享对齐;录音段先 align 成缓存;不因改词轴重做已接受的音频。
5
后续阶段再次确认时长表仍属于当前音频。
  • transcribe.py 在 auto 模式先保留绑定有效的旧词轴,再读同一音频的 Fish 原生时间;确需对齐才调用已登记 ChineseASR 的 Qwen3-ForcedAligner-0.6B,传入已确认文案与音频,每段上限 300 秒,模型和依赖不属于视频工程。10 月 21 日起也读 ElevenLabs 的原生时间,两家原生词轴都映射回原稿(保留数字、英文与空格),映射不可靠时才走共享对齐;切换时间来源不重做配音。
  • docfilm 全片一条时间线:镜头单锚点 "s12:某几个字" 按它找时刻;插删念白段时用 shotlist renumber 批量移段号。字幕默认按标点断句,个别段可指定断点,段末字幕在下一条字幕开始、下一个插入段开始减叠化、该段结束后 0.25 秒三者中取最早收掉。改了配音依次:改配置 → 多音字检查及合成 → 镜头单 check → plan → 只渲过期段 → 合并。
  • 段间 pause 按秒生成静音(须为有限正数,不放头尾、不连续插),画面与当时字幕保持,后面的音频、词轴和绑词一起顺延。
  • workflow 在后续读取 durations.json 前再次核对当前音频身份;需要生成却失败时直接报错,旧文件不能让配音阶段假装通过。
执行流程
名词和入口
本模块用到的名词
名词意思
reference voice(参考声线)Fish 配音使用的公开配置标识;它不是 API 密钥,也不证明服务当前可用。
word timestamp(词级时间)每个识别词的开始和结束秒数,精度服务画面触发,但仍受识别结果影响。
--force(明确重建)确认脚本、音频或识别需要变化后才重新生成,防止普通重跑改掉已验收的节奏。
专业定义

已有定稿配音就直接用;需要新配音时优先用配音自带的时间,缺少时本地对齐,不重复配音,也不另养一套语音模型。

解决什么

防止脚本、旁白与时间轴三者漂移,以及把配置存在误写成真实网络或识别成功。

名词和入口
本模块用到的名词
名词意思
reference voice(参考声线)
意思:
Fish 配音使用的公开配置标识;它不是 API 密钥,也不证明服务当前可用。
word timestamp(词级时间)
意思:
每个识别词的开始和结束秒数,精度服务画面触发,但仍受识别结果影响。
--force(明确重建)
意思:
确认脚本、音频或识别需要变化后才重新生成,防止普通重跑改掉已验收的节奏。
专业定义

已有定稿配音就直接用;需要新配音时优先用配音自带的时间,缺少时本地对齐,不重复配音,也不另养一套语音模型。

解决什么

防止脚本、旁白与时间轴三者漂移,以及把配置存在误写成真实网络或识别成功。

出问题时
边界
  • 情绪与停顿标记按所选供应商和型号写:Fish S2 用 [excited]、[pause] 这类,ElevenLabs v4 用 [curious]、[Brief pause] 这类音频标记(不用 SSML break)。标记只写在表演稿里,字幕和共享对齐用原稿,不把标记当实际发音;不保证每个标签每次都被遵从,也不保证未知标签不被念出。录音段之间也能用 pause 加停顿。10 月 21 日之前的版本里,这类标记只用于 Fish 配音。docfilm 的多音字检查不报“一 / 不”变调、轻声和独立的“的”;本人报一个读错,就在项目多音字表加一行,新增后用检查命令确认命中和相邻反例。
  • 录音只裁切和统一采样率、声道,不变速、不降噪、不改音色,也不加配音默认的淡入淡出;逐字稿必须对应所选区间,录音来源和内容是否属实仍须人工核对。
  • 传统字幕导出仍不烧录;图文页出的可播放副本会用原配音和字幕(逐字,或可选整句),这份副本和传统 SRT/WebVTT、正式交付记录分开。超过 300 秒的单段对齐要按已审阅分镜拆开,不能把时间估计当逐音素真值。
  • 本期影片的定稿音频和词轴已登记,影片已于 10 月 11 日 12:43 通过本人审定;ElevenLabs 只在 10 月 21 日用免费账户的 Roger 音色跑通过一次接口,音色未定稿;网页能试听的 Jason 音色走接口返回 HTTP 402(免费账户不能经接口用音色库音色),没有因此充值或订阅。这次网页核对没有发配音请求、没有加载模型、没有回听,账户和真实语音链路当前是否可用未核对。
  • 旧配音 v1 身份和有效的旧 Whisper 词轴仍可读取;自带 Whisper 推理已退役,兼容读取不等于重新启用它。
失败与恢复
情况
怎么处理
旧音频没有身份,或脚本、表演稿、供应商、型号、音色、选项变了
拒绝复用,保留旧文件并提示审阅后运行 tts --force。
Fish 或 ElevenLabs 返回错误、空内容或坏的时间戳
当前阶段直接失败,即使旧 MP3 还在也不能通过;ElevenLabs 付费结果不确定时不自动重试。
音频、文案或对齐来源改变
拒绝过期词轴;明确 timing --source chinese-asr --force 可只重建时间位置,保持原配音,随后重建受影响的场景。
录音对齐缓存缺失或失效
plan 只提示先运行 align;align 失败直接报错,不估计词时刻、不重新配音。
docfilm 多音字检查有待看项(退出码 2)
交 AI 改当期 say 或在项目表加规则,再检查;检查本身不拦合成,所以要先处理再合成。
docfilm 改了配音或插删念白段
先 shotlist renumber 移锚点,再重新检查、plan,只重渲受影响的段。
出问题时
边界
  • 情绪与停顿标记按所选供应商和型号写:Fish S2 用 [excited]、[pause] 这类,ElevenLabs v4 用 [curious]、[Brief pause] 这类音频标记(不用 SSML break)。标记只写在表演稿里,字幕和共享对齐用原稿,不把标记当实际发音;不保证每个标签每次都被遵从,也不保证未知标签不被念出。录音段之间也能用 pause 加停顿。10 月 21 日之前的版本里,这类标记只用于 Fish 配音。docfilm 的多音字检查不报“一 / 不”变调、轻声和独立的“的”;本人报一个读错,就在项目多音字表加一行,新增后用检查命令确认命中和相邻反例。
  • 录音只裁切和统一采样率、声道,不变速、不降噪、不改音色,也不加配音默认的淡入淡出;逐字稿必须对应所选区间,录音来源和内容是否属实仍须人工核对。
  • 传统字幕导出仍不烧录;图文页出的可播放副本会用原配音和字幕(逐字,或可选整句),这份副本和传统 SRT/WebVTT、正式交付记录分开。超过 300 秒的单段对齐要按已审阅分镜拆开,不能把时间估计当逐音素真值。
  • 本期影片的定稿音频和词轴已登记,影片已于 10 月 11 日 12:43 通过本人审定;ElevenLabs 只在 10 月 21 日用免费账户的 Roger 音色跑通过一次接口,音色未定稿;网页能试听的 Jason 音色走接口返回 HTTP 402(免费账户不能经接口用音色库音色),没有因此充值或订阅。这次网页核对没有发配音请求、没有加载模型、没有回听,账户和真实语音链路当前是否可用未核对。
  • 旧配音 v1 身份和有效的旧 Whisper 词轴仍可读取;自带 Whisper 推理已退役,兼容读取不等于重新启用它。
失败与恢复
情况
怎么处理
旧音频没有身份,或脚本、表演稿、供应商、型号、音色、选项变了
拒绝复用,保留旧文件并提示审阅后运行 tts --force。
Fish 或 ElevenLabs 返回错误、空内容或坏的时间戳
当前阶段直接失败,即使旧 MP3 还在也不能通过;ElevenLabs 付费结果不确定时不自动重试。
音频、文案或对齐来源改变
拒绝过期词轴;明确 timing --source chinese-asr --force 可只重建时间位置,保持原配音,随后重建受影响的场景。
录音对齐缓存缺失或失效
plan 只提示先运行 align;align 失败直接报错,不估计词时刻、不重新配音。
docfilm 多音字检查有待看项(退出码 2)
交 AI 改当期 say 或在项目表加规则,再检查;检查本身不拦合成,所以要先处理再合成。
docfilm 改了配音或插删念白段
先 shotlist renumber 移锚点,再重新检查、plan,只重渲受影响的段。
依据与来源
真实入口
  • 外部旁白、尾静音与音频身份;Fish / ElevenLabs 供应商配置(pipeline.tts show/configure,voice.json)
  • 原稿与表演稿、GB 发音替换
  • 真实录音裁段、逐字稿对齐与段间停顿
  • 真实时长与音频身份
  • 词轴复用、Fish / ElevenLabs 原生时间与共享 ChineseASR 对齐适配
  • SHA-256 与原子伴随记录
如何验证
  • 2026-09-03 历史 33 项回归覆盖旧脚本/音频身份,之后未重新运行;当前 test_speech_linkage.py 扩展了原生词轴和共享对齐合同,另有 test_recording_alignment.py、test_pages_documentary_audio.py 覆盖录音和停顿;626774f 源码共有 267 个测试定义(全项目),这次都没有运行。自动回归里的配音用模拟响应。
  • 2026-09-18 21:02 的静态 doctor 证明路由和适配入口存在,不证明实际 API、声线或本地语音推理成功;doctor-live 会真向当前供应商发一句测试音,可能消耗额度,这次没跑。
  • 2026-10-21 用免费账户、eleven_v4 和官方内置 Roger 音色跑通实际 tts → timing → subtitles,产出 10.04 秒音频,用原生时间戳,字幕保留 16GB、32GB 和 Good morning(记录在 docs/VOICE.md,这次未重跑);这是接口验收,不是音色或听感验收。
  • 本期真实配音与词轴的产生和审定属于影片制作记录;这次网页核对没有生成新的 audio_NN.mp3 或 srt_NN.json 样例。
与其他模块的关系

本模块给画面提供声音、总时长和可触发的词;场景制作决定怎样用这些时间,出片负责逐帧执行。

依据与来源
真实入口
  • 外部旁白、尾静音与音频身份;Fish / ElevenLabs 供应商配置(pipeline.tts show/configure,voice.json)
  • 原稿与表演稿、GB 发音替换
  • 真实录音裁段、逐字稿对齐与段间停顿
  • 真实时长与音频身份
  • 词轴复用、Fish / ElevenLabs 原生时间与共享 ChineseASR 对齐适配
  • SHA-256 与原子伴随记录
如何验证
  • 2026-09-03 历史 33 项回归覆盖旧脚本/音频身份,之后未重新运行;当前 test_speech_linkage.py 扩展了原生词轴和共享对齐合同,另有 test_recording_alignment.py、test_pages_documentary_audio.py 覆盖录音和停顿;626774f 源码共有 267 个测试定义(全项目),这次都没有运行。自动回归里的配音用模拟响应。
  • 2026-09-18 21:02 的静态 doctor 证明路由和适配入口存在,不证明实际 API、声线或本地语音推理成功;doctor-live 会真向当前供应商发一句测试音,可能消耗额度,这次没跑。
  • 2026-10-21 用免费账户、eleven_v4 和官方内置 Roger 音色跑通实际 tts → timing → subtitles,产出 10.04 秒音频,用原生时间戳,字幕保留 16GB、32GB 和 Good morning(记录在 docs/VOICE.md,这次未重跑);这是接口验收,不是音色或听感验收。
  • 本期真实配音与词轴的产生和审定属于影片制作记录;这次网页核对没有生成新的 audio_NN.mp3 或 srt_NN.json 样例。
与其他模块的关系

本模块给画面提供声音、总时长和可触发的词;场景制作决定怎样用这些时间,出片负责逐帧执行。

复制 AI 续作说明

项目:让每段旁白有声音,也知道每个词在什么时候出现;仓库:页面未提供仓库地址;范围:整个项目;目标:(这里写这次要做的事)。先读项目的 AGENTS.md 和说明,按现行规则做。

把“目标”换成这次要做的事,整段复制给 AI。