更新记录

1.0.0（2025-09-05）

项目初始化

• iOS和Android基础录音功能实现
• 暂停/恢复、进度监控、格式支持等核心功能
• UTS混合开发架构搭建

平台兼容性

uni-app(4.76)

uni-app x(4.76)

hens-recorder

跨端统一录音插件 - UTS实现版本

✨ 特性

• 🎯 跨平台一致性: iOS/Android行为完全统一，相同的API，相同的响应
• 📱 原生性能: UTS混合开发，Swift/Kotlin原生实现，性能卓越
• 🎚️ 完整功能: 录音/暂停/恢复/停止，实时进度，状态监控
• 🔄 智能缓存: iOS端状态缓存优化，减少桥接调用
• 🚨 统一错误处理: 标准化错误码格式，便于应用层处理
• 📊 多订阅模式: 支持多个进度/状态/错误监听器
• 🎵 统一格式: 两端都输出m4a(AAC)格式
• 📂 私有存储: 统一使用应用私有目录，无需额外存储权限

🚀 快速开始

基本用法

import { ensurePermissions, start, pause, resume, stop, getStatus, 
         onRecordingProgress, offRecordingProgress, onStateChange, 
         offStateChange, onError, offError, getCapabilities } 
from '@/uni_modules/hens-recorder'

// 1. 确保权限
ensurePermissions({
  options: { mic: true, notifications: 'auto' },
  success: () => {
    // 2. 开始录音
    start({
      options: {
        format: 'm4a',        // 固定m4a格式(AAC编码)
        quality: 'medium',    // 音质: high/medium/low
        maxDurationMs: 0,     // 0=无限制
        // 可选：自定义输出路径(应用私有目录内)
        // output: { filePath: '/path/to/private/dir/my.m4a' },
        foreground: { 
          enabled: true, 
          channelId: 'recorder', 
          channelName: '录音服务' 
        },
        interruption: 'pause',      // 中断策略: pause/stop/ignore
        progressIntervalMs: 500,    // 进度间隔[100,2000]ms
        ensurePermissions: true     // 自动检查权限
      },
      success: (res) => { console.log('录音开始:', res) },
      fail: (e) => { console.log('录音失败:', e) }
    })
  },
  fail: (e) => { console.log('权限申请失败:', e) }
})

进度与状态监控

// 进度监控 - 支持多订阅
const progressId = onRecordingProgress((status) => { 
  console.log('录音进度:', status.durationMs, 'ms') 
})

// 状态变化监控
const stateId = onStateChange((state, status) => { 
  console.log('状态变化:', state) // idle/recording/paused
})

// 错误监控
const errorId = onError((err) => { 
  console.log('录音错误:', err.errCode, err.errMsg) 
})

// 控制操作
pause({ success: () => {}, fail: console.error })
resume({ success: () => {}, fail: console.error })  
stop({ success: (res) => { 
  console.log('录音完成:', res.status.filePath) 
}, fail: console.error })

// 取消监听
offRecordingProgress(progressId)
offStateChange(stateId)
offError(errorId)

📋 API参考

核心配置

响应格式

// RecorderResult
{
  status: {
    state: 'idle' | 'recording' | 'paused',
    durationMs: number,      // 累计录音时长(毫秒)
    filePath: string         // 录音文件路径
  },
  message?: string,          // 附加消息
  actualFormat: 'm4a',       // 实际输出格式
  autoStopReason?: 'manual' | 'maxDuration' | 'interruption' | 'error'
}

⚠️ 错误码说明

标准格式: "9010XXX:详细说明"

🔧 平台特性

iOS

• ✅ AVFoundation + AVAudioRecorder
• ✅ 状态缓存优化性能
• ✅ 后台录音支持
• ✅ 音频会话中断处理
• ✅ 简化的实例管理

Android

• ✅ MediaRecorder + 前台服务
• ✅ API 24+ 原生暂停/恢复
• ✅ 音频焦点管理
• ✅ 自动存储清理
• ✅ 通知权限适配(Android 13+)

📝 注意事项

1. 格式统一: 两端都输出m4a(AAC)格式，RecorderResult.actualFormat === 'm4a'
2. 权限处理: 建议使用ensurePermissions统一处理权限申请
3. 错误监控: 推荐使用onError统一监听错误，便于集中处理
4. 进度监控: iOS/Android都支持多订阅模式，行为完全一致
5. 存储路径: 统一使用应用私有目录，无需WRITE_EXTERNAL_STORAGE权限

🔗 相关链接

• UTS 语法
• UTS API插件
• Hello UTS