zipvoice_cpp_server/README.md

# ZipVoice C++ Resident Server

ZipVoice distill TTS 的 C++ 常驻服务及 C API 动态库实现。

本目录包含从 ZipVoice.AXERA 命令行版本提取的推理核心源码，
用于编译常驻 daemon（`zipvoice_axera_server`）和 C API 动态库
（`libzipvoice_axera.so`），供 Python 通过 ctypes 单层常驻调用。

## 文件说明

| 文件 | 说明 |
|------|------|
| `main.cpp` | daemon 入口，stdin/stdout JSON 协议（调试用） |
| `zipvoice_resident_server.hpp/cpp` | 常驻服务核心实现 |
| `zipvoice_c_api.h/cpp` | C API 接口，供 Python ctypes 调用 |
| `CMakeLists.txt` | CMake 构建配置 |

## 依赖

### 1. AX650 BSP SDK

```bash
git clone https://github.com/AXERA-TECH/ax650n_bsp_sdk.git
```

克隆后 `msp/out/` 包含所需的头文件和库文件：

- `libax_sys.so`
- `libax_engine.so`
- `libax_interpreter.so`

### 2. ARM 交叉编译工具链

下载地址：

```text
https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
```

```bash
wget https://developer.arm.com/-/media/Files/downloads/gnu-a/9.2-2019.12/binrel/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
tar xf gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu.tar.xz
```

### 3. ZipVoice 推理核心源码

CMakeLists.txt 中引用的 `src/`、`third_party/`、`utils/` 等源文件位于：

```text
<项目根>/models/zipvoice/cpp/
├── src/tokenizer.cpp / .hpp
├── src/fbank.cpp / .hpp
├── src/zipvoice_engine.cpp / .hpp
├── src/vocoder.cpp / .hpp
├── src/EngineWrapper.cpp / .hpp
├── src/cmdline.hpp
├── third_party/kissfft/kiss_fft.c / .h
├── utils/checker.h / io.hpp / logger.h
└── toolchains/aarch64-none-linux-gnu.toolchain.cmake
```

这些文件随 ZipVoice.AXERA 模型包一起发布，下载模型后自动位于：

```text
models/zipvoice/
├── zipvoice_distill_ax650/   (模型文件)
├── cpp/                      (推理核心源码，即上述目录)
├── resources/
├── assets/
└── scripts/
```

无需单独下载或从其他工程复制。

### 4. onnxruntime (aarch64)

交叉编译时需要 aarch64 版本的 `libonnxruntime.so`，可从以下位置获取：
- sherpa-onnx 预编译包（如 MeloTTS 或 Kokoro 的 `build/lib/` 目录）
- 或从 [onnxruntime releases](https://github.com/microsoft/onnxruntime/releases) 下载

编译时 CMakeLists.txt 已配置从 `<项目根>/models/melotts_sherpa/build/lib/` 查找。

### 5. ZipVoice AX650 distill 模型文件

从 HuggingFace 下载 ZipVoice.AXERA 到 `models/zipvoice/`：

```text
https://huggingface.co/AXERA-TECH/ZipVoice.AXERA
```

模型目录结构：

```text
models/zipvoice/zipvoice_distill_ax650/
├── encoder.axmodel
├── decoder_part0.axmodel
├── decoder_part1.axmodel
├── decoder_part2.axmodel
├── decoder_part3.axmodel
├── decoder4_split_manifest.json
└── runtime_config.json
```

## 编译


```bash
BSP_MSP_DIR=/path/to/ax650n_bsp_sdk/msp/out \
TOOLCHAIN_DIR=/path/to/gcc-arm-9.2-2019.12-x86_64-aarch64-none-linux-gnu \
bash build_ax650.sh
```

编译产物：

- `build/libzipvoice_axera.so` — C API 动态库（供 `zipvoice_tts_ctypes.py` 调用）
- `build/zipvoice_axera_server` — 常驻 daemon（调试用）

## 与 Python 服务的关系

生产环境使用 `zipvoice_tts_ctypes.py`（Python 单层常驻 HTTP 服务），
通过 ctypes 直接加载 `libzipvoice_axera.so`，模型常驻在当前进程内：

```text
zipvoice_tts_ctypes.py
  → ctypes.CDLL("libzipvoice_axera.so")
  → zipvoice_create(...)        # 初始化模型
  → zipvoice_cache_prompt(...)  # 加载自定义 prompt
  → zipvoice_infer(...)         # 推理
  → zipvoice_destroy(...)       # 销毁
```

不再经过 daemon stdin/stdout 文本协议，响应不会错位。