README.md

---
license: mit
library_name: axera
pipeline_tag: audio-to-audio
tags:
- axera
- ax650
- npu3
- speech-enhancement
- h-gtcrn
---

# H-GTCRN.AXERA

[H-GTCRN](https://github.com/Max1Wz/H-GTCRN) 语音增强 AXERA 板端推理 demo。
AX650/NPU3 预编译模型 + Python SDK + C++ 可执行文件，即取即用，**wav 进 wav 出**。

- [x] Python 示例（numpy + pyaxengine，无 torch/onnxruntime 回退）
- [x] C++ 示例（`bin/` 下可执行文件，无需编译）

## 支持模型

| 模型 | 输入 | 输出 | axmodel | 端到端 RTF | NPU core RTF |
|------|------|------|---------|:--:|:--:|
| H-GTCRN-core | 16kHz wav（1/2 声道） | 16kHz 增强 wav | 24.2 MB | ~0.36 | 0.0023 |

> 完整链路（与官方 GTCRN_IVA 一致）：STFT → WPE 去混响 → auxIVA 声源分离 →
> 特征构造 → [NPU: GTCRN 核 `feat→mask`] → 掩码应用 → ISTFT。
> CPU 侧为 numpy / C++ 实现，NPU 只跑神经核。
> **端到端 RTF =（CPU 链路 + NPU）总耗时 / 音频时长**（10s 音频约 3.6s，AX650 实测）；
> NPU core RTF = 仅神经核推理 / 音频时长。CPU 链路占绝对主导：WPE/IVA 是
> 整段统计算法（每频点 36×36 矩阵求逆 + 10 轮迭代），与上游一致为离线整段推理，
> 非流式；如需实时需改造为在线分块算法。

## 目录结构

```
H-GTCRN.AXERA/
├── models/                 # model.axmodel + model_meta.json
├── bin/                    # h_gtcrn_ax650 可执行文件（板端直接运行，wav→wav）
├── python/                 # Python SDK + numpy 版 wav→wav demo
├── samples/                # 带噪/增强对比音频
├── run.sh                  # Python 一键推理
├── run_cpp_ax650.sh        # C++ 一键推理（wav→wav）
├── setup.sh                # 板端 Python 依赖安装
└── README.md
```

## 快速开始（AX650 板端）

```bash
# 下载本仓库到板端后：
bash run_cpp_ax650.sh        # C++ 一键降噪：Samples1_noisy.wav → output_cpp_enhanced.wav
# 或 Python：
bash setup.sh                # 安装依赖（numpy + pyaxengine，已装则跳过）
python3 python/audio_demo.py --model models/model.axmodel \
  --input-wav samples/Samples1_noisy.wav --output output_enhanced.wav
```

输入要求：16kHz PCM16 wav，1 或 2 声道；长度 ≤ 10.0s（626 帧，自动补零），更长请
自行分片。板端运行库在 `/soc/lib`，系统已配置搜索路径，一般直接运行即可；如提示
找不到 `libax_*.so`，再加 `export LD_LIBRARY_PATH=/soc/lib:${LD_LIBRARY_PATH:-}`。

## Python SDK

```python
import numpy as np
from h_gtcrn_core_sdk import ModelSession

feat = np.load("examples/sample_input.npy").astype("float32")
session = ModelSession("models/model.axmodel")
mask = session.run_named({"feat": feat})["mask"]
```

依赖仅 numpy + pyaxengine（板端），无 torch/onnxruntime 回退。
`python/audio_demo.py` 是完整 wav→wav demo（numpy 实现 CPU 链路）。

## C++ 推理（bin/ 可执行文件）

`bin/h_gtcrn_ax650` 已按 AX650 交叉编译好，板端直接运行：

```bash
./bin/h_gtcrn_ax650 models/model.axmodel samples/Samples1_noisy.wav output_enhanced.wav --bench 20
```

输出 16kHz PCM16 增强 wav，并打印 CPU 链路耗时 / NPU 耗时 / RTF。
C++ 源码（编译方法 + 工具链下载说明）见 GitHub：
<https://github.com/AXERA-TECH/H-GTCRN.AXERA>

## 示例音频 (samples/)

- `Samples1_noisy.wav` — 原始 16kHz 双通道带噪输入（RMS 0.09499）
- `Samples1_board_enhanced.wav` — **AX650 板端增强输出**（RMS 0.02932）
- `Samples1_core_ref_enhanced.wav` — ONNX 参考增强输出

## 验证（AX650 板端实测）

| 指标 | 值 |
|------|-----|
| 端到端 RTF（CPU 链路 + NPU）/ 10s 音频 | ~0.36（C++ 3.6s；numpy 3.9s） |
| NPU core 20 次平均耗时 | 22.8 ms（RTF 0.0023） |
| C++ 输出 vs torch 链参考 cosine | 0.99999 |
| 板端 vs PyTorch mask cosine | 0.99876 |
| 板端增强音频 vs 原版 cosine | 0.99947 |

## 参考

- [H-GTCRN](https://github.com/Max1Wz/H-GTCRN) — 原始模型
- [H-GTCRN.AXERA（GitHub 源码）](https://github.com/AXERA-TECH/H-GTCRN.AXERA) — 模型转换 + C++ 源码
- [Magnetar](https://github.com/AXERA-TECH/Magnetar) — AXERA 模型部署 agent 工具