三芯片合并:AX620E/AX637 升级 encoder+decoder 全 NPU,新增新一代 SDK;AX650 保持老 SDK

README.md

@@ -5,17 +5,59 @@ tags: [text-to-speech, vits, ax650, ax620e, ax637, npu, onnx]
 pipeline_tag: text-to-speech
 ---
 
-# Inflect-Micro-v2 for AXera NPU
+# Inflect-Micro-v2 for AXera NPU（三芯片）
 
 High-quality English TTS (VITS) optimized for **AX650 / AX620E / AX637** NPUs.
 
-| Chip | Encoder | Decoder | Precision |
-|------|---------|---------|-----------|
-| **AX650** | NPU (axmodel) | NPU (axmodel) | U16 |
-| **AX620E** | NPU (axmodel) | CPU (onnxruntime) | U16 |
-| **AX637** | NPU (axmodel) | CPU (onnxruntime) | U16 |
+## 芯片支持
 
-## 🎧 Audio Samples (AX650 NPU)
+| Chip | Encoder | Decoder | SDK |
+|------|---------|---------|-----|
+| **AX650** | NPU (axmodel) | NPU (axmodel) | 老一代 `inflect_tts_sdk`（emb + dp 分离） |
+| **AX620E** | NPU (axmodel) | **NPU (axmodel)** | 新一代 `inflect_ax_tts` |
+| **AX637** | NPU (axmodel) | **NPU (axmodel)** | 新一代 `inflect_ax_tts` |
+
+> 注：AX620E/AX637 已从“encoder NPU + decoder CPU(onnxruntime)”升级为
+> **encoder/decoder 双 NPU**。AX650 保持原有全 NPU 交付与老 SDK 不变。
+
+## 模型
+
+```
+models/
+  ax650/   — 老一代全 NPU（encoder/decoder axmodel + dp.onnx + emb.npy）
+  ax620e/  — 新一代全 NPU（encoder.axmodel + decoder.axmodel, T=256/Tp=512）
+  ax637/   — 新一代全 NPU（encoder.axmodel + decoder.axmodel, 权重 S16 升级版）
+```
+
+新一代 encoder 输入 `tokens [1,256] S32` + `x_lengths [1] S32`，输出
+`m_p/logs_p [1,192,256]`、`logw [1,1,256]`；decoder 输入 `z_p [1,192,512] fp32`，
+输出 `wav [1,1,131072]`（≈5.46 s/块）。Host 侧完成音素前端、时长取整、
+generate_path 对齐、prior 扩展与噪声注入（seed 可控）。
+
+## 快速开始
+
+```bash
+bash setup.sh
+
+# AX650（老 SDK）
+bash run.sh "Hello world." output.wav cli ax650
+
+# AX620E / AX637（新 SDK，encoder+decoder 全 NPU）
+bash run.sh "Hello world." output.wav cli ax620e
+bash run.sh "Hello world." output.wav cli ax637
+```
+
+新 SDK 也可以直接用：
+
+```bash
+cd python
+python3 example.py \
+  --encoder ../models/ax620e/encoder.axmodel \
+  --decoder ../models/ax620e/decoder.axmodel \
+  --text "The quick brown fox jumps over the lazy dog." --output out.wav
+```
+
+## 音频示例（AX650 NPU）
 
 **"Hello and welcome to Inflect Micro V2 text to speech."**
 <audio controls src="https://huggingface.co/AXERA-TECH/inflect_micro_v2/resolve/main/samples/en_hello.wav"></audio>
@@ -32,21 +74,18 @@ High-quality English TTS (VITS) optimized for **AX650 / AX620E / AX637** NPUs.
 **"This audio was generated entirely on the AX650 NPU chip."**
 <audio controls src="https://huggingface.co/AXERA-TECH/inflect_micro_v2/resolve/main/samples/en_intro.wav"></audio>
 
-## 🚀 Quick Start
-
-```bash
-bash setup.sh
-bash run.sh "Hello world." output.wav cli ax650
-```
-
-## 📁 Structure
+## 目录结构
 
 ```
 models/
-  ax650/   — full NPU (encoder + decoder axmodel)
-  ax620e/  — encoder axmodel + decoder ONNX
-  ax637/   — encoder axmodel + decoder ONNX
-python/    — Python SDK
-cpp/       — C++ SDK
-samples/   — audio samples
+  ax650/    — 全 NPU（老一代模型,emb + dp 分离）
+  ax620e/   — 全 NPU（新一代模型）
+  ax637/    — 全 NPU（新一代模型,decoder 权重 S16）
+python/
+  inflect_tts_sdk/   — 老 SDK（AX650）
+  inflect_ax_tts/    — 新 SDK（AX620E/AX637）+ example.py + tests
+cpp/
+  inflect_tts_sdk/   — 老 C++ SDK（AX650）
+  CMakeLists.txt + src/ — 新 C++ SDK（AX620E/AX637）
+samples/   — 音频示例（AX650 NPU 生成）
 ```

cpp/CMakeLists.txt

@@ -0,0 +1,36 @@
+cmake_minimum_required(VERSION 3.16)
+project(inflect_tts_sdk CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+
+if(NOT CMAKE_BUILD_TYPE)
+  set(CMAKE_BUILD_TYPE Release)
+endif()
+
+# Root of the AXera BSP runtime (contains include/ with ax_engine_api.h,
+# ax_sys_api.h and lib/ with libax_engine.so, libax_sys.so). Leave empty for a
+# host configure/build check — the engine wrapper compiles to a throwing stub.
+set(AX_RUNTIME_ROOT "" CACHE PATH "AX BSP runtime root (include/ + lib/)")
+
+add_library(inflect_tts STATIC
+  src/inflect_tts.cpp
+  src/host_chain.cpp
+  src/ax_runner.cpp
+  src/wav_writer.cpp
+)
+target_include_directories(inflect_tts PUBLIC src)
+
+if(AX_RUNTIME_ROOT)
+  target_compile_definitions(inflect_tts PRIVATE INFLECT_WITH_AX_ENGINE=1)
+  target_include_directories(inflect_tts PRIVATE ${AX_RUNTIME_ROOT}/include)
+  target_link_directories(inflect_tts PUBLIC ${AX_RUNTIME_ROOT}/lib)
+  target_link_libraries(inflect_tts PUBLIC ax_engine ax_sys)
+  message(STATUS "inflect_tts: AX runtime from ${AX_RUNTIME_ROOT}")
+else()
+  message(STATUS "inflect_tts: AX_RUNTIME_ROOT not set — building host stub (no NPU runtime)")
+endif()
+
+add_executable(inflect_tts_cli src/main.cpp)
+target_link_libraries(inflect_tts_cli PRIVATE inflect_tts)

cpp/README.md

@@ -0,0 +1,85 @@
+# Inflect AX TTS C++ SDK
+
+`owensong/Inflect-Micro-v2` Encoder/Decoder 两段式 AXMODEL 的 C++ 推理 SDK,面向 **AX620E / AX637** 板端。直接链接 AX Engine 运行时(`ax_engine` + `ax_sys`,AX620E BSP 惯例)。两套 axmodel 接口一致,通过模型路径切换目标。
+
+## 范围说明
+
+- **包含**:encoder/decoder 推理封装(`AxRunner`)、完整 Host 链(时长取整、`generate_path` 对齐、prior 扩展、噪声注入、Tp=512 分块 crossfade、edge fade、clip、WAV 写出)——纯 C++17,无 Eigen/第三方依赖;`generate_path` 为纯整数逻辑,扩展 matmul 由 0/1 对齐性质等价实现为逐帧 gather(与 matmul 逐位一致,有自测)。
+- **不包含**:eSpeak 文本前端(文本 → 音素 id)。C++ 侧 API 接收音素 id 序列;文本前端请用 Python SDK(`../python`)离线生成 id,或在板端自行集成 eSpeak-ng 后按模型仓库 `runtime/text/symbols.py` 映射。
+- **seed**:C++ 用 `std::mt19937_64 + normal_distribution`,SDK 内可复现;与 PyTorch 参考及 Python SDK(numpy PCG64)均不逐位一致。
+
+## 目录
+
+```
+src/ax_runner.{h,cpp}     AX Engine 运行时封装(AX_RUNTIME_ROOT 未设时为 stub)
+src/host_chain.{h,cpp}    Host 链:expand_priors / inject_noise / 分块 crossfade / edge fade
+src/inflect_tts.{h,cpp}   InflectTTS 类:synthesize_tokens(token_ids, speed, variation, seed)
+src/wav_writer.{h,cpp}    16-bit PCM WAV 写出
+src/main.cpp              inflect_tts_cli 示例 + --selftest
+cmake/aarch64-linux-gnu.toolchain.cmake
+```
+
+## 构建
+
+### 本机 configure / 构建检查(无 BSP,stub 引擎)
+
+```bash
+cd package/cpp
+cmake -B build .
+cmake --build build -j
+./build/inflect_tts_cli --selftest   # Host 链自测(无需 AX 运行时)
+```
+
+### 板端 aarch64 交叉编译(AX620E)
+
+```bash
+cd package/cpp
+cmake -B build-aarch64 \
+  -DCMAKE_TOOLCHAIN_FILE=cmake/aarch64-linux-gnu.toolchain.cmake \
+  -DAX_RUNTIME_ROOT=/opt/ax620e_bsp/runtime \
+  .
+cmake --build build-aarch64 -j
+```
+
+`AX_RUNTIME_ROOT` 指向 AX620E BSP SDK 的运行时目录(示例写 `/opt/ax620e_bsp/runtime`,按实际 BSP 安装位置替换),需含 `include/ax_engine_api.h`、`include/ax_sys_api.h` 与 `lib/libax_engine.so`、`lib/libax_sys.so`。板内原生编译去掉 toolchain 行、保留 `-DAX_RUNTIME_ROOT` 即可。AX637 同一份代码,仅 axmodel 与 BSP 库不同。
+
+## 板端部署与运行
+
+```bash
+# 目标机(示例 IP 192.168.1.10,按实际板地址替换)
+scp build-aarch64/inflect_tts_cli root@192.168.1.10:/opt/inflect/
+scp ../models/ax620e/encoder.axmodel ../models/ax620e/decoder.axmodel root@192.168.1.10:/opt/inflect/
+
+# 板上(dummy 音素 id,对应文本 "ðə kwɪk")
+./inflect_tts_cli \
+  --encoder encoder.axmodel --decoder decoder.axmodel \
+  --tokens 81,83,16,53,65,102,53 \
+  --output out.wav --speed 1.0 --variation 0.667 --seed 0
+```
+
+## API
+
+```cpp
+#include "inflect_tts.h"
+#include "wav_writer.h"
+
+InflectTTS tts("encoder.axmodel", "decoder.axmodel");
+std::vector<int64_t> ids = {81, 83, 16, 53, 65, 102, 53};  // 音素 id(未 intersperse)
+std::vector<float> wav = tts.synthesize_tokens(ids, /*speed*/1.0f,
+                                               /*variation*/0.667f, /*seed*/0);
+write_wav("out.wav", wav, 24000);
+```
+
+- `token_ids`:音素 id(**未** intersperse;SDK 内部插 blank,长度上限 127 音素 → 255 tokens,对应 encoder 静态 T=256)。
+- 返回 24 kHz mono float32,[-1,1],已做 5 ms edge fade。
+
+## I/O 契约(与 Python SDK 一致)
+
+- encoder in:`tokens` int32 [1,256](0 右补齐;**注意 axmodel 运行时输入为 S32**,S64 input_processors 已在编译期折叠)、`x_lengths` int32 [1];out:`m_p`/`logs_p` fp32 [1,192,256]、`logw` fp32 [1,1,256](按输出名寻址,取前 x_lengths 帧)。
+- decoder in:`z_p` fp32 [1,192,512](右补零);out:`wav` fp32 [1,1,131072],按有效帧裁剪、块间 64 帧 crossfade。
+- Host 链限制:decoder 右缘 padding 会经卷积感受野倒灌污染末段帧(实测 T'=51 时约最后 12 帧;SDK 以 5 ms edge fade 缓解);多块(T'>512)crossfade 路径未做数值门禁验证。
+
+## 已知限制
+
+- 本仓库构建机上 **未做交叉编译与板端运行验证**(无 aarch64 工具链/无板):仅验证本机 configure + 构建 + `--selftest` 通过。`ax_runner.cpp` 的 AX Engine 调用按 AX620E BSP 惯例编写,首次板端构建如遇到 API 差异以 BSP 头文件为准。
+- 文本前端不在 C++ 范围内(见"范围说明")。

cpp/cmake/aarch64-linux-gnu.toolchain.cmake

@@ -0,0 +1,15 @@
+# aarch64 cross toolchain for AX620E / AX637 boards.
+# Usage:
+#   cmake -B build-aarch64 \
+#     -DCMAKE_TOOLCHAIN_FILE=cmake/aarch64-linux-gnu.toolchain.cmake \
+#     -DAX_RUNTIME_ROOT=<ax bsp runtime root> .
+set(CMAKE_SYSTEM_NAME Linux)
+set(CMAKE_SYSTEM_PROCESSOR aarch64)
+
+set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
+set(CMAKE_CXX_COMPILER aarch64-linux-gnu-g++)
+
+set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
+set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
+set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)

cpp/src/ax_runner.cpp

@@ -0,0 +1,188 @@
+#include "ax_runner.h"
+
+#include <stdexcept>
+
+#ifdef INFLECT_WITH_AX_ENGINE
+
+#include <ax_engine_api.h>
+#include <ax_sys_api.h>
+
+#include <cstring>
+#include <fstream>
+#include <iterator>
+
+namespace {
+
+std::vector<char> read_binary(const std::string& path) {
+    std::ifstream file(path, std::ios::binary);
+    if (!file) {
+        throw std::runtime_error("failed to open " + path);
+    }
+    return std::vector<char>(std::istreambuf_iterator<char>(file),
+                             std::istreambuf_iterator<char>());
+}
+
+void check_ax(int ret, const char* message) {
+    if (ret != 0) {
+        throw std::runtime_error(message);
+    }
+}
+
+}  // namespace
+
+struct AxRunner::Impl {
+    AX_ENGINE_HANDLE handle = nullptr;
+    AX_ENGINE_CONTEXT_T context = nullptr;
+    AX_ENGINE_IO_INFO_T* info = nullptr;
+    AX_ENGINE_IO_T io{};
+    std::vector<AX_ENGINE_IO_BUFFER_T> inputs;
+    std::vector<AX_ENGINE_IO_BUFFER_T> outputs;
+    std::vector<char> model;
+
+    explicit Impl(const std::string& model_path) : model(read_binary(model_path)) {
+        check_ax(AX_SYS_Init(), "AX_SYS_Init failed");
+
+        AX_ENGINE_NPU_ATTR_T npu_attr;
+        std::memset(&npu_attr, 0, sizeof(npu_attr));
+        npu_attr.eHardMode = static_cast<AX_ENGINE_NPU_MODE_T>(0);
+        check_ax(AX_ENGINE_Init(&npu_attr), "AX_ENGINE_Init failed");
+
+        AX_ENGINE_HANDLE_EXTRA_T extra;
+        std::memset(&extra, 0, sizeof(extra));
+        char model_name[] = "inflect_tts";
+        extra.pName = reinterpret_cast<AX_S8*>(model_name);
+        check_ax(AX_ENGINE_CreateHandleV2(&handle, model.data(),
+                                          static_cast<AX_U32>(model.size()), &extra),
+                 "AX_ENGINE_CreateHandleV2 failed");
+        check_ax(AX_ENGINE_CreateContextV2(handle, &context),
+                 "AX_ENGINE_CreateContextV2 failed");
+        check_ax(AX_ENGINE_GetIOInfo(handle, &info), "AX_ENGINE_GetIOInfo failed");
+        if (!info || info->nInputSize < 1 || info->nOutputSize < 1) {
+            throw std::runtime_error("model has no input or output tensors");
+        }
+
+        inputs.resize(info->nInputSize);
+        outputs.resize(info->nOutputSize);
+        io.pInputs = inputs.data();
+        io.nInputSize = info->nInputSize;
+        io.pOutputs = outputs.data();
+        io.nOutputSize = info->nOutputSize;
+
+        for (AX_U32 i = 0; i < info->nInputSize; ++i) {
+            allocate(inputs[i], info->pInputs[i].nSize, "inflect_input");
+        }
+        for (AX_U32 i = 0; i < info->nOutputSize; ++i) {
+            allocate(outputs[i], info->pOutputs[i].nSize, "inflect_output");
+        }
+    }
+
+    ~Impl() {
+        for (auto& item : inputs) {
+            if (item.phyAddr) AX_SYS_MemFree(item.phyAddr, item.pVirAddr);
+        }
+        for (auto& item : outputs) {
+            if (item.phyAddr) AX_SYS_MemFree(item.phyAddr, item.pVirAddr);
+        }
+        if (handle) AX_ENGINE_DestroyHandle(handle);
+        AX_ENGINE_Deinit();
+        AX_SYS_Deinit();
+    }
+
+    static void allocate(AX_ENGINE_IO_BUFFER_T& buffer, AX_U32 size, const char* token) {
+        std::memset(&buffer, 0, sizeof(buffer));
+        buffer.nSize = size;
+        check_ax(AX_SYS_MemAllocCached(&buffer.phyAddr, &buffer.pVirAddr, buffer.nSize,
+                                       128, reinterpret_cast<const AX_S8*>(token)),
+                 "AX_SYS_MemAllocCached failed");
+    }
+};
+
+AxRunner::AxRunner(const std::string& model_path) : impl_(new Impl(model_path)) {}
+AxRunner::~AxRunner() { delete impl_; }
+
+std::vector<size_t> AxRunner::input_sizes() const {
+    std::vector<size_t> sizes;
+    for (AX_U32 i = 0; i < impl_->info->nInputSize; ++i) {
+        sizes.push_back(impl_->info->pInputs[i].nSize);
+    }
+    return sizes;
+}
+
+std::vector<size_t> AxRunner::output_sizes() const {
+    std::vector<size_t> sizes;
+    for (AX_U32 i = 0; i < impl_->info->nOutputSize; ++i) {
+        sizes.push_back(impl_->info->pOutputs[i].nSize);
+    }
+    return sizes;
+}
+
+std::vector<std::string> AxRunner::input_names() const {
+    std::vector<std::string> names;
+    for (AX_U32 i = 0; i < impl_->info->nInputSize; ++i) {
+        names.emplace_back(impl_->info->pInputs[i].pName
+                               ? reinterpret_cast<const char*>(impl_->info->pInputs[i].pName)
+                               : "");
+    }
+    return names;
+}
+
+std::vector<std::string> AxRunner::output_names() const {
+    std::vector<std::string> names;
+    for (AX_U32 i = 0; i < impl_->info->nOutputSize; ++i) {
+        names.emplace_back(impl_->info->pOutputs[i].pName
+                               ? reinterpret_cast<const char*>(impl_->info->pOutputs[i].pName)
+                               : "");
+    }
+    return names;
+}
+
+std::vector<std::vector<uint8_t>> AxRunner::run(
+    const std::vector<std::pair<const void*, size_t>>& feeds) {
+    if (feeds.size() != impl_->inputs.size()) {
+        throw std::runtime_error("feed count != model input count");
+    }
+    for (size_t i = 0; i < feeds.size(); ++i) {
+        if (feeds[i].second != impl_->inputs[i].nSize) {
+            throw std::runtime_error("feed byte size != model input buffer size");
+        }
+        std::memcpy(impl_->inputs[i].pVirAddr, feeds[i].first, feeds[i].second);
+        AX_SYS_MflushCache(impl_->inputs[i].phyAddr, impl_->inputs[i].pVirAddr,
+                           impl_->inputs[i].nSize);
+    }
+    check_ax(AX_ENGINE_RunSyncV2(impl_->handle, impl_->context, &impl_->io),
+             "AX_ENGINE_RunSyncV2 failed");
+
+    std::vector<std::vector<uint8_t>> result(impl_->outputs.size());
+    for (size_t i = 0; i < impl_->outputs.size(); ++i) {
+        AX_SYS_MinvalidateCache(impl_->outputs[i].phyAddr, impl_->outputs[i].pVirAddr,
+                                impl_->outputs[i].nSize);
+        result[i].resize(impl_->outputs[i].nSize);
+        std::memcpy(result[i].data(), impl_->outputs[i].pVirAddr,
+                    impl_->outputs[i].nSize);
+    }
+    return result;
+}
+
+#else  // !INFLECT_WITH_AX_ENGINE — host stub (configure/build only)
+
+struct AxRunner::Impl {};
+
+AxRunner::AxRunner(const std::string&) : impl_(nullptr) {
+    throw std::runtime_error(
+        "inflect_tts was built without the AX runtime; reconfigure with "
+        "-DAX_RUNTIME_ROOT=<ax bsp root> (see sdk/cpp/README.md)");
+}
+
+AxRunner::~AxRunner() = default;
+
+std::vector<size_t> AxRunner::input_sizes() const { return {}; }
+std::vector<size_t> AxRunner::output_sizes() const { return {}; }
+std::vector<std::string> AxRunner::input_names() const { return {}; }
+std::vector<std::string> AxRunner::output_names() const { return {}; }
+
+std::vector<std::vector<uint8_t>> AxRunner::run(
+    const std::vector<std::pair<const void*, size_t>>&) {
+    throw std::runtime_error("AX runtime not available in this build");
+}
+
+#endif  // INFLECT_WITH_AX_ENGINE

cpp/src/ax_runner.h

@@ -0,0 +1,38 @@
+#pragma once
+
+// Thin wrapper over the AX Engine runtime (ax_engine/ax_sys from the AXera
+// BSP, AX620E convention). Compiled against the real runtime when CMake is
+// configured with -DAX_RUNTIME_ROOT=<bsp root>; otherwise a stub that throws
+// on construction (host-side configure/build still passes — see README).
+
+#include <cstddef>
+#include <cstdint>
+#include <string>
+#include <utility>
+#include <vector>
+
+class AxRunner {
+public:
+    explicit AxRunner(const std::string& model_path);
+    ~AxRunner();
+
+    AxRunner(const AxRunner&) = delete;
+    AxRunner& operator=(const AxRunner&) = delete;
+
+    // Input/output buffer sizes in bytes, in model-declared order.
+    std::vector<size_t> input_sizes() const;
+    std::vector<size_t> output_sizes() const;
+    // Tensor names in model-declared order (empty when unavailable).
+    std::vector<std::string> input_names() const;
+    std::vector<std::string> output_names() const;
+
+    // feeds[i] = (data, bytes) for input i; returns output byte buffers in
+    // model output order (m_p, logs_p, logw for the encoder; wav for the
+    // decoder — all float32).
+    std::vector<std::vector<uint8_t>> run(
+        const std::vector<std::pair<const void*, size_t>>& feeds);
+
+private:
+    struct Impl;
+    Impl* impl_;
+};

cpp/src/host_chain.cpp

@@ -0,0 +1,110 @@
+#include "host_chain.h"
+
+#include <algorithm>
+#include <cmath>
+#include <random>
+#include <stdexcept>
+
+namespace inflect {
+
+ExpandedPriors expand_priors(const float* logw, const float* m_p,
+                             const float* logs_p, int t_total, int x_len,
+                             float length_scale) {
+    if (x_len < 1 || x_len > t_total) {
+        throw std::invalid_argument("x_len out of range [1, t_total]");
+    }
+    // Duration rounding: w = exp(logw) * x_mask * length_scale; w_ceil = ceil(w).
+    // Pure integer cumsum from here on (generate_path).
+    std::vector<int64_t> cum(t_total);
+    int64_t acc = 0;
+    for (int i = 0; i < t_total; ++i) {
+        const float w = (i < x_len) ? std::exp(logw[i]) * length_scale : 0.0f;
+        acc += static_cast<int64_t>(std::ceil(w));
+        cum[i] = acc;
+    }
+    ExpandedPriors priors;
+    priors.t_prime = static_cast<int>(std::max<int64_t>(acc, 1));
+    priors.m_p.resize(static_cast<size_t>(kHiddenChannels) * priors.t_prime);
+    priors.logs_p.resize(static_cast<size_t>(kHiddenChannels) * priors.t_prime);
+
+    // Alignment: output frame t copies input frame src(t), where src(t) is the
+    // unique i with cum[i-1] <= t < cum[i]. This is exactly
+    // attn @ m_p^T with the 0/1 generate_path alignment.
+    int src = 0;
+    for (int t = 0; t < priors.t_prime; ++t) {
+        while (src < t_total - 1 && cum[src] <= t) {
+            ++src;
+        }
+        if (cum[src] <= t) {
+            break;  // t beyond total duration: leave zeros (matches masked path)
+        }
+        for (int c = 0; c < kHiddenChannels; ++c) {
+            const size_t dst = static_cast<size_t>(c) * priors.t_prime + t;
+            const size_t s = static_cast<size_t>(c) * t_total + src;
+            priors.m_p[dst] = m_p[s];
+            priors.logs_p[dst] = logs_p[s];
+        }
+    }
+    return priors;
+}
+
+std::vector<float> inject_noise(const ExpandedPriors& priors, float variation,
+                                uint64_t seed) {
+    std::mt19937_64 rng(seed);
+    std::normal_distribution<float> normal(0.0f, 1.0f);
+    std::vector<float> z_p(priors.m_p.size());
+    for (size_t i = 0; i < z_p.size(); ++i) {
+        z_p[i] = priors.m_p[i] + normal(rng) * std::exp(priors.logs_p[i]) * variation;
+    }
+    return z_p;
+}
+
+std::vector<int> decoder_chunk_starts(int t_prime) {
+    if (t_prime <= kDecoderTp) {
+        return {0};
+    }
+    const int stride = kDecoderTp - kDecoderOverlap;
+    std::vector<int> starts;
+    for (int s = 0; s + kDecoderTp <= t_prime; s += stride) {
+        starts.push_back(s);
+    }
+    const int last = t_prime - kDecoderTp;
+    if (starts.back() < last) {
+        starts.push_back(last);
+    }
+    return starts;
+}
+
+void crossfade_append(std::vector<float>& out, const std::vector<float>& wav,
+                      int ov_frames) {
+    const size_t ov = static_cast<size_t>(ov_frames) * kHopLength;
+    if (ov == 0 || out.size() < ov || wav.size() < ov) {
+        out.insert(out.end(), wav.begin(), wav.end());
+        return;
+    }
+    const size_t tail = out.size() - ov;
+    for (size_t i = 0; i < ov; ++i) {
+        const float t = static_cast<float>(i + 1) / static_cast<float>(ov);
+        out[tail + i] = out[tail + i] * (1.0f - t) + wav[i] * t;
+    }
+    out.insert(out.end(), wav.begin() + ov, wav.end());
+}
+
+void edge_fade(std::vector<float>& waveform, float milliseconds) {
+    const size_t frames = std::min(
+        static_cast<size_t>(kSampleRate * milliseconds / 1000.0f + 0.5f),
+        waveform.size() / 2);
+    for (size_t i = 0; i < frames; ++i) {
+        const float t = static_cast<float>(i + 1) / static_cast<float>(frames);
+        waveform[i] *= t;
+        waveform[waveform.size() - 1 - i] *= t;
+    }
+}
+
+void clip_inplace(std::vector<float>& waveform, float lo, float hi) {
+    for (float& v : waveform) {
+        v = std::min(hi, std::max(lo, v));
+    }
+}
+
+}  // namespace inflect

cpp/src/host_chain.h

@@ -0,0 +1,63 @@
+#pragma once
+
+// Host-side chain between encoder.axmodel and decoder.axmodel, pure C++17
+// (no Eigen, no torch). Mirrors export/export_onnx.py:host_expand, which
+// replicates origin/runtime/models.py:546-558:
+//
+//   w      = exp(logw) * x_mask * length_scale
+//   w_ceil = ceil(w);  T' = max(sum(w_ceil), 1)
+//   attn   = generate_path(w_ceil, mask)   -- pure integer interval logic
+//   m_p'   = attn @ m_p^T ; logs_p' = attn @ logs_p^T
+//
+// generate_path produces a 0/1 alignment with exactly one 1 per output frame,
+// so the "matmul" is implemented as an exact per-frame gather (same integer
+// cumsum intervals, provably identical result).
+
+#include <cstdint>
+#include <vector>
+
+namespace inflect {
+
+constexpr int kSampleRate = 24000;
+constexpr int kHopLength = 256;
+constexpr int kHiddenChannels = 192;
+constexpr int kEncoderT = 256;     // encoder static token length (0-padded)
+constexpr int kDecoderTp = 512;    // decoder static frame length per chunk
+constexpr int kDecoderOverlap = 64;  // frames of overlap between decoder chunks
+
+struct ExpandedPriors {
+    int t_prime = 0;           // T'
+    // channel-major [kHiddenChannels * t_prime]: element (c, t) at c*t_prime+t
+    std::vector<float> m_p;
+    std::vector<float> logs_p;
+};
+
+// logw:   [t_total]        (encoder output logw[0,0,:])
+// m_p:    [192 * t_total]  channel-major (encoder output m_p[0])
+// logs_p: [192 * t_total]  channel-major
+// x_len:  number of valid (unpadded) token frames
+ExpandedPriors expand_priors(const float* logw, const float* m_p,
+                             const float* logs_p, int t_total, int x_len,
+                             float length_scale);
+
+// z_p = m_p' + randn * exp(logs_p') * variation, channel-major [192 * T'].
+// NOTE: std::mt19937_64 + normal_distribution — deterministic within this SDK
+// for a given seed, NOT bit-identical to the PyTorch reference.
+std::vector<float> inject_noise(const ExpandedPriors& priors, float variation,
+                                uint64_t seed);
+
+// Frame offsets of Tp-sized decoder chunks covering [0, t_prime) with
+// >= kDecoderOverlap overlap (EXPORT_NOTES §5.3).
+std::vector<int> decoder_chunk_starts(int t_prime);
+
+// Crossfade-append `wav` (samples of chunk starting at `start_frame`) onto
+// `out`, overlapping the previous chunk tail by ov_frames frames.
+void crossfade_append(std::vector<float>& out, const std::vector<float>& wav,
+                      int ov_frames);
+
+// 5 ms raised-linear edge fade, as origin/inference.py.
+void edge_fade(std::vector<float>& waveform, float milliseconds = 5.0f);
+
+void clip_inplace(std::vector<float>& waveform, float lo = -1.0f, float hi = 1.0f);
+
+}  // namespace inflect

cpp/src/inflect_tts.cpp

@@ -0,0 +1,120 @@
+#include "inflect_tts.h"
+
+#include <algorithm>
+#include <cstring>
+#include <stdexcept>
+
+#include "host_chain.h"
+
+namespace {
+
+// The compiled AXMODELs take S32 token inputs at runtime: the S64
+// input_processors of the ONNX graphs are folded into the model at compile
+// time (COMPILE_NOTES §3, confirmed by SIMULATE §1).
+using token_t = int32_t;
+
+// Index of tensor `name` in `names`; falls back to `fallback` when names are
+// unavailable (older runtimes may not report tensor names).
+size_t name_index(const std::vector<std::string>& names, const char* name,
+                  size_t fallback) {
+    const auto it = std::find(names.begin(), names.end(), name);
+    if (it != names.end()) {
+        return static_cast<size_t>(it - names.begin());
+    }
+    return fallback;
+}
+
+}  // namespace
+
+InflectTTS::InflectTTS(const std::string& encoder_path,
+                       const std::string& decoder_path)
+    : encoder_(encoder_path), decoder_(decoder_path) {}
+
+std::vector<float> InflectTTS::synthesize_tokens(
+    const std::vector<int64_t>& token_ids, float speed, float variation,
+    uint64_t seed) {
+    if (speed < 0.5f || speed > 2.0f) {
+        throw std::invalid_argument("speed must be between 0.5 and 2.0");
+    }
+    if (variation < 0.0f || variation > 1.0f) {
+        throw std::invalid_argument("variation must be between 0.0 and 1.0");
+    }
+    // intersperse(add_blank): N phonemes -> 2N+1 tokens.
+    const int x_len = static_cast<int>(token_ids.size()) * 2 + 1;
+    if (x_len > inflect::kEncoderT) {
+        throw std::invalid_argument(
+            "token sequence exceeds encoder static T=256 (split the text)");
+    }
+
+    // ---- encoder: tokens [1,256] zero-padded + x_lengths [1] -------------
+    std::vector<token_t> tokens(inflect::kEncoderT, 0);
+    for (size_t i = 0; i < token_ids.size(); ++i) {
+        tokens[2 * i + 1] = static_cast<token_t>(token_ids[i]);
+    }
+    token_t x_lengths[1] = {static_cast<token_t>(x_len)};
+    const auto enc_in_names = encoder_.input_names();
+    std::vector<std::pair<const void*, size_t>> enc_feeds(2);
+    enc_feeds[name_index(enc_in_names, "tokens", 0)] =
+        {tokens.data(), tokens.size() * sizeof(token_t)};
+    enc_feeds[name_index(enc_in_names, "x_lengths", 1)] =
+        {x_lengths, sizeof(x_lengths)};
+    auto enc_out = encoder_.run(enc_feeds);
+    if (enc_out.size() != 3) {
+        throw std::runtime_error("encoder must produce 3 outputs (m_p, logs_p, logw)");
+    }
+
+    // ---- host chain: durations + generate_path + expansion + noise -------
+    const auto enc_names = encoder_.output_names();
+    const float* m_p = reinterpret_cast<const float*>(
+        enc_out[name_index(enc_names, "m_p", 0)].data());
+    const float* logs_p = reinterpret_cast<const float*>(
+        enc_out[name_index(enc_names, "logs_p", 1)].data());
+    const float* logw = reinterpret_cast<const float*>(
+        enc_out[name_index(enc_names, "logw", 2)].data());
+    auto priors = inflect::expand_priors(logw, m_p, logs_p, inflect::kEncoderT,
+                                         x_len, 1.0f / speed);
+    std::vector<float> z_p = inflect::inject_noise(priors, variation, seed);
+
+    // ---- decoder: Tp=512 chunks, overlap crossfade, tail trim ------------
+    const int t_prime = priors.t_prime;
+    const auto starts = inflect::decoder_chunk_starts(t_prime);
+    std::vector<float> out;
+    int prev_end = 0;
+    for (size_t k = 0; k < starts.size(); ++k) {
+        const int start = starts[k];
+        const int take = std::min(inflect::kDecoderTp, t_prime - start);
+        std::vector<float> z_chunk(
+            static_cast<size_t>(inflect::kHiddenChannels) * inflect::kDecoderTp, 0.0f);
+        for (int c = 0; c < inflect::kHiddenChannels; ++c) {
+            const float* src =
+                z_p.data() + static_cast<size_t>(c) * t_prime + start;
+            float* dst =
+                z_chunk.data() + static_cast<size_t>(c) * inflect::kDecoderTp;
+            std::memcpy(dst, src, static_cast<size_t>(take) * sizeof(float));
+        }
+        std::vector<float> wav = run_decoder_chunk(z_chunk);
+        if (k == 0) {
+            out = std::move(wav);
+        } else {
+            inflect::crossfade_append(out, wav, prev_end - start);
+        }
+        prev_end = start + inflect::kDecoderTp;
+    }
+    out.resize(static_cast<size_t>(t_prime) * inflect::kHopLength);
+    inflect::edge_fade(out);
+    inflect::clip_inplace(out);
+    return out;
+}
+
+std::vector<float> InflectTTS::run_decoder_chunk(
+    const std::vector<float>& z_chunk) {
+    auto dec_out = decoder_.run(
+        {{z_chunk.data(), z_chunk.size() * sizeof(float)}});
+    if (dec_out.size() != 1) {
+        throw std::runtime_error("decoder must produce 1 output (wav)");
+    }
+    const size_t n = dec_out[0].size() / sizeof(float);
+    std::vector<float> wav(n);
+    std::memcpy(wav.data(), dec_out[0].data(), dec_out[0].size());
+    return wav;
+}

cpp/src/inflect_tts.h

@@ -0,0 +1,36 @@
+#pragma once
+
+// InflectTTS: two-stage (encoder/decoder AXMODEL) VITS TTS pipeline.
+//
+// Scope note: the eSpeak text frontend is NOT part of the C++ SDK — the
+// caller supplies phoneme token ids (produced by the Python SDK frontend or
+// a board-side eSpeak-ng integration; see README). The full duration /
+// alignment / expansion / noise / chunking host chain IS implemented here.
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+#include "ax_runner.h"
+
+class InflectTTS {
+public:
+    InflectTTS(const std::string& encoder_path, const std::string& decoder_path);
+
+    // token_ids: raw phoneme ids (NOT interspersed; blank 0 is inserted here,
+    // mirroring commons.intersperse with add_blank=true).
+    // speed in [0.5, 2.0], variation in [0.0, 1.0].
+    // Returns 24 kHz mono float32 samples in [-1, 1].
+    std::vector<float> synthesize_tokens(const std::vector<int64_t>& token_ids,
+                                         float speed = 1.0f,
+                                         float variation = 0.667f,
+                                         uint64_t seed = 0);
+
+private:
+    AxRunner encoder_;
+    AxRunner decoder_;
+
+    // One Tp=512 decoder chunk: z_chunk channel-major [192 * kDecoderTp]
+    // (zero right-padded) -> wav [kDecoderTp * 256].
+    std::vector<float> run_decoder_chunk(const std::vector<float>& z_chunk);
+};

cpp/src/main.cpp

@@ -0,0 +1,219 @@
+// inflect_tts_cli — Inflect AX TTS C++ SDK example / smoke tool.
+//
+// Synthesize from phoneme ids (eSpeak text frontend is intentionally out of
+// scope for the C++ SDK — see README):
+//
+//   ./inflect_tts_cli \
+//       --encoder models/ax620e/encoder.axmodel \
+//       --decoder models/ax620e/decoder.axmodel \
+//       --tokens 81,83,16,53,65,102,53 --output out.wav
+//
+// Host-side self test of the pure-C++ host chain (no AX runtime needed):
+//
+//   ./inflect_tts_cli --selftest
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <cstdio>
+#include <fstream>
+#include <iostream>
+#include <random>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
+#include "host_chain.h"
+#include "inflect_tts.h"
+#include "wav_writer.h"
+
+namespace {
+
+int selftest() {
+    int failures = 0;
+    auto check = [&](bool ok, const char* name) {
+        std::cout << (ok ? "[PASS] " : "[FAIL] ") << name << "\n";
+        if (!ok) ++failures;
+    };
+
+    // 1) expand_priors == explicit generate_path + matmul reference.
+    {
+        std::mt19937 rng(42);
+        std::normal_distribution<float> norm(0.0f, 1.0f);
+        const int t_total = 16, x_len = 12;
+        std::vector<float> logw(t_total), m_p(inflect::kHiddenChannels * t_total),
+            logs_p(inflect::kHiddenChannels * t_total);
+        for (auto& v : logw) v = norm(rng);
+        for (auto& v : m_p) v = norm(rng);
+        for (auto& v : logs_p) v = norm(rng);
+        const float ls = 1.25f;
+        auto priors = inflect::expand_priors(logw.data(), m_p.data(), logs_p.data(),
+                                             t_total, x_len, ls);
+
+        // Reference: integer cumsum + explicit 0/1 attn matmul.
+        std::vector<int64_t> cum(t_total);
+        int64_t acc = 0;
+        for (int i = 0; i < t_total; ++i) {
+            const float w = (i < x_len) ? std::exp(logw[i]) * ls : 0.0f;
+            acc += static_cast<int64_t>(std::ceil(w));
+            cum[i] = acc;
+        }
+        const int t_prime = static_cast<int>(std::max<int64_t>(acc, 1));
+        check(priors.t_prime == t_prime, "expand_priors: T' == cumsum sum");
+        double max_diff = 0.0;
+        for (int t = 0; t < t_prime; ++t) {
+            for (int c = 0; c < inflect::kHiddenChannels; ++c) {
+                float ref = 0.0f;
+                for (int i = 0; i < t_total; ++i) {
+                    const int64_t lo = (i == 0) ? 0 : cum[i - 1];
+                    if (lo <= t && t < cum[i]) {
+                        ref = m_p[static_cast<size_t>(c) * t_total + i];
+                        break;
+                    }
+                }
+                max_diff = std::max(max_diff,
+                    static_cast<double>(std::fabs(
+                        priors.m_p[static_cast<size_t>(c) * t_prime + t] - ref)));
+            }
+        }
+        check(max_diff == 0.0, "expand_priors: gather == attn matmul (exact)");
+    }
+
+    // 2) Unity durations: identity expansion.
+    {
+        const int t_total = 8, x_len = 5;
+        std::vector<float> logw(t_total, 0.0f);  // exp(0)=1 -> 1 frame each
+        std::vector<float> m_p(inflect::kHiddenChannels * t_total),
+            logs_p(inflect::kHiddenChannels * t_total);
+        for (size_t i = 0; i < m_p.size(); ++i) {
+            m_p[i] = static_cast<float>(i % 7) * 0.1f;
+            logs_p[i] = -1.0f;
+        }
+        auto priors = inflect::expand_priors(logw.data(), m_p.data(), logs_p.data(),
+                                             t_total, x_len, 1.0f);
+        bool ok = priors.t_prime == x_len;
+        for (int t = 0; ok && t < x_len; ++t) {
+            for (int c = 0; c < inflect::kHiddenChannels; ++c) {
+                ok = priors.m_p[static_cast<size_t>(c) * priors.t_prime + t] ==
+                     m_p[static_cast<size_t>(c) * t_total + t];
+            }
+        }
+        check(ok, "expand_priors: unity durations == identity");
+    }
+
+    // 3) Noise injection determinism.
+    {
+        inflect::ExpandedPriors priors;
+        priors.t_prime = 4;
+        priors.m_p.assign(inflect::kHiddenChannels * 4, 0.5f);
+        priors.logs_p.assign(inflect::kHiddenChannels * 4, -1.0f);
+        const auto a = inflect::inject_noise(priors, 0.667f, 7);
+        const auto b = inflect::inject_noise(priors, 0.667f, 7);
+        const auto c = inflect::inject_noise(priors, 0.667f, 8);
+        check(a == b, "inject_noise: same seed reproducible");
+        check(a != c, "inject_noise: different seed differs");
+    }
+
+    // 4) Decoder chunk starts: coverage + >=64-frame overlap.
+    {
+        const auto single = inflect::decoder_chunk_starts(51);
+        check(single.size() == 1 && single[0] == 0, "chunk_starts: T'<=512 single");
+        const auto multi = inflect::decoder_chunk_starts(812);
+        bool ok = multi.size() >= 2 && multi.front() == 0 &&
+                  multi.back() + inflect::kDecoderTp >= 812;
+        for (size_t i = 1; ok && i < multi.size(); ++i) {
+            ok = multi[i] < multi[i - 1] + inflect::kDecoderTp - inflect::kDecoderOverlap + 1;
+        }
+        check(ok, "chunk_starts: T'=812 coverage + overlap");
+    }
+
+    // 5) WAV writer round trip header.
+    {
+        const std::string path = "inflect_selftest_tmp.wav";
+        std::vector<float> wav(2400, 0.25f);
+        write_wav(path, wav, 24000);
+        std::ifstream f(path, std::ios::binary);
+        char riff[4];
+        f.read(riff, 4);
+        const bool ok = f && riff[0] == 'R' && riff[1] == 'I' && riff[2] == 'F' &&
+                        riff[3] == 'F';
+        f.close();
+        std::remove(path.c_str());
+        check(ok, "write_wav: RIFF header");
+    }
+
+    std::cout << (failures ? "SELFTEST FAILED" : "SELFTEST PASS") << "\n";
+    return failures ? 1 : 0;
+}
+
+std::vector<int64_t> parse_tokens(const std::string& csv) {
+    std::vector<int64_t> ids;
+    size_t pos = 0;
+    while (pos <= csv.size()) {
+        const size_t comma = csv.find(',', pos);
+        const std::string part = csv.substr(pos, comma - pos);
+        if (!part.empty()) {
+            ids.push_back(std::stoll(part));
+        }
+        if (comma == std::string::npos) break;
+        pos = comma + 1;
+    }
+    return ids;
+}
+
+void usage(const char* argv0) {
+    std::cerr
+        << "usage:\n"
+        << "  " << argv0 << " --selftest\n"
+        << "  " << argv0 << " --encoder ENC.axmodel --decoder DEC.axmodel\n"
+        << "      --tokens 81,83,16,53,65,102,53 --output out.wav\n"
+        << "      [--speed 1.0] [--variation 0.667] [--seed 0]\n";
+}
+
+}  // namespace
+
+int main(int argc, char** argv) {
+    std::string encoder, decoder, tokens_csv, output;
+    float speed = 1.0f, variation = 0.667f;
+    uint64_t seed = 0;
+    for (int i = 1; i < argc; ++i) {
+        const std::string arg = argv[i];
+        auto next = [&](const char* name) -> std::string {
+            if (i + 1 >= argc) {
+                throw std::runtime_error(std::string("missing value for ") + name);
+            }
+            return argv[++i];
+        };
+        if (arg == "--selftest") return selftest();
+        if (arg == "--encoder") encoder = next("--encoder");
+        else if (arg == "--decoder") decoder = next("--decoder");
+        else if (arg == "--tokens") tokens_csv = next("--tokens");
+        else if (arg == "--output") output = next("--output");
+        else if (arg == "--speed") speed = std::stof(next("--speed"));
+        else if (arg == "--variation") variation = std::stof(next("--variation"));
+        else if (arg == "--seed") seed = std::stoull(next("--seed"));
+        else if (arg == "--help" || arg == "-h") { usage(argv[0]); return 0; }
+        else {
+            std::cerr << "unknown argument: " << arg << "\n";
+            usage(argv[0]);
+            return 2;
+        }
+    }
+    if (encoder.empty() || decoder.empty() || tokens_csv.empty() || output.empty()) {
+        usage(argv[0]);
+        return 2;
+    }
+    try {
+        InflectTTS tts(encoder, decoder);
+        const auto ids = parse_tokens(tokens_csv);
+        auto wav = tts.synthesize_tokens(ids, speed, variation, seed);
+        write_wav(output, wav, inflect::kSampleRate);
+        std::cout << "wrote " << output << ": " << wav.size() << " samples ("
+                  << static_cast<double>(wav.size()) / inflect::kSampleRate
+                  << " s @ " << inflect::kSampleRate << " Hz)\n";
+    } catch (const std::exception& exc) {
+        std::cerr << "error: " << exc.what() << "\n";
+        return 1;
+    }
+    return 0;
+}

cpp/src/wav_writer.cpp

@@ -0,0 +1,52 @@
+#include "wav_writer.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstdint>
+#include <fstream>
+#include <stdexcept>
+
+namespace {
+
+void write_u32(std::ofstream& f, uint32_t v) {
+    char b[4] = {static_cast<char>(v & 0xff), static_cast<char>((v >> 8) & 0xff),
+                 static_cast<char>((v >> 16) & 0xff), static_cast<char>((v >> 24) & 0xff)};
+    f.write(b, 4);
+}
+
+void write_u16(std::ofstream& f, uint16_t v) {
+    char b[2] = {static_cast<char>(v & 0xff), static_cast<char>((v >> 8) & 0xff)};
+    f.write(b, 2);
+}
+
+}  // namespace
+
+void write_wav(const std::string& path, const std::vector<float>& waveform,
+               int sample_rate) {
+    std::ofstream f(path, std::ios::binary);
+    if (!f) {
+        throw std::runtime_error("failed to open " + path);
+    }
+    const uint32_t data_bytes = static_cast<uint32_t>(waveform.size() * 2);
+    f.write("RIFF", 4);
+    write_u32(f, 36 + data_bytes);
+    f.write("WAVE", 4);
+    f.write("fmt ", 4);
+    write_u32(f, 16);          // PCM chunk size
+    write_u16(f, 1);           // PCM format
+    write_u16(f, 1);           // mono
+    write_u32(f, static_cast<uint32_t>(sample_rate));
+    write_u32(f, static_cast<uint32_t>(sample_rate * 2));  // byte rate
+    write_u16(f, 2);           // block align
+    write_u16(f, 16);          // bits per sample
+    f.write("data", 4);
+    write_u32(f, data_bytes);
+    for (float v : waveform) {
+        v = std::min(1.0f, std::max(-1.0f, v));
+        write_u16(f, static_cast<uint16_t>(
+                         static_cast<int16_t>(std::lround(v * 32767.0f))));
+    }
+    if (!f) {
+        throw std::runtime_error("failed while writing " + path);
+    }
+}

cpp/src/wav_writer.h

@@ -0,0 +1,8 @@
+#pragma once
+
+#include <string>
+#include <vector>
+
+// Write float32 mono samples in [-1, 1] as 16-bit PCM WAV.
+void write_wav(const std::string& path, const std::vector<float>& waveform,
+               int sample_rate = 24000);

models/ax620e/decoder.axmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b30551a723f8d87182c5211de471da80b3ce2b998bcdc6ead4d8d3b895409d16
+size 22973407

models/ax620e/encoder.axmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6651c46a2e747bda45e1781d7993696d605ec2a1b0cec44bab49d91a3cc96bad
+size 2322718

models/ax620e/model_meta.json

@@ -0,0 +1,269 @@
+{
+  "model": "owensong/Inflect-Micro-v2 (VITS-family TTS, 9.36M params)",
+  "opset": 17,
+  "exported_with": "torch 2.13.0+cpu dynamo exporter, fp32, weight_norm collapsed (9,344,753 params)",
+  "sample_rate": 24000,
+  "hop_length": 256,
+  "graphs": {
+    "encoder": {
+      "file": "encoder.onnx",
+      "contains": [
+        "enc_p (TextEncoder: embedding*sqrt(96) + 3-layer Transformer w/ relative-position attention)",
+        "dp (deterministic DurationPredictor, use_sdp=false)"
+      ],
+      "inputs": {
+        "tokens": {
+          "dtype": "int64",
+          "shape": [
+            1,
+            "T"
+          ],
+          "note": "phoneme ids, add_blank intersperse -> 2N+1"
+        },
+        "x_lengths": {
+          "dtype": "int64",
+          "shape": [
+            1
+          ]
+        }
+      },
+      "outputs": {
+        "m_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "T"
+          ]
+        },
+        "logs_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "T"
+          ]
+        },
+        "logw": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            1,
+            "T"
+          ],
+          "note": "log-duration; host: w=exp(logw)*length_scale, ceil"
+        }
+      },
+      "dynamic_axes": {
+        "tokens": {
+          "1": "T"
+        },
+        "m_p": {
+          "2": "T"
+        },
+        "logs_p": {
+          "2": "T"
+        },
+        "logw": {
+          "2": "T"
+        }
+      },
+      "suggested_static_shape": {
+        "T": 256
+      }
+    },
+    "decoder": {
+      "file": "decoder.onnx",
+      "contains": [
+        "flow (ResidualCouplingBlock x4 + Flip, reverse)",
+        "dec (HiFi-GAN style Generator, upsample 8x8x2x2=256)"
+      ],
+      "inputs": {
+        "z_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "Tp"
+          ],
+          "note": "m_p_expanded + randn*exp(logs_p_expanded)*noise_scale; noise injected on host (seed-controlled)"
+        }
+      },
+      "outputs": {
+        "wav": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            1,
+            "256*Tp"
+          ],
+          "note": "24 kHz mono, tanh-bounded [-1,1]"
+        }
+      },
+      "dynamic_axes": {
+        "z_p": {
+          "2": "Tp"
+        },
+        "wav": {
+          "2": "256*Tp"
+        }
+      },
+      "suggested_static_shape": {
+        "Tp": 512
+      }
+    }
+  },
+  "host_side": {
+    "frontend": "eSpeak-ng phonemizer + symbols mapping + intersperse(0)",
+    "duration": "w=exp(logw)*x_mask/speed; w_ceil=ceil(w); T'=sum(w_ceil) (data-dependent)",
+    "align": "generate_path(w_ceil, mask): cumsum + sequence_mask (integer logic)",
+    "expand": "m_p'=attn@m_p, logs_p'=attn@logs_p  (matmul [1,T',T]x[1,T,192])",
+    "noise": "z_p = m_p' + randn*exp(logs_p')*variation; torch.manual_seed(seed)",
+    "postprocess": "edge fade 5 ms + clip [-1,1] (see origin/inference.py)"
+  },
+  "numeric_baseline": {
+    "seed": 0,
+    "variation": 0.667,
+    "speed": 1.0,
+    "dummy_tokens": [
+      0,
+      81,
+      0,
+      83,
+      0,
+      16,
+      0,
+      53,
+      0,
+      65,
+      0,
+      102,
+      0,
+      53,
+      0
+    ],
+    "dummy_phonemes": "ðə kwɪk",
+    "dummy_T": 15,
+    "dummy_frames_Tp": 51,
+    "dummy_samples": 13056,
+    "note": "ACQUIRE smoke baseline was 7 phonemes -> 13568 samples; the exact ACQUIRE dummy sequence is not recorded, this deterministic 7-phoneme sequence is the EXPORT parity baseline instead."
+  },
+  "verification": {
+    "method": "onnxruntime CPU vs PyTorch fp32 reference",
+    "metrics": {
+      "encoder": [
+        {
+          "tensor": "m_p@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999999486,
+          "max_abs_diff": 9.5367431640625e-07
+        },
+        {
+          "tensor": "logs_p@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999999916,
+          "max_abs_diff": 2.384185791015625e-07
+        },
+        {
+          "tensor": "logw@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999998201,
+          "max_abs_diff": 1.3113021850585938e-06
+        },
+        {
+          "tensor": "m_p@T=33,xlen=33",
+          "cosine_similarity": 0.999999999999952,
+          "max_abs_diff": 1.430511474609375e-06
+        },
+        {
+          "tensor": "logs_p@T=33,xlen=33",
+          "cosine_similarity": 0.9999999999999927,
+          "max_abs_diff": 2.384185791015625e-07
+        },
+        {
+          "tensor": "logw@T=33,xlen=33",
+          "cosine_similarity": 0.9999999999999284,
+          "max_abs_diff": 8.344650268554688e-07
+        },
+        {
+          "tensor": "m_p@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999566,
+          "max_abs_diff": 1.1920928955078125e-06
+        },
+        {
+          "tensor": "logs_p@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999887,
+          "max_abs_diff": 4.172325134277344e-07
+        },
+        {
+          "tensor": "logw@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999055,
+          "max_abs_diff": 1.6689300537109375e-06
+        },
+        {
+          "tensor": "m_p@T=128,xlen=128",
+          "cosine_similarity": 0.99999999999994,
+          "max_abs_diff": 2.1457672119140625e-06
+        },
+        {
+          "tensor": "logs_p@T=128,xlen=128",
+          "cosine_similarity": 0.9999999999999903,
+          "max_abs_diff": 2.980232238769531e-07
+        },
+        {
+          "tensor": "logw@T=128,xlen=128",
+          "cosine_similarity": 0.9999999999998469,
+          "max_abs_diff": 1.6689300537109375e-06
+        },
+        {
+          "tensor": "m_p@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999999413,
+          "max_abs_diff": 1.430511474609375e-06
+        },
+        {
+          "tensor": "logs_p@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999999761,
+          "max_abs_diff": 5.960464477539062e-07
+        },
+        {
+          "tensor": "logw@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999998836,
+          "max_abs_diff": 1.9073486328125e-06
+        }
+      ],
+      "decoder": [
+        {
+          "tensor": "wav@Tp=15",
+          "cosine_similarity": 0.9999999999978111,
+          "max_abs_diff": 6.407499313354492e-07
+        },
+        {
+          "tensor": "wav@Tp=53",
+          "cosine_similarity": 0.9999999999974042,
+          "max_abs_diff": 3.888271749019623e-07
+        },
+        {
+          "tensor": "wav@Tp=100",
+          "cosine_similarity": 0.9999999999919882,
+          "max_abs_diff": 1.7862766981124878e-06
+        },
+        {
+          "tensor": "wav@Tp=256",
+          "cosine_similarity": 0.9999999999763655,
+          "max_abs_diff": 4.171393811702728e-06
+        },
+        {
+          "tensor": "wav@Tp=512",
+          "cosine_similarity": 0.9999999999960342,
+          "max_abs_diff": 1.3224780559539795e-06
+        }
+      ],
+      "end_to_end": [
+        {
+          "tensor": "wav(dummy)",
+          "cosine_similarity": 0.9999999999137207,
+          "max_abs_diff": 9.82731580734253e-06
+        }
+      ]
+    },
+    "all_cosine_similarity_min": 0.9999999999137207
+  },
+  "export_time_seconds": 18.9
+}

models/ax637/decoder.axmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fd0a39f93c113d78045c583ca79c74bb5e3e65b8b7cf6e028b0601d30024819c
+size 21256191

models/ax637/encoder.axmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7c365cdcaa2696a81ffb11e5c333be634908f06b851c65d8f85dcc056a5a5346
+size 2220488

models/ax637/model_meta.json

@@ -0,0 +1,269 @@
+{
+  "model": "owensong/Inflect-Micro-v2 (VITS-family TTS, 9.36M params)",
+  "opset": 17,
+  "exported_with": "torch 2.13.0+cpu dynamo exporter, fp32, weight_norm collapsed (9,344,753 params)",
+  "sample_rate": 24000,
+  "hop_length": 256,
+  "graphs": {
+    "encoder": {
+      "file": "encoder.onnx",
+      "contains": [
+        "enc_p (TextEncoder: embedding*sqrt(96) + 3-layer Transformer w/ relative-position attention)",
+        "dp (deterministic DurationPredictor, use_sdp=false)"
+      ],
+      "inputs": {
+        "tokens": {
+          "dtype": "int64",
+          "shape": [
+            1,
+            "T"
+          ],
+          "note": "phoneme ids, add_blank intersperse -> 2N+1"
+        },
+        "x_lengths": {
+          "dtype": "int64",
+          "shape": [
+            1
+          ]
+        }
+      },
+      "outputs": {
+        "m_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "T"
+          ]
+        },
+        "logs_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "T"
+          ]
+        },
+        "logw": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            1,
+            "T"
+          ],
+          "note": "log-duration; host: w=exp(logw)*length_scale, ceil"
+        }
+      },
+      "dynamic_axes": {
+        "tokens": {
+          "1": "T"
+        },
+        "m_p": {
+          "2": "T"
+        },
+        "logs_p": {
+          "2": "T"
+        },
+        "logw": {
+          "2": "T"
+        }
+      },
+      "suggested_static_shape": {
+        "T": 256
+      }
+    },
+    "decoder": {
+      "file": "decoder.onnx",
+      "contains": [
+        "flow (ResidualCouplingBlock x4 + Flip, reverse)",
+        "dec (HiFi-GAN style Generator, upsample 8x8x2x2=256)"
+      ],
+      "inputs": {
+        "z_p": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            192,
+            "Tp"
+          ],
+          "note": "m_p_expanded + randn*exp(logs_p_expanded)*noise_scale; noise injected on host (seed-controlled)"
+        }
+      },
+      "outputs": {
+        "wav": {
+          "dtype": "float32",
+          "shape": [
+            1,
+            1,
+            "256*Tp"
+          ],
+          "note": "24 kHz mono, tanh-bounded [-1,1]"
+        }
+      },
+      "dynamic_axes": {
+        "z_p": {
+          "2": "Tp"
+        },
+        "wav": {
+          "2": "256*Tp"
+        }
+      },
+      "suggested_static_shape": {
+        "Tp": 512
+      }
+    }
+  },
+  "host_side": {
+    "frontend": "eSpeak-ng phonemizer + symbols mapping + intersperse(0)",
+    "duration": "w=exp(logw)*x_mask/speed; w_ceil=ceil(w); T'=sum(w_ceil) (data-dependent)",
+    "align": "generate_path(w_ceil, mask): cumsum + sequence_mask (integer logic)",
+    "expand": "m_p'=attn@m_p, logs_p'=attn@logs_p  (matmul [1,T',T]x[1,T,192])",
+    "noise": "z_p = m_p' + randn*exp(logs_p')*variation; torch.manual_seed(seed)",
+    "postprocess": "edge fade 5 ms + clip [-1,1] (see origin/inference.py)"
+  },
+  "numeric_baseline": {
+    "seed": 0,
+    "variation": 0.667,
+    "speed": 1.0,
+    "dummy_tokens": [
+      0,
+      81,
+      0,
+      83,
+      0,
+      16,
+      0,
+      53,
+      0,
+      65,
+      0,
+      102,
+      0,
+      53,
+      0
+    ],
+    "dummy_phonemes": "ðə kwɪk",
+    "dummy_T": 15,
+    "dummy_frames_Tp": 51,
+    "dummy_samples": 13056,
+    "note": "ACQUIRE smoke baseline was 7 phonemes -> 13568 samples; the exact ACQUIRE dummy sequence is not recorded, this deterministic 7-phoneme sequence is the EXPORT parity baseline instead."
+  },
+  "verification": {
+    "method": "onnxruntime CPU vs PyTorch fp32 reference",
+    "metrics": {
+      "encoder": [
+        {
+          "tensor": "m_p@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999999486,
+          "max_abs_diff": 9.5367431640625e-07
+        },
+        {
+          "tensor": "logs_p@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999999916,
+          "max_abs_diff": 2.384185791015625e-07
+        },
+        {
+          "tensor": "logw@T=15,xlen=15",
+          "cosine_similarity": 0.9999999999998201,
+          "max_abs_diff": 1.3113021850585938e-06
+        },
+        {
+          "tensor": "m_p@T=33,xlen=33",
+          "cosine_similarity": 0.999999999999952,
+          "max_abs_diff": 1.430511474609375e-06
+        },
+        {
+          "tensor": "logs_p@T=33,xlen=33",
+          "cosine_similarity": 0.9999999999999927,
+          "max_abs_diff": 2.384185791015625e-07
+        },
+        {
+          "tensor": "logw@T=33,xlen=33",
+          "cosine_similarity": 0.9999999999999284,
+          "max_abs_diff": 8.344650268554688e-07
+        },
+        {
+          "tensor": "m_p@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999566,
+          "max_abs_diff": 1.1920928955078125e-06
+        },
+        {
+          "tensor": "logs_p@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999887,
+          "max_abs_diff": 4.172325134277344e-07
+        },
+        {
+          "tensor": "logw@T=64,xlen=40",
+          "cosine_similarity": 0.9999999999999055,
+          "max_abs_diff": 1.6689300537109375e-06
+        },
+        {
+          "tensor": "m_p@T=128,xlen=128",
+          "cosine_similarity": 0.99999999999994,
+          "max_abs_diff": 2.1457672119140625e-06
+        },
+        {
+          "tensor": "logs_p@T=128,xlen=128",
+          "cosine_similarity": 0.9999999999999903,
+          "max_abs_diff": 2.980232238769531e-07
+        },
+        {
+          "tensor": "logw@T=128,xlen=128",
+          "cosine_similarity": 0.9999999999998469,
+          "max_abs_diff": 1.6689300537109375e-06
+        },
+        {
+          "tensor": "m_p@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999999413,
+          "max_abs_diff": 1.430511474609375e-06
+        },
+        {
+          "tensor": "logs_p@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999999761,
+          "max_abs_diff": 5.960464477539062e-07
+        },
+        {
+          "tensor": "logw@T=256,xlen=256",
+          "cosine_similarity": 0.9999999999998836,
+          "max_abs_diff": 1.9073486328125e-06
+        }
+      ],
+      "decoder": [
+        {
+          "tensor": "wav@Tp=15",
+          "cosine_similarity": 0.9999999999978111,
+          "max_abs_diff": 6.407499313354492e-07
+        },
+        {
+          "tensor": "wav@Tp=53",
+          "cosine_similarity": 0.9999999999974042,
+          "max_abs_diff": 3.888271749019623e-07
+        },
+        {
+          "tensor": "wav@Tp=100",
+          "cosine_similarity": 0.9999999999919882,
+          "max_abs_diff": 1.7862766981124878e-06
+        },
+        {
+          "tensor": "wav@Tp=256",
+          "cosine_similarity": 0.9999999999763655,
+          "max_abs_diff": 4.171393811702728e-06
+        },
+        {
+          "tensor": "wav@Tp=512",
+          "cosine_similarity": 0.9999999999960342,
+          "max_abs_diff": 1.3224780559539795e-06
+        }
+      ],
+      "end_to_end": [
+        {
+          "tensor": "wav(dummy)",
+          "cosine_similarity": 0.9999999999137207,
+          "max_abs_diff": 9.82731580734253e-06
+        }
+      ]
+    },
+    "all_cosine_similarity_min": 0.9999999999137207
+  },
+  "export_time_seconds": 18.9
+}

python/README.md

@@ -0,0 +1,103 @@
+# Inflect AX TTS Python SDK
+
+`owensong/Inflect-Micro-v2`(VITS 系英文 TTS,文本 → 24 kHz 单声道波形)的 Encoder/Decoder 两段式 AXMODEL 推理 SDK,双目标 **AX620E(NPU2)/ AX637(NPU1)**。两套 AXMODEL 接口完全一致(同 shape 契约),SDK 通过模型路径切换目标,代码零改动。
+
+## 推理流水线
+
+```
+text → [Host: eSpeak 音素化 + symbols 映射 + intersperse(add_blank)]
+     → tokens[1,256](int,0 补齐)+ x_lengths[1]
+     → encoder.axmodel → m_p/logs_p[1,192,256]、logw[1,1,256]
+     → [Host: 取前 x_lengths 帧;w=exp(logw)*length_scale;ceil;generate_path;
+        matmul 扩展为 T' 帧;z_p=m_p'+randn(seed)*exp(logs_p')*variation]
+     → 按 Tp=512 分块(64 帧重叠 crossfade)→ decoder.axmodel
+     → 波形块拼接(尾部裁剪)→ edge fade 5ms + clip → 24kHz mono wav
+```
+
+- encoder 静态 shape `T=256`(tokens 以 0 右补齐,`x_lengths` 填真实长度;单 chunk 上限 255 个 intersperse 后 token,超长文本自动二次拆分)。
+- decoder 静态 shape `Tp=512`(~5.46 s/块),Host 侧分块 + 64 帧重叠 crossfade,最后一块尾部裁剪(EXPORT_NOTES §5.3)。
+- 噪声注入在 Host 侧:`np.random.default_rng(seed)`。**seed 在 SDK 内可复现,但与 PyTorch 参考(torch MT19937)不逐位一致。**
+
+## 模型文件位置
+
+| 目标 | encoder | decoder |
+| --- | --- | --- |
+| AX620E | `models/ax620e/encoder.axmodel` | `models/ax620e/decoder.axmodel` |
+| AX637 | `models/ax637/encoder.axmodel` | `models/ax637/decoder.axmodel`(权重 S16 升级版) |
+
+(路径相对于交付包根目录 `package/`;AX637 decoder 为权重 S16 升级版,wav cos 0.9995,详见 `../reports/accuracy_summary.md`。)
+
+## 环境与安装
+
+板端 / 主机(有 NPU 运行时):
+
+```bash
+pip install -r requirements.txt   # numpy, phonemizer, espeakng-loader, num2words, pyaxengine
+```
+
+- eSpeak-ng:优先使用系统库(`/usr/lib/x86_64-linux-gnu/libespeak-ng.so.1` 或 aarch64 对应路径,Debian/Ubuntu:`apt install libespeak-ng1`);无系统库时 `espeakng-loader` pip 包自动提供。**仅真实文本合成需要;`--demo-tokens` 与 `synthesize_tokens()` 不依赖 eSpeak。**
+- 本机(Host)无数值 NPU 时的验证替身:`pip install onnxruntime`,把 `../model_convert/export/encoder.onnx` / `../model_convert/export/decoder.onnx` 作为模型路径传入即可(backend 自动切换)。
+
+## API
+
+```python
+from inflect_ax_tts import InflectTTS
+
+tts = InflectTTS(
+    "../models/ax620e/encoder.axmodel",
+    "../models/ax620e/decoder.axmodel",
+)  # backend="auto": .axmodel -> pyaxengine, .onnx -> onnxruntime
+
+# 文本合成(需要 eSpeak)
+sr, wav = tts.synthesize("The quick brown fox.", speed=1.0, variation=0.667, seed=0)
+tts.save("The quick brown fox.", "out.wav")
+
+# 免前端:直接给音素 id(未 intersperse,SDK 内部加 blank)
+sr, wav = tts.synthesize_tokens([81, 83, 16, 53, 65, 102, 53], seed=0)
+```
+
+- `speed` ∈ [0.5, 2.0](length_scale = 1/speed);`variation` ∈ [0.0, 1.0](噪声幅度,基线 0.667);`seed` 整数,同参可复现。
+- 返回 `(24000, float32 ndarray)`,幅值 [-1, 1];`write_wav()` 写 16-bit PCM。
+
+## 示例
+
+```bash
+cd package/python
+
+# 板端真实文本(AX620E;AX637 换路径即可)
+python example.py \
+  --encoder ../models/ax620e/encoder.axmodel \
+  --decoder ../models/ax620e/decoder.axmodel \
+  --text "The quick brown fox jumps over the lazy dog." \
+  --output out.wav
+
+# Host 干跑:无 NPU、无 eSpeak,onnxruntime 替身 + 确定性 dummy tokens
+python example.py --demo-tokens \
+  --encoder ../model_convert/export/encoder.onnx \
+  --decoder ../model_convert/export/decoder.onnx \
+  --output demo.wav
+```
+
+## Host 前后处理说明
+
+- **前端**(仅 `synthesize()` 文本路径):`normalize_text`(数字/缩写/日期/货币展开,`num2words`)→ eSpeak `en-us` 音素化(`preserve_punctuation + with_stress`)→ 音素覆盖表(2 条)→ 逐字符 symbols 映射 → `intersperse(0)`。与 `origin/inference.py` 完全一致。
+- **时长/对齐**(纯 numpy 整数逻辑):`w=exp(logw)*x_mask/speed` → `ceil` → `T'=max(sum,1)` → `generate_path`(cumsum 区间)→ `attn @ m_p/logs_p` 扩展。
+- **噪声**:`z_p = m_p' + randn(seed) * exp(logs_p') * variation`。
+- **decoder 分块**:`Tp=512`、64 帧重叠线性 crossfade;`T'<=512` 单块路径即 SIMULATE 验证路径。
+- **后处理**:每块 edge fade 5 ms、句间停顿(按上一句末标点 0.08~0.28 s)、最终 clip [-1,1]。
+
+## 测试(Host,onnxruntime 替身)
+
+```bash
+cd package/python
+python tests/test_host_chain.py        # 或 pytest tests/
+```
+
+覆盖:Host 链(`expand_priors`)与 PyTorch 参考逐位级一致性、encoder padding 语义、decoder 分块合成与 fp32 参考链路数值一致(ORT 层面)、端到端确定性、前端冒烟(espeak 可用时)。
+
+## 已知差异 / 限制
+
+- seed 语义与 PyTorch 参考不逐位一致(RNG 不同),仅保证 SDK 内可复现。
+- encoder 输入 dtype:AXMODEL 运行时为 **int32**(input_processors S64 已折叠进模型),ONNX 为 int64;SDK 按 session 元数据自适应。
+- decoder 多块(T'>512)crossfade 路径未做数值门禁验证(仿真仅覆盖单块路径)。
+- 精度结论(仿真,详见 `../reports/accuracy_summary.md`):encoder 双目标 cos ≥ 0.9999;AX637 decoder(权重 S16 升级版)wav cos 0.9995 [PASS];**AX620E decoder(基线)wav cos ≈ 0.95,未达 0.99 门禁**(权重 S8 量化导致的高频细节损失,本工具链版本不可修复),属量化方案限制,非 SDK 问题。

python/example.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Inflect AX TTS SDK example.
+
+Real text synthesis (requires phonemizer + espeak-ng, see README):
+
+    python example.py \
+        --encoder ../models/ax620e/encoder.axmodel \
+        --decoder ../models/ax620e/decoder.axmodel \
+        --text "The quick brown fox jumps over the lazy dog." \
+        --output out.wav
+
+Host dry-run without NPU and without eSpeak (onnxruntime stand-in on the
+fp32 ONNX graphs, deterministic dummy tokens from
+../models/model_meta.json numeric_baseline):
+
+    python example.py --demo-tokens \
+        --encoder ../model_convert/export/encoder.onnx \
+        --decoder ../model_convert/export/decoder.onnx \
+        --output demo.wav
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from inflect_ax_tts import DUMMY_PHONEME_IDS, InflectTTS, write_wav
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Inflect AX TTS SDK example")
+    parser.add_argument("--encoder", required=True, help="encoder .axmodel (or .onnx)")
+    parser.add_argument("--decoder", required=True, help="decoder .axmodel (or .onnx)")
+    parser.add_argument("--text", help="text to synthesize (needs phonemizer + eSpeak-ng)")
+    parser.add_argument(
+        "--demo-tokens",
+        action="store_true",
+        help="skip the text frontend and use the deterministic EXPORT dummy "
+        "phoneme ids (no eSpeak dependency)",
+    )
+    parser.add_argument("--output", required=True, help="output wav path")
+    parser.add_argument("--speed", type=float, default=1.0)
+    parser.add_argument("--variation", type=float, default=0.667)
+    parser.add_argument("--seed", type=int, default=0)
+    parser.add_argument(
+        "--backend",
+        default="auto",
+        choices=["auto", "axengine", "onnxruntime"],
+        help="inference backend (auto: .axmodel -> pyaxengine, .onnx -> onnxruntime)",
+    )
+    args = parser.parse_args()
+
+    if bool(args.text) == bool(args.demo_tokens):
+        parser.error("provide exactly one of --text or --demo-tokens")
+
+    tts = InflectTTS(args.encoder, args.decoder, backend=args.backend)
+    if args.demo_tokens:
+        sample_rate, wav = tts.synthesize_tokens(
+            DUMMY_PHONEME_IDS,
+            speed=args.speed,
+            variation=args.variation,
+            seed=args.seed,
+        )
+    else:
+        sample_rate, wav = tts.synthesize(
+            args.text, speed=args.speed, variation=args.variation, seed=args.seed
+        )
+    write_wav(args.output, wav, sample_rate)
+    print(
+        f"wrote {args.output}: {wav.size} samples "
+        f"({wav.size / sample_rate:.2f} s @ {sample_rate} Hz), "
+        f"amp [{wav.min():.3f}, {wav.max():.3f}]"
+    )
+
+
+if __name__ == "__main__":
+    main()

python/inflect_ax_tts/__init__.py

@@ -0,0 +1,13 @@
+"""Inflect AX TTS SDK — two-stage (encoder/decoder) AXMODEL pipeline for
+owensong/Inflect-Micro-v2 on AXera AX620E / AX637.
+
+    from inflect_ax_tts import InflectTTS
+    tts = InflectTTS("models/ax620e/encoder.axmodel", "models/ax620e/decoder.axmodel")
+    tts.save("The quick brown fox.", "out.wav", speed=1.0, variation=0.667, seed=0)
+"""
+
+from .tts import DUMMY_PHONEME_IDS, InflectTTS
+from .wav_io import write_wav
+
+__all__ = ["InflectTTS", "DUMMY_PHONEME_IDS", "write_wav"]
+__version__ = "1.0.0"

python/inflect_ax_tts/backend.py

@@ -0,0 +1,90 @@
+"""Inference backend wrapper: pyaxengine (default) or onnxruntime (host stand-in).
+
+Both expose an onnxruntime-like API (run / get_inputs / get_outputs). The
+backend is selected from the model file suffix unless overridden:
+
+    *.axmodel -> axengine.InferenceSession   (pyaxengine, on-device or host sim)
+    *.onnx    -> onnxruntime.InferenceSession (host numeric stand-in only)
+
+Encoder input dtype note: the compiled AXMODELs declare their token inputs as
+S32 at runtime (COMPILE_NOTES §3 folds the S64 input_processors into the
+model; SIMULATE §1 confirmed S32 binaries), while the ONNX graphs take int64.
+The wrapper therefore adapts the feed dtype from the session's input metadata.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+
+class ModelSession:
+    """Minimal name-addressable inference session over axengine/onnxruntime."""
+
+    def __init__(self, model_path: str | Path, backend: str = "auto") -> None:
+        self.path = Path(model_path)
+        if not self.path.is_file():
+            raise FileNotFoundError(self.path)
+        if backend == "auto":
+            backend = "axengine" if self.path.suffix == ".axmodel" else "onnxruntime"
+        self.backend = backend
+        if backend == "axengine":
+            try:
+                from axengine import InferenceSession
+            except ImportError as exc:
+                raise ImportError(
+                    "pyaxengine is required for .axmodel files "
+                    "(pip install axengine on an AXera host/BSP environment)"
+                ) from exc
+            self._sess = InferenceSession(str(self.path))
+        elif backend == "onnxruntime":
+            try:
+                import onnxruntime as ort
+            except ImportError as exc:
+                raise ImportError(
+                    "onnxruntime is required for .onnx files "
+                    "(host numeric stand-in only)"
+                ) from exc
+            self._sess = ort.InferenceSession(
+                str(self.path), providers=["CPUExecutionProvider"]
+            )
+        else:
+            raise ValueError(f"unknown backend {backend!r}")
+
+    # -- metadata -----------------------------------------------------------
+    def _inputs(self):
+        return self._sess.get_inputs()
+
+    def output_names(self) -> list[str]:
+        return [o.name for o in self._sess.get_outputs()]
+
+    def input_dtype(self, name: str) -> np.dtype:
+        """Best-effort numpy dtype of a named input.
+
+        onnxruntime exposes `.type` strings ('tensor(int64)'); pyaxengine
+        exposes numpy-like `.dtype`. Fallback: int32 for .axmodel (see module
+        docstring), int64 for .onnx.
+        """
+        for meta in self._inputs():
+            if meta.name != name:
+                continue
+            dt = getattr(meta, "dtype", None)
+            if dt is not None:
+                try:
+                    return np.dtype(dt)
+                except TypeError:
+                    pass
+            type_str = str(getattr(meta, "type", "") or "")
+            if "int32" in type_str:
+                return np.dtype(np.int32)
+            if "int64" in type_str:
+                return np.dtype(np.int64)
+            if "float" in type_str:
+                return np.dtype(np.float32)
+        return np.dtype(np.int32 if self.path.suffix == ".axmodel" else np.int64)
+
+    # -- inference ----------------------------------------------------------
+    def run(self, feeds: dict[str, np.ndarray]) -> dict[str, np.ndarray]:
+        results = self._sess.run(None, feeds)
+        return dict(zip(self.output_names(), results))

python/inflect_ax_tts/frontend.py

@@ -0,0 +1,75 @@
+"""VITS text frontend: text -> phoneme token ids.
+
+Faithful port of origin/inflect_vits_frontend.py + the token mapping from
+origin/runtime/text/__init__.py + commons.intersperse. Text normalization and
+eSpeak configuration live in text_normalize.py (verbatim copy of
+origin/inflect_nano_v2_frontend.py).
+
+Pipeline (mirrors origin/inference.py:InflectTTS._tokens):
+    text -> normalize_text -> eSpeak phonemize (en-us, with_stress,
+    preserve_punctuation) -> phoneme overrides -> per-character symbol ids
+    -> intersperse(0)  (add_blank)
+"""
+
+from __future__ import annotations
+
+from .symbols import symbols
+from .text_normalize import _configure_espeak, normalize_text
+
+__all__ = ["normalize_text", "phonemize_text", "text_to_token_ids", "intersperse"]
+
+# eSpeak is the general fallback. This table contains verified exceptions only
+# (verbatim from origin/inflect_vits_frontend.py).
+PHONEME_OVERRIDES = {
+    "sˈæskɐtʃˌuːən": "sɐskˈætʃəwən",
+    "flʊɹɹˈɛsənt": "flʊˈɹɛsənt",
+}
+
+_SYMBOL_TO_ID = {s: i for i, s in enumerate(symbols)}
+_BLANK_ID = 0  # symbols[0] == '_'
+
+
+def intersperse(seq: list[int], item: int = _BLANK_ID) -> list[int]:
+    """commons.intersperse: insert `item` around every element -> 2N+1."""
+    result = [item] * (len(seq) * 2 + 1)
+    result[1::2] = seq
+    return result
+
+
+def phonemize_text(text: str) -> str:
+    """normalize + eSpeak phonemize + overrides (run_vits_frontend equivalent)."""
+    import re
+
+    normalized = normalize_text(text)
+    _configure_espeak()
+    from phonemizer import phonemize
+
+    phoneme_text = phonemize(
+        [normalized],
+        language="en-us",
+        backend="espeak",
+        strip=True,
+        preserve_punctuation=True,
+        with_stress=True,
+        njobs=1,
+    )[0]
+    for source, replacement in PHONEME_OVERRIDES.items():
+        phoneme_text = phoneme_text.replace(source, replacement)
+    return re.sub(r"\s+", " ", phoneme_text).strip()
+
+
+def text_to_token_ids(text: str, add_blank: bool = True) -> list[int]:
+    """Full frontend: text -> interspersed phoneme ids (2N+1 with add_blank)."""
+    phoneme_text = phonemize_text(text)
+    try:
+        sequence = [_SYMBOL_TO_ID[ch] for ch in phoneme_text]
+    except KeyError as exc:
+        raise ValueError(
+            f"phoneme {exc.args[0]!r} from {phoneme_text!r} is not in the "
+            "model symbol table"
+        ) from exc
+    if add_blank:
+        sequence = intersperse(sequence, _BLANK_ID)
+    if not sequence:
+        raise ValueError("The text frontend produced no speakable tokens.")
+    return sequence

python/inflect_ax_tts/host_chain.py

@@ -0,0 +1,217 @@
+"""Host-side chain between encoder.axmodel and decoder.axmodel (pure numpy).
+
+Replicates, in numpy, the torch host chain of export/export_onnx.py:host_expand
+(which itself mirrors origin/runtime/models.py:546-558):
+
+    w      = exp(logw) * x_mask * length_scale
+    w_ceil = ceil(w);  T' = max(sum(w_ceil), 1)
+    attn   = generate_path(w_ceil, mask)          # pure integer logic
+    m_p'   = attn @ m_p^T ;  logs_p' = attn @ logs_p^T
+    z_p    = m_p' + randn * exp(logs_p') * variation   (seed-controlled, host)
+
+Also contains the fixed-shape plumbing: encoder T=256 zero padding and decoder
+Tp=512 chunking with overlap crossfade (EXPORT_NOTES §5.3 recommends
+>=64-frame overlap between chunks; single-chunk T'<=512 is the path validated
+by SIMULATE).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+SAMPLE_RATE = 24000
+HOP_LENGTH = 256
+HIDDEN_CHANNELS = 192
+ENCODER_T = 256
+DECODER_TP = 512
+DECODER_OVERLAP = 64  # frames of overlap between decoder chunks (EXPORT_NOTES §5.3)
+
+
+# ---------------------------------------------------------------------------
+# Duration rounding + alignment (generate_path)
+# ---------------------------------------------------------------------------
+
+def expand_priors(
+    logw: np.ndarray,
+    m_p: np.ndarray,
+    logs_p: np.ndarray,
+    x_len: int,
+    length_scale: float,
+) -> tuple[np.ndarray, np.ndarray, int]:
+    """Duration rounding + generate_path + prior expansion.
+
+    Args:
+        logw:   [1, 1, T]  log-durations (encoder output, static T)
+        m_p:    [1, C, T]  prior means
+        logs_p: [1, C, T]  prior log-stds
+        x_len:  number of valid (unpadded) token frames
+        length_scale: 1.0 / speed
+
+    Returns:
+        (m_p_e [T', C], logs_p_e [T', C], T')
+    """
+    t_total = logw.shape[-1]
+    if not 1 <= x_len <= t_total:
+        raise ValueError(f"x_len {x_len} out of range [1, {t_total}]")
+    x_mask = (np.arange(t_total) < x_len).astype(np.float32)
+    w = np.exp(logw[0, 0].astype(np.float32)) * x_mask * np.float32(length_scale)
+    w_ceil = np.ceil(w).astype(np.int64)
+    y_len = max(int(w_ceil.sum()), 1)
+
+    # generate_path (origin/runtime/commons.py): with the masked durations the
+    # alignment reduces to pure integer interval logic — frame t of the output
+    # copies input frame i for cum[i-1] <= t < cum[i].  O(T) loop, no matmul
+    # of the [T', T] path needed; we still build attn explicitly for the prior
+    # expansion to stay a literal port (T=256, T'<=~2000: cheap).
+    cum = np.cumsum(w_ceil)
+    attn = np.zeros((y_len, t_total), dtype=np.float32)
+    lo = 0
+    for i in range(t_total):
+        hi = min(int(cum[i]), y_len)
+        if hi > lo:
+            attn[lo:hi, i] = 1.0
+        lo = hi
+    m_p_e = attn @ m_p[0].T.astype(np.float32)
+    logs_p_e = attn @ logs_p[0].T.astype(np.float32)
+    return m_p_e, logs_p_e, y_len
+
+
+def inject_noise(
+    m_p_e: np.ndarray,
+    logs_p_e: np.ndarray,
+    variation: float,
+    seed: int,
+) -> np.ndarray:
+    """z_p = m_p' + randn * exp(logs_p') * variation, seed-controlled.
+
+    NOTE: numpy PCG64 is used, not torch's MT19937 — a given `seed` is
+    deterministic and reproducible within this SDK but is NOT bit-identical to
+    the PyTorch reference (origin/inference.py).
+    """
+    rng = np.random.default_rng(seed)
+    noise = rng.standard_normal(m_p_e.shape, dtype=np.float32)
+    z_p = m_p_e + noise * np.exp(logs_p_e.astype(np.float32)) * np.float32(variation)
+    return z_p.T.copy()  # [C, T']
+
+
+# ---------------------------------------------------------------------------
+# Decoder chunk composition (Tp=512 static shape, overlap crossfade)
+# ---------------------------------------------------------------------------
+
+def decoder_chunk_starts(t_prime: int, chunk: int = DECODER_TP,
+                         overlap: int = DECODER_OVERLAP) -> list[int]:
+    """Frame offsets of decoder chunks covering [0, t_prime) with >=overlap."""
+    if t_prime <= chunk:
+        return [0]
+    stride = chunk - overlap
+    starts = list(range(0, t_prime - chunk + 1, stride))
+    last = t_prime - chunk
+    if starts[-1] < last:
+        starts.append(last)
+    return starts
+
+
+def decode_waveform(
+    z_p: np.ndarray,
+    run_decoder,
+    chunk: int = DECODER_TP,
+    overlap: int = DECODER_OVERLAP,
+) -> np.ndarray:
+    """Run the fixed-shape decoder over z_p and stitch chunks.
+
+    Args:
+        z_p: [C, T'] float32 prior with noise injected.
+        run_decoder: callable taking z_p_chunk [C, chunk] float32 (already
+            right-padded with zeros) and returning wav [chunk*HOP] float32.
+        chunk/overlap: see DECODER_TP / DECODER_OVERLAP.
+
+    Returns:
+        wav [T'*HOP] float32 (tail trimmed; chunk overlaps crossfaded).
+    """
+    t_prime = z_p.shape[1]
+    hop = HOP_LENGTH
+    starts = decoder_chunk_starts(t_prime, chunk, overlap)
+
+    out: np.ndarray | None = None
+    prev_end_frame = 0
+    for start in starts:
+        take = min(chunk, t_prime - start)
+        z_chunk = np.zeros((z_p.shape[0], chunk), dtype=np.float32)
+        z_chunk[:, :take] = z_p[:, start:start + take]
+        wav = np.asarray(run_decoder(z_chunk), dtype=np.float32)
+        if out is None:
+            out = wav
+        else:
+            ov_frames = prev_end_frame - start
+            ov = ov_frames * hop
+            fade_in = np.linspace(0.0, 1.0, ov, endpoint=True, dtype=np.float32)
+            out = np.concatenate(
+                [out[:-ov], out[-ov:] * (1.0 - fade_in) + wav[:ov] * fade_in, wav[ov:]]
+            )
+        prev_end_frame = start + chunk
+    assert out is not None
+    return out[: t_prime * hop]
+
+
+# ---------------------------------------------------------------------------
+# Waveform post-processing (origin/inference.py)
+# ---------------------------------------------------------------------------
+
+def edge_fade(waveform: np.ndarray, sample_rate: int = SAMPLE_RATE,
+              milliseconds: float = 5.0) -> np.ndarray:
+    frames = min(round(sample_rate * milliseconds / 1000.0), waveform.size // 2)
+    if frames <= 0:
+        return waveform
+    output = waveform.copy()
+    ramp = np.linspace(0.0, 1.0, frames, endpoint=True, dtype=np.float32)
+    output[:frames] *= ramp
+    output[-frames:] *= ramp[::-1]
+    return output
+
+
+# ---------------------------------------------------------------------------
+# Text chunking (origin/inference.py: split_text / boundary_pause_seconds)
+# ---------------------------------------------------------------------------
+
+def split_text(text: str, limit: int = 280) -> list[str]:
+    import re
+
+    normalized = " ".join(text.split())
+    sentences = [
+        part.strip()
+        for part in re.split(r"(?<=[.!?;:])\s+", normalized)
+        if part.strip()
+    ]
+    chunks: list[str] = []
+    for sentence in sentences or [normalized]:
+        while len(sentence) > limit:
+            search = sentence[: limit + 1]
+            punctuation = max(search.rfind(mark) for mark in (",", ";", ":"))
+            split_at = (
+                punctuation + 1
+                if punctuation >= limit // 2
+                else sentence.rfind(" ", 0, limit + 1)
+            )
+            if split_at < limit // 2:
+                split_at = limit
+            chunks.append(sentence[:split_at].strip())
+            sentence = sentence[split_at:].strip()
+        if sentence:
+            chunks.append(sentence)
+    return chunks
+
+
+def boundary_pause_seconds(chunk: str) -> float:
+    ending = chunk.rstrip()[-1:] if chunk.strip() else ""
+    return {
+        "?": 0.28,
+        "!": 0.24,
+        ".": 0.22,
+        ";": 0.16,
+        ":": 0.13,
+        ",": 0.09,
+    }.get(ending, 0.08)
+
+
+def seconds_to_samples(seconds: float) -> int:
+    return round(seconds * SAMPLE_RATE)

python/inflect_ax_tts/symbols.py

@@ -0,0 +1,16 @@
+""" from https://github.com/keithito/tacotron """
+
+'''
+Defines the set of symbols used in text input to the model.
+'''
+_pad        = '_'
+_punctuation = ';:,.!?¡¿—…"«»“” '
+_letters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+_letters_ipa = "ɑɐɒæɓʙβɔɕçɗɖðʤəɘɚɛɜɝɞɟʄɡɠɢʛɦɧħɥʜɨɪʝɭɬɫɮʟɱɯɰŋɳɲɴøɵɸθœɶʘɹɺɾɻʀʁɽʂʃʈʧʉʊʋⱱʌɣɤʍχʎʏʑʐʒʔʡʕʢǀǁǂǃˈˌːˑʼʴʰʱʲʷˠˤ˞↓↑→↗↘'̩'ᵻ"
+
+
+# Export all symbols:
+symbols = [_pad] + list(_punctuation) + list(_letters) + list(_letters_ipa)
+
+# Special symbol ids
+SPACE_ID = symbols.index(" ")

python/inflect_ax_tts/text_normalize.py

@@ -0,0 +1,395 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from dataclasses import asdict, dataclass
+from datetime import date
+from pathlib import Path
+
+from num2words import num2words
+
+
+MONTHS = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+]
+
+WORD_OVERRIDES = {
+    "Qwen3": "Qwen three",
+    "Qwen": "Qwen",
+    "PyTorch": "pie torch",
+    "SQLite": "ess cue lite",
+    "USB-C": "you ess bee see",
+    "RTX 3060": "ar tee ex thirty sixty",
+    "RTX 3090": "ar tee ex thirty ninety",
+    "RTX 4090": "ar tee ex forty ninety",
+    "RTX 5080": "ar tee ex fifty eighty",
+    "RTX 5090": "ar tee ex fifty ninety",
+}
+
+LETTER_NAMES = {
+    "A": "ay",
+    "B": "bee",
+    "C": "see",
+    "D": "dee",
+    "E": "ee",
+    "F": "eff",
+    "G": "gee",
+    "H": "aitch",
+    "I": "eye",
+    "J": "jay",
+    "K": "kay",
+    "L": "ell",
+    "M": "em",
+    "N": "en",
+    "O": "oh",
+    "P": "pee",
+    "Q": "cue",
+    "R": "ar",
+    "S": "ess",
+    "T": "tee",
+    "U": "you",
+    "V": "vee",
+    "W": "double you",
+    "X": "ex",
+    "Y": "why",
+    "Z": "zee",
+}
+
+ABBREVIATIONS = {
+    "Dr.": "doctor",
+    "Mr.": "mister",
+    "Mrs.": "missus",
+    "Ms.": "miss",
+    "Prof.": "professor",
+    "St.": "saint",
+    "vs.": "versus",
+    "etc.": "et cetera",
+    "e.g.": "for example",
+    "i.e.": "that is",
+}
+
+PUNCT_TRANSLATION = str.maketrans(
+    {
+        "\u2018": "'",
+        "\u2019": "'",
+        "\u201c": '"',
+        "\u201d": '"',
+        "\u2013": "-",
+        "\u2014": ", ",
+        "\u2026": "...",
+        "(": ", ",
+        ")": ", ",
+        "[": ", ",
+        "]": ", ",
+        "{": ", ",
+        "}": ", ",
+    }
+)
+
+_ESPEAK_CONFIGURED = False
+_ESPEAK_BACKEND = None
+
+
+@dataclass
+class FrontendOutput:
+    raw_text: str
+    normalized_text: str
+    phoneme_text: str
+    tokens: list[str]
+    token_count: int
+
+
+def _words(value: int | float, *, ordinal: bool = False) -> str:
+    if ordinal:
+        text = num2words(value, to="ordinal")
+    else:
+        text = num2words(value)
+    return text.replace("-", " ").replace(",", "")
+
+
+def _digit_words(text: str) -> str:
+    return " ".join(_words(int(ch)) for ch in text if ch.isdigit())
+
+
+def _identifier_digits(text: str) -> str:
+    words = []
+    for index, character in enumerate(text):
+        if not character.isdigit():
+            continue
+        words.append("oh" if character == "0" and index > 0 else _words(int(character)))
+    return " ".join(words)
+
+
+def _expand_identifier_token(token: str) -> str:
+    match = re.fullmatch(r"([A-Za-z]?)(\d+)([A-Za-z]?)", token)
+    if match is None:
+        return token
+    prefix, digits, suffix = match.groups()
+    pieces = []
+    if prefix:
+        pieces.append(LETTER_NAMES[prefix.upper()])
+    if len(digits) == 3 or digits.startswith("0"):
+        pieces.append(_identifier_digits(digits))
+    else:
+        pieces.append(_words(int(digits)))
+    if suffix:
+        pieces.append(LETTER_NAMES[suffix.upper()])
+    return " ".join(pieces)
+
+
+def _expand_labeled_identifier(match: re.Match[str]) -> str:
+    return f"{match.group(1)} {_expand_identifier_token(match.group(2))}"
+
+
+def _expand_street_number(match: re.Match[str]) -> str:
+    return _identifier_digits(match.group(1))
+
+
+def _expand_money(match: re.Match[str]) -> str:
+    raw = match.group(1).replace(",", "")
+    dollars, _, cents = raw.partition(".")
+    dollar_count = int(dollars)
+    parts = [_words(dollar_count), "dollar" if dollar_count == 1 else "dollars"]
+    if cents:
+        cents = cents[:2].ljust(2, "0")
+        cent_count = int(cents)
+        if cent_count:
+            parts.extend(["and", _words(cent_count), "cent" if cent_count == 1 else "cents"])
+    return " ".join(parts)
+
+
+def _expand_date_slash(match: re.Match[str]) -> str:
+    month = int(match.group(1))
+    day = int(match.group(2))
+    year = int(match.group(3))
+    try:
+        date(year, month, day)
+    except ValueError:
+        return match.group(0)
+    return f"{MONTHS[month - 1]} {_words(day, ordinal=True)} {_words(year)}"
+
+
+def _expand_time(match: re.Match[str]) -> str:
+    hour = int(match.group(1))
+    minute = int(match.group(2))
+    suffix = match.group(3) or ""
+    pieces = [_words(hour)]
+    if minute == 0:
+        pieces.append("o clock")
+    elif minute < 10:
+        pieces.extend(["oh", _words(minute)])
+    else:
+        pieces.append(_words(minute))
+    if suffix:
+        suffix = suffix.lower().replace(".", "")
+        pieces.extend(list(suffix))
+    return " ".join(pieces)
+
+
+def _expand_bare_hour_time(match: re.Match[str]) -> str:
+    hour = int(match.group(1))
+    suffix = re.sub(r"[^A-Za-z]", "", match.group(2)).lower()
+    return f"{_words(hour)} {' '.join(suffix)}"
+
+
+def _expand_version(match: re.Match[str]) -> str:
+    return " point ".join(_words(int(part)) for part in match.group(0).split("."))
+
+
+def _expand_decimal(match: re.Match[str]) -> str:
+    whole, frac = match.group(1), match.group(2)
+    return f"{_words(int(whole))} point {_digit_words(frac)}"
+
+
+def _expand_ordinal(match: re.Match[str]) -> str:
+    return _words(int(match.group(1)), ordinal=True)
+
+
+def _expand_number(match: re.Match[str]) -> str:
+    value = match.group(0).replace(",", "")
+    if len(value) >= 5 and not value.startswith("20"):
+        return _digit_words(value)
+    return _words(int(value))
+
+
+def _expand_phone(match: re.Match[str]) -> str:
+    left, right = match.group(1), match.group(2)
+    return f"{_digit_words(left)}, {_digit_words(right)}"
+
+
+def _expand_acronym(match: re.Match[str]) -> str:
+    acronym = match.group(0)
+    if len(acronym) <= 1:
+        return acronym
+    return " ".join(LETTER_NAMES.get(ch, ch) for ch in acronym)
+
+
+def normalize_text(text: str) -> str:
+    text = text.translate(PUNCT_TRANSLATION)
+    text = re.sub(r"\s+", " ", text).strip()
+
+    for src, dst in WORD_OVERRIDES.items():
+        text = re.sub(rf"\b{re.escape(src)}\b", dst, text)
+    for src, dst in ABBREVIATIONS.items():
+        text = re.sub(rf"\b{re.escape(src)}", dst, text, flags=re.IGNORECASE)
+
+    text = re.sub(r"\b([A-Z])(?:\.([A-Z]))+\.", lambda m: " ".join(re.findall(r"[A-Z]", m.group(0))), text)
+    text = re.sub(
+        r"\b(apartment|apt\.?|suite|unit|room|flight|extension|order|invoice|locker|aisle|gate)\s+([A-Za-z]?\d{1,4}[A-Za-z]?)\b",
+        _expand_labeled_identifier,
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(
+        r"\b(\d{3})(?=\s+(?:North|South|East|West)\b)",
+        _expand_street_number,
+        text,
+        flags=re.IGNORECASE,
+    )
+    text = re.sub(r"\$(\d[\d,]*(?:\.\d{1,2})?)", _expand_money, text)
+    text = re.sub(r"\b(0?[1-9]|1[0-2])/(0?[1-9]|[12]\d|3[01])/(20\d{2}|19\d{2})\b", _expand_date_slash, text)
+    text = re.sub(r"\b(\d{1,2}):(\d{2})\s*([AaPp]\.?\s*[Mm]\.?)?\b", _expand_time, text)
+    text = re.sub(r"\b(\d{1,2})\s*([AaPp]\.?\s*[Mm]\.?)\b", _expand_bare_hour_time, text)
+    text = re.sub(r"\b(\d{3})-(\d{4})\b", _expand_phone, text)
+    text = re.sub(r"\b\d+(?:\.\d+){2,}\b", _expand_version, text)
+    text = re.sub(r"\b(\d+)\.(\d+)\b", _expand_decimal, text)
+    text = re.sub(r"\b(\d+)(st|nd|rd|th)\b", _expand_ordinal, text, flags=re.IGNORECASE)
+    text = re.sub(r"\b\d[\d,]*\b", _expand_number, text)
+    text = re.sub(r"\b[A-Z]{2,}\b", _expand_acronym, text)
+    text = re.sub(r",(?:\s*,)+", ",", text)
+    text = re.sub(r",\s*([.!?])", r"\1", text)
+    text = re.sub(r"\s+([,;:.!?])", r"\1", text)
+    text = re.sub(r"([,;:.!?])(?=\S)", r"\1 ", text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+def _configure_espeak() -> None:
+    global _ESPEAK_CONFIGURED
+    if _ESPEAK_CONFIGURED:
+        return
+
+    # Prefer the persistent distro library for long Linux preprocessing jobs.
+    # espeakng-loader extracts a temporary shared object, which can exhaust mmap
+    # resources when phonemizer repeatedly creates backends over a large corpus.
+    system_libraries = (
+        Path("/usr/lib/x86_64-linux-gnu/libespeak-ng.so.1"),
+        Path("/usr/lib/aarch64-linux-gnu/libespeak-ng.so.1"),
+        Path("/usr/lib64/libespeak-ng.so.1"),
+    )
+    system_library = next((path for path in system_libraries if path.is_file()), None)
+    if system_library is not None:
+        os.environ.setdefault("PHONEMIZER_ESPEAK_LIBRARY", str(system_library))
+    else:
+        import espeakng_loader
+
+        os.environ.setdefault("PHONEMIZER_ESPEAK_LIBRARY", espeakng_loader.get_library_path())
+        os.environ.setdefault("ESPEAK_DATA_PATH", espeakng_loader.get_data_path())
+        espeakng_loader.make_library_available()
+        espeakng_loader.load_library()
+    _ESPEAK_CONFIGURED = True
+
+
+def phonemize_normalized_text(normalized_text: str) -> str:
+    global _ESPEAK_BACKEND
+    _configure_espeak()
+    from phonemizer.backend import EspeakBackend
+    from phonemizer.separator import Separator
+
+    if _ESPEAK_BACKEND is None:
+        _ESPEAK_BACKEND = EspeakBackend(
+            language="en-us",
+            preserve_punctuation=True,
+            with_stress=True,
+            language_switch="remove-flags",
+        )
+    return _ESPEAK_BACKEND.phonemize(
+        [normalized_text],
+        separator=Separator(phone=" ", word=" | ", syllable=""),
+        strip=True,
+        njobs=1,
+    )[0]
+
+
+def tokenize_phoneme_text(phoneme_text: str) -> list[str]:
+    text = phoneme_text.replace("|", " <word> ")
+    text = re.sub(r"([,;:.!?])", r" \1 ", text)
+    tokens = [tok for tok in re.split(r"\s+", text.strip()) if tok]
+    return tokens
+
+
+def run_frontend(text: str) -> FrontendOutput:
+    normalized = normalize_text(text)
+    phoneme_text = phonemize_normalized_text(normalized)
+    tokens = tokenize_phoneme_text(phoneme_text)
+    return FrontendOutput(
+        raw_text=text,
+        normalized_text=normalized,
+        phoneme_text=phoneme_text,
+        tokens=tokens,
+        token_count=len(tokens),
+    )
+
+
+def _iter_input_rows(path: Path):
+    with path.open("r", encoding="utf-8") as f:
+        for line_number, line in enumerate(f, 1):
+            line = line.strip()
+            if not line:
+                continue
+            if line.startswith("{"):
+                row = json.loads(line)
+                text = row.get("target_text") or row.get("text") or row.get("source_text")
+                if not text:
+                    raise ValueError(f"No text field found at {path}:{line_number}")
+                yield row, str(text)
+            else:
+                yield {"line_number": line_number}, line
+
+
+def main() -> None:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    if hasattr(sys.stderr, "reconfigure"):
+        sys.stderr.reconfigure(encoding="utf-8", errors="replace")
+
+    ap = argparse.ArgumentParser(description="Inflect-Nano-v2 English text frontend.")
+    ap.add_argument("--text", help="Single text string to normalize and phonemize.")
+    ap.add_argument("--input", type=Path, help="Text file or JSONL to process.")
+    ap.add_argument("--out", type=Path, help="Output JSONL path for --input.")
+    args = ap.parse_args()
+
+    if bool(args.text) == bool(args.input):
+        raise SystemExit("Provide exactly one of --text or --input.")
+
+    if args.text:
+        print(json.dumps(asdict(run_frontend(args.text)), ensure_ascii=False, indent=2))
+        return
+
+    if not args.out:
+        raise SystemExit("--out is required with --input.")
+
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    with args.out.open("w", encoding="utf-8") as f:
+        for metadata, text in _iter_input_rows(args.input):
+            result = asdict(run_frontend(text))
+            result["metadata"] = metadata
+            f.write(json.dumps(result, ensure_ascii=False) + "\n")
+    print(f"Wrote {args.out}")
+
+
+if __name__ == "__main__":
+    main()

python/inflect_ax_tts/tts.py

@@ -0,0 +1,170 @@
+"""InflectTTS: two-stage (encoder/decoder AXMODEL) VITS TTS pipeline.
+
+Pipeline (per text chunk):
+
+    text -> [Host: eSpeak phonemize + symbol ids + intersperse(add_blank)]
+         -> tokens[1,256] int (0-padded) + x_lengths[1]
+         -> encoder.axmodel -> m_p/logs_p[1,192,256], logw[1,1,256]
+         -> [Host: first x_lengths frames; w=exp(logw)*length_scale; ceil;
+             generate_path; attn matmul -> T' frames;
+             z_p = m_p' + randn(seed)*exp(logs_p')*variation]
+         -> Tp=512 chunks (64-frame overlap crossfade) -> decoder.axmodel
+         -> waveform blocks, tail trimmed
+         -> edge fade 5 ms + sentence pauses + clip [-1,1]
+         -> 24 kHz mono float32
+
+The same class drives both hardware targets: AX620E and AX637 AXMODELs share
+the identical shape contract, so switching target = switching model paths.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+
+from . import host_chain
+from .backend import ModelSession
+from .frontend import intersperse, text_to_token_ids
+from .wav_io import write_wav
+
+# Deterministic EXPORT parity baseline (export/model_meta.json numeric_baseline):
+# cleaned_text_to_sequence("ðə kwɪk"), 7 phonemes.
+DUMMY_PHONEME_IDS = [81, 83, 16, 53, 65, 102, 53]
+
+
+class InflectTTS:
+    ENCODER_T = host_chain.ENCODER_T
+    DECODER_TP = host_chain.DECODER_TP
+    SAMPLE_RATE = host_chain.SAMPLE_RATE
+
+    def __init__(
+        self,
+        encoder_path: str | Path,
+        decoder_path: str | Path,
+        backend: str = "auto",
+    ) -> None:
+        self.encoder = ModelSession(encoder_path, backend)
+        self.decoder = ModelSession(decoder_path, backend)
+
+    # ------------------------------------------------------------------
+    # Encoder + host chain
+    # ------------------------------------------------------------------
+    def _run_encoder(
+        self, token_ids: list[int], length_scale: float
+    ) -> tuple[np.ndarray, np.ndarray, int]:
+        """token ids (already interspersed) -> (m_p_e [T',C], logs_p_e, T')."""
+        x_len = len(token_ids)
+        if x_len > self.ENCODER_T:
+            raise ValueError(
+                f"token sequence length {x_len} exceeds encoder static T={self.ENCODER_T}"
+            )
+        tok_dtype = self.encoder.input_dtype("tokens")
+        len_dtype = self.encoder.input_dtype("x_lengths")
+        tokens = np.zeros((1, self.ENCODER_T), dtype=tok_dtype)
+        tokens[0, :x_len] = np.asarray(token_ids, dtype=tok_dtype)
+        x_lengths = np.asarray([x_len], dtype=len_dtype)
+        out = self.encoder.run({"tokens": tokens, "x_lengths": x_lengths})
+        m_p, logs_p, logw = out["m_p"], out["logs_p"], out["logw"]
+        # Only the first x_len frames are valid (rest is padding, x_mask-zeroed).
+        return host_chain.expand_priors(
+            logw, m_p, logs_p, x_len, length_scale=length_scale
+        )
+
+    def _decode_z_p(self, z_p: np.ndarray) -> np.ndarray:
+        """z_p [C, T'] -> wav [T'*256] via chunked decoder."""
+        z_dtype = self.decoder.input_dtype("z_p")
+
+        def run_chunk(z_chunk: np.ndarray) -> np.ndarray:
+            out = self.decoder.run({"z_p": z_chunk[None].astype(z_dtype)})
+            return np.asarray(out["wav"], dtype=np.float32).reshape(-1)
+
+        return host_chain.decode_waveform(
+            z_p, run_chunk, self.DECODER_TP, host_chain.DECODER_OVERLAP
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+    def synthesize_tokens(
+        self,
+        token_ids: list[int],
+        *,
+        speed: float = 1.0,
+        variation: float = 0.667,
+        seed: int = 0,
+    ) -> tuple[int, np.ndarray]:
+        """Synthesize from raw phoneme ids (NOT interspersed; blank added here).
+
+        Skips the eSpeak text frontend — useful for tests or when the frontend
+        runs elsewhere. Mirrors one chunk of origin model.infer.
+        """
+        if not 0.5 <= speed <= 2.0:
+            raise ValueError("speed must be between 0.5 and 2.0")
+        if not 0.0 <= variation <= 1.0:
+            raise ValueError("variation must be between 0.0 and 1.0")
+        sequence = intersperse(list(token_ids), 0)
+        m_p_e, logs_p_e, _ = self._run_encoder(sequence, 1.0 / speed)
+        z_p = host_chain.inject_noise(m_p_e, logs_p_e, variation, seed)
+        wav = self._decode_z_p(z_p)
+        return self.SAMPLE_RATE, np.clip(wav, -1.0, 1.0)
+
+    def _token_chunks(self, text: str) -> list[list[int]]:
+        """text -> list of interspersed token id lists, each <= ENCODER_T-1."""
+        ids = text_to_token_ids(text)  # interspersed, 2N+1
+        if len(ids) <= self.ENCODER_T - 1:
+            return [ids]
+        words = text.split()
+        if len(words) < 2:
+            raise ValueError(
+                f"single unbreakable chunk produces {len(ids)} tokens "
+                f"(> {self.ENCODER_T - 1}); shorten the text"
+            )
+        mid = len(words) // 2
+        return self._token_chunks(" ".join(words[:mid])) + self._token_chunks(
+            " ".join(words[mid:])
+        )
+
+    def synthesize(
+        self,
+        text: str,
+        *,
+        speed: float = 1.0,
+        variation: float = 0.667,
+        seed: int = 0,
+    ) -> tuple[int, np.ndarray]:
+        """Full text -> 24 kHz mono waveform (mirrors origin inference.py)."""
+        normalized = " ".join(text.split())
+        if not normalized:
+            raise ValueError("Text must not be empty.")
+        if not 0.5 <= speed <= 2.0:
+            raise ValueError("speed must be between 0.5 and 2.0")
+        if not 0.0 <= variation <= 1.0:
+            raise ValueError("variation must be between 0.0 and 1.0")
+        length_scale = 1.0 / speed
+
+        chunks = host_chain.split_text(normalized)
+        pieces: list[np.ndarray] = []
+        prev_ending = ""
+        index = 0
+        for chunk in chunks:
+            for token_ids in self._token_chunks(chunk):
+                if index:
+                    pause = host_chain.boundary_pause_seconds(prev_ending)
+                    pieces.append(
+                        np.zeros(
+                            host_chain.seconds_to_samples(pause), dtype=np.float32
+                        )
+                    )
+                m_p_e, logs_p_e, _ = self._run_encoder(token_ids, length_scale)
+                z_p = host_chain.inject_noise(m_p_e, logs_p_e, variation, seed + index)
+                wav = self._decode_z_p(z_p)
+                pieces.append(host_chain.edge_fade(wav, self.SAMPLE_RATE))
+                index += 1
+            prev_ending = chunk
+        waveform = np.clip(np.concatenate(pieces), -1.0, 1.0)
+        return self.SAMPLE_RATE, waveform
+
+    def save(self, text: str, output: str | Path, **kwargs) -> Path:
+        sample_rate, waveform = self.synthesize(text, **kwargs)
+        return write_wav(output, waveform, sample_rate)

python/inflect_ax_tts/wav_io.py

@@ -0,0 +1,22 @@
+"""16-bit PCM WAV writer (stdlib only, no soundfile dependency)."""
+
+from __future__ import annotations
+
+import wave
+from pathlib import Path
+
+import numpy as np
+
+
+def write_wav(path: str | Path, waveform: np.ndarray, sample_rate: int = 24000) -> Path:
+    """Write float32 mono waveform in [-1, 1] as 16-bit PCM WAV."""
+    destination = Path(path)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    pcm = np.clip(np.asarray(waveform, dtype=np.float32), -1.0, 1.0)
+    pcm16 = (pcm * 32767.0).round().astype("<i2")
+    with wave.open(str(destination), "wb") as handle:
+        handle.setnchannels(1)
+        handle.setsampwidth(2)
+        handle.setframerate(sample_rate)
+        handle.writeframes(pcm16.tobytes())
+    return destination

python/requirements.txt

@@ -0,0 +1,11 @@
+# Inflect AX TTS Python SDK dependencies
+# Runtime (on-device / host with AX runtime):
+numpy>=1.24
+# pyaxengine (PyPI package name: axengine) — NPU runtime, required for .axmodel files:
+axengine>=0.1.3
+# Text frontend (only needed for text -> phonemes; not for synthesize_tokens):
+phonemizer>=3.0
+espeakng-loader>=0.2
+num2words>=0.5
+# Host numeric stand-in (run export/*.onnx on a machine without NPU):
+onnxruntime>=1.16

python/tests/test_host_chain.py

@@ -0,0 +1,244 @@
+#!/usr/bin/env python3
+"""Host-chain unit tests for the Inflect AX TTS Python SDK.
+
+Runs on a plain host without NPU: onnxruntime is used as a numeric stand-in
+for the AXMODEL runtime (the SDK pipeline above the session layer is identical
+for both backends; see README.md for what is NOT covered by this).
+
+Runnable two ways:
+    python tests/test_host_chain.py     # plain script, exit code 0 on pass
+    pytest tests/                       # if pytest is installed
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import numpy as np
+
+SDK_ROOT = Path(__file__).resolve().parents[1]
+PKG_DIR = Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(SDK_ROOT))
+
+from inflect_ax_tts import DUMMY_PHONEME_IDS, InflectTTS  # noqa: E402
+from inflect_ax_tts import host_chain  # noqa: E402
+from inflect_ax_tts.frontend import intersperse  # noqa: E402
+
+CONVERT_DIR = PKG_DIR / "model_convert"
+REF_NPZ = CONVERT_DIR / "export" / "reference_io.npz"
+ENCODER_ONNX = CONVERT_DIR / "export" / "encoder.onnx"
+DECODER_ONNX = CONVERT_DIR / "export" / "decoder.onnx"
+
+
+def _cosine(a: np.ndarray, b: np.ndarray) -> float:
+    a = np.asarray(a, dtype=np.float64).ravel()
+    b = np.asarray(b, dtype=np.float64).ravel()
+    assert a.shape == b.shape, f"shape {a.shape} vs {b.shape}"
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b) + 1e-30))
+
+
+def _torch_reference_expand(logw, m_p, logs_p, x_len, length_scale):
+    """Replicates export/export_onnx.py:host_expand with torch (ground truth)."""
+    import torch
+
+    def sequence_mask(lengths, max_length):
+        return torch.arange(max_length).unsqueeze(0) < lengths.unsqueeze(1)
+
+    x_lengths = torch.LongTensor([x_len])
+    x_mask = sequence_mask(x_lengths, logw.shape[-1]).unsqueeze(1).float()
+    w = torch.exp(torch.from_numpy(logw)) * x_mask * length_scale
+    w_ceil = torch.ceil(w)
+    y_lengths = torch.clamp_min(torch.sum(w_ceil, [1, 2]), 1).long()
+    y_len = int(y_lengths.item())
+    y_mask = sequence_mask(y_lengths, y_len).unsqueeze(1).float()
+    attn_mask = x_mask.unsqueeze(2) * y_mask.unsqueeze(-1)
+    # generate_path (origin/runtime/commons.py)
+    cum = torch.cumsum(w_ceil, -1).view(-1)
+    path = sequence_mask(cum, y_len).float().view(1, 1, -1, y_len)
+    path = path - torch.nn.functional.pad(path, (0, 0, 1, 0))[:, :, :-1]
+    attn = path.transpose(2, 3) * attn_mask  # [1, 1, T', T]
+    m_p_e = torch.matmul(attn.squeeze(1), torch.from_numpy(m_p).transpose(1, 2))
+    logs_p_e = torch.matmul(attn.squeeze(1), torch.from_numpy(logs_p).transpose(1, 2))
+    return m_p_e[0].numpy(), logs_p_e[0].numpy(), y_len
+
+
+# ---------------------------------------------------------------------------
+# Tests
+# ---------------------------------------------------------------------------
+
+def test_expand_priors_matches_torch_reference():
+    """numpy host chain (durations + generate_path + matmul) vs torch."""
+    ref = np.load(REF_NPZ)
+    logw, m_p, logs_p = ref["logw_torch"], ref["m_p_torch"], ref["logs_p_torch"]
+    x_len = int(ref["x_lengths"][0])
+    for length_scale in (1.0, 0.8, 1.6):
+        exp_m, exp_l, y_len = host_chain.expand_priors(
+            logw, m_p, logs_p, x_len, length_scale
+        )
+        ref_m, ref_l, ref_y = _torch_reference_expand(
+            logw, m_p, logs_p, x_len, length_scale
+        )
+        assert y_len == ref_y, f"T' {y_len} vs torch {ref_y}"
+        assert np.allclose(exp_m, ref_m, atol=1e-5), (
+            f"m_p_e max diff {np.abs(exp_m - ref_m).max():.2e} @ls={length_scale}"
+        )
+        assert np.allclose(exp_l, ref_l, atol=1e-5), (
+            f"logs_p_e max diff {np.abs(exp_l - ref_l).max():.2e} @ls={length_scale}"
+        )
+    print("[PASS] expand_priors == torch host_expand (3 length scales)")
+
+
+def test_encoder_padding_semantics_ort():
+    """Padded static-shape encoder call == unpadded reference (first x_len frames)."""
+    import onnxruntime as ort
+
+    ref = np.load(REF_NPZ)
+    tokens = np.zeros((1, 256), dtype=np.int64)
+    x_len = int(ref["x_lengths"][0])
+    tokens[0, :x_len] = ref["tokens"][0]
+    sess = ort.InferenceSession(str(ENCODER_ONNX), providers=["CPUExecutionProvider"])
+    m_p, logs_p, logw = sess.run(
+        None, {"tokens": tokens, "x_lengths": np.asarray([x_len], dtype=np.int64)}
+    )
+    for name, got, want in (
+        ("m_p", m_p, ref["m_p_torch"]),
+        ("logs_p", logs_p, ref["logs_p_torch"]),
+        ("logw", logw, ref["logw_torch"]),
+    ):
+        cos = _cosine(got[..., :x_len], want[..., :x_len])
+        assert cos >= 0.999999, f"{name} cos {cos}"
+    print("[PASS] encoder T=256 padding: first-x_len frames match torch ref")
+
+
+def test_decoder_chunk_compose_ort():
+    """SDK chunked decode (Tp=512 path) vs EXPORT reference chain wav."""
+    import onnxruntime as ort
+
+    ref = np.load(REF_NPZ)
+    z_p = ref["z_p"][0]  # [192, 51]
+    sess = ort.InferenceSession(str(DECODER_ONNX), providers=["CPUExecutionProvider"])
+
+    def run_chunk(z_chunk: np.ndarray) -> np.ndarray:
+        return sess.run(None, {"z_p": z_chunk[None].astype(np.float32)})[0].reshape(-1)
+
+    wav = host_chain.decode_waveform(z_p, run_chunk)
+    want = ref["wav_onnx_chain"].reshape(-1)
+    assert wav.shape == want.shape, f"{wav.shape} vs {want.shape}"
+    # Right zero-padding bleeds into the trailing frames (flow/dec conv
+    # receptive field; SIMULATE §4 uses the same metric convention): crop
+    # min(64, T'/4) frames off the right edge for the comparison.
+    t_prime = z_p.shape[1]
+    crop = min(64, t_prime // 4) * host_chain.HOP_LENGTH
+    cos = _cosine(wav[:-crop], want[:-crop])
+    assert cos >= 0.9999, f"decoder compose cos {cos}"
+    head = _cosine(wav[: (t_prime // 2) * host_chain.HOP_LENGTH],
+                   want[: (t_prime // 2) * host_chain.HOP_LENGTH])
+    assert head >= 0.999999, f"decoder compose head cos {head}"
+    print(f"[PASS] decoder chunk compose vs EXPORT chain: cos={cos:.9f} (right-edge crop), head cos={head:.9f}")
+
+
+def test_decoder_multi_chunk_compose_ort():
+    """T'>512 multi-chunk path: overlap crossfade vs single dynamic ORT call.
+
+    Uses synthetic z_p (not a real prior): checks stitching correctness only,
+    comparing against the dynamic-shape ONNX decoder run over the full length.
+    Boundary regions are excluded from the metric (conv receptive-field bleed
+    is expected; EXPORT_NOTES §5.3).
+    """
+    import onnxruntime as ort
+
+    rng = np.random.default_rng(1234)
+    t_prime = 512 + 300
+    z_p = rng.standard_normal((192, t_prime), dtype=np.float32) * 0.5
+    sess = ort.InferenceSession(str(DECODER_ONNX), providers=["CPUExecutionProvider"])
+    want = sess.run(None, {"z_p": z_p[None]})[0].reshape(-1)
+    got = host_chain.decode_waveform(
+        z_p, lambda z: sess.run(None, {"z_p": z[None]})[0].reshape(-1)
+    )
+    assert got.shape == want.shape
+    # Exclude 32 frames around the chunk boundary (frame 512) and the edges.
+    hop = host_chain.HOP_LENGTH
+    lo, hi = (512 + 32) * hop, (t_prime - 32) * hop
+    interior = _cosine(got[lo:hi], want[lo:hi])
+    head = _cosine(got[: 480 * hop], want[: 480 * hop])
+    assert interior >= 0.999, f"multi-chunk interior cos {interior}"
+    assert head >= 0.999, f"multi-chunk head cos {head}"
+    print(f"[PASS] multi-chunk compose: head cos={head:.6f}, interior cos={interior:.6f}")
+
+
+def test_synthesize_tokens_end_to_end_ort():
+    """Full SDK pipeline on ORT stand-in: length, determinism, finiteness."""
+    tts = InflectTTS(ENCODER_ONNX, DECODER_ONNX, backend="onnxruntime")
+    sr, wav1 = tts.synthesize_tokens(DUMMY_PHONEME_IDS, seed=0, variation=0.667)
+    _, wav2 = tts.synthesize_tokens(DUMMY_PHONEME_IDS, seed=0, variation=0.667)
+    _, wav3 = tts.synthesize_tokens(DUMMY_PHONEME_IDS, seed=1, variation=0.667)
+    ref = np.load(REF_NPZ)
+    assert sr == 24000
+    # Same Host chain as EXPORT baseline -> same T'=51 -> 13056 samples.
+    assert wav1.size == int(ref["wav_onnx_chain"].size), (
+        f"{wav1.size} vs baseline {ref['wav_onnx_chain'].size}"
+    )
+    assert np.array_equal(wav1, wav2), "same seed must be bit-reproducible"
+    assert not np.array_equal(wav1, wav3), "different seed must differ"
+    assert np.isfinite(wav1).all()
+    assert np.abs(wav1).max() <= 1.0
+    print(f"[PASS] e2e synthesize_tokens: {wav1.size} samples, deterministic, bounded")
+
+
+def test_frontend_symbol_mapping():
+    """Symbol table mapping: literal IPA baseline string -> EXPORT baseline ids.
+
+    export/model_meta.json numeric_baseline was built with
+    cleaned_text_to_sequence("ðə kwɪk") — a literal IPA string, NOT eSpeak
+    output (eSpeak with_stress would add stress marks)."""
+    from inflect_ax_tts.symbols import symbols
+
+    symbol_to_id = {s: i for i, s in enumerate(symbols)}
+    ids = [symbol_to_id[ch] for ch in "ðə kwɪk"]
+    assert ids == DUMMY_PHONEME_IDS, f"{ids} vs {DUMMY_PHONEME_IDS}"
+    assert intersperse(ids, 0) == [0, 81, 0, 83, 0, 16, 0, 53, 0, 65, 0, 102, 0, 53, 0]
+    print("[PASS] symbol mapping: 'ðə kwɪk' -> baseline phoneme ids")
+
+
+def test_frontend_smoke():
+    """eSpeak frontend structural check (skipped when espeak is unavailable)."""
+    try:
+        from inflect_ax_tts.frontend import text_to_token_ids
+        ids = text_to_token_ids("the quick")
+    except Exception as exc:  # espeak missing on host -> skip, not a failure
+        print(f"[SKIP] frontend (espeak unavailable: {exc})")
+        return
+    assert len(ids) % 2 == 1, "interspersed sequence must be odd length"
+    assert ids[::2] == [0] * (len(ids) // 2 + 1), "blanks must interleave"
+    from inflect_ax_tts.symbols import symbols
+
+    assert all(0 <= i < len(symbols) for i in ids)
+    print(f"[PASS] frontend smoke: 'the quick' -> {len(ids)} interspersed ids")
+
+
+ALL_TESTS = [
+    test_expand_priors_matches_torch_reference,
+    test_encoder_padding_semantics_ort,
+    test_decoder_chunk_compose_ort,
+    test_decoder_multi_chunk_compose_ort,
+    test_synthesize_tokens_end_to_end_ort,
+    test_frontend_symbol_mapping,
+    test_frontend_smoke,
+]
+
+
+def main() -> int:
+    failures = 0
+    for test in ALL_TESTS:
+        try:
+            test()
+        except Exception as exc:  # noqa: BLE001
+            failures += 1
+            print(f"[FAIL] {test.__name__}: {exc}")
+    print(f"{'ALL PASS' if not failures else f'{failures} FAILURES'} ({len(ALL_TESTS)} tests)")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

run.sh

@@ -3,16 +3,28 @@ set -euo pipefail
 TEXT="${1:-Hello world, this is Inflect Micro V2.}"
 OUTPUT="${2:-output.wav}"
 MODE="${3:-cli}"
-CHIP="${4:-ax650}"
+CHIP="${4:-ax620e}"
 
-SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
-cd "$SCRIPT_DIR/python"
+cd "$(dirname "$0")"
 
-if [ "$MODE" = "server" ]; then
+if [ "$CHIP" = "ax650" ]; then
+  cd python
+  if [ "$MODE" = "server" ]; then
     echo "🌐 Starting OpenAI TTS Server on port ${5:-8000}..."
     python3 -m inflect_tts_sdk.server --port "${5:-8000}" --chip "$CHIP"
-else
+  else
     echo "🎤 ${TEXT}"
     python3 -m inflect_tts_sdk --text "${TEXT}" --output "${OUTPUT}" --chip "$CHIP"
     echo "🔊 ${OUTPUT}"
+  fi
+else
+  if [ "$MODE" = "server" ]; then
+    echo "⚠️ server 模式仅支持 ax650,已切换为 CLI 模式"
+  fi
+  echo "🎤 ${TEXT} (${CHIP}, encoder+decoder 全 NPU)"
+  python3 python/example.py \
+    --encoder "models/${CHIP}/encoder.axmodel" \
+    --decoder "models/${CHIP}/decoder.axmodel" \
+    --text "${TEXT}" --output "${OUTPUT}"
+  echo "🔊 ${OUTPUT}"
 fi

setup.sh

@@ -1,11 +1,16 @@
 #!/usr/bin/env bash
 set -euo pipefail
-echo "=== Inflect-Micro-v2 TTS Setup (AX650) ==="
-echo "Installing dependencies..."
-pip install -q numpy onnxruntime soundfile unidecode inflect num2words espeakng-loader fastapi uvicorn
+echo "=== Inflect-Micro-v2 TTS Setup (AX650 / AX620E / AX637) ==="
 
-echo "Installing pyaxengine..."
-pip install "pyaxengine @ git+https://github.com/AXERA-TECH/pyaxengine.git"
+echo "Installing Python dependencies..."
+pip install -q numpy onnxruntime soundfile unidecode inflect num2words \
+  espeakng-loader phonemizer fastapi uvicorn
+
+echo "Installing axengine (pyaxengine)..."
+pip install -q axengine || pip install "pyaxengine @ git+https://github.com/AXERA-TECH/pyaxengine.git"
 
 echo ""
-echo "✅ Setup complete. Run: bash run.sh 'Hello!' output.wav"
+echo "✅ Setup complete. 用法:"
+echo "  bash run.sh 'Hello!' output.wav cli ax650    # AX650(老 SDK)"
+echo "  bash run.sh 'Hello!' output.wav cli ax620e   # AX620E(新 SDK,双 NPU)"
+echo "  bash run.sh 'Hello!' output.wav cli ax637    # AX637(新 SDK,双 NPU)"