更新记录

1.1.0（2026-04-23）

• 完善插件发布文档，补充平台支持、权限说明、API 用法、错误码和接入建议。
• 对齐当前代码能力，补充 getRecordPermissionStatus 与 requestRecordPermission 文档。
• 明确 Android 与 iOS 的实现差异：
  • Android 提供实时 PCM 采集，权限接口为兼容层，默认返回已授权。
  • iOS 已接入 AVAudioEngine + AVAudioConverter 的实时采集链路，并提供权限查询与申请接口。

1.0.0（2026-04-17）

• 初始化 UTS API 插件结构
• 增加实时录音帧采集接口：
  • startRecordFrameStream
  • stopRecordFrameStream
• 完成 Android 端基础实时 PCM 帧采集链路
• 增加统一的接口定义与错误码定义
• 增加插件使用说明文档

平台兼容性

uni-app(3.7.6)

pcm-realtime

pcm-realtime 是一个 uni-app UTS API 插件，用于在 App 端采集实时 PCM 音频帧，适合接入流式 ASR、实时字幕、语音输入和语音助手等场景。

当前版本已经包含：

• Android 实时 PCM 采集实现
• iOS 实时 PCM 采集实现
• 统一的权限查询 / 申请接口
• 统一的错误码与回调结构

功能概览

• 基于 UTS API 实现，可直接在 uni_modules 中集成
• 支持 startRecordFrameStream / stopRecordFrameStream
• 支持配置采样率、声道数、帧大小
• 通过回调持续返回 Base64 编码的 PCM 帧
• 内置权限查询与权限申请接口
• 适合在业务层继续封装 WebSocket 推流和 ASR 结果处理

适用场景

• 流式语音识别
• 实时字幕
• 按住说话
• 语音输入框
• 语音助手或实时对话

平台支持

环境要求

• HBuilderX 3.6.8+
• uni-app 3.1.0+
• Android 5.0+
• iOS 12.0+

安装方式

方式一：本地集成

将插件放入项目目录：

uni_modules/pcm-realtime

然后在业务代码中直接引用：

import {
  startRecordFrameStream,
  stopRecordFrameStream,
  getRecordPermissionStatus,
  requestRecordPermission
} from '@/uni_modules/pcm-realtime'

方式二：插件市场安装

发布到 uni-app 插件市场后，可通过 HBuilderX 安装到项目中。

权限说明

Android

需要麦克风权限：

android.permission.RECORD_AUDIO

说明：

• 当前 Android 端 getRecordPermissionStatus / requestRecordPermission 是统一接口兼容层，默认返回已授权。
• 实际权限申请建议仍由业务层统一处理。

iOS

需要在应用配置中声明麦克风权限用途，例如：

NSMicrophoneUsageDescription

说明：

• iOS 端实现了真实的权限查询与申请逻辑。
• 如果未正确配置麦克风权限说明，系统将无法正常拉起录音权限弹窗。

导出 API

startRecordFrameStream(options)

开始实时录音并通过 onFrame 持续回调 PCM 帧。

type RecordFrameEvent = {
  pcmBase64: string
  byteLength: number
  sampleRate: number
  channels: number
  timestamp: number
}

type StartRecordFrameOptions = {
  sampleRate?: number
  channels?: number
  frameSize?: number
  onFrame: (event: RecordFrameEvent) => void
  onStart?: () => void
  onStop?: () => void
  onError?: (error: RecordFrameFail) => void
}

参数说明：

• sampleRate：默认值为 16000
• channels：默认值为 1
• frameSize：默认值为 3200，通常表示单次回调目标字节数
• onFrame：每次收到一帧实时 PCM 数据时触发
• onStart：录音成功启动后触发
• onStop：录音停止后触发
• onError：录音过程出现错误时触发

stopRecordFrameStream()

停止实时录音。

getRecordPermissionStatus()

获取录音权限状态。

返回值：

• iOS: granted / denied / undetermined / unknown
• Android: 当前实现固定返回 granted

requestRecordPermission(callback)

请求录音权限。

type RequestRecordPermission = (
  callback: (granted: boolean, status: string) => void
) => void

说明：

• iOS 会触发系统权限申请
• Android 当前实现直接回调 true, 'granted'

错误码

type RecordFrameErrorCode =
  | 9010001
  | 9010002
  | 9010003
  | 9010004
  | 9010005

使用示例

基础采集

import {
  startRecordFrameStream,
  stopRecordFrameStream
} from '@/uni_modules/pcm-realtime'

startRecordFrameStream({
  sampleRate: 16000,
  channels: 1,
  frameSize: 3200,
  onStart() {
    console.log('record start')
  },
  onFrame(event) {
    const pcmBuffer = uni.base64ToArrayBuffer(event.pcmBase64)
    console.log('frame byteLength:', event.byteLength)

    // 这里可以继续推送到 WebSocket / SocketTask / 原生桥
    // socket.send({ data: pcmBuffer })
    console.log(pcmBuffer.byteLength)
  },
  onError(error) {
    console.error('record error:', error)
  },
  onStop() {
    console.log('record stop')
  }
})

// 业务结束时调用
stopRecordFrameStream()

iOS 权限申请

import {
  getRecordPermissionStatus,
  requestRecordPermission
} from '@/uni_modules/pcm-realtime'

const status = getRecordPermissionStatus()

if (status !== 'granted') {
  requestRecordPermission((granted, nextStatus) => {
    console.log('permission result:', granted, nextStatus)
  })
}

输出数据说明

插件回调中的 pcmBase64 为 Base64 编码后的 PCM 音频数据。

推荐在业务层进行以下处理：

• 使用 uni.base64ToArrayBuffer() 转为 ArrayBuffer
• 按业务协议写入 WebSocket
• 在 ASR 返回结果后自行更新页面 UI

平台差异

Android

• 基于 AudioRecord
• 直接输出 PCM 16-bit 数据
• 录音权限建议由业务侧统一申请

iOS

• 基于 AVAudioEngine
• 使用 AVAudioConverter 转换到目标采样率 / 声道数 / PCM 16-bit
• 已实现权限查询与申请接口
• 建议在真机环境下完成最终稳定性验证

接入建议

• 流式 ASR 建议固定使用：
  • sampleRate = 16000
  • channels = 1
• 业务层建议自行封装一层录音管理器，统一处理：
  • 权限申请
  • Base64 转 ArrayBuffer
  • WebSocket 推流
  • 停止录音与资源释放
  • 错误提示与日志上报

已知说明

• 当前插件只负责本地实时采集，不负责上传和识别。
• 如果重复调用 startRecordFrameStream，会返回 9010001。
• iOS 与 Android 的权限实现存在差异，发布说明中应按平台分别提示。

License

请根据你的发布策略自行补充。