AgoraMediaRtcRecorder 类

用于录制声网 RTC 媒体流。

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

AgoraMediaRtcRecorder

Java

public AgoraMediaRtcRecorder(long handle)

构造一个 AgoraMediaRtcRecorder 录制器实例。

参数

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

initialize[1/2]

Java

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

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

参数

参数	数据类型	描述
service	AgoraService	声网服务实例，调用该方法前必须先初始化。详见 AgoraService。
enableMix	boolean	是否启用合流模式： true：启用合流模式。 false：不启用合流模式。
recordEncodedOnly	boolean	是否仅录制编码视频（仅当 enableMix 为 false 时有效）： true：不解码接收的视频，直接将 H.264 或 H.265 码流写入容器（不支持水印）。 false：将视频解码为 YUV 并重新编码为 H.264 后写入容器（支持水印）。

返回值

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

initialize[2/2]

Java

public int initialize(AgoraService service, boolean enableMix)

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

参数

参数	数据类型	描述
service	AgoraService	声网服务实例。调用该方法前必须先初始化。详见 AgoraService。
enableMix	boolean	录制时是否启用合流模式： true：启用合流模式。 false：不启用合流模式。

返回值

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

joinChannel

Java

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

加入一个声网 RTC 频道。

参数

参数	数据类型	描述
token	String	用于鉴权的 。
channelName	String	要加入的频道名。频道名长度不能超过 64 字节，支持以下字符： 小写英文字母（a-z）。 大写英文字母（A-Z）。 数字（0-9）。 空格。 特殊字符：!、#、$、%、&、(、)、+、-、:、;、<、=、.、>、?、@、[、]、^、_、{、}、|、~、,。
userId	String	本地用户的用户 ID。如果传入 null，系统会自动分配一个用户 ID。

返回值

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

leaveChannel

Java

public int leaveChannel()

离开当前频道。

返回值

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

enableEncryption

Java

public int enableEncryption(boolean enabled, EncryptionConfig config)

启用或禁用内置加密。

建议在加入频道前调用 enableEncryption 启用加密，以满足高安全性场景的需求。频道中的所有用户必须使用相同的加密模式和密钥。当所有用户离开频道时，加密密钥会被自动清除。

参数

参数	数据类型	描述
enabled	boolean	是否启用内置加密： true：启用加密。 false：（默认）不启用加密。
config	EncryptionConfig	加密配置参数。详见 EncryptionConfig。

返回值

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

subscribeAllAudio

Java

public int subscribeAllAudio()

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

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

返回值

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

subscribeAllVideo

Java

public int subscribeAllVideo(VideoSubscriptionOptions options)

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

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

参数

参数	数据类型	描述
options	VideoSubscriptionOptions	视频订阅选项。详见 VideoSubscriptionOptions。

返回值

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

unsubscribeAllAudio

Java

public int unsubscribeAllAudio()

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

该方法会自动停止订阅所有新加入用户的音频，除非你显式调用 subscribeAudio 或 subscribeAllAudio。

返回值

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

unsubscribeAllVideo

Java

public int unsubscribeAllVideo()

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

除非你显式调用 subscribeVideo 或 subscribeAllVideo，否则该方法会自动停止订阅后续加入用户的视频流。

返回值

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

subscribeAudio

Java

public int subscribeAudio(String userId)

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

参数

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

返回值

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

unsubscribeAudio

Java

public int unsubscribeAudio(String userId)

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

参数

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

返回值

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

subscribeVideo

Java

public int subscribeVideo(String userId, VideoSubscriptionOptions options)

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

参数

参数	数据类型	描述
userId	String	要订阅视频的远端用户 ID。
options	VideoSubscriptionOptions	视频订阅选项。详见 VideoSubscriptionOptions。

返回值

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

unsubscribeVideo

Java

public int unsubscribeVideo(String userId)

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

参数

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

返回值

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

setAudioVolumeIndicationParameters

Java

public int setAudioVolumeIndicationParameters(int intervalInMs)

设置 onAudioVolumeIndication 回调的时间间隔。

参数

参数	数据类型	描述
intervalInMs	int	设置两次音量提示之间的时间间隔（单位为毫秒），默认值为 500。 ≤ 10：关闭音量提示。 > 10：设置两次回调之间的时间间隔（单位为毫秒）。

返回值

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

setVideoMixingLayout

Java

public int setVideoMixingLayout(VideoMixingLayout layout)

设置视频合流布局。

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

参数

参数	数据类型	描述
layout	VideoMixingLayout	视频合流布局的配置。详见 VideoMixingLayout。

返回值

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

setRecorderConfig

Java

public int setRecorderConfig(MediaRecorderConfiguration config)

配置录制器实例的设置。

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

参数

参数	数据类型	描述
config	MediaRecorderConfiguration	录制器的配置参数。详见 MediaRecorderConfiguration。

返回值

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

setRecorderConfigByUid

Java

public int setRecorderConfigByUid(MediaRecorderConfiguration config, String userId)

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

参数

参数	数据类型	描述
config	MediaRecorderConfiguration	录制器实例的配置参数。详见 MediaRecorderConfiguration。
userId	String	你想要配置其录制设置的用户 ID。

返回值

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

startRecording

Java

public int startRecording()

启动录制过程。

调用此方法前，请确保已使用 setRecorderConfig 配置录制器实例。

返回值

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

stopRecording

Java

public int stopRecording()

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

返回值

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

startSingleRecordingByUid

Java

public int startSingleRecordingByUid(String userId)

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

参数

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

返回值

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

stopSingleRecordingByUid

Java

public int stopSingleRecordingByUid(String userId)

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

参数

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

返回值

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

registerRecorderEventHandler

Java

public int registerRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)

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

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

参数

参数	数据类型	描述
handler	IAgoraMediaRtcRecorderEventHandler	事件处理器。详见 IAgoraMediaRtcRecorderEventHandler。

返回值

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

unregisterRecorderEventHandler

Java

public int unregisterRecorderEventHandler(IAgoraMediaRtcRecorderEventHandler handler)

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

参数

参数	数据类型	描述
handler	IAgoraMediaRtcRecorderEventHandler	要取消注册的事件处理器。详见 IAgoraMediaRtcRecorderEventHandler。

返回值

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

enableAndUpdateVideoWatermarks

Java

public int enableAndUpdateVideoWatermarks(WatermarkConfig[] watermarkConfigs)

为视频流添加水印。

参数

参数	数据类型	描述
watermarkConfigs	WatermarkConfig[]	水印配置。详见 WatermarkConfig。

返回值

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

disableVideoWatermarks

Java

public int disableVideoWatermarks()

禁用视频流中的水印。

返回值

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

enableAndUpdateVideoWatermarksByUid

Java

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

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

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

参数

参数	数据类型	描述
watermarkConfigs	WatermarkConfig[]	水印配置。详见 WatermarkConfig。
userId	String	你希望添加水印的视频流所属用户的用户 ID。

返回值

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

disableVideoWatermarksByUid

Java

public int disableVideoWatermarksByUid(String userId)

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

参数

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

返回值

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

renewToken

Java

public int renewToken(String token)

为当前会话更新 。

当触发 onError 回调并报告错误码 ERR_TOKEN_EXPIRED (109)，或触发 onTokenPrivilegeWillExpire 或 onTokenPrivilegeDidExpire 回调时，你必须在服务器上生成新的 ，并调用 renewToken 进行更新。否则，SDK 将从声网频道断开连接。

参数

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

返回值

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

enableRecorderVideoFrameCapture

Java

public int enableRecorderVideoFrameCapture(boolean enable, RecorderVideoFrameCaptureConfig config)

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

启用该功能后，视频帧会根据配置的 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 中设置 jpgFileStorePath 和 jpgCaptureIntervalInSec。

参数

参数	数据类型	描述
enable	boolean	是否启用视频帧采集： true：启用视频帧采集。 false：关闭视频帧采集。
config	RecorderVideoFrameCaptureConfig	视频帧采集的配置参数。详见 RecorderVideoFrameCaptureConfig。

返回值

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

release

Java

public int release()

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

返回值

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