@bingtang-rn/react-native-vosk for HarmonyOS

本项目基于 react-native-vosk 开发，为 React Native 鸿蒙（OpenHarmony）适配版本。如果在使用过程中有任何问题，可以在GitCode提Issue，会及时跟进。issue地址：issues。

版本对应关系

| 鸿蒙适配包版本 | 原始库版本 | 支持 RN 版本 | Autolink | 编译 API 版本 | | ------------ | ---------- | ------------ | -------- | ------------- | | 见发布记录 | 2.1.7 | 0.72+ | 是 | API17+ |

安装

npm install @bingtang-rn/react-native-vosk

使用

import { loadModel, start, stop, unload, onResult, onPartialResult, onFinalResult, onError, onTimeout } from 'react-native-vosk';

// 加载模型
await loadModel('model-zh-cn');

// 监听识别结果
const resultSub = onResult((text) => console.log('Result:', text));
const partialSub = onPartialResult((text) => console.log('Partial:', text));
const finalSub = onFinalResult((text) => console.log('Final:', text));
const errorSub = onError((err) => console.error('Error:', err));
const timeoutSub = onTimeout(() => console.log('Timed out'));

// 启动识别（默认模式）
await start();

// 带语法/超时启动
await start({ grammar: ['hello', 'world', '[unk]'] });
await start({ timeout: 5000 });

// 停止识别
stop();

// 卸载模型
unload();

import 时使用原库名 'react-native-vosk'，而非鸿蒙包名。

平台差异：

• HarmonyOS 使用 Core Speech Kit 替代 Vosk 引擎，仅支持中文（zh-CN）离线识别
• loadModel(path) 的 path 参数仅用于语言标识（如 'model-zh-cn'→中文），不加载自定义模型文件
• 已加载引擎时再次调用 loadModel(path) 会直接复用当前引擎，不会中断正在进行的识别
• grammar 参数通过会话热词提高命中率，并在适配层过滤列表外结果
• 引擎使用长语音模式，短暂停顿只结束当前子句，调用 stop() 或达到 timeout 才结束会话
• timeout 单位为毫秒；模块定时器按传入值结束识别，原生长语音时长限制为 20000ms～8 小时

权限要求：

• 需在 module.json5 声明 ohos.permission.MICROPHONE（user_grant，运行时由原生模块自动申请）

Link

| 版本 | 是否支持 Autolink | |------|------------------| | 当前版本 | 是 |

如使用版本支持 Autolink 且工程已接入，可跳过手动配置。

说明：本模块需要同时在 C++ 侧和 ETS 侧注册 Package。

1. Overrides RN SDK

在工程根目录 oh-package.json5 添加：

{
  "overrides": {
    "@rnoh/react-native-openharmony": "./react_native_openharmony"
  }
}

2. 引入原生端依赖

打开 entry/oh-package.json5，添加：

"dependencies": {
  "@bingtang-rn/react-native-vosk": "file:../../node_modules/@bingtang-rn/react-native-vosk/harmony/vosk.har"
}

执行 ohpm install。

3. 配置 CMakeLists

打开 entry/src/main/cpp/CMakeLists.txt，添加：

set(OH_MODULES "${CMAKE_CURRENT_SOURCE_DIR}/../../../oh_modules")

add_subdirectory("${OH_MODULES}/@bingtang-rn/react-native-vosk/src/main/cpp" ./vosk)

target_link_libraries(rnoh_app PUBLIC vosk)

4. 注册 Package（C++ 侧）

打开 entry/src/main/cpp/PackageProvider.cpp，添加：

#include "VoskPackage.h"

std::vector<std::shared_ptr<Package>> PackageProvider::getPackages(Package::Context ctx) {
    return {
        std::make_shared<VoskPackage>(ctx),
    };
}

5. 注册 Package（ETS 侧）

打开 entry/src/main/ets/RNPackagesFactory.ets，添加：

import { VoskPackage } from '@bingtang-rn/react-native-vosk/ts';

export function createRNPackages(ctx: RNPackageContext): RNPackage[] {
  return [
    new VoskPackage(ctx),
  ];
}

属性 / API

| API | 描述 | 参数 | 返回值 | HarmonyOS 支持 | |-----|------|------|--------|----------------| | loadModel | 加载语音识别模型 | path: string | Promise<void> | ⚠️ 部分支持（path 仅作语言标识，不加载自定义模型文件） | | unload | 卸载模型并停止识别 | 无 | void | ✅ 完全支持 | | start | 启动语音识别 | options?: VoskOptions | Promise<void> | ⚠️ 部分支持（grammar 使用热词与结果过滤近似实现；timeout 原生精度为 ms） | | stop | 停止识别 | 无 | void | ✅ 完全支持 | | onResult | 监听句子完成结果 | cb: (e: string) => void | EmitterSubscription | ✅ 完全支持 | | onPartialResult | 监听部分识别结果 | cb: (e: string) => void | EmitterSubscription | ✅ 完全支持 | | onFinalResult | 监听最终识别结果 | cb: (e: string) => void | EmitterSubscription | ✅ 完全支持 | | onError | 监听错误事件 | cb: (e: any) => void | EmitterSubscription | ✅ 完全支持 | | onTimeout | 监听超时事件 | cb: () => void | EmitterSubscription | ✅ 完全支持 |

平台差异

• loadModel(path)：HarmonyOS Core Speech Kit 使用系统内置离线模型，path 参数仅解析为语言标识（如含 zh-cn/chinese 映射为 'zh-CN'），非中文语言自动回退至中文
• start({ grammar })：grammar 中 [unk] 会被过滤，其余词条作为会话热词提高识别率；适配层忽略空白和常见中英文标点后匹配，只返回列表中的原始短语
• 连续识别：使用 Core Speech Kit 长语音模式，停顿后仍保持当前识别会话，可继续接收后续子句结果

未实现功能

| 功能 | 原因 | |------|------| | 多语言离线模型（en-US/fr-FR 等） | Core Speech Kit 当前仅支持中文（zh-CN）离线识别 | | 自定义模型文件加载 | Core Speech Kit 使用系统内置模型，无加载外部模型 API | | 解码阶段的严格语法匹配 | Core Speech Kit 仅提供热词能力；当前通过适配层结果过滤保证输出范围 |

使用限制

• 需声明 ohos.permission.MICROPHONE（user_grant）
• 需要 HarmonyOS 4.1+（API17+）设备
• Core Speech Kit 离线识别仅支持中文

快速验证（运行 Example）

前置条件

| 依赖 | 版本要求 | |------|----------| | Node.js | >= 18 | | DevEco Studio | 5.0+ / 6.0+ | | HarmonyOS SDK | API 17+ |

运行步骤

1. 克隆仓库

git clone <仓库地址>
cd <仓库目录>

2. 安装依赖并构建

npm install --legacy-peer-deps
npm pack           # 生成 tgz 包（会自动触发 prepare 构建 JS 产物）

3. 进入 example 目录，安装依赖

cd example
npm install --legacy-peer-deps

4. 生成 JS Bundle

npm run dev

产物：harmony/entry/src/main/resources/rawfile/bundle.harmony.js

5. 用 DevEco Studio 打开鸿蒙工程

• 打开 DevEco Studio
• 选择 example/harmony 目录
• 等待 Sync 完成

6. 编译并运行 HAP

在 DevEco Studio 中点击运行按钮，将 HAP 安装到设备/模拟器。

注意：Example 中已预置插件依赖和 Package 注册，无需手动配置 Link。

约束与限制

兼容性

• RNOH: 0.72+
• HarmonyOS SDK: API 17+
• DevEco Studio: 5.0+

遗留问题

无（或列出已知问题）

开源协议

本项目基于 [原始库协议](原始库 LICENSE 链接)，详见 LICENSE 文件。