鸿蒙录音实时转文字：从权限申请到实时转写的完整实现

做鸿蒙录音实时转文字这个需求最直接的问题是手机上一堆语音转文字的App要么收费要么必须联网要么识别完才给结果真正能做到边说边出字、还不需要复杂接入的少之又少。这次我把录音和语音识别整个流程放到HarmonyOS工程里跑通从权限申请到音频采集再到实时转写和分段回显完整做了一个录音转文字案例。折腾下来最大的感受是鸿蒙开发套件在媒体和语音能力上其实比想象中成熟关键是要把音频采集、识别回调、UI刷新这几个环节的配合捋清楚。如果你也想做类似的鸿蒙工具类应用或者只是想把录音功能升级成实时转写这篇文章应该能帮你走通一条可行的路子。1. 项目到底是什么——需求与适用场景1.1 核心需求拆解这个项目说白了就是一个带“实时听写”能力的录音工具用户按住录音按钮说话界面上的文字跟着你说话的节奏一条一条冒出来。录音结束以后除了能回放音频还能把刚才转出来的整段文本导出到本地。拆开看有三个核心点录音采集要稳定不能说着说着就断了也不能在后台被系统干掉。识别要“实时”不是等一段话说完才出结果而是要边说边出字带中间结果刷新。文字和语音要能对得上至少每个段落结束的时候前面那一句的内容要保持完整可读。实际做下来实时性这件事最容易被低估。很多人以为语音识别就是把整段音频扔给引擎等回调拿结果就行但真正的实时转写不是一次请求是一个长连接式的识别会话中间结果和最终结果交替返回需要有一套精确的状态管理才能处理好。1.2 选用鸿蒙原生方案的原因我考虑过几种实现路径。第一种是接第三方语音识别服务效果虽然好但需要申请各种鉴权配置而且依赖网络离线场景直接抓瞎。第二种是自己部署语音识别模型准确率可调可控但打包体积和算力成本对手机App来说太重了。第三种就是走鸿蒙系统的语音识别能力把采集到的音频流交给系统识别服务处理好处是调用简单、本地离线也能跑不需要额外引入庞大的SDK。综合评估下来这个案例选择的是“系统音频采集 系统语音识别”的路线。整个工程不需要额外申请第三方Key也不依赖公网服务核心代码量比对接云端服务少了一半适合做一个普适性比较高的基础案例。2. 整体架构与关键设计2.1 模块划分整个项目按功能拆成四块模块职责关键点录音采集模块创建音频采集器、读取PCM数据、控制启停采样率、声道数、Buffer大小语音识别模块启动识别会话、接收中间/最终结果、结束会话回调时序、分段策略状态管理模块维护空闲/录音中/识别中/暂停态状态机防重复操作结果展示模块文本实时刷新、段落追加、导出保存UI刷新频率、数据合并这四个模块互相之间尽量解耦。录音采集只管把数据流喂给识别引擎识别模块只往外部抛回调结果状态管理负责把两边的启停时机对齐UI模块只做展示和交互。这样即使后期想把系统识别换成云端的也不需要动录音采集的代码。2.2 为什么要走“系统级语音识别”这是我踩了一圈之后才确定的方案。最初我尝试直接在录音模块里手动分割音频片段每段单独做一次一次性识别结果发现两个问题第一手动切分很难找准断句位置切到半句话上识别结果就是乱的第二多次短识别之间会有明显的接缝文本出来后还得自己拼实时性也很差。系统级识别的好处在于它是一个持续的会话你在里面录入多少音频它就帮你识别多少内容按语义自动断句不需要我管音频从哪里切到哪里。我只需要在合适的时机告诉它“开始听”和“有结果了”它可以连续返回中间文本。这个设计大大降低了核心逻辑的复杂度但也带来了一个约束必须保证音频流数据是连续的。Buffer不能太小太小会导致底层频繁唤醒、识别结果碎片化Buffer也不能太大太大会让识别延迟变高。2.3 双Buffer接力读取设计音频采集这个过程很多人第一次写的时候会直接在回调里同步read数据然后把数据处理放在同一个线程里效果很差。我测试前几个版本时就有过识别文字接不上、UI卡顿的情况。后来改用双Buffer接力主采集循环读取第一块数据写入识别引擎。同一时间第二块Buffer预先就绪线程不被阻塞。主循环轮流使用两个Buffer避免每次读取都等底层设备填充数据。这样处理后整个录音链路基本稳定识别中间结果出来的节奏也顺了很多。3. 开发环境搭建与权限处理3.1 开发工具与工程创建开发这个案例使用的是DevEco Studio基于HarmonyOS的API构建工程。创建工程时选择“Empty Ability”模板就够了语言选ArkTS。有一个小经验项目创建后第一时间检查编译SDK版本。不同版本对语音识别和音频框架的支持有差异如果一开始没选对中间改配置会很麻烦。建议把compileSdkVersion调到当前工具支持的最高稳定版本目标设备版本可以放开保证兼容性。3.2 权限声明与动态申请鸿蒙里录音相关权限是敏感权限除了在module.json5里声明还必须在运行时动态申请否则弹窗不会出现。模块配置里需要声明requestPermissions: [ { name: ohos.permission.MICROPHONE, reason: 用于录制声音并实时转写为文字, usedScene: { abilities: [ EntryAbility ] } } ]reason字段是必填的这个字段会展示在系统权限弹窗的说明里写得越直白越好用户可以一眼明白为什么要麦克风权限。动态申请代码方面先拿到应用自身的权限校验器再逐个检查权限是否已被授予import { abilityAccessCtrl, bundleManager, Permissions } from kit.AbilityKit; async function checkAndRequestPermission(): Promiseboolean { // 获取当前应用的 bundle 信息 let bundleInfo await bundleManager.getBundleInfoForSelf( bundleManager.BundleFlag.GET_BUNDLE_INFO_WITH_APPLICATION ); // 通过 bundleInfo 拿到应用需要申请的权限列表 let wantPermissions: ArrayPermissions []; let atManager abilityAccessCtrl.createAtManager(); // 先检查麦克风权限是否已经授予 try { let grantStatus await atManager.checkAccessToken( bundleInfo.appInfo.accessTokenId, ohos.permission.MICROPHONE ); if (grantStatus abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { return true; } } catch (err) { console.error(check permission failed: ${JSON.stringify(err)}); } // 未授权则弹出系统弹窗 try { const result await atManager.requestPermissionsFromUser( getContext(), [ohos.permission.MICROPHONE] ); // result 是一个数组需要判断对应权限的授权结果 if (result.length 0 result[0].grantStatus 0) { return true; } } catch (err) { console.error(request permission failed: ${JSON.stringify(err)}); } return false; }需要留意的是requestPermissionsFromUser返回的是一个授权结果数组不能光判断接口有没有执行成功必须逐项检查里面每个权限的grantStatus否则容易出现在模拟器上看着弹窗但实际没拿到权限的情况。3.3 语音识别权限的额外处理除了麦克风语音识别还会用到网络信息、音频设置等辅助能力。这些通常不是危险权限但如果没有配置识别服务可能在启动时静默失败。我遇到过一种情况录音能正常采集麦克风权限也给了但识别结果一直不出来排查到最后是缺少网络状态权限导致语音引擎无法初始化高精度模型。所以项目里建议把这几项也一并声明ohos.permission.INTERNET, ohos.permission.ACCESS_NETWORK_STATE, ohos.permission.GET_NETWORK_INFO, ohos.permission.MODIFY_AUDIO_SETTINGS这些权限不一定会弹窗但是缺少了会影响底层服务的运行提前在配置里加上能省掉很多隐性问题。4. 核心功能实现——录音采集与转写流水线4.1 初始化音频采集器音频采集在鸿蒙里走AudioCapturer。初始化之前要先定义采集参数采样率、声道、采样格式这三项必须和识别引擎的期望输入对齐。我最终的参数选择是采样率44100Hz声道数单声道采样格式16位整型PCM编码类型RAW为什么选44.1kHz而不是48kHz主要是因为语音识别引擎在默认配置下对这种采样率的兼容性最好如果选了48kHz部分识别引擎需要做重采样会增加处理延迟和CPU消耗。初始化代码如下import { audio } from kit.AudioKit; let audioCapturer: audio.AudioCapturer | null null; const bufferSize 4096; let readBuffer new ArrayBuffer(bufferSize); async function initAudioCapturer() { if (audioCapturer) { return; } let streamInfo: audio.AudioStreamInfo { samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_44100, channels: audio.AudioChannel.CHANNEL_1, sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE, encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW }; let capturerInfo: audio.AudioCapturerInfo { source: audio.SourceType.SOURCE_TYPE_MIC, capturerFlags: 0 }; try { audioCapturer await audio.createAudioCapturer(streamInfo, capturerInfo); } catch (err) { console.error(createAudioCapturer failed: ${JSON.stringify(err)}); audioCapturer null; } }这里有个容易忽略的点SAMPLE_RATE_44100、SAMPLE_FORMAT_S16LE这些枚举值在不同的API版本里可能写法不一样如果你的编译版本偏旧直接写字符串或数字在某些场景下更稳妥。我遇到过升级SDK后枚举名变化导致编译失败所以稍微需要注意版本差异。4.2 启动录音与读取音频流音频采集器创建好之后启动录音前需要先启动语音识别会话然后马上开始读取音频流async function startRecording() { if (!audioCapturer) { await initAudioCapturer(); if (!audioCapturer) { return; } } // 先启动识别引擎 await startSpeechRecognizer(); // 再启动采集 await audioCapturer.start(); // 开启读取循环 readLoop(); }读取循环是一个独立的异步循环里面不断从采集器读取数据然后交给识别引擎async function readLoop() { if (!audioCapturer) { return; } while (isRecording) { // 每次读取一块数据true 表示阻塞读取 let ret await audioCapturer.read(readBuffer, true); if (ret 0) { // 将本次读到的数据交给语音识别模块 feedAudioToRecognizer(readBuffer.slice(0, ret)); } else { // 读取失败可能是音频焦点被抢占 console.error(audio capturer read failed: ${ret}); } } }读取循环一旦跑起来CPU会一直在工作如果UI操作也放在主线程就很容易出现界面掉帧。我的做法是把采集、识别、UI刷新拆在三个不同的调度队列里采集线程只管读数据和投递识别模块单独维护自己的队列UI刷新只在收到回调的瞬间回到主线程执行。这样处理之后连续录制十分钟也不会有明显的卡顿。4.3 接入语音识别服务语音识别方面我封装了一个SpeechRecognizerHelper对外暴露三个方法start、stop、onResult。内部负责管理识别会话的启停和回调分发。核心逻辑class SpeechRecognizerHelper { private isListening: boolean false; private session: SpeechRecognizerSession | null null; private onPartialResult: (text: string) void; private onFinalResult: (text: string) void; async start() { if (this.isListening) { return; } // 创建识别会话设置参数 // 注册中间结果与最终结果回调 this.session await createSpeechSession(); this.session.on(partialResult, (event: { text: string; }) { if (this.onPartialResult) { this.onPartialResult(event.text); } }); this.session.on(finalResult, (event: { text: string; }) { if (this.onFinalResult) { this.onFinalResult(event.text); } }); this.session.on(error, (err: string) { console.error(recognizer error: ${err}); }); this.isListening true; } feedAudio(buffer: ArrayBuffer) { // 将音频数据写入识别会话 } async stop() { this.isListening false; // 通知识别引擎停止并等待最后的最终结果 } }这里的回调时机很关键。中间结果的意思是“目前暂时识别到的内容”它可能随着音频继续输入而改变。比如你刚开始说“今天的天”中间结果先出“今天”后面又变成“今天的天”。如果直接把每次中间结果都交给UI做追加界面上的文字就会乱掉。我的策略是中间结果只刷新当前未完成段落的展示区域不追加新段落只有拿到finalResult之后才把该段内容固定下来新增一个段落。4.4 文本输出与分段刷新实时转写界面上需要维护两个数据historyList已经结束断句的段落列表。currentText正在识别中的当前段落文本。UI层通过State装饰器管理这两个数据。每当收到中间结果时更新currentText界面随之刷新每当收到最终结果时把currentText追加进historyList同时清空currentText。用ArkTS写大概是这样State historyList: string[] []; State currentText: string ; onPartialResult(text: string) { this.currentText text; } onFinalResult(text: string) { this.historyList.push(text); this.currentText ; }这种“一条追加、一条刷新”的结构很直观但还有一个细节要注意finalResult之后引擎可能还会再给一条包含完整标点的finalResult这和前面的中间结果会有一段重叠。为了避免重复可以在收到finalResult时先判断当前段落是否已经以相同文本结尾如果是就只做微调不要重复追加。5. 从能跑到好用——状态管理与准确率优化5.1 录音状态机录音和识别是两个容易互相干扰的操作。用户点一下开始按钮以后系统要依次完成“创建采集器、开启识别会话、启动采集、开启读取循环”这几件事。如果用户手快点两下或者识别还没初始化完就开始录音就会出问题。我引入了一个RecordingState枚举状态含义触发条件IDLE空闲初始状态 / 停止后STARTING启动中用户点击启动按钮RECORDING录音中采集器和识别都启动成功STOPPING停止中用户点击停止按钮ERROR异常采集或识别过程出错在STARTING状态下启动按钮会被禁用防止重复点击在STOPPING状态下停止按钮也会禁用直到所有资源完整释放。这个状态机看起来简单但真的能挡住很多莫名其妙的bug。之前没有状态机的时候我在停止录音后立刻再次启动偶尔会出现音频采集器还没释放干净就重新创建的情况导致识别无响应。加上状态机之后每次启动前都会检查上一次的停止流程是否走完。5.2 断句与分段策略实时转写最大的体验差异在分段上。如果完全依赖识别引擎的断句能力会出现句子特别长、半天不分段的情况。如果完全自己按时间切分又会把完整的一句话拦腰截断。我的做法是“识别引擎为主超时兜底”如果识别引擎持续返回中间结果就让它继续累积如果超过5秒没有新的最终结果同时当前段落文本已经超过一定长度就主动调用一次“强制分段”把当前内容作为一条已完成的段落归入历史记录。这个兜底策略在会议记录场景下特别好用因为发言经常有停顿有时候这一整句话说完会停两三秒然后继续说。如果只等引擎断句两句话会黏在一段里阅读起来很累。加了超时强制分段后文字段落基本和发言人停顿对齐了阅读体验好很多。5.3 识别准确率优化影响识别准确率的因素很多我实际测试下来主要是这几个第一是录入音量。麦克风采集的音频如果太小声识别引擎会漏字如果太大声会出现爆音识别出来的内容全是乱码。解决办法是在采集器启动前检查系统音频音量并提示用户调整到合适区间。这个检查逻辑很简单但能显著提升首测体验。第二是环境噪音。在比较安静的办公室识别率很高一到咖啡厅噪音一大错误率立刻上来了。系统识别引擎本身就带一定的降噪能力但采集到的声音质量决定了上限。如果做的是严肃场景的转写工具建议在工程里引入音频降噪处理模块或者至少在UI上做好“建议在安静环境使用”的提示。第三是标点和语气词。识别引擎有时候会把“嗯”“啊”这种语气词直接转成文字比如“啊然后今天”这种。我在最终结果回调里做了一层清洗把句首的“嗯啊”和连续重复的虚词去掉只保留有效内容。这个清洗不能太激进因为正常语句里也可能出现“啊”这种语气词我采用的方式是只清理“开头连续且重复出现两次以上”的语气词。5.4 UI刷新频率控制实时转写场景里currentText变更是非常高频的。因为引擎返回中间结果的频率远高于普通人输入文字的速度如果每一次回调都立刻去修改State界面会频繁重新渲染严重时会出现闪屏。我做了节流如果两个中间结果的间隔小于200毫秒就只在内部更新文本不触发UI刷新只有超过200毫秒才同步一次UI。实际体验下来文字还是接近实时地出现在屏幕上但界面没有任何卡顿。想用这个方案需要注意ArkTS的响应式约束不要在非UI线程里直接修改State变量必须通过postTask回到UI线程再改。我刚开始图省事直接在识别回调里改不仅界面不刷新偶尔还会出现运行时报错。6. 问题排查实录6.1 权限弹窗未出现现象应用启动后点击录音按钮没有弹出麦克风授权弹窗录音直接失败。排查过程首先检查module.json5权限声明没问题再检查代码发现动态申请被放在了页面加载前的异步逻辑里实际运行时被提前拦截了。解决把动态申请的调用点改到用户点击录音按钮之后并且把等待授权结果的逻辑做成一个单独的异步函数有了结果再往下走。同时注意如果用户选择“不允许且不再询问”需要引导去设置页开启权限不能每次都发申请请求。6.2 识别结果长时间不出现象录音正常麦克风权限正常音频波形也在动但文字一两个字都不出。排查过程刚开始怀疑是采集数据和识别引擎的格式没对齐检查了采样率、声道数都一致。后来打印音频读取的返回字节数发现读取量很小怀疑是底层音量不够但测试时声音很大。最后定位到是识别会话和采集创建的顺序反了识别会话还没创建完成音频数据就已经开始读取导致前几秒的数据被丢弃。解决调整启动顺序先创建识别会话并等待会话状态变为“就绪”再启动音频采集最后开启读取循环。加上这个时序控制后基本一说话就能出字。6.3 录完能回放但没有文字现象录音文件正常保存回放也没问题但整个录制过程一个字的识别结果都没有。排查过程这个现象很迷惑因为录音模块明显正常工作。后来检查发现问题出在识别会话的结束时间。stopRecording时先结束了识别会话再停止采集导致最后一段有效音频永远没有送进识别引擎。而且识别引擎被强制停止时没有等待最后一个finalResult回调。解决调整停止顺序先停止音频采集再等待识别引擎把缓冲区的剩余数据全部处理完最后再关闭识别会话。为了等最后的处理结果需要在停止流程里增加一个2秒左右的超时等待防止UI无限阻塞。6.4 后台熄屏断录现象录音界面切到后台或者手机熄屏一段时间后录音停止识别中断。排查过程这是鸿蒙应用的后台资源限制问题。系统在应用退到后台后会限制音频能力尤其是麦克风这种高敏感资源默认不允许无限期占用。解决如果是短期切后台可以申请短时任务让应用在后台继续保持一段时间的运行能力。如果是长期录音需要考虑使用系统级录音服务或者至少在UI上明确提示用户保持前台运行。实际案例里我选择了前者在录音期间申请短时任务并在任务即将到期时发出提醒要求用户回到前台。6.5 快速问题速查表问题大概率原因处理建议权限弹窗没出现动态申请时机太早改为点击录音后再申请录音能进行但识别无字识别会话和采集顺序反了先建识别会话再启动采集停止后文字漏一段先关闭了识别会话先停采集再等待最后回调界面卡顿严重中间结果更新太频繁增加200ms节流后台几分钟就断后台资源限制申请短时任务或保持前台同一句话被记两次finalResult和中间结果重叠追加前做重复判断7. 实战心得与扩展方向这个案例做下来我最深的体会是实时转写类应用的技术难点不在某一个单点功能上而在多个模块的协同节奏上。每一个模块单独拿出来都能跑但一旦要对付“实时”两字所有延迟都会放大到用户面前。一个300毫秒的采集延迟一个500毫秒的回调延迟叠加起来用户就会觉得“字幕慢半拍”。如果你准备在这个案例基础上继续扩展有几个方向值得试一是把转写结果导出成带时间戳的SRT字幕文件这样可以直接拿去做视频字幕生成。实现起来很简单在每次finalResult回调时记录当前录音时间戳然后写入文本文件即可。二是增加多语种识别。系统识别引擎支持的语言不止中文可以在识别会话启动时配置目标语言做一个语言切换的开关。三是把录音和识别放到一个独立的Service里跑这样即使页面被销毁录音和转写还能继续。这次案例为了控制复杂度没有做这一层但实际产品中这一步基本是刚需。四是做音频增益控制。实测在嘈杂环境下适当提高采集增益能明显提升识别率但过度会引入爆音。可以在设置页提供增益调节滑块实时生效。五是在结束识别后增加一个文本校准页面把转写结果和原始音频做一次对齐播放用户点某一行文字就能从对应的位置开始回放音频。这个功能对会议记录类工具非常实用。做这类工具型应用不用追求大而全先把“边说边出字”这一个核心体验打磨顺就已经比市面上很多半成品App强了。录音和识别两个模块已经打通剩下的就是围绕场景不断加细节。希望这套实操记录能帮你减少一些踩坑时间。