mcpField
K
kokoro-tts

kokoro-tts

github.com/calesthio创意与媒体219123 次安装15 周前更新
代码仓库

关于 kokoro-tts

用于评估和运行 Kokoro 自托管文本转语音模型的技能，涵盖 Python、JavaScript/ONNX 和本地服务器运行方式。内容包括声音与发音选择、长文本处理，以及不适合使用 Kokoro 的场景。

主要功能

  1. 01选择声音并混合音色风格
  2. 02拆分长文本并检查输出
  3. 03通过音素覆盖纠正发音
  4. 04选择 Python、ONNX 或服务器运行方式
  5. 05评估适用性与局限

适用场景

  1. 01生成私密的离线旁白
  2. 02批量制作长篇音频
  3. 03在浏览器或设备端运行语音合成
  4. 04大批量生成前测试发音

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/calesthio/generative-media-skills --skill kokoro-tts

安装后在 Claude Code 中输入/kokoro-tts确认已加载。

附带文件EVAL.md

详细介绍

Kokoro TTS（开放权重，可自托管）

Kokoro 是一款小巧、快速、采用宽松许可证的文本转语音模型。它的核心优势在于由你自行运行：无需 API 密钥，无需按字符付费，音频也不会离开你的设备。本技能可帮助 Agent 判断 Kokoro 是否适合某项任务、选择合适的运行时来运行它，并获得可接受的输出；同样重要的是，识别哪些任务会让用户对 Kokoro 失望，以及在这些情况下应该选择其他方案。

以下所有关于版本、许可证、语音数量、排名和性能的事实，均已于 2026-07-10 根据文末所列来源核实。请注意，这些信息可能会变化。

Kokoro 是什么（已记录的事实）

  • 模型。 约 8200 万个参数。其架构采用 StyleTTS 2（arXiv 2306.07691）和 ISTFTNet 解码器（arXiv 2203.02395）。模型卡将其描述为“仅解码器：没有扩散模型，也没有发布编码器”。来源：hexgrad/Kokoro-82M 模型卡。
  • 许可证。 Apache 2.0，权重也适用此许可证。v0.19 权重于 2024-12-25 以完整 fp32 形式发布；v1.0 于 2025-01-27 发布，目前为默认版本。由于权重采用 Apache-2.0 许可证，你可以将其用于商业部署、再分发和微调（须注明出处）。来源：模型卡。
  • 训练数据与来源。 v1.0 使用“数百小时”数据训练，仅使用宽松许可或不受版权保护的材料：公有领域音频、采用 Apache/MIT 许可的内容，以及由闭源 TTS 模型生成的合成音频；此外还使用了来自 Koniwa（CC BY 3.0）的不足 1 小时数据，以及来自 SIWIS（CC BY 4.0）的不足 11 小时数据。报告的训练成本约为 1000 美元（约 1000 个 A100-80GB GPU 小时）。对合成数据的高度依赖是 Kokoro 韵律平淡、非英语质量参差不齐的根本原因。请牢记这一点。来源：模型卡。
  • 输出。 24 kHz 单声道音频。采样率固定为 24000 Hz。来源：模型卡。
  • 覆盖范围。 v1.0 支持 8 种语言和 54 种语音（美式英语和英式英语合计为一种语言）。来源：模型卡，VOICES.md。

什么时候使用 Kokoro，什么时候不使用

以下情况可考虑使用 Kokoro：

  • 你需要免费、高容量的英语旁白（有声读物、课程或视频配音、批量文档转语音、屏幕阅读器）。边际成本只有电费。
  • 工作流需要离线运行或保护隐私——例如医疗、法律、设备端或隔离网络环境——且不能将文本发送到云端 API。
  • 你想在浏览器内或设备端使用 TTS，且不需要服务器（kokoro-js + WebGPU/WASM）。
  • 你正在制作原型，希望立即获得足够好的语音，而无需配置付费服务。

如果任务需要以下能力，请勿使用 Kokoro（并告知用户）：

  • 语音克隆或特定人物的声音。 Kokoro 没有说话人编码器，也不支持零样本克隆。编码器有意未发布。你无法克隆参考语音。请改用支持克隆的服务商。
  • 情绪或角色表演——欢笑、哭泣、喊叫、讽刺、富有变化的表达。Kokoro 没有情绪或风格标记，韵律范围也很窄；输出虽合格，但较为平淡。适合中性旁白，不适合电子游戏角色。
  • 高保真非英语语音或多语言支持。 非英语语音大多仅获 C/D 级，训练数据也很少（见下文质量等级）；有几种语言还会截断较长文本。英语是唯一的一级语言。
  • 需要支持插话并具备个性的实时双向对话式 Agent。 Kokoro 是批量或流式合成器，不是对话语音系统。

如果用户需要语音克隆或富有情感表现力的配音，不要尝试通过混音或提示词技巧来伪造效果——应直接说明限制，并推荐支持克隆或表达力更强的服务商。

语音、语言代码和质量等级

语音 ID 遵循 [langprefix][gender]_[name] 格式，例如，af_heart = 美国女性 “Heart”，bm_george = 英国男性“George”，if_sara = 意大利女性“Sara”。

语言代码（在 Python 中作为 lang_code 传入；别名 en-us→a、en-gb→b）：

codelanguagecodelanguage
a美式英语i意大利语
b英式英语j日语
e西班牙语p巴西葡萄牙语
f法语z中文普通话
h印地语

来源：VOICES.md。

质量并不一致——应按等级而不是名称挑选。 VOICES.md 为每种语音指定一个“Overall”等级，该等级综合了目标质量字母等级和训练音频量（音频越多，等级越高）。文档中值得关注的语音（已于 2026-07-10 验证）：

  • 最佳英语女性语音： af_heart（A 级，模型卡默认语音）、af_bella（A−）、 af_nicole（B−，气声/ASMR 风格）、bf_emma（B−，英式英语）。
  • 表现稳健的英语语音： af_aoede、af_kore、af_sarah、am_fenrir、am_michael、 am_puck（均为 C+）。bm_fable、bm_george（C 级，英国男性）。
  • 除非有特定理由，否则避免使用： 许多语音为 C 级或更低；例如，am_adam（F+）、 af_jessica / af_river（D）。大多数非英语语音为 C/D 级，训练使用的合成数据仅约几分钟。

生产环境经验法则： 默认使用 af_heart（语言代码 a）。在项目中确定语音前，用户应试听 3–4 种 A/B 级语音——等级可用于预测，但不能保证每句话的质量。

文本长度、分块与长篇合成

文档记载的限制： Kokoro 每次前向传递最多处理 510 个音素化 token （含边界 token 时为 512 个）。VOICES.md 指出，语音在“100–200 个 token 的理想范围内表现最佳”，对非常短的语句（<10–20 个 token）表现较弱，而且长语句（>400 个 token）会读得很急。来源：模型卡 / VOICES.md。

对生产环境的影响：

  • 切勿将整章作为一个字符串输入。应按句子/段落拆分并拼接。
  • Python KPipeline 会自动拆分；其 split_pattern 对英语默认为 r'\n+'，每个分块返回一个 (graphemes, phonemes, audio) 结果，然后将其拼接。来源：pipeline.py。
  • 非英语文本的分块功能尚未完全实现。 除非预先自行拆分（在句子边界插入 \n），否则较长的非英语文本可能会被截断。这是一个常见的静默失败问题——请核实非英语输出的长度。
  • 保证长篇内容清晰的经验法则： 在句子边界处分块，每块约 100–250 个 token（约一至三句话），分别进行合成，并以一小段静音间隔拼接。若要自行构建分割器，Kokoro-FastAPI 的默认值（目标约 175 / 250 / 450 个绝对最大 token）是合理的起点。

发音控制（misaki + espeak-ng）

Kokoro 不会直接读取字素，而是先由 hexgrad 的 G2P 库 misaki 将文本转换为音素，再输入模型。英语使用 misaki 的词典（spaCy + num2words）。词典中没有的单词会回退到 espeak-ng（默认启用的 EspeakFallback）；espeak-ng 也是非英语 G2P 的基础。请将 espeak-ng 安装为系统依赖，否则 OOV 单词会退化为逐字母拼读。文档中的示例：启用回退时，eBook → ˈi bˈʊk；不启用时，→ ˈiː bˈi ˈoʊ ˈoʊ kˈeɪ（逐字母拼读）。来源：misaki README。

修正发音错误的单词（专有名词、品牌、缩写、读错的数字）：

  1. 内联音素覆盖 — misaki 支持类似 Markdown 的语法 [word](/phonemes/)，例如 [Misaki](/misˈɑki/) 或 [Kokoro](/kˈOkəɹO/)。将 IPA/Kokoro 音素放在斜杠之间；重音符号（如 ˈ）很重要。
  2. 生成一次音素，重复使用 — 用 misaki 生成音素，手动修正，然后将音素直接传给模型，以确保批处理作业的发音一致。
  3. 在文本中拼出读音 — 如果音素处理过于繁琐，可改写文本（例如，“A-P-I”“二零二六年”）。

**经验法则：**长批处理开始前，务必先试读领域术语、姓名和数字——这是 Kokoro 最常见的一类错误，而且每个错误都能通过一行音素修正。

声音混合（混音）

Kokoro 的“声音”是一个风格向量（voicepack 张量）。混合是对两个风格向量进行加权平均，从而生成一个可用的新声音。文档中介绍的机制是通过 numpy 加权相加：style1*(w0/100) + style2*(w1/100)；如果权重总和不为 100，则会进行归一化；有些工具将混合数量限制为恰好两个声音。来源：nazdridoy/kokoro-tts 声音混合文档。

  • 在 Kokoro-FastAPI 中，可通过组合声音 ID 请求混合：voice="af_sky+af_bella"（权重相等），也可按该服务的语法指定权重。来源： remsky/Kokoro-FastAPI。
  • 使用 原生 Python 时，可加载两个 voicepack 张量并自行求平均，从而获得完全控制（可使用任意比例；如果自行编写计算代码，就不会受到最多混合两个声音的限制）。

**混合适用于：**微调两个已评定声音之间的音色/音高，或打造一个不同于任何单个内置声音的品牌声音。混合不能增加情绪、根据参考音频创建新的说话人身份，也无法挽救低等级声音——两个 C 级声音平均后仍是 C 级混合声音。

运行时 — 根据部署目标选择

1. Python kokoro 包（服务器/批处理的默认选择）

适合旁白流水线、有声读物，以及任何运行在自有设备上的场景。使用 PyTorch 后端；GPU 可选。示例（标注为示例 — 请按需调整路径/声音）：

# pip install kokoro>=0.9.2 soundfile   ; plus system espeak-ng
from kokoro import KPipeline
import soundfile as sf
import numpy as np

pipeline = KPipeline(lang_code='a')          # 'a' = American English
text = "The quarterly report is ready.\nRevenue rose twelve percent."

chunks = []
for graphemes, phonemes, audio in pipeline(text, voice='af_heart', speed=1.0):
    chunks.append(audio)                     # one result per split (default r'\n+')

sf.write('out.wav', np.concatenate(chunks), 24000)   # 24 kHz mono

采用这种结构的原因：KPipeline 负责 G2P、分块和推理；迭代时会生成每个分块的音频，你可以将它们拼接起来，这正是上述长文本处理模式。speed（约 0.8–1.3）用于在语速和自然度之间进行权衡。如需更底层的控制，可使用 KModel 处理单个已转换为音素的分块。来源：模型卡，Python API。

2. kokoro-js / ONNX（浏览器、设备端、Node）

通过 Transformers.js 完全在客户端运行——无需服务器，也不会上传任何内容。模型 ID 为 onnx-community/Kokoro-82M-v1.0-ONNX。示例（标注为示例）：

// npm i kokoro-js
import { KokoroTTS, TextSplitterStream } from "kokoro-js";

const tts = await KokoroTTS.from_pretrained("onnx-community/Kokoro-82M-v1.0-ONNX", {
  dtype: "q8",        // "fp32" | "fp16" | "q8" | "q4" | "q4f16"
  device: "webgpu",   // "wasm" | "webgpu" in-browser, "cpu" in Node ; use fp32 with webgpu
});

const audio = await tts.generate("Hello from the browser.", { voice: "af_heart" });
audio.save("audio.wav");                 // tts.list_voices() lists all IDs

// Streaming: push tokens, get audio incrementally
const splitter = new TextSplitterStream();
const stream = tts.stream(splitter);
(async () => { for await (const { text, phonemes, audio } of stream) audio.save("chunk.wav"); })();

量化的权衡：q8/q4 可缩小下载体积并提升 WASM 运行速度，但会牺牲一些质量； fp32 质量最高，推荐与 WebGPU 搭配使用。来源： kokoro-js README， onnx-community/Kokoro-82M-v1.0-ONNX。

如需在非 JS 场景中使用 ONNX，kokoro-onnx（Python）可在 onnxruntime（CPU）或 onnxruntime-gpu（CUDA）上运行，适用于 Raspberry Pi / 边缘设备部署。

3. Kokoro-FastAPI（即插即用的 OpenAI 兼容服务）

为现有应用提供本地 TTS 后端的最快方式：使用 Docker 封装的服务，提供 与 OpenAI 兼容的 /v1/audio/speech 端点，因此任何为 OpenAI TTS 编写的客户端 只需更改基础 URL 即可使用。支持混合音色（af_sky+af_bella）、MP3/WAV/Opus/FLAC/M4A/PCM、 流式传输、逐词时间戳、音素端点，以及 CPU/NVIDIA/AMD 镜像。示例 （标注为示例）：

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8880/v1", api_key="not-needed")

client.audio.speech.create(
    model="kokoro", voice="af_heart", input="Local TTS, OpenAI-shaped API.",
    response_format="mp3",
).stream_to_file("out.mp3")

来源：remsky/Kokoro-FastAPI。请注意，这是一个 第三方封装（模型采用 Apache-2.0 许可证，封装为独立项目）——请固定版本，并根据其当前 README 验证端点和混合音色语法，因为它们可能会发生变化。

托管端点。 多个推理平台（例如 Replicate、Baseten 等）都托管了 Kokoro，如果你希望 使用该模型，同时不必自托管；但这会重新引入按使用量计费，并将文本发送到本机之外，因此会削弱选择 Kokoro 的两个主要理由。 建议仅在需要突发容量，或无法在本地运行模型时使用它们。

性能预期（次要、过时的证据）

不同来源对 RTF（实时因子）的定义各不相同——有些报告每计算秒可生成的音频秒数（越高 = 越快）， 另一些则报告其倒数。请留意单位。

  • GPU 的速度比实时快数十倍。一项基准测试（PyTorch，约 16k 个字符， 分块 ≤510 个 token）报告称，A10G 上的 RTF 约为 96×，L4 上约为 81×，T4 上约为 36×；ONNX 的速度 较低（20–37×）。来源：Kokoro v1 benchmark gist，检索于 2026-07-10。
  • CPU 在许多核心上仍能轻松快于实时——同一基准测试显示，32-vCPU 实例上的 RTF 约为 5×；另一项测试报告称，在4 核上 RTF ≈ 0.45–0.51（即比实时快约 2×）。来源：上方的 gist 和一次 4 核 AMD EPYC 运行，检索于 2026-07-10。
  • 占用空间： 82M 参数非常小；模型加载所需内存远低于 1 GB，推理使用 4 GB RAM 即可（若要舒适地进行批处理，则需 8 GB+）。通过 ONNX 可在配置适中的硬件和 Raspberry-Pi 级别设备上运行。

经验法则： 对于实时或流式体验，优先使用 GPU 或性能强劲的多核 CPU； 核心数较少的 CPU/边缘设备适合批处理或离线任务，但处理长文本时可能接近或低于实时速度。 量化 ONNX（q8/q4）有助于在受限的 CPU/WASM 上运行，但会牺牲质量。

基准测试 / 排名情况（过时、证据混杂）

  • 官方说法（2024-12）： 模型卡称 Kokoro v0.19 在发布前后几周内，于 TTS Spaces Arena 中“排名第 1”。这是一个模型有限、单音色的 Arena 环境——对于其体量来说是有力的信号，但并不意味着它胜过所有商用模型。 来源：模型卡。
  • 更广泛的竞技场（2026）： 在更广泛的 TTS 排行榜中，Kokoro 在开放权重模型中处于中游。截至约 2026-03，某个汇总排行榜将 Kokoro-82M v1.0 列为开放权重模型中的第 4 名左右（Elo ≈ 1060），而更新、规模更大的开放模型（例如 Step Audio EditX，Elo ≈ 1118）则排名更高。次要来源，检索于 2026-07-10： TTS Arena / Artificial Analysis。

给用户的诚实说法： 对于仅有 82M 参数且边际成本为 $0 的模型而言，Kokoro 表现出色， 在中性英语旁白方面能与大得多的模型竞争，但在表现力、克隆能力和多语言保真度方面，显然不及前沿商用模型和规模更大的开放模型。应强调其经济性、隐私性和占用空间——而不是声称它拥有最高质量的音色。

输出审核清单

发布 Kokoro 音频前，请留意：

  • 姓名／术语／数字发音错误——最常见的问题。使用音素覆盖来修正。
  • 超过约 400 个 token 的分块语速过快或被截断——重新拆分为更短的分块。
  • 非英语长文本被截断——核实时长；使用 \n 预先拆分。
  • 极短文本行（一两个词）出现瑕疵——补充上下文或在末尾加句点。
  • 语言与语音口音不匹配——将 lang_code 与语音前缀匹配（例如，a／b 开头的语音搭配英语文本）；不匹配时听起来会很别扭。
  • 脚本需要情感表达，但语调平淡——如果读起来不对，解决办法是换一个模型，而不是多次重试。

安全、许可和权利

  • 权重采用 Apache-2.0 许可——允许商业使用、再分发和微调，但需注明出处。请另外核实任何封装项目（例如 Kokoro-FastAPI）的许可；它们是不同的项目。（已于 2026-07-10 核实。）
  • **合成数据来源：**训练使用了来自闭源 TTS 模型的合成音频。相关情况已有记录，发布的数据（Koniwa CC BY 3.0、SIWIS CC BY 4.0）采用宽松许可；但如果客户端对数据来源有严格要求，请予以披露。
  • **不能克隆 ≠ 没有滥用风险。**即使无法克隆，生成的语音也可能被用来模仿某种风格或制作误导性音频。请勿生成模仿真实且可识别人物的音频，也不要生成意图欺骗他人的音频；如果听众有合理理由认为声音来自真人，请披露其为合成语音。
  • 语音是模型产物，而非真人——这些名称（Heart、Emma、George）只是标签，并非同意使用其声音的个人，因此不存在逐位说话人的授权问题；但仍应遵守合成媒体披露的一般规范。

来源（已于 2026-07-10 核实）

评论

支持 Markdown