《HarmonyOS技术精讲-Core Speech Kit（基础语音服务）》第1篇：音频管理基础与语音服务入门

《HarmonyOS技术精讲-Core Speech Kit（基础语音服务）》第1篇：音频管理基础与语音服务入门

开篇：音频管理在语音服务中的真实门槛

在HarmonyOS NEXT项目中接入语音功能时，很多开发者会直接跳到语音识别API的调用。但实际上，语音服务稳定运行的前提，是音频管理模块的初始化配置必须正确。

Microphone权限申请失败、采样率不匹配、音频流类型设错导致录音无法启动------这几个问题，在论坛里反复出现。核心原因在于，Core Speech Kit的音频管理模块设计比较底层，官方API虽然参数清晰，但没有说明实际使用中的设备兼容性差异。

本文先从架构层面讲清楚音频管理模块在语音服务中的位置，然后演示如何完成AudioCapturer（录音器）和AudioRenderer（播放器）的初始化配置。这些基础工作做扎实了，后续的语音识别（ASR）和语音合成（TTS）才不会出问题。

Core Speech Kit音频管理模块解决什么问题

Core Speech Kit是HarmonyOS提供的端侧语音能力套件，音频管理模块承担了底层音频设备的统一调度。它的核心职责包括：

• 管理音频输入输出设备（麦克风、扬声器、蓝牙耳机等）
• 控制音频流的采样率、编码格式、通道数等参数
• 处理音频焦点的抢占与释放（比如语音播报时暂停音乐播放）

很多人第一反应是用@ohos.multimedia.media（媒体库）来录音和播放，但核心区别在于：

对比项	Core Speech Kit音频管理	媒体库（media）
定位	语音服务专用，低延迟	通用媒体播放/录制
音频焦点管理	支持，与语音识别/合成深度集成	独立控制，需手动处理焦点
采样率支持	推荐16kHz（语音领域标准）	全范围，但无针对语音的优化
设备切换	支持自动切换（如蓝牙耳机连接/断开）	需监听回调手动重连

所以，如果项目里要做语音输入（识别）或语音输出（合成），必须使用Core Speech Kit的音频管理模块，否则会遇到录音延迟高、焦点冲突、设备切换时断音等问题。

环境说明

DevEco Studio 版本：DevEco Studio 6.1.0 及以上
HarmonyOS SDK 版本：HarmonyOS 6.1.0(23) 及以上
目标设备：手机、平板（带麦克风和扬声器）

核心实现：音频管理初始化与配置

1. 权限声明

麦克风权限是音频管理的基础，必须在module.json5中声明，并在运行时动态申请。

// module.json5
{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "用于语音识别和录音功能",
        "usedScene": {
          "when": "always"
        }
      }
    ]
  }
}

注意：reason字段不能为空，否则审核会被驳回。when建议设为always，因为语音服务通常需要后台持续运行。

2. 动态权限申请

// utils/PermissionUtil.ets
import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';

export class PermissionUtil {
  static async requestMicrophonePermission(context: common.UIAbilityContext): Promise<boolean> {
    const atManager = abilityAccessCtrl.createAtManager();
    const permission: Permissions = 'ohos.permission.MICROPHONE';
    
    try {
      // 检查是否已授权
      const result = await atManager.checkAccessToken(context.token, permission);
      if (result === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) {
        return true;
      }
      
      // 申请授权
      const grantResult = await atManager.requestPermissionsFromUser(context, [permission]);
      return grantResult.authResults[0] === abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED;
    } catch (error) {
      console.error('权限申请失败:', error);
      return false;
    }
  }
}

3. 创建AudioCapturer（音频采集器）

音频采集器用于从麦克风获取原始音频数据，是语音识别的基础。

// service/AudioCaptureService.ets
import { audio } from '@kit.MediaKit';

export class AudioCaptureService {
  private audioCapturer: audio.AudioCapturer | null = null;
  
  async initCapture(): Promise<void> {
    try {
      const audioManager = audio.getAudioManager();
      const capturerOptions: audio.AudioCapturerOptions = {
        streamInfo: {
          samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000, // 语音识别推荐16kHz
          channels: audio.AudioChannel.CHANNEL_1,                  // 单声道
          sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_PCM_16_BIT, // 16位PCM
          encodingType: audio.CodecType.CODEC_AUDIO_PCM            // 原始PCM编码
        },
        capturerInfo: {
          source: audio.SourceType.SOURCE_TYPE_MIC,                // 麦克风输入
          usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION, // 语音通信场景
          sessionId: audio.AudioSessionId.SESSION_ID_DEFAULT
        }
      };
      
      this.audioCapturer = await audio.createAudioCapturer(capturerOptions);
      console.info('AudioCapturer创建成功');
    } catch (error) {
      console.error('AudioCapturer创建失败:', JSON.stringify(error));
      throw error;
    }
  }
  
  async startCapture(): Promise<void> {
    if (!this.audioCapturer) {
      throw new Error('AudioCapturer未初始化');
    }
    await this.audioCapturer.start();
  }
  
  async stopCapture(): Promise<void> {
    if (!this.audioCapturer) {
      return;
    }
    await this.audioCapturer.stop();
  }
  
  release(): void {
    if (this.audioCapturer) {
      this.audioCapturer.release();
      this.audioCapturer = null;
    }
  }
}

配置说明：

• samplingRate: SAMPLE_RATE_16000：16kHz是语音识别领域的标准采样率，既能保证识别精度，又能控制带宽和功耗。
• source: SOURCE_TYPE_MIC：明确指定麦克风输入，不要用SOURCE_TYPE_DEFAULT，某些设备上默认源可能不是麦克风。
• usage: STREAM_USAGE_VOICE_COMMUNICATION：这个设置会让系统优先优化语音通道的延迟和降噪。

4. 创建AudioRenderer（音频播放器）

音频播放器用于播放语音合成结果（TTS）或处理后的音频文件。

// service/AudioRenderService.ets
import { audio } from '@kit.MediaKit';

export class AudioRenderService {
  private audioRenderer: audio.AudioRenderer | null = null;
  
  async initRenderer(): Promise<void> {
    try {
      const audioManager = audio.getAudioManager();
      const rendererOptions: audio.AudioRendererOptions = {
        streamInfo: {
          samplingRate: audio.AudioSamplingRate.SAMPLE_RATE_16000,
          channels: audio.AudioChannel.CHANNEL_1,
          sampleFormat: audio.AudioSampleFormat.SAMPLE_FORMAT_PCM_16_BIT,
          encodingType: audio.CodecType.CODEC_AUDIO_PCM
        },
        rendererInfo: {
          usage: audio.StreamUsage.STREAM_USAGE_VOICE_COMMUNICATION, // 语音通信场景
          rendererFlags: 0
        }
      };
      
      this.audioRenderer = await audio.createAudioRenderer(rendererOptions);
      console.info('AudioRenderer创建成功');
    } catch (error) {
      console.error('AudioRenderer创建失败:', JSON.stringify(error));
      throw error;
    }
  }
  
  async writeAudioData(data: ArrayBuffer): Promise<void> {
    if (!this.audioRenderer) {
      throw new Error('AudioRenderer未初始化');
    }
    await this.audioRenderer.write(data);
  }
  
  release(): void {
    if (this.audioRenderer) {
      this.audioRenderer.release();
      this.audioRenderer = null;
    }
  }
}

5. 获取音频设备列表

有时需要检测当前可用的音频设备（比如蓝牙耳机是否连接），以便切换路由。

// service/DeviceManager.ets
import { audio } from '@kit.MediaKit';

export class DeviceManager {
  static async getInputDevices(): Promise<audio.AudioDeviceDescriptor[]> {
    const audioManager = audio.getAudioManager();
    
    try {
      const devices = await audioManager.getDevices(audio.DeviceFlag.INPUT_DEVICES);
      return devices;
    } catch (error) {
      console.error('获取输入设备失败:', JSON.stringify(error));
      return [];
    }
  }
  
  static async getOutputDevices(): Promise<audio.AudioDeviceDescriptor[]> {
    const audioManager = audio.getAudioManager();
    
    try {
      const devices = await audioManager.getDevices(audio.DeviceFlag.OUTPUT_DEVICES);
      return devices;
    } catch (error) {
      console.error('获取输出设备失败:', JSON.stringify(error));
      return [];
    }
  }
}

6. 主界面整合

// pages/Index.ets
import { AudioCaptureService } from '../service/AudioCaptureService';
import { AudioRenderService } from '../service/AudioRenderService';
import { DeviceManager } from '../service/DeviceManager';
import { PermissionUtil } from '../utils/PermissionUtil';

@Entry
@Component
struct Index {
  private captureService: AudioCaptureService = new AudioCaptureService();
  private renderService: AudioRenderService = new AudioRenderService();
  @State deviceList: string = '';
  
  async aboutToAppear(): Promise<void> {
    // 1. 获取UIAbilityContext（实际项目中建议通过依赖注入传递）
    const context = getContext().applicationContext;
    
    // 2. 申请权限
    const granted = await PermissionUtil.requestMicrophonePermission(context);
    if (!granted) {
      console.error('麦克风权限被拒绝');
      return;
    }
    
    // 3. 初始化音频服务
    try {
      await this.captureService.initCapture();
      await this.renderService.initRenderer();
    } catch (error) {
      console.error('音频服务初始化失败:', JSON.stringify(error));
    }
  }
  
  build() {
    Column() {
      Button('开始录音')
        .onClick(async () => {
          try {
            await this.captureService.startCapture();
            console.info('录音已启动');
          } catch (error) {
            console.error('启动录音失败:', JSON.stringify(error));
          }
        })
      
      Button('停止录音')
        .onClick(async () => {
          try {
            await this.captureService.stopCapture();
            console.info('录音已停止');
          } catch (error) {
            console.error('停止录音失败:', JSON.stringify(error));
          }
        })
      
      Button('查询设备')
        .onClick(async () => {
          const inputs = await DeviceManager.getInputDevices();
          const outputs = await DeviceManager.getOutputDevices();
          this.deviceList = `输入设备: ${inputs.length}个\n输出设备: ${outputs.length}个`;
        })
      
      Text(this.deviceList)
    }
    .width('100%')
    .height('100%')
  }
}

常见问题与解决方案

问题1：页面返回后AudioCapturer状态丢失

现象 ：用户进入语音页面，录音正常。返回上一页后再进入，点击录音按钮报错StateError（状态错误）。

原因 ：AudioCapturer和AudioRenderer的生命周期没有被正确处理。当页面销毁时，服务实例被回收，但系统音频管道可能还保持打开状态。再次创建时，旧管道未释放导致冲突。

解决方案：

• 在onPageHide中暂停录音，在onPageShow中恢复（推荐）
• 或在组件销毁时（aboutToDisappear）手动调用release()

// 在Index组件中添加
onPageShow(): void {
  // 页面显示时，如果captureService已经初始化，则不需要重复create
  // 但如果之前调用过stop，需要处理start的逻辑
}

onPageHide(): void {
  // 页面隐藏时暂停录音，但不释放资源
  this.captureService.stopCapture();
}

aboutToDisappear(): void {
  // 组件销毁时释放资源
  this.captureService.release();
  this.renderService.release();
}

问题2：真机录音无声音，采样率设置错误

现象：代码在模拟器上运行正常，但真机录制的声音时长正确，数据量却很大，播放出来全是杂音（白噪声）。

原因 ：某些低端设备只支持SAMPLE_RATE_44100或SAMPLE_RATE_48000，对16kHz采样率的硬件支持不完善。系统会尝试进行采样率转换，如果转换失败则输出空数据。

解决方案：

• 先查询设备支持的采样率列表（通过getAudioManager().getSupportedSamplingRates()）
• 如果16kHz不支持，降级到44.1kHz
• 语音识别引擎仍然能处理44.1kHz的输入（只是带宽浪费）

async getAvailableSamplingRate(): Promise<audio.AudioSamplingRate> {
  const audioManager = audio.getAudioManager();
  const supportedRates = await audioManager.getSupportedSamplingRates();
  
  // 优先16kHz，其次44.1kHz，再次48kHz
  if (supportedRates.includes(audio.AudioSamplingRate.SAMPLE_RATE_16000)) {
    return audio.AudioSamplingRate.SAMPLE_RATE_16000;
  } else if (supportedRates.includes(audio.AudioSamplingRate.SAMPLE_RATE_44100)) {
    return audio.AudioSamplingRate.SAMPLE_RATE_44100;
  }
  return audio.AudioSamplingRate.SAMPLE_RATE_8000; // 兜底
}

问题3：权限弹窗一闪而过，未授权成功

现象 ：调用requestPermissionsFromUser时弹窗几乎不显示，直接返回PERMISSION_DENIED。

原因 ：用户之前在系统设置中选择了"拒绝"且勾选了"不再询问"。或者，UIAbilityContext传入错误，导致系统找不到正确的应用窗口。

解决方案：

• 首次申请前检查授权状态，建议使用checkAccessToken减少弹窗频次
• 如果弹窗被永久拒绝，引导用户去设置中手动开启
• 确保context来自实际的UIAbility，而不是Application或Service

最佳实践

1. 不要在build()方法中创建AudioCapturer ：build()方法在每帧渲染时都可能执行，频繁创建音频资源会触发系统保护机制，导致创建失败。把所有音频服务初始化放在aboutToAppear()或独立的Service类中。

2. 优先使用STREAM_USAGE_VOICE_COMMUNICATION而非STREAM_USAGE_MUSIC：这个设置影响系统的音频降噪和回声消除策略。音乐类型会开启均衡器等效果，对语音输入来说是灾难。

3. 异步错误必须捕获 ：start()和write()都可能会抛出异常（如设备被拔出）。如果不在try-catch中处理，页面会无响应。建议封装统一的错误回调处理机制。

4. 设备切换时主动重建音频管道 ：监听audioManager.on('deviceChange')事件，当检测到输入/输出设备变化时（如插入耳机），手动调用release()再重新初始化。系统默认的自动切换在某些场景下会有延迟。

项目包含完整的音频服务层封装、权限管理工具和主页面UI，可直接在真机上运行测试。

FAQ

Q：为什么模拟器能录音，真机却一直报权限错误？

A：模拟器默认有麦克风权限，不需要动态申请。真机上必须手动触发requestPermissionsFromUser，且弹窗需要用户确认。检查你的module.json5中的权限声明是否完整。

Q：录音数据可以实时处理吗？对性能影响大吗？

A：可以。通过audioCapturer.on('data')监听缓冲区回调，但注意不要在回调中做大量运算，否则会阻塞音频线程。建议只做简单的格式转换（如PCM转WAV），然后通过消息队列将数据传递给子线程处理。

Q：支持多路音频同时输入吗？

A：目前一个AudioCapturer一个输入源。如果需要同时录音和播放（如对讲场景），需要分别创建AudioCapturer和AudioRenderer，并处理回声消除问题。Core Speech Kit不提供内置的AEC（回声消除），需要外部实现。

Q：为什么初始化AudioRenderer时设置了采样率，播放还是音调不对？

A：播放时采样率必须与PCM数据本身的采样率一致，而不是与录音时的采样率一致。例如，如果写入的是16kHz的PCM数据，播放器采样率也必须设为16kHz，否则音调和播放速度都会错位。