游戏/视频批量角色语音 + 音效生成指南（audio.cpp 本地工具链）

2026-08-07 第九轮修订：本版已按"Higgs 音色性别漂移专项测试"（300+ 条定向实验与多轮复验，全部人耳听判）重写配方——旧版喊话配方（含 emotion:fear/pitch_high）已证实会在 en/ja/ru 参考音上 ≈100% 变女声，全部作废。修订要点：①喊话类禁用 anger×fear 组合（翻车根因是组合、不是 fear 本身）；②新喊话配方 = anger+shouting(±expressive_high)，实测 74/74 条全男声且响度更高；③fear 脱离 anger 单独使用安全（fear+whispering 可做"被压制/颤抖"，限已验证参考）；④sadness 单独 6/6 翻车，恐惧/悲伤情绪女声表现更佳 → 这类台词直接配女声参考；⑤机器 YIN-F0 在强情绪喊叫上误报 100%，性别只能人耳判定。本文为自包含可分享版（作者完整实验档案保留在本地，本指南不依赖任何外部文件即可复现全部工作流）。

解决什么问题

给游戏/视频批量生成角色语音：需要音色统一（同一个角色所有台词听起来是同一人）、多语言（中/俄/德/日/英等）、带情绪强度（喊话要有力气、不是念台词）。
AI 音效来源问题：不想用有版权风险的网络音效库，或想为每一把枪/每一个场景生成独有音效。
"有气无力"的通病：同一条文本，加不加情绪标签（<|emotion:anger|><|style:shouting|>）听感天差地别——本文给出实测最优配方。
音色性别漂移（2026-08-07 专项定位）：有参考音克隆时偶尔/经常"男声变女声"——根因是 anger×fear 标签组合 × en/ja/ru 参考音（≈100% 翻车，zh/de 参考免疫），与台词语言、seed、pitch_high 无关；sadness 单独也 6/6 翻车。本文给出零翻车配方与分场景使用规则（恐惧/悲伤台词反而建议直接用女声参考——实测女声表现更佳）。
批量生成的高失败率：批量跑 95 条台词，单条卡死会中断整批、个别 seed 会触发无限循环——本文给出避坑流程。
入库麻烦：生成完要裁剪、归一化、转码、嵌入游戏（本文实测 OGG + base64 内嵌，file:// 直接可玩、无 CORS 问题）。

适用条件

引擎 / 框架：任意游戏引擎/编辑器（本文示例为 HTML5 + WebAudio，decodeAudioData 原生吃 OGG）；音频生成侧使用 audio.cpp（ggml 运行时，支持 CUDA / Vulkan / Metal / CPU，Windows/Linux/macOS）。
AI 模型（均本地运行）：
- Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF —— 文字描述"造音色"（无需参考音频）
- Higgs-Audio-v3-TTS-4B-GGUF —— 音色克隆 + 情绪/风格标签控制（建议常备）
- Stable-Audio-3-Medium-GGUF —— 音效 / BGM 生成（提示词用英文）
AI 模型或 Agent：人工命令行操作即可；也可交给具备命令行与文件读写能力的 Coding Agent（opencode 等）按本文 Prompt 自动执行。
已验证版本和日期：2026-08-07（第九轮，300+ 条实测样本全流程）；Windows 11 + AMD RX 6600 XT（Vulkan 后端）实测；audio.cpp GGUF 包、Higgs v3-4B、Qwen3 VoiceDesign 1.7B、Stable Audio 3 Medium。BGM 路径与音效同工具链（Stable Audio 3 系列），音乐生成本文未实测，标注为规划项。

验证环境

操作系统：Windows 11（PowerShell 5.1 环境，UTF-8/GBK 混用问题已按文档规避）
硬件：AMD Ryzen 平台 + AMD Radeon RX 6600 XT（8GB 显存），未使用独立声卡（板载输出）
推理后端：ggml Vulkan（设备 fp16 支持，矩阵核无）；audio.cpp 官方 Windows 预编译包 bin/audiocpp_cli.exe
模型与任务（均为 GGUF 包，来自 audio-cpp/audio.cpp-gguf）：
- Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF —— 造基准音色（--task vdes，24kHz 输出）
- Higgs-Audio-v3-TTS-4B-GGUF —— 台词克隆（--task tts，24kHz 输出）
- Stable-Audio-3-Medium-GGUF —— 音效生成（--task gen，带 mem_saver=true）
辅助工具：ffmpeg（转 44.1kHz mono OGG）、audio.cpp tools/ 下的 audio_qa.py / loop_check.py / burst_check.py / audio_trim.py（Python venv 运行）
游戏侧：HTML5 + Three.js + WebAudio（decodeAudioData 原生解码 OGG，base64 内嵌免 CORS）
生成规模与耗时参考（本环境实测）：50 条人声（5 语言 × 10 类）批量生成约 2 分钟；单条 Higgs 克隆 1~~2s；单条 VoiceDesign 约 1.2~~1.4s；质检+裁剪+转码另需约 2 分钟
验证日期：2026-08-07（第九轮修订，300+ 条实测样本全流程复验）

使用方法

0. 准备（一次性）

# 1) 安装 audio.cpp 预编译包(Windows) 或按官方 README 构建
#    Release 页下载 zip 解压即可, 内含 bin/audiocpp_cli.exe

# 2) 下载 GGUF 模型包(建议 hf-mirror.com 加速), 放入 models/ 对应目录
#    Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF
#    Higgs-Audio-v3-TTS-4B-GGUF
#    Stable-Audio-3-Medium-GGUF

# 3) 确认 GPU 可用
& "E:\path\to\bin\audiocpp_cli.exe" --list-loaders
# 输出 registered_loaders=11 ... 即正常; 若驱动缺 Vulkan/CUDA, 可退 --backend cpu(慢)

1. 人声工作流（核心）

第 1 步：造基准音色 + 出基准台词（一个角色 = 一条基准音频；克隆永远挂这条基准，音色才不会漂）

$CLI = "E:\path\to\bin\audiocpp_cli.exe"
& $CLI --task vdes --family qwen3_tts `
  --model "E:\path\to\models\Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF" `
  --backend vulkan `
  --text "全体注意！听我命令！" `          # 基准台词 = 角色最有辨识度的短句
  --instruct "低沉沙哑的中年男声" `         # 音色描述; 换 instruct/seed = 换一个音色
  --language Chinese --max-tokens 256 --seed 7001 `
  --out "ref_zh.wav"

注意：俄/德/日等非中文文本必须走 UTF-8 JSON（--request-sequence），PowerShell 5.1 命令行按 GBK 解码会乱码。记住基准台词原文——后面克隆的 reference_text 必须一字不差（官方建议逐字转写含语气词，可显著提升克隆保真度；参考音 530s 干净语音最佳）。造完基准跑 F0 自检看音域：python tools\check_baseline_f0.py 基准.wav（2026-08-07 修正：Qwen vdes 按男声指令输出基本都是男声，F0≥175Hz 只是"音域偏高=偏年轻男声或偏女声"，以人耳为准；理想沉稳男声 80150Hz；克隆后若实测偏女声再换 instruct/seed 重造）。

第 2 步：Higgs 批量克隆台词（台词 JSON 必须 UTF-8 保存）

[
  {"id":"zh_spot_a","text":"<|emotion:anger|><|style:shouting|>敌人！有埋伏！","voice_ref":"E:/out/ref_zh.wav","reference_text":"全体注意！听我命令！","seed":8101,"max_tokens":2048},
  {"id":"zh_die_a","text":"<|emotion:anger|><|style:shouting|>Aaaah!","voice_ref":"E:/out/ref_zh.wav","reference_text":"全体注意！听我命令！","seed":9104,"max_tokens":2048},
  {"id":"zh_hurt_a","text":"<|emotion:anger|><|style:shouting|>Ugh!","voice_ref":"E:/out/ref_zh.wav","reference_text":"全体注意！听我命令！","seed":9011,"max_tokens":2048}
]

& $CLI --task tts --family higgs_audio_tts `
  --model "E:\path\to\models\Higgs-Audio-v3-TTS-4B-GGUF" `
  --backend vulkan `
  --request-sequence "lines.json" --out-dir "out"
# 输出 = 每条 id + .wav; 换 seed = 换一版

已验证的最优标签配方（2026-08-07 第九轮定稿，全配方禁用 emotion:fear）：

场景	配方（拼在台词前）
喊话类（发现/开火/手雷/坦克/敌机/冲锋/坚守/撤退/机枪）	`<\|emotion:anger\|><\|style:shouting\|>` + 台词（想更激昂加 `<\|prosody:expressive_high\|>`；实测 anger+shouting 74/74 全男声，RMS -20.6dB；+expressive_high 亦 24/24 全男，-21.6dB）
死亡尖叫	`<\|emotion:anger\|><\|style:shouting\|>Aaaah!`
受伤闷哼	`<\|emotion:anger\|><\|style:shouting\|>Ugh!`（最简最强）
击杀/换弹	`<\|emotion:anger\|><\|style:shouting\|><\|prosody:expressive_high\|>` + 台词
应答（收到）	`<\|emotion:determination\|><\|style:shouting\|>` + 台词
遗言	`<\|emotion:determination\|>` + 台词

为什么喊话禁用 anger×fear（2026-08-07 专项测试实锤）：翻车根因 = anger×fear 组合——含该组合的配方在 en/ja/ru 参考音上 ≈100% 输出女声（连 89Hz 深男参考也翻车），zh/de 参考免疫（0/50）；与台词语言、seed、pitch_high 均无关（交叉实验 + 单标签对照）。fear 脱离 anger 单独使用是安全的（fear 单独 / fear+shouting(无anger) / fear+expressive_low/high 全部保男声 10/10），但情绪平淡；fear+whispering 做"被压制/颤抖"效果最佳但按参考音分化（ref_ja 3/3 男声、ref_en 3/3 女声）。sadness 单独 = 6/6 女声（en/ja 参考必翻车），遗言/哀伤用 determination。实测听感：fear/sad 情绪女声明显更佳 → 恐惧/悲伤类台词建议直接配女声参考生成（女声参考+任意配方稳定且贴合）。响度实测：无 fear 配方 RMS -20.6dB 反而比含 fear(-23.1dB) 更响——旧版"fear 叠加是关键增益"的说法是误传，已作废。旧版含 pitch_high 的配方（曾认为是女声元凶）同样作废：pitch_high 本身无罪（zh 参考下 20/20 全男），只是与 fear 同时出现时被误判为元凶。

拟声词铁律：闷哼/尖叫一律用英文写法（Ugh! / Aaaah!），即使角色是俄/德/日/中——对应语言拟声词（Ай!/Aua!/うわっ!/呃啊!）生成后发音含糊出戏。<|sfx:screaming|> 标签+纯元音长喊、个别 seed 的长喊 Aaaah! 会 max_tokens 无限循环，批量遇中断按缺失清单换 seed 单条重跑。

批量质检（性别只能靠人耳）：机器 YIN-F0 在强情绪喊叫上误报 100%（实测机器全判女声、人耳全男），绝不能只靠 F0 数值判性别。流程：生成后抽 10%+（ja/en 短喊话全量）用试听页分组人耳确认——自制一个本地 HTML 试听页（每样本一个 <audio controls src="相对路径.wav"> 标签，按语言/类别分组排列，每条旁边标注 id 与机器 F0 仅供参考），浏览器 file:// 直接打开，逐条听并记录"男/女/可疑/异常"，无女声/无异常再入库；个别翻车条目换 seed 重抽。进阶做法：试听页里给每条加"男/女/可疑/异常"四个点击按钮 + 备注框，判定存 localStorage（刷新不丢），最后"导出 JSON"汇总给 Agent 解析入库——本流程在作者处已脚本化（make_listen_panel.py），任何具备文件读写能力的 Agent 均可自行实现同款，几分钟的事。

采样参数（P 组 30 条实测）：temp/top-k 全网格（0.8~1.2 × 30/50）救不了 anger×fear 翻车率（≈79%，seed 抽签决定）；安全配方在极端随机（temp1.2/topk50）下仍 3/3 全男；temp≥1.2 有爆音/音质劣化——生产保持默认 temp0.8/top-k30 即可。

2. 音效 / BGM 工作流

# 音效(Stable Audio 3 Medium, 提示词用英文; 枪声必须声明 single shot)
& $CLI --task gen --family stable_audio `
  --model "E:\path\to\models\Stable-Audio-3-Medium-GGUF" `
  --backend vulkan --session-option stable_audio.mem_saver=true `
  --text "single rifle shot, one shot only, no burst" --duration-seconds 3 `
  --seed 12345 --out "shot_a.wav"
# 同一提示词换 --seed 抽多版挑最好; 时长参考: 触发型2-4s/爆炸6-10s/氛围循环15-30s

# BGM/氛围: 同工具链, 提示词写风格+情绪(如 "somber war ambience, low strings, tense drums, loopable")
# 注意: BGM 路径与音效同管线, 音乐生成效果需按上述 QA 流程自行验证(本文未实测)

3. 质检 + 入库（必做，顺序固定）

$PY = "E:\path\to\venv\Scripts\python.exe"   # audio.cpp 的 venv 或系统 python3
# ① 循环检测(相似度>0.85=循环) / 杂音长段(>3s) —— 逐文件
$files = Get-ChildItem "out" -Filter *.wav | % FullName
& $PY "tools\loop_check.py"  @files
& $PY "tools\burst_check.py" @files
# ② 综合 QA(人声 --type voice; 枪声 --type sfx; 爆炸 --type explosion)
& $PY "tools\audio_qa.py" "out" --type voice --expected-s 1 --clip-pct 2
# ③ 裁首尾静音+峰值归一化(-1dBFS)
& $PY "tools\audio_trim.py" "out" --normalize
# ④ 转 44.1kHz mono OGG(WebAudio 原生支持, 比 WAV 小~60%)
ffmpeg -i out\zh_spot_a_t.wav -ar 44100 -ac 1 -c:a libvorbis -q:a 5 zh_spot_a.ogg
# ⑤ base64 内嵌进游戏(规避 file:// 的 CORS 限制)
[Convert]::ToBase64String([IO.File]::ReadAllBytes("zh_spot_a.ogg"))

游戏侧（WebAudio）播放：音频注册表对象（如 SFX_BANK）里存 base64 → atob → decodeAudioData → 空间化播放（距离增益/低通/pan）。

4. 交给 Agent 自动执行的主 Prompt（可单独复制）

你的任务：为我的游戏批量生成【人声台词】并入库。严格按以下工作流执行：

1. 用 E:\path\to\bin\audiocpp_cli.exe（--backend vulkan）完成全部生成；
2. 每个角色先造基准音色：Qwen3-TTS VoiceDesign 生成一条基准台词音频，
   记录基准台词原文（后续克隆 reference_text 必须一字不差），
   并用 check_baseline_f0.py 看音域作参考（F0 只提示音域高低，性别以我人耳为准；
   克隆后若实测偏女声再换 instruct/seed 重造）；
3. 克隆台词全部走 Higgs Audio TTS，文本必须写 UTF-8 JSON 文件再 --request-sequence 提交，
   禁止把非 ASCII 文本直接写在命令行（Windows GBK 会乱码）；
4. 强度标签铁律（2026-08-07 定稿，喊话类禁用 anger×fear 组合——en/ja/ru 参考含该组合必变女声）：
   喊话类 = <|emotion:anger|><|style:shouting|> 台词（更激昂加 <|prosody:expressive_high|>）；
   死亡尖叫 = <|emotion:anger|><|style:shouting|>Aaaah!；闷哼 = <|emotion:anger|><|style:shouting|>Ugh!；
   击杀/换弹 = anger+shouting+expressive_high；应答 = determination+shouting；遗言 = determination；
   被压制/颤抖 = <|emotion:fear|><|style:whispering|> 台词（限已验证参考，其余先小样抽验）；
   恐惧/悲伤/哀伤类台词建议直接配女声参考（女声表现更佳且稳定），禁用 sadness 标签（6/6 翻车）；
5. max_tokens 一律 ≥2048（512 在非中文语言会提前截断失败）；
6. 批量跑完必须核对输出文件数；缺失的条目按 id 单条重生成（批量遇循环会中断后续全部请求）；
   若某条报 "reached max_tokens before EOC"（长喊 Aaaah! 常见），换 seed 重试，别整批重跑；
7. 质检三件套：loop_check.py + burst_check.py（逐文件）+ audio_qa.py --type voice --expected-s 1，
   全部通过才算完成；日语省略号类遗言文本易触发 5.1s 周期死循环，发现即换 seed；
8. 性别验收（必须人耳）：机器 F0 在强情绪喊叫上不可信。生成试听页（HTML，每组样本一个
   <audio> 标签 + 分组 + F0 标注），我逐条试听确认无女声/无异常后你再入库；
9. 入库：audio_trim.py --normalize 裁剪 → ffmpeg 转 44.1kHz mono OGG → base64 内嵌进
   游戏的音频注册表（如 JS 资源对象/数据库），键名 = <语言>_<类别>_<变体>；
10. 完成后汇报：生成条数/质检通过率/缺失重生成记录/人耳验收结果。

如何验证结果

客观质检（生成侧）：loop_check 无 LOOP、burst_check 无 >3s 长段、audio_qa --type voice 全 PASS（含时长/SNR 分数）。人声短句 QA 阈值用 --expected-s 1（喊话 0.5~3s 属正常）。
能量对比：同一文本"无标签 vs 带强度标签"，RMS 差约 5dB（实测无标签 -25.6dB，anger+shouting -20.6dB）——听感"喊出来"而非"念出来"。（注：旧版"含 fear 最响 -19.9dB"的说法经 2026-08-07 实测修正：fear 配方反而更轻，-23dB 级。）
性别/音色一致性：同一角色多条台词由同一基准克隆，人耳确认同一人、无女声漂移（机器 YIN-F0 不可靠）；换 instruct/seed 才是另一个音色。
游戏内实机：硬刷新（避免浏览器缓存旧版），确认触发点（发现敌人/开火/受伤/阵亡/占旗等）能听到对应语言语音，距离衰减与左右声道正确。
入库一致性：base64 解码回 OGG 与源文件逐字节一致（脚本比对）。

已知限制与风险

性别漂移（2026-08-07 已定位）：anger×fear 组合 × en/ja/ru 参考音 ≈100% 女声化，zh/de 参考免疫；sadness 单独 6/6 翻车；与台词语言无关。规避 = 喊话用无 anger×fear 配方；fear 脱离 anger 单独使用安全（fear+whispering 做"被压制"限已验证参考）；个别 seed 仍偶发（如 ja 长喊 1/2），抽 10%+ 人耳验收 + 翻车条目换 seed。pitch_high 标签无罪（旧理论作废）。恐惧/悲伤台词直接用女声参考效果更好。
机器判定局限：YIN-F0 在强情绪喊叫上误报 100%；check_baseline_f0.py 只适用于平静基准台词的自检。
口音（2026-08-07 实测）：Higgs 无口音能力（无标签；vdes 造口音参考与跨语言克隆都发音归一化，参考音只贡献音色）。唯一可行 = 音译 hack：用目标口音语言的正字法拼写英语台词（西里尔/片假名/德语拼写/拼音），模型按该语言读音念英语即得口音——听感是"读错读乱的外国士兵"，做"会说英语的俄/德/日士兵"角色很好用。示例：Мув ап, каве ми!（俄）/ ホールドザライン、ドントリトリート！（日）/ Mof ap, kawer mi!（德）/ Muwu apu, kawa mi!（中）。局限：可懂度与口音浓度此消彼长、逐词音译成本高、整句统一口音不可细控、俄最顺日次之德中需人耳抽验。
硬件：Higgs 4B 建议 8GB+ 显存；无独显可退 CPU 后端但慢很多。Vulkan 后端需驱动支持（AMD/Intel/NVIDIA 均可，本文 AMD 实测）。
批量中断：--request-sequence 遇单条 max_tokens 循环会中断后续全部请求——失败后按缺失清单单条重生成，不要整批重跑（本文 95 条实战踩过，含 ja seed 9004、长喊 Aaaah! 个别 seed、日语省略号遗言三个循环案例）。
个别 seed 玄学：同配方+同文本，个别 seed 会循环/变形，换 seed 即好；多抽几版人工挑。
拟声词必须英文写法：非英语母语拟声词生成的闷哼/尖叫质量差，已实测并全量替换。
非 ASCII 命令行：Windows PowerShell 5.1 走 GBK，俄/德/日/中文文本必须 UTF-8 JSON 文件提交。
BGM 未实测：Stable Audio 3 音乐生成（BGM）与音效同管线，但本文未做音乐侧质检，效果需自行验证。
咆哮天花板（2026-08-07 实测）：Higgs 无法生成真·持续破音长吼（长元音必循环 bug），单段连续生成极限 ≈2.8s。产出最佳组合（人耳评分）：①截断法（总冠军 9/10）：长元音文本（如 12 个 お）+ max_tokens 80 硬截断循环源（2.4s，"音更高、降音点靠后"；mt64/160 亦可用；必须单发 CLI——放 request-sequence 批量会硬失败中断整批；截断落点=循环相位，出条后跑 loop_check）；②自然收尾（8/10）：10 元音 + mt2048 + 非循环 seed（2.76s，找 seed 抽签即可）；③生成侧（游戏可用）：高音域粗粝男参考 + 全标签 + speed_slow + 辅音起头词（GRRRR/突撃）。--speaking-rate CLI 参数对 Higgs 无效。更长只能后期拼接/慢放（en 可用）/混响尾音。
人工听感验收不可省：QA 工具把关"循环/杂音/时长/性别粗筛"，审美与角色感仍需人耳（或与目标音频 A/B 对比）确认。
模型许可：audio.cpp 与各模型有各自开源许可，商用前请核对所用模型的具体许可证；生成内容版权与模型训练数据风险按平台政策自担。

来源与致谢

工具链：audio.cpp（ggml 本地音频推理框架，作者 0xShug0，仓库 https://github.com/0xShug0/audio.cpp ，README 声明开源）；模型 GGUF 包来自 HuggingFace audio-cpp/audio.cpp-gguf（国内可换 hf-mirror.com）。
模型：Qwen3-TTS（阿里巴巴）、Higgs Audio v3（Boson AI，HF bosonai/higgs-tts-3-4b）、Stable Audio 3（Stability AI），均经 audio.cpp 本地运行。
工作流与配方：本文为作者在 2026-08-06 实战（95 条多语言人声 + 24 类音效全流程）及 2026-08-07 第九轮修订（300+ 条性别漂移专项测试与多轮复验：配方对比、参数网格、极限强度、长吼技巧、口音探索，全部人耳听判）中整理的第一手经验：原创配方（无 anger×fear 强度标签组合实测对比、英文拟声词铁律、批量中断与 seed 循环避坑、性别漂移根因定位与分场景使用规则、截断法/音译 hack），可自由分享；引用他人内容时请保留以上署名。

平台通知

本地 AI 游戏配音/音效全流程工作流（audio.cpp 版）