切换音色与语速

音色集合

Kokoro INT8 模型包内置 103 个音色。每个音色有 id、在 voices.bin 中的索引、 语言与标签：

前缀	语言	示例 id
zf_	中文女声	zf_001、zf_002……
zm_	中文男声	zm_009……
af_	美式英文女声	af_maple、af_sol
bf_	英式英文女声	bf_vale

音色条目遵循 KokoroVoiceManifest 结构：

interface KokoroVoiceManifest {
  id: string; // "zf_001"
  index: number; // 在 voices.bin 中的位置
  language: "en" | "zh";
  label: string; // 可读标签
}

只有 Recommended 音色经过认证

在模型 manifest 中，音色被标记为 recommended 或 experimental。只有 recommended 音色通过了 Beta 语料。已认证的集合是 zf_001、zm_009、 af_maple、af_sol、bf_vale —— 其余均为 Experimental。中文的韵律与标点停顿 在不同音色间差异明显，上线前请用你自己的内容评估其他音色。

切换音色

在每次请求里传 voiceId：

const tts = createTts({
  model: kokoroZhInt8,
  voiceId: "zf_001",
  numThreads: 4,
});
await tts.load();

const chinese = await tts.synthesizeToFile({ text: "你好。" });
const english = await tts.synthesizeToFile({
  text: "Hello.",
  voiceId: "af_maple",
});

切换音色不会重载模型。ONNX session 只创建一次；不同的 voiceId 只是在本次 合成中从 voices.bin 里选取不同的 style embedding。切换的代价很低。

如果想改变默认音色，直接在创建时指定即可：

const tts = createTts({ model: kokoroZhInt8, voiceId: "af_maple" });

语速

speed 是生成音频的倍率，有效范围 0.5 到 2.0：

await tts.synthesizeToFile({ text: "慢一点。", speed: 0.8 });
await tts.synthesizeToFile({ text: "Faster now.", speed: 1.4 });

超出范围的值会在推理开始前被拒绝。

语速是硬性范围，不是建议值

0.5 与 2.0 是两端极值。超出范围 SDK 会抛错而不是静默截断，因此任何面向用户的 语速控件都要你自己做校验。

调优线程数

numThreads 映射到 ONNX Runtime 的 intra-op 线程数：

const tts = createTts({
  model: kokoroZhInt8,
  voiceId: "zf_001",
  numThreads: 4,
});

线程不是越多越好 —— 在移动端，超额占用核心可能得不偿失。请在目标机型上用 result.elapsedMs（不含模型加载）做基准测试，选最优值。

文本长度限制

限制项	值
单次输入总长	2000 个 Unicode code point
单个候选分段	300 个 code point
模型 token 预算	510（有效负载 508）

SDK 会把长文本切分成多段并拼接生成的音频。超出总长限制会抛 TEXT_TOO_LONG； 某一段无法切到上限以下则抛 TEXT_SEGMENT_TOO_LONG。

中文数字与日期会在编码前自动归一化 —— 2024年5月1日 会按中文读法朗读，而不是 逐位读数字。