# AgoraMediaRtcRecorder 类 (/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java)

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

用于录制声网 RTC 媒体流。

支持录制频道中的音视频流，提供流混合、加密和选择性订阅等功能。

<a id="agoramediartcrecorder"></a>
## AgoraMediaRtcRecorder [#agoramediartcrecorder]

```java
public AgoraMediaRtcRecorder(long handle)
```

构造一个 [`AgoraMediaRtcRecorder`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java) 录制器实例。

#### 参数 [#参数]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handle` | `long` | 录制器实例的原生句柄。 |

<a id="initialize[1/2]"></a>
## initialize[1/2] [#initialize12]

```java
public int initialize(AgoraService service, boolean enableMix, boolean recordEncodedOnly)
```

初始化录制器实例，设置服务、是否启用合流模式，以及是否仅录制编码视频。

#### 参数 [#参数-1]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `service` | `AgoraService` | 声网服务实例，调用该方法前必须先初始化。详见 [`AgoraService`](/zh-CN/api-reference/local-server-recording/java/agoraservice.java)。 |
| `enableMix` | `boolean` | [agoramediartcrecorder-java-html-1-2-2 details](#table-slot-agoramediartcrecorder-java-html-1-2-2) |
| `recordEncodedOnly` | `boolean` | [agoramediartcrecorder-java-html-1-3-2 details](#table-slot-agoramediartcrecorder-java-html-1-3-2) |

<a id="table-slot-agoramediartcrecorder-java-html-1-2-2"></a>

**agoramediartcrecorder-java-html-1-2-2 details**

是否启用合流模式：

- `true`：启用合流模式。
- `false`：不启用合流模式。

<a id="table-slot-agoramediartcrecorder-java-html-1-3-2"></a>

**agoramediartcrecorder-java-html-1-3-2 details**

是否仅录制编码视频（仅当 `enableMix` 为 `false` 时有效）：

- `true`：不解码接收的视频，直接将 H.264 或 H.265 码流写入容器（不支持水印）。
- `false`：将视频解码为 YUV 并重新编码为 H.264 后写入容器（支持水印）。

#### 返回值 [#返回值]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="initialize"></a>

<a id="initialize[2/2]"></a>
## initialize[2/2] [#initialize22]

```java
public int initialize(AgoraService service, boolean enableMix)
```

初始化录制器，并设置服务实例和是否启用合流模式。

#### 参数 [#参数-2]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `service` | `AgoraService` | 声网服务实例。调用该方法前必须先初始化。详见 [`AgoraService`](/zh-CN/api-reference/local-server-recording/java/agoraservice.java)。 |
| `enableMix` | `boolean` | [agoramediartcrecorder-java-html-2-2-2 details](#table-slot-agoramediartcrecorder-java-html-2-2-2) |

<a id="table-slot-agoramediartcrecorder-java-html-2-2-2"></a>

**agoramediartcrecorder-java-html-2-2-2 details**

录制时是否启用合流模式：

- `true`：启用合流模式。
- `false`：不启用合流模式。

#### 返回值 [#返回值-1]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="joinchannel"></a>
## joinChannel [#joinchannel]

```java
public int joinChannel(String token, String channelName, String userId)
```

加入一个声网 RTC 频道。

#### 参数 [#参数-3]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `token` | `String` | 用于鉴权的 Token。 |
| `channelName` | `String` | [agoramediartcrecorder-java-html-3-2-2 details](#table-slot-agoramediartcrecorder-java-html-3-2-2) |
| `userId` | `String` | 本地用户的用户 ID。如果传入 `null`，系统会自动分配一个用户 ID。 |

<a id="table-slot-agoramediartcrecorder-java-html-3-2-2"></a>

**agoramediartcrecorder-java-html-3-2-2 details**

要加入的频道名。频道名长度不能超过 64 字节，支持以下字符：

- 小写英文字母（a-z）。
- 大写英文字母（A-Z）。
- 数字（0-9）。
- 空格。
- 特殊字符：`!`、`#`、`$`、`%`、`&`、`(`、`)`、`+`、`-`、`:`、`;`、`<`、`=`、`.`、`>`、`?`、`@`、`[`、`]`、`^`、`_`、`{`、`}`、`|`、`~`、`,`。

#### 返回值 [#返回值-2]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="leavechannel"></a>
## leaveChannel [#leavechannel]

```java
public int leaveChannel()
```

离开当前频道。

#### 返回值 [#返回值-3]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="enableencryption"></a>
## enableEncryption [#enableencryption]

```java
public int enableEncryption(boolean enabled, EncryptionConfig config)
```

启用或禁用内置加密。

建议在加入频道前调用 [`enableEncryption`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#enableencryption) 启用加密，以满足高安全性场景的需求。频道中的所有用户必须使用相同的加密模式和密钥。当所有用户离开频道时，加密密钥会被自动清除。

#### 参数 [#参数-4]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `enabled` | `boolean` | [agoramediartcrecorder-java-html-4-1-2 details](#table-slot-agoramediartcrecorder-java-html-4-1-2) |
| `config` | `EncryptionConfig` | 加密配置参数。详见 [`EncryptionConfig`](/zh-CN/api-reference/local-server-recording/java/struct#encryptionconfig)。 |

<a id="table-slot-agoramediartcrecorder-java-html-4-1-2"></a>

**agoramediartcrecorder-java-html-4-1-2 details**

是否启用内置加密：

- `true`：启用加密。
- `false`：（默认）不启用加密。

#### 返回值 [#返回值-4]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="subscribeallaudio"></a>
## subscribeAllAudio [#subscribeallaudio]

```java
public int subscribeAllAudio()
```

订阅频道中所有远端用户的音频流。

该方法会自动订阅频道中所有远端用户的音频流，包括后续加入频道的新用户。

#### 返回值 [#返回值-5]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="subscribeallvideo"></a>
## subscribeAllVideo [#subscribeallvideo]

```java
public int subscribeAllVideo(VideoSubscriptionOptions options)
```

订阅频道中所有远端用户的视频流。

该方法会自动订阅新加入频道的所有远端用户的视频流。

#### 参数 [#参数-5]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `options` | `VideoSubscriptionOptions` | 视频订阅选项。详见 [`VideoSubscriptionOptions`](/zh-CN/api-reference/local-server-recording/java/struct#videosubscriptionoptions)。 |

#### 返回值 [#返回值-6]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="unsubscribeallaudio"></a>
## unsubscribeAllAudio [#unsubscribeallaudio]

```java
public int unsubscribeAllAudio()
```

停止订阅所有远端用户的音频流。

该方法会自动停止订阅所有新加入用户的音频，除非你显式调用 [`subscribeAudio`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#subscribeaudio) 或 [`subscribeAllAudio`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#subscribeallaudio)。

#### 返回值 [#返回值-7]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="unsubscribeallvideo"></a>
## unsubscribeAllVideo [#unsubscribeallvideo]

```java
public int unsubscribeAllVideo()
```

停止订阅所有远端用户的视频流。

除非你显式调用 [`subscribeVideo`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#subscribevideo) 或 [`subscribeAllVideo`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#subscribeallvideo)，否则该方法会自动停止订阅后续加入用户的视频流。

#### 返回值 [#返回值-8]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="subscribeaudio"></a>
## subscribeAudio [#subscribeaudio]

```java
public int subscribeAudio(String userId)
```

订阅指定远端用户的音频流。

#### 参数 [#参数-6]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要订阅音频的远端用户 ID。 |

#### 返回值 [#返回值-9]

- 0：方法调用成功。
- < 0：方法调用失败。
  - -2：`userId` 无效。

<a id="unsubscribeaudio"></a>
## unsubscribeAudio [#unsubscribeaudio]

```java
public int unsubscribeAudio(String userId)
```

停止订阅指定远端用户的音频流。

#### 参数 [#参数-7]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要取消订阅音频的远端用户的 ID。 |

#### 返回值 [#返回值-10]

- 0：方法调用成功。
- -2：`userId` 无效。
- < 0：方法调用失败。

<a id="subscribevideo"></a>
## subscribeVideo [#subscribevideo]

```java
public int subscribeVideo(String userId, VideoSubscriptionOptions options)
```

订阅指定远端用户的视频流。

#### 参数 [#参数-8]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要订阅视频的远端用户 ID。 |
| `options` | `VideoSubscriptionOptions` | 视频订阅选项。详见 [`VideoSubscriptionOptions`](/zh-CN/api-reference/local-server-recording/java/struct#videosubscriptionoptions)。 |

#### 返回值 [#返回值-11]

- 0：方法调用成功。
- < 0：方法调用失败。
  - -2：`userId` 无效。

<a id="unsubscribevideo"></a>
## unsubscribeVideo [#unsubscribevideo]

```java
public int unsubscribeVideo(String userId)
```

停止订阅指定远端用户的视频流。

#### 参数 [#参数-9]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要取消订阅视频流的远端用户的 ID。 |

#### 返回值 [#返回值-12]

- 0：方法调用成功。
- -2：`userId` 无效。
- < 0：方法调用失败。

<a id="setaudiovolumeindicationparameters"></a>
## setAudioVolumeIndicationParameters [#setaudiovolumeindicationparameters]

```java
public int setAudioVolumeIndicationParameters(int intervalInMs)
```

设置 [`onAudioVolumeIndication`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler#onaudiovolumeindication) 回调的时间间隔。

#### 参数 [#参数-10]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `intervalInMs` | `int` | [agoramediartcrecorder-java-html-10-1-2 details](#table-slot-agoramediartcrecorder-java-html-10-1-2) |

<a id="table-slot-agoramediartcrecorder-java-html-10-1-2"></a>

**agoramediartcrecorder-java-html-10-1-2 details**

设置两次音量提示之间的时间间隔（单位为毫秒），默认值为 500。

- ≤ 10：关闭音量提示。
- > 10：设置两次回调之间的时间间隔（单位为毫秒）。

#### 返回值 [#返回值-13]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="setvideomixinglayout"></a>
## setVideoMixingLayout [#setvideomixinglayout]

```java
public int setVideoMixingLayout(VideoMixingLayout layout)
```

设置视频合流布局。

该方法用于配置不同视频流在合流输出中的布局位置和尺寸。

#### 参数 [#参数-11]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `layout` | `VideoMixingLayout` | 视频合流布局的配置。详见 [`VideoMixingLayout`](/zh-CN/api-reference/local-server-recording/java/struct#videomixinglayout)。 |

#### 返回值 [#返回值-14]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="setrecorderconfig"></a>
## setRecorderConfig [#setrecorderconfig]

```java
public int setRecorderConfig(MediaRecorderConfiguration config)
```

配置录制器实例的设置。

你必须在开始录制之前调用该方法。

#### 参数 [#参数-12]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `config` | `MediaRecorderConfiguration` | 录制器的配置参数。详见 [`MediaRecorderConfiguration`](/zh-CN/api-reference/local-server-recording/java/struct#mediarecorderconfiguration)。 |

#### 返回值 [#返回值-15]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="setrecorderconfigbyuid"></a>
## setRecorderConfigByUid [#setrecorderconfigbyuid]

```java
public int setRecorderConfigByUid(MediaRecorderConfiguration config, String userId)
```

为指定用户设置录制器实例的配置。

#### 参数 [#参数-13]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `config` | `MediaRecorderConfiguration` | 录制器实例的配置参数。详见 [`MediaRecorderConfiguration`](/zh-CN/api-reference/local-server-recording/java/struct#mediarecorderconfiguration)。 |
| `userId` | `String` | 你想要配置其录制设置的用户 ID。 |

#### 返回值 [#返回值-16]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="startrecording"></a>
## startRecording [#startrecording]

```java
public int startRecording()
```

启动录制过程。

调用此方法前，请确保已使用 [`setRecorderConfig`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#setrecorderconfig) 配置录制器实例。

#### 返回值 [#返回值-17]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="stoprecording"></a>
## stopRecording [#stoprecording]

```java
public int stopRecording()
```

停止所有正在进行的录制并保存录制文件。

#### 返回值 [#返回值-18]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="startsinglerecordingbyuid"></a>
## startSingleRecordingByUid [#startsinglerecordingbyuid]

```java
public int startSingleRecordingByUid(String userId)
```

启动指定用户的录制流程。

#### 参数 [#参数-14]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要启动录制的用户 ID。 |

#### 返回值 [#返回值-19]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="stopsinglerecordingbyuid"></a>
## stopSingleRecordingByUid [#stopsinglerecordingbyuid]

```java
public int stopSingleRecordingByUid(String userId)
```

停止指定用户的录制进程。

#### 参数 [#参数-15]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要停止录制的用户 ID。 |

#### 返回值 [#返回值-20]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="registerrecordereventhandler"></a>
## registerRecorderEventHandler [#registerrecordereventhandler]

```java
public int registerRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)
```

注册用于录制事件的事件处理器。

该方法用于注册事件处理器，用于接收录制相关的事件回调，例如状态变化、错误信息和录制进度更新。

#### 参数 [#参数-16]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IAgoraMediaRtcRecorderEventHandler` | 事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler)。 |

#### 返回值 [#返回值-21]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="unregisterrecordereventhandler"></a>
## unregisterRecorderEventHandler [#unregisterrecordereventhandler]

```java
public int unregisterRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)
```

取消注册之前注册的事件处理器。

#### 参数 [#参数-17]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IAgoraMediaRtcRecorderEventHandler` | 要取消注册的事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler)。 |

#### 返回值 [#返回值-22]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="enableandupdatevideowatermarks"></a>
## enableAndUpdateVideoWatermarks [#enableandupdatevideowatermarks]

```java
public int enableAndUpdateVideoWatermarks(WatermarkConfig[] watermarkConfigs)
```

为视频流添加水印。

#### 参数 [#参数-18]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `watermarkConfigs` | `WatermarkConfig[]` | 水印配置。详见 [`WatermarkConfig`](/zh-CN/api-reference/local-server-recording/java/struct#watermarkconfig)。 |

#### 返回值 [#返回值-23]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="disablevideowatermarks"></a>
## disableVideoWatermarks [#disablevideowatermarks]

```java
public int disableVideoWatermarks()
```

禁用视频流中的水印。

#### 返回值 [#返回值-24]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="enableandupdatevideowatermarksbyuid"></a>
## enableAndUpdateVideoWatermarksByUid [#enableandupdatevideowatermarksbyuid]

```java
public int enableAndUpdateVideoWatermarksByUid(WatermarkConfig[] watermarkConfigs, String userId)
```

为指定用户的视频流添加水印。

你可以通过传入的水印配置数组，为指定用户的视频流启用并更新水印。

#### 参数 [#参数-19]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `watermarkConfigs` | `WatermarkConfig[]` | 水印配置。详见 [`WatermarkConfig`](/zh-CN/api-reference/local-server-recording/java/struct#watermarkconfig)。 |
| `userId` | `String` | 你希望添加水印的视频流所属用户的用户 ID。 |

#### 返回值 [#返回值-25]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="disablevideowatermarksbyuid"></a>
## disableVideoWatermarksByUid [#disablevideowatermarksbyuid]

```java
public int disableVideoWatermarksByUid(String userId)
```

通过用户 ID 禁用其视频流上的水印。

#### 参数 [#参数-20]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要禁用视频水印的用户 ID。 |

#### 返回值 [#返回值-26]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="renewtoken"></a>
## renewToken [#renewtoken]

```java
public int renewToken(String token)
```

为当前会话更新 Token。

当触发 [`onError`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler#onerror) 回调并报告错误码 `ERR_TOKEN_EXPIRED (109)`，或触发 [`onTokenPrivilegeWillExpire`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler#ontokenprivilegewillexpire) 或 [`onTokenPrivilegeDidExpire`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler#ontokenprivilegedidexpire) 回调时，你必须在服务器上生成新的 Token，并调用 [`renewToken`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#renewtoken) 进行更新。否则，SDK 将从声网频道断开连接。

#### 参数 [#参数-21]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `token` | `String` | 从服务器生成的新 Token。 |

#### 返回值 [#返回值-27]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="enablerecordervideoframecapture"></a>
## enableRecorderVideoFrameCapture [#enablerecordervideoframecapture]

```java
public int enableRecorderVideoFrameCapture(boolean enable, RecorderVideoFrameCaptureConfig config)
```

启用或关闭录制器实例的视频帧采集功能。

启用该功能后，视频帧会根据配置的 [`VideoFrameCaptureType`](/zh-CN/api-reference/local-server-recording/java/enum#videoframecapturetype) 类型传递给观察者：

- `VIDEO_FORMAT_ENCODED_FRAME_TYPE`
- `VIDEO_FORMAT_YUV_FRAME_TYPE`
- `VIDEO_FORMAT_JPG_FRAME_TYPE`
- `VIDEO_FORMAT_JPG_FILE_TYPE`

当使用 `VIDEO_FORMAT_JPG_FILE_TYPE` 类型时，必须在 [`RecorderVideoFrameCaptureConfig`](/zh-CN/api-reference/local-server-recording/java/struct#recordervideoframecaptureconfig) 中设置 `jpgFileStorePath` 和 `jpgCaptureIntervalInSec`。

#### 参数 [#参数-22]

| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `enable` | `boolean` | [agoramediartcrecorder-java-html-22-1-2 details](#table-slot-agoramediartcrecorder-java-html-22-1-2) |
| `config` | `RecorderVideoFrameCaptureConfig` | 视频帧采集的配置参数。详见 [`RecorderVideoFrameCaptureConfig`](/zh-CN/api-reference/local-server-recording/java/struct#recordervideoframecaptureconfig)。 |

<a id="table-slot-agoramediartcrecorder-java-html-22-1-2"></a>

**agoramediartcrecorder-java-html-22-1-2 details**

是否启用视频帧采集：

- `true`：启用视频帧采集。
- `false`：关闭视频帧采集。

#### 返回值 [#返回值-28]

- 0：方法调用成功。
- < 0：方法调用失败。

<a id="release"></a>
## release [#release]

```java
public int release()
```

释放与 `Recorder` 实例关联的原生资源。

#### 返回值 [#返回值-29]

- 0：方法调用成功。
- < 0：方法调用失败。