HarmonyOS Core Speech Kit基础语音服务完整使用指南效果一、概述Core Speech Kit 是 HarmonyOS 提供的基础语音服务套件集成了语音类基础 AI 能力。它是 HarmonyOS AI Kit 体系中的重要组成部分向上为开发者提供声明式 API向下调用系统内置的离线模型与云端算力实现文本与语音之间的高效互转。架构层次┌──────────────────────────────────┐ │ 应用层 (Application) │ │ 聊天、搜索、输入等场景 │ ├──────────────────────────────────┤ │ 框架层 (Framework) │ │ kit.CoreSpeechKit │ │ ┌────────────┬────────────┐ │ │ │speechRecognizer│textToSpeech│ │ │ │ (语音识别ASR) │ (语音合成TTS)│ │ │ └────────────┴────────────┘ │ ├──────────────────────────────────┤ │ 系统服务层 (System Service) │ │ AI Engine Service │ │ Audio Service │ ├──────────────────────────────────┤ │ 硬件层 (Hardware) │ │ 麦克风 / 扬声器 / NPU │ └──────────────────────────────────┘二、两大核心能力能力模块名功能适用场景语音识别 (ASR)speechRecognizer语音转文字语音输入、语音搜索、聊天转文字语音合成 (TTS)textToSpeech文字转语音文本朗读、语音播报、有声阅读2.1 语音识别能力详情项目说明支持语种中文普通话模型类型离线端侧运行短语音模式≤ 60 秒长语音模式≤ 8 小时音频格式PCM16kHz单声道16位2.2 语音合成能力详情项目说明支持语种中文、英文含中文语境英文音色类型聆小珊女声、劳拉女声美英、凌飞哲男声文本长度≤ 10000 字符离线支持支持离线播报三、环境准备3.1 开发环境要求DevEco Studio 6.1.0 Release 及以上HarmonyOS SDK 6.1.0 Release 及以上运行设备华为手机/平板/2in1HarmonyOS 6.1.0 Release 及以上3.2 权限配置语音识别需要麦克风权限// entry/src/main/module.json5 { module: { requestPermissions: [ { name: ohos.permission.MICROPHONE, reason: $string:mic_permission_desc, usedScene: { abilities: [EntryAbility], when: always } } ] } }语音合成不需要额外权限仅播放音频。3.3 导入方式// 语音识别import{speechRecognizer}fromkit.CoreSpeechKit;// 语音合成import{textToSpeech}fromkit.CoreSpeechKit;// 错误码import{BusinessError}fromkit.BasicServicesKit;四、语音识别ASR开发步骤4.1 创建识别引擎import{speechRecognizer}fromkit.CoreSpeechKit;import{BusinessError}fromkit.BasicServicesKit;letasrEngine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;constparams:speechRecognizer.CreateEngineParams{language:zh-CN,online:1,extraParams:{locate:CN,recognizerMode:short}};speechRecognizer.createEngine(params,(err:BusinessError,engine:speechRecognizer.SpeechRecognitionEngine){if(err){console.error(ASR引擎创建失败:${err.code});return;}asrEngineengine;console.info(ASR引擎创建成功);});4.2 设置回调并启动识别// 设置监听constlistener:speechRecognizer.RecognitionListener{onStart:(sessionId:string){console.info(识别开始);},onEvent:(){},onResult:(sessionId:string,result:speechRecognizer.SpeechRecognitionResult){console.info(识别结果:${result.result});},onComplete:(){console.info(识别完成);},onError:(sessionId:string,code:number,msg:string){console.error(识别出错:${code}${msg});}};asrEngine?.setListener(listener);// 开始识别asrEngine?.startListening({sessionId:session_001,audioInfo:{audioType:pcm,sampleRate:16000,soundChannel:1,sampleBit:16}});4.3 写入音频数据import{fileIoasfs}fromkit.CoreFileKit;asyncfunctionwritePcmToEngine(filePath:string):Promisevoid{constfilefs.openSync(filePath,fs.OpenMode.READ_ONLY);constbufnewArrayBuffer(1280);constsessionIdsession_001;letoffset0;// HarmonyOS 中 offset 表示文件读取位置while(true){constbytesReadfs.readSync(file.fd,buf,{offset:offset,length:1280});if(bytesRead0)break;asrEngine?.writeAudio(sessionId,newUint8Array(buf,0,bytesRead));offsetbytesRead;awaitnewPromisevoid(rsetTimeout(r,40));}asrEngine?.finish(sessionId);fs.closeSync(file);}五、语音合成TTS开发步骤5.1 创建合成引擎import{textToSpeech}fromkit.CoreSpeechKit;letttsEngine:textToSpeech.TextToSpeechEngine|undefinedundefined;constparams:textToSpeech.CreateEngineParams{language:zh-CN,speaker:xiaoshan,// 音色xiaoshan/laura/lingfeizheextraParams:{}};textToSpeech.createEngine(params,(err:BusinessError,engine:textToSpeech.TextToSpeechEngine){if(!err){ttsEngineengine;console.info(TTS引擎创建成功);}});5.2 设置回调并开始合成constttsListener:textToSpeech.CallbackListener{onStart:(){console.info(合成开始);},onAudioAvailable:(sessionId:string,audioData:textToSpeech.AudioDataInfo){// 处理音频数据console.info(音频数据就绪: sessionId${sessionId});},onComplete:(sessionId:string){console.info(合成完成);},onError:(sessionId:string,code:number,msg:string){console.error(合成错误:${code}${msg});},onAudioVolume:(sessionId:string,volume:number,start:number,end:number){// 音量变化回调},onMarkReached:(sessionId:string,mark:string){// 标记到达回调}};ttsEngine?.setListener(ttsListener);// 开始合成播报constspeakParams:textToSpeech.SpeakParams{sessionId:tts_001,text:你好欢迎使用鸿蒙语音服务,extraParams:{}};ttsEngine?.speak(speakParams);5.3 控制播报// 暂停播报ttsEngine?.pause(tts_001);// 恢复播报ttsEngine?.resume(tts_001);// 停止播报ttsEngine?.stop(tts_001);// 销毁引擎ttsEngine?.shutdown();5.4 SSML 标记语言增强Core Speech Kit 支持类 SSML 的控制标签可精确调节合成效果// 多音字纠偏ttsEngine?.speak({sessionId:tts_002,text:今天的音乐会将在[chóng]庆举行,extraParams:{}});// 数字播报控制ttsEngine?.speak({sessionId:tts_003,text:订单号是say-as interpret-ascardinal12345/say-as,extraParams:{}});六、完整示例语音识别 语音合成 双功能页面import{speechRecognizer,textToSpeech}fromkit.CoreSpeechKit;import{audio}fromkit.AudioKit;import{abilityAccessCtrl,common,Permissions}fromkit.AbilityKit;import{BusinessError}fromkit.BasicServicesKit;EntryComponentstruct CoreSpeechKitDemo{StateasrResult:string;StatettsInput:string你好鸿蒙语音合成测试;Statestatus:string;privateasrEngine:speechRecognizer.SpeechRecognitionEngine|undefinedundefined;privatettsEngine:textToSpeech.TextToSpeechEngine|undefinedundefined;aboutToAppear():void{constctxgetContext(this)ascommon.UIAbilityContext;abilityAccessCtrl.createAtManager().requestPermissionsFromUser(ctx,[ohos.permission.MICROPHONEasPermissions]);this.initAsr();this.initTts();}initAsr():void{speechRecognizer.createEngine({language:zh-CN,online:1,extraParams:{locate:CN,recognizerMode:short}},(err,eng){if(!err){this.asrEngineeng;this.asrEngine.setListener({onStart:(){},onEvent:(){},onResult:(_sid,result){if(result.result)this.asrResultresult.result;},onComplete:(){this.status语音识别完成;},onError:(_sid,code){this.status识别错误:${code};}});}});}initTts():void{textToSpeech.createEngine({language:zh-CN,speaker:xiaoshan,extraParams:{}},(err,eng){if(!err){this.ttsEngineeng;this.ttsEngine.setListener({onStart:(){this.status正在播报...;},onAudioAvailable:(){},onComplete:(){this.status播报完成;},onError:(){},onAudioVolume:(){},onMarkReached:(){}});}});}speakText():void{if(this.ttsInput.trim().length0)return;this.ttsEngine?.speak({sessionId:Date.now().toString(),text:this.ttsInput,extraParams:{}});}aboutToDisappear():void{this.asrEngine?.shutdown();this.ttsEngine?.shutdown();}build(){Column({space:16}){Text(Core Speech Kit 示例).fontSize(22).fontWeight(FontWeight.Bold).margin({top:50})// 语音合成区Column({space:10}){Text(语音合成 (TTS)).fontSize(16).fontWeight(FontWeight.Medium)TextInput({text:this.ttsInput}).width(80%).onChange((v){this.ttsInputv;})Button(播报文字).backgroundColor(#4FC08D).onClick(()this.speakText())}.padding(16).backgroundColor(#F8F8F8).borderRadius(12).width(90%)// 语音识别区Column({space:10}){Text(语音识别 (ASR)).fontSize(16).fontWeight(FontWeight.Medium)Text(this.asrResult||识别结果将显示在此).fontColor(this.asrResult?#333:#CCC).fontSize(15)}.padding(16).backgroundColor(#F8F8F8).borderRadius(12).width(90%)Text(this.status).fontSize(13).fontColor(#999)}.width(100%).height(100%).justifyContent(FlexAlign.Start)}}七、约束与限制汇总能力约束项限制说明语音识别语种仅支持中文普通话语音识别模型仅离线模型语音识别时长短语音≤60s长语音≤8h语音识别设备不支持模拟器语音合成语种中文、英文语音合成文本长度≤ 10000 字符语音合成音色3 种内置音色通用并发不支持多线程并发调用同一引擎八、最佳实践引擎预热在页面加载时提前创建引擎避免用户操作时等待资源管理页面销毁时务必调用shutdown()释放引擎音频格式ASR 输入必须是 PCM 格式16kHz/单声道/16位写入节奏writeAudio每次 1280 字节间隔 40ms模拟实时流速率识别结果异步回调onResult回调是异步触发的finish()后需轮询等待结果错误处理始终处理onError回调向用户展示友好提示引擎互斥同一时刻只能有一个应用使用语音识别引擎fs.readSync offset 语义HarmonyOS 的fileIo.readSync中offset参数表示文件读取位置非 Node.js 缓冲区偏移离线优先Core Speech Kit 采用离线优先策略地铁/电梯等弱网环境仍可使用九、总结Core Speech Kit 提供了 HarmonyOS 平台上的两大语音基础能力语音识别ASR和语音合成TTS。ASR通过speechRecognizer模块将 PCM 音频转换为文字适用于聊天转文字、语音搜索等场景TTS通过textToSpeech模块将文字转换为语音播报适用于朗读、语音通知等场景两者结合使用可以构建完整的语音交互闭环为应用赋予听和说的双重能力。