更新记录

1.0.0（2026-06-17）

首次更新

平台兼容性

uni-app(4.84)

uni-app x(4.84)

hl-audio-uts (高级音频处理插件)

新手必读：
首次使用 UTS 插件，请优先阅读 《UTS 插件新手使用与调试指南》，了解自定义基座打包等必经流程。

简介

hl-audio-uts 是一款提供底层音频控制能力的 UTS 原生插件，支持 Android 和 iOS 平台。与常规 WebAudio 相比，本插件直接调用系统底层音频框架，提供更低的延迟与更丰富的硬件级控制，适用于实时通讯、智能语音识别 (ASR) 等场景。

核心特性

• 硬件级 3A 处理：支持开启底层硬件 AEC（回声消除）、NS（噪声抑制）、AGC（自动增益），提升通话与语音识别场景下的音频质量。
• 实时音频帧回调：支持以自定义间隔回调 PCM 数据帧（Base64 格式），适用于实时语音流传输。
• 多格式编码支持：底层集成原生 C++ 编码器，支持将采集的音频保存为 PCM、WAV、G.711 (a-law / u-law) 格式。
• 动态设备路由：提供音频输出路由控制，支持代码级切换扬声器、听筒，并支持监听蓝牙耳机（含 SCO 通道）的状态变更。
• 波形可视化特征提取：底层以指定频率提取音频波形特征数据（Float32 归一化格式），便于前端实现声波动画渲染。
• 自动权限管理：配置 requestPermissionsIfNeeded 参数后，可在缺少麦克风权限时自动拉起系统授权机制，减少上层业务逻辑判断。

API 参考

1. 引入插件与初始化

import * as HlAudio from '@/uni_modules/hl-audio-uts'

// 启用调试日志
HlAudio.enableDebugLog()

// 创建音频控制器实例
const controller = HlAudio.createAudioController({
  sampleRate: 16000,
  channels: 1,
  bitDepth: 16,
  format: 'wav',
  enableAec: true,
  enableNs: true,
  enableAgc: true,
  saveToFile: true,
  filePath: '_doc/audio_record.wav',
  enablePcmCallback: true,
  enableVolumeCallback: true,
  pcmCallbackInterval: 100,
  volumeCallbackInterval: 150,
  requestPermissionsIfNeeded: true // 自动拉起麦克风权限申请
})

2. 配置参数 (AudioRecordConfig)

3. 事件回调监听

在开始录音前，建议注册需要的状态回调。

// 状态变更回调
controller.onStateChanged((state) => {
  console.log(`当前状态: ${state.state}, 消息: ${state.message}`)
})

// 实时音量回调
controller.onVolumeChange((db) => {
  console.log(`当前音量分贝: ${db}`)
})

// 实时音频帧回调
controller.onPcmFrame((frame) => {
  console.log(`收到音频流，截取长度: ${frame.length}, 数据: ${frame.base64Data}`)
})

// 设备插拔与路由变更回调
controller.onDeviceChanged((device) => {
  console.log(`音频设备改变: ${device.name} [${device.type}], 状态: ${device.connected}`)
})

4. 录音与播放控制

controller.startRecord()  // 开始录音
controller.pauseRecord()  // 暂停
controller.resumeRecord() // 恢复
controller.stopRecord()   // 停止

// 播放本地音频文件
controller.startPlay({ filePath: '/path/to/your/audio.wav', format: 'wav' })

5. 获取波形可视化特征数据

前端可通过定时器轮询获取底层计算完成的特征值用于渲染：

const waveData = controller.getVisualizationData()
// waveData 为 Base64 格式的 Float32Array

6. 销毁实例

// 当页面卸载或不再需要音频服务时调用
controller.release()