agentleFS
miaqu766520-a11ymiaqu766520-a11y/ai-line-skills/skills/voicebox-clone/SKILL.md

voicebox-clone

Skill7 starsChanged 2 months agoMITView on GitHub

本地克隆配音管线:用本地 Voicebox(Qwen3-TTS 克隆音色)或任何兼容的本地 TTS 服务,给口播稿/解说词配音,产出 mp3 + spans.json 句级时间轴。当用户说「配个音」「口播配音」「解说配音」「克隆配音」「把这段文案读出来」时默认用本 skill。发声指令只能走 instruct 参数,正文里写括号标注会被念出来。首次使用先走「第 0 步 · 装配音服务」和「建你自己的音色」。

The file

Files
SKILL.md

Voicebox 克隆配音

把文案转成你自己克隆音色的配音音频(本地 Qwen3-TTS,免费无限重生成),产出 mp3 + spans.json 供画面/字幕对齐。

品牌说明:本 skill 源自「博仔说」AI 自媒体生产线,此为粉丝通用化改写版——音色、路径全部参数化,任何人在本机建好自己的音色即可使用。

第 0 步 · 装配音服务(首次使用必做,已装过跳过)

  1. Voicebox 是什么:一个本地运行的 Qwen3-TTS 克隆配音桌面 App,启动后在 http://127.0.0.1:17493 提供 HTTP API(FastAPI,文档在 /docs)。它不是本 skill 的一部分,需要单独安装。
  2. 去哪装:获取与安装方式见群公告 / 配套文档(随本 skill 发布渠道提供,本文件不提供下载地址)。模型首次下载需要网络能访问 Hugging Face(或设置 hf-mirror 镜像)。
  3. 没有 Voicebox 怎么办:可换任何 OpenAI 兼容本地 TTS 服务,改配置里的 base_url 即可(scripts/config.json,参照 config.example.json;若 API 形状不同,需要按其接口适配 voicebox_tts.py 的 api()/generate() 两个函数)。
  4. 装完自检:App 在跑的前提下,浏览器打开 http://127.0.0.1:17493/health 能通即就绪。

建你自己的音色(首次使用必做,一次即可)

  1. 录参考音:手机/电脑录一段 ≥10 秒干净人声(安静环境、正常语速、无背景音乐、无混响),存成 mp3/wav。
  2. 建档案:打开 Voicebox App → 音色/Profile 管理 → 用这段参考音新建一个音色档案 → 记下生成的 profile id(一串 UUID)。
  3. 记到用户配置:把 skill 目录下的 config.example.json 复制为 config.json,填入你的 profile id(也可以用环境变量 VOICEBOX_PROFILE_ID 或命令行 --profile-id 传,优先级:命令行 > 环境变量 > config.json)。

铁律

  1. 发声指令只走 instruct 参数(如「语速放慢,声音压低」),正文里写括号标注会被逐字念出来(12 组实测实锤)。
  2. 停顿只能靠标点(逗号/句号/省略号/破折号),指令控停顿无效。
  3. 音色档案全部参数化:--profile-id 参数 / 环境变量 VOICEBOX_PROFILE_ID / scripts 同级 config.json 三选一;没有内置音色,参考音 = 任意 ≥10s 干净人声(见上「建你自己的音色」)。
  4. 输出 wav 统一转 mp3;spans.json 用本机缓存 whisper small 对齐生成。
  5. 起音脏字必剪头(多次复现):克隆音色在「你的…」开头的稿会固定多发一个「是」音节(0~0.2s)。交稿前 whisper 词级查第一个词,是脏字就 ffmpeg -ss 0.17 剪掉,别整段重生成。不限首词(首词「上一期」也中招)——每稿必查,不赌首词。
    • 补丁(A/B 实测 9 条 5s 样本):instruct 防脏头无效(「直接念正文,不要任何语气词」3/3 仍带「是」脏头,与读音控制一样压不住采样级口癖)。正解 = 首垫字法:输入文首垫「好,」,脏头被钉在垫字区(实测「是」落在「好」前 0-0.26s,正文 0.98s 才起)——生成后按词级剪到正文首词前 50ms,垫字带脏头一次剪净,落点 3/3 稳定。尾垫「嗯」不稳定(3 条仅 1 条保留,模型会吞垫字)——垫尾可省。
  6. 标点停顿不可控,精确停顿靠后补静音(实测):文稿里写「……」各关节间隙随机落在 0.3~0.65s,想要均匀长停顿(如段落间 0.75s)别赌标点——流程:whisper 词级定位段落首词前一帧 → wave/numpy 在该点插静音(目标间隙 − 现有间隙,30ms 淡入边防爆音)→ 再 loudnorm。间隙时长用 silencedetect=noise=-35dB:d=0.3 验收。⚠️ 适用边界(事故补丁):本流程仅限段界/关节级大间隙(≥6 处以内);行内逐句补静音禁用,详见铁律 11 红线。
  7. ≥300 字必须分段生成(实锤):整条 /generate 超 300 字会病态卡死(45 分钟 GPU 99% 空转不出,cancel 杀掉);按段落分段生成(每段 37 分钟稳出),ffmpeg 拼接,段间 0.35s 静音。
  8. 分段生成 = 每段一次脏头机会,必须逐段查起音再拼接(交付事故教训):只查整文件头不够——每次 /generate 都可能带脏头(单字「是」到多音节幻觉都有),分段拼接后脏头全落在片中。流程:每段 whisper 词级定位首个正确词起音点 → 逐段 -ss 剪头(+30ms 淡入)→ 才准拼接。词级检测只认「词」,非词爆破音/气声会漏网(二次事故:0.36s 爆破音残留进成片)——裁剪点必须词级 + RMS 能量前沿双证,剪后段首能量干净才算完。
    • 补丁(用户耳朵抓出词级漏检):词级无脏词 ≠ 无插入音节。句中接缝处(词与词的 0.1~0.3s 低能区)可能藏 whisper 词级完全不转写的插入音节(「有/是」气声级,RMS 仅 -30dB 上下),全文转写还会把它吸收掉。增补流程:词级词间间隙 >0.15s 的接缝逐个数 → 每处 ffmpeg -ss <窗> -af volume=+8dB 隔离放大 → medium 转写该窗 → 出现稿外音节 = 插入词,重 roll 该段(别想静音替换蒙混——插入音节常紧贴下词起音)。用户报「多了一个字」时优先怀疑此类。
    • 补丁(用户报「停顿中间有脏字」):末词后尾随音节扫描。TTS 会在句尾能量谷后再吐一个小尾巴音节(「的」类,可仅低于语音 5dB)——whisper 词级把它吸收进末词时间戳、段头扫描又覆盖不到段尾,双重盲区;成片里正好落在演示停顿开头,听感=「停顿中间有脏字」。终检增补两道门:①末词后 0.5s 尾随事件扫描——末词结束后能量谷后再复起 ≥10dB 即判脏,谷 ≤-38dB 双证下刀(30ms 淡出+补静);②段内停顿查「谷内复起」——不只查起音点,每个 ≥0.3s 静音窗的前后沿都扫,窗内/窗沿复起事件按接缝隔离放大转写验明正身。
    • 补丁(段头口头禅 + 等量置静音修复法):分段合成时 TTS 在每段开头自动补一个口头禅「是」(3/3 段全中,拼接静音后独立鼓起峰 -10~-12dB,隔离转写实证)——段头 0.3s 必扫已是铁律,此条确认命中率可视为 100%。修复新选项:脏音节若完整落在静音区(不贴任何真词起音),允许等量置静音(区间拉数字零、切口 30ms raised-cosine、总长不变)代替剪头/重 roll——字幕时间轴零错位,适合字幕已按原音频对齐的返修场景;贴真词的仍按铁律 8 剪头或重 roll。验收:修后 insert 清零、切口单样本跳变 ≤-40dBFS 防咔哒。
  9. 交付前独立转写全文比对稿文(同事故根源):强制对齐(SequenceMatcher 把稿文贴到音频上)会掩盖音频里的插入词——字幕干净 ≠ 音频干净。验收门:whisper 独立转写最终配音 → 与稿文 diff,插入词/错读词清零才交付。声调错读(打法→答法 dǎ→dá 级)用同音写法修正重 roll 该段(纪要→记要、事实链→事时链、生成→声成),别整片重 roll。
    • 补丁:全文转写会吸收 faint 插入音节(上下文平滑),full-text diff 干净 ≠ 无插入——铁律 8 补丁的接缝隔离放大转写是全文比对的补充门,不是替代。
    • 专名连读解法(同批验证):TTS 把「知识库搭建师」这类复合专名切成两截读时,重 roll 加 instruct「『X』是一个完整产品名,中间不要停顿」可愈(一次即中);验证用 silencedetect 查词内应无 ≥0.06s 间隙。
    • 补丁(文本比对的两个天生盲区——多音字读音错 + 韵律断句错)。whisper 把语音归一成文字:「调」念 diào 还是 tiáo 写出来都是「调」;norm() 去标点后「怎么用深」和「怎么用|深」是同一字串——两类错误在 diff 里完全隐形(曾实证毛坯带这两处暗病连过三版自检,直到卡顿修好后才被用户耳朵抓到)。补两道门: ① 多音字人耳清单:稿文落档时机械扫描多音字(调/长/重/少/还/为/着/得/好/难/行/省/乐/处/当/差/空/只…),凡出现即列入「人耳抽听清单」,交付前逐个确认读音(人耳或偏置 prompt 转写);错读修法 = 同音写法修正重 roll 该句(合不合调→合不合条)。 ② 不可拆短语连贯门:稿里所有自创/口语缩略搭配(这类 TTS 不认识的组合)列入短语表,验收时 silencedetect 查词内间隙 ≥0.06s 即报拆读;修法 = 连写重 roll,仍拆加 instruct「『X』是一个完整短语,中间不要停顿」(与专名解法同源)。 ③ 读音方向先确认再动手(三轮返工教训):用户报「念成了 X 不是 Y」时,用户写的拼音就是目标音(「不是 tiao」= 要 diào)——理解反了越修越错。多音字锁音写法优先级:锁音词写法 > instruct 声明 > 同音字——「调子」一词锁定 diào(一次即中),instruct「读 diào」压不住(仍升调),同音字「钓」读成平调。 ④ F0 判定窗必须词级精确到单字:多字综合窗会把「前高后低」的多字轮廓误判成降调;逐字词级窗 + F0 走向才是物证。另:拉长起音的字会被 whisper 听成别的字(「配」长起音→幻听「是」),转写存疑时用归一化互相关证本体(峰值 ≥0.94)。
  10. 验证模型选型:large-v3 与 Voicebox 共存会 VRAM 不够 segfault;验证用 medium,small 只作旁证;判错/判对都要 small+medium 双模型一致,防单模型幻觉双向误判。
  11. 气口只利用真实静音,绝不在连续语流中间硬造(三返工实锤):whisper(medium)词级时间戳误差 ±0.2-0.5s,TTS 连续语流字间电平降不到 -45dB——按「词界中点」下刀 37 刀实测 32 刀切在正在发音的字上(切口两侧 50ms 电平 -14~-35dB),听感全程卡顿。红线:
    • ① whisper 词级时间戳不可作切割依据(只可作 ±0.5s 窗的定位参考);
    • ② 切点必须落在 RMS 包络实测的天然静音段中心(5ms 窗 < -40dB、段长 ≥0.06s),切口两侧 50ms 电平 < -38dB 才下刀,找不到就弃刀——紧一点的自然语流 ≫ 切伤的卡顿;
    • ③ 行内零切割:只验收段界(天然 ≥0.22s 即免刀),行界赶是 TTS 语流问题,靠 ④/⑤ 解决,不靠手术;
    • ④ 接缝淡化长度 ≤ 天然静音段长/2 − 5ms(淡化必须在静音段内部完成,不碰字);
    • ⑤ 需要均匀气口的长稿:分段生成再拼接(铁律 7/8,段尾天然衰减干净)是唯一正确路线,别在整条音频上做手术;
    • ⑥ 误诊防线:用户报「卡顿/一顿一顿」先跑切口电平实证(每刀两侧 50ms RMS),别拍脑袋归因——实证教训:v1(52 刀)判「一顿一顿」→ v2 减到 37 刀仍「非常卡顿」,根因从来不是刀数,是每刀都切伤。
    • ⑦ 样本索引换算漂移坑(实锤):5ms 窗 winN=int(0.005*44100)=220,但每秒实际 200.45 窗——时间↔索引换算用 i*0.005 会系统性右偏 0.24%(60s 处偏 0.14s,正好从静音谷偏到字音头上)。一切 index↔time 换算必须走 i*winN/SR,验收时用已知静音段反验换算正确性。
  12. 锁音写法预检=机器门:voicebox_tts.py 默认调用 scripts/tts_precheck.py 自动改写词表锁音规则(V2→V two、18年→一八年、拉丁连字符兜底去连字符),改写打印 [预检] 行;--no-precheck 可关。你自己的新教训加在 scripts/tts_rules.local.json(可选用户规则文件,[["原文","写法"],…])或直接改 LOCKS 表,别再指望执行时翻文档。
  13. 词级转写提速:词级慢的根因=Triton 缺失(Windows 无官方版),不是 CUDA 缺失;装 triton-windows 后 medium 词级从 5-8 分钟/文件 → 6 秒。faster-whisper 亦推荐安装(模型下载需可访问 Hugging Face,或设置 hf-mirror 镜像)。QA 一律直接带 word_timestamps 跑,不再绕。
  14. 后期编辑必须脚本化并入拼接管线,手工一次性编辑必丢(交付事故实锤):消音手工做了一次,流水线两次重跑拼接后被无声覆盖,交付才发现——重跑的拼接脚本只认自己产物,不会保留来路不明的手改。任何成品级音频编辑(消音/换音节/剪字)必须落成可重跑的 qa 脚本步骤(手术+自检一体),排进管线在拼接之后跑,报告里引用「已修复」前先确认该脚本存在于管线清单。
  15. 外科修补法定型:交付后发现局部读音错/漏消音,走「词级定位 → 等长替换(参考样本嫁接 / 置静音)→ -c:v copy 换音轨」,禁止整片重渲染(字幕已烧录时等长是铁条件,总时长差必须 ≤0.05s)。要点:
    • ① ASR 词界只作 ±0.3s 参考,切口边界用 5ms RMS+谱质心剖面钉死(音节起始脉冲/鼻音尾/能量谷都是物证);
    • ② 嫁接样本用 atempo 伸缩到与被替换区样本级等长(比值 0.52.0),RMS 配平(增益夹 0.52.0),30ms raised-cosine 交叉淡化;
    • ③ 消音的过渡必须放区外(前 30ms 罩前字衰减尾、洞体严格全零)——过渡罩在爆破脉冲上会留「d-」残声(实证改区外过渡后残峰归零);
    • ④ 拼回 -map 0:v -map 1:a -c:v copy -c:a aac + -movflags +faststart,交付前机器三验:silencedetect 洞落在消音位(-40dB)、替换区谱质心 ≈ 参考样本(16k 幂谱 300-3500Hz 带内口径)、新旧视频流 md5 一致+总时长差 ≤0.05s。

用法

python <本skill目录>/scripts/voicebox_tts.py \
  --text "文案全文" \
  --out 配音文件名 \           # 产出 配音文件名.mp3 + 配音文件名.spans.json
  [--instruct "语速放慢,声音压低"] \
  [--text-file 稿.txt] \
  [--profile-id <你的音色id>]   # 不传则按 环境变量 VOICEBOX_PROFILE_ID → config.json 顺序取
  • 音色 id 管理:python <本skill目录>/scripts/voicebox_tts.py --list-profiles 可尝试列出服务端音色档案(列不出就打开 http://127.0.0.1:17493/docs 或在 App 内查看)
  • 前置:Voicebox 服务在跑(脚本会自动探测;没跑会尝试启动,启动路径按 环境变量 VOICEBOX_EXE → config.json 的 exe 字段 → 常见安装位置探测,都不中就提示你手动打开 App)
  • 不满意就重跑换 seed;API 文档 http://127.0.0.1:17493/docs
  • 强情绪演绎(哭腔/冷笑要足劲儿)若 instruct 效果不够:换 seed 多 roll 几次、把情绪写得更具体(「压抑着愤怒,低声说」);或换其他支持情感指令的本地 TTS 管线

实战回流(生产线介绍配音)

  1. whisper 词界零间隙吸附:手术插入补丁时,在词界 ±0.3s 内找 ≥30ms 微静音段且段尾贴词界、取中心插入——13 个关节零损伤;别用能量最低点裸搜(会扎进上一字尾衰减区),也别固定 t-0.02(切残长尾字)。
  2. 响度两遍线性 loudnorm 到 -15.2 LUFS 即真峰值安全上限;单遍到 -14 会回落 -15.9。要更响需动态限幅,但 TP 会超 -1.5 规范,取舍保 -15.2。
  3. 同音写法修正按语境选字:「18 年做抖音」要念 yī bā nián 就写「一八年」不写「十八年」(shí bā nián)——修反过一次。配套:whisper 转写会把「一八年」也写成「18年/十八年」,字幕落稿前必查这类数字写法(曾实证字幕「相当于十八年」就是被转写带错的)。
  4. 偏置 prompt 转写鉴别法:验证「一八年 vs 十八年」这类同音字时,whisper 默认都写成 "18",加「年份数字用汉字书写」prompt 后才能区分。

实战回流(配音气口手术)

  1. 整条生成能过 ≠ 能交付:无气口病。375 字整条一次生成没卡死(铁律 7 边界下),但行界间隙中位 0.09s,用户判「一句话读太长、完全没停顿气口」。根因:配音输入版把稿面短句合并成长段落,标点停顿随机且太短。气口手术管线(作者生产线脚本不随包分发,思路如下可自建):breath_audit(medium 词级体检+间隙分布)→ breath_fix(行界词界插静音:行界补到 0.30s/段界 0.70s + 两遍 loudnorm)——交付配音标配气口,别等用户点名。 ⚠️ 更正:上述「逐行界插静音」路线已推翻禁用——v1(52 刀)用户判「一顿一顿」,v2(37 刀)判「非常卡顿」,实证 32/37 刀切在正在发音的字上(whisper 词界中点不准 + 连续语流无真静音)。正确管线 = 段界天然静音验收版:行内零切割 + 段界天然静音验收(≥0.22s 免刀、找不到真静音弃刀)。「标配气口」的正确理解 = 标配「段界验收门」,不是标配「行界插值」(铁律 11)。
  2. 双模型判定器先繁简归一:whisper small/medium 都爱写繁体(進階篇/最細),判定函数直接字符串匹配会把读对的 take 误判 FAIL(白 roll 4 次教训)。判定目标词前先做繁简映射(進→进/階→阶/細→细/館→管/還→还/誠→成/徵→蒸…)。
  3. 互相关物证法破「幻听死循环」:孤立 take 验收说对、整文件上下文转写说错(篇/片、细/吸 flip-flop)时,别再用 whisper 判 whisper——把验收过的 take 与终版对应区域做归一化互相关(numpy correlate),峰值 0.94+ 且位置正确 = 好 take 确实在终版里,上下文幻听不攻自破。whisper 对同一段音频在不同上下文会给不同文本,只有波形不会撒谎。
  4. 手术后 spans 必须重算,不用位移簿记:插静音/替换后用「原 spans + 累计位移」推的新 spans 会累积漂移(实测中段起逐行晚 ~1.5-2s,fuzzy 匹配还会丢行首)。正确姿势:终版音频重新跑一遍 medium 词级 + SequenceMatcher 对齐,个别 fuzzy 行首用词级区域实测手修。
  5. 错读重 roll 顺手记:蒸(zhēng→zhēn 双模型实锤,原文 roll 不出,TTS 输入改「蒸馏成」读出正确音)、篇(piān→piàn 种子依赖,重 roll 可愈)、接活(huó→huǒ,重 roll 可愈)。

实战回流(配音卡顿三返工·气口手术红线确立)

  1. 事故链:v1 按 56 行插 52 刀(行界 0.30/段界 0.70)→ 用户判「一顿一顿」;v2 误判为「刀数太多」减到 37 刀(行界 0.18/段界 0.55)→ 用户判「非常卡顿」;实证:37 刀里 32 刀切口两侧 50ms 电平 -14~-35dB = 切在正在发音的字上。v3 方案「段界-only 深静音利用法」:0 插入、4 段界天然静音(0.23-0.32s)验收免刀、2 段界 TTS 连读弃刀保语流 → 用户验收通过。
  2. 为什么以前没犯:一期无手术整条直用;二期分 6 段生成再拼接(段尾天然衰减 + 拼接点干净);三期第一次在整条连续语流上「人造气口」——气口只能利用真实静音,不能在语音中间硬造。
  3. 正确管线(段界天然静音验收版):对齐仅用于定位段界窗口(±1.0s)→ RMS 包络(5ms 窗 <-40dB)找最长天然静音段 → ≥0.22s 免刀 / 不足则在静音中心补到 0.45s(切口两侧 50ms <-38dB 硬验收,不过弃刀)→ 接缝淡化 ≤ 静音段长/2−5ms → loudnorm。产物自带每刀电平复检报告。
  4. 段界天然间隙参考谱(克隆音色实测):段界 -40dB 阈值下 0.09~0.32s 不等——连读段界(<0.15s)是语流属性不可手术,要均匀气口只能分段生成(铁律 11-⑤)。
  5. 误诊教训:用户报卡顿第一反应别归因「量」(刀数/静音长度),先做切口电平实证归因「质」(是否切伤)——v1→v2 就浪费一轮返工。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.