本篇技术封面

图:本篇 AI 智能应用主题封面。

把会议助手的录音按钮接入系统能力以后,最常见的误判是“用户点了允许,权限问题就结束了”。实际上麦克风可能被其他应用占用,录音对象还没有完成准备,应用在切换到后台时被限制,或者上一次录制尚未释放。结果就是 UI 上计时器走得很认真,文件却没有生成或长度异常。对于会议应用,这比普通页面崩溃更严重:用户可能只在会议结束时才发现内容根本不存在。

这篇围绕 HarmonyOS 的 AVRecorder 录音流程,讨论的是状态约束和失败恢复,不是列出所有媒体 API。官方指南说明录音需申请 ohos.permission.MICROPHONE,使用 AVRecorder 时应遵循状态机;录制通常需要在前台启动,持续或后台录制还需按场景评估长时任务。正式接入前要核对实际 SDK 和设备支持范围,不应把“申请了权限”理解为“录音肯定能持续”。

一、先抓住“UI 已经开始”这一假象

页面往往先执行 isRecording = true,随后异步申请权限与创建录音对象。权限弹窗关闭需要时间,期间用户可能再次按下按钮,或者应用进入后台。若计时器在调用系统 start 前启动,用户看到的是前端自己的计时,而不是设备实际采样时长。录音按钮应该由系统录音状态的确认回调驱动,最迟也要由受控的业务状态机控制,不能和权限申请过程脱节。

排查第一步是分离四种时间:点击按钮时间、权限授权完成时间、录音对象进入 started 时间、文件保存完成时间。把每一步变成可记录的状态,不需要把麦克风的数据本身写进日志,就能看出卡在申请授权、设备准备还是文件封装。若这些时间戳都没有,出现“录制了十分钟却只有一秒音频”时,只能依赖猜测和反复重装。

另一个坑是拒绝授权后的空转。用户可能明确拒绝一次,也可能选择了有限授权或在设置里撤销。如果代码使用 finally 无条件改成 recording,会把拒绝误当成功。产品层需要明确提供“继续使用文字输入”的降级入口,并在用户主动点击录音时再解释申请原因,而不是应用启动即索取所有可能用到的敏感权限。

二、状态机比 if/else 更可靠

录音可以拆成 idle → preparing → recording → paused → stopping → saved,失败统一进入 failed,然后允许主动复位。要点是:每个状态只能接受少量合法动作。preparing 时再次点击录音不新建对象,stopping 时屏蔽重复停止,saved 时把文件完整性检查交给文件层。真实 AVRecorder 的状态名称与我们的业务状态不一定完全相同,映射时要尊重官方的 prepare/start/pause/resume/stop/release 语义。

// 来源:示例源码/src/recorder.mjs(独立可测试的业务模块)
const transitions = {
  idle: ['preparing'], preparing: ['recording', 'failed'],
  recording: ['paused', 'stopping', 'failed'],
  paused: ['recording', 'stopping', 'failed'],
  stopping: ['saved', 'failed'], saved: ['idle'], failed: ['idle']
};

export class RecorderState {
  state = 'idle';
  token = 0;
  move(next) {
    if (!transitions[this.state]?.includes(next))
      throw new Error(`recorder: ${this.state} -> ${next}`);
    this.state = next;
    return ++this.token;
  }
  async prepare(requestPermission, openDevice) {
    if (this.state !== 'idle') return false;
    const ticket = this.move('preparing');
    try {
      const granted = await requestPermission();
      if (!granted || ticket !== this.token) throw Error('permission or stale task');
      await openDevice();
      if (ticket !== this.token) return false;
      this.move('recording');
      return true;
    } catch (err) {
      if (this.state === 'preparing') this.move('failed');
      return false;
    }
  }
  reset() { if (['saved', 'failed'].includes(this.state)) this.move('idle'); }
}

这里使用 RecorderState 作为平台无关的门禁。prepare 收到权限授权结果之后才会调用打开设备的回调;遇到授权失败、异常或者过期任务,业务层进入失败分支。工程中应由单独的 HarmonyRecorderAdapter 把业务状态映射至 AVRecorder 的实际方法,当前示例不假定任何系统调用已经在设备上运行。

录音状态门禁开发过程界面

图:录音状态门禁的开发环境样式示意;非 DevEco Studio 实际运行截图,日志为界面示例内容。

三、资源释放不能只寄托在页面销毁

会议中的用户经常切到浏览器看资料,再返回继续讨论。UIAbility 会经历 onBackground 和 onForeground,但并不是每次退出都会可靠收到 onDestroy。官方生命周期指南还指出,后台回调适合轻量操作,不能将大文件写入或耗时事务全部塞进去。因此正确策略应当在录制过程中就建立安全的保存策略,退出时快速释放不再使用的 UI 资源,而不是等销毁才开始保存整段音频。

如果业务确实需要后台录音,不能只是在前台录完后偷偷保持一个定时器。应根据系统长时任务与麦克风使用规则设计可见的状态和用户终止入口;能否持续录制、在什么条件下保持、通知如何展示都需要针对实际设备验证。本系列为了先把正确性讲透,默认以用户可感知的前台录音为基础:遇到不支持持续工作的环境,明确结束当前分段并提示,而不是声称后台录音永远正常。

音频文件写入也要避免“先把目标文件名写入记录,再尝试创建文件”的顺序。若创建失败,数据库会留下一个看似存在的路径。建议先通过临时文件名写入,确认录音对象停止并释放、文件大小及媒体可读性满足预期,再更新会议记录里的最终 audio 指针;失败时保留临时文件供受控恢复,或清理后显示错误。文件校验不能只检查路径非空,还应核对文件是否真实存在。

四、定位麦克风占用与音频格式问题

权限已经允许但仍不能录制时,优先查看录音对象所处状态以及系统返回的错误类别;其次检查当前是否存在电话、语音通话或其他应用占用录音资源。不要立即把问题归咎于应用签名,也不要反复弹权限申请框。授权属于访问资格,设备占用属于运行时资源,两者是不同层面。对前者给出设置引导,对后者给出“稍后重试”或回退到文字输入的建议。

另一类问题是“文件生成了,却识别不了”。这里通常涉及采样率、编码格式、通道数、封装类型与识别器要求是否一致。AVRecorder 能产生音频文件,并不意味着 Core Speech Kit 的识别输入一定接受同样的文件格式。方案应明确音频路径:需要时经过受控的转码或使用识别器支持的数据输入方式,并保留录音原件以免损坏。编解码参数及设备支持应以目标 SDK 文档为准,不能凭网上旧代码随意填写。

五、不要把用户的安全感建立在动画上

录音中的红点和波纹仅仅是视觉表现,真正值得展示的是开始时间、录音已持续时长、当前是否暂停和录音文件是否已保存。失败时不应把上次成功文件继续展示为本次结果,否则下一步模型会分析错误会议,表面却像完成了新任务。页面可以在 preparing 显示“正在启用麦克风”,在 recording 后再启动计时,停止后使用“保存中”过渡状态,直到文件层确认可用。

录音控制应用界面

图:录音控制的手机界面设计示意,页面数据用于说明交互,非真机截图。

针对无障碍和极端环境,录音按钮应该有清晰的可点击尺寸、文字状态与声音提示可选项;盲目依赖颜色区分录制和暂停会造成认知误差。系统层可能打断录制的条件也应可理解地呈现给用户,例如“录音已暂停,请确认麦克风是否被其他应用使用”,而不是只写一个技术错误码。提醒文案不需要透露系统内部栈信息,但要给下一步动作。

六、用故障注入检查保存链路

建议做六次专门验证。第一,首次安装拒绝麦克风权限,确认不会启动计时和生成空会议;第二,授权后再从系统设置撤销,看是否会阻止下次录音;第三,在 preparing 期间快速多次点击,确认只创建一个设备对象;第四,正在录制时按 Home,检查产品预期与系统行为;第五,结束后立即关闭页面,确认已成功保存的文件仍然可访问;第六,故意设置很低的可用存储空间,观察文件保存失败时数据库是否残留错误引用。

针对长会议还需要测试暂停、恢复与分段合并。某些异常可能发生在进入暂停前而不是恢复时,切忌将任意失败都自动 resume。必须查看当前状态,只有符合官方状态机时才能调用对应方法,必要时回退到新录音分段并记录段号。一个会议可以关联多个音频分段,但每段的时间顺序和来源都必须明确,避免在识别阶段把不同时间段拼错。

七、当 SDK 文档和博客写法不一致时

HarmonyOS 媒体 API 随版本演进,文章里的核心概念可以长期适用,具体函数签名、支持设备、权限用途和后台策略却不应靠记忆断言。实际项目先锁定 DevEco Studio 和编译 SDK,再读取该 SDK 对应的 AVRecorder 指南及权限表,最后以有设备、有场景的测试记录形成可发布判断。搜索到的旧 @ohos 导入示例与新 Kit 风格代码也不可不经核对直接拼在一起。

八、再往下挖:录音文件应该怎样才算真正完成

在故障复盘里,“停止成功”与“文件可供后续处理”需要设置两道验收。第一道核对录音对象状态及关闭结果,第二道由文件层验证目标文件能够打开、长度超过合理的最小值,并能被预期解码路径读取。文件长度可以辅助排查,但并非唯一质量指标:纯静音录制也可能占据正常大小的文件,而非常短的语音可能合法。因此不能用一个固定 KB 阈值直接断言录音内容无效。

设备时间和音频时间也常常不一致。用户按下暂停后,页面墙上时钟继续走了五分钟,但实际音频只包含暂停前后各一分钟。若会议详情用开始时间与结束时间相减当作录音时长,就会误导后续识别进度与定位回放。更稳妥的是保存每段实际录制时长及其与会议时间线的对应关系,暂停区间保留为元数据而非虚构成音频。对长会议拆段录制时,这种时间映射能避免纪要引用到错误时间点。

还要制定对资源冲突的用户提示优先级:如果权限被拒绝,先提示授权;如果权限正常但录音对象准备失败,再提示设备繁忙或输入配置需检查;如果系统回调显示已经开始而文件最终不可读,则归为存储与封装问题。三种错误不能都靠“清理缓存、重新安装”解决。排查日志只记录状态迁移与设备返回的安全错误类别,不需要收集用户实际说了什么。

在真机验证记录表里,建议附上系统版本、设备型号、权限状态、前后台切换步骤、期望与实际录制时长以及最终文件格式。测试结束后让参与人员检查并删除不再需要的录音素材。只要这张表持续维护,系统 SDK 升级导致的行为变化就更容易被发现,而不会被错误地归因于新的 AI 模型。

如果用户在录制时收到来电,恢复后的行为尤其要写入测试用例。系统是否暂停音频采集、麦克风是否重新可用,必须读取设备状态而不是沿用进入后台前的布尔值。若不能安全恢复,清楚地结束旧分段并提示开始新段,比显示持续录制而保存一份缺失内容的文件更负责任。

本篇结论:录音不是一个按钮,而是一条有授权、准备、采样、封装和释放的资源链。下一篇将讨论录音转换为文本时的另一类坑:增量识别会不断修改历史片段,若不区分预览与最终结果,会议原文会越来越乱。


资料核对说明:本系列部分涉及 HarmonyOS 原生能力,应以当前开发套件与华为官方文档为准;项目中的纯 JavaScript 代码属于业务示例,不等同于已完成端侧 SDK 对接。相关链接见根目录《官方资料索引.md》。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐