speechrecognizer

Flutter 语音识别插件，支持 HarmonyOS/OpenHarmony 平台。通过系统语音识别能力（@kit.CoreSpeechKit 的 speechRecognizer）实现实时语音转文字，支持麦克风模式。

1. 安装与使用

1.1 安装方式

在工程目录的 pubspec.yaml 中添加依赖：

方式一：Pub 依赖（推荐）

dependencies:
  speechrecognizer: ^0.0.1

方式二：Git 依赖

dependencies:
  speechrecognizer:
    git:
      url: https://gitcode.com/oh-flutter/speechrecognizer.git
      path: .
      ref: main

方式三：本地路径依赖

dependencies:
  speechrecognizer:
    path: ../speechrecognizer

然后执行：

flutter pub get

1.2 使用案例

使用示例见 speechrecognizer/example 目录。

2. 约束与限制

2.1 兼容性

在以下版本中已测试通过：

Flutter: 3.35.8-ohos-0.0.2
Dart: 3.9.2
SDK: 5.1.0(18)
IDE: DevEco Studio 6.0.2 Release
ROM: 6.0.0.130 SP15

2.2 权限要求

语音识别需要麦克风权限。在 插件 HAR 模块 的 ohos/src/main/module.json5 中已声明：

"requestPermissions": [
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:microphone_reason"
  }
]

若使用 entry 工程（如 example/ohos），需在 entry 的 module.json5 中申请该权限，并补充 reason 与 usedScene 字段：

"requestPermissions": [
  {
    "name": "ohos.permission.MICROPHONE",
    "reason": "$string:microphone_reason",
    "usedScene": {
      "abilities": ["EntryAbility"],
      "when": "inuse"
    }
  }
]

同时在 entry/src/main/resources/base/element/string.json 中提供说明文案：

{
  "string": [
    { "name": "microphone_reason", "value": "用于语音识别功能，需要访问麦克风采集语音数据" }
  ]
}

3. API

"ohos Support" 列：yes 表示 OHOS 支持，no 表示不支持。

3.1 Speechrecognizer（主入口）

Name	return	Description	Type	ohos Support
requestPermission()	Future<bool>	请求麦克风权限，返回是否授权成功	function	yes
startSpeechRecognition({...})	Future<String?>	开始语音识别，返回 sessionId	function	yes
stopSpeechRecognition()	Future<void>	停止语音识别	function	yes
getLastSpeechRecognitionResult()	Future<SpeechRecognitionResult?>	获取最后一次识别结果	function	yes
setListeners({...})	void	设置语音识别事件监听回调	function	yes
removeListeners()	void	移除所有事件监听	function	yes
getPlatformVersion()	Future<String?>	获取平台版本信息	function	yes

3.2 startSpeechRecognition 参数

Name	Description	Type	Default	ohos Support
language	识别语言	String?	`zh-CN`	yes
sessionId	会话 ID，不传则自动生成	String?	`session-{timestamp}`	yes
recognitionMode	识别模式，当前仅支持 `0`（麦克风模式）	int?	`0`	yes
audioInfo	音频配置信息	SpeechAudioInfo?	见下方默认值	yes

3.3 setListeners 回调

Name	Description	Type	ohos Support
onStart	识别开始回调	OnSpeechStart?	yes
onResult	识别结果回调（可能多次触发）	OnSpeechResult?	yes
onComplete	识别完成回调	OnSpeechComplete?	yes
onError	识别出错回调	OnSpeechError?	yes

4. 数据类型

4.1 SpeechRecognitionResult

Name	Description	Type	ohos Support
text	识别出的文本	String	yes
isFinal	当前句子是否为最终结果	bool	yes
isLast	是否为最后一条结果	bool	yes

4.2 SpeechRecognitionStartResult

Name	Description	Type	ohos Support
sessionId	会话 ID	String	yes
message	附加信息	String?	yes

4.3 SpeechRecognitionCompleteResult

Name	Description	Type	ohos Support
sessionId	会话 ID	String	yes
message	完成描述信息	String?	yes

4.4 SpeechRecognitionError

Name	Description	Type	ohos Support
errorCode	错误码	int	yes
errorMessage	错误描述	String	yes

4.5 SpeechAudioInfo

Name	Description	Type	Default	ohos Support
audioType	音频类型	String	`pcm`	yes
sampleRate	采样率	int	`16000`	yes
soundChannel	声道数	int	`1`	yes
sampleBit	采样位数	int	`16`	yes

4.6 回调类型定义

Name	Description	Type	ohos Support
OnSpeechStart(SpeechRecognitionStartResult result)	识别开始时的回调签名	typedef	yes
OnSpeechResult(SpeechRecognitionResult result)	识别结果的回调签名	typedef	yes
OnSpeechComplete(SpeechRecognitionCompleteResult result)	识别完成时的回调签名	typedef	yes
OnSpeechError(SpeechRecognitionError error)	识别出错时的回调签名	typedef	yes

5. 遗留问题

无。

6. 其他

实现原理：Dart 通过 MethodChannel（speechrecognizer）调用原生端开始/停止识别；原生端通过 channel.invokeMethod 将 speech.onStart、speech.onResult、speech.onComplete、speech.onError 事件回传至 Dart。OHOS 端使用 @kit.CoreSpeechKit 的 speechRecognizer.createEngine 创建识别引擎，通过 RecognitionListener 监听识别过程。
权限处理：原生端实现 AbilityAware 接口获取 UIAbilityContext，通过 abilityAccessCtrl.requestPermissionsFromUser 动态申请麦克风权限。
更多说明见项目内 example 目录。