# KokoroTTS-Python

**Repository Path**: yan6818/kokoro-tts-python

## Basic Information

- **Project Name**: KokoroTTS-Python
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-05
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Kokoro TTS - 企业级语音合成应用

基于 [Kokoro](https://github.com/hexgrad/kokoro) 的中文 TTS 应用，提供 GUI 界面和 API 服务。

## ✨ 特性

- 🎯 **企业级架构**：模块化设计，易于维护和扩展
- 🖥️ **图形界面**：直观的 GUI，支持实时语音合成
- 🌐 **API 服务**：RESTful API，支持远程调用
- 📦 **一键打包**：支持 PyInstaller 和 Inno Setup 打包
- 🎤 **多种语音**：支持 8 种中文语音（4 女 4 男）
- ⚡ **轻量快速**：82M 参数模型，推理速度快

## 📋 环境要求

- **Python**: 3.10 - 3.12（推荐 3.11）
- **操作系统**: Windows 10/11, Linux, macOS
- **内存**: 建议 4GB 以上
- **GPU**: 可选（CPU 也可运行）

## 🚀 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/yourusername/kokoro-tts.git
cd kokoro-tts
```

### 2. 创建虚拟环境（推荐）

```bash
# 使用 conda
conda create -n kokoro python=3.11
conda activate kokoro

# 或使用 venv
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Linux/macOS
```

### 3. 安装依赖

```bash
# 生产依赖
pip install -r requirements.txt

# 开发依赖（可选）
pip install -r requirements-dev.txt
```

### 4. 下载模型

首次使用会自动下载模型，或手动下载：

```bash
python scripts/download_model.py
```

### 5. 运行程序

#### 方式一：GUI 界面（推荐）

```bash
# 方法 1: 使用模块方式
python -m kokoro_tts gui

# 方法 2: 使用入口点（安装后）
kokoro-gui
```

#### 方式二：API 服务

```bash
# 方法 1: 使用模块方式
python -m kokoro_tts api --port 8000

# 方法 2: 使用入口点
kokoro-api --host 127.0.0.1 --port 8000
```

#### 方式三：命令行模式

```bash
python -m kokoro_tts cli "你好，欢迎使用 Kokoro TTS"
```

## 📁 项目结构

```
KokoroTTS/
├── src/kokoro_tts/          # 源代码
│   ├── core/                 # 核心功能
│   ├── gui/                  # GUI 界面
│   ├── api/                  # API 服务
│   ├── utils/                # 工具函数
│   └── config/               # 配置文件
├── tests/                    # 测试
├── resources/                # 资源文件
│   ├── models/               # 模型文件
│   ├── voices/               # 语音文件
│   └── icons/                # 图标
├── docs/                     # 文档
├── scripts/                  # 脚本工具
├── build/                    # 打包配置
├── dist/                     # 打包输出
└── vendor/                   # 第三方依赖
```

## 🎤 可用语音

### 女声

| ID | 名称 | 说明 |
|------|------|------|
| zf_xiaobei | 小北 | 温柔女声 |
| zf_xiaoni | 小妮 | 甜美女声 |
| zf_xiaoxiao | 小小 | 清脆女声 |
| zf_xiaoyi | 小艺 | 成熟女声 |

### 男声

| ID | 名称 | 说明 |
|------|------|------|
| zm_yunjian | 云健 | 稳重男声 |
| zm_yunxi | 云希 | 磁性男声 |
| zm_yunxia | 云夏 | 阳光男声 |
| zm_yunyang | 云阳 | 深沉男声 |

## 💻 API 使用说明

### 启动 API 服务

```bash
python -m kokoro_tts api --port 8000
```

### API 文档

访问 `http://localhost:8000/docs` 查看 Swagger UI 文档

### 接口示例

#### 1. 获取服务状态

```bash
curl http://localhost:8000/
```

#### 2. 获取可用语音

```bash
curl http://localhost:8000/voices
```

#### 3. 文本转语音

```bash
curl -X POST http://localhost:8000/tts \
  -H "Content-Type: application/json" \
  -d '{
    "text": "你好，欢迎使用 Kokoro TTS",
    "voice": "zf_xiaobei",
    "speed": 1.0
  }' \
  --output output.wav
```

### Python 调用示例

```python
import requests

url = "http://localhost:8000/tts"
data = {
    "text": "你好，欢迎使用 Kokoro TTS",
    "voice": "zf_xiaobei",
    "speed": 1.0
}

response = requests.post(url, json=data)
if response.status_code == 200:
    with open("output.wav", "wb") as f:
        f.write(response.content)
    print("音频保存成功！")
```

## 📦 打包发布

### 使用 PyInstaller 打包

```bash
# 安装打包依赖
pip install pyinstaller

# 打包 GUI 版本
pyinstaller build/pyinstaller/kokoro_tts.spec

# 输出在 dist/ 目录
```

### 使用 Inno Setup 制作安装包

1. 先使用 PyInstaller 打包
2. 打开 `build/innosetup/setup.iss`
3. 使用 Inno Setup Compiler 编译
4. 生成 `KokoroTTS_Setup.exe`

## ⚙️ 配置说明

配置文件位于 `src/kokoro_tts/config/default.yaml`

### 常用配置

```yaml
# 模型配置
model:
  repo_id: "hexgrad/Kokoro-82M-v1.1-zh"
  lang_code: "z"

# TTS 配置
tts:
  default_voice: "zf_xiaobei"
  default_speed: 1.0

# API 配置
api:
  host: "127.0.0.1"
  port: 8000
```

## 🧪 开发指南

### 运行测试

```bash
pytest tests/ -v
```

### 代码格式化

```bash
black src/ tests/
isort src/ tests/
```

### 类型检查

```bash
mypy src/
```

## ❓ 常见问题

### Q: Python 3.13 出现兼容性问题？

**A**: 请使用 Python 3.11 或 3.12

```bash
conda create -n kokoro python=3.11
conda activate kokoro
```

### Q: 下载模型速度慢？

**A**: 配置 Hugging Face 镜像

```bash
export HF_ENDPOINT=https://hf-mirror.com  # Linux/macOS
set HF_ENDPOINT=https://hf-mirror.com     # Windows
```

### Q: 如何自定义语音？

**A**: 将语音文件放入 `resources/voices/` 目录，并在 `default.yaml` 中配置

## 📚 相关链接

- [Kokoro GitHub](https://github.com/hexgrad/kokoro)
- [Kokoro-82M-v1.1-zh (HF)](https://huggingface.co/hexgrad/Kokoro-82M-v1.1-zh)
- [FastAPI 文档](https://fastapi.tiangolo.com/)

## 📄 许可证

- Kokoro 代码: Apache 2.0
- Kokoro-82M 模型权重: Apache 2.0
- 本项目代码: Apache 2.0

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📧 联系方式

- 问题反馈：[GitHub Issues](https://gitee.com/yan6818/kokoro-tts-python/issues)
- 邮件联系：184773349@qq.com