# 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 媒体流。
支持录制频道中的音视频流,提供流混合、加密和选择性订阅等功能。
## AgoraMediaRtcRecorder [#agoramediartcrecorder]
```java
public AgoraMediaRtcRecorder(long handle)
```
构造一个 [`AgoraMediaRtcRecorder`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java) 录制器实例。
#### 参数 [#参数]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handle` | `long` | 录制器实例的原生句柄。 |
## 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) |
**agoramediartcrecorder-java-html-1-2-2 details**
是否启用合流模式:
- `true`:启用合流模式。
- `false`:不启用合流模式。
**agoramediartcrecorder-java-html-1-3-2 details**
是否仅录制编码视频(仅当 `enableMix` 为 `false` 时有效):
- `true`:不解码接收的视频,直接将 H.264 或 H.265 码流写入容器(不支持水印)。
- `false`:将视频解码为 YUV 并重新编码为 H.264 后写入容器(支持水印)。
#### 返回值 [#返回值]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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) |
**agoramediartcrecorder-java-html-2-2-2 details**
录制时是否启用合流模式:
- `true`:启用合流模式。
- `false`:不启用合流模式。
#### 返回值 [#返回值-1]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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。 |
**agoramediartcrecorder-java-html-3-2-2 details**
要加入的频道名。频道名长度不能超过 64 字节,支持以下字符:
- 小写英文字母(a-z)。
- 大写英文字母(A-Z)。
- 数字(0-9)。
- 空格。
- 特殊字符:`!`、`#`、`$`、`%`、`&`、`(`、`)`、`+`、`-`、`:`、`;`、`<`、`=`、`.`、`>`、`?`、`@`、`[`、`]`、`^`、`_`、`{`、`}`、`|`、`~`、`,`。
#### 返回值 [#返回值-2]
- 0:方法调用成功。
- < 0:方法调用失败。
## leaveChannel [#leavechannel]
```java
public int leaveChannel()
```
离开当前频道。
#### 返回值 [#返回值-3]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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)。 |
**agoramediartcrecorder-java-html-4-1-2 details**
是否启用内置加密:
- `true`:启用加密。
- `false`:(默认)不启用加密。
#### 返回值 [#返回值-4]
- 0:方法调用成功。
- < 0:方法调用失败。
## subscribeAllAudio [#subscribeallaudio]
```java
public int subscribeAllAudio()
```
订阅频道中所有远端用户的音频流。
该方法会自动订阅频道中所有远端用户的音频流,包括后续加入频道的新用户。
#### 返回值 [#返回值-5]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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:方法调用失败。
## 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:方法调用失败。
## 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:方法调用失败。
## subscribeAudio [#subscribeaudio]
```java
public int subscribeAudio(String userId)
```
订阅指定远端用户的音频流。
#### 参数 [#参数-6]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要订阅音频的远端用户 ID。 |
#### 返回值 [#返回值-9]
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:`userId` 无效。
## unsubscribeAudio [#unsubscribeaudio]
```java
public int unsubscribeAudio(String userId)
```
停止订阅指定远端用户的音频流。
#### 参数 [#参数-7]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要取消订阅音频的远端用户的 ID。 |
#### 返回值 [#返回值-10]
- 0:方法调用成功。
- -2:`userId` 无效。
- < 0:方法调用失败。
## 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` 无效。
## unsubscribeVideo [#unsubscribevideo]
```java
public int unsubscribeVideo(String userId)
```
停止订阅指定远端用户的视频流。
#### 参数 [#参数-9]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要取消订阅视频流的远端用户的 ID。 |
#### 返回值 [#返回值-12]
- 0:方法调用成功。
- -2:`userId` 无效。
- < 0:方法调用失败。
## 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) |
**agoramediartcrecorder-java-html-10-1-2 details**
设置两次音量提示之间的时间间隔(单位为毫秒),默认值为 500。
- ≤ 10:关闭音量提示。
- > 10:设置两次回调之间的时间间隔(单位为毫秒)。
#### 返回值 [#返回值-13]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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:方法调用失败。
## 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:方法调用失败。
## 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:方法调用失败。
## startRecording [#startrecording]
```java
public int startRecording()
```
启动录制过程。
调用此方法前,请确保已使用 [`setRecorderConfig`](/zh-CN/api-reference/local-server-recording/java/agoramediartcrecorder.java#setrecorderconfig) 配置录制器实例。
#### 返回值 [#返回值-17]
- 0:方法调用成功。
- < 0:方法调用失败。
## stopRecording [#stoprecording]
```java
public int stopRecording()
```
停止所有正在进行的录制并保存录制文件。
#### 返回值 [#返回值-18]
- 0:方法调用成功。
- < 0:方法调用失败。
## startSingleRecordingByUid [#startsinglerecordingbyuid]
```java
public int startSingleRecordingByUid(String userId)
```
启动指定用户的录制流程。
#### 参数 [#参数-14]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要启动录制的用户 ID。 |
#### 返回值 [#返回值-19]
- 0:方法调用成功。
- < 0:方法调用失败。
## stopSingleRecordingByUid [#stopsinglerecordingbyuid]
```java
public int stopSingleRecordingByUid(String userId)
```
停止指定用户的录制进程。
#### 参数 [#参数-15]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要停止录制的用户 ID。 |
#### 返回值 [#返回值-20]
- 0:方法调用成功。
- < 0:方法调用失败。
## registerRecorderEventHandler [#registerrecordereventhandler]
```java
public int registerRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)
```
注册用于录制事件的事件处理器。
该方法用于注册事件处理器,用于接收录制相关的事件回调,例如状态变化、错误信息和录制进度更新。
#### 参数 [#参数-16]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IAgoraMediaRtcRecorderEventHandler` | 事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler)。 |
#### 返回值 [#返回值-21]
- 0:方法调用成功。
- < 0:方法调用失败。
## unregisterRecorderEventHandler [#unregisterrecordereventhandler]
```java
public int unregisterRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)
```
取消注册之前注册的事件处理器。
#### 参数 [#参数-17]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `handler` | `IAgoraMediaRtcRecorderEventHandler` | 要取消注册的事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/java/iagoramediartcrecordereventhandler)。 |
#### 返回值 [#返回值-22]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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:方法调用失败。
## disableVideoWatermarks [#disablevideowatermarks]
```java
public int disableVideoWatermarks()
```
禁用视频流中的水印。
#### 返回值 [#返回值-24]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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:方法调用失败。
## disableVideoWatermarksByUid [#disablevideowatermarksbyuid]
```java
public int disableVideoWatermarksByUid(String userId)
```
通过用户 ID 禁用其视频流上的水印。
#### 参数 [#参数-20]
| 参数 | 数据类型 | 描述 |
| --- | --- | --- |
| `userId` | `String` | 要禁用视频水印的用户 ID。 |
#### 返回值 [#返回值-26]
- 0:方法调用成功。
- < 0:方法调用失败。
## 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:方法调用失败。
## 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)。 |
**agoramediartcrecorder-java-html-22-1-2 details**
是否启用视频帧采集:
- `true`:启用视频帧采集。
- `false`:关闭视频帧采集。
#### 返回值 [#返回值-28]
- 0:方法调用成功。
- < 0:方法调用失败。
## release [#release]
```java
public int release()
```
释放与 `Recorder` 实例关联的原生资源。
#### 返回值 [#返回值-29]
- 0:方法调用成功。
- < 0:方法调用失败。