python/README.md

# Python SDK

## 环境安装

```bash
pip install -r requirements.txt
```

依赖：`torch`、`transformers==4.57.1`、`sentencepiece`、`numpy`、`onnxruntime`、
`soundfile`；AX650 板上另需 `pyaxengine`。

## 快速使用

```python
from moss_tts_sdk import MossTTSNano

tts = MossTTSNano("models")                      # provider 默认 auto
result = tts.synthesize("你好，欢迎使用模思智能。", "out.wav")
print(result["duration_s"], "秒")
```

## 命令行

```bash
python demo.py --text "今天天气真好。" --out out.wav
python demo.py --provider axengine --text "中文优先" --out out.wav
```

## API

### MossTTSNano(model_dir, provider="auto", device="cpu")

- `model_dir`：包内 `models/` 目录
- `provider`：`auto`（有 axmodel 且装 pyaxengine 时用 NPU，否则 onnxruntime）| `axengine` | `onnxruntime`

### synthesize(text, output_path, max_new_frames=375, seed=42, do_sample=True)

返回 `dict`：

- `audio_path`：输出 wav 路径
- `sample_rate`：48000
- `channels`：2
- `frames`：音频 token 帧数（12.5 帧/秒）
- `duration_s`：音频时长（秒）
- `provider`：实际解码后端（axengine / onnxruntime）

## 预处理说明

1. 中文文本按标点自动分句，逐句生成
2. 每句按官方 voice-clone 模板拼接文本与参考音频 token（内置 `zh_1.wav` 音色）
3. LLM 自回归生成 16 个 codebook 的音频 token（12.5 Hz）
4. CPU 查表得到 code 嵌入，送入 codec 解码器（NPU AXMODEL 或 ONNX）
5. 输出 48kHz 双声道波形，clamp 到 [-1,1] 后写 int16 WAV

## 数值稳定性说明

LLM 在 x86 高负载环境下偶发 fp32 denormal 导致的 NaN，SDK 已内置四重防护：
固定线程数、`torch.set_flush_denormal(True)`、-1e9 注意力掩码、换种子自动重试。
AX650 板端（aarch64）不受影响。