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