cpp/README.md

# openWakeWord C++（HF 发布版）

本目录只包含**预编译产物**：可直接运行的二进制与供二次开发链接的共享库。
源码、构建脚本与 BSP 下载在 GitHub 仓库：
<https://github.com/AXERA-TECH/openWakeWord.AXERA>。

## 目录

```text
cpp/
├── bin/
│   ├── openwakeword_ax650     # AX650 预编译可执行文件
│   └── openwakeword_ax630c    # AX630C 预编译可执行文件
├── lib/
│   ├── ax650/libopenwakeword_ax.so     # AX650 共享库
│   └── ax630c/libopenwakeword_ax.so    # AX630C 共享库
├── include/openwakeword_ax.hpp         # 公共 API 头文件
└── run_openwakeword_ax*.sh             # 板端单条运行脚本
```

WAV、STFT、mel 在 CPU 端完成，embedding 与 6 个 classifier 使用对应平台的
axmodel 在 NPU 执行。

## 板端运行（预编译二进制）

AX650：

```bash
AUDIO=audio/openwakeword/alexa_test.wav bash cpp/run_openwakeword_ax650.sh
```

AX630C：

```bash
AUDIO=audio/openwakeword/alexa_test.wav bash cpp/run_openwakeword_ax630c.sh
```

运行脚本自动设置板端运行库路径（AX650 默认 `/soc/lib`，AX630C 默认
`/opt/lib`）；如 BSP 在其他位置，用环境变量覆盖：

```bash
AXERA_BSP_LIB_DIR=/path/to/bsp/lib bash cpp/run_openwakeword_ax650.sh
```

阈值可通过 `THRESHOLD` 调整。输入音频必须为 16 kHz、单声道、16-bit PCM WAV。

## 二次开发（共享库）

```cpp
#include "openwakeword_ax.hpp"

openwakeword::WakeWordDetector detector(
    "models/650",                                 // axmodel 目录
    "config/openwakeword_mel_weights.bin",        // CPU mel 权重
    0.5f);                                        // 阈值

// 每 80ms 喂一帧 1280 个 int16 样本（16 kHz）
openwakeword::FrameResult result = detector.ProcessFrame(pcm_frame);
for (std::size_t i = 0; i < result.names.size(); ++i) {
    printf("%s max_score=%.4f\n", result.names[i].c_str(),
           result.max_scores[i]);
}
if (result.any_triggered) { /* 唤醒 */ }
detector.Reset();  // 新会话时清空流式状态
```

在自己的 CMake 工程中链接：

```cmake
add_library(openwakeword_ax SHARED IMPORTED)
set_target_properties(openwakeword_ax PROPERTIES
  IMPORTED_LOCATION "${CMAKE_CURRENT_SOURCE_DIR}/cpp/lib/ax650/libopenwakeword_ax.so")
target_include_directories(your_app PRIVATE cpp/include)
target_link_libraries(your_app PRIVATE openwakeword_ax)
```

板端运行时需提供 BSP 动态库路径（AX650 通常为 `/soc/lib`，AX630C 为
`/opt/lib`）。