先聊一个语音录入模块折磨我很久的真实问题。当时要做语音转文字功能,选用 AudioCapturer 来采集麦克风原始音频帧,最开始我只在页面打开的时候创建实例,配置好采样率、声道格式之后就启动采集,单独开循环读取 buffer。 测试的时候麻烦事一件接着一件。前台录音一切正常,切到后台一段时间之后音频采集直接断掉;连续采集的时候时不时出现丢帧,转文字结果断断续续、吞掉开头或者结尾语音;音量回调偶尔卡住不更新,UI 上的音量条一动不动;还有部分机型停止采集之后麦克风收音灯还一直亮着,别的 App 拿不到麦克风权限,重启采集直接报错。 一开始我以为只是权限配置不全,反复核对权限之后发现,后台采集、音频帧读取、实例生命周期、音频会话抢占是一套联动逻辑。AudioCapturer 只是底层音频采集句柄,它不会自动帮你维持后台采集通路,也不会自带队列缓冲,读取节奏跟不上音频硬件输出节奏就会丢帧。很多开发者只关注创建和开始采集这两步,忽略缓冲区队列、音频焦点、后台限制、资源释放这些边界,最后出现采集不稳、硬件资源占用异常的问题。

这里先理清两个核心概念,后面所有避坑逻辑都围绕它们展开。 音频环形缓冲区,就是我们自己在业务层维护的音频帧队列。硬件会持续输出音频数据,如果我们读取不及时,硬件缓冲区填满之后新帧直接丢弃,也就是丢帧。AudioCapturer 没有内置的长缓冲队列,读取逻辑和硬件输出节奏必须匹配,或者自己做环形队列承接音频数据。 音频会话抢占,鸿蒙系统里同一时刻麦克风资源属于独占资源。别的音频应用、通话、系统提示音都可能抢占音频输入通道。一旦发生抢占,AudioCapturer 会收到状态回调,这时候要暂停采集、保存现场,等资源释放之后再尝试恢复,而不是一直重试创建实例。

最重要的一句话放在前面。想稳定采集音频,读取线程、缓冲队列、状态监听、权限生命周期四个环节都要配套处理。只启动采集不维护读取循环,大概率会丢帧;采集结束不释放,麦克风硬件锁不会自动释放。

新建 utils/AudioCaptureHelper.ets,这是项目里打磨稳定的录音采集工具,包含环形缓冲、音量计算、状态监听、停止释放整套逻辑。

import { audio } from '@kit.AudioKit';
import { hilog } from '@ohos.hilog';
import { BusinessError } from '@ohos.base';

const TAG = "AUDIO_CAPTURE_HELPER";

export class AudioCaptureHelper {
  private audioCapturer: audio.AudioCapturer | null = null;
  private isCapturing: boolean = false;
  // 环形缓冲,承接音频帧,防止读取不及时丢帧
  private frameQueue: Uint8Array[] = [];
  private maxQueueLength: number = 20;
  private onVolumeUpdate: ((vol: number) => void) | null = null;
  private onFrameCallback: ((frame: Uint8Array) => void) | null = null;
  private readLoopTask: Promise<void> | null = null;

  setVolumeCallback(cb: (vol: number) => void) {
    this.onVolumeUpdate = cb;
  }

  setFrameCallback(cb: (frame: Uint8Array) => void) {
    this.onFrameCallback = cb;
  }

  async initCapturer() {
    if (this.audioCapturer) return;
    try {
      const audioInfo: audio.AudioCapturerInfo = {
        source: audio.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
        audioFormat: {
          sampleRate: 16000,
          channelCount: 1,
          sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_S16LE,
          encodingType: audio.AudioEncodingType.ENCODING_TYPE_RAW
        }
      };
      const capturerOptions: audio.AudioCapturerOptions = {
        capturerInfo: audioInfo,
        bufferSize: 4096
      };
      this.audioCapturer = await audio.createAudioCapturer(capturerOptions);

      // 监听采集状态变化,音频抢占、系统限制都会触发
      this.audioCapturer.on("stateChange", (state) => {
        hilog.info(0x0018, TAG, "capturer state change: %d", state);
        if (state === audio.AudioCapturerState.STATE_INTERRUPTED) {
          this.stopCapture();
        }
      });
      hilog.info(0x0018, TAG, "AudioCapturer 创建完成");
    } catch (err) {
      const e = err as BusinessError;
      hilog.error(0x0018, TAG, "创建采集器失败 code:%d msg:%s", e.code, e.message);
    }
  }

  async startCapture() {
    if (!this.audioCapturer || this.isCapturing) return;
    const state = await this.audioCapturer.getState();
    if (state === audio.AudioCapturerState.STATE_PREPARED) {
      await this.audioCapturer.start();
      this.isCapturing = true;
      this.startReadLoop();
    }
  }

  // 持续读取音频帧的循环
  private async startReadLoop() {
    if (!this.audioCapturer) return;
    this.readLoopTask = (async () => {
      while (this.isCapturing) {
        const bufferSize = 4096;
        const buffer = new ArrayBuffer(bufferSize);
        const readLen = await this.audioCapturer.read(buffer, bufferSize);
        if (readLen <= 0) continue;
        const frameData = new Uint8Array(buffer, 0, readLen);
        // 入队,队列溢出时丢弃最早的帧
        if (this.frameQueue.length >= this.maxQueueLength) {
          this.frameQueue.shift();
        }
        this.frameQueue.push(frameData);
        // 音量简单计算
        let sum = 0;
        for (let i = 0; i < frameData.length; i += 2) {
          const val = (frameData[i + 1] << 8) | frameData[i];
          sum += Math.abs(val);
        }
        const avg = sum / (frameData.length / 2);
        const volume = Math.min(100, avg / 30);
        if (this.onVolumeUpdate) {
          this.onVolumeUpdate(volume);
        }
        // 回调抛出音频帧
        if (this.onFrameCallback) {
          this.onFrameCallback(frameData);
        }
      }
    })();
  }

  async stopCapture() {
    if (!this.audioCapturer || !this.isCapturing) return;
    this.isCapturing = false;
    await this.audioCapturer.stop();
    this.frameQueue = [];
    hilog.info(0x0018, TAG, "采集停止,缓冲队列清空");
  }

  async release() {
    await this.stopCapture();
    if (this.audioCapturer) {
      this.audioCapturer.off("stateChange");
      await this.audioCapturer.release();
      this.audioCapturer = null;
    }
    this.onFrameCallback = null;
    this.onVolumeUpdate = null;
    hilog.info(0x0018, TAG, "采集器资源释放");
  }
}

页面调用代码,控制录音启停,接收音频帧和音量数据更新 UI。

import { AudioCaptureHelper } from '../utils/AudioCaptureHelper';
import { hilog } from '@ohos.hilog';

@Entry
@ComponentV2
struct AudioRecordPage {
  @State currentVolume: number = 0;
  @State isRecording: boolean = false;
  private captureHelper: AudioCaptureHelper = new AudioCaptureHelper();

  aboutToAppear() {
    this.captureHelper.initCapturer();
    this.captureHelper.setVolumeCallback((vol) => {
      this.currentVolume = vol;
    });
    this.captureHelper.setFrameCallback((frame) => {
      // 在这里把音频帧送入转写或者本地保存逻辑
    });
  }

  aboutToDisappear() {
    this.captureHelper.release();
  }

  async toggleRecord() {
    if (this.isRecording) {
      await this.captureHelper.stopCapture();
      this.isRecording = false;
    } else {
      await this.captureHelper.startCapture();
      this.isRecording = true;
    }
  }

  build() {
    Column({ space: 24 }) {
      Text(`当前音量:${this.currentVolume.toFixed(1)}`)
        .fontSize(20)
      Button(this.isRecording ? "停止录音" : "开始录音")
        .onClick(() => this.toggleRecord())
    }
    .width("100%")
    .height("100%")
  }
}

接下来梳理真机高频踩坑点,语音采集、后台录音场景反复验证出来的问题。 读取循环放在主线程执行。读取音频是持续 IO 操作,主线程循环读取会阻塞 UI 渲染,同时读取间隔不稳定,直接引发丢帧。音频读取循环必须单独放到 TaskPool 子线程里运行,不能占用主线程。 没有维护帧缓冲队列,read 拿到数据之后直接处理。如果转码、写入文件的处理逻辑耗时,下一次 read 到来的时候上一帧还没处理完成,新音频帧就会被覆盖,表现为语音断断续续。环形队列用来削峰,缓解处理耗时带来的丢帧。 后台采集只申请麦克风权限,没有配置后台任务类型。鸿蒙 7 对后台麦克风采集管控严格,单纯切到后台之后,系统一段时间后会冻结应用线程,read 循环直接停掉。后台持续录音需要搭配 audio 类型的后台长时任务,没有后台任务,采集一定会中断。 停止采集之后不调用 release。很多人只调用 stop,认为停止采集就释放麦克风。stop 只是暂停数据流,AudioCapturer 实例依旧持有麦克风硬件锁,别的应用无法使用麦克风,必须主动调用 release 释放底层句柄。 采样参数和业务下游不匹配。比如转写服务要求 16K 单声道,代码里配置成 44.1K 立体声,音频送入之后识别错乱。音频采集参数要和下游消费端对齐,不要随便修改采样率、位深、声道。 stateChange 中断回调到来之后没有做恢复策略。通话、系统录音、别的音频 App 抢占麦克风,会触发 STATE_INTERRUPTED。收到中断之后不能立刻循环重试创建实例,要先停止采集,等收到资源释放信号之后再尝试恢复采集。 短时间连续多次调用 start。实例还没完成 prepare,重复调用 start,底层状态机混乱,采集句柄直接失效。启停操作需要增加互斥锁,保证上一次流程完成之后再执行下一次。 音量计算方式不对,数值跳动剧烈或者长时间不变。直接取原始 pcm 幅值没有做平滑,UI 音量条抖动严重。可以对连续几次音量做均值平滑之后再赋值给 UI。 采集过程中屏幕休眠。屏幕休眠会连带触发应用的资源管控策略,线程调度优先级降低,读取间隔变长,丢帧概率大幅提升。长时间录音场景,按需申请屏幕常亮。 权限只在页面打开的时候校验一次。用户中途在系统设置里关闭麦克风权限,采集器不会主动抛出明显错误,read 读取的数据全部是空帧。每次启动采集前都要重新校验麦克风权限状态。

这里做一份方案对比,帮你区分两种音频采集方案的边界。 AudioCapturer,直接读取原始 PCM 音频帧,自由度高,可以拿到原始音频做降噪、转写、自定义编码,适合语音识别、实时音频处理场景;开发成本高,要自己管理缓冲、读取线程、后台任务、状态中断。 AVRecorder,封装好的录音工具,直接输出 mp3、aac 文件,不用处理原始音频帧,适合只需要保存录音文件的场景;拿不到实时音频流,没法做实时语音识别、实时音量检测。

开发自查清单,新增录音模块的时候对照核对。 音频读取循环放到独立子线程,禁止主线程循环 read;配套环形缓冲队列,避免处理逻辑阻塞造成丢帧;后台持续录音,必须申请对应类型的后台长时任务;采集结束,成对调用 stop 和 release 释放麦克风硬件;监听 stateChange 中断回调,做好音频抢占的暂停与恢复逻辑;启停方法增加互斥标记,防止重复调用打乱状态机;采样率、声道、采样格式和下游消费业务对齐;音量计算增加平滑处理,避免 UI 剧烈跳动;每次开始采集前校验麦克风权限;屏幕休眠、系统资源冻结场景提前评估风险。

最后聊一句复盘。AudioCapturer 的坑大多集中在资源和线程管控上。麦克风是独占硬件资源,音频数据流是持续流动的,它不像普通接口调用,发一次请求拿一次结果。硬件输出节奏、系统资源调度、其他 App 抢占都会干扰采集链路。缓冲队列承接峰值、子线程负责读取、中断回调处理抢占、release 释放硬件锁,把这几件事做好,录音采集才能稳定可用。

Logo

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

更多推荐