更新记录

1.0.7（2026-08-13）

更新日志 外部录音设备时强制不开启回声消除，开了也没用

1.0.6（2026-08-11）

修复云打包错误

1.0.5（2026-08-11）

更新文档

平台兼容性

uni-app(5.15)

uni-app x(5.15)

tki-audio-recorder

录音+帧回调+回声消除+PCM流播放，支持实时 PCM 帧数据回调、PCM 流播放、通话模式（AEC + NS + AGC）。

适用于：H5（AudioWorklet）、Android（AudioRecord）、iOS（AVAudioEngine，不确定）。

目录

• 安装
• 快速开始
• API 文档
  • 录音控制
  • 录音事件监听
  • 录音状态查询
  • PCM 播放控制
  • 播放事件监听
  • 资源销毁
• RecordOptions 配置项
• RecordEndInfo 回调信息
• 完整示例
• 平台差异说明
• 常见问题

安装

通过 uni_modules 安装（推荐）

在 HBuilderX 中右键项目目录 → 插件市场 → 搜索 tki-audio-recorder → 点击安装。

手动安装

将 uni_modules/tki-audio-recorder 目录复制到项目的 uni_modules/ 目录下。

配置

Android: 插件会自动处理录音权限。Android 6.0+ 需要运行时权限，插件内部已处理。

iOS: 项目 manifest.json → App模块配置 → 勾选 AVFoundation（音频录制和播放）。

如果需要配置隐私权限描述，可在 manifest.json 的 iOS 节点下添加：

{
  "plist": {
    "NSMicrophoneUsageDescription": "需要麦克风权限以录制音频"
  }
}

快速开始

import {
  // 录音控制
  recordStart, recordStop, recordPause, recordResume, recordMute, recordUnmute,
  // 录音事件
  onRecordStop, onRecordError, onRecordTimer, onRecordFrame, onRecordDecibel, onRecordWaveform,
  // PCM 播放
  pcmInit, pcmPlay, pcmPlayWav, pcmAppend, pcmStop, pcmReplay, pcmClear, pcmStatus,
  // 播放事件
  onPcmStatus, onPcmError, onPcmDecibel, onPcmWaveform, onPcmTimer,
  // 资源销毁
  recordDestroy, pcmDestroy,
} from '@/uni_modules/tki-audio-recorder'

// 1. 开始录音
recordStart({
  sampleRate: 16000,
  enableCommunicationMode: true,
  format: 'wav',
})

// 2. 监听录音结束
onRecordStop((info) => {
  console.log('录音结束，时长:', info.duration, '秒')
  console.log('WAV 文件:', info.tempFilePath)
  // 回放：通过 PCM 播放器（含 FFT 频谱/分贝/计时）
  if (info.tempFilePath) {
    pcmPlayWav(info.tempFilePath)
    // 或用系统播放器: uni.createInnerAudioContext()
  }
})

// 3. 停止录音
setTimeout(() => {
  recordStop()
}, 5000) // 5 秒后停止

API 文档

录音控制

内部调用链：

函数	内部调用	触发回调?
recordStop()	吐出剩余帧 → 停止录音引擎	✅ 触发 onRecordStop
recordDestroy()	先清回调 → recorder.stop()	❌ 不触发（回调已清完，防止最后一帧反调触发 pcmPlay）

recordStart(options?)

recordStart({
  sampleRate: 16000,             // 采样率，默认 16000
  numberOfChannels: 1,           // 声道数，默认 1（单声道）
  format: 'wav',                 // 录音格式：'wav' 或 'pcm'
  duration: 0,                   // 录音时长限制(ms)，0=不限时
  bufferSize: 4096,              // onRecordFrame 回调触发阈值
  enableCommunicationMode: true, // 通话模式(含 AEC+NS+AGC)
})

• format='wav'：录音结束后生成 WAV 文件并通过 onRecordStop 返回文件路径
• format='pcm'：仅通过 onRecordFrame 回调原始 PCM 数据，不生成文件
• 如果已处于录音状态，重复调用会被忽略

录音事件监听

错误码说明：

onRecordFrame(callback)

回调固定返回 base64 编码的字符串（16-bit 小端序 Int16 PCM），三端一致。 每帧样本数等于 bufferSize（默认 4096，约 256ms@16kHz）。

标准 ArrayBuffer 用 uni.base64ToArrayBuffer() 转：

onRecordFrame((base64) => {
  const pcm = uni.base64ToArrayBuffer(base64)  // ArrayBuffer
  const samples = new Int16Array(pcm)           // Int16 PCM 样本
  console.log('收到帧，样本数:', samples.length)
})

onRecordDecibel(callback)

onRecordDecibel((db: number) => {
  // db: 范围约 -96 ~ 0（-96 ≈ 静音，0 ≈ 最大声）
})

onRecordWaveform(callback)

64 段 FFT 频谱归一化值 [0, 1]，对应 0~8000Hz（@16kHz 采样率）。

onRecordWaveform((arr: number[]) => {
  const bass   = arr.slice(0, 2).reduce((a, b) => a + b, 0) / 2     // ~0~250Hz
  const mid    = arr.slice(2, 32).reduce((a, b) => a + b, 0) / 30   // ~250~4000Hz
  const treble = arr.slice(32).reduce((a, b) => a + b, 0) / 32      // ~4000~8000Hz
})

录音状态查询

PCM 播放控制

内部调用链（仅记录有副作用的函数，纯查询/设置类省略）：

函数	内部调用	playQueue	allData	还能 pcmReplay()?
pcmStop()	player.stop()	❌ 清空	✅ 保留	✅ 能
pcmClear()	player.stop() + 清 allData	❌ 清空	❌ 清空	❌ 不能
pcmDestroy()	player.destroy() → player.stop() + 释放资源 + 置空回调 → player=null	❌ 不可访问	❌ 不可访问	❌ 不能
pcmReplay()	player.stop() + 从 allData 重建队列 + play()	重建	✅ 保留	—

不要冗余：

• pcmStop() + pcmClear() → 只需 pcmClear()
• pcmStop() + pcmDestroy() → 只需 pcmDestroy()

pcmPlay data 支持的类型：

pcmPlay 只接受 base64 PCM 数据，不支持 ArrayBuffer 或 WAV 文件路径。播放 WAV 文件用 pcmPlayWav 或 uni.createInnerAudioContext()。

pcmInit({ inputSampleRate: 16000 })   // 页面加载时初始化一次

// 使用 onRecordFrame 配合 pcmPlay（推荐方式）
onRecordFrame((base64) => {
  pcmPlay(base64)                      // 实时回放
  queue.push(base64)                   // 存入队列
})
// 批量播放
pcmPlay([base64Frame1, base64Frame2])
// 播放 WAV 文件（自动解析 → PCM 播放，FFT/分贝/计时均有效）
pcmPlayWav('file:///storage/emulated/0/.../recording.wav')
pcmPlayWav('blob:http://localhost:5173/xxxxx')
// 追加到队列
pcmAppend(base64Frame)
pcmAppend(base64Frame, true)           // 追加并立即播放

pcmInit(config?) 配置项 PlayerConfig：

PlayerConfig 参数表：

bufferSize 需与 recordStart({ bufferSize }) 一致。Android 端用此值计算 AudioTrack 缓冲区和无数据超时阈值。

pcmStatus() 返回值 PlaybackStatus：

播放事件监听

资源销毁

内部调用链：

onUnload(() => {
  recordDestroy()   // 已含 stop，不触发回调
  pcmDestroy()      // 已含 stop，销毁播放器
})

不要冗余：

• pcmStop() + pcmClear() → 只需 pcmClear()
• pcmStop() + pcmDestroy() → 只需 pcmDestroy()
• recordStop() + recordDestroy() → 只需 recordDestroy()（需要 onRecordStop 时除外）

RecordOptions 配置项

enableCommunicationMode 各平台实现

Android 回声消除说明

Android 端 enableCommunicationMode: true 选择 VOICE_COMMUNICATION 音频源。硬件 AEC 生效需满足以下条件：

1. 使用 pcmPlay 播放音频（不能只用 uni.createInnerAudioContext）
2. 在 recordStart() 之前调用 pcmInit()，确保 PCMPlayer 已创建
3. 在录音进行中播放（停止录音后 sessionId 失效）

// ✅ AEC 生效的正确顺序
pcmInit({ inputSampleRate: 16000 })   // 1. 先创建 PCMPlayer
recordStart({                         // 2. AudioRecord 启动，sessionId=123
  enableCommunicationMode: true,      //    自动传到 PCMPlayer
})
// 录音中...
pcmPlay(data)                         // 3. AudioTrack 用 sessionId=123 创建 ✅ 硬件 AEC

// ❌ AEC 无效的典型错误
recordStart({})                       // 1. 录音启动，但 player==null，sessionId 无法传递
pcmInit({})                           // 2. 新建 player，sessionId=0
pcmPlay(data)                         // 3. AudioTrack 以 sessionId=0 创建 ❌ 无 AEC

原理：Android 硬件 AEC 要求 AudioRecord 和 AudioTrack 用同一个 audioSessionId。recordStart 获取真实 sessionId 传给 PCMPlayer，pcmPlay 首次创建 AudioTrack 时用该 sessionId，系统才挂载硬件 AEC。

Android USB 录音设备说明

Android 端可通过 enableExternalMic: true 将录音输入路由到外置 USB 音频设备（如 USB 摄像头麦克风、USB 声卡），适合需要外部拾音的场景。

recordStart({
  enableExternalMic: true,          // 优先使用 USB 麦克风
  // 注意：enableExternalMic=true 时 enableCommunicationMode 被强制忽略，
  // 无论传 true/false，系统回声消除（AEC）一律禁用
  enableCommunicationMode: false,
})

前提条件：

1. 系统要求：Android 8.0（API 26）及以上
2. 设备要求：系统能识别到 USB 音频输入设备（TYPE_USB_DEVICE 或 TYPE_USB_HEADSET）
3. 未检测到 USB 设备时静默跳过，自动使用系统默认输入设备，不影响正常录音

注意事项：

原理：enableExternalMic: true 时，AudioRecord 创建后调用 setPreferredDevice() 显式指定 USB 设备作为输入源；无 USB 设备或路由失败时静默降级，不改变默认行为。

RecordEndInfo 回调信息

onRecordStop 回调的参数：

各平台文件路径格式

完整示例

录音 + 文件回放

import {
  recordStart, recordStop, recordPause, recordResume,
  recordMute, recordUnmute,
  onRecordStop, onRecordError, onRecordTimer,
  recordDestroy, pcmDestroy,
} from '@/uni_modules/tki-audio-recorder'

const state = reactive({
  isRec: false,
  isPaused: false,
  isMuted: false,
  duration: 0,
  filePath: '',
})

// 录音控制
function startRec() {
  state.filePath = ''
  state.duration = 0
  recordStart({
    sampleRate: 16000,
    enableCommunicationMode: true,
    format: 'wav',
    bufferSize: 4096,
  })
  state.isRec = true
}

function stopRec() { recordStop() }
function pauseRec() { recordPause(); state.isPaused = true }
function resumeRec() { recordResume(); state.isPaused = false }
function muteRec() { recordMute(); state.isMuted = true }
function unmuteRec() { recordUnmute(); state.isMuted = false }

// 事件监听
onRecordStop((info) => {
  state.isRec = false
  state.isPaused = false
  state.filePath = info.tempFilePath
  console.log(`录制 ${info.duration}秒, 文件: ${info.tempFilePath}`)
})

onRecordTimer((sec) => { state.duration = sec })

// 回放
function playWav() {
  if (!state.filePath) return
  const audio = uni.createInnerAudioContext()
  audio.src = state.filePath
  audio.onEnded(() => audio.destroy())
  audio.onError(() => audio.destroy())
  audio.play()
}

// 页面卸载
onUnload(() => {
  recordDestroy()
  pcmDestroy()
})

实时 PCM 回放（对讲机模式）

import {
  recordStart, recordStop, pcmInit, pcmPlay,
  onRecordFrame, onRecordStop, onRecordError,
  recordDestroy, pcmDestroy,
} from '@/uni_modules/tki-audio-recorder'

// 页面加载时初始化播放器
pcmInit({ inputSampleRate: 16000 })

// 监听录音错误（如权限被拒）
onRecordError((err) => {
  console.error('录音出错:', err.errCode, err.errMsg)
  uni.showToast({ title: '录音失败', icon: 'none' })
})

// 录音时实时回放（base64 直传，无需转换）
onRecordFrame((data) => {
  pcmPlay(data)
})

function start() {
  recordStart({
    sampleRate: 16000,
    enableCommunicationMode: true,
    format: 'pcm',
    bufferSize: 4096,
  })
}

onUnload(() => {
  recordDestroy()
  pcmDestroy()
})

format: 'pcm' 不生成 WAV 文件，仅帧回调。

平台差异说明

功能差异

onRecordFrame 返回数据格式

三端统一返回 base64 编码的字符串（16-bit 小端序 Int16 PCM），无平台差异。

onRecordFrame((base64) => {
  // 三端一致，无需任何平台判断
  const pcm = uni.base64ToArrayBuffer(base64)  // 可选：转 ArrayBuffer
  const samples = new Int16Array(pcm)
})

常见问题

Q: 录音后无法播放 WAV 文件？

Android 端 WAV 文件保存在 externalCacheDir（/sdcard/Android/data/.../cache/），uni.createInnerAudioContext 可以直接访问。 文件管理器找不到时检查路径是否包含 Android/data/（外部存储）。

Q: 为什么静音后 WAV 文件还是原来的大小？

静音不改变文件时长和大小——PCM 数据替换为零，tempFilePath 指向的 WAV 文件时长不变。

Q: pcmPlay 只接受 base64，为什么？

Android 端 UTS 桥接对 ArrayBuffer/Uint8Array 等二进制类型存在类型丢失问题，base64 字符串可完全规避。 如需从 ArrayBuffer 转换为 base64，使用 btoa 或 uni.arrayBufferToBase64。

Q: H5 端录制时间长后页面卡顿？

H5 端 PCM 数据分块存储（pcmChunks: Float32Array[]），不每帧拷贝整个缓冲区。

Q: 录音时长不准？

Web 端用 AudioContext.currentTime（暂停时自动冻结）。 Android/iOS 用 elapsedPaused 累计暂停时间扣除。 时长偏差检查是否误调了 pause()/resume()。

Q: 录音文件保存在哪里？

持久保存需自行复制到应用其他目录。

Q: 支持后台录音吗？

• H5: 不支持（浏览器限制，页面不可见时 getUserMedia 会暂停）
• Android: 支持（Service 保活需额外配置）
• iOS: 不确定（需配置 Background Modes → Audio, AirPlay, and Picture in Picture）