README.md

---
title: GENIE TTS
emoji: 🔮
colorFrom: pink
colorTo: gray
sdk: gradio
sdk_version: 5.46.0
app_file: app.py
pinned: false
license: apache-2.0
short_description: High-quality Japanese TTS based on Genie (GPT-SoVITS V2)
---

# 🔮 Genie TTS - Hugging Face Spaces Deployment

基于 [High-Logic/Genie](https://github.com/High-Logic/Genie) 的官方 TTS 引擎，提供高质量日语语音合成服务。

## ✨ 功能特点

- 🚀 **高性能推理**：基于 ONNX Runtime 的 CPU 优化推理
- 🎯 **即开即用**：内置 misono_mika 预定义角色，无需额外模型
- 📱 **Web 界面**：响应式 Gradio 界面，支持音频实时播放
- 🔧 **官方对齐**：配置与上游官方项目完全一致
- 💾 **智能缓存**：自动模型缓存，提升后续使用体验

## ⚠️ 部署状态

> **Hugging Face Spaces 环境限制**
> 
> 由于 Hugging Face Spaces 环境缺少 `portaudio19-dev` 系统依赖，PyAudio 编译可能失败，导致 genie-tts 安装失败。我们已添加了：
> 
> - ✅ `packages.txt` 文件尝试安装系统依赖
> - ✅ 智能错误处理和状态显示  
> - ✅ 运行时安装策略（`--no-deps` 模式）
> - ✅ 详细的故障诊断信息
> 
> 🔧 **推荐解决方案:**
> 1. **本地运行**：在本地环境可完整安装所有依赖
> 2. **Docker 部署**：使用官方 Docker 配置
> 3. **其他云平台**：支持系统依赖安装的平台

## 🏗️ 技术架构

```
用户输入 → Gradio界面 → Genie TTS引擎 → ONNX推理 → 音频输出
    ↓             ↓              ↓           ↓          ↓
   文本预处理    参数验证      模型加载    语音合成    Web播放
```

### 核心组件

- **TTS Engine**: Genie TTS v1.0+ (官方包)
- **Model Runtime**: ONNX Runtime 1.16+  
- **Audio Processing**: SoundFile + SoXR
- **Web Interface**: Gradio 4.0+
- **Text Processing**: PyOpenJTalk (日语支持)

## 🚀 快速开始

### 本地开发

```bash
# 1. 克隆仓库
git clone <repository-url>
cd genie-tts-deployment

# 2. 安装依赖
pip install -r requirements.txt

# 3. 启动应用
python app.py
```

### Hugging Face Spaces 部署

1. **Fork 仓库** 到您的 GitHub 账户
2. **创建 Space**：
   - 访问 [Hugging Face Spaces](https://huggingface.co/spaces)
   - 选择 "Create new Space"
   - 选择 "Gradio" SDK
   - 连接 GitHub 仓库
3. **自动部署**：推送代码后自动构建部署

## 📋 依赖说明

### 核心依赖（基于官方配置）

```txt
# 官方 TTS 引擎
genie-tts>=1.0.0

# Web 界面框架  
gradio>=4.0.0

# 机器学习推理
onnxruntime>=1.16.0

# 音频处理（官方核心依赖）
soundfile>=0.12.0    # 音频文件读写
soxr>=0.3.0          # 高质量音频重采样  
librosa>=0.10.0      # 音频分析
scipy>=1.9.0         # 科学计算

# 日语文本处理
pyopenjtalk          # 日语分词和读音

# 模型下载
huggingface-hub>=0.17.0

# 系统工具
rich>=12.0.0         # 美化日志输出
requests>=2.25.0     # 网络请求
psutil>=5.8.0        # 系统信息
```

### 兼容性说明

- **PyAudio 处理**：移除以避免 HF Spaces 编译错误
- **音频播放**：通过 Web 界面实现，无需本地音频设备
- **Python 版本**：支持 3.9+（与官方一致）

## 🎮 使用指南

### 基础用法

1. **选择角色**：当前支持 `misono_mika`
2. **输入文本**：支持日语文本（建议500字符以内）
3. **点击合成**：等待处理完成
4. **播放音频**：直接在浏览器中播放

### 示例文本

```
どうしようかな……やっぱりやりたいかも……！
私も昔、これと似たようなの持ってたなぁ…。
おはようございます！今日もよろしくお願いします。
```

## 🔧 技术细节

### 模型信息

- **架构**：GPT-SoVITS V2
- **语言支持**：日语
- **采样率**：32kHz
- **推理引擎**：ONNX Runtime (CPU)
- **模型大小**：约180MB

### 性能优化

- **内存管理**：自动垃圾回收
- **缓存策略**：智能模型缓存
- **错误处理**：完善的异常捕获
- **资源限制**：文本长度限制

## 📚 参考资料

- [官方项目](https://github.com/High-Logic/Genie)
- [官方文档](https://github.com/High-Logic/Genie/tree/main/README.md)
- [API 教程](https://github.com/High-Logic/Genie/tree/main/Tutorial)
- [配置对齐说明](./OFFICIAL_ALIGNMENT.md)

## 📄 许可证

本项目基于 Apache-2.0 许可证开源，详情请见 [LICENSE](./LICENSE) 文件。

---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference