# 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:方法调用失败。