# mindspore_lite_audio_enhance

**Repository Path**: ybf521/mindspore_lite_audio_enhance

## Basic Information

- **Project Name**: mindspore_lite_audio_enhance
- **Description**: ohos_next上使用mindspore_lites实现音频增强，包括降噪与人声增强、回声消除。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-12
- **Last Updated**: 2026-04-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎧 MindSpore Lite Audio Enhancement Engine (AEC & ANS)

高性能、低延迟的实时音频增强 C++ 核心库，专为 OpenHarmony / HarmonyOS 原生开发设计。集成声学回声消除 (AEC) 与主动降噪 (ANS)，基于 MindSpore Lite 推理框架，支持 CPU/NPU 硬件加速与流式音频处理。

## 📖 项目简介

本项目提供一套完整的音频信号增强管线，包含 **双路径时频域 AEC** 与 **流式 DFSMN/ANS 降噪** 两大核心引擎。底层采用 MindSpore Lite 进行端侧模型推理，结合 FFTW 频域变换、环形缓冲区、零拷贝优化与 N-API 线程安全回调，可直接对接 ArkTS/JS 层实现 UI 进度同步与波形对比可视化。
### 音频降噪
![img_2.png](img/img_2.png)
### 回声消除
![img_3.png](img/img_3.png)

**适用于**：在线会议、语音通话、录音设备、车载语音、耳机通话等对实时性与音质要求较高的场景。

## ✨ 核心特性

| 特性 | 说明 |
| :--- | :--- |
| 🔹 **双引擎架构** | DTLNAEC（频域+时域双路径回声消除）与 AnsEngine（流式降噪）独立解耦，可组合或单独使用 |
| 🔹 **硬件加速** | 支持 MindSpore Lite CPU 与 NNRT（NPU）推理，支持异步加载与执行 |
| 🔹 **流式实时处理** | 环形缓冲区 + 分块推理 + 重叠相加（Overlap-Add），保障低延迟音频流处理 |
| 🔹 **零拷贝优化** | 输入张量直接映射填充后音频数组，消除冗余内存拷贝与对齐开销 |
| 🔹 **OpenHarmony 深度集成** | 原生音频渲染 (ohaudio) + N-API 线程安全函数 (tsfn) 实现主线程 UI 回调 |
| 🔹 **高性能 DSP** | FFTW 单精度 STFT/ISTFT、Fbank 特征提取、自定义窗函数与缩放对齐 |
| 🔹 **全格式支持** | 支持 WAV/MP3/AAC/FLAC/OGG/OPUS/RAW PCM 读写与重采样 |
| 🔹 **性能监控** | 内置 RTF（实时因子）、耗时统计、进度百分比与队列状态追踪 |

## 🧱 架构与核心模块
![img_1.png](img/arc.png)

## 项目结构

```text
.
├── 📄 根目录配置
│   ├── README.md                          # 项目说明文档
│   ├── oh-package.json5                   # 依赖与包管理
│   ├── hvigorfile.ts                      # 构建脚本
│   └── .gitignore
│
├── 📱 AppScope/                           # 应用全局配置
│   ├── app.json5
│   └── resources/base/media/              # 应用图标与启动图
│
└── 📦 entry/                              # 核心业务模块 (HAP)
    ├── src/main/
    │   ├── module.json5                   # 模块声明、路由与权限配置
    │   │
    │   ├── 🎨 ets/                        # ArkTS UI & 业务逻辑层
    │   │   ├── entryability/              # EntryAbility (应用生命周期入口)
    │   │   ├── pages/                     # 界面路由与交互页面
    │   │   │   ├── Index.ets              # 首页/功能控制台
    │   │   │   ├── AudioAEC.ets           # AEC 回声消除控制页
    │   │   │   └── AudioDenoise.ets       # ANS 降噪控制页
    │   │   ├── model/                     # 数据模型与状态管理
    │   │   │   ├── AudioPlayer.ets        # 播放器封装与状态同步
    │   │   │   └── RealTimeWaveform.ets   # 实时波形对比渲染
    │   │   └── utils/                     # 工具类
    │   │       └── FileUtils.ets          # 文件读写与路径解析
    │   │
    │   ├── ⚙️ cpp/                        # C++ Native 核心引擎层
    │   │   ├── CMakeLists.txt             # Native 编译与依赖链接配置
    │   │   ├── napi_init.cpp              # N-API 桥接入口 (ArkTS ↔ C++)
    │   │   ├── include/                   # 核心头文件
    │   │   │   ├── aec_engine.h           # DTLN AEC 双路径引擎
    │   │   │   ├── ans_engine.h           # DFSMN ANS 流式降噪引擎
    │   │   │   ├── model_base.h           # MindSpore Lite 推理基类
    │   │   │   ├── stft_fftw.h            # FFTW STFT/ISTFT 频域处理
    │   │   │   ├── audio_processor.h      # 音频编解码/重采样/IO
    │   │   │   ├── audio_stream_player.h  # OpenHarmony 原生音频流播放
    │   │   │   └── thread_safe_*.h        # 线程安全队列 & UI 回调封装
    │   │   ├── src/                       # 核心算法实现
    │   │   │   ├── aec_engine.cpp
    │   │   │   ├── ans_engine.cpp
    │   │   │   ├── model_base.cpp
    │   │   │   ├── stft_fftw.cpp
    │   │   │   └── audio_*.cpp
    │   │   └── third_party/               # 第三方算法库头文件 (核心摘要)
    │   │       ├── fftw3/                 # FFT 快速傅里叶变换
    │   │       ├── ffmpeg/                # 多格式音频编解码
    │   │       ├── kaldi-native-fbank/    # Fbank 声学特征提取
    │   │       └── soxr/                  # 高质量音频重采样
    │   │
    │   └── resources/
    │       └── resfile/                   # 📀 模型与测试数据
    │           ├── model/                 # .ms AI 推理模型 (支持 CPU/NPU)
    │           ├── double_talk/           # 双讲测试音频 (Mic + Lpb 配对)
    │           └── noisy_wav/             # 噪声/干净语音测试集
    │
    ├── libs/arm64-v8a/                    # 🔌 预编译动态库 (.so)
    │   ├── libmindspore_lite_audio_enhance.so  # 核心增强引擎
    │   ├── libfftw3f.so                       # FFT 数学库
    │   ├── ffmpeg/                            # FFmpeg 编解码组件
    │   └── kaldi/ & soxr/                     # 特征提取与重采样组件
    │
    └── oh_modules/                        # N-API 模块导出与类型声明

```

## 📦 模块说明

| 头文件 | 职责 |
| :--- | :--- |
| `aec_engine.h` | DTLN 双路径 AEC 引擎，频域掩码估计 + 时域波形重建，支持零拷贝输入 |
| `ans_engine.h` | 流式 ANS 引擎，Fbank 特征提取、分块推理、环形缓冲、RTF 统计与进度追踪 |
| `model_base.h` | MindSpore Lite 统一包装类，支持 CPU/NNRT、同步/异步、类型安全张量填充 |
| `stft_fftw.h` | FFTW 单精度 STFT/ISTFT 实现，含 1D 优化路径与对齐内存管理 |
| `audio_processor.h` | 多格式音频读写、重采样、PCM 转换工具类 |
| `audio_stream_player.h` | OpenHarmony 原生音频流播放器，基于 ohaudio API 实现队列驱动播放 |
| `thread_safe_queue.h` | 泛型线程安全队列（`std::condition_variable` + `std::mutex`） |
| `thread_safe_ui_updater.h` | N-API 线程安全回调封装，用于向 ArkTS/JS 推送进度与波形对比数据 |

## 🛠️ 依赖与环境

| 依赖 | 版本/要求                                    |
| :--- |:-----------------------------------------|
| OpenHarmony SDK | API 16+ (Stage 模型推荐)                     |
| MindSpore Lite | `mindspore-lite-cpp` Runtime (含 NNRT 支持) |
| FFTW3 | `fftw3f` (单精度)                           |
| 编译器 | C++11/C++14 兼容 (Clang/GCC)               |
| 构建系统 | CMake 3.16+ / Ohpm / hvigor              |
| 可选 | N-API 绑定层 (用于 ArkTS/JS 集成)               |

## 📦 项目集成

### OpenHarmony 集成步骤

1.  将 .so 与头文件放入 `native/libs` 与 `native/include`
2.  在 `module.json5` 声明 syscap 与 reqPermissions（如需读取外部音频）
3.  通过 N-API 封装暴露 `PredictorConfig` 与 `ProcessAudio` 接口给 ArkTS
4.  调用 `napi_create_threadsafe_function` 绑定 UI 回调

## 💻 使用示例

### 1. 初始化 ANS 引擎（流式降噪）
```cpp
PredictorConfig config;
config.model_path = "/data/storage/el2/base/haps/entry/files/ans_dfsmn.mindir";
config.enable_npu = true; // 启用 NPU 加速
config.is_async = false; // 同步推理
config.lorder = 2; // 上下文帧数
AnsEngine ans_engine(config);
ans_engine.InitializeEngine(config);
ans_engine.InitFbankComputer();
```

### 2. 流式音频处理与进度回调
```cpp
// 在 ArkTS 层注册回调
ThreadSafeProgressCallback progress_cb(env, js_progress_callback);
ThreadSafeWaveContrastCallback wave_cb(env, js_wave_callback);
// 推入音频分块 (PCM int16)
std::vector<uint8_t> pcm_chunk = read_next_chunk();
std::vector<uint8_t> enhanced = ans_engine.Push(pcm_chunk);
// 处理完毕后获取统计
ProcessStats stats = ans_engine.Enhance();
LOGI("RTF: %.3f, Duration: %.2fs, Output Bytes: %zd",
stats.rtf, stats.output_duration_seconds, stats.total_output_bytes);
// 推送波形对比至 UI
ContrastWaveBlock block = ans_engine.GetContrastWaveBlock();
wave_cb.callAsync(std::move(block));
```
### 3. AEC 回声消除（文件/流式）
```cpp
DTLNAEC aec;
aec.Initialize(
"/data/storage/el2/base/haps/entry/files/freq_est_512.ms",
"/data/storage/el2/base/haps/entry/files/time_domain_512.ms"
);
aec.Enhance("mic_input.wav", "speaker_lpb.wav", "aec_output.wav");
```

## 性能&功耗
### 基于Huawei mate70pro
#### 音频降噪
![img_4.png](img/img_4.png)
![img_5.png](img/img_5.png)
![img.png](img/img_11.png)

#### 回声消除
![img_7.png](img/img_7.png)
![img_8.png](img/img_8.png)
![img_9.png](img/img_10.png)

## ⚡ 性能与优化说明

| 优化项 | 实现方式 |
| :--- | :--- |
| **零拷贝输入** | `FillInputTensorRaw` 直接映射填充后缓冲区，避免 `std::vector` 拷贝 |
| **FFTW 计划缓存** | 构造函数预创建 plan_r2c/plan_c2r，使用 `FFTW_ESTIMATE` 避免启动卡顿 |
| **异步模型加载** | `std::future<OH_AI_ModelHandle>` 实现非阻塞加载，首帧无阻塞 |
| **内存对齐** | `fftwf_malloc` 分配对齐内存，提升 SIMD 与 NPU 访存效率 |
| **重叠相加重建** | ISTFT 输出自动归一化与窗口重叠，避免分块边界失真 |
| **RTF 实时监控** | `ProcessStats` 记录实际处理耗时 vs 音频时长，便于性能调优 |

> **📌 注意**：NPU 推理需确保设备支持 NNRT 驱动，且模型已导出为 .ms 或 .om 格式。首次加载 NPU 模型可能存在数百毫秒冷启动延迟，建议后台预加载。


## 📜 许可证与致谢

*   **许可证**：Apache-2.0
*   **致谢**：
    *   **MindSpore Lite**：端侧推理框架
    *   **FFTW**：高性能 FFT 库
    *   **OpenHarmony ohaudio 与 N-API 团队**：原生音频与跨线程回调支持
    *   **音频增强算法参考**：DTLN、DFSMN等开源架构

## 🤝 贡献与支持

*   🐛 **遇到问题？** 请提交 Issue 并附 `ProcessStats` 输出与设备型号
*   🛠️ **欢迎 PR**：模型适配、DSP 优化、ArkTS 绑定示例、性能 benchmark
*   📧 **联系**：yangbaifeng@mail.ustc.edu.cn

> 本项目为 C++ 核心 SDK，ArkTS/JS 绑定层与 UI 示例可按需开源或内部交付。编译与部署请参考 OpenHarmony 官方文档与 MindSpore Lite C++ API 指南。