# 调用 API 录制 (/zh-CN/realtime-media/local-server-recording/build/legacy/record-by-api)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="cpp" platform="cpp" />
声网服务端录制 SDK 支持使用命令行或调用 API 的方式实现录制。你可以根据自己的开发习惯选择一种方式。本文介绍如何通过调用 API 实现录制。

## 前提条件 [#前提条件]

开始前请确保你已经完成[集成录制 SDK](/zh-CN/realtime-media/local-server-recording/build/legacy/integrate-sdk)。

## 调用 API 实现录制 [#调用-api-实现录制]

### 创建实例 [#创建实例]

在加入频道进行录制之前，需要调用 `createAgoraRecordingEngine` 方法创建一个录制实例，并将其与应用程序相关联。可根据需要创建多个实例同时录制。在该方法中你需要传入与声网 RTC SDK 相同的 App ID。

```cpp
IRecordingEngineEventHandler *handler = {<prepare>};
IRecordingEngine* engine = createAgoraRecordingEngine(<APPID>, handler);
```

### 开始录制 [#开始录制]

创建实例后，调用 `joinChannel` 方法加入频道开始录制，在该方法中需要填写如下参数：

- `channelKey`：如果待录制的频道使用了 Token，你需要在该参数中传入 Token。详见[校验用户权限](/zh-CN/realtime-media/local-server-recording/build/recording-preparation/generate-token)。
- `channelId`：待录制频道的频道名，必填。
- `uid`：录制使用的用户 ID，32 位无符号整数，取值范围 1 到 (2³² - 1)，需保证唯一性，必填。
- `config`：配置录制参数，选填，如不填则使用默认配置。详见 `RecordingConfig`。

```cpp
RecordingConfig config = {<prepare>};
engine->joinChannel(<channelKey>, <channelId>, <uid>, config);
```

在默认情况下，录制实例加入频道后，监测到频道内有用户即开始录制。

如果你在 `RecordingConfig` 中将 `triggerMode` 设为了 `MANUALLY_MODE`（手动模式），需要调用 `startService` 开始录制，开始录制后可以调用 `stopService` 暂停录制。

```cpp
engine->startService();
engine->stopService();
```

:::info[信息]
`startService` 和 `stopService` 必须在加入频道之后调用。
:::

### 获取录制文件路径 [#获取录制文件路径]

加入频道后可以调用 `getProperties` 方法获取录制文件的存放路径。

当有用户加入频道时触发的 `onUserJoined` 回调中也包含录制文件的存放路径。

```cpp
RecordingEngineProperites ps = engine->getProperties();
```

### 结束录制 [#结束录制]

录制完成后，调用 `leaveChannel` 方法离开频道，停止录制。

```cpp
engine->leaveChannel();
```

:::info[信息]
录制结束后如果需要再次开始录制，必须重新创建实例。
:::

在默认情况下，当频道空闲（无用户）超过 300 秒（在 `RecordingConfig` 中的 `idleLimitSec` 可以设置该时间）后，录制实例也会自动退出频道停止录制。

### 释放资源 [#释放资源]

待录制完成后，你需要调用 `release` 方法销毁录制实例，释放 SDK 使用的资源，释放资源后将无法再次使用和回调 SDK 内的其它方法。如需再次使用本地服务端录制，必须重新创建实例。

```cpp showLineNumbers
engine->release();
```

:::info[信息]
`release` 方法不能在回调线程中调用。
:::

## 相关文档 [#相关文档]

在录制过程中，你还可以参考如下文档：

- 录制完成后，你可能需要使用转码脚本将录制的文件进行合成，详见[使用转码脚本](/zh-CN/realtime-media/local-server-recording/build/legacy/merge-files)。
- 如果想了解如何通过命令行录制，可以参考[使用命令行录制](/zh-CN/realtime-media/local-server-recording/build/legacy/record-by-cmd)。
- 如果录制文件或状态出现异常，你还可以参考[录制文件异常](/zh-CN/reference/faq/quality/record_file_issue)和[录制状态异常](/zh-CN/reference/faq/quality/record_status_error)定位和排查问题。
<_PlatformProcessedMarker close="true" />

<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="cpp" platform="java" />
声网服务端录制 SDK 支持使用命令行或调用 API 的方式实现录制。你可以根据自己的开发习惯选择一种方式。本文介绍如何通过调用 API 实现录制。

## 前提条件 [#前提条件-1]

开始前请确保你已经完成[集成录制 SDK](/zh-CN/realtime-media/local-server-recording/build/legacy/integrate-sdk)，并将以下文件复制到你的项目：

- 编译生成的  `librecording.so` 文件
- SDK 包中的 `AgoraCoreService` 文件（位于 `bin` 文件夹）
- SDK 包中的 Java 文件（位于 `samples/java/src/io/agora/recording` 目录下）
  - `RecordingEventHandler.java`
  - `RecordingSDK.java`
  - `common/Common.java`
  - `common/RecordingConfig.java`
  - `common/RecordingEngineProperties.java`

举例来说，假设项目顶层目录为 `ROOT_DIR`，将  `librecording.so` 文件复制到 `ROOT_DIR/lib` 目录下，将 `AgoraCoreService` 文件复制到 `ROOT_DIR/bin` 目录下，将上述 Java 文件复制到 `ROOT_DIR/src/io/agora/recording` 目录下。

运行 Java 程序时，设置 `-Djava.library.path=ROOT_DIR/lib` 参数来指定动态库的目录地址。此外你需要在开始录制时设置 `RecordingConfig` 中的 `appliteDir` 参数为 `ROOT_DIR/bin`。

## 调用 API 实现录制 [#调用-api-实现录制-1]

### 加入频道并开始录制 [#加入频道并开始录制]

调用 `createChannel` 方法创建并加入频道，随后开始录制。

- `appId`：项目的 App ID，需要和你传入 RTC SDK 中的 App ID 一致。
- `channelKey`：如果待录制的频道使用了 Token，你需要在该参数中传入 Token。详见[校验用户权限](/zh-CN/realtime-media/local-server-recording/build/recording-preparation/generate-token)。
- `name`：待录制频道的频道名，必填。
- `uid`：录制使用的用户 ID，32 位无符号整数，取值范围 1 到 (2³² - 1)，需保证唯一性，必填。
- `config`：配置录制参数，选填，如不填则使用默认配置。详见 `RecordingConfig`。

在默认情况下，录制实例加入频道后，监测到频道内有用户即开始录制。

如果你在 `RecordingConfig` 中将 `triggerMode` 设为了 `MANUALLY_MODE`（手动模式），需要调用 `startService` 开始录制，开始录制后可以调用 `stopService` 暂停录制。

:::info[信息]
`startService` 和 `stopService` 必须在加入频道之后调用。
:::

### 获取录制文件路径 [#获取录制文件路径-1]

加入频道后可以调用 `getProperties` 方法获取录制文件的存放路径。

当有用户加入频道时触发的 `onUserJoined` 回调中也包含录制文件的存放路径。

### 结束录制 [#结束录制-1]

录制完成后，调用 `leaveChannel` 方法离开频道，停止录制。

:::info[信息]
录制结束后如果需要再次开始录制，必须重新创建并加入频道。
:::

在默认情况下，当频道空闲（无用户）超过 300 秒（在 `RecordingConfig` 中的 `idleLimitSec` 可以设置该时间）后，录制实例也会自动退出频道停止录制。

## 相关文档 [#相关文档-1]

在录制过程中，你还可以参考如下文档：

- 录制完成后，你可能需要使用转码脚本将录制的文件进行合成，详见[使用转码脚本](/zh-CN/realtime-media/local-server-recording/build/legacy/merge-files)。
- 如果想了解如何通过命令行录制，可以参考[使用命令行录制](/zh-CN/realtime-media/local-server-recording/build/legacy/record-by-cmd)。
- 如果录制文件或状态出现异常，你还可以参考[录制文件异常](/zh-CN/reference/faq/quality/record_file_issue)和[录制状态异常](/zh-CN/reference/faq/quality/record_status_error)定位和排查问题。
<_PlatformProcessedMarker close="true" />
</_PlatformTabsGroup>