《聊天页-语音转文字》二、speechRecognizer语音识别API使用指南

张

张建站

2026/7/12 13:52:11

10分钟阅读

《聊天页-语音转文字》二、speechRecognizer语音识别API使用指南

HarmonyOS speechRecognizer语音识别API 详解与使用指南效果一、模块简介speechRecognizer是 HarmonyOS Core Speech Kit 中提供的语音识别核心模块属于kit.CoreSpeechKit的一部分。它封装了华为自研的语音识别引擎提供将音频数据转换为文本的能力。系统能力SystemCapability.AI.SpeechRecognizer约束与限制仅可在Stage 模型下使用当前不支持模拟器需真机调试支持语种中文普通话模型类型离线二、导入方式import{speechRecognizer}fromkit.CoreSpeechKit;import{BusinessError}fromkit.BasicServicesKit;三、核心类型定义3.1 CreateEngineParams引擎创建参数interfaceCreateEngineParams{language:string;// 语种如 zh-CNonline:number;// 0离线1在线优先extraParams?:Recordstring,Object;// 扩展参数}extraParams 常用键值键值说明locateCN地区标识recognizerModeshort/long短语音/长语音模式3.2 SpeechRecognitionEngine引擎实例引擎核心对象提供以下方法方法签名说明setListener(listener: RecognitionListener): void设置识别回调监听startListening(params: StartParams): void开始识别writeAudio(sessionId: string, audioData: Uint8Array): void写入音频数据finish(sessionId: string): void结束当前识别会话cancel(sessionId: string): void取消识别不返回结果shutdown(): void销毁引擎释放资源3.3 StartParams识别启动参数interfaceStartParams{sessionId:string;// 会话唯一标识audioInfo:AudioInfo;// 音频信息配置}interfaceAudioInfo{audioType:string;// pcmsampleRate:number;// 采样率16000soundChannel:number;// 声道数1单声道sampleBit:number;// 采样位深16}3.4 RecognitionListener回调监听interfaceRecognitionListener{onStart:(sessionId:string,eventMessage:string)void;onEvent:(sessionId:string,eventCode:number,eventMessage:string)void;onResult:(sessionId:string,result:SpeechRecognitionResult)void;onComplete:(sessionId:string,eventMessage:string)void;onError:(sessionId:string,errorCode:number,errorMessage:string)void;}3.5 SpeechRecognitionResult识别结果interfaceSpeechRecognitionResult{result:string;// 识别出的文本内容}四、API 调用完整流程┌─────────────────────────────────────────────┐ │ 1. createEngine(params, callback) │ │ ↓ 获得 SpeechRecognitionEngine 实例 │ │ 2. engine.setListener(listener) │ │ ↓ 注册识别结果/错误/完成回调 │ │ 3. engine.startListening(startParams) │ │ ↓ 通知引擎开始接收音频 │ │ 4. engine.writeAudio(sessionId, audioData) │ │ ↓ 循环写入 PCM 音频块1280字节/次 │ │ 5. engine.finish(sessionId) │ │ ↓ 通知引擎音频写入结束 │ │ 6. engine.shutdown() │ │ 释放引擎资源 │ └─────────────────────────────────────────────┘五、分步代码讲解5.1 创建引擎letengine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;constcreateParams:speechRecognizer.CreateEngineParams{language:zh-CN,online:1,extraParams:{locate:CN,recognizerMode:short}};// 方式一callback 形式speechRecognizer.createEngine(createParams,(err:BusinessError,eng:speechRecognizer.SpeechRecognitionEngine){if(err){console.error(创建失败:${err.code}-${err.message});return;}engineeng;});// 方式二Promise 形式API 11speechRecognizer.createEngine(createParams).then((eng:speechRecognizer.SpeechRecognitionEngine){engineeng;console.info(创建成功);}).catch((err:BusinessError){console.error(创建失败:${err.code}-${err.message});});5.2 设置回调监听constlistener:speechRecognizer.RecognitionListener{// 识别开始onStart:(sessionId:string,eventMessage:string){console.info([${sessionId}] 识别已开始);},// 事件通知如VAD检测等onEvent:(sessionId:string,eventCode:number,eventMessage:string){console.info([${sessionId}] 事件: code${eventCode});},// 识别结果中间结果最终结果都会回调onResult:(sessionId:string,result:speechRecognizer.SpeechRecognitionResult){if(result.result){console.info([${sessionId}] 识别文本:${result.result});// 更新 UI 显示}},// 识别完成onComplete:(sessionId:string,eventMessage:string){console.info([${sessionId}] 识别完成);},// 错误回调onError:(sessionId:string,errorCode:number,errorMessage:string){console.error([${sessionId}] 错误: code${errorCode}, msg${errorMessage});}};engine?.setListener(listener);5.3 启动识别并写入音频import{fileIoasfs}fromkit.CoreFileKit;asyncfunctionstartRecognition(sessionId:string,pcmFilePath:string):Promisevoid{// 1. 配置音频参数并启动conststartParams:speechRecognizer.StartParams{sessionId:sessionId,audioInfo:{audioType:pcm,sampleRate:16000,soundChannel:1,sampleBit:16}};engine?.startListening(startParams);// 2. 打开 PCM 文件constfilefs.openSync(pcmFilePath,fs.OpenMode.READ_ONLY);constCHUNK_SIZE1280;constbuffernewArrayBuffer(CHUNK_SIZE);// 3. 分段写入letoffset0;// HarmonyOS 中 offset 表示文件读取位置while(true){constbytesReadfs.readSync(file.fd,buffer,{offset:offset,length:CHUNK_SIZE});if(bytesRead0)break;constdatanewUint8Array(buffer,0,bytesRead);engine?.writeAudio(sessionId,data);offsetbytesRead;// 每次写入后等待40ms匹配实时音频速率awaitnewPromisevoid(rsetTimeout(r,40));}// 4. 通知引擎写入结束engine?.finish(sessionId);fs.closeSync(file);}5.4 取消与销毁// 取消当前识别不返回结果engine?.cancel(sessionId);// 销毁引擎页面退出时调用engine?.shutdown();engineundefined;六、完整示例实时语音转文字以下示例演示录制一段语音并实时转换为文字的完整过程import{speechRecognizer}fromkit.CoreSpeechKit;import{audio}fromkit.AudioKit;import{fileIoasfs}fromkit.CoreFileKit;import{abilityAccessCtrl,common,Permissions}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct RealtimeAsrDemo{StateresultText:string;Statestatus:string点击按钮开始;privateengine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;privatecapturer:audio.AudioCapturer|undefinedundefined;privatesessionId:string;aboutToAppear():void{constctxgetContext(this)ascommon.UIAbilityContext;constatManagerabilityAccessCtrl.createAtManager();atManager.requestPermissionsFromUser(ctx,[ohos.permission.MICROPHONEasPermissions]);this.createAsrEngine();}createAsrEngine():void{constparams:speechRecognizer.CreateEngineParams{language:zh-CN,online:1,extraParams:{locate:CN,recognizerMode:short}};speechRecognizer.createEngine(params,(err,eng){if(!err){this.engineeng;this.engine.setListener({onStart:(){},onEvent:(){},onResult:(_sid:string,result:speechRecognizer.SpeechRecognitionResult){if(result.result){this.resultTextresult.result;}},onComplete:(){this.status识别完成;},onError:(_sid:string,code:number,msg:string){this.status错误:${code};}});}});}startRecognize():void{this.sessionIdDate.now().toString();this.resultText;this.status正在录音...;// 启动识别this.engine?.startListening({sessionId:this.sessionId,audioInfo:{audioType:pcm,sampleRate:16000,soundChannel:1,sampleBit:16}});// 创建录音器16kHz, 单声道, 16bit PCMconstoptions:audio.AudioCapturerOptions{streamInfo:{samplingRate:audio.AudioSamplingRate.SAMPLE_RATE_16000,channels:audio.AudioChannel.CHANNEL_1,sampleFormat:audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,encodingType:audio.AudioEncodingType.ENCODING_TYPE_RAW},capturerInfo:{source:audio.SourceType.SOURCE_TYPE_MIC,capturerFlags:0}};audio.createAudioCapturer(options,(err,capturer){if(err)return;this.capturercapturer;// 将录音数据实时写入识别引擎this.capturer.on(readData,(buffer:ArrayBuffer){constdatanewUint8Array(buffer);this.engine?.writeAudio(this.sessionId,data);});this.capturer.start();});}stopRecognize():void{this.capturer?.stop().then((){this.capturer?.release();});this.engine?.finish(this.sessionId);this.status处理中...;}aboutToDisappear():void{this.engine?.shutdown();}build(){Column({space:24}){Text(实时语音转文字).fontSize(20).fontWeight(FontWeight.Bold).margin({top:60})Text(this.status).fontSize(14).fontColor(#999)Text(this.resultText||识别结果将显示在这里).fontSize(16).fontColor(this.resultText?#333:#CCC).padding(20).width(80%).backgroundColor(#F8F8F8).borderRadius(12)Row({space:16}){Button(开始).backgroundColor(#4FC08D).onClick(()this.startRecognize())Button(停止).backgroundColor(#FF6B6B).onClick(()this.stopRecognize())}}.width(100%).height(100%).justifyContent(FlexAlign.Center).backgroundColor(#FFFFFF)}}七、错误码速查表错误码描述解决方案1002200001创建引擎失败检查语种/模式是否支持确认非模拟器环境1002200006引擎忙碌其他应用正在使用等待后重试1002200008引擎已销毁重新调用createEngine创建引擎1002200009内部服务错误重启应用或设备八、最佳实践引擎生命周期管理在aboutToAppear创建引擎在aboutToDisappear销毁引擎引擎预初始化页面加载时即创建引擎避免用户操作时等待引擎创建完成sessionId 唯一性每次识别会话使用不同的 sessionId推荐使用时间戳音频参数一致性录音参数采样率、声道、位深必须与StartParams.audioInfo一致写入节流每次writeAudio写入 1280 字节后等待 40ms识别结果异步性finish()调用后onResult回调可能延迟数百毫秒需轮询等待而非固定 setTimeout及时释放录音结束后立即调用finish避免引擎空转错误处理始终在onError回调中处理异常情况避免静默失败fs.readSync offset 语义HarmonyOS 的fileIo.readSync中offset参数表示文件读取位置与 Node.js 语义不同九、总结speechRecognizer模块是 HarmonyOS 语音识别的核心提供了从引擎创建到音频识别的完整 API 链路。掌握createEngine → setListener → startListening → writeAudio → finish → shutdown这六步流程即可在各类应用中快速集成语音转文字能力。