# IAgoraMediaRtcRecorder 类 (/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## initialize [#initialize] ```cpp virtual int initialize(base::IAgoraService* agora_service, bool enable_mix = true, bool recordEncodedOnly = false) = 0; ``` 初始化录制器实例。 :::warning[注意] - `recordEncodedOnly` 参数仅在 `enable_mix` 为 `false` 时有效。 - 如果你将 `recordEncodedOnly` 设为 `true`,则无法在录制过程中使用水印功能。 ::: #### 参数 [#参数] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `agora_service` | `base::IAgoraService*` | 声网服务对象,请确保已完成初始化。详见 [`IAgoraService`](/zh-CN/api-reference/local-server-recording/cpp/iagoraservice.cpp)。 | | `enable_mix` | `bool` | [iagoramediartcrecorder-cpp-html-0-2-2 details](#table-slot-iagoramediartcrecorder-cpp-html-0-2-2) | | `recordEncodedOnly` | `bool` | [iagoramediartcrecorder-cpp-html-0-3-2 details](#table-slot-iagoramediartcrecorder-cpp-html-0-3-2) | **iagoramediartcrecorder-cpp-html-0-2-2 details** 录制时是否启用合流模式: - `true`:(默认)启用合流录制。 - `false`:启用单流录制。 **iagoramediartcrecorder-cpp-html-0-3-2 details** 是否仅录制编码后的视频: - `true`:接收到的视频不会被解码,视频数据将以编码格式录制。该模式下仅支持 H264 和 H265。 - `false`:(默认)接收到的视频将被解码并重新编码。 #### 返回值 [#返回值] - 0:方法调用成功。 - < 0:方法调用失败。 ## joinChannel [#joinchannel] ```cpp virtual int joinChannel(const char* token,const char* channelId,const char* userId) = 0; ``` 加入声网 RTC 频道。 #### 参数 [#参数-1] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `token` | `const char*` | 用于鉴权的 App ID 或 Token。 | | `channelId` | `const char*` | [iagoramediartcrecorder-cpp-html-1-2-2 details](#table-slot-iagoramediartcrecorder-cpp-html-1-2-2) | | `userId` | `const char*` | 本地用户的用户 ID。如果未指定该参数或将 `userId` 设置为 `null`,SDK 会自动分配一个用户 ID。 | **iagoramediartcrecorder-cpp-html-1-2-2 details** 频道名。必须为字符串格式,且长度不超过 64 字节。支持的字符包括: - 所有小写英文字母:a 到 z。 - 所有大写英文字母:A 到 Z。 - 所有数字字符:0 到 9。 - 空格字符。 - 标点符号和其他符号,包括:"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","。 #### 返回值 [#返回值-1] - 0:方法调用成功。 - < 0:方法调用失败。 ## leaveChannel [#leavechannel] ```cpp virtual int leaveChannel() = 0; ``` 离开声网 RTC 频道。 #### 返回值 [#返回值-2] - 0:方法调用成功。 - < 0:方法调用失败。 ## enableEncryption [#enableencryption] ```cpp virtual int enableEncryption(bool enabled, const EncryptionConfig& config) = 0; ``` 启用或禁用内置加密功能。 在高安全性场景下,建议你在加入频道前调用该方法启用内置加密功能。 同一频道内的所有用户必须使用相同的加密模式和加密密钥。当所有用户离开频道后,该频道的加密密钥会被自动清除。 #### 参数 [#参数-2] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `enabled` | `bool` | [iagoramediartcrecorder-cpp-html-2-1-2 details](#table-slot-iagoramediartcrecorder-cpp-html-2-1-2) | | `config` | `const EncryptionConfig&` | 内置加密配置。详见 [`EncryptionConfig`](/zh-CN/api-reference/local-server-recording/cpp/struct#encryptionconfig)。 | **iagoramediartcrecorder-cpp-html-2-1-2 details** 是否启用内置加密功能: - `true`:启用内置加密功能。 - `false`:(默认)禁用内置加密功能。 #### 返回值 [#返回值-3] - 0:方法调用成功。 - < 0:方法调用失败。 ## subscribeAllAudio [#subscribeallaudio] ```cpp virtual int subscribeAllAudio() = 0; ``` 订阅并录制频道中所有远端用户的音频。 该方法会订阅并录制频道中所有远端用户的音频,并自动订阅后续加入频道的远端用户的音频。 #### 返回值 [#返回值-4] - 0:方法调用成功。 - < 0:方法调用失败。 ## subscribeAllVideo [#subscribeallvideo] ```cpp virtual int subscribeAllVideo(const agora::rtc::VideoSubscriptionOptions& subscriptionOptions) = 0; ``` 订阅频道中所有远端用户的视频。 该方法会自动订阅频道中所有远端用户的视频,包括之后加入频道的远端用户的视频。 #### 参数 [#参数-3] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `subscriptionOptions` | `const agora::rtc::VideoSubscriptionOptions&` | 视频订阅选项。详见 [`VideoSubscriptionOptions`](/zh-CN/api-reference/local-server-recording/cpp/struct#videosubscriptionoptions)。 | #### 返回值 [#返回值-5] - 0:方法调用成功。 - < 0:方法调用失败。 ## unsubscribeAllAudio [#unsubscribeallaudio] ```cpp virtual int unsubscribeAllAudio() = 0; ``` 停止订阅频道中所有远端用户的音频。 除非你显式调用 [`subscribeAudio`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribeaudio) 或 [`subscribeAllAudio`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribeallaudio),否则该方法会自动停止订阅之后加入频道的任何用户的音频。 #### 返回值 [#返回值-6] - 0:方法调用成功。 - < 0:方法调用失败。 ## unsubscribeAllVideo [#unsubscribeallvideo] ```cpp virtual int unsubscribeAllVideo() = 0; ``` 停止订阅频道中所有远端用户的视频。 调用该方法后,SDK 会停止订阅当前频道中所有远端用户的视频流。除非你显式调用 [`subscribeVideo`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribevideo) 或 [`subscribeAllVideo`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecorder.cpp#subscribeallvideo) 方法,否则该方法会自动停止订阅之后加入频道的任何用户的视频流。 #### 返回值 [#返回值-7] - 0:方法调用成功。 - < 0:方法调用失败。 ## subscribeAudio [#subscribeaudio] ```cpp virtual int subscribeAudio(user_id_t userId) = 0; ``` 订阅并录制频道中指定远端用户的音频。 #### 参数 [#参数-4] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 你想要订阅音频的远端用户的用户 ID。 | #### 返回值 [#返回值-8] - 0:方法调用成功。 - < 0:方法调用失败。 - -2(`ERR_INVALID_ARGUMENT`):用户不存在或 `userId` 无效。 ## unsubscribeAudio [#unsubscribeaudio] ```cpp virtual int unsubscribeAudio(user_id_t userId) = 0; ``` 停止订阅频道中指定远端用户的音频。 #### 参数 [#参数-5] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 要停止订阅音频的远端用户 ID。 | #### 返回值 [#返回值-9] - 0:方法调用成功。 - < 0:方法调用失败。 - -2(`ERR_INVALID_ARGUMENT`):用户不存在或 `userId` 无效。 ## subscribeVideo [#subscribevideo] ```cpp virtual int subscribeVideo(user_id_t userId, const VideoSubscriptionOptions& subscriptionOptions) = 0; ``` 订阅频道中指定远端用户的视频。 #### 参数 [#参数-6] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 你想要订阅的视频所属的远端用户 ID。 | | `subscriptionOptions` | `const VideoSubscriptionOptions&` | 视频订阅选项,例如仅订阅编码后的视频数据,或订阅低码率的视频流。详见 [`VideoSubscriptionOptions`](/zh-CN/api-reference/local-server-recording/cpp/struct#videosubscriptionoptions)。 | #### 返回值 [#返回值-10] - 0:方法调用成功。 - < 0:方法调用失败。 - -2(`ERR_INVALID_ARGUMENT`):用户不存在或 `userId` 无效。 ## unsubscribeVideo [#unsubscribevideo] ```cpp virtual int unsubscribeVideo(user_id_t userId) = 0; ``` 停止订阅频道中指定远端用户的视频。 #### 参数 [#参数-7] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 指定要停止订阅其视频的远端用户的用户 ID。 | #### 返回值 [#返回值-11] - 0:方法调用成功。 - < 0:方法调用失败。 - -2(`ERR_INVALID_ARGUMENT`):用户不存在或 `userId` 无效。 ## setAudioVolumeIndicationParameters [#setaudiovolumeindicationparameters] ```cpp virtual int setAudioVolumeIndicationParameters(int intervalInMS) = 0; ``` 设置 [`onAudioVolumeIndication`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler#onaudiovolumeindication) 回调的时间间隔。 #### 参数 [#参数-8] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `intervalInMS` | `int` | [iagoramediartcrecorder-cpp-html-8-1-2 details](#table-slot-iagoramediartcrecorder-cpp-html-8-1-2) | **iagoramediartcrecorder-cpp-html-8-1-2 details** 设置两次音量回调之间的时间间隔,单位为毫秒(默认值为 500)。 - 小于或等于 10:关闭音量回调。 - 大于 10:设置两次回调之间的时间间隔(毫秒)。 #### 返回值 [#返回值-12] - 0:方法调用成功。 - < 0:方法调用失败。 ## setVideoMixingLayout [#setvideomixinglayout] ```cpp virtual int setVideoMixingLayout(const VideoMixingLayout& layout) = 0; ``` 设置混合视频流的布局。 #### 参数 [#参数-9] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `layout` | `const VideoMixingLayout&` | 混合视频流的布局。详见 [`VideoMixingLayout`](/zh-CN/api-reference/local-server-recording/cpp/struct#videomixinglayout)。 | #### 返回值 [#返回值-13] - 0:方法调用成功。 - < 0:方法调用失败。 ## setRecorderConfig [#setrecorderconfig] ```cpp virtual int setRecorderConfig(const media::MediaRecorderConfiguration& config) = 0; ``` 设置录制器实例配置。 #### 参数 [#参数-10] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `config` | `const media::MediaRecorderConfiguration&` | 录制器实例配置。详见 [`MediaRecorderConfiguration`](/zh-CN/api-reference/local-server-recording/cpp/struct#mediarecorderconfiguration)。 | #### 返回值 [#返回值-14] - 0:方法调用成功。 - < 0:方法调用失败。 ## enableAndUpdateVideoWatermarks [#enableandupdatevideowatermarks] ```cpp virtual int enableAndUpdateVideoWatermarks(WatermarkConfig* watermark_configs, int num) = 0; ``` 为视频流添加水印。 #### 参数 [#参数-11] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `watermark_configs` | `WatermarkConfig*` | 水印配置。详见 [`WatermarkConfig`](/zh-CN/api-reference/local-server-recording/cpp/struct#watermarkconfig)。 | | `num` | `int` | 水印配置的数量。 | #### 返回值 [#返回值-15] - 0:方法调用成功。 - < 0:方法调用失败。 ## disableVideoWatermarks [#disablevideowatermarks] ```cpp virtual int disableVideoWatermarks() = 0; ``` 禁用视频水印。 #### 返回值 [#返回值-16] - 0:方法调用成功。 - < 0:方法调用失败。 ## startRecording [#startrecording] ```cpp virtual int startRecording() = 0; ``` 开始录制。 #### 返回值 [#返回值-17] - 0:方法调用成功。 - < 0:方法调用失败。 ## stopRecording [#stoprecording] ```cpp virtual int stopRecording() = 0; ``` 停止录制。 #### 返回值 [#返回值-18] - 0:方法调用成功。 - < 0:方法调用失败。 ## startSingleRecordingByUid [#startsinglerecordingbyuid] ```cpp virtual int startSingleRecordingByUid(user_id_t userId) = 0; ``` 根据用户 ID 启动录制。 #### 参数 [#参数-12] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 要启动录制的用户 ID。 | #### 返回值 [#返回值-19] - 0:方法调用成功。 - < 0:方法调用失败。 ## stopSingleRecordingByUid [#stopsinglerecordingbyuid] ```cpp virtual int stopSingleRecordingByUid(user_id_t userId) = 0; ``` 通过指定用户 ID 停止录制。 #### 参数 [#参数-13] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 要停止录制的用户 ID。 | #### 返回值 [#返回值-20] - 0:方法调用成功。 - < 0:方法调用失败。 ## setRecorderConfigByUid [#setrecorderconfigbyuid] ```cpp virtual int setRecorderConfigByUid(const media::MediaRecorderConfiguration& config, user_id_t userId) = 0; ``` 根据用户 ID 设置录制配置。 #### 参数 [#参数-14] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `config` | `const media::MediaRecorderConfiguration&` | 录制器实例的配置。详见 [`MediaRecorderConfiguration`](/zh-CN/api-reference/local-server-recording/cpp/struct#mediarecorderconfiguration)。 | | `userId` | `user_id_t` | 要设置录制配置的用户 ID。 | #### 返回值 [#返回值-21] - 0:方法调用成功。 - < 0:方法调用失败。 ## enableAndUpdateVideoWatermarksByUid [#enableandupdatevideowatermarksbyuid] ```cpp virtual int enableAndUpdateVideoWatermarksByUid(WatermarkConfig* watermark_configs, int num, user_id_t userId) = 0; ``` 为指定用户的视频流添加水印。 #### 参数 [#参数-15] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `watermark_configs` | `WatermarkConfig*` | 水印配置数组。详见 [`WatermarkConfig`](/zh-CN/api-reference/local-server-recording/cpp/struct#watermarkconfig)。 | | `num` | `int` | 水印配置的数量。 | | `userId` | `user_id_t` | 你想要添加水印的视频流所属用户的 ID。 | #### 返回值 [#返回值-22] - 0:方法调用成功。 - < 0:方法调用失败。 ## disableVideoWatermarksByUid [#disablevideowatermarksbyuid] ```cpp virtual int disableVideoWatermarksByUid(user_id_t userId) = 0; ``` 根据用户 ID 关闭其视频流的水印。 #### 参数 [#参数-16] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `userId` | `user_id_t` | 要关闭水印的视频流所属用户的 ID。 | #### 返回值 [#返回值-23] - 0:方法调用成功。 - < 0:方法调用失败。 ## registerRecorderEventHandle [#registerrecordereventhandle] ```cpp virtual int registerRecorderEventHandle(IAgoraMediaRtcRecorderEventHandler* handler) = 0; ``` 注册录制事件处理器。 #### 参数 [#参数-17] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `handler` | `IAgoraMediaRtcRecorderEventHandler*` | 录制事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler)。 | #### 返回值 [#返回值-24] - 0:方法调用成功。 - < 0:方法调用失败。 ## unregisterRecorderEventHandle [#unregisterrecordereventhandle] ```cpp virtual int unregisterRecorderEventHandle(IAgoraMediaRtcRecorderEventHandler* handler) = 0; ``` 注销录制事件处理器。 #### 参数 [#参数-18] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `handler` | `IAgoraMediaRtcRecorderEventHandler*` | 录制事件处理器。详见 [`IAgoraMediaRtcRecorderEventHandler`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler)。 | #### 返回值 [#返回值-25] - 0:方法调用成功。 - < 0:方法调用失败。 ## setGlobalLocalAccessPoint [#setgloballocalaccesspoint] ```cpp virtual int setGlobalLocalAccessPoint(const LocalAccessPointConfiguration& config) = 0; ``` 设置本地 AP 模式下的全局本地接入点地址。 请在加入频道前调用该方法设置本地 AP 模式(该模式也会调用本地代理)下的全局本地接入点地址。该方法会影响同一进程中的所有录制器实例,仅需调用一次。 #### 参数 [#参数-19] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `config` | `const LocalAccessPointConfiguration&` | 本地接入点配置。详见 [`LocalAccessPointConfiguration`](/zh-CN/api-reference/local-server-recording/cpp/struct#localaccesspointconfiguration)。 | #### 返回值 [#返回值-26] - 0:方法调用成功。 - < 0:方法调用失败。 ## renewToken [#renewtoken] ```cpp virtual int renewToken(const char* token) = 0; ``` 更新 Token。 Token 在一段时间后会过期。你必须在以下任一情况下从服务器重新生成新的 Token,并调用该方法进行更新,否则 SDK 会断开与频道的连接: - [`onError`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler#onerror) 回调报告错误码 ERR_TOKEN_EXPIRED(109)。 - 触发 [`onTokenPrivilegeWillExpire`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler#ontokenprivilegewillexpire) 回调。 - 触发 [`onTokenPrivilegeDidExpire`](/zh-CN/api-reference/local-server-recording/cpp/iagoramediartcrecordereventhandler#ontokenprivilegedidexpire) 回调。 #### 参数 [#参数-20] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `token` | `const char*` | 指向新 Token 的指针。 | #### 返回值 [#返回值-27] - 0:方法调用成功。 - < 0:方法调用失败。 ## enableRecorderVideoFrameCapture [#enablerecordervideoframecapture] ```cpp virtual int enableRecorderVideoFrameCapture(bool enable, const RecorderVideoFrameCaptureConfig& config) = 0; ``` 启用并配置录制器视频帧采集。 #### 参数 [#参数-21] | 参数 | 数据类型 | 描述 | | --- | --- | --- | | `enable` | `bool` | [iagoramediartcrecorder-cpp-html-21-1-2 details](#table-slot-iagoramediartcrecorder-cpp-html-21-1-2) | | `config` | `const RecorderVideoFrameCaptureConfig&` | 视频帧采集配置,详见 [`RecorderVideoFrameCaptureConfig`](/zh-CN/api-reference/local-server-recording/cpp/struct#recordervideoframecaptureconfig)。 | **iagoramediartcrecorder-cpp-html-21-1-2 details** 是否启用视频帧采集: - `true`:启用。 - `false`:不启用。 #### 返回值 [#返回值-28] - 0:方法调用成功。 - < 0:方法调用失败。