HarmonyOS NEXT 语音识别技术完整使用指南效果一、概述HarmonyOS NEXT 提供了系统级的**语音识别Automatic Speech Recognition, ASR**能力由 Core Speech Kit 统一封装开发者可以通过kit.CoreSpeechKit中的speechRecognizer模块将音频信息PCM 文件或实时语音流转换为文本。核心特性特性说明支持语种中文普通话含中文语境下的英文识别模式短语音模式≤60s、长语音模式≤8h模型类型离线模型端侧运行不依赖网络识别准确率本地识别约95%云端识别约97%起始版本HarmonyOS 4.1.0 (API 11)典型应用场景语音输入法说话即输入文字语音搜索用语音直接发起搜索聊天语音转文字点击语音消息按钮转成文本实时字幕会议、直播场景的实时文字显示语音指令控制智能家居、车载场景的声控操作二、开发环境准备2.1 软件要求DevEco Studio6.1.0 Release 及以上HarmonyOS SDK6.1.0 Release 及以上运行设备华为手机、平板、2in1HarmonyOS 6.1.0 Release 及以上注意当前语音识别不支持模拟器必须使用真机调试2.2 权限配置在entry/src/main/module.json5中添加麦克风权限声明{ module: { requestPermissions: [ { name: ohos.permission.MICROPHONE, reason: $string:microphone_reason, usedScene: { abilities: [EntryAbility], when: always } } ] } }在resources/base/element/string.json中补充说明文案{string:[{name:microphone_reason,value:用于语音识别录音}]}2.3 运行时权限申请import{abilityAccessCtrl,common,Permissions}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;constpermissions:ArrayPermissions[ohos.permission.MICROPHONE];functionrequestMicPermission(context:common.UIAbilityContext):void{constatManagerabilityAccessCtrl.createAtManager();atManager.requestPermissionsFromUser(context,permissions).then((){console.info(权限获取成功);}).catch((err:BusinessError){console.error(权限申请失败:${err.code}${err.message});});}三、核心API调用流程语音识别的完整流程分为四个阶段创建引擎 → 设置回调监听 → 开始识别并写入音频 → 结束识别3.1 第一步导入模块import{speechRecognizer}fromkit.CoreSpeechKit;import{BusinessError}fromkit.BasicServicesKit;3.2 第二步创建识别引擎letasrEngine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;// 配置引擎参数constextraParam:Recordstring,Object{locate:CN,// 地区recognizerMode:short// 短语音模式长语音为 long};constinitParams:speechRecognizer.CreateEngineParams{language:zh-CN,// 语种online:1,// 1在线优先0纯离线extraParams:extraParam};// 异步创建引擎speechRecognizer.createEngine(initParams,(err:BusinessError,engine:speechRecognizer.SpeechRecognitionEngine){if(err){console.error(创建引擎失败: code${err.code}, msg${err.message});return;}asrEngineengine;console.info(引擎创建成功);});常见错误码错误码说明1002200001语种不支持、模式不支持或初始化超时1002200006引擎正在被其他应用占用1002200008引擎已被销毁3.3 第三步设置回调监听constlistener:speechRecognizer.RecognitionListener{onStart:(sessionId:string,eventMessage:string){console.info(识别开始: sessionId${sessionId});},onEvent:(sessionId:string,eventCode:number,eventMessage:string){console.info(事件回调: code${eventCode});},onResult:(sessionId:string,result:speechRecognizer.SpeechRecognitionResult){// result.result 包含识别的文本中间结果和最终结果console.info(识别结果:${result.result});},onComplete:(sessionId:string,eventMessage:string){console.info(识别完成: sessionId${sessionId});},onError:(sessionId:string,errorCode:number,errorMessage:string){console.error(识别错误: code${errorCode}, msg${errorMessage});}};asrEngine?.setListener(listener);3.4 第四步开始识别并写入音频import{fileIoasfs}fromkit.CoreFileKit;asyncfunctionrecognizeFromPcmFile(sessionId:string,filePath:string):Promisevoid{// 设置识别参数conststartParams:speechRecognizer.StartParams{sessionId:sessionId,audioInfo:{audioType:pcm,// 音频类型sampleRate:16000,// 采样率soundChannel:1,// 单声道sampleBit:16// 16位采样}};// 启动识别asrEngine?.startListening(startParams);// 逐段读取 PCM 文件并写入引擎constfilefs.openSync(filePath,fs.OpenMode.READ_ONLY);constbufSize1280;// 每次写入1280字节constbufnewArrayBuffer(bufSize);letoffset0;// HarmonyOS 中 offset 表示文件读取位置非 Node.js 的缓冲区偏移while(true){constbytesReadfs.readSync(file.fd,buf,{offset:offset,length:bufSize});if(bytesRead0)break;constchunknewUint8Array(buf,0,bytesRead);asrEngine?.writeAudio(sessionId,chunk);offsetbytesRead;// 节流每次写入后等待40ms匹配实时音频流速率awaitnewPromisevoid((resolve)setTimeout(resolve,40));}// 结束识别asrEngine?.finish(sessionId);fs.closeSync(file);}// 调用示例recognizeFromPcmFile(session_001,/data/storage/el2/base/cache/voice_record.pcm);3.5 第五步销毁引擎// 页面销毁时释放引擎资源asrEngine?.shutdown();asrEngineundefined;四、完整示例语音识别页面import{speechRecognizer}fromkit.CoreSpeechKit;import{audio}fromkit.AudioKit;import{fileIoasfs}fromkit.CoreFileKit;import{abilityAccessCtrl,common,Permissions}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct SpeechDemo{StaterecognizedText:string等待识别...;StateisRecording:booleanfalse;privateengine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;privatecapturer:audio.AudioCapturer|undefinedundefined;aboutToAppear():void{// 申请权限constctxgetContext(this)ascommon.UIAbilityContext;constatManagerabilityAccessCtrl.createAtManager();atManager.requestPermissionsFromUser(ctx,[ohos.permission.MICROPHONEasPermissions]);// 初始化引擎this.initEngine();}initEngine():void{constparams:speechRecognizer.CreateEngineParams{language:zh-CN,online:1,extraParams:{locate:CN,recognizerMode:short}};speechRecognizer.createEngine(params,(err,eng){if(!err){this.engineeng;this.setupListener();}});}setupListener():void{constlistener:speechRecognizer.RecognitionListener{onStart:(){},onEvent:(){},onResult:(sessionId:string,result:speechRecognizer.SpeechRecognitionResult){if(result.result){this.recognizedTextresult.result;}},onComplete:(){},onError:(){}};this.engine?.setListener(listener);}build(){Column({space:20}){Text(语音识别示例).fontSize(22).fontWeight(FontWeight.Bold).margin({top:40})Text(this.recognizedText).fontSize(16).padding(20).backgroundColor(#F5F5F5).borderRadius(12).width(80%).textAlign(TextAlign.Center)Button(this.isRecording?录音中...:开始录音).width(200).height(48).backgroundColor(this.isRecording?#FF6B6B:#4FC08D).onClick((){this.isRecording!this.isRecording;// 实际项目中在此控制录音开始/停止})}.width(100%).height(100%).justifyContent(FlexAlign.Center)}}五、注意事项与最佳实践真机调试语音识别不支持模拟器请在真机上测试引擎预初始化在aboutToAppear中提前调用createEngine避免用户首次操作时等待引擎创建引擎复用创建引擎后应复用同一实例避免频繁创建/销毁音频格式要求PCM 格式采样率 16000Hz单声道16位写入节流每次writeAudio写入 1280 字节后建议等待 40ms避免引擎过载识别结果异步回调onResult回调是异步触发的finish()调用后结果可能延迟几百毫秒到数秒才回调需要轮询等待而非固定 setTimeout权限检查录音前务必检查麦克风权限是否已授予引擎忙碌多个应用同时调用语音识别时引擎可能返回1002200006错误码资源释放页面退出时调用shutdown()释放引擎资源fs.readSync offset 语义HarmonyOS 的fileIo.readSync中offset参数表示文件读取位置与 Node.js 的缓冲区偏移不同短语音 vs 长语音短语音模式适合即时交互≤60s长语音模式适合会议记录≤8h六、总结HarmonyOS 的语音识别能力通过 Core Speech Kit 提供整体调用流程清晰import speechRecognizer → createEngine创建引擎 → setListener设置回调 → startListening开始识别 → writeAudio写入音频数据 → finish结束识别 → shutdown销毁引擎掌握以上流程即可在聊天、搜索、输入等多种场景中快速接入语音转文字功能。短语音 vs 长语音短语音模式适合即时交互≤60s长语音模式适合会议记录≤8h六、总结HarmonyOS 的语音识别能力通过 Core Speech Kit 提供整体调用流程清晰import speechRecognizer → createEngine创建引擎 → setListener设置回调 → startListening开始识别 → writeAudio写入音频数据 → finish结束识别 → shutdown销毁引擎掌握以上流程即可在聊天、搜索、输入等多种场景中快速接入语音转文字功能。