Kokoro TTS

一款基于Kokoro模型的命令行文本转语音工具，支持多种语言、多种音色（可混合）以及多种输入格式，包括EPUB电子书和PDF文档。

功能特性

• 多语言与多音色支持
• 支持自定义权重的音色混合
• 支持EPUB、PDF和TXT文件输入
• 支持标准输入（stdin）及与其他程序的管道连接（|）
• 流式音频播放
• 可将输出按章节分割
• 语速可调
• 输出格式支持WAV和MP3
• 具备章节合并功能
• 提供详细的调试输出选项
• GPU加速支持

演示

Kokoro TTS是一款开源的命令行工具，能够直接在终端中实现高质量的文本转语音。它就像你的私人语音工作室，只需简单操作就能将任意文本转换为自然流畅的语音。

https://github.com/user-attachments/assets/8413e640-59e9-490e-861d-49187e967526

演示音频（MP3） | 演示音频（WAV）

待办事项

• 添加GPU支持
• 添加PDF支持
• 添加GUI界面

系统要求

• Python 3.11–3.12（目前不支持Python 3.13及以上版本）

安装方法

方法1：从PyPI安装（推荐）

安装Kokoro TTS最简单的方式是从PyPI获取：

# 使用uv（推荐）
uv tool install kokoro-tts

# 使用pip
pip install kokoro-tts

安装完成后，您可以运行：

kokoro-tts --help

方法2：从Git仓库安装

直接从代码仓库安装：

# 使用uv（推荐）
uv tool install git+https://github.com/nazdridoy/kokoro-tts

# 使用pip
pip install git+https://github.com/nazdridoy/kokoro-tts

方法3：克隆并本地安装

1. 克隆仓库：

git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts

2. 安装软件包：

使用uv（推荐）：

uv venv
uv pip install -e .

使用pip：

python -m venv .venv
source .venv/bin/activate  # Windows系统下：.venv\Scripts\activate
pip install -e .

3. 运行工具：

# 如果使用uv
uv run kokoro-tts --help

# 如果使用pip并激活了虚拟环境
kokoro-tts --help

方法4：无需安装直接运行

如果您希望不进行安装而直接运行：

1. 克隆仓库：

git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts

2. 仅安装依赖项：

使用uv：

uv venv
uv sync

使用pip：

python -m venv .venv
source .venv/bin/activate  # Windows系统下：.venv\Scripts\activate
pip install -r requirements.txt

3. 直接运行：

# 使用uv
uv run -m kokoro_tts --help

# 使用pip（已激活虚拟环境）
python -m kokoro_tts --help

下载模型文件

安装完成后，请将所需的模型文件下载到工作目录中：

# 下载音色数据（推荐使用bin格式）
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

# 下载模型
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx

脚本需要voices-v1.0.bin和kokoro-v1.0.onnx文件位于您运行kokoro-tts命令的同一目录下。

支持的音色：

类别	音色	语言代码
🇺🇸 👩	af_alloy, af_aoede, af_bella, af_heart, af_jessica, af_kore, af_nicole, af_nova, af_river, af_sarah, af_sky	en-us
🇺🇸 👨	am_adam, am_echo, am_eric, am_fenrir, am_liam, am_michael, am_onyx, am_puck	en-us
🇬🇧	bf_alice, bf_emma, bf_isabella, bf_lily, bm_daniel, bm_fable, bm_george, bm_lewis	en-gb
🇫🇷	ff_siwis	fr-fr
🇮🇹	if_sara, im_nicola	it
🇯🇵	jf_alpha, jf_gongitsune, jf_nezumi, jf_tebukuro, jm_kumo	ja
🇨🇳	zf_xiaobei, zf_xiaoni, zf_xiaoxiao, zf_xiaoyi, zm_yunjian, zm_yunxi, zm_yunxia, zm_yunyang	cmn

使用方法

基本用法

kokoro-tts <输入文本文件> [<输出音频文件>] [选项]

[!注意]

• 如果您通过方法1（PyPI）或方法2（Git安装）安装，请直接使用kokoro-tts
• 如果您通过方法3（本地安装）安装，请使用uv run kokoro-tts，或者先激活您的虚拟环境
• 如果您使用方法4（无需安装），请使用uv run -m kokoro_tts或python -m kokoro_tts，并确保已激活虚拟环境

命令

• -h, --help: 显示帮助信息
• --help-languages: 列出支持的语言
• --help-voices: 列出可用的音色
• --merge-chunks: 将现有分段合并为章节文件

选项

• --stream: 流式播放音频，而非保存为文件
• --speed <浮点数>: 设置语速（默认值：1.0）
• --lang <字符串>: 设置语言（默认值：en-us）
• --voice <字符串>: 设置单一音色或混合音色（默认为交互式选择）
  • 单一音色：使用音色名称（如“af_sarah”）
  • 混合音色：使用“音色1:权重,音色2:权重”格式
• --split-output <目录>: 将每个分段分别保存到指定目录
• --format <字符串>: 音频格式：wav或mp3（默认为wav）
• --debug: 在处理过程中显示详细的调试信息

输入格式

• .txt: 文本文件输入
• .epub: EPUB电子书输入（会按章节处理）
• .pdf: PDF文档输入（从目录或内容中提取章节）
• - 或 /dev/stdin（Linux/macOS）或 CONIN$（Windows）: 标准输入（stdin）

示例

# 基本用法，生成输出文件
kokoro-tts input.txt output.wav --speed 1.2 --lang en-us --voice af_sarah

# 从标准输入读取
echo "Hello World" | kokoro-tts - --stream
cat input.txt | kokoro-tts - output.wav

# 跨平台标准输入支持：
# Linux/macOS：echo "text" | kokoro-tts - --stream
# Windows：echo "text" | kokoro-tts - --stream
# 所有平台还支持：kokoro-tts /dev/stdin --stream（Linux/macOS）或 kokoro-tts CONIN$ --stream（Windows）

# 使用音色混合（60-40比例）
kokoro-tts input.txt output.wav --voice "af_sarah:60,am_adam:40"

# 使用等比例音色混合（50-50）
kokoro-tts input.txt --stream --voice "am_adam,af_sarah"

# 处理EPUB并按章节分割
kokoro-tts input.epub --split-output ./chunks/ --format mp3

# 直接流式播放音频
kokoro-tts input.txt --stream --speed 0.8

# 合并现有分段
kokoro-tts --merge-chunks --split-output ./chunks/ --format wav

# 处理EPUB并显示详细调试信息
kokoro-tts input.epub --split-output ./chunks/ --debug

# 处理PDF并按章节分割
kokoro-tts input.pdf --split-output ./chunks/ --format mp3

# 列出所有可用音色
kokoro-tts --help-voices

# 列出支持的语言
kokoro-tts --help-languages

[!提示] 如果您使用的是方法 3，请将上述示例中的 kokoro-tts 替换为 uv run kokoro-tts。 如果您使用的是方法 4，请将上述示例中的 kokoro-tts 替换为 uv run -m kokoro_tts 或 python -m kokoro_tts。

功能详解

EPUB 处理

• 自动从 EPUB 文件中提取章节
• 保留章节标题和结构
• 为每个章节创建有序的输出
• 提供详细的调试输出以方便故障排除

音频处理

• 将长文本分割成易于管理的片段
• 支持流式传输以便即时播放
• 可自定义混合比例的语音融合
• 长时间处理过程中的进度指示器
• 能够优雅地处理中断情况

输出选项

• 单文件输出
• 按章节组织的拆分输出
• 片段合并功能
• 支持多种音频格式

调试模式

• 显示文件处理的详细信息
• 展示 EPUB 文件的 NCX 解析详情
• 列出所有找到的章节及其元数据
• 帮助排查处理过程中出现的问题

输入选项

• 文本文件输入 (.txt)
• EPUB 书籍输入 (.epub)
• 标准输入 (stdin)
• 支持从其他程序进行管道输入

贡献

这是一个个人项目。但如果您想贡献代码，欢迎提交 Pull Request。

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

致谢

• Kokoro-ONNX

Kokoro TTS 快速上手指南

Kokoro TTS 是一款基于命令行的高品质文本转语音（TTS）工具，支持多语言、多音色混合、EPUB/PDF 文档处理及流式播放。

环境准备

• 操作系统：Windows / macOS / Linux
• Python 版本：3.11 或 3.12（不支持 Python 3.13+）
• 依赖管理：推荐使用 uv（速度更快），也可使用 pip
• 模型文件：运行前需手动下载模型和音色数据（见安装步骤）

安装步骤

1. 安装工具

推荐使用 uv 进行安装（若未安装 uv，可先运行 curl -LsSf https://astral.sh/uv/install.sh | sh 或使用 pip）。

方式 A：从 PyPI 安装（推荐）

# 使用 uv
uv tool install kokoro-tts

# 或使用 pip
pip install kokoro-tts

方式 B：从源码安装

git clone https://github.com/nazdridoy/kokoro-tts.git
cd kokoro-tts

# 使用 uv (推荐)
uv venv
uv pip install -e .

# 或使用 pip
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

2. 下载模型文件

工具安装完成后，必须在当前工作目录下下载以下两个文件才能运行：

# 下载音色数据 (推荐 bin 格式)
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/voices-v1.0.bin

# 下载模型文件
wget https://github.com/nazdridoy/kokoro-tts/releases/download/v1.0.0/kokoro-v1.0.onnx

注意：如果无法访问 GitHub Releases，请确保网络通畅或使用代理加速。这两个文件必须与运行命令的目录一致。

基本使用

查看帮助与支持列表

# 查看帮助
kokoro-tts --help

# 列出支持的音色
kokoro-tts --help-voices

# 列出支持的语言
kokoro-tts --help-languages

最简单的使用示例

将文本文件转换为音频：

kokoro-tts input.txt output.wav

指定音色、语速并直接流式播放（不保存文件）：

echo "你好，世界" | kokoro-tts - --stream --lang cmn --voice zf_xiaoxiao

处理 EPUB 电子书并分割章节输出：

kokoro-tts book.epub --split-output ./chapters/ --format mp3

常用参数说明

• --voice <name>: 指定音色（如 af_sarah），支持混合音色（如 "af_sarah:60,am_adam:40"）。
• --lang <code>: 指定语言代码（中文为 cmn，默认 en-us）。
• --speed <float>: 调整语速（默认 1.0）。
• --stream: 实时流式播放音频。
• --split-output <dir>: 将长文本按章节分割保存到指定目录。
• --format: 输出格式，支持 wav 或 mp3。

提示：如果你是通过源码本地安装（方式 B），请在上述命令前加上 uv run 或激活虚拟环境后运行。