更新记录

0.1.0（2026-09-06）

• 插件版本更新为 0.1.0，未新增或修改运行能力。
• 补充核心特性、平台支持、安装权限、完整接口、参数、事件、结果、状态和错误码表格。
• 补充推荐参数、输出路径、文件提交、生命周期、常见问题、隐私合规和真机验收说明。
• 明确区分源码已实现、编译已通过与自定义基座真机已验证，未提前宣传规划能力。
• 修正示例页在自定义导航模式下的状态栏避让和长页面滚动。

平台兼容性

uni-app x(4.0)

专业录音与实时音频采集

xs-audio-capture-pro 是面向 uni-app x App 的本地录音 UTS 插件。它用一套接口封装 Android 与 iOS 的麦克风权限、M4A/AAC 录音、暂停继续、停止取消、状态变化和实时音量事件。

当前版本：0.1.0

当前版本已通过 Android、iOS 插件模块和示例项目编译，但尚未完成包含本插件的双端自定义基座真机验收。本文把“源码已实现”“编译已通过”和“真机已验证”分开说明，不用编译结果代替真机录音结论。

核心特性

平台支持

开发环境

能力差异

插件只面向 App 原生平台，不支持网页、小程序和鸿蒙平台。

安装与运行

将插件目录放到项目的 uni_modules/xs-audio-capture-pro 后，从插件根目录导入公开接口：

import {
  getAudioCaptureCapabilities,
  getAudioCapturePermission,
  requestAudioCapturePermission,
  startAudioCapture,
  pauseAudioCapture,
  resumeAudioCapture,
  stopAudioCapture,
  cancelAudioCapture
} from '@/uni_modules/xs-audio-capture-pro'

不要从 utssdk 或平台子目录导入内部实现，否则后续升级可能失去兼容性。

原生权限配置

插件自带以下原生声明：

标准基座不包含本插件的原生代码和权限配置。真机调试前需要制作包含本插件的自定义基座，再在真实 Android、iPhone 设备上检查权限弹窗、录音文件和音频中断行为。

快速开始

下面示例先在用户点击后申请权限，再开始录音。业务页面应保存返回的会话编号，并通过同一个编号控制本次录音。

import {
  requestAudioCapturePermission,
  startAudioCapture,
  pauseAudioCapture,
  resumeAudioCapture,
  stopAudioCapture,
  cancelAudioCapture
} from '@/uni_modules/xs-audio-capture-pro'

let currentSessionId = ''

function beginRecord() {
  requestAudioCapturePermission((status) => {
    if (status != 'granted') {
      console.log('用户未授予麦克风权限')
      return
    }

    currentSessionId = startAudioCapture({
      format: 'm4a-aac',
      sampleRate: 16000,
      channels: 1,
      bitRate: 64000,
      outputPath: null,
      meterIntervalMs: 100,
      allowBackground: false
    }, (event) => {
      if (event.type == 'state') {
        console.log('状态变化', event.previousState, event.state, event.reason)
      } else if (event.type == 'meter') {
        console.log('录音时长', event.durationMs, '当前音量', event.amplitude)
      } else if (event.type == 'warning') {
        console.log('非致命提醒', event.reason)
      }
    }, (result) => {
      currentSessionId = ''
      console.log('录音文件', result.filePath)
      console.log('文件大小', result.fileSize)
      console.log('有效时长', result.durationMs)
    }, (error) => {
      currentSessionId = ''
      console.error(error.code, error.message, error.nativeCode)
    })
  }, (error) => {
    console.error(error.code, error.message)
  })
}

function pauseRecord() {
  if (currentSessionId.length > 0) pauseAudioCapture(currentSessionId)
}

function resumeRecord() {
  if (currentSessionId.length > 0) resumeAudioCapture(currentSessionId)
}

function finishRecord() {
  if (currentSessionId.length > 0) stopAudioCapture(currentSessionId)
}

function discardRecord() {
  if (currentSessionId.length > 0) cancelAudioCapture(currentSessionId)
}

接口总览

能力查询

getAudioCaptureCapabilities()

同步返回当前运行平台的能力，不申请权限，也不启动录音。建议在页面初始化时读取它，不要根据系统名称自行猜测能力。

权限接口

getAudioCapturePermission()

Android 的同步权限接口不能稳定区分“从未申请”和“已经拒绝”，因此未授权时统一返回 denied。不要在页面加载时自动申请权限，应在用户点击录音或授权按钮后调用权限申请接口。

requestAudioCapturePermission(onSuccess, onFail)

iOS 当前实现不会主动调用权限申请的失败回调；授权结果统一通过成功回调返回。

开始录音

startAudioCapture(options, onEvent, onSuccess, onFail)

创建唯一录音会话。正常开始后返回非空 sessionId；参数校验、权限或启动失败时返回空字符串，并调用 onFail。

录音参数

当前所有字段都需要显式传入，没有自动补默认值。

公开参数通过校验只表示进入原生录音器的支持范围。不同设备是否精确接受某组采样率、声道和码率，仍需读取最终文件并在真机上核对。

事件回调

onEvent 在录音过程中可被多次调用。所有事件使用同一结构，不适用的字段返回空值。

iOS 收到系统中断开始时会把录音切换为暂停状态；中断结束只发送事件，不会自动继续，业务页面需要让用户确认后主动调用继续接口。

成功结果

只有 stopAudioCapture() 正常关闭编码器并提交最终文件后，onSuccess 才会调用一次。

结果中的采样率、声道和码率是传给平台录音器的参数，不等同于独立解析文件头得到的实测值。对音频参数有严格要求时，请在真机上用音频分析工具复核最终文件。

失败回调

onFail 接收结构化错误：

会话控制

在错误状态调用暂停、继续或停止不会抛出同步异常，而是向当前会话发送 warning。传入空编号或不匹配的编号也不会误控制其他会话；如果当前仍有活动会话，会收到 sessionIdMismatch 警告。

状态流转

空闲 -> 准备中 -> 录音中 <-> 已暂停 -> 停止中 -> 已完成
                    |          |           |
                    +----------+-----------+-> 失败
                    +-----------------------> 已取消

输出路径与文件行为

录音过程使用与最终文件同目录的隐藏 .partial 文件。正常停止并确认文件非空后，插件才把临时文件移动为最终文件；取消或致命错误会删除临时文件。因此业务层只能在成功回调后使用、上传或播放 filePath。

推荐参数

这些是起始建议，不是所有设备的实测保证。正式上线前应覆盖目标设备、耳机和蓝牙输入进行验证。

错误码

页面与生命周期建议

• 页面上持续展示当前状态、有效时长、暂停、完成和取消入口。
• 开始按钮防止重复点击；只有拿到非空会话编号后才开放控制按钮。
• 页面离开前根据业务语义主动停止或取消，不要让会话失去控制入口。
• 音量事件只用于波形、动效和静音提示，不要把它当作校准声压数据。
• 成功回调后再播放、上传或持久化路径；取消和失败都不应保留业务记录。
• 长时间录音由业务层设置计时提醒或主动停止；当前插件没有自动限时和自动分片。

常见问题

为什么查询权限返回拒绝，但用户还没看到过弹窗？

Android 当前只能稳定判断“是否已经授权”，不能稳定区分“从未申请”和“已经拒绝”。请在用户点击按钮后调用 requestAudioCapturePermission()，不要只依赖同步查询结果决定是否允许申请。

为什么开始录音返回空字符串？

创建失败时会返回空字符串，同时调用失败回调。应优先查看 error.code、error.message 和 error.nativeCode，常见原因是权限未授权、参数不合法、已有活动会话或目标路径不可写。

为什么拿到路径后文件还不能使用？

录音中只存在隐藏临时文件。只有正常调用停止并进入成功回调后，最终文件才完成提交。不要自行拼接文件名，也不要访问 .partial 文件。

取消录音为什么没有成功或失败回调？

取消是一个正常但不产出文件的终态。插件发送 state = cancelled 事件，清理临时文件，不调用录音成功回调，也不把用户主动取消当作失败。

系统中断结束后为什么没有自动继续？

iOS 中断开始会暂停录音，中断结束只发出 interruption 事件。为避免在用户不知情时重新采集，当前需要用户确认后主动继续。

能否后台、锁屏或静默录音？

当前版本不支持后台录音，allowBackground 必须为 false。插件也不提供静默启动、隐藏通知、远程偷录或电话通话录音。

能否直接获得 PCM、波形数组或自动去掉静音？

当前不支持 PCM 帧、语音活动检测、自动分片或静音自动停止。音量事件可以驱动简单的电平动画，但不能替代原始音频帧。

插件会上传或识别录音内容吗？

不会。插件只在设备本地采集并写入文件。上传、转写、内容分析和文件保留策略都由业务项目在成功回调后自行实现。

当前限制

• 仅支持 m4a-aac，不支持 WAV 或裸 PCM 文件。
• 不向 UTS 层发送实时 PCM 帧。
• 不支持语音活动检测、自动静音停止和自动分片。
• 不支持 Android 音频焦点、音频路由变化事件。
• 不支持后台录音、异常退出片段恢复和进程重启续录。
• 未完成双端自定义基座真机验收，暂不能把所有设备组合描述为已验证。

验证建议

正式使用前至少完成以下真机测试：

1. 首次授权、拒绝、永久拒绝和系统设置恢复。
2. 开始、暂停、继续、停止和取消的完整状态流转。
3. 默认路径、自定义路径、已存在文件和不可写路径。
4. 系统播放器实际播放输出文件，并独立核对容器、编码、时长、采样率和声道。
5. iOS 电话、闹钟或语音助手中断，以及有线、蓝牙输入切换。
6. 5 分钟、30 分钟和连续 50 次会话的稳定性。
7. 前后台切换、锁屏、磁盘不足和应用被系统终止时的边界行为。

隐私与合规

插件不会赋予业务方录音的法律许可。业务方应在录音前清晰告知相关人员录音目的、保存期限和使用范围，并遵守所在地关于同意、隐私、劳动和客户服务录音的规定。

更多文档

• docs/API.md：完整类型、接口、回调、状态和错误说明。
• docs/AUDIO_FORMATS.md：格式、参数组合、体积估算和音量数据说明。
• docs/BACKGROUND_AND_PRIVACY.md：权限、前后台边界、隐私与宿主检查清单。
• docs/FAQ.md：接入和排错问题汇总。
• docs/TESTING.md：双端真机测试矩阵。
• docs/VERIFICATION.md：当前已经完成与尚未完成的验证证据。

官方参考

• UTS 原生插件开发说明
• uni_modules 插件规范