README.md

---
language:
- en
license: apache-2.0
pipeline_tag: audio-classification
tags:
- keyword-spotting
- wake-word
- axera
- ax650
- ax630c
---

# openWakeWord.AXERA

[openWakeWord](https://github.com/dscripka/openWakeWord) 语音唤醒 AXERA 推理 demo。

## 功能

- 支持 AX650 和 AX630C；
- 支持 Python SDK 和 C++ 预编译二进制；

## 目录结构

```text
OpenWakeWord.AXERA/
├── models/
│   ├── 650/          # AX650 axmodel
│   └── 630C/         # AX630C axmodel
├── config/           # STFT/mel 权重
├── audio/openwakeword/
├── scripts/          # Python SDK
├── cpp/
│   ├── bin/          # C++ 预编译二进制（ax650 / ax630c）
│   └── run_*.sh      # 板端运行脚本
└── README.md
```

C++ 源码、构建脚本与 BSP 下载脚本在 GitHub 仓库：
<https://github.com/AXERA-TECH/openWakeWord.AXERA>
（HuggingFace 仅发布预编译产物。）

## Python

```bash
# 创建虚拟环境
conda create -n OpenWakeWord python=3.10
conda activate OpenWakeWord

# 安装 pyaxengine（https://github.com/AXERA-TECH/pyaxengine/releases/latest）
pip install axengine-x.x.x-py3-none-any.whl

pip install -r requirements.txt
```

`requirements.txt` 已包含 axengine（pyaxengine）wheel 依赖，直接
`pip install -r requirements.txt` 即可。`--backend onnx`（CPU 回退）仅用于
开发/验证，发布运行请使用默认 `axengine`（NPU）。

AX650：

```bash
python scripts/openwakeword_ax650.py
```

AX630C：

```bash
python scripts/openwakeword_ax630c.py
```

自定义音频目录、阈值和输出文件：

```bash
python scripts/openwakeword_ax630c.py \
  --audio-dir audio/openwakeword \
  --threshold 0.5 \
  --output outputs/openwakeword_ax630c.json
```

## C++（预编译二进制）

板端直接使用 `cpp/bin/` 下的预编译二进制，无需交叉编译。

AX650：

```bash
LD_LIBRARY_PATH=<BSP_LIB_DIR> cpp/bin/openwakeword_ax650 \
  --models-dir models/650 \
  --mel-weights config/openwakeword_mel_weights.bin \
  --audio audio/openwakeword/alexa_test.wav \
  --threshold 0.5
```

AX630C：

```bash
LD_LIBRARY_PATH=<BSP_LIB_DIR> cpp/bin/openwakeword_ax630c \
  --models-dir models/630C \
  --mel-weights config/openwakeword_mel_weights.bin \
  --audio audio/openwakeword/alexa_test.wav \
  --threshold 0.5
```

详细 C++ 说明见 `cpp/README.md`。

### 共享库（二次开发）

```text
cpp/lib/ax650/libopenwakeword_ax.so      # AX650 共享库
cpp/lib/ax630c/libopenwakeword_ax.so     # AX630C 共享库
cpp/include/openwakeword_ax.hpp          # 公共 API 头文件
```

```cpp
#include "openwakeword_ax.hpp"

openwakeword::WakeWordDetector detector(
    "models/650",                                 // axmodel 目录
    "config/openwakeword_mel_weights.bin",        // CPU mel 权重
    0.5f);                                        // 阈值
openwakeword::FrameResult result = detector.ProcessFrame(pcm_frame); // 1280 samples
// result.names / result.max_scores / result.any_triggered
```

板端运行时需提供 BSP 动态库路径（AX650 通常为 `/soc/lib`，AX630C 为
`/opt/lib`）。共享库源码与构建脚本在 GitHub 仓库。

## 参考

- [openWakeWord](https://github.com/dscripka/openWakeWord)
- [Pulsar2](https://pulsar2-docs.readthedocs.io/en/latest/pulsar2/introduction.html)

## 已知问题与改进

- **mel 请使用 CPU 实现**：`melspectrogram.axmodel` 在 AX650/AX630C 板上输出全零
  （NPU 定点无法表达 mel 前端动态范围），`config.json` 默认 `mel_backend=numpy`，
  Python/C++ 运行时均使用 `config/openwakeword_mel_weights.npz` 在 CPU 计算。
- **hey_rhasspy / weather 分类器已重新校准**：旧发布版在真实触发窗口得分退化
  （峰值窗口实测 0.005 / 0.79）；本版本改用包含 TTS 唤醒词正样本的校准集
  （高响应窗口采样），峰值窗口得分恢复到 0.97 / 1.00（alexa/mycroft/timer 保持 1.0）。
  校准与编译配方见 https://github.com/AXERA-TECH/openWakeWord.AXERA/pull/1 。