# record-manage

**Repository Path**: Fie_Ryan/record-manage

## Basic Information

- **Project Name**: record-manage
- **Description**: AVRecorderManage 是一个基于 HarmonyOS 开发的音视频录制管理库，采用单例模式设计，提供完整的音频录制生命周期管理能力。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/Fie_Ryan
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-26
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 音视频录制, HarmonyOS, AVRecorder, 录音录屏, ArkTS

## README

# AVRecorderManage 音视频录制库文档

---

## 一、库概述

`AVRecorderManage` 是一个基于 **HarmonyOS** 开发的音视频录制管理库，采用**单例模式**设计，提供完整的音频录制生命周期管理能力。

### 1.1 核心特点

| 特性 | 说明 |
|-----|------|
| **单例模式** | 全局唯一实例，避免资源浪费和状态混乱 |
| **状态管理** | 完整的录制状态机，支持状态监听与回调 |
| **生命周期管理** | 初始化、启动、暂停、恢复、停止、释放全流程控制 |
| **默认配置** | 内置音频/视频默认配置，开箱即用 |
| **扩展性强** | 支持自定义编码参数、输出路径和文件格式 |
| **错误处理** | 完善的异常捕获和错误回调机制 |
| **日志系统** | 可配置的日志输出模式，便于调试和生产环境切换 |

### 1.2 功能状态

| 功能模块 | 状态 | 说明 |
|---------|------|------|
| ✅ **音频录制** | 已实现 | 完整支持麦克风录音、暂停、恢复、停止 |
| ⏳ **视频录制** | 待开发 | 框架已预留，相机流和视频编码待实现 |
| ⏳ **文件导出** | 待开发 | 导出到系统相册、分享功能 |
| ⏳ **录制时长限制** | 待开发 | 支持配置最大录制时长自动停止 |

### 1.3 技术栈

- **框架**: HarmonyOS ArkUI (TypeScript)
- **核心能力**: MediaKit、AudioKit、CameraKit（预留）
- **文件系统**: @ohos.file.fs

---

## 二、项目结构

```
library/
├── src/main/ets/
│   ├── AVRecorderManage.ets    # 核心管理器（单例）
│   ├── constants/
│   │   └── LoggerMode.ets      # 日志模式常量定义
│   ├── model/
│   │   └── AVRecorderModel.ets # 默认配置模型（音频/视频参数）
│   ├── type/
│   │   ├── AVRecorder.type.ets     # 录制状态类型定义
│   │   ├── AVRecorderListener.ets  # 监听器回调接口
│   │   ├── AVRecorderOptions.ets   # 初始化配置选项类型
│   │   └── File.type.ets           # 文件操作相关类型
│   └── utils/
│       ├── FileUtil.ets      # 文件操作工具类
│       ├── Log.ets           # 日志工具类
│       └── RandomUtil.ets    # 随机字符串生成工具
├── src/ohosTest/            # 鸿蒙单元测试
├── src/test/                # 本地单元测试
├── Index.ets                # 库导出入口（所有对外API）
├── BuildProfile.ets         # 构建配置
├── CHANGELOG.md             # 版本变更记录
├── LICENSE                  # 许可证
├── README.md                # 项目说明
├── build-profile.json5      # 构建配置
├── consumer-rules.txt       # 消费者规则
├── hvigorfile.ts            # 构建脚本
├── obfuscation-rules.txt    # 混淆规则
└── oh-package.json5         # 包依赖配置
```

### 2.1 文件职责说明

| 文件路径 | 职责描述 |
|---------|---------|
| `AVRecorderManage.ets` | 核心管理器，单例模式，管理录制全生命周期 |
| `LoggerMode.ets` | 定义日志模式枚举（开发/生产） |
| `AVRecorderModel.ets` | 音视频默认配置参数（编码、比特率、采样率等） |
| `AVRecorder.type.ets` | 录制状态类型和状态枚举定义 |
| `AVRecorderListener.ets` | 状态监听回调接口定义 |
| `AVRecorderOptions.ets` | 初始化配置选项类型定义 |
| `FileUtil.ets` | 文件操作工具（打开、关闭、读写、删除） |
| `Log.ets` | 日志工具类，封装 hilog |
| `RandomUtil.ets` | 随机文件名生成工具 |
| `Index.ets` | 统一导出入口，聚合所有公开API |

---

## 三、快速开始

### 3.1 安装依赖

在项目的 `oh-package.json5` 中添加本地依赖：

```json
{
  "name": "@ohos/your-app",
  "version": "1.0.0",
  "dependencies": {
    "@ryan/record-manage": "v1.0.0"
  }
}
```

然后执行依赖安装：

```bash
ohpm install
```

或者在项目的根目录执行以下命令：

```bash
ohpm install @ryan/record-manage
```

### 3.2 基础使用示例

```typescript
import { 
  AVRecorderManage, 
  AVRecorderOptions, 
  AVRecorderListener,
  LoggerMode 
} from '@ryan/record-manage';

// 1. 设置日志模式（可选，默认开发模式）
AVRecorderManage.setLogMode(LoggerMode.DEVELOPMENT);

// 2. 创建状态监听回调
const listener: AVRecorderListener = {
  prepared: () => {
    console.log('✅ 录制器准备完成，可开始录制');
  },
  running: () => {
    console.log('🎙️ 正在录制...');
  },
  paused: () => {
    console.log('⏸️ 录制已暂停');
  },
  stopped: () => {
    console.log('⏹️ 录制已停止');
  },
  saved: () => {
    const filePath = AVRecorderManage.getSaveFileUrl();
    console.log(`📁 文件已保存: ${filePath}`);
  },
  release: () => {
    console.log('🔌 资源已释放');
  },
  error: (err) => {
    console.error(`❌ 录制错误: ${err.code} - ${err.message}`);
  }
};

// 3. 初始化录制器（音频模式）
const options: AVRecorderOptions = {
  recordType: 'audio',        // 录制类型：audio | video
  listener: listener,         // 状态回调
  recordFileType: 'mp3'       // 输出格式：mp3 | wav | mp4
};

try {
  await AVRecorderManage.initAVRecorderManage(this.context, options);
  
  // 4. 开始录制
  await AVRecorderManage.startedAudioRecord();
  
  // 5. 模拟录制3秒后暂停
  setTimeout(async () => {
    await AVRecorderManage.pausedAudioRecord();
    
    // 6. 1秒后恢复录制
    setTimeout(async () => {
      await AVRecorderManage.resumedAudioRecord();
      
      // 7. 2秒后停止录制
      setTimeout(async () => {
        await AVRecorderManage.stoppedAudioRecord();
        
        // 8. 释放资源
        await AVRecorderManage.release();
      }, 2000);
    }, 1000);
  }, 3000);
  
} catch (error) {
  console.error('初始化失败:', error);
}
```

---

## 四、API 文档

### 4.1 核心方法

| 方法名 | 功能描述 | 参数 | 返回值 |
|-------|---------|------|--------|
| `getInstance()` | **[内部]** 获取单例实例 | 无 | `AVRecorderManage` |
| `initAVRecorderManage(context, options)` | **初始化录制器**，创建系统录音实例并配置参数 | `context`: 应用上下文（必需）<br>`options`: 配置项（必需） | `Promise<void>` |
| `setLogMode(mode)` | 设置日志输出模式 | `mode`: `LoggerMode.DEVELOPMENT` \| `LoggerMode.PRODUCTION` | `void` |
| `getCurrentState()` | 获取当前录制状态 | 无 | `AVRecorderState` |
| `getSaveFileUrl()` | 获取录制文件保存路径（fd://格式） | 无 | `string` |
| `startedAudioRecord()` | **开始音频录制** | 无 | `Promise<void>` |
| `pausedAudioRecord()` | **暂停音频录制** | 无 | `Promise<void>` |
| `resumedAudioRecord()` | **恢复音频录制** | 无 | `Promise<void>` |
| `stoppedAudioRecord()` | **停止音频录制** | 无 | `Promise<void>` |
| `reset()` | **重置录制器**，恢复到IDLE状态 | 无 | `Promise<void>` |
| `release()` | **释放所有资源**（必须调用） | 无 | `Promise<void>` |
| `exportFile()` | **导出录制文件** | 无 | `Promise<void>` |
| `startedVideoRecord()` | **[预留]** 开始视频录制 | 无 | `Promise<void>` |
| `stoppedVideoRecord()` | **[预留]** 停止视频录制 | 无 | `Promise<void>` |

### 4.2 状态约束说明

| 方法 | 允许调用的状态 | 调用后状态 |
|-----|---------------|-----------|
| `initAVRecorderManage()` | 仅 `IDLE` | `PREPARED` |
| `startedAudioRecord()` | `PREPARED`, `SAVED`, `PAUSED`, `STOPPED` | `STARTED` → `RUNNING` |
| `pausedAudioRecord()` | `STARTED`, `RUNNING` | `PAUSED` |
| `resumedAudioRecord()` | `PAUSED` | `RUNNING` |
| `stoppedAudioRecord()` | `STARTED`, `RUNNING`, `PAUSED` | `STOPPED` → `SAVED` |
| `reset()` | 任意状态 | `RESET` → `IDLE` |
| `release()` | 任意状态 | `RELEASED` |

> **注意**: 调用方法时如果当前状态不符合约束，方法会记录警告日志并直接返回，不会抛出异常。

### 4.3 方法详细说明

#### 4.3.1 initAVRecorderManage

**功能**: 初始化录制器，完成系统资源分配和参数配置

**参数详解**:
- `context`: 应用上下文，必须是 `common.Context` 类型，用于获取应用沙箱目录和权限
- `options`: 初始化配置项，详见 [5.1 AVRecorderOptions](#51-avrecorderoptions)

**内部执行流程**:
1. 校验上下文有效性
2. 创建系统 `media.AVRecorder` 实例
3. 注册状态监听回调
4. 初始化音频/视频编码参数
5. 生成随机文件路径并打开文件句柄
6. 调用 `prepare()` 进入 PREPARED 状态

**示例**:
```typescript
await AVRecorderManage.initAVRecorderManage(this.context, {
  recordType: 'audio',
  listener: myListener,
  recordFileType: 'mp3',
  avProfile: {
    audioBitrate: 128000,      // 自定义比特率
    audioChannels: 2,           // 立体声
    audioCodec: media.CodecMimeType.AUDIO_AAC
  }
});
```

#### 4.3.2 startedAudioRecord

**功能**: 开始音频录制

**状态约束**: 必须在 `PREPARED`, `SAVED`, `PAUSED`, `STOPPED` 状态调用

**内部执行流程**:
1. 校验当前状态是否允许启动
2. 调用系统 `avRecorder.start()`
3. 更新状态为 `STARTED` → `RUNNING`
4. 触发 `started` 和 `running` 回调

#### 4.3.3 stoppedAudioRecord

**功能**: 停止音频录制并保存文件

**状态约束**: 必须在 `STARTED`, `RUNNING`, `PAUSED` 状态调用

**内部执行流程**:
1. 校验当前状态是否允许停止
2. 调用系统 `avRecorder.stop()`
3. 更新状态为 `STOPPED` → `SAVED`
4. 安全关闭文件句柄
5. 触发 `stopped` 和 `saved` 回调

#### 4.3.4 release

**功能**: 释放所有资源，防止内存泄漏

**内部执行流程**:
1. 注销所有事件监听器
2. 调用系统 `avRecorder.release()`
3. 释放视频输出流（如存在）
4. 安全关闭文件句柄
5. 更新状态为 `RELEASED`
6. 触发 `release` 回调

> **重要**: 录制完成后**必须**调用此方法释放资源！

---

## 五、类型定义

### 5.1 AVRecorderOptions（初始化配置）

```typescript
interface AVRecorderOptions {
  /** 
   * 录制类型 
   * @description audio: 音频录制（已实现）, video: 视频录制（待开发）
   * @required 必需参数
   */
  recordType: 'audio' | 'video';
  
  /** 
   * 状态监听回调
   * @description 监听录制生命周期的各个状态变化
   */
  listener?: AVRecorderListener;
  
  /** 
   * 音视频编码配置
   * @description 自定义比特率、声道数、采样率、编码格式等
   */
  avProfile?: media.AVRecorderProfile;
  
  /** 
   * 录制器基础配置
   * @description 音源类型、输出路径、文件生成模式等
   */
  avConfig?: media.AVRecorderConfig;
  
  /** 
   * 输出文件格式
   * @description mp3: 音频MP3格式, wav: 无损音频格式, mp4: 视频格式
   * @default audio模式默认'mp3', video模式默认'mp4'
   */
  recordFileType?: 'mp3' | 'wav' | 'mp4';
  
  /** 
   * 自定义保存路径
   * @description 完整的应用沙箱路径，如 `${context.cacheDir}/my_recording.mp3`
   * @default 自动生成随机路径: `${cacheDir}/{random}.{ext}`
   */
  saveFileUrl?: string;
}
```

### 5.2 AVRecorderListener（状态监听）

```typescript
interface AVRecorderListener {
  /** 空闲状态：录制器已创建/已重置，等待准备 */
  idle?: () => void;
  
  /** 准备完成：参数配置完毕，可开始录制 */
  prepared?: () => void;
  
  /** 已启动：录制开始触发，仅执行一次 */
  started?: () => void;
  
  /** 录制中：正在持续采集音频数据 */
  running?: () => void;
  
  /** 已暂停：暂停采集，可通过resume恢复 */
  paused?: () => void;
  
  /** 已停止：完全停止采集，等待保存或重置 */
  stopped?: () => void;
  
  /** 文件已保存：音频数据已写入存储 */
  saved?: () => void;
  
  /** 资源已释放：录制器销毁，不可再使用 */
  release?: () => void;
  
  /** 已重置：恢复到初始空闲状态 */
  reset?: () => void;
  
  /** 已恢复：从暂停状态恢复到录制中 */
  resume?: () => void;
  
  /** 
   * 错误回调：录制过程中发生异常
   * @param error 业务错误对象，包含错误码和错误信息
   */
  error?: (error: BusinessError) => void;
}
```

### 5.3 AVRecorderStateEnum（状态枚举）

| 状态值 | 字符串表示 | 说明 |
|-------|-----------|------|
| `IDLE` | `'idle'` | 空闲状态：录制器已创建但未准备，或已重置 |
| `PREPARED` | `'prepared'` | 准备完成：参数配置完毕，等待启动录制 |
| `STARTED` | `'started'` | 已启动：录制刚刚开始，仅短暂停留 |
| `RUNNING` | `'running'` | 录制中：正在持续采集音频数据 |
| `PAUSED` | `'paused'` | 已暂停：暂停采集，可恢复 |
| `STOPPED` | `'stopped'` | 已停止：完全停止采集，等待保存 |
| `SAVED` | `'saved'` | 已保存：文件已写入存储 |
| `RESET` | `'reset'` | 已重置：恢复到初始状态 |
| `RELEASED` | `'released'` | 已释放：资源已销毁，不可再使用 |
| `ERROR` | `'error'` | 错误状态：发生异常错误 |

### 5.4 RecorderFileType（文件格式类型）

```typescript
type RecorderFileType = "mp3" | "wav" | "mp4";
```

| 格式 | 适用场景 | 特点 |
|-----|---------|------|
| `mp3` | 音频录制 | 压缩率高，文件小，兼容性好 |
| `wav` | 无损音频 | 无压缩，音质好，文件大 |
| `mp4` | 视频录制 | 音视频封装，兼容性强 |

---

## 六、默认配置参数

### 6.1 音频默认配置

```typescript
// 音频编码配置
DEFAULT_AVDIO_PROFILE = {
  audioBitrate: 112000,     // 比特率：112kbps（保证音质清晰）
  audioChannels: 2,         // 声道数：2（立体声）
  audioCodec: AUDIO_AAC,    // 编码格式：AAC（标准编码，兼容性最好）
  audioSampleRate: 48000,   // 采样率：48kHz（高保真音质）
  fileFormat: CFT_MPEG_4A   // 文件格式：M4A（音频专用，体积小）
};

// 音频录制配置
DEFAULT_AVDIO_CONFIG = {
  audioSourceType: AUDIO_SOURCE_TYPE_MIC,  // 音源：麦克风
  profile: DEFAULT_AVDIO_PROFILE,
  url: ''  // 输出路径（动态生成）
};
```

### 6.2 视频默认配置（预留）

```typescript
// 视频编码配置
DEFAULT_VIDEO_PROFILE = {
  fileFormat: CFT_MPEG_4,   // 文件格式：MP4（通用标准）
  videoBitrate: 200000,     // 比特率：200kbps
  videoCodec: VIDEO_AVC,    // 编码格式：H.264（硬件编码支持最好）
  videoFrameWidth: 640,     // 宽度：640px
  videoFrameHeight: 480,    // 高度：480px
  videoFrameRate: 30        // 帧率：30fps
};

// 视频录制配置
DEFAULT_VIDEO_CONFIG = {
  videoSourceType: VIDEO_SOURCE_TYPE_SURFACE_YUV,  // 视频源类型
  audioSourceType: AUDIO_SOURCE_TYPE_MIC,          // 音频源：麦克风
  profile: DEFAULT_VIDEO_PROFILE,
  url: ''  // 输出路径（动态生成）
};
```

### 6.3 通用配置

```typescript
// 通用编码配置（音视频共用）
COMMON_RECORD_PROFILE = {
  fileFormat: CFT_MPEG_4,    // MP4格式
  isHdr: false,              // 关闭HDR
  enableTemporalScale: false,// 关闭时域缩放
  enableBFrame: false        // 关闭B帧编码
};

// 通用录制配置
COMMON_RECORD_CONFIG = {
  fileGenerationMode: AUTO_CREATE_CAMERA_SCENE,  // 相机场景自动创建
  rotation: 0,                                   // 画面不旋转
  location: { latitude: 0, longitude: 0 },       // 不记录位置
  metadata: { videoOrientation: '0' },           // 元数据
  maxDuration: 0,                                // 不限制时长
  profile: COMMON_RECORD_PROFILE,
  url: ""
};
```

---

## 七、状态流转图

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           录制器状态流转                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│    IDLE ──init()──> PREPARED ──start()──> STARTED ──running──> RUNNING      │
│     ^                   │                      │                            │
│     │                   │                      └──pause()──> PAUSED          │
│     │                   │                            │                      │
│     │                   │                            └──resume()──┘          │
│     │                   │                                                 │
│ reset()<── STOPPED <──stop()<───────────────────────────────────────────────│
│     │         │                                                            │
│     │         └──saved()──> SAVED ──start()──┐                             │
│     │                                        │                             │
│     └────────────────────────────────────────┘                             │
│                                                                             │
│     [任何状态] ──release()──> RELEASED (资源销毁，不可再用)                   │
│                                                                             │
│     [任何状态] ──error()──> ERROR (异常状态，需reset或release)                │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

### 状态转换规则

| 转换方向 | 触发条件 | 说明 |
|---------|---------|------|
| IDLE → PREPARED | `initAVRecorderManage()` | 初始化成功 |
| PREPARED → STARTED | `startedAudioRecord()` | 开始录制 |
| STARTED → RUNNING | 系统状态回调 | 录制进入稳定状态 |
| RUNNING / STARTED → PAUSED | `pausedAudioRecord()` | 暂停录制 |
| PAUSED → RUNNING | `resumedAudioRecord()` | 恢复录制 |
| RUNNING / PAUSED / STARTED → STOPPED | `stoppedAudioRecord()` | 停止录制 |
| STOPPED → SAVED | 内部自动转换 | 文件保存完成 |
| SAVED → STARTED | `startedAudioRecord()` | 继续录制（新文件） |
| SAVED / STOPPED → IDLE | `reset()` | 重置到初始状态 |
| 任意 → RELEASED | `release()` | 释放资源 |
| 任意 → ERROR | 发生异常 | 错误状态 |

---

## 八、工具类详解

### 8.1 Log（日志工具）

**功能**: 封装 HarmonyOS `hilog`，提供统一的日志管理能力

**特性**:
- 支持开发/生产模式切换
- 支持日志级别：debug、info、warn、error
- 支持标签(TAG)和参数格式化
- 单例模式，全局唯一实例

**方法说明**:

| 方法 | 功能 | 参数 |
|-----|------|------|
| `debug(message, tag?, ...args)` | 调试日志（仅开发模式） | `message`: 日志内容<br>`tag`: 模块标签<br>`args`: 可变参数 |
| `info(message, tag?, ...args)` | 信息日志（仅开发模式） | 同上 |
| `warn(message, tag?, ...args)` | 警告日志（仅开发模式） | 同上 |
| `error(message, tag?, error?, ...args)` | 错误日志（始终输出） | `error`: 可选错误对象 |
| `setLoggerMode(mode)` | 设置日志模式 | `mode`: LoggerMode |

**使用示例**:
```typescript
import { LogUtils } from '@ryan/record-manage';

LogUtils.debug('初始化参数', 'AVRecorder', { option: 'value' });
LogUtils.info('录制开始', 'AudioManager');
LogUtils.warn('状态异常', 'StateMachine');
LogUtils.error('文件写入失败', 'FileUtil', new Error('磁盘空间不足'));
```

### 8.2 FileUtil（文件工具）

**功能**: 封装 `@ohos.file.fs`，提供便捷的文件操作能力

**方法说明**:

| 方法 | 功能 | 参数 | 返回值 |
|-----|------|------|--------|
| `getFdPath(filePath)` | 添加 fd:// 前缀 | `filePath`: 原始路径 | `string` |
| `open(path, mode)` | 异步打开文件 | `path`: 文件路径<br>`mode`: 打开模式 | `Promise<fs.File>` |
| `openSync(path, mode)` | 同步打开文件 | 同上 | `fs.File` |
| `checkExists(path, mode)` | 检查文件/目录是否存在 | `path`: 路径<br>`mode`: 检查模式 | `Promise<boolean>` |
| `createFolder(path)` | 创建目录 | `path`: 目录路径 | `Promise<CreateStatus>` |
| `createFile(path)` | 创建文件 | `path`: 文件路径 | `Promise<CreateStatus>` |
| `close(file)` | 关闭文件句柄 | `file`: 文件对象 | `Promise<void>` |
| `write(file, buffer, option)` | 异步写入文件 | `file`: 文件对象<br>`buffer`: 数据<br>`option`: 写入选项 | `Promise<number>` |
| `writeSync(file, buffer, option)` | 同步写入文件 | 同上 | `number` |
| `read(file, buffer, option)` | 异步读取文件 | `file`: 文件对象<br>`buffer`: 数据缓冲区<br>`option`: 读取选项 | `Promise<number>` |
| `readSync(file, buffer, option)` | 同步读取文件 | 同上 | `number` |
| `deleteFile(path)` | 删除文件 | `path`: 文件路径 | `Promise<boolean>` |

**CreateStatus 枚举**:

| 值 | 说明 |
|-----|------|
| `Success` | 创建成功 |
| `Exists` | 已存在 |
| `Fail` | 创建失败 |

### 8.3 RandomUtil（随机工具）

**功能**: 生成随机字符串，用于生成唯一文件名

**方法说明**:

| 方法 | 功能 | 参数 | 返回值 |
|-----|------|------|--------|
| `generateRandomFilename(length, ext)` | 生成随机文件名 | `length`: 文件名长度（默认8）<br>`ext`: 文件扩展名 | `string` |

**使用示例**:
```typescript
import { RandomUtil } from '@ryan/record-manage';

// 生成20位随机文件名，带mp3扩展名
const filename = RandomUtil.generateRandomFilename(20, 'mp3');
// 输出示例: 'aB3kLm7pQr9sT1uV2wX4y6.mp3'
```

---

## 九、高级用法

### 9.1 自定义编码参数

```typescript
import { media } from '@kit.MediaKit';

const options: AVRecorderOptions = {
  recordType: 'audio',
  avProfile: {
    audioBitrate: 192000,           // 更高比特率，更好音质
    audioChannels: 2,               // 立体声
    audioCodec: media.CodecMimeType.AUDIO_AAC,
    audioSampleRate: 48000,         // 48kHz采样率
    fileFormat: media.ContainerFormatType.CFT_MPEG_4A
  },
  avConfig: {
    audioSourceType: media.AudioSourceType.AUDIO_SOURCE_TYPE_MIC,
    maxDuration: 600000             // 最大录制时长10分钟
  }
};

await AVRecorderManage.initAVRecorderManage(this.context, options);
```

### 9.2 自定义保存路径

```typescript
const customPath = `${this.context.filesDir}/recordings/my_audio.mp3`;

const options: AVRecorderOptions = {
  recordType: 'audio',
  recordFileType: 'mp3',
  avConfig: {
    url: customPath  // 使用自定义路径
  }
};

await AVRecorderManage.initAVRecorderManage(this.context, options);
```

### 9.3 状态轮询检测

```typescript
// 轮询检测录制状态
const checkRecordingState = async () => {
  const state = AVRecorderManage.getCurrentState();
  
  switch (state) {
    case 'idle':
      console.log('等待初始化');
      break;
    case 'prepared':
      await AVRecorderManage.startedAudioRecord();
      break;
    case 'running':
      console.log('录制中...');
      break;
    case 'saved':
      const path = AVRecorderManage.getSaveFileUrl();
      console.log(`录制完成: ${path}`);
      break;
    default:
      console.log(`当前状态: ${state}`);
  }
};

// 每秒检测一次
setInterval(checkRecordingState, 1000);
```

### 9.4 错误处理最佳实践

```typescript
try {
  await AVRecorderManage.initAVRecorderManage(this.context, options);
  await AVRecorderManage.startedAudioRecord();
  
  // 录制逻辑...
  
} catch (error) {
  console.error('录制异常:', error);
  
  // 错误处理策略
  const state = AVRecorderManage.getCurrentState();
  if (state !== 'released') {
    await AVRecorderManage.release();
  }
  
  // 通知用户
  prompt.showToast({ message: '录制失败，请重试' });
}
```

---

## 十、权限配置

在 `module.json5` 中声明必要权限：

```json
{
  "module": {
    "reqPermissions": [
      {
        "name": "ohos.permission.MICROPHONE",
        "reason": "需要使用麦克风进行录音",
        "usedScene": {
          "abilities": ["YourAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.WRITE_MEDIA",
        "reason": "需要保存录音文件到媒体库",
        "usedScene": {
          "abilities": ["YourAbility"],
          "when": "inuse"
        }
      },
      {
        "name": "ohos.permission.READ_MEDIA",
        "reason": "需要读取录音文件",
        "usedScene": {
          "abilities": ["YourAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}
```

**权限说明**:

| 权限 | 用途 |
|-----|------|
| `ohos.permission.MICROPHONE` | 访问麦克风进行录音 |
| `ohos.permission.WRITE_MEDIA` | 写入媒体文件 |
| `ohos.permission.READ_MEDIA` | 读取媒体文件 |

---

## 十一、注意事项

### 11.1 资源管理

```typescript
// ❌ 错误：忘记释放资源
await AVRecorderManage.initAVRecorderManage(context, options);
await AVRecorderManage.startedAudioRecord();
await AVRecorderManage.stoppedAudioRecord();
// 资源泄漏！

// ✅ 正确：使用完毕后释放资源
await AVRecorderManage.initAVRecorderManage(context, options);
try {
  await AVRecorderManage.startedAudioRecord();
  // 录制...
  await AVRecorderManage.stoppedAudioRecord();
} finally {
  await AVRecorderManage.release();  // 必须调用
}
```

### 11.2 状态校验

```typescript
// 在调用方法前检查状态
const state = AVRecorderManage.getCurrentState();

if (state === 'prepared') {
  await AVRecorderManage.startedAudioRecord();
} else {
  console.warn(`当前状态不允许开始录制: ${state}`);
}
```

### 11.3 文件路径处理

```typescript
// 使用应用沙箱路径，不要使用绝对路径
const validPath = `${this.context.cacheDir}/recording.mp3`;  // ✅
const invalidPath = '/sdcard/recording.mp3';                 // ❌ 无权限
```

### 11.4 异步操作顺序

```typescript
// 异步操作需要按顺序执行
await AVRecorderManage.initAVRecorderManage(context, options);
await AVRecorderManage.startedAudioRecord();  // 必须等初始化完成

// 错误示例：没有等待初始化完成
AVRecorderManage.initAVRecorderManage(context, options);
await AVRecorderManage.startedAudioRecord();  // 可能失败
```

---


## 十二、代码示例汇总

### 完整音频录制示例

```typescript
import { 
  AVRecorderManage, 
  AVRecorderOptions, 
  AVRecorderListener,
  LoggerMode,
  AVRecorderStateEnum 
} from '@ohos/av-recorder';

class RecordingService {
  private isRecording = false;
  
  async startRecording(context: common.Context): Promise<void> {
    if (this.isRecording) return;
    
    const listener: AVRecorderListener = {
      prepared: () => console.log('准备完成'),
      running: () => {
        this.isRecording = true;
        console.log('开始录制');
      },
      paused: () => console.log('已暂停'),
      stopped: () => console.log('已停止'),
      saved: () => {
        const path = AVRecorderManage.getSaveFileUrl();
        console.log(`文件保存路径: ${path}`);
      },
      error: (err) => console.error(`错误: ${err.message}`)
    };
    
    const options: AVRecorderOptions = {
      recordType: 'audio',
      listener: listener,
      recordFileType: 'mp3'
    };
    
    try {
      await AVRecorderManage.initAVRecorderManage(context, options);
      await AVRecorderManage.startedAudioRecord();
    } catch (error) {
      console.error('录制启动失败:', error);
    }
  }
  
  async stopRecording(): Promise<void> {
    if (!this.isRecording) return;
    
    try {
      await AVRecorderManage.stoppedAudioRecord();
      this.isRecording = false;
    } finally {
      await AVRecorderManage.release();
    }
  }
  
  async pauseRecording(): Promise<void> {
    await AVRecorderManage.pausedAudioRecord();
  }
  
  async resumeRecording(): Promise<void> {
    await AVRecorderManage.resumedAudioRecord();
  }
}

// 使用方式
const service = new RecordingService();
await service.startRecording(this.context);
```

---