OFFICIAL_ALIGNMENT.md

# 官方配置对齐说明

## 📋 概述

本部署配置基于 [High-Logic/Genie](https://github.com/High-Logic/Genie) 官方仓库进行对齐，确保与上游项目保持一致性。

## 🔍 官方仓库分析

### Docker 配置分析

从官方 `Docker/Dockerfile` 发现：
```dockerfile
# Use official Python image
FROM python:3.12-slim

# Install system dependencies needed by PyAudio
RUN apt-get update && apt-get install -y \
    portaudio19-dev \
    python3-dev \
    build-essential \
 && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir -r requirements.txt
```

### 核心依赖

从官方源码分析得出的核心依赖：
- `genie-tts`: 官方包
- `soundfile`: 音频文件读写
- `soxr`: 高质量音频重采样
- `onnxruntime`: ONNX 模型推理
- `huggingface_hub`: 模型下载
- `rich`: 日志输出
- `pyopenjtalk`: 日语文本处理

### API 使用方式

官方 API 调用方式：
```python
import genie_tts as genie

# 1. 加载预定义角色
genie.load_predefined_character('misono_mika')

# 2. TTS 合成
genie.tts(
    character_name='misono_mika',
    text='どうしようかな……やっぱりやりたいかも……！',
    play=True,
    split_sentence=True,
    save_path="output.wav"
)
```

### 环境变量配置

官方推荐的环境变量：
```python
# HuBERT 模型路径（可选）
os.environ['HUBERT_MODEL_PATH'] = r"C:\path\to\chinese-hubert-base.onnx"

# Open JTalk 字典路径（可选）
os.environ['OPEN_JTALK_DICT_DIR'] = r"C:\path\to\open_jtalk_dic_utf_8-1.11"

# 缓存配置（可选）
os.environ['Max_Cached_Character_Models'] = '3'
os.environ['Max_Cached_Reference_Audio'] = '10'
```

## 🔄 我们的对齐方案

### 1. 依赖配置对齐

**更新前（问题）：**
- 包含了非必需的 `torch`, `torchaudio`
- 缺少 `soxr` 高质量音频处理库
- 缺少官方核心包 `genie-tts`

**更新后（对齐）：**
```txt
# 核心TTS引擎 - 官方Genie包
genie-tts>=1.0.0

# 音频处理库（来自官方源码）
soundfile>=0.12.0
soxr>=0.3.0
scipy>=1.9.0
librosa>=0.10.0

# ONNX运行时（与官方对齐）
onnxruntime>=1.16.0

# 日语文本处理（官方要求）
pyopenjtalk

# 日志输出（与官方对齐）
rich>=12.0.0
```

### 2. API 调用对齐

**更新前：**
- 复杂的模型管理逻辑
- 自定义缓存处理

**更新后：**
```python
# 直接使用官方API
genie.load_predefined_character(character_name)
genie.tts(
    character_name=character_name,
    text=processed_text,
    play=False,
    split_sentence=True,
    save_path=output_path
)
```

### 3. 环境变量对齐

```python
# 基于官方文档设置环境变量
os.environ["HF_HUB_ENABLE_PROGRESS_BAR"] = "1"
os.environ["TOKENIZERS_PARALLELISM"] = "false"

# 可选的官方配置（注释形式）
# os.environ['HUBERT_MODEL_PATH'] = r"path/to/chinese-hubert-base.onnx"
# os.environ['OPEN_JTALK_DICT_DIR'] = r"path/to/open_jtalk_dic_utf_8-1.11"
# os.environ['Max_Cached_Character_Models'] = '3'
# os.environ['Max_Cached_Reference_Audio'] = '10'
```

## 🚀 PyAudio 问题解决

### 官方 Docker 处理方式

官方 Docker 通过系统级依赖解决：
```dockerfile
RUN apt-get install -y portaudio19-dev python3-dev build-essential
```

### Hugging Face Spaces 适配

由于 HF Spaces 限制，我们采用：
1. **移除 PyAudio**：避免编译错误
2. **Web 音频播放**：通过 Gradio 界面播放
3. **备注说明**：清楚标注处理方式

```txt
# Note: PyAudio is excluded for Hugging Face Spaces compatibility
# Audio playback is handled via web interface instead of local system audio
```

## ✅ 验证清单

- [x] 使用官方 `genie-tts` 包
- [x] 包含所有官方核心依赖（soundfile, soxr, onnxruntime）
- [x] API 调用方式与官方一致
- [x] 环境变量设置参考官方文档
- [x] 错误处理机制完善
- [x] 文档说明完整

## 🔗 参考资料

- [Official GitHub Repository](https://github.com/High-Logic/Genie)
- [Official Documentation](https://github.com/High-Logic/Genie/tree/main/README.md)
- [Docker Configuration](https://github.com/High-Logic/Genie/tree/main/Docker)
- [API Tutorial](https://github.com/High-Logic/Genie/tree/main/Tutorial)
- [Official Examples](https://github.com/High-Logic/Genie/tree/main/Tutorial/English)