更新记录

0.1.2（2026-05-28） 下载此版本

增加API文档

0.1.1（2026-05-28） 下载此版本

修复已知bug

0.1.0（2026-05-28） 下载此版本

完善基础功能

平台兼容性

uni-app(4.0)

trip-recorder

后台音频录制 UTS 原生插件。

能力

• iOS: 使用 AVAudioSession + AVAudioRecorder 录制音频，支持配置 UIBackgroundModes = audio 后进行后台录制。
• Android: 提供 MediaRecorder 录制实现和麦克风前台服务示例，调用方可按项目需要启用。
• JS 侧统一调用 startRecorder / stopRecorder / getRecorderFiles。
• 支持按 segmentSeconds 分段录制，并通过 onSegment 返回每段本地文件信息。
• 分段重启失败、音频会话中断后恢复失败等运行异常会通过 onError 回调返回，调用方应停止业务侧录音状态并提示用户重试。
• iOS 会监听音频中断和路由变化，尽量在来电、系统语音、蓝牙切换等场景后恢复录制；无法恢复时触发 onError。
• 插件只负责生成本地音频文件，不内置上传、存储服务或远程服务。

注意

• 必须使用自定义调试基座或云打包验证，普通运行基座不一定包含本插件原生能力。
• iOS 后台录音需要在应用配置中声明后台音频能力，并提供明确的用户授权和隐私说明。
• Android 后台持续录音通常需要前台服务、通知权限和麦克风权限，具体权限请按目标系统版本配置。
• 调用方应自行处理录音文件上传、清理、加密、失败重试和隐私合规。

引入

import {
  startRecorder,
  stopRecorder,
  getRecorderFiles,
  isRecording,
} from "@/uni_modules/trip-recorder";

基础示例

let recording = false;

function startAudioRecord() {
  const result = startRecorder({
    // 每段录音时长，单位：秒。常用于分段上传，默认 300。
    segmentSeconds: 60,
    // 采样率，默认 16000。
    sampleRate: 16000,
    // 编码码率，默认 64000。
    bitRate: 64000,
    // Android 前台服务通知文案；iOS 会忽略通知字段。
    notificationTitle: "音频录制中",
    notificationText: "正在录制音频",

    success(res) {
      recording = true;
      console.log("录音启动成功", res);
    },

    fail(res) {
      recording = false;
      console.log("录音启动失败", res);
    },

    complete(res) {
      console.log("startRecorder complete", res);
    },

    onSegment(file) {
      console.log("收到录音分段", file);
      // 可在这里上传 file.path。
      // uploadRecordFile(file.path, file.startTime, file.endTime);
    },

    onError(res) {
      recording = false;
      console.log("录音运行中断", res);
      uni.showToast({
        title: res.msg || "录音已中断，请重试",
        icon: "none",
      });
    },
  });

  console.log("startRecorder 返回值", result);
}

function stopAudioRecord() {
  const result = stopRecorder();
  recording = false;
  console.log("录音已停止", result);
}

function checkAudioRecord() {
  const running = isRecording();
  const result = getRecorderFiles();
  console.log("是否正在录音", running);
  console.log("已生成文件", result.files);
}

API

startRecorder(options)

开始录音。返回 TripRecorderResult。

const result = startRecorder({
  segmentSeconds: 60,
  sampleRate: 16000,
  bitRate: 64000,
  notificationTitle: "音频录制中",
  notificationText: "正在录制音频",
  onSegment(file) {},
  onError(result) {},
  success(result) {},
  fail(result) {},
  complete(result) {},
});

stopRecorder()

停止录音。停止当前正在录制的分段，并返回 TripRecorderResult。

const result = stopRecorder();

getRecorderFiles()

获取当前录音会话中已经生成的本地文件列表。

const result = getRecorderFiles();
console.log(result.files);

isRecording()

获取当前是否正在录音。

const running = isRecording();

options 参数

回调说明

success(result)

startRecorder 启动成功时触发。

fail(result)

startRecorder 启动失败时触发，例如缺少麦克风权限、原生录音启动失败。

complete(result)

startRecorder 调用完成时触发，无论成功或失败都会触发。

onSegment(file)

每完成一个录音分段时触发。适合在这里做上传、入队、缓存记录等操作。

onError(result)

录音已经启动后，如果出现分段重启失败、音频会话中断后恢复失败、前台服务启动异常等情况，会触发该回调。调用方应在这里停止业务侧录音状态，并提示用户重试。

返回数据格式

TripRecorderFile

type TripRecorderFile = {
  // 本地音频文件路径。
  path: string;
  // 本段录音开始时间，格式：yyyy-MM-dd HH:mm:ss。
  startTime: string;
  // 本段录音结束时间，格式：yyyy-MM-dd HH:mm:ss。
  endTime: string;
  // 本段录音时长，单位：秒。
  duration: number;
  // 文件大小，单位：byte。
  size: number;
};

示例：

{
  "path": "/var/mobile/Containers/Data/Application/xxx/Library/Caches/trip_recorder/trip_1710000000.123.m4a",
  "startTime": "2026-05-28 10:00:00",
  "endTime": "2026-05-28 10:01:00",
  "duration": 60,
  "size": 524288
}

TripRecorderResult

type TripRecorderResult = {
  // 1 表示成功，小于 1 表示失败或异常。
  code: number;
  // 状态说明。
  msg: string;
  // 当前原生录音器是否正在录制。
  isRecording: boolean;
  // 当前录音会话已生成的文件列表。
  files: TripRecorderFile[];
};

示例：

{
  "code": 1,
  "msg": "录音已启动",
  "isRecording": true,
  "files": []
}

分段上传建议

startRecorder({
  segmentSeconds: 60,
  onSegment(file) {
    uni.uploadFile({
      url: "https://example.com/upload",
      filePath: file.path,
      name: "file",
      formData: {
        start_time: file.startTime,
        end_time: file.endTime,
        duration: String(file.duration),
      },
      success(uploadRes) {
        console.log("上传成功", uploadRes);
      },
      fail(error) {
        console.log("上传失败，可自行加入重试队列", error);
      },
    });
  },
  onError(result) {
    console.log("录音中断，需要提示用户或重新启动", result);
  },
});

真机验证

1. 云打包或制作自定义调试基座。
2. 调用 startRecorder 开始录制。
3. 授权麦克风权限，Android 还需按系统版本授权通知权限。
4. 退后台/锁屏，等待超过一个分段周期。
5. 通过 onSegment 或 stopRecorder 返回的文件列表检查本地音频文件。
6. 分别测试来电、弱网、断网、导航中、系统回收等场景。