# Voicebox Clone

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

- **Type:** Skill
- **Install:** `agentstack add skill-miaqu766520-a11y-ai-line-skills-voicebox-clone`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [miaqu766520-a11y](https://agentstack.voostack.com/s/miaqu766520-a11y)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [miaqu766520-a11y](https://github.com/miaqu766520-a11y)
- **Source:** https://github.com/miaqu766520-a11y/ai-line-skills/tree/main/skills/voicebox-clone

## Install

```sh
agentstack add skill-miaqu766520-a11y-ai-line-skills-voicebox-clone
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 杀掉）；按段落分段生成（每段 3~7 分钟稳出），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 窗 /scripts/voicebox_tts.py \
  --text "文案全文" \
  --out 配音文件名 \           # 产出 配音文件名.mp3 + 配音文件名.spans.json
  [--instruct "语速放慢，声音压低"] \
  [--text-file 稿.txt] \
  [--profile-id ]   # 不传则按 环境变量 VOICEBOX_PROFILE_ID → config.json 顺序取
```

- 音色 id 管理：`python /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 就浪费一轮返工。

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [miaqu766520-a11y](https://github.com/miaqu766520-a11y)
- **Source:** [miaqu766520-a11y/ai-line-skills](https://github.com/miaqu766520-a11y/ai-line-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-miaqu766520-a11y-ai-line-skills-voicebox-clone
- Seller: https://agentstack.voostack.com/s/miaqu766520-a11y
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.