# IAudioMixingManager ```cpp class bytertc::IAudioMixingManager ``` > Deprecated since 353. Use [IAudioEffectPlayer](#IAudioEffectPlayer) and [IMediaPlayer](#IMediaPlayer) instead. 混音管理类 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual void | [deprecated] [startAudioMixing](#IAudioMixingManager-startaudiomixing) | | virtual void | [deprecated] [stopAudioMixing](#IAudioMixingManager-stopaudiomixing) | | virtual void | [deprecated] [pauseAudioMixing](#IAudioMixingManager-pauseaudiomixing) | | virtual void | [deprecated] [resumeAudioMixing](#IAudioMixingManager-resumeaudiomixing) | | virtual void | [deprecated] [preloadAudioMixing](#IAudioMixingManager-preloadaudiomixing) | | virtual void | [deprecated] [unloadAudioMixing](#IAudioMixingManager-unloadaudiomixing) | | virtual int | [deprecated] [getAudioMixingDuration](#IAudioMixingManager-getaudiomixingduration) | | virtual int | [deprecated] [getAudioMixingCurrentPosition](#IAudioMixingManager-getaudiomixingcurrentposition) | | virtual void | [deprecated] [setAudioMixingPosition](#IAudioMixingManager-setaudiomixingposition) | | virtual void | [deprecated] [setAudioMixingDualMonoMode](#IAudioMixingManager-setaudiomixingdualmonomode) | | virtual void | [deprecated] [setAudioMixingPitch](#IAudioMixingManager-setaudiomixingpitch) | | virtual int | [deprecated] [setAudioMixingPlaybackSpeed](#IAudioMixingManager-setaudiomixingplaybackspeed) | | virtual void | [deprecated] [setAudioMixingProgressInterval](#IAudioMixingManager-setaudiomixingprogressinterval) | | virtual void | [deprecated] [setAudioMixingLoudness](#IAudioMixingManager-setaudiomixingloudness) | | virtual void | [deprecated] [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) | | virtual void | [deprecated] [disableAudioMixingFrame](#IAudioMixingManager-disableaudiomixingframe) | | virtual int | [deprecated] [pushAudioMixingFrame](#IAudioMixingManager-pushaudiomixingframe) | | virtual int | [deprecated] [getAudioTrackCount](#IAudioMixingManager-getaudiotrackcount) | | virtual void | [deprecated] [selectAudioTrack](#IAudioMixingManager-selectaudiotrack) | ## 函数说明 ### startAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::startAudioMixing( int mix_id, const char* file_path, const AudioMixingConfig &config )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 开始播放音频文件。可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个混音文件，实现混音叠加。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID。用于标识混音，请保证混音 ID 唯一性。
如果使用相同的 ID 重复调用本方法后，前一次混音会停止，后一次混音开始，SDK 会使用 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调通知前一次混音已停止。 | | file_path | const char * | 用于混音文件路径。
支持在线文件的 URL 和本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。
推荐的音频文件采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。
不同平台支持的本地音频文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线音频文件格式:

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

| | config | const AudioMixingConfig & | 混音配置
可以设置混音的播放次数、是否本地播放混音、以及是否将混音发送至远端，详见 [AudioMixingConfig](85519#AudioMixingConfig)。 | **注意** - 如果已经通过 [preloadAudioMixing](#IAudioMixingManager-preloadaudiomixing) 将文件加载至内存，确保此处的 ID 与预加载时设置的 ID 相同。 - 调用本方法播放音频文件后，关于当前的混音状态，会收到回调 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 - 开始播放音频文件后，可以调用 [stopAudioMixing](#IAudioMixingManager-stopaudiomixing) 方法停止播放音频文件。 - 本方法的混音数据来源于外部文件，而 [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) 的混音数据来源于外部缓存且音频格式为 PCM，这两种混音方式可以共存。 ### stopAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::stopAudioMixing(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 停止播放音频文件及混音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **注意** - 调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 方法开始播放音频文件及混音后，可以调用本方法停止播放音频文件及混音。 - 调用本方法停止播放音频文件后，SDK 会向本地回调通知已停止混音，见 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 - 调用本方法停止播放音频文件后，该音乐文件会被自动卸载。 ### pauseAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::pauseAudioMixing(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 暂停播放音频文件及混音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **注意** - 调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 方法开始播放音频文件及混音后，可以通过调用本方法暂停播放音频文件及混音。 - 调用本方法暂停播放音频文件及混音后，可调用 [resumeAudioMixing](#IAudioMixingManager-resumeaudiomixing) 方法恢复播放及混音。 - 调用本方法暂停播放音频文件后，SDK 会向本地回调通知已暂停混音，见 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 ### resumeAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::resumeAudioMixing(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 恢复播放音频文件及混音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **注意** - 调用 [pauseAudioMixing](#IAudioMixingManager-pauseaudiomixing) 方法暂停播放音频文件及混音后，可以通过调用本方法恢复播放及混音。 - 调用本方法恢复播放音频文件及混音后，SDK 会向本地回调通知音乐文件正在播放中，见 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 ### preloadAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::preloadAudioMixing( int mix_id, const char* file_path )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID。用于标识混音，请保证混音 ID 唯一性。
如果使用相同的 ID 重复调用本方法，后一次会覆盖前一次。
如果先调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing)，再使用相同的 ID 调用本方法，会先回调 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 通知上一个混音停止，然后加载后一个混音。
调用本方法预加载 A.mp3 后，如果需要使用相同的 ID 调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 播放 B.mp3，请先调用 [unloadAudioMixing](#IAudioMixingManager-unloadaudiomixing) 卸载 A.mp3。 | | file_path | const char * | 混音文件路径。仅支持本地文件的绝对路径。预加载的文件长度不得超过 20s。
不同平台支持的音频文件格式：

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

| **注意** - 本方法只是预加载指定音频文件，只有调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 方法才开始播放指定音频文件。 - 调用本方法预加载音频文件后，关于当前的混音状态，会收到回调 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 - 调用本方法预加载的指定音频文件可以通过 [unloadAudioMixing](#IAudioMixingManager-unloadaudiomixing) 卸载。 ### unloadAudioMixing ```cpp virtual void bytertc::IAudioMixingManager::unloadAudioMixing(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 卸载指定音乐文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **注意** 不论音乐文件是否播放，调用本方法卸载该文件后，SDK 会回调通知混音已停止，见 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged)。 ### getAudioMixingDuration ```cpp virtual int bytertc::IAudioMixingManager::getAudioMixingDuration(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 获取音频文件时长。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **返回值** - \>0: 成功, 音乐文件时长，单位为毫秒。 - < 0: 失败 **注意** 调用本方法获取音乐文件时长前，需要先调用 [preloadAudioMixing](#IAudioMixingManager-preloadaudiomixing) 或 [startAudioMixing](#IAudioMixingManager-startaudiomixing)。 ### getAudioMixingCurrentPosition ```cpp virtual int bytertc::IAudioMixingManager::getAudioMixingCurrentPosition(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 获取音频文件播放进度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int |
混音 ID | **返回值** - \>0: 成功, 音乐文件播放进度，单位为毫秒。 - < 0: 失败 **注意** 调用本方法获取音乐文件播放进度前，需要先调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音乐文件。 ### setAudioMixingPosition ```cpp virtual void bytertc::IAudioMixingManager::setAudioMixingPosition( int mix_id, int position )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 设置音频文件的起始播放位置 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | position | int | 音频文件起始播放位置，单位为毫秒。
你可以通过 [getAudioMixingDuration](#IAudioMixingManager-getaudiomixingduration) 获取音频文件总时长，position 的值应小于音频文件总时长。 | **注意** 在播放在线文件时，调用此接口可能造成播放延迟的现象。 ### setAudioMixingDualMonoMode ```cpp virtual void bytertc::IAudioMixingManager::setAudioMixingDualMonoMode( int mix_id, AudioMixingDualMonoMode mode )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 设置当前音频文件的声道模式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | mode | AudioMixingDualMonoMode | 声道模式。默认的声道模式和源文件一致，详见 [AudioMixingDualMonoMode](85519#AudioMixingDualMonoMode)。 | **注意** - 调用本方法设置音频文件的声道模式前，需要先调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件。 - 此方法对 [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) 播放的音乐无效。 ### setAudioMixingPitch ```cpp virtual void bytertc::IAudioMixingManager::setAudioMixingPitch( int mix_id, int pitch )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 开启本地播放音乐文件变调功能，多用于 K 歌场景。使用该方法，你可以对本地播放音乐文件的音调进行升调或降调等调整。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | pitch | int | 相对于音乐文件原始音调的升高/降低值，取值范围[-12，12]，默认值为 0，即不做调整。
取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。
超出取值范围则设置失败，并且会触发 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调，提示 [AudioMixingState](85519#AudioMixingState) 状态为 `AUDIO_MIXING_STATE_FAILED` 混音播放失败， [AudioMixingError](85519#AudioMixingError) 错误码为 `AUDIO_MIXING_ERROR_ID_TYPE_INVALID_PITCH` 设置混音文件音调不合法。 | **注意** 本方法需要在调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件后、调用 [stopAudioMixing](#IAudioMixingManager-stopaudiomixing) 停止播放音频文件前使用，否则会触发 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调报错 ### setAudioMixingPlaybackSpeed ```cpp virtual int bytertc::IAudioMixingManager::setAudioMixingPlaybackSpeed( int mix_id, int speed )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer or IAudioEffectPlayer instead 设置混音时音频文件的播放速度 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | speed | int | 播放速度与原始文件速度的比例，单位：%，取值范围为 [50,200]，默认值为 100。
超出取值范围则设置失败，你会收到 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调，提示 [AudioMixingState](85519#AudioMixingState) 状态为 `kAudioMixingStateFailed` 混音播放失败， [AudioMixingError](85519#AudioMixingError) 错误码为 `kAudioMixingErrorInValidPlaybackSpeed` 设置混音文件的播放速度不合法。 | **注意** - 暂不支持对 PCM 音频数据进行变速调整。 - 你需要在调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始混音，并且收到 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调提示 [AudioMixingState](85519#AudioMixingState) 状态为 `kAudioMixingStatePlaying`， [AudioMixingError](85519#AudioMixingError) 错误码为 `kAudioMixingErrorOk` 之后调用该方法。 - 在 [stopAudioMixing](#IAudioMixingManager-stopaudiomixing) 停止混音或 [unloadAudioMixing](#IAudioMixingManager-unloadaudiomixing) 卸载音频文件后调用该 API，会收到状态为 `kAudioMixingStateFailed` 错误码为 `kAudioMixingErrorIdNotFound` 的 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调。 ### setAudioMixingProgressInterval ```cpp virtual void bytertc::IAudioMixingManager::setAudioMixingProgressInterval( int mix_id, int64_t interval )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 设置混音时音频文件播放进度回调的间隔 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID
可以通过多次调用本接口传入不同的 ID 对多个 ID 进行间隔设置。 | | interval | int64_t | 音频文件播放进度回调的时间间隔，单位毫秒。

interval 的值为大于 0 的 10 的倍数，当设置的值不能被 10 整除时，则默认向上取整 10，如设为 52ms 时会默认调整为 60ms。设置完成后 SDK 将会按照设置的时间间隔触发 `onAudioMixingPlayingProgress` 回调。
interval 的值小于等于 0 时，不会触发进度回调。

| **注意** 本方法需要在调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件后、调用 [stopAudioMixing](#IAudioMixingManager-stopaudiomixing) 停止播放音频文件前使用，否则会触发 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 回调报错。若想在音乐文件开始播放前设置播放进度回调间隔，你需调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 在 [AudioMixingConfig](85519#AudioMixingConfig) 中设置时间间隔，开始播放后可以通过此接口更新回调间隔。 ### setAudioMixingLoudness ```cpp virtual void bytertc::IAudioMixingManager::setAudioMixingLoudness( int mix_id, float loudness )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 如果你需要使用 `enableVocalInstrumentBalance` 对混音音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | loudness | float | 原始响度，单位：lufs，取值范围为 [-70.0, 0.0]。
当设置的值小于 -70.0lufs 时，则默认调整为 -70.0lufs，大于 0.0lufs 时，则不对该响度做音均衡处理。默认值为 1.0lufs，即不做处理。 | **注意** 建议在 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件之前调用该接口，以免播放过程中的音量突变导致听感体验下降。 ### enableAudioMixingFrame ```cpp virtual void bytertc::IAudioMixingManager::enableAudioMixingFrame( int mix_id, AudioMixingType type )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 启动 PCM 音频数据混音。要实现多个 PCM 音频数据混音，多次调用本方法，并传入不同的 mix_id。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID，用于标识混音，保证混音 ID 唯一性。
如果使用相同的 ID 重复调用本方法后，前一次混音会停止，后一次混音开始，会收到 [onAudioMixingStateChanged](85517#IRTCVideoEventHandler-onaudiomixingstatechanged) 通知前一次混音已停止。 | | type | AudioMixingType | 混音播放类型
是否本地播放、以及是否发送到远端，详见 [AudioMixingType](85519#AudioMixingType)。 | **注意** - 必须先调用本方法启动 PCM 音频数据混音，随后调用 [pushAudioMixingFrame](#IAudioMixingManager-pushaudiomixingframe) 方法，才会开始混音。 - 如要结束 PCM 音频数据混音，使用 [disableAudioMixingFrame](#IAudioMixingManager-disableaudiomixingframe)。 ### disableAudioMixingFrame ```cpp virtual void bytertc::IAudioMixingManager::disableAudioMixingFrame(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 关闭 PCM 混音 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID。 | ### pushAudioMixingFrame ```cpp virtual int bytertc::IAudioMixingManager::pushAudioMixingFrame( int mix_id, IAudioFrame* audio_frame )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 推送 PCM 音频帧数据用于混音 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID。 | | audio_frame | IAudioFrame * | 音频帧，详见 [IAudioFrame](85519#IAudioFrame)。 | **返回值** - 0: 成功 - < 0: 失败 **注意** - 调用该方法前，须通过 [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) 启动外部音频流混音。 - 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 100 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。要暂停播放，暂停推送即可。 ### getAudioTrackCount ```cpp virtual int bytertc::IAudioMixingManager::getAudioTrackCount(int mix_id)=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 获取当前音频文件的音轨索引 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | **返回值** 方法调用结果 - ≥ 0：成功，返回当前音频文件的音轨索引 - < 0：方法调用失败 **注意** - 调用本方法获取音频文件的音轨前，需要先调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件。 - 此方法对 [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) 播放的音频无效。 ### selectAudioTrack ```cpp virtual void bytertc::IAudioMixingManager::selectAudioTrack( int mix_id, int audio_track_index )=0 ``` > Deprecated since 353.1, will be deleted in 359, use IMediaPlayer instead 指定当前音频文件的播放音轨 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mix_id | int | 混音 ID | | audio_track_index | int | 指定的播放音轨
设置的参数值需要小于或等于 [getAudioTrackCount](#IAudioMixingManager-getaudiotrackcount) 的返回值 | **注意** - 调用本方法设置音频文件的音轨前，需要先调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件。 - 此方法对 [enableAudioMixingFrame](#IAudioMixingManager-enableaudiomixingframe) 播放的音乐无效。 # IRTCVideo ```cpp class bytertc::IRTCVideo ``` 引擎 API ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual int | [muteAudioCapture](#IRTCVideo-muteaudiocapture) | | virtual int | [setCaptureVolume](#IRTCVideo-setcapturevolume) | | virtual int | [setPlaybackVolume](#IRTCVideo-setplaybackvolume) | | virtual int | [startAudioCapture](#IRTCVideo-startaudiocapture) | | virtual int | [stopAudioCapture](#IRTCVideo-stopaudiocapture) | | virtual int | [setAudioProfile](#IRTCVideo-setaudioprofile) | | virtual int | [setAnsMode](#IRTCVideo-setansmode) | | virtual int | [enableAGC](#IRTCVideo-enableagc) | | virtual int | [setAudioSourceType](#IRTCVideo-setaudiosourcetype) | | virtual int | [setAudioRenderType](#IRTCVideo-setaudiorendertype) | | virtual int | [pushExternalAudioFrame](#IRTCVideo-pushexternalaudioframe) | | virtual int | [pullExternalAudioFrame](#IRTCVideo-pullexternalaudioframe) | | virtual int | [startVideoCapture](#IRTCVideo-startvideocapture) | | virtual int | [stopVideoCapture](#IRTCVideo-stopvideocapture) | | virtual int | [setVideoCaptureConfig](#IRTCVideo-setvideocaptureconfig) | | virtual int | [setVideoCaptureRotation](#IRTCVideo-setvideocapturerotation) | | virtual int | [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) | | virtual int | [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig) | | virtual int | [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig-3) | | virtual int | [setScreenVideoEncoderConfig](#IRTCVideo-setscreenvideoencoderconfig) | | virtual int | [disableAlphaChannelVideoEncode](#IRTCVideo-disablealphachannelvideoencode) | | virtual int | [setLocalVideoCanvas](#IRTCVideo-setlocalvideocanvas) | | virtual int | [updateLocalVideoCanvas](#IRTCVideo-updatelocalvideocanvas) | | virtual int | [setRemoteVideoCanvas](#IRTCVideo-setremotevideocanvas) | | virtual int | [pushScreenVideoFrame](#IRTCVideo-pushscreenvideoframe) | | virtual int | [updateScreenCaptureRegion](#IRTCVideo-updatescreencaptureregion) | | virtual int | [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) | | virtual int | [stopScreenVideoCapture](#IRTCVideo-stopscreenvideocapture) | | virtual int | [updateScreenCaptureHighlightConfig](#IRTCVideo-updatescreencapturehighlightconfig) | | virtual int | [updateScreenCaptureMouseCursor](#IRTCVideo-updatescreencapturemousecursor) | | virtual IScreenCaptureSourceList * | [getScreenCaptureSourceList](#IRTCVideo-getscreencapturesourcelist) | | virtual IVideoFrame * | [getThumbnail](#IRTCVideo-getthumbnail) | | virtual IVideoFrame * | [getWindowAppIcon](#IRTCVideo-getwindowappicon) | | virtual int | [setVideoSourceType](#IRTCVideo-setvideosourcetype) | | virtual int | [pushExternalVideoFrame](#IRTCVideo-pushexternalvideoframe) | | virtual IRTCRoom * | [createRTCRoom](#IRTCVideo-creatertcroom) | | virtual int | [setPublishFallbackOption](#IRTCVideo-setpublishfallbackoption) | | virtual int | [setSubscribeFallbackOption](#IRTCVideo-setsubscribefallbackoption) | | virtual int | [setRemoteUserPriority](#IRTCVideo-setremoteuserpriority) | | virtual int | [setBusinessId](#IRTCVideo-setbusinessid) | | virtual int | [setRemoteVideoMirrorType](#IRTCVideo-setremotevideomirrortype) | | virtual int | [setEncryptInfo](#IRTCVideo-setencryptinfo) | | virtual int | [setCustomizeEncryptHandler](#IRTCVideo-setcustomizeencrypthandler) | | virtual int | [enableAudioFrameCallback](#IRTCVideo-enableaudioframecallback) | | virtual int | [disableAudioFrameCallback](#IRTCVideo-disableaudioframecallback) | | virtual int | [registerAudioFrameObserver](#IRTCVideo-registeraudioframeobserver) | | virtual int | [registerAudioProcessor](#IRTCVideo-registeraudioprocessor) | | virtual int | [enableAudioProcessor](#IRTCVideo-enableaudioprocessor) | | virtual int | [disableAudioProcessor](#IRTCVideo-disableaudioprocessor) | | virtual int | [registerLocalVideoProcessor](#IRTCVideo-registerlocalvideoprocessor) | | virtual int | [setVideoDigitalZoomConfig](#IRTCVideo-setvideodigitalzoomconfig) | | virtual int | [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol) | | virtual int | [startVideoDigitalZoomControl](#IRTCVideo-startvideodigitalzoomcontrol) | | virtual int | [stopVideoDigitalZoomControl](#IRTCVideo-stopvideodigitalzoomcontrol) | | virtual int | [sendSEIMessage](#IRTCVideo-sendseimessage-2) | | virtual IVideoDeviceManager * | [getVideoDeviceManager](#IRTCVideo-getvideodevicemanager) | | virtual IAudioDeviceManager * | [getAudioDeviceManager](#IRTCVideo-getaudiodevicemanager) | | virtual int | [startFileRecording](#IRTCVideo-startfilerecording) | | virtual int | [stopFileRecording](#IRTCVideo-stopfilerecording) | | virtual int | [startAudioRecording](#IRTCVideo-startaudiorecording) | | virtual int | [stopAudioRecording](#IRTCVideo-stopaudiorecording) | | virtual int | [enableExternalSoundCard](#IRTCVideo-enableexternalsoundcard) | | virtual int | [setRuntimeParameters](#IRTCVideo-setruntimeparameters) | | virtual int | [feedback](#IRTCVideo-feedback) | | virtual IAudioEffectPlayer * | [getAudioEffectPlayer](#IRTCVideo-getaudioeffectplayer) | | virtual IMediaPlayer * | [getMediaPlayer](#IRTCVideo-getmediaplayer) | | virtual int | [login](#IRTCVideo-login) | | virtual int | [logout](#IRTCVideo-logout) | | virtual int | [updateLoginToken](#IRTCVideo-updatelogintoken) | | virtual int | [setServerParams](#IRTCVideo-setserverparams) | | virtual int | [getPeerOnlineStatus](#IRTCVideo-getpeeronlinestatus) | | virtual int64_t | [sendUserMessageOutsideRoom](#IRTCVideo-sendusermessageoutsideroom) | | virtual int64_t | [sendUserBinaryMessageOutsideRoom](#IRTCVideo-senduserbinarymessageoutsideroom) | | virtual int64_t | [sendServerMessage](#IRTCVideo-sendservermessage) | | virtual int64_t | [sendServerBinaryMessage](#IRTCVideo-sendserverbinarymessage) | | virtual int | [startNetworkDetection](#IRTCVideo-startnetworkdetection) | | virtual int | [stopNetworkDetection](#IRTCVideo-stopnetworkdetection) | | virtual int | [startScreenAudioCapture](#IRTCVideo-startscreenaudiocapture) | | virtual int | [stopScreenAudioCapture](#IRTCVideo-stopscreenaudiocapture) | | virtual int | [setAudioAlignmentProperty](#IRTCVideo-setaudioalignmentproperty) | | virtual int | [startPushPublicStream](#IRTCVideo-startpushpublicstream) | | virtual int | [stopPushPublicStream](#IRTCVideo-stoppushpublicstream) | | virtual int | [updatePublicStreamParam](#IRTCVideo-updatepublicstreamparam) | | virtual int | [enableAudioPropertiesReport](#IRTCVideo-enableaudiopropertiesreport) | | virtual int | [setRemoteAudioPlaybackVolume](#IRTCVideo-setremoteaudioplaybackvolume) | | virtual int | [enableVocalInstrumentBalance](#IRTCVideo-enablevocalinstrumentbalance) | | virtual int | [enablePlaybackDucking](#IRTCVideo-enableplaybackducking) | | virtual int | [registerLocalEncodedVideoFrameObserver](#IRTCVideo-registerlocalencodedvideoframeobserver) | | virtual int | [registerRemoteEncodedVideoFrameObserver](#IRTCVideo-registerremoteencodedvideoframeobserver) | | virtual int | [setExternalVideoEncoderEventHandler](#IRTCVideo-setexternalvideoencodereventhandler) | | virtual int | [pushExternalEncodedVideoFrame](#IRTCVideo-pushexternalencodedvideoframe) | | virtual int | [setVideoDecoderConfig](#IRTCVideo-setvideodecoderconfig) | | virtual int | [requestRemoteVideoKeyFrame](#IRTCVideo-requestremotevideokeyframe) | | virtual int | [sendStreamSyncInfo](#IRTCVideo-sendstreamsyncinfo) | | virtual int | [setLocalVoicePitch](#IRTCVideo-setlocalvoicepitch) | | virtual int | [startPlayPublicStream](#IRTCVideo-startplaypublicstream) | | virtual int | [stopPlayPublicStream](#IRTCVideo-stopplaypublicstream) | | virtual int | [setPublicStreamVideoCanvas](#IRTCVideo-setpublicstreamvideocanvas) | | virtual int | [setPublicStreamVideoSink](#IRTCVideo-setpublicstreamvideosink) | | virtual int | [setPublicStreamAudioPlaybackVolume](#IRTCVideo-setpublicstreamaudioplaybackvolume) | | virtual int | [setVideoWatermark](#IRTCVideo-setvideowatermark) | | virtual int | [clearVideoWatermark](#IRTCVideo-clearvideowatermark) | | virtual int | [setDummyCaptureImagePath](#IRTCVideo-setdummycaptureimagepath) | | virtual int | [startCloudProxy](#IRTCVideo-startcloudproxy) | | virtual int | [stopCloudProxy](#IRTCVideo-stopcloudproxy) | | virtual int | [setLocalProxy](#IRTCVideo-setlocalproxy) | | virtual int | [setLowLightAdjusted](#IRTCVideo-setlowlightadjusted) | | virtual int | [deprecated] [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig-4) | | virtual int | [deprecated] [updateRemoteStreamVideoCanvas](#IRTCVideo-updateremotestreamvideocanvas) | | virtual int | [setLocalVideoSink](#IRTCVideo-setlocalvideosink) | | virtual int | [setRemoteVideoSink](#IRTCVideo-setremotevideosink) | | virtual int | [deprecated] [sendSEIMessage](#IRTCVideo-sendseimessage) | | virtual IAudioMixingManager * | [deprecated] [getAudioMixingManager](#IRTCVideo-getaudiomixingmanager) | | virtual int | [deprecated] [muteAudioPlayback](#IRTCVideo-muteaudioplayback) | ## 函数说明 ### muteAudioCapture ```cpp virtual int bytertc::IRTCVideo::muteAudioCapture( StreamIndex index, bool mute )=0 ``` > Available since 3.58.1 设置是否将采集到的音频信号静音，而不影响改变本端硬件采集状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 流索引，指定调节主流/屏幕流音量，参看 [StreamIndex](70083#streamindex-2)。 | | mute | bool | 是否静音采集信号。

True：是
False：否

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 该方法用于设置是否使用静音数据替换设备采集到的音频数据进行推流，不影响 SDK 音频流的采集发布状态。 - 静音后通过 [setCaptureVolume](#IRTCVideo-setcapturevolume) 调整音量不会取消静音状态，音量状态会保存至取消静音。 - 调用 [startAudioCapture](#IRTCVideo-startaudiocapture) 开启音频采集前后，都可以使用此接口设置采集音量。 ### setCaptureVolume ```cpp virtual int bytertc::IRTCVideo::setCaptureVolume( StreamIndex index, int volume )=0 ``` 调节音频采集音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 流索引，指定调节主流还是调节屏幕流的音量，参看 [StreamIndex](85519#StreamIndex) | | volume | int | 采集的音量值和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。
只改变音频数据的音量信息，不涉及本端硬件的音量调节。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0：静音
100：原始音量
400: 最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 在开启音频采集前后，你都可以使用此接口设定采集音量。 ### setPlaybackVolume ```cpp virtual int bytertc::IRTCVideo::setPlaybackVolume(const int volume)=0 ``` 调节本地播放的所有远端用户音频混音后的音量，混音内容包括远端人声、音乐、音效等。播放音频前或播放音频时，你都可以使用此接口设定播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | const int | 音频播放音量值和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。
只改变音频数据的音量信息，不涉及本端硬件的音量调节。
为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0: 静音
100: 原始音量
400: 最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内，当该方法与 [setRemoteAudioPlaybackVolume](#IRTCVideo-setremoteaudioplaybackvolume) 或 [setRemoteRoomAudioPlaybackVolume](#IRTCRoom-setremoteroomaudioplaybackvolume) 共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 ### startAudioCapture ```cpp virtual int bytertc::IRTCVideo::startAudioCapture()=0 ``` 开启内部音频采集。默认为关闭状态。内部采集是指：使用 RTC SDK 内置的音频采集机制进行音频采集。调用该方法开启后，本地用户会收到 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 的回调。非隐身用户进房后调用该方法，房间中的其他用户会收到 [onUserStartAudioCapture](85517#IRTCVideoEventHandler-onuserstartaudiocapture) 的回调。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 若未取得当前设备的麦克风权限，调用该方法后会触发 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 回调，对应的错误码为 `MediaDeviceError.kMediaDeviceErrorDeviceNoPermission = 1`。 - 调用 [stopAudioCapture](#IRTCVideo-stopaudiocapture) 可以关闭音频采集设备，否则，SDK 只会在销毁引擎的时候自动关闭设备。 - 由于不同硬件设备初始化响应时间不同，频繁调用 [stopAudioCapture](#IRTCVideo-stopaudiocapture) 和本接口闭麦/开麦可能出现短暂无声问题，建议使用 [publishStream](#IRTCRoom-publishstream)/ [unpublishStream](#IRTCRoom-unpublishstream) 实现临时闭麦和重新开麦。 - 创建引擎后，无论是否发布音频数据，你都可以调用该方法开启音频采集，并且调用后方可发布音频。 ### stopAudioCapture ```cpp virtual int bytertc::IRTCVideo::stopAudioCapture()=0 ``` 立即关闭内部音频采集。默认为关闭状态。内部采集是指：使用 RTC SDK 内置的音频采集机制进行音频采集。调用该方法，本地用户会收到 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 的回调。非隐身用户进房后调用该方法后，房间中的其他用户会收到 [onUserStopAudioCapture](85517#IRTCVideoEventHandler-onuserstopaudiocapture) 的回调。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [startAudioCapture](#IRTCVideo-startaudiocapture) 可以开启音频采集设备。 - 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部音频采集才会停止。 ### setAudioProfile ```cpp virtual int bytertc::IRTCVideo::setAudioProfile(AudioProfileType audio_profile)=0 ``` 设置音质档位。当所选的 [RoomProfileType](85519#RoomProfileType) 中的音频参数无法满足你的场景需求时，调用本接口切换的音质档位。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_profile | AudioProfileType | 音质档位，参看 [AudioProfileType](85519#AudioProfileType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法在进房前后均可调用； - 支持通话过程中动态切换音质档位。 ### setAnsMode ```cpp virtual int bytertc::IRTCVideo::setAnsMode(AnsMode ans_mode)=0 ``` > Available since 3.52 支持根据业务场景，设置通话中的音频降噪模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | ans_mode | AnsMode | 降噪模式。具体参见 [AnsMode](85519#AnsMode)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该接口进房前后均可调用，可重复调用，仅最后一次调用生效。 - 降噪算法包含传统降噪和 AI 降噪。传统降噪主要是抑制平稳噪声，比如空调声、风扇声等。而 AI 降噪主要是抑制非平稳噪声，比如键盘敲击声、桌椅碰撞声等。 - 只有以下 [RoomProfileType](85519#RoomProfileType) 场景时，调用本接口可以开启 AI 降噪。其余场景的 AI 降噪不会生效。 - 游戏语音模式：kRoomProfileTypeGame - 高音质游戏模式：kRoomProfileTypeGameHD - 云游戏模式：kRoomProfileTypeCloudGame - 1 vs 1 音视频通话：kRoomProfileTypeChat - 多端同步播放音视频：kRoomProfileTypeLwTogether - 云端会议中的个人设备：kRoomProfileTypeMeeting - 课堂互动模式：kRoomProfileTypeClassroom - 云端会议中的会议室终端：kRoomProfileTypeMeetingRoom ### enableAGC ```cpp virtual int bytertc::IRTCVideo::enableAGC(bool enable)=0 ``` > Available since 3.51 打开/关闭 AGC(Automatic Gain Control) 自动增益控制功能。开启该功能后，SDK 会自动调节麦克风的采集音量，确保音量稳定。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool | 是否打开 AGC 功能:

true: 打开 AGC 功能。
false: 关闭 AGC 功能。

| **返回值** - 0：调用成功。 - -1：调用失败。 **注意** 该方法在进房前后均可调用。如果你需要在进房前使用 AGC 功能，请联系技术支持获得私有参数，传入对应 [RoomProfileType](85519#RoomProfileType)。要想在进房后开启 AGC 功能，你需要把 [RoomProfileType](85519#RoomProfileType) 设置为 `kRoomProfileTypeMeeting` 、`kRoomProfileTypeMeetingRoom` 或 `kRoomProfileTypeClassroom` 。 AGC 功能生效后，不建议再调用 [setAudioCaptureDeviceVolume](#IAudioDeviceManager-setaudiocapturedevicevolume) 来调节设备麦克风的采集音量。 ### setAudioSourceType ```cpp virtual int bytertc::IRTCVideo::setAudioSourceType (AudioSourceType type) = 0 ``` 切换音频采集方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type |AudioSourceType | 音频数据源，详见 [AudioSourceType](85519#AudioSourceType)。
默认使用内部音频采集。音频采集和渲染方式无需对应。 | **返回值** - ≥0：切换成功。 - -1：切换失败。 **注意** - 进房前后调用此方法均有效。 - 如果你调用此方法由内部采集切换至自定义采集，SDK 会自动关闭内部采集。然后，调用 [pushExternalAudioFrame](#IRTCVideo-pushexternalaudioframe) 推送自定义采集的音频数据到 RTC SDK 用于传输。 - 如果你调用此方法由自定义采集切换至内部采集，你必须再调用 [startAudioCapture](#IRTCVideo-startaudiocapture) 手动开启内部采集。 ### setAudioRenderType ```cpp virtual int bytertc::IRTCVideo::setAudioRenderType (AudioRenderType type) = 0 ``` 切换音频渲染方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type |AudioRenderType | 音频输出类型，详见 [AudioRenderType](85519#AudioRenderType)。
默认使用内部音频渲染。音频采集和渲染方式无需对应。 | **返回值** - \>0：切换成功。 - -1：切换失败。 **注意** - 进房前后调用此方法均有效。 - 如果你调用此方法切换至自定义渲染，调用 [pullExternalAudioFrame](#IRTCVideo-pullexternalaudioframe) 获取音频数据。 ### pushExternalAudioFrame ```cpp virtual int bytertc::IRTCVideo::pushExternalAudioFrame(IAudioFrame* audio_frame) = 0 ``` 推送自定义采集的音频数据到 RTC SDK。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_frame | IAudioFrame * | 10 ms 对应的音频数据。详见 [IAudioFrame](85519#IAudioFrame)。

音频采样格式必须为 S16。音频缓冲区内的数据格式必须为 PCM，其容量大小应该为 audioFrame.samples × audioFrame.channel × 2。
必须指定具体的采样率和声道数，不支持设置为自动。

| **返回值** - 0：方法调用成功。 - <0：方法调用失败。 **注意** - 推送自定义采集的音频数据前，必须先调用 [setAudioSourceType](#IRTCVideo-setaudiosourcetype) 开启自定义采集。 - 你必须每 10 ms 推送一次数据。 ### pullExternalAudioFrame ```cpp virtual int bytertc::IRTCVideo::pullExternalAudioFrame(IAudioFrame* audio_frame) = 0 ``` 拉取下行音频数据用于自定义音频渲染。调用该方法后，SDK 会主动拉取待播放的音频数据，包括远端已解码和混音后的音频数据，用于外部播放。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_frame | IAudioFrame * | 获取的 10 ms 内的音频数据。详见 [IAudioFrame](85519#IAudioFrame)。 | **返回值** - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 获取音频数据用于自定义渲染前，必须先调用 [setAudioRenderType](#IRTCVideo-setaudiorendertype) 开启自定义渲染。 - 由于 RTC SDK 的帧长为 10 毫秒，你应当每隔 10 毫秒拉取一次音频数据。确保音频采样点数（sample）x 拉取频率等于 audio_frame 的采样率（sampleRate）。如设置采样率为 48000 时，每 10 毫秒调用本接口拉取数据，每次应拉取 480 个采样点。 - 该函数运行在用户调用线程内，是一个同步函数。 ### startVideoCapture ```cpp virtual int bytertc::IRTCVideo::startVideoCapture()=0 ``` 立即开启内部视频采集。默认为关闭状态。内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。调用该方法后，本地用户会收到 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 的回调。本地用户在非隐身状态下调用该方法后，房间中的其他用户会收到 [onUserStartVideoCapture](85517#IRTCVideoEventHandler-onuserstartvideocapture) 的回调。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [stopVideoCapture](#IRTCVideo-stopvideocapture) 可以停止内部视频采集。否则，只有当销毁引擎实例时，内部视频采集才会停止。 - 创建引擎后，无论是否发布视频数据，你都可以调用该方法开启内部视频采集。只有当（内部或外部）视频采集开始以后视频流才会发布。 - 如果需要从自定义视频采集切换为内部视频采集，你必须先关闭自定义采集，再调用此方法手动开启内部采集。 ### stopVideoCapture ```cpp virtual int bytertc::IRTCVideo::stopVideoCapture()=0 ``` 立即关闭内部视频采集。默认为关闭状态。内部视频采集指：使用 RTC SDK 内置视频采集模块，进行采集。调用该方法后，本地用户会收到 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 的回调。非隐身用户进房后调用该方法，房间中的其他用户会收到 [onUserStopVideoCapture](85517#IRTCVideoEventHandler-onuserstopvideocapture) 的回调。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [startVideoCapture](#IRTCVideo-startvideocapture) 可以开启内部视频采集。 - 如果不调用本方法停止内部视频采集，则只有当销毁引擎实例时，内部视频采集才会停止。 ### setVideoCaptureConfig ```cpp virtual int bytertc::IRTCVideo::setVideoCaptureConfig(const VideoCaptureConfig &video_capture_config)=0 ``` 设置 RTC SDK 内部采集时的视频采集参数。如果你的项目使用了 SDK 内部采集模块，可以通过本接口指定视频采集参数，包括模式、分辨率、帧率。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | video_capture_config | const VideoCaptureConfig & | 视频采集参数。参看: [VideoCaptureConfig](85519#VideoCaptureConfig)。 | **返回值** - 0: 成功。 - < 0: 失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 本接口在引擎创建后可调用，调用后立即生效。建议在调用 [startVideoCapture](#IRTCVideo-startvideocapture) 前调用本接口。 - 建议同一设备上的不同引擎使用相同的视频采集参数。 - 如果调用本接口前使用内部模块开始视频采集，采集参数默认为 Auto 模式。 ### setVideoCaptureRotation ```cpp virtual int bytertc::IRTCVideo::setVideoCaptureRotation(VideoRotation rotation)=0 ``` 设置本端采集的视频帧的旋转角度。当摄像头倒置或者倾斜安装时，可调用本接口进行调整。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | rotation | VideoRotation | 相机朝向角度，默认为 `VIDEO_ROTATION_0(0)`，无旋转角度。详见 [VideoRotation](85519#VideoRotation)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用本接口也将对自定义采集视频画面生效，在原有的旋转角度基础上叠加本次设置。 ### enableSimulcastMode ```cpp virtual int bytertc::IRTCVideo::enableSimulcastMode(bool enabled)=0 ``` 该方法设置视频流发布端是否开启发布多路编码参数不同的视频流的模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enabled | bool | 是否开启推送多路视频流模式：

true：开启
false：关闭（默认）

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 你应在进房前或进房后但未发布流时，调用此方法。 - 开启推送多路流后，不能动态关闭，也不能更新多路流的路数和编码参数。 - 开启推送多路视频流模式后，你可以在发布流前调用 [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig-1) 为多路视频流分别设置编码参数。 - 该功能关闭时，或该功能开启但未设置多路流参数时，默认只发一路视频流，该流的编码参数为：分辨率 640px × 360px，帧率 15fps。 ### setVideoEncoderConfig ```cpp virtual int bytertc::IRTCVideo::setVideoEncoderConfig(const VideoEncoderConfig &max_solution)=0 ``` 视频发布端设置期望发布的最大分辨率视频流参数，包括分辨率、帧率、码率、网络不佳时的回退策略等。该接口支持设置一路视频流参数，设置多路参数请使用重载 API：[setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig-2)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | max_solution | const VideoEncoderConfig & | 期望发布的最大分辨率视频流参数。参看 [VideoEncoderConfig](85519#VideoEncoderConfig)。 | **返回值** 方法调用结果： - 0：成功。 - !0：失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 你可以同时使用 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 方法来发布多路分辨率不同的流。具体而言，若期望发布多路不同分辨率的流，你需要在发布流之前调用本方法以及 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 方法开启多路流模式，SDK 会根据订阅端的设置智能调整发布的流数（最多发布 4 条）以及各路流的参数。其中，调用本方法设置的分辨率为各路流中的最大分辨率。具体规则参看[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 - 调用该方法前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。 - 使用自定义采集时，必须调用该方法设置编码参数，以保证远端收到画面的完整性。 - 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 [setScreenVideoEncoderConfig](#IRTCVideo-setscreenvideoencoderconfig)（Linux 不适用）。 ### setVideoEncoderConfig ```cpp virtual int bytertc::IRTCVideo::setVideoEncoderConfig( const VideoEncoderConfig* channel_solutions, int solution_num )=0 ``` 视频发布端设置推送多路流时各路流的参数，包括分辨率、帧率、码率、网络不佳时的回退策略等。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | channel_solutions | const VideoEncoderConfig * | 要推送的多路视频流的参数。注意，所设置的分辨率是各路流的最大分辨率。参看 [VideoEncoderConfig](85519#VideoEncoderConfig)。 | | solution_num | int | 视频参数数组长度，最多支持设置 3 路参数，超过 3 路时默认取前 3 路的值。当设置了多路参数时，分辨率和帧率必须是从大到小排列。| **返回值** 方法调用结果： - 0：成功。 - !0：失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 该方法设置的多路参数是否均生效，取决于是否同时调用了 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 开启发布多路参数不同的视频流模式。若未开启推送多路流模式，但调用本方法设置了多个分辨率，SDK 则默认发布设置的第一条流，多个分辨率的设置会在开启推送多路流模式之后生效。 - 若期望推送多路不同分辨率的流，你需要在发布流之前调用本方法以及 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 方法。 - 开启推送多路流后，不能动态关闭，也不能更新多路流的路数和编码参数。 - 调用该方法设置多路视频流参数前，SDK 默认仅发布一条分辨率为 640px × 360px，帧率为 15fps 的视频流。 - 调用该方法设置分辨率不同的多条流后，SDK 会根据订阅端设置的期望订阅参数自动匹配发送的流，具体规则参看[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 - 该方法适用于摄像头采集的视频流，设置屏幕共享视频流参数参看 [setScreenVideoEncoderConfig](#IRTCVideo-setscreenvideoencoderconfig)（Linux 不适用）。 ### setScreenVideoEncoderConfig ```cpp virtual int bytertc::IRTCVideo::setScreenVideoEncoderConfig(const ScreenVideoEncoderConfig &screen_solution)=0 ``` 为发布的屏幕共享视频流设置期望的编码参数，包括分辨率、帧率、码率、网络不佳时的回退策略等。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | screen_solution | const ScreenVideoEncoderConfig & | 屏幕共享视频流参数。参看 [ScreenVideoEncoderConfig](85519#ScreenVideoEncoderConfig)。 | **返回值** - 0：成功。 - !0：失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** 建议在采集视频前设置编码参数。若采集前未设置编码参数，则使用默认编码参数: 分辨率 1920px × 1080px，帧率 15fps。 ### disableAlphaChannelVideoEncode ```cpp virtual int bytertc::IRTCVideo::disableAlphaChannelVideoEncode(StreamIndex streamIndex)=0 ``` > Available since 3.58 关闭外部采集视频帧的 Alpha 通道编码功能。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | streamIndex | StreamIndex | 需关闭该功能的视频流类型，当前仅支持设置为 StreamIndex.kStreamIndexMain 即主流。 | **返回值** 方法调用结果： - 0：成功； - !0：失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** 该接口须在停止发布视频流之后调用。 ### setLocalVideoCanvas ```cpp virtual int bytertc::IRTCVideo::setLocalVideoCanvas( StreamIndex index, const VideoCanvas &canvas )=0 ``` 设置本地视频渲染时使用的视图，并设置渲染模式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 视频流属性, 参看 [StreamIndex](85519#StreamIndex) | | canvas | const VideoCanvas & | 视图信息和渲染模式，参看： [VideoCanvas](85519#VideoCanvas)。其中 [render_rotation](85519#VideoCanvas-render_rotation) 仅对远端视频有效，对本接口不生效。 | **返回值** - 0：成功。 - -2: 参数错误。 - -12: 本方法不支持在 Audio SDK 中使用。 **注意** - 你应在加入房间前，绑定本地视图。退出房间后，此设置仍然有效。 - 如果需要解除绑定，你可以调用本方法传入空视图。 ### updateLocalVideoCanvas ```cpp virtual int bytertc::IRTCVideo::updateLocalVideoCanvas( StreamIndex index, const enum RenderMode render_mode, const uint32_t background_color )=0 ``` 修改本地视频渲染模式和背景色。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 视频流属性, 参看 [StreamIndex](85519#StreamIndex) | | render_mode | const enum RenderMode | 渲染模式，参看 [RenderMode](85519#RenderMode) | | background_color | const uint32_t | 背景颜色，参看 [VideoCanvas](85519#VideoCanvas).background_color | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** 你可以在本地视频渲染过程中，调用此接口。调用结果会实时生效。 ### setRemoteVideoCanvas ```cpp virtual int bytertc::IRTCVideo::setRemoteVideoCanvas( RemoteStreamKey stream_key, const VideoCanvas &canvas )=0 ``` 设置渲染指定视频流 `stream_key` 时，使用的视图和渲染模式。如果需要解除某个用户的绑定视图，你可以把 `canvas` 设置为空。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_key | RemoteStreamKey | 参看 [RemoteStreamKey](85519#RemoteStreamKey) | | canvas | const VideoCanvas & | 视图信息和渲染模式，参看： [VideoCanvas](85519#VideoCanvas) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 本地用户离开房间时，会解除调用此 API 建立的绑定关系；远端用户离开房间则不会影响。 ### pushScreenVideoFrame ```cpp virtual int bytertc::IRTCVideo::pushScreenVideoFrame(IVideoFrame* frame)=0 ``` 推送屏幕视频帧 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | frame | IVideoFrame * | 设置屏幕视频帧，详见： [IVideoFrame](85519#IVideoFrame)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 支持格式：I420, NV12, RGBA, BGRA, ARGB。不支持 RGB 24。 - 该函数运行在用户调用线程内，即将销毁 IRTCVideo 实例前，请停止调用该函数推送屏幕共享数据 ### updateScreenCaptureRegion ```cpp virtual int bytertc::IRTCVideo::updateScreenCaptureRegion(const Rectangle ®ion_rect)=0 ``` 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新采集区域。仅用于采集源为显示器屏幕时。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | region_rect | const Rectangle & | 采集区域。参见 [Rectangle](85519#Rectangle)
此参数描述了调用此接口后的采集区域，和 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 中 `source_info` 设定区域的相对关系。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用此接口前，必须已通过调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 开启了内部屏幕流采集。 ### startScreenVideoCapture ```cpp virtual int bytertc::IRTCVideo::startScreenVideoCapture( const ScreenCaptureSourceInfo &source_info, const ScreenCaptureParameters &capture_params )=0 ``` 采集屏幕视频流，用于共享。屏幕视频流包括：屏幕上显示的内容，应用窗口中显示的内容，或虚拟屏幕中显示的内容。其中，虚拟屏幕中显示的内容仅在 Windows 平台上支持。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | source_info | const ScreenCaptureSourceInfo & | 待共享的屏幕源，参看 [ScreenCaptureSourceInfo](85519#ScreenCaptureSourceInfo)。
你可以调用 [getScreenCaptureSourceList](#IRTCVideo-getscreencapturesourcelist) 获得所有可以共享的屏幕源。 | | capture_params | const ScreenCaptureParameters & | 共享参数。参看 [ScreenCaptureParameters](85519#ScreenCaptureParameters)。 | **返回值** - 0: 成功 - -1: 失败 **注意** - 调用本接口时，采集模式应为内部模式。在外部采集模式下调用无效，并将触发 [onVideoDeviceWarning](85517#IRTCVideoEventHandler-onvideodevicewarning) 回调。 - 调用此方法仅开启屏幕流视频采集，不会发布采集到的视频。发布屏幕流视频需要调用 [publishScreen](#IRTCRoom-publishscreen)。 - 调用 [stopScreenVideoCapture](#IRTCVideo-stopscreenvideocapture) 关闭屏幕视频源采集。 - 本地用户通过 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 的回调获取屏幕采集状态，包括开始、暂停、恢复、错误等。 - 调用成功后，本端会收到 [onFirstLocalVideoFrameCaptured](85517#IRTCVideoEventHandler-onfirstlocalvideoframecaptured) 回调。 - 调用此接口前，你可以调用 [setScreenVideoEncoderConfig](#IRTCVideo-setscreenvideoencoderconfig) 设置屏幕视频流的采集帧率和编码分辨率。 - 在收到 [onFirstLocalVideoFrameCaptured](85517#IRTCVideoEventHandler-onfirstlocalvideoframecaptured) 回调后通过调用 [setLocalVideoCanvas](#IRTCVideo-setlocalvideocanvas) 或 [setLocalVideoSink](#IRTCVideo-setlocalvideosink) 函数设置本地屏幕共享视图。 - 可以调用 [setLocalVideoSink](#IRTCVideo-setlocalvideosink) 将本地视频流与自定义渲染器绑定，通过回调 [onFrame](85519#IVideoSink-onframe) 获取采集成功的本地视频帧。 ### stopScreenVideoCapture ```cpp virtual int bytertc::IRTCVideo::stopScreenVideoCapture()=0 ``` 停止屏幕视频流采集。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本接口时，采集模式应为内部模式。在外部采集模式下调用无效，并将触发 [onVideoDeviceWarning](85517#IRTCVideoEventHandler-onvideodevicewarning) 回调。 - 要开启屏幕视频流采集，调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture)。 - 调用后，本地用户会收到 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 的回调。 - 调用此接口不影响屏幕视频流发布。 ### updateScreenCaptureHighlightConfig ```cpp virtual int bytertc::IRTCVideo::updateScreenCaptureHighlightConfig(const HighlightConfig &highlight_config)=0 ``` 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新边框高亮设置。默认展示表框。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | highlight_config | const HighlightConfig & | 边框高亮设置。参见 [HighlightConfig](85519#HighlightConfig) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用此接口前，必须已通过调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 开启了内部屏幕流采集。 - 对 Linux 系统，采用 X11 协议时可用；采用 Wayland 协议时不可用。 ### updateScreenCaptureMouseCursor ```cpp virtual int bytertc::IRTCVideo::updateScreenCaptureMouseCursor(MouseCursorCaptureState capture_mouse_cursor)=0 ``` 通过 RTC SDK 提供的采集模块采集屏幕视频流时，更新对鼠标的处理设置。默认采集鼠标。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | capture_mouse_cursor | MouseCursorCaptureState | 参看 [MouseCursorCaptureState](85519#MouseCursorCaptureState) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用此接口前，必须已通过调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 开启了内部屏幕流采集。 ### getScreenCaptureSourceList ```cpp virtual IScreenCaptureSourceList * bytertc::IRTCVideo::getScreenCaptureSourceList()=0 ``` 获取共享对象列表。 **返回值** 共享对象列表，包括应用窗口和屏幕。详见 [IScreenCaptureSourceList](#IScreenCaptureSourceList)。用户选择后，可调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 进行共享。 **注意** - 对 Linux 系统，采用 X11 协议时可用；采用 Wayland 协议时不可用。采用 Wayland 协议，调用 [startScreenVideoCapture](#IRTCVideo-startscreenvideocapture) 时，系统会通过弹窗供用户选择共享对象。 - 使用完之后需要调用 [release](#IScreenCaptureSourceList-release) 接口释放。 ### getThumbnail ```cpp virtual IVideoFrame * bytertc::IRTCVideo::getThumbnail( ScreenCaptureSourceType type, view_t source_id, int max_width, int max_height )=0 ``` 获取共享对象缩略图 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | ScreenCaptureSourceType | 屏幕采集对象的类型。详见 [ScreenCaptureSourceType](85519#ScreenCaptureSourceType)。 | | source_id | view_t | 屏幕共享对象的 ID，可通过 [getScreenCaptureSourceList](#IRTCVideo-getscreencapturesourcelist) 枚举共享对象列表中获取。详见 [view_t](#view_t)。 | | max_width | int | 最大宽度。保持采集对象本身的宽高比不变，将缩略图缩放到指定范围内的最大宽高。如果给出的尺寸与共享对象比例不同，得到的缩略图会有黑边。 | | max_height | int | 最大高度。参见 max_width 的说明。 | **返回值** 共享对象缩略图，详见 [IVideoFrame](85519#IVideoFrame)。 **注意** 对 Linux 系统，采用 X11 协议时可用；采用 Wayland 协议时不可用。 ### getWindowAppIcon ```cpp virtual IVideoFrame * bytertc::IRTCVideo::getWindowAppIcon( view_t source_id, int max_width=100, int max_height=100 )=0 ``` 获取应用窗体所属应用的图标。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | source_id | view_t | 屏幕共享对象的 ID，可通过 [getScreenCaptureSourceList](#IRTCVideo-getscreencapturesourcelist) 枚举共享对象列表中获取。详见 [view_t](#view_t)。 | | max_width | int | 最大宽度。返回的图标将是宽高相等的，输入宽高不等时，取二者较小值。宽高范围为 [32,256]，超出该范围将返回 nullptr，默认输出 100 x 100 的图像。 | | max_height | int | 最大高度。参见 max_width 的说明。 | **返回值** 详见 [IVideoFrame](85519#IVideoFrame)。当屏幕共享对象为应用窗体，且有图标时有效，否则返回 nullptr。 **注意** 对 Linux 系统，采用 X11 协议时可用；采用 Wayland 协议时不可用。 ### setVideoSourceType ```cpp virtual int bytertc::IRTCVideo::setVideoSourceType( StreamIndex stream_index, VideoSourceType type )=0 ``` 设置向 SDK 输入的视频源，包括屏幕流默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_index | StreamIndex | 视频流的属性，参看 [StreamIndex](85519#StreamIndex) | | type | VideoSourceType | 视频输入源类型，参看 [VideoSourceType](85519#VideoSourceType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法进房前后均可调用。 - 当你已调用 [startVideoCapture](#IRTCVideo-startvideocapture) 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。 - 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 [startVideoCapture](#IRTCVideo-startvideocapture) 手动开启内部采集。 - 当你需要向 SDK 推送自定义编码后的视频帧，你需调用该方法将视频源切换至自定义编码视频源。 ### pushExternalVideoFrame ```cpp virtual int bytertc::IRTCVideo::pushExternalVideoFrame(IVideoFrame* frame)=0 ``` 推送外部视频帧。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | frame | IVideoFrame * | 设置视频帧，参看 [IVideoFrame](85519#IVideoFrame)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 支持格式：I420, NV12, RGBA, BGRA, ARGB - 该函数运行在用户调用线程内 - 推送外部视频帧前，必须调用 [setVideoSourceType](#IRTCVideo-setvideosourcetype) 开启外部视频源采集。 ### createRTCRoom ```cpp virtual IRTCRoom * bytertc::IRTCVideo::createRTCRoom(const char* room_id)=0 ``` 创建房间实例。调用此方法仅返回一个房间实例，你仍需调用 [joinRoom](#IRTCRoom-joinroom) 才能真正地创建/加入房间。多次调用此方法以创建多个 [IRTCRoom](#IRTCRoom) 实例。分别调用各 IRTCRoom 实例中的 [joinRoom](#IRTCRoom-joinroom) 方法，同时加入多个房间。多房间模式下，用户可以同时订阅各房间的音视频流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | room_id | const char * | 标识通话房间的房间 ID。该字符串符合正则表达式：`[a-zA-Z0-9_@-.]{1,128}`。 | **返回值** 创建的 [IRTCRoom](#IRTCRoom) 房间实例。 **注意** - 如果需要加入的房间已存在，你仍需先调用本方法来获取 IRTCRoom 实例，再调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 请勿使用同样的 roomId 创建多个房间，否则后创建的房间实例会替换先创建的房间实例。 - 如果你需要在多个房间发布音视频流，无须创建多房间，直接调用 [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms) 开始跨房间转发媒体流。 ### setPublishFallbackOption ```cpp virtual int bytertc::IRTCVideo::setPublishFallbackOption(PublishFallbackOption option)=0 ``` 设置发布的音视频流的回退选项。你可以调用该接口设置网络不佳或设备性能不足时从大流起进行降级处理，以保证通话质量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | option | PublishFallbackOption | 本地发布的音视频流回退选项，参看 [PublishFallbackOption](85519#PublishFallbackOption)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法仅在调用 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 开启了发送多路视频流的情况下生效。 - 该方法必须在进房前设置，进房后设置或更改设置无效。 - 调用该方法后，如因性能或网络不佳产生发布性能回退或恢复，本端会提前收到 [onPerformanceAlarms](85517#IRTCVideoEventHandler-onperformancealarms) 回调发出的告警，以便采集设备配合调整。 - 设置回退后，本地发布的音视频流发生回退或从回退中恢复后，远端会收到 [onSimulcastSubscribeFallback](85517#IRTCVideoEventHandler-onsimulcastsubscribefallback) 回调，通知该情况。 - 你可以调用客户端 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 ### setSubscribeFallbackOption ```cpp virtual int bytertc::IRTCVideo::setSubscribeFallbackOption(SubscribeFallbackOption option)=0 ``` 设置订阅的音视频流的回退选项。你可调用该接口设置网络不佳或设备性能不足时允许订阅流进行降级或只订阅音频流，以保证通话流畅。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | option | SubscribeFallbackOption | 订阅的音视频流回退选项，参看 [SubscribeFallbackOption](85519#SubscribeFallbackOption)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 你必须在进房前设置，进房后设置或更改设置无效。 - 设置回退选项后，订阅的音视频流发生回退或从回退中恢复时，会收到 [onSimulcastSubscribeFallback](85517#IRTCVideoEventHandler-onsimulcastsubscribefallback) 和 [onRemoteVideoSizeChanged](85517#IRTCVideoEventHandler-onremotevideosizechanged) 回调通知。 - 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。 ### setRemoteUserPriority ```cpp virtual int bytertc::IRTCVideo::setRemoteUserPriority( const char* room_id, const char* user_id, RemoteUserPriority priority )=0 ``` 设置用户优先级。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | room_id | const char * | 房间 ID | | user_id | const char * | 远端用户的 ID | | priority | RemoteUserPriority | 远端用户的需求优先级，详见枚举类型 [RemoteUserPriority](85519#RemoteUserPriority) | **返回值** - 0: 调用成功。 - < 0: 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 1. 该方法与 [setSubscribeFallbackOption](#IRTCVideo-setsubscribefallbackoption) 搭配使用。 - 2. 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。 - 3. 该方法在进房前后都可以使用，可以修改远端用户的优先级。 ### setBusinessId ```cpp virtual int bytertc::IRTCVideo::setBusinessId(const char* business_id)=0 ``` 设置业务标识参数可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | business_id | const char * |
用户设置的自己的 businessId 值
businessId 只是一个标签，颗粒度需要用户自定义。 | **返回值** - 0：成功。 - -2：输入非法，合法字符包括所有小写字母、大写字母和数字，除此外还包括四个独立字符，分别是：英文句号，短横线，下划线和 @ 。 **注意** - 需要在调用 [joinRoom](#IRTCRoom-joinroom) 之前调用，[joinRoom](#IRTCRoom-joinroom) 之后调用该方法无效。 ### setRemoteVideoMirrorType ```cpp virtual int bytertc::IRTCVideo::setRemoteVideoMirrorType( RemoteStreamKey stream_key, RemoteMirrorType mirror_type )=0 ``` > Available since 3.57 使用内部渲染时，为远端流开启镜像。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_key | RemoteStreamKey | 远端流信息，用于指定需要镜像的视频流来源及属性，参看 [RemoteStreamKey](85519#RemoteStreamKey)。 | | mirror_type | RemoteMirrorType | 远端流的镜像类型，参看 [RemoteMirrorType](85519#RemoteMirrorType)。 | **返回值** - 0: 调用成功。 - < 0: 调用失败，参看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 ### setEncryptInfo ```cpp virtual int bytertc::IRTCVideo::setEncryptInfo( EncryptType encrypt_type, const char* key, int key_size )=0 ``` 设置传输时使用内置加密的方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | encrypt_type | EncryptType | 内置加密算法，详见 [EncryptType](85519#EncryptType) | | key | const char * | 加密密钥，长度限制为 36 位，超出部分将会被截断 | | key_size | int | 参数 key 的长度 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 使用传输时内置加密时，使用此方法；如果需要使用传输时自定义加密，参看 [onEncryptData](85517#IEncryptHandler-onencryptdata)。内置加密和自定义加密互斥，根据最后一个调用的方法确定传输是加密的方案。 - 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。 ### setCustomizeEncryptHandler ```cpp virtual int bytertc::IRTCVideo::setCustomizeEncryptHandler(IEncryptHandler* handler)=0 ``` 设置自定义加密和解密方式。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IEncryptHandler * | 自定义加密 handler，需要实现 handler 的加密和解密方法。参看 [IEncryptHandler](85517#IEncryptHandler)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法与 [setEncryptInfo](#IRTCVideo-setencryptinfo) 为互斥关系，只能选择自定义加密方式或者默认加密方式。最终生效的加密方式取决于最后一个调用的方法。 - 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。 - 无论加密或者解密，其对原始数据的长度修改，需要控制在 180% 之间，即如果输入数据为 100 字节，则处理完成后的数据必须不超过 180 字节，如果加密或解密结果超出该长度限制，则该音视频帧可能会被丢弃。 - 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率。是否使用该方法，需要由使用方谨慎评估。 ### enableAudioFrameCallback ```cpp virtual int bytertc::IRTCVideo::enableAudioFrameCallback( AudioFrameCallbackMethod method, AudioFormat format )=0 ``` 设置并开启指定的音频数据帧回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioFrameCallbackMethod | 音频回调方法，参看 [AudioFrameCallbackMethod](85519#AudioFrameCallbackMethod)。
当音频回调方法设置为 `kRecord`、`kPlayback`、`kMixed`、`kRecordScreen`时，你需要在参数 `format` 中指定准确的采样率和声道，暂不支持设置为自动。
当音频回调方法设置为 `kRemoteUser`时，将 `format` 中的各个字段设置为默认值。 | | format | AudioFormat | 音频参数格式，参看 [AudioFormat](85519#AudioFormat)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 开启音频回调并调用 [registerAudioFrameObserver](#IRTCVideo-registeraudioframeobserver) 后， [IAudioFrameObserver](85517#IAudioFrameObserver) 会收到对应的音频回调。两者调用顺序没有限制且相互独立。 ### disableAudioFrameCallback ```cpp virtual int bytertc::IRTCVideo::disableAudioFrameCallback(AudioFrameCallbackMethod method)=0 ``` 关闭音频回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioFrameCallbackMethod | 音频回调方法，参看 [AudioFrameCallbackMethod](85519#AudioFrameCallbackMethod)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 该方法需要在调用 [enableAudioFrameCallback](#IRTCVideo-enableaudioframecallback) 之后调用。 ### registerAudioFrameObserver ```cpp virtual int bytertc::IRTCVideo::registerAudioFrameObserver(IAudioFrameObserver* observer)=0 ``` 注册音频数据回调观察者。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IAudioFrameObserver * | 音频数据观察者，参看 [IAudioFrameObserver](85517#IAudioFrameObserver)。如果传入 null，则取消注册。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 注册音频数据回调观察者并调用 [enableAudioFrameCallback](#IRTCVideo-enableaudioframecallback) 后， [IAudioFrameObserver](85517#IAudioFrameObserver) 会收到对应的音频回调。对回调中收到的音频数据进行处理，不会影响 RTC 的编码发送或渲染。 ### registerAudioProcessor ```cpp virtual int bytertc::IRTCVideo::registerAudioProcessor(IAudioFrameProcessor* processor)=0 ``` 注册自定义音频处理器。注册完成后，你可以调用 [enableAudioProcessor](#IRTCVideo-enableaudioprocessor)，对本地采集到的音频进行处理，RTC SDK 将对处理后的音频进行编码和发送。也可以对接收到的远端音频进行自定义处理，RTC SDK 将对处理后的音频进行渲染。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | processor | IAudioFrameProcessor * | 自定义音频处理器，详见 [IAudioFrameProcessor](85517#IAudioFrameProcessor)。
SDK 只持有 processor 的弱引用，你应保证其生命周期。需要取消注册时，设置此参数为 nullptr。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 重复调用此接口时，仅最后一次调用生效。 - 更多相关信息，详见[音频自定义处理](https://www.volcengine.com/docs/6348/80635)。 ### enableAudioProcessor ```cpp virtual int bytertc::IRTCVideo::enableAudioProcessor( AudioProcessorMethod method, AudioFormat format )=0 ``` 设置并开启指定的音频帧回调，进行自定义处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioProcessorMethod | 音频帧类型，参看 [AudioProcessorMethod](85519#AudioProcessorMethod)。可多次调用此接口，处理不同类型的音频帧。
选择不同类型的音频帧将收到对应的回调：

选择本地采集的音频时，会收到 [onProcessRecordAudioFrame](85517#IAudioFrameProcessor-onprocessrecordaudioframe)。
选择远端音频流的混音音频时，会收到 [onProcessPlayBackAudioFrame](85517#IAudioFrameProcessor-onprocessplaybackaudioframe)。
选择远端音频流时，会收到 [onProcessRemoteUserAudioFrame](85517#IAudioFrameProcessor-onprocessremoteuseraudioframe)。
选择屏幕共享音频流时，会收到 [onProcessScreenAudioFrame](85517#IAudioFrameProcessor-onprocessscreenaudioframe)。（Linux 不适用）

| | format | AudioFormat | 设定自定义处理时获取的音频帧格式，参看 [AudioFormat](85519#AudioFormat)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 在调用此接口前，你需要调用 [registerAudioProcessor](#IRTCVideo-registeraudioprocessor) 注册自定义音频处理器。 - 要关闭音频自定义处理，调用 [disableAudioProcessor](#IRTCVideo-disableaudioprocessor)。 ### disableAudioProcessor ```cpp virtual int bytertc::IRTCVideo::disableAudioProcessor(AudioProcessorMethod method)=0 ``` 关闭自定义音频处理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | method | AudioProcessorMethod | 音频帧类型，参看 [AudioProcessorMethod](85519#AudioProcessorMethod)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 ### registerLocalVideoProcessor ```cpp virtual int bytertc::IRTCVideo::registerLocalVideoProcessor( IVideoProcessor* processor, VideoPreprocessorConfig config )=0 ``` 设置自定义视频前处理器。使用这个视频前处理器，你可以调用 [processVideoFrame](#IVideoProcessor-processvideoframe) 对 RTC SDK 采集得到的视频帧进行前处理，并将处理后的视频帧用于 RTC 音视频通信。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | processor | IVideoProcessor * | 自定义视频处理器，详见 [IVideoProcessor](#IVideoProcessor)。如果传入 null，则不对 RTC SDK 采集得到的视频帧进行前处理。
SDK 只持有 processor 的弱引用，你应保证其生命周期。 | | config | VideoPreprocessorConfig | 自定义视频前处理器适用的设置，详见 [VideoPreprocessorConfig](85519#VideoPreprocessorConfig)。
当前，`config` 中的 `required_pixel_format` 仅支持：`kVideoPixelFormatI420` 和 `kVideoPixelFormatUnknown`：

设置为 `kVideoPixelFormatUnknown` 时，RTC SDK 给出供 processor 处理的视频帧格式即采集的格式。你可以通过 [VideoFrameType](85519#VideoFrameType) 和 [VideoPixelFormat](85519#VideoPixelFormat) 获取实际采集的视频帧格式和像素类型。
设置为 `kVideoPixelFormatI420` 时，RTC SDK 会将采集得到的视频帧转变为对应的格式，供前处理使用。
设置为其他值时，此方法调用失败。

| **返回值** - 0：调用成功。 - !0：调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 对于 Windows 平台，经前处理返回的视频帧格式仅支持 `kVideoPixelFormatI420` - 对于 Windows 平台，将 `config` 中的 required_pixel_format 设置为 `kVideoPixelFormatI420`，可以通过避免格式转换带来一些性能优化。 - 重复调用此接口时，仅最后一次调用生效。效果不会叠加。 ### setVideoDigitalZoomConfig ```cpp virtual int bytertc::IRTCVideo::setVideoDigitalZoomConfig( ZoomConfigType type, float size )=0 ``` > Available since 3.51 设置本地摄像头数码变焦参数，包括缩放倍数，移动步长。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | ZoomConfigType | 数码变焦参数类型，缩放系数或移动步长。参看 [ZoomConfigType](85519#ZoomConfigType)。必填。 | | size | float | 缩放系数或移动步长，保留到小数点后三位。默认值为 0。必填。
选择不同 `type` 时有不同的取值范围。当计算后的结果超过缩放和移动边界时，取临界值。

`kZoomConfigTypeFocusOffset`：缩放系数增量，范围为 [0, 7]。例如，设置为 0.5 时，如果调用 [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol) 选择 Zoom in，则缩放系数增加 0.5。缩放系数范围 [1，8]，默认为 `1`，原始大小。
`kZoomConfigTypeMoveOffset`：移动百分比，范围为 [0, 0.5]，默认为 0，不移动。如果调用 [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol) 选择的是左右移动，则移动距离为 size x 原始视频宽度；如果选择的是上下移动，则移动距离为 size x 原始视频高度。例如，视频帧边长为 1080 px，设置为 0.5 时，实际移动距离为 0.5 x 1080 px = 540 px。

| **返回值** - 0：成功。 - !0：失败。 **注意** - 每次调用本接口只能设置一种参数。如果缩放系数和移动步长都需要设置，分别调用本接口传入相应参数。 - 由于移动步长的默认值为 `0` ，在调用 [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol) 或 [startVideoDigitalZoomControl](#IRTCVideo-startvideodigitalzoomcontrol) 进行数码变焦操作前，应先调用本接口。 ### setVideoDigitalZoomControl ```cpp virtual int bytertc::IRTCVideo::setVideoDigitalZoomControl(ZoomDirectionType direction)=0 ``` > Available since 3.51 控制本地摄像头数码变焦，缩放或移动一次。设置对本地预览画面和发布到远端的视频都生效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | direction | ZoomDirectionType | 数码变焦操作类型，参看 [ZoomDirectionType](85519#ZoomDirectionType)。 | **返回值** - 0：成功。 - !0：失败。 **注意** - 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomConfig](#IRTCVideo-setvideodigitalzoomconfig) 设置参数。 - 调用该方法进行移动前，应先使用本方法或 [startVideoDigitalZoomControl](#IRTCVideo-startvideodigitalzoomcontrol) 进行放大，否则无法移动。 - 当数码变焦操作超出范围时，将置为临界值。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 - 如果你希望实现持续数码变焦操作，调用 [startVideoDigitalZoomControl](#IRTCVideo-startvideodigitalzoomcontrol)。 - 移动端可对摄像头进行光学变焦控制，参看 `setCameraZoomRatio`。 ### startVideoDigitalZoomControl ```cpp virtual int bytertc::IRTCVideo::startVideoDigitalZoomControl(ZoomDirectionType direction)=0 ``` > Available since 3.51 开启本地摄像头持续数码变焦，缩放或移动。设置对本地预览画面和发布到远端的视频都生效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | direction | ZoomDirectionType | 数码变焦操作类型，参看 [ZoomDirectionType](85519#ZoomDirectionType)。 | **返回值** - 0：成功。 - !0：失败。 **注意** - 由于默认步长为 `0`，调用该方法前需通过 [setVideoDigitalZoomConfig](#IRTCVideo-setvideodigitalzoomconfig) 设置参数。 - 调用该方法进行移动前，应先使用本方法或 [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol) 进行放大，否则无法移动。 - 当数码变焦操作超出范围时，将置为临界值并停止操作。例如，移动到了图片边界、放大到了 8 倍、缩小到原图大小。 - 你也可以调用 [stopVideoDigitalZoomControl](#IRTCVideo-stopvideodigitalzoomcontrol) 手动停止控制。 - 如果你希望实现单次数码变焦操作，调用 [setVideoDigitalZoomControl](#IRTCVideo-setvideodigitalzoomcontrol)。 - 移动端可对摄像头进行光学变焦控制，参看 `setCameraZoomRatio`。 ### stopVideoDigitalZoomControl ```cpp virtual int bytertc::IRTCVideo::stopVideoDigitalZoomControl()=0 ``` > Available since 3.51 停止本地摄像头持续数码变焦。 **返回值** - 0：成功。 - !0：失败。 **注意** 关于开始数码变焦，参看 [startVideoDigitalZoomControl](#IRTCVideo-startvideodigitalzoomcontrol)。 ### sendSEIMessage ```cpp virtual int bytertc::IRTCVideo::sendSEIMessage( StreamIndex stream_index, const uint8_t* message, int length, int repeat_count, SEICountPerFrame mode )=0 ``` 通过视频帧发送 SEI 数据。在视频通话场景下，SEI 数据会随视频帧发送；在语音通话场景下，SDK 会自动生成一路 16px × 16px 的黑帧视频流用来发送 SEI 数据。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_index | StreamIndex | 指定携带 SEI 数据的媒体流类型，参看 [StreamIndex](85519#StreamIndex)。
语音通话场景下，该值需设为 `kStreamIndexMain`，否则 SEI 数据会被丢弃从而无法送达远端。 | | message | const uint8_t * | SEI 消息。 | | length | int | SEI 消息长度，建议每帧 SEI 数据总长度长度不超过 4 KB。 | | repeat_count | int | 消息发送重复次数。取值范围是 [0, max{29, %{视频帧率}-1}]。推荐范围 [2,4]。
调用此接口后，SEI 数据会添加到从当前视频帧开始的连续 `repeat_count+1` 个视频帧中。 | | mode | SEICountPerFrame | SEI 发送模式，参看 [SEICountPerFrame](85519#SEICountPerFrame)。 | **返回值** - \>= 0: 将被添加到视频帧中的 SEI 的数量。 - < 0: 发送失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 每秒发送的 SEI 消息数量建议不超过当前的视频帧率。在语音通话场景下，黑帧帧率为 15 fps。 - 语音通话场景中，仅支持在内部采集模式下调用该接口发送 SEI 数据。 - 视频通话场景中，使用自定义采集并通过 [pushExternalVideoFrame](#IRTCVideo-pushexternalvideoframe) 推送至 SDK 的视频帧，若本身未携带 SEI 数据，也可通过本接口发送 SEI 数据；若原视频帧中已添加了 SEI 数据，则调用此方法不生效。 - 视频帧仅携带前后 2s 内收到的 SEI 数据；语音通话场景下，若调用此接口后 1min 内未有 SEI 数据发送，则 SDK 会自动取消发布视频黑帧。 - 消息发送成功后，远端会收到 [onSEIMessageReceived](85517#IRTCVideoEventHandler-onseimessagereceived) 回调。 - 语音通话切换至视频通话时，会停止使用黑帧发送 SEI 数据，自动转为用采集到的正常视频帧发送 SEI 数据。 - SEI PayLoadType 需为 `5` 或 `100`。 ### getVideoDeviceManager ```cpp virtual IVideoDeviceManager * bytertc::IRTCVideo::getVideoDeviceManager()=0 ``` 创建视频设备管理实例 **返回值** 视频设备管理实例，详见 [IVideoDeviceManager](#IVideoDeviceManager) ### getAudioDeviceManager ```cpp virtual IAudioDeviceManager * bytertc::IRTCVideo::getAudioDeviceManager()=0 ``` 设备音频管理接口创建 **返回值** 音频设备管理接口 ### startFileRecording ```cpp virtual int bytertc::IRTCVideo::startFileRecording( StreamIndex type, RecordingConfig config, RecordingType recording_type )=0 ``` 录制通话过程中的音视频数据到本地的文件中。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | StreamIndex | 流属性，指定录制主流还是屏幕流，参看 [StreamIndex](85519#StreamIndex) | | config | RecordingConfig | 本地录制参数配置，参看 [RecordingConfig](85519#RecordingConfig) | | recording_type | RecordingType | 本地录制的媒体类型，参看 [RecordingType](85519#RecordingType) | **返回值** - 0: 调用成功。录制开始后，你可以通过每秒一次的 [onRecordingProgressUpdate](85517#IRTCVideoEventHandler-onrecordingprogressupdate) 回调获取录制进度。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。你还可以通过 [onRecordingStateUpdate](85517#IRTCVideoEventHandler-onrecordingstateupdate) 回调感知和处理录制错误。 **注意** 该方法需在本端用户进房并发布媒体流后调用。 ### stopFileRecording ```cpp virtual int bytertc::IRTCVideo::stopFileRecording(StreamIndex type)=0 ``` 停止本地录制 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | StreamIndex | 流属性，指定停止主流或者屏幕流录制，参看 [StreamIndex](85519#StreamIndex) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 调用 [startFileRecording](#IRTCVideo-startfilerecording) 开启本地录制后，你必须调用该方法停止录制。 - 调用该方法后，你会收到 [onRecordingStateUpdate](85517#IRTCVideoEventHandler-onrecordingstateupdate) 回调提示录制结果。 ### startAudioRecording ```cpp virtual int bytertc::IRTCVideo::startAudioRecording(AudioRecordingConfig &config)=0 ``` 开启录制语音通话，生成本地文件。在进房前后开启录制，如果未打开麦克风采集，录制任务正常进行，只是不会将数据写入生成的本地文件；只有调用 [startAudioCapture](#IRTCVideo-startaudiocapture) 接口打开麦克风采集后，才会将录制数据写入本地文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | AudioRecordingConfig & | 参看 [AudioRecordingConfig](85519#AudioRecordingConfig) | **返回值** - 0: 正常 - -2: 参数设置异常 - -3: 当前版本 SDK 不支持该特性，请联系技术支持人员 **注意** - 录制包含各种音频效果。但不包含背景音乐。 - 调用 [stopAudioRecording](#IRTCVideo-stopaudiorecording) 关闭录制。 - 加入房间前后均可调用。在进房前调用该方法，退房之后，录制任务不会自动停止，需调用 [stopAudioRecording](#IRTCVideo-stopaudiorecording) 关闭录制。在进房后调用该方法，退房之后，录制任务会自动被停止。如果加入了多个房间，录制的文件中会包含各个房间的音频。 - 调用该方法后，你会收到 [onAudioRecordingStateUpdate](85517#IRTCVideoEventHandler-onaudiorecordingstateupdate) 回调。 ### stopAudioRecording ```cpp virtual int bytertc::IRTCVideo::stopAudioRecording()=0 ``` 停止音频文件录制 **返回值** - 0: 正常 - -3: 当前版本 SDK 不支持该特性，请联系技术支持人员 **注意** 调用 [startAudioRecording](#IRTCVideo-startaudiorecording) 开启本地录制。 ### enableExternalSoundCard ```cpp virtual int bytertc::IRTCVideo::enableExternalSoundCard(bool enable)=0 ``` 启用匹配外置声卡的音频处理模式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool |

true: 开启
false: 不开启(默认)

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 当采用外接声卡进行音频采集时，建议开启此模式，以获得更好的音质。 - 开启此模式时，仅支持耳机播放。如果需要使用扬声器或者外置音箱播放，关闭此模式。 ### setRuntimeParameters ```cpp virtual int bytertc::IRTCVideo::setRuntimeParameters(const char* json_string)=0 ``` 设置运行时的参数 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | json_string | const char * | json 序列化之后的字符串 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 该接口需在 [joinRoom](#IRTCRoom-joinroom) 和 [startAudioCapture](#IRTCVideo-startaudiocapture) 之前调用。 ### feedback ```cpp virtual int bytertc::IRTCVideo::feedback( uint64_t type, const ProblemFeedbackInfo* info )=0 ``` 将用户反馈的问题上报到 RTC。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | uint64_t | 预设问题列表，参看 [ProblemFeedbackOption](85519#ProblemFeedbackOption) | | info | const ProblemFeedbackInfo * | 预设问题以外的其他问题的具体描述，房间信息。参看 [ProblemFeedbackInfo](85519#ProblemFeedbackInfo) | **返回值** - 0: 上报成功。 - -3: 上报失败。 **注意** - 你可以在 [RTC 控制台](https://console.volcengine.com/rtc/callQualityRTC/feedback?from=doc)上查看用户通过此接口提交的反馈详情和整体趋势。 - 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。 ### getAudioEffectPlayer ```cpp virtual IAudioEffectPlayer * bytertc::IRTCVideo::getAudioEffectPlayer()=0 ``` > Available since 3.53 创建音效播放器实例。 **返回值** 音效播放器。详见 [IAudioEffectPlayer](#IAudioEffectPlayer)。 ### getMediaPlayer ```cpp virtual IMediaPlayer * bytertc::IRTCVideo::getMediaPlayer(int player_id)=0 ``` > Available since 3.53 创建音乐播放器实例。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | player_id | int | 音乐播放器实例 id。取值范围为 `[0, 3]`。最多同时存在 4 个实例，超出取值范围时返回 nullptr。 | **返回值** 音乐播放器实例，详见 [IMediaPlayer](#IMediaPlayer) ### login ```cpp virtual int bytertc::IRTCVideo::login( const char* token, const char* uid )=0 ``` 登陆 RTS 服务器。必须先登录，才能调用 [sendUserMessageOutsideRoom](#IRTCVideo-sendusermessageoutsideroom) 和 [sendServerMessage](#IRTCVideo-sendservermessage) 发送房间外点对点消息和向应用服务器发送消息在调用本接口登录后，如果想要登出，需要调用 [logout](#IRTCVideo-logout)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | const char * | 用户登录必须携带的 Token，用于鉴权验证。
测试时可使用[控制台](https://console.volcengine.com/rtc/listRTC?from=doc)生成临时 Token，`roomId` 填任意值。
正式上线需要使用密钥 SDK 在你的服务端生成并下发 Token，`roomId` 置为空字符串（即 `roomId:""`），Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。 | | uid | const char * |
用户 ID
用户 ID 在 appid 的维度下是唯一的。 | **返回值** - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** 本地用户调用此方法登录后，会收到 [onLoginResult](85517#IRTCVideoEventHandler-onloginresult) 回调通知登录结果，远端用户不会收到通知。 ### logout ```cpp virtual int bytertc::IRTCVideo::logout()=0 ``` 登出 RTS 服务器。调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本接口登出前，必须先调用 [login](#IRTCVideo-login) 登录。 - 本地用户调用此方法登出后，会收到 [onLogout](85517#IRTCVideoEventHandler-onlogout) 回调通知结果，远端用户不会收到通知。 ### updateLoginToken ```cpp virtual int bytertc::IRTCVideo::updateLoginToken(const char* token)=0 ``` 更新用户用于登录的 Token Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。调用 [login](#IRTCVideo-login) 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 [onLoginResult](85517#IRTCVideoEventHandler-onloginresult) 回调通知，错误码为 kLoginErrorCodeInvalidToken。此时需要重新获取 Token，并调用此方法更新 Token。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | const char * |
更新的动态密钥 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 如果 Token 无效导致登录失败，则调用此方法更新 Token 后，SDK 会自动重新登录，而用户不需要自己调用 [login](#IRTCVideo-login) 方法。 - Token 过期时，如果已经成功登录，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 登录时，或因本地网络状况不佳导致断网重新登录时通知给用户。 ### setServerParams ```cpp virtual int bytertc::IRTCVideo::setServerParams( const char* signature, const char* url )=0 ``` 设置应用服务器参数客户端调用 [sendServerMessage](#IRTCVideo-sendservermessage) 或 [sendServerBinaryMessage](#IRTCVideo-sendserverbinarymessage) 发送消息给应用服务器之前，必须设置有效签名和应用服务器地址。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | signature | const char * | 动态签名，应用服务器可使用该签名验证消息来源。
签名需自行定义，可传入任意非空字符串，建议将 uid 等信息编码为签名。
设置的签名会以 post 形式发送至通过本方法中 url 参数设置的应用服务器地址。 | | url | const char * | 应用服务器的地址 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 用户必须调用 [login](#IRTCVideo-login) 登录后，才能调用本接口。 - 调用本接口后，SDK 会使用 [onServerParamsSetResult](85517#IRTCVideoEventHandler-onserverparamssetresult) 返回相应结果。 ### getPeerOnlineStatus ```cpp virtual int bytertc::IRTCVideo::getPeerOnlineStatus(const char* peer_user_id)=0 ``` 查询对端用户或本端用户的登录状态 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | peer_user_id | const char * |
需要查询的用户 ID | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 必须调用 [login](#IRTCVideo-login) 登录后，才能调用本接口。 - 调用本接口后，SDK 会使用 [onGetPeerOnlineStatus](85517#IRTCVideoEventHandler-ongetpeeronlinestatus) 回调通知查询结果。 - 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。 ### sendUserMessageOutsideRoom ```cpp virtual int64_t bytertc::IRTCVideo::sendUserMessageOutsideRoom( const char* uid, const char* message, MessageConfig config=kMessageConfigReliableOrdered )=0 ``` 给房间外指定的用户发送文本消息（P2P） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | const char * |
消息接收用户的 ID | | message | const char * |
发送的文本消息内容
消息不超过 64 KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](85519#MessageConfig)。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 **注意** - 在发送房间外文本消息前，必须先调用 [login](#IRTCVideo-login) 完成登录。 - 用户调用本接口发送文本信息后，会收到一次 [onUserMessageSendResultOutsideRoom](85517#IRTCVideoEventHandler-onusermessagesendresultoutsideroom) 回调，得知消息是否成功发送。 - 若文本消息发送成功，则 uid 所指定的用户会通过 [onUserMessageReceivedOutsideRoom](85517#IRTCVideoEventHandler-onusermessagereceivedoutsideroom) 回调收到该消息。 ### sendUserBinaryMessageOutsideRoom ```cpp virtual int64_t bytertc::IRTCVideo::sendUserBinaryMessageOutsideRoom( const char* uid, int length, const uint8_t* message, MessageConfig config=kMessageConfigReliableOrdered )=0 ``` 给房间外指定的用户发送二进制消息（P2P） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | const char * |
消息接收用户的 ID | | length | int |
二进制字符串的长度 | | message | const uint8_t * |
发送的二进制消息内容
消息不超过 46KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](85519#MessageConfig)。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 - -1：发送失败。消息为空。 **注意** - 在发送房间外二进制消息前，必须先调用 [login](#IRTCVideo-login) 完成登录。 - 用户调用本接口发送二进制消息后，会收到一次 [onUserMessageSendResultOutsideRoom](85517#IRTCVideoEventHandler-onusermessagesendresultoutsideroom) 回调，通知消息是否发送成功。 - 若二进制消息发送成功，则 uid 所指定的用户会通过 [onUserBinaryMessageReceivedOutsideRoom](85517#IRTCVideoEventHandler-onuserbinarymessagereceivedoutsideroom) 回调收到该条消息。 ### sendServerMessage ```cpp virtual int64_t bytertc::IRTCVideo::sendServerMessage(const char* message)=0 ``` 客户端给应用服务器发送文本消息（P2Server） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | message | const char * |
发送的文本消息内容
消息不超过 64 KB。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 **注意** - 在向应用服务器发送文本消息前，必须先调用 [login](#IRTCVideo-login) 完成登录，随后调用 [setServerParams](#IRTCVideo-setserverparams) 设置应用服务器。 - 调用本接口后，会收到一次 [onServerMessageSendResult](85517#IRTCVideoEventHandler-onservermessagesendresult) 回调，通知消息发送方是否发送成功。 - 若文本消息发送成功，则之前调用 [setServerParams](#IRTCVideo-setserverparams) 设置的应用服务器会收到该条消息。 ### sendServerBinaryMessage ```cpp virtual int64_t bytertc::IRTCVideo::sendServerBinaryMessage( int length, const uint8_t* message )=0 ``` 客户端给应用服务器发送二进制消息（P2Server） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | length | int |
二进制字符串的长度 | | message | const uint8_t * |
发送的二进制消息内容
消息不超过 46KB。 | **返回值** - \>0：发送成功，返回这次发送消息的编号，从 1 开始递增。 - -1：发送失败。消息为空。 **注意** - 在向应用服务器发送二进制消息前，必须先调用 [login](#IRTCVideo-login) 完成登录，随后调用 [setServerParams](#IRTCVideo-setserverparams) 设置应用服务器。 - 调用本接口后，会收到一次 [onServerMessageSendResult](85517#IRTCVideoEventHandler-onservermessagesendresult) 回调，通知消息发送方发送成功或失败。 - 若二进制消息发送成功，则之前调用 [setServerParams](#IRTCVideo-setserverparams) 设置的应用服务器会收到该条消息。 ### startNetworkDetection ```cpp virtual int bytertc::IRTCVideo::startNetworkDetection( bool is_test_uplink, int expected_uplink_bitrate, bool is_test_downlink, int expected_downlink_biterate )=0 ``` 开启通话前网络探测 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | is_test_uplink | bool | 是否探测上行带宽 | | expected_uplink_bitrate | int | 期望上行带宽，单位：kbps
范围为 {0, [100-10000]}，其中， `0` 表示由 SDK 指定最高码率。 | | is_test_downlink | bool | 是否探测下行带宽 | | expected_downlink_biterate | int | 期望下行带宽，单位：kbps
范围为 {0, [100-10000]}，其中， `0` 表示由 SDK 指定最高码率。 | **返回值** - 0: 调用成功。探测结果将通过 [onNetworkDetectionResult](85517#IRTCVideoEventHandler-onnetworkdetectionresult) 周期性回调。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 调用时机：本端发布或订阅媒体流之前，进房前后均可调用。进房不会打断进房前已开始的探测。 - 若探测停止，则会收到一次 [onNetworkDetectionStopped](85517#IRTCVideoEventHandler-onnetworkdetectionstopped) 通知探测停止。 ### stopNetworkDetection ```cpp virtual int bytertc::IRTCVideo::stopNetworkDetection()=0 ``` 停止通话前网络探测 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本接口后，会收到一次 [onNetworkDetectionStopped](85517#IRTCVideoEventHandler-onnetworkdetectionstopped) 回调通知探测停止。 ### startScreenAudioCapture ```cpp virtual int bytertc::IRTCVideo::startScreenAudioCapture()=0 ``` 在屏幕共享时，开始使用 RTC SDK 内部采集方式，采集屏幕音频 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 本接口仅对内部采集生效，RTC SDK 默认使用内部采集模块采集屏幕音频。 - 采集后，你还需要调用 [publishScreen](#IRTCRoom-publishscreen) 将采集到的屏幕音频推送到远端。 - 要关闭屏幕音频内部采集，调用 [stopScreenAudioCapture](#IRTCVideo-stopscreenaudiocapture)。 ### stopScreenAudioCapture ```cpp virtual int bytertc::IRTCVideo::stopScreenAudioCapture()=0 ``` 在屏幕共享时，停止使用 RTC SDK 内部采集方式，采集屏幕音频。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本接口时，采集模式应为内部模式。在外部采集模式下调用无效，并将触发 [onAudioDeviceWarning](85517#IRTCVideoEventHandler-onaudiodevicewarning) 回调。 - 本接口仅对内部采集生效。如果为外部采集模式，调用本接口失败。你需要在外部采集器中实现停止采集的逻辑。 - 要开始屏幕音频内部采集，调用 [startScreenAudioCapture](#IRTCVideo-startscreenaudiocapture)。 ### setAudioAlignmentProperty ```cpp virtual int bytertc::IRTCVideo::setAudioAlignmentProperty( const RemoteStreamKey &stream_key, AudioAlignmentMode mode )=0 ``` 在听众端，设置订阅的所有远端音频流精准对齐后播放。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_key | const RemoteStreamKey & | 作为对齐基准的远端音频流。参看 [RemoteStreamKey](85519#RemoteStreamKey)。
一般选择主唱的音频流。
你必须在收到 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream)，确认此音频流已发布后，调用此 API。 | | mode | AudioAlignmentMode | 是否对齐，默认不对齐。参看 [AudioAlignmentMode](85519#AudioAlignmentMode)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 你必须在实时合唱场景下使用此功能。在加入房间时，所有人应设置 [RoomProfileType](85519#RoomProfileType) 为 `kRoomProfileTypeChorus`。 - 订阅的所有远端流必须通过 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开启了背景音乐混音，并将 [AudioMixingConfig](85519#AudioMixingConfig) 中的 `sync_progress_to_record_frame` 设置为 `true`。 - 如果订阅的某个音频流延迟过大，可能无法实现精准对齐。 - 合唱的参与者不应调用此 API，因为调用此 API 会增加延迟。如果希望从听众变为合唱参与者，应关闭对齐功能。 ### startPushPublicStream ```cpp virtual int bytertc::IRTCVideo::startPushPublicStream( const char* public_stream_id, IPublicStreamParam* param )=0 ``` 发布一路公共流用户可以指定房间内多个用户发布的媒体流合成一路公共流。使用同一 `appID` 的用户，可以调用 [startPlayPublicStream](#IRTCVideo-startplaypublicstream) 获取和播放指定的公共流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | | param | IPublicStreamParam * | 公共流参数。详见 [IPublicStreamParam](85519#IPublicStreamParam)。
一路公共流可以包含多路房间内的媒体流，按照指定的布局方式进行聚合。
如果指定的媒体流还未发布，则公共流将在指定流开始发布后实时更新。 | **返回值** - 0: 成功。同时将收到 [onPushPublicStreamResult](85517#IRTCVideoEventHandler-onpushpublicstreamresult) 回调。 - !0: 失败。当参数不合法或参数为空，调用失败。 **注意** - 同一用户使用同一公共流 ID 多次调用本接口无效。如果你希望更新公共流参数，调用 [updatePublicStreamParam](#IRTCVideo-updatepublicstreamparam) 接口。 - 不同用户使用同一公共流 ID 多次调用本接口时，RTC 将使用最后一次调用时传入的参数更新公共流。 - 使用不同的 ID 多次调用本接口可以发布多路公共流。 - 调用 [stopPushPublicStream](#IRTCVideo-stoppushpublicstream) 停止发布公共流。 - 关于公共流功能的介绍，详见[发布和订阅公共流](https://www.volcengine.com/docs/6348/108930) ### stopPushPublicStream ```cpp virtual int bytertc::IRTCVideo::stopPushPublicStream(const char* public_stream_id)=0 ``` 停止发布当前用户发布的公共流关于发布公共流，查看 [startPushPublicStream](#IRTCVideo-startpushpublicstream)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID
指定的流必须为当前用户所发布。 | **返回值** - 0: 成功 - !0: 失败 ### updatePublicStreamParam ```cpp virtual int bytertc::IRTCVideo::updatePublicStreamParam( const char* public_stream_id, IPublicStreamParam* param )=0 ``` 更新公共流参数关于发布公共流，查看 [startPushPublicStream](#IRTCVideo-startpushpublicstream)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | | param | IPublicStreamParam * | 公共流参数。详见 [IPublicStreamParam](85519#IPublicStreamParam)。
指定的流必须为当前用户所发布的。 | **返回值** - 0: 成功 - !0: 失败 **注意** 调用本接口前需要通过 [onPushPublicStreamResult](85517#IRTCVideoEventHandler-onpushpublicstreamresult) 确认公共流是否已经成功启动。 ### enableAudioPropertiesReport ```cpp virtual int bytertc::IRTCVideo::enableAudioPropertiesReport(const AudioPropertiesConfig &config)=0 ``` 启用音频信息提示。开启提示后，你会收到 [onLocalAudioPropertiesReport](85517#IRTCVideoEventHandler-onlocalaudiopropertiesreport)， [onRemoteAudioPropertiesReport](85517#IRTCVideoEventHandler-onremoteaudiopropertiesreport) 和 [onActiveSpeaker](85517#IRTCVideoEventHandler-onactivespeaker)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | config | const AudioPropertiesConfig & | 详见 [AudioPropertiesConfig](85519#AudioPropertiesConfig) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### setRemoteAudioPlaybackVolume ```cpp virtual int bytertc::IRTCVideo::setRemoteAudioPlaybackVolume( const char* room_id, const char* user_id, int volume )=0 ``` 调节来自指定远端用户的音频播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | room_id | const char * | 音频来源用户所在的房间 ID | | user_id | const char * | 音频来源的远端用户 ID | | volume | int | 音频播放音量值和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。为保证更好的通话质量，建议将 volume 值设为 [0,100]。
只改变音频数据的音量信息，不涉及本端硬件的音量调节。

0: 静音
100: 原始音量，默认值
400: 最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内， - 该方法与 [setRemoteRoomAudioPlaybackVolume](#IRTCRoom-setremoteroomaudioplaybackvolume) 互斥，最新调用的任一方法设置的音量将覆盖此前已设置的音量，效果不叠加； - 当该方法与 [setPlaybackVolume](#IRTCVideo-setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 ### enableVocalInstrumentBalance ```cpp virtual int bytertc::IRTCVideo::enableVocalInstrumentBalance(bool enable)=0 ``` 开启/关闭音量均衡功能。开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 [setAudioMixingLoudness](#IAudioMixingManager-setaudiomixingloudness) 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。（Linux 不支持） **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool | 是否开启音量均衡功能：

true: 是
false: 否

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 该接口须在调用 [startAudioMixing](#IAudioMixingManager-startaudiomixing) 开始播放音频文件之前调用。 ### enablePlaybackDucking ```cpp virtual int bytertc::IRTCVideo::enablePlaybackDucking(bool enable)=0 ``` 打开/关闭音量闪避功能，适用于在 RTC 通话过程中会同时播放短视频或音乐的场景，如“一起看”、“在线 KTV”等。开启该功能后，当检测到远端人声时，RTC 的本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，RTC 的本地媒体音量会恢复到闪避前的音量水平。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool | 是否开启音量闪避：

true: 是
false: 否

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### registerLocalEncodedVideoFrameObserver ```cpp virtual int bytertc::IRTCVideo::registerLocalEncodedVideoFrameObserver(ILocalEncodedVideoFrameObserver* observer)=0 ``` 注册本地视频帧监测器。无论使用内部采集还是自定义采集，调用该方法后，SDK 每监测到一帧本地视频帧时，都会将视频帧信息通过 [onLocalEncodedVideoFrame](85517#ILocalEncodedVideoFrameObserver-onlocalencodedvideoframe) 回调给用户 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | ILocalEncodedVideoFrameObserver * | 本地视频帧监测器，参看 [ILocalEncodedVideoFrameObserver](85517#ILocalEncodedVideoFrameObserver)。将参数设置为 nullptr 则取消注册。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 该方法可在进房前后的任意时间调用，在进房前调用可保证尽可能早地监测视频帧并触发回调 ### registerRemoteEncodedVideoFrameObserver ```cpp virtual int bytertc::IRTCVideo::registerRemoteEncodedVideoFrameObserver(IRemoteEncodedVideoFrameObserver* observer)=0 ``` 注册远端待解码视频帧回调。完成注册后，当 SDK 监测到远端编码后视频帧时，会触发 [onRemoteEncodedVideoFrame](85517#IRemoteEncodedVideoFrameObserver-onremoteencodedvideoframe) 回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IRemoteEncodedVideoFrameObserver * | 远端编码后视频数据监测器，参看 [IRemoteEncodedVideoFrameObserver](85517#IRemoteEncodedVideoFrameObserver) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 更多自定义解码功能说明参看 [自定义视频编解码](https://www.volcengine.com/docs/6348/82921#%E8%87%AA%E5%AE%9A%E4%B9%89%E8%A7%86%E9%A2%91%E8%A7%A3%E7%A0%81)。 - 该方法适用于手动订阅，并且进房前后均可调用，建议在进房前调用。 - 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。 ### setExternalVideoEncoderEventHandler ```cpp virtual int bytertc::IRTCVideo::setExternalVideoEncoderEventHandler(IExternalVideoEncoderEventHandler* encoder_handler)=0 ``` 注册自定义编码帧推送事件回调 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | encoder_handler | IExternalVideoEncoderEventHandler * | 自定义编码帧回调类，参看 [IExternalVideoEncoderEventHandler](85517#IExternalVideoEncoderEventHandler) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法需在进房前调用。 - 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。 ### pushExternalEncodedVideoFrame ```cpp virtual int bytertc::IRTCVideo::pushExternalEncodedVideoFrame( StreamIndex index, int video_index, IEncodedVideoFrame* video_stream )=0 ``` 推送自定义编码后的视频流 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 需要推送的编码流的属性，参看 [StreamIndex](85519#StreamIndex) | | video_index | int | 对应的编码流下标，从 0 开始，如果调用 [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig) 设置了多路流，此处数量须与之保持一致 | | video_stream | IEncodedVideoFrame * | 编码流视频帧信息，参看 [IEncodedVideoFrame](85519#IEncodedVideoFrame)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 目前仅支持推送 H264 和 ByteVC1 格式的视频帧，且视频流协议格式须为 Annex B 格式。 - 该函数运行在用户调用线程内 - 推送自定义编码视频帧前，必须调用 [setVideoSourceType](#IRTCVideo-setvideosourcetype) 将视频输入源切换至自定义编码视频源。 ### setVideoDecoderConfig ```cpp virtual int bytertc::IRTCVideo::setVideoDecoderConfig( RemoteStreamKey key, VideoDecoderConfig config )=0 ``` 在订阅远端视频流之前，设置远端视频数据解码方式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | key | RemoteStreamKey | 远端流信息，即对哪一路视频流进行解码方式设置，参看 [RemoteStreamKey](85519#RemoteStreamKey)。 | | config | VideoDecoderConfig | 视频解码方式，参看 [VideoDecoderConfig](85519#VideoDecoderConfig)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 当你想要对远端流进行自定义解码时，你需要先调用 [registerRemoteEncodedVideoFrameObserver](#IRTCVideo-registerremoteencodedvideoframeobserver) 注册远端视频流监测器，然后再调用该接口将解码方式设置为自定义解码。监测到的视频数据会通过 [onRemoteEncodedVideoFrame](85517#IRemoteEncodedVideoFrameObserver-onremoteencodedvideoframe) 回调出来。 - 自 3.56 起，要用于自动订阅场景下，你可以设置 `key` 中的 `RoomId` 和 `UserId` 为 `nullptr`，此时，通过此接口设置的解码方式根据 `key` 中的 `StreamIndex` 值，适用于所有的远端主流或屏幕流的解码方式。 ### requestRemoteVideoKeyFrame ```cpp virtual int bytertc::IRTCVideo::requestRemoteVideoKeyFrame(const RemoteStreamKey &stream_info)=0 ``` 在订阅远端视频流之后，向远端请求关键帧 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_info | const RemoteStreamKey & | 远端流信息，参看 [RemoteStreamKey](85519#RemoteStreamKey)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法仅适用于手动订阅模式，并且在成功订阅远端流之后使用。 - 该方法适用于调用 [setVideoDecoderConfig](#IRTCVideo-setvideodecoderconfig) 开启自定义解码功能后，并且自定义解码失败的情况下使用 ### sendStreamSyncInfo ```cpp virtual int bytertc::IRTCVideo::sendStreamSyncInfo( const uint8_t* data, int32_t length, const StreamSycnInfoConfig &config )=0 ``` 发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步，该接口调用成功后，远端用户会收到 [onStreamSyncInfoReceived](85517#IRTCVideoEventHandler-onstreamsyncinforeceived) 回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | data | const uint8_t * | 消息内容。 | | length | int32_t | 消息长度。取值范围是 [1,255] 字节，建议小于 16 字节，否则可能占用较大带宽。 | | config | const StreamSycnInfoConfig & | 媒体流信息同步的相关配置，详见 [StreamSycnInfoConfig](85519#StreamSycnInfoConfig) 。 | **返回值** - \>=0: 消息发送成功。返回成功发送的次数。 - -1: 消息发送失败。消息长度大于 255 字节。 - -2: 消息发送失败。传入的消息内容为空。 - -3: 消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。 - -4: 消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 [ErrorCode](85518#ErrorCode)。 **注意** - 调用本接口的频率建议不超过 50 次每秒。 - 在 `kRoomProfileTypeInteractivePodcast` 房间模式下，此消息一定会送达。在其他房间模式下，如果本地用户未说话，此消息不一定会送达。 ### setLocalVoicePitch ```cpp virtual int bytertc::IRTCVideo::setLocalVoicePitch(int pitch)=0 ``` 开启本地语音变调功能，多用于 K 歌场景。使用该方法，你可以对本地语音的音调进行升调或降调等调整。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | pitch | int | 相对于语音原始音调的升高/降低值，取值范围[-12，12]，默认值为 0，即不做调整。
取值范围内每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调，设置的绝对值越大表示音调升高或降低越多。
超出取值范围则设置失败，并且会触发 [onWarning](85517#IRTCVideoEventHandler-onwarning) 回调，提示 [WarningCode](85518#WarningCode) 错误码为 `WARNING_CODE_SET_SCREEN_STREAM_INVALID_VOICE_PITCH` 设置语音音调不合法 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### startPlayPublicStream ```cpp virtual int bytertc::IRTCVideo::startPlayPublicStream(const char* public_stream_id)=0 ``` 订阅指定公共流无论用户是否在房间内，都可以调用本接口获取和播放指定的公共流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID，如果指定流暂未发布，则本地客户端将在其开始发布后接收到流数据。 | **返回值** - 0: 成功。同时将收到 [onPlayPublicStreamResult](85517#IRTCVideoEventHandler-onplaypublicstreamresult) 回调。 - !0: 失败。当参数不合法或参数为空，调用失败。 **注意** - 一个客户端最多同时播放 5 路公共流，请及时调用 [stopPlayPublicStream](#IRTCVideo-stopplaypublicstream) 取消订阅公共流，避免订阅的公共流数量超限。 - 在调用本接口之前，建议先绑定渲染视图。 - 调用 [setPublicStreamVideoCanvas](#IRTCVideo-setpublicstreamvideocanvas) 绑定内部渲染视图： - 调用 [setPublicStreamVideoSink](#IRTCVideo-setpublicstreamvideosink) 绑定自定义渲染视图： - 调用本接口后，可以通过 [onFirstPublicStreamVideoFrameDecoded](85517#IRTCVideoEventHandler-onfirstpublicstreamvideoframedecoded) 和 [onFirstPublicStreamAudioFrame](85517#IRTCVideoEventHandler-onfirstpublicstreamaudioframe) 回调公共流的视频和音频首帧解码情况。 - 调用本接口后，可以通过 [onPublicStreamSEIMessageReceived](85517#IRTCVideoEventHandler-onpublicstreamseimessagereceived) 回调公共流中包含的 SEI 信息。 - 订阅公共流之后，可以通过调用 [stopPlayPublicStream](#IRTCVideo-stopplaypublicstream) 接口取消订阅公共流。 ### stopPlayPublicStream ```cpp virtual int bytertc::IRTCVideo::stopPlayPublicStream(const char* public_stream_id)=0 ``` 取消订阅指定公共流关于订阅公共流，查看 [startPlayPublicStream](#IRTCVideo-startplaypublicstream)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | **返回值** - 0：成功 - !0：失败 ### setPublicStreamVideoCanvas ```cpp virtual int bytertc::IRTCVideo::setPublicStreamVideoCanvas( const char* public_stream_id, const VideoCanvas &canvas )=0 ``` 为指定公共流绑定内部渲染视图。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | | canvas | const VideoCanvas & | 内部渲染视图，如果需要解除视频的绑定视图，把 videoCanvas 设置为空。详见 [VideoCanvas](85519#VideoCanvas)。 | **返回值** - 0：成功 - !0：失败 ### setPublicStreamVideoSink ```cpp virtual int bytertc::IRTCVideo::setPublicStreamVideoSink( const char* public_stream_id, IVideoSink* video_sink, IVideoSink::PixelFormat format )=0 ``` 为指定公共流绑定自定义渲染器。详见[自定义视频渲染](https://www.volcengine.com/docs/6348/81201)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | | video_sink | IVideoSink * | 自定义视频渲染器，自定义视频渲染器，需要释放渲染器资源时，将 videoSink 设置为 `null`。参看 [IVideoSink](85519#IVideoSink) | | format | IVideoSink::PixelFormat | videoSink 适用的视频帧编码格式，参看 [PixelFormat](85519#PixelFormat) | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 ### setPublicStreamAudioPlaybackVolume ```cpp virtual int bytertc::IRTCVideo::setPublicStreamAudioPlaybackVolume( const char* public_stream_id, int volume )=0 ``` > Available since 3.51 调节公共流的音频播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | public_stream_id | const char * | 公共流 ID | | volume | int | 音频播放音量值和原始音量值的比值，该比值的范围是 `[0, 400]`，单位为 %，且自带溢出保护。为保证更好的音频质量，建议设定在 `[0, 100]` 之间，其中 100 为系统默认值。 | **返回值** - 0: 成功调用。 - -2: 参数错误。 ### setVideoWatermark ```cpp virtual int bytertc::IRTCVideo::setVideoWatermark( StreamIndex stream_index, const char* image_path, RTCWatermarkConfig config )=0 ``` 在指定视频流上添加水印。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_index | StreamIndex | 需要添加水印的视频流属性，参看 [StreamIndex](85519#StreamIndex)。 | | image_path | const char * | 水印图片路径，仅支持本地文件绝对路径，长度限制为 512 字节。
水印图片为 PNG 或 JPG 格式。 | | config | RTCWatermarkConfig | 水印参数，参看 [RTCWatermarkConfig](85519#RTCWatermarkConfig)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [clearVideoWatermark](#IRTCVideo-clearvideowatermark) 移除指定视频流的水印。 - 同一路流只能设置一个水印，新设置的水印会代替上一次的设置。你可以多次调用本方法来设置不同流的水印。 - 若开启本地预览镜像，或开启本地预览和编码传输镜像，则远端水印均不镜像；在开启本地预览水印时，本端水印会镜像。 - 开启大小流后，水印对大小流均生效，且针对小流进行等比例缩小。 ### clearVideoWatermark ```cpp virtual int bytertc::IRTCVideo::clearVideoWatermark(StreamIndex stream_index)=0 ``` 移除指定视频流的水印。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_index | StreamIndex | 需要移除水印的视频流属性，参看 [StreamIndex](85519#StreamIndex)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### setDummyCaptureImagePath ```cpp virtual int bytertc::IRTCVideo::setDummyCaptureImagePath(const char* file_path)=0 ``` 摄像头处于关闭状态时，使用静态图片填充本地推送的视频流。调用 `stopVideoCapture` 接口时，会开始推静态图片。若要停止发送图片，可传入空字符串或启用内部摄像头采集。可重复调用该接口来更新图片。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | file_path | const char * | 设置静态图片的路径。
支持本地文件绝对路径，不支持网络链接，长度限制为 512 字节。
静态图片支持类型为 JPEG/JPG、PNG、BMP。
若图片宽高比与设置的编码宽高比不一致，图片会按编码高宽等比缩放，并裁剪长边。推流帧率与码率与设置的编码参数一致。 | **返回值** - 0: 成功。 - -2: 失败。确保传入的 file_path 为有效路径。 - -12: 本方法不支持在 Audio SDK 中使用。 **注意** - 该接口只适用于 SDK 内部摄像头采集，不适用于自定义视频采集。 - 本地预览无法看到静态图片。 - 进入房间前后均可调用此方法。在多房间场景中，静态图片仅在发布的房间中生效。 - 针对该静态图片，滤镜和镜像效果不生效，水印效果生效。 - 只有主流能设置静态图片，屏幕流不支持设置。 - 开启大小流后，静态图片对大小流均生效，且针对小流进行等比例缩小。 ### startCloudProxy ```cpp virtual int bytertc::IRTCVideo::startCloudProxy(const CloudProxyConfiguration &configuration)=0 ``` 开启云代理 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | configuration | const CloudProxyConfiguration & | 云代理服务器信息列表。参看 [CloudProxyConfiguration](85519#CloudProxyConfiguration)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 在加入房间前调用此接口 - 在开启云代理后，进行通话前网络探测 - 开启云代理后，并成功链接云代理服务器后，会收到 [onCloudProxyConnected](85517#IRTCVideoEventHandler-oncloudproxyconnected)。 - 要关闭云代理，调用 [stopCloudProxy](#IRTCVideo-stopcloudproxy)。 ### stopCloudProxy ```cpp virtual int bytertc::IRTCVideo::stopCloudProxy()=0 ``` 关闭云代理 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 要开启云代理，调用 [startCloudProxy](#IRTCVideo-startcloudproxy)。 ### setLocalProxy ```cpp virtual int bytertc::IRTCVideo::setLocalProxy( const LocalProxyConfiguration* configurations, int configuration_num )=0 ``` 设置本地代理。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | configurations | const LocalProxyConfiguration * | 本地代理配置参数。参看 [LocalProxyConfiguration](85519#LocalProxyConfiguration)。
你可以根据自己的需要选择同时设置 Http 隧道和 Socks5 两类代理，或者单独设置其中一类代理。如果你同时设置了 Http 隧道和 Socks5 两类代理，此时，媒体和信令采用 Socks5 代理， Http 请求采用 Http 隧道代理；如果只设置 Http 隧道或 Socks5 一类代理，媒体、信令和 Http 请求均采用已设置的代理。
调用此接口设置本地代理后，若想清空当前已有的代理设置，可再次调用此接口，选择不设置任何代理即可清空。 | | configuration_num | int | 本地代理配置参数的数量。 | **注意** - 该方法需要在进房前调用。 - 调用该方法设置本地代理后，SDK 会触发 [onLocalProxyStateChanged](85517#IRTCVideoEventHandler-onlocalproxystatechanged)，返回代理连接的状态。 ### setLowLightAdjusted ```cpp virtual int bytertc::IRTCVideo::setLowLightAdjusted(VideoEnhancementMode mode)=0 ``` > Available since 3.57 设置视频暗光增强模式。对于光线不足、照明不均匀或背光等场景下推荐开启，可有效改善画面质量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | VideoEnhancementMode | 默认不开启。参看 [VideoEnhancementMode](85519#VideoEnhancementMode)。 | **返回值** - 0: API 调用成功。会立即生效，但需要等待下载和检测完成后才能看到增强后的效果。 - < 0: API 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 开启后会影响设备性能，应根据实际需求和设备性能决定是否开启。 - 对 RTC SDK 内部采集的视频和自定义采集的视频都生效。 ### setVideoEncoderConfig ```cpp virtual int bytertc::IRTCVideo::setVideoEncoderConfig( StreamIndex index, const VideoSolution* solutions, int solution_num )=0 ``` > Deprecated since 3.36 and will be deleted in 3.51, use [setVideoEncoderConfig](#IRTCVideo-setvideoencoderconfig-2) instead. 设置推送多路流时的各路视频参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 视频流属性，参看 [StreamIndex](85519#StreamIndex)。 | | solutions | const VideoSolution * | 要推送的多路视频流参数，参看 [VideoSolution](85519#VideoSolution)。
最大分辨率为 4096px × 4096px，超过或设置的分辨率无法编码时，会导致编码推流失败。 | | solution_num | int | 视频参数数组长度。
最多支持 4 路参数。当设置了多路参数时，分辨率必须是从大到小排列。 | **返回值** - 0：成功 - !0：失败 **注意** - 该接口已废弃，请使用同名新接口代替；若仍需使用该旧接口，请注意无需先调用 `enableSimulcastMode` 开启推送多路流模式。 - 当使用内部采集时，视频采集的分辨率、帧率会根据最大的编码分辨率、帧率进行适配 - 默认的视频编码参数为：分辨率 640px × 360px，帧率 15fps。 - 变更编码分辨率后马上生效，可能会引发相机重启。 - 屏幕流只取视频参数数组的第一组数据。 ### updateRemoteStreamVideoCanvas ```cpp virtual int bytertc::IRTCVideo::updateRemoteStreamVideoCanvas( RemoteStreamKey stream_key, const enum RenderMode render_mode, const uint32_t background_color )=0 ``` > Deprecated since 3.56 on iOS and Android, and will be deleted in 3.62. 修改远端视频帧的渲染设置，包括渲染模式和背景颜色。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_key | RemoteStreamKey | 远端流信息。参看 [RemoteStreamKey](85519#RemoteStreamKey)。 | | render_mode | const enum RenderMode | 渲染模式，参看 [RenderMode](85519#RenderMode)。 | | background_color | const uint32_t | 背景颜色，参看 [VideoCanvas](85519#VideoCanvas).background_color | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 你可以在远端视频渲染过程中，调用此接口。调用结果会实时生效。 ### setLocalVideoSink ```cpp virtual int bytertc::IRTCVideo::setLocalVideoSink( StreamIndex index, IVideoSink* video_sink, IVideoSink::PixelFormat required_format )=0 ``` 将本地视频流与自定义渲染器绑定。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | StreamIndex | 视频流属性。采集的视频流/屏幕视频流，参看 [StreamIndex](85519#StreamIndex) | | video_sink | IVideoSink * | 自定义视频渲染器，参看 [IVideoSink](85519#IVideoSink)。 | | required_format | IVideoSink::PixelFormat | video_sink 适用的视频帧编码格式，参看 [PixelFormat](85519#PixelFormat) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。 - 如果需要解除绑定，必须将 video_sink 设置为 null。退房时将清除绑定状态。 - 一般在收到 [onFirstLocalVideoFrameCaptured](85517#IRTCVideoEventHandler-onfirstlocalvideoframecaptured) 回调通知完成本地视频首帧采集后，调用此方法为视频流绑定自定义渲染器；然后加入房间。 - 本方法获取的是前处理后的视频帧。 ### setRemoteVideoSink ```cpp virtual int bytertc::IRTCVideo::setRemoteVideoSink( RemoteStreamKey stream_key, IVideoSink* video_sink, IVideoSink::PixelFormat required_format )=0 ``` 将远端视频流与自定义渲染器绑定。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_key | RemoteStreamKey | 远端流信息，用于指定需要渲染的视频流来源及属性，参看 [RemoteStreamKey](85519#RemoteStreamKey)。 | | video_sink | IVideoSink * | 自定义视频渲染器，参看 [IVideoSink](85519#IVideoSink)。 | | required_format | IVideoSink::PixelFormat | video_sink 适用的视频帧编码格式，参看 [PixelFormat](85519#PixelFormat)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - RTC SDK 默认使用 RTC SDK 自带的渲染器（内部渲染器）进行视频渲染。 - 该方法进房前后均可以调用。若想在进房前调用，你需要在加入房间前获取远端流信息；若无法预先获取远端流信息，你可以在加入房间并通过 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream) 回调获取到远端流信息之后，再调用该方法。 - 如果需要解除绑定，必须将 video_sink 设置为 null。退房时将清除绑定状态。 - 本方法获取的是后处理后的视频帧。 ### sendSEIMessage ```cpp virtual int bytertc::IRTCVideo::sendSEIMessage( StreamIndex stream_index, const uint8_t* message, int length, int repeat_count )=0 ``` > Deprecated since 3.50 and will be deleted in 3.55, use [sendSEIMessage](#IRTCVideo-sendseimessage-2) instead. 通过视频帧发送 SEI 数据。在视频通话场景下，SEI 数据会随视频帧发送；在语音通话场景下，SDK 会自动生成一路 16px × 16px 的黑帧视频流用来发送 SEI 数据。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | stream_index | StreamIndex | 指定携带 SEI 数据的媒体流类型，参看 [StreamIndex](85519#StreamIndex)。
语音通话场景下，该值需设为 `kStreamIndexMain`，否则 SEI 数据会被丢弃从而无法送达远端。 | | message | const uint8_t * | SEI 消息。 | | length | int | SEI 消息长度，不超过 4KB。 | | repeat_count | int | 消息发送重复次数。取值范围是 [0, 30]。
调用此接口后，SEI 数据会添加到从当前视频帧开始的连续 `repeat_count+1` 个视频帧中。 | **返回值** - \>=0: 将被添加到视频帧中的 SEI 的数量 - <0: 发送失败 **注意** - 语音通话场景中，仅支持在内部采集模式下调用该接口发送 SEI 数据，且调用频率需为 15/repeat_count FPS。 - 视频帧仅携带前后 2s 内收到的 SEI 数据；语音通话场景下，若调用此接口后 1min 内未有 SEI 数据发送，则 SDK 会自动取消发布视频黑帧。 - 消息发送成功后，远端会收到 [onSEIMessageReceived](85517#IRTCVideoEventHandler-onseimessagereceived) 回调。 - 语音通话切换至视频通话时，会停止使用黑帧发送 SEI 数据，自动转为用采集到的正常视频帧发送 SEI 数据。 ### getAudioMixingManager ```cpp virtual IAudioMixingManager * bytertc::IRTCVideo::getAudioMixingManager()=0 ``` > Deprecated since 353.1, will be deleted in 359, use [getAudioEffectPlayer](#IRTCVideo-getaudioeffectplayer) or [getMediaPlayer](#IRTCVideo-getmediaplayer) instead 混音管理接口创建 **返回值** 混音管理实例，详见 [IAudioMixingManager](#IAudioMixingManager) ### muteAudioPlayback ```cpp virtual int bytertc::IRTCVideo::muteAudioPlayback(MuteState mute_state)=0 ``` > Deprecated since 3.45 and will be deleted in 3.51, use [setPlaybackVolume](#IRTCVideo-setplaybackvolume) instead. 控制本地音频流播放状态：播放/不播放 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute_state | MuteState | 播放状态，标识是否播放本地音频流，详见： [MuteState](85519#MuteState) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 本方法仅控制本地收到音频流的播放状态，并不影响本地音频播放设备。 # IAudioDeviceCollection ```cpp class bytertc::IAudioDeviceCollection ``` 音频设备相关的信息 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual int | [getCount](#IAudioDeviceCollection-getcount) | | virtual int | [getDevice](#IAudioDeviceCollection-getdevice) | | virtual void | [release](#IAudioDeviceCollection-release) | | virtual int | [getDevice](#IAudioDeviceCollection-getdevice-2) | ## 函数说明 ### getCount ```cpp virtual int bytertc::IAudioDeviceCollection::getCount() override ``` 获取当前系统内音频设备数量 **返回值** 音频设备数量 ### getDevice ```cpp virtual int bytertc::IAudioDeviceCollection::getDevice( int index, char device_name[MAX_DEVICE_ID_LENGTH], char device_id[MAX_DEVICE_ID_LENGTH] ) override ``` 根据索引号，获取设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 设备索引号，从 0 开始，注意需小于 [getCount](#IAudioDeviceCollection-getcount) 返回值。 | | device_name | char[MAX_DEVICE_ID_LENGTH] | 设备名称 | | device_id | char[MAX_DEVICE_ID_LENGTH] | 设备 ID | **返回值** - 0：方法调用成功，从已设定好的内容中成功读取设备信息。 - !0：方法调用失败 ### release ```cpp virtual void bytertc::IAudioDeviceCollection::release() override ``` 释放当前 [IAudioDeviceCollection](#IAudioDeviceCollection) 对象占用的资源。 **注意** 不需要返回音频设备相关信息列表时应该调用本方法释放相关资源。 ### getDevice ```cpp virtual int bytertc::IAudioDeviceCollection::getDevice( int index, AudioDeviceInfo* audio_device_info )=0 ``` 根据索引号，获取设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 设备索引号，从 0 开始，注意需小于 [getCount](#IAudioDeviceCollection-getcount) 返回值。 | | audio_device_info | AudioDeviceInfo * | 设备信息，详见 [AudioDeviceInfo](85519#AudioDeviceInfo) | **返回值** - 0：方法调用成功，从已设定好的内容中成功读取设备信息。 - !0：方法调用失败 # IScreenCaptureSourceList ```cpp class bytertc::IScreenCaptureSourceList ``` 屏幕共享对象信息列表共享对象相关数据将在调用 [release](#IScreenCaptureSourceList-release) 后被释放。 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual int32_t | [getCount](#IScreenCaptureSourceList-getcount) | | virtual ScreenCaptureSourceInfo | [getSourceInfo](#IScreenCaptureSourceList-getsourceinfo) | | virtual void | [release](#IScreenCaptureSourceList-release) | ## 函数说明 ### getCount ```cpp virtual int32_t bytertc::IScreenCaptureSourceList::getCount()=0 ``` 获取列表长度 **返回值** 可共享对象数量 ### getSourceInfo ```cpp virtual ScreenCaptureSourceInfo bytertc::IScreenCaptureSourceList::getSourceInfo(int32_t index)=0 ``` 根据索引号，获取屏幕共享列表中的元素 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int32_t | 列表索引号 | **返回值** 屏幕源类型信息，详见 [ScreenCaptureSourceInfo](85519#ScreenCaptureSourceInfo)。 ### release ```cpp virtual void bytertc::IScreenCaptureSourceList::release()=0 ``` [IScreenCaptureSourceList](#IScreenCaptureSourceList) 使用结束后，调用本接口删除对象，清空和释放内存。 # IVideoDeviceCollection ```cpp class bytertc::IVideoDeviceCollection ``` 视频设备相关的信息 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual int | [getCount](#IVideoDeviceCollection-getcount) | | virtual int | [getDevice](#IVideoDeviceCollection-getdevice) | | virtual void | [release](#IVideoDeviceCollection-release) | | virtual int | [getDevice](#IVideoDeviceCollection-getdevice-2) | ## 函数说明 ### getCount ```cpp virtual int bytertc::IVideoDeviceCollection::getCount() override ``` 获取当前系统内视频设备数量 **返回值** 视频设备数量 ### getDevice ```cpp virtual int bytertc::IVideoDeviceCollection::getDevice( int index, char device_name[MAX_DEVICE_ID_LENGTH], char device_id[MAX_DEVICE_ID_LENGTH] ) override ``` 根据索引号，获取设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 设备索引号，从 0 开始，注意需小于 [getCount](#IVideoDeviceCollection-getcount) 返回值。 | | device_name | char[MAX_DEVICE_ID_LENGTH] | 设备名称 | | device_id | char[MAX_DEVICE_ID_LENGTH] | 设备 ID | **返回值** - 0：方法调用成功，从已设定好的内容中成功读取设备信息。 - !0：方法调用失败 ### release ```cpp virtual void bytertc::IVideoDeviceCollection::release() override ``` 释放当前 [IVideoDeviceCollection](#IVideoDeviceCollection) 对象占用的资源。 **注意** 不需要返回视频设备相关信息列表时应该调用本方法释放相关资源。 ### getDevice ```cpp virtual int bytertc::IVideoDeviceCollection::getDevice( int index, VideoDeviceInfo* video_device_info )=0 ``` 根据索引号，获取设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 设备索引号，从 0 开始，注意需小于 [getCount](#IVideoDeviceCollection-getcount) 返回值。 | | video_device_info | VideoDeviceInfo * | 设备信息 | **返回值** - 0：方法调用成功，从已设定好的内容中成功读取设备信息。 - !0：方法调用失败 # IRTCRoom ```cpp class bytertc::IRTCRoom ``` 房间接口 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual void | [destroy](#IRTCRoom-destroy) | | virtual int | [setUserVisibility](#IRTCRoom-setuservisibility) | | virtual int | [setRTCRoomEventHandler](#IRTCRoom-setrtcroomeventhandler) | | virtual int | [joinRoom](#IRTCRoom-joinroom) | | virtual int | [leaveRoom](#IRTCRoom-leaveroom) | | virtual int | [updateToken](#IRTCRoom-updatetoken) | | virtual int64_t | [sendUserMessage](#IRTCRoom-sendusermessage) | | virtual int64_t | [sendUserBinaryMessage](#IRTCRoom-senduserbinarymessage) | | virtual int64_t | [sendRoomMessage](#IRTCRoom-sendroommessage) | | virtual int64_t | [sendRoomBinaryMessage](#IRTCRoom-sendroombinarymessage) | | virtual int | [publishStream](#IRTCRoom-publishstream) | | virtual int | [unpublishStream](#IRTCRoom-unpublishstream) | | virtual int | [publishScreen](#IRTCRoom-publishscreen) | | virtual int | [unpublishScreen](#IRTCRoom-unpublishscreen) | | virtual int | [setRemoteVideoConfig](#IRTCRoom-setremotevideoconfig) | | virtual int | [subscribeStream](#IRTCRoom-subscribestream) | | virtual int | [subscribeAllStreams](#IRTCRoom-subscribeallstreams) | | virtual int | [unsubscribeStream](#IRTCRoom-unsubscribestream) | | virtual int | [unsubscribeAllStreams](#IRTCRoom-unsubscribeallstreams) | | virtual int | [subscribeScreen](#IRTCRoom-subscribescreen) | | virtual int | [unsubscribeScreen](#IRTCRoom-unsubscribescreen) | | virtual int | [pauseAllSubscribedStream](#IRTCRoom-pauseallsubscribedstream) | | virtual int | [resumeAllSubscribedStream](#IRTCRoom-resumeallsubscribedstream) | | virtual int | [setMultiDeviceAVSync](#IRTCRoom-setmultideviceavsync) | | virtual int | [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms) | | virtual int | [updateForwardStreamToRooms](#IRTCRoom-updateforwardstreamtorooms) | | virtual int | [stopForwardStreamToRooms](#IRTCRoom-stopforwardstreamtorooms) | | virtual int | [pauseForwardStreamToAllRooms](#IRTCRoom-pauseforwardstreamtoallrooms) | | virtual int | [resumeForwardStreamToAllRooms](#IRTCRoom-resumeforwardstreamtoallrooms) | | virtual int | [setRemoteRoomAudioPlaybackVolume](#IRTCRoom-setremoteroomaudioplaybackvolume) | | virtual int | [setAudioSelectionConfig](#IRTCRoom-setaudioselectionconfig) | | virtual int64_t | [setRoomExtraInfo](#IRTCRoom-setroomextrainfo) | | virtual int | [startSubtitle](#IRTCRoom-startsubtitle) | | virtual int | [stopSubtitle](#IRTCRoom-stopsubtitle) | | virtual const char * | [getRoomId](#IRTCRoom-getroomid) | | virtual int | [deprecated] [subscribeUserStream](#IRTCRoom-subscribeuserstream) | ## 函数说明 ### destroy ```cpp virtual void bytertc::IRTCRoom::destroy()=0 ``` 退出并销毁调用 [createRTCRoom](#IRTCVideo-creatertcroom) 所创建的房间实例。 ### setUserVisibility ```cpp virtual int bytertc::IRTCRoom::setUserVisibility(bool enable)=0 ``` 设置用户可见性。未调用该接口前，本地用户默认对他人可见。默认情况下，一个 RTC 房间最多同时容纳 50 名可见用户，最多 30 人可同时上麦。更多信息参看[用户和媒体流上限](https://www.volcengine.com/docs/6348/257549)。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool | 设置用户是否对房间内其他用户可见：

true: 可见，用户可以在房间内发布音视频流，房间中的其他用户将收到用户的行为通知，例如进房、开启视频采集和退房。
false: 不可见，用户不可以在房间内发布音视频流，房间中的其他用户不会收到用户的行为通知，例如进房、开启视频采集和退房。

| **返回值** - 0: 调用成功。 - < 0: 调用失败。参看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 在加入房间前后，用户均可调用此方法设置用户可见性。 - 设置用户可见性，会收到设置成功/失败回调 [onUserVisibilityChanged](85517#IRTCRoomEventHandler-onuservisibilitychanged)。（v3.54 新增） • 在加入房间前设置用户可见性，若设置的可见性与默认值不同，将在加入房间时触发本回调。 • 在加入房间后设置用户可见性，若可见性前后不同，会触发本回调。 • 在断网重连后，若可见性发生改变，会触发本回调。 - 在房间内，调用此方法成功切换用户可见性后，房间内其他用户会收到相应的回调。 • 从可见换至不可见时，房间内其他用户会收到 [onUserLeave](85517#IRTCRoomEventHandler-onuserleave)。 • 从不可见切换至可见时，房间内其他用户会收到 [onUserJoined](85517#IRTCRoomEventHandler-onuserjoined)。 • 若调用该方法将可见性设为 `false`，此时尝试发布流会收到 `kWarningCodePublishStreamForbiden` 警告。 ### setRTCRoomEventHandler ```cpp virtual int bytertc::IRTCRoom::setRTCRoomEventHandler(IRTCRoomEventHandler* room_event_handler)=0 ``` 通过设置 [IRTCRoom](#IRTCRoom) 对象的事件句柄，监听此对象对应的回调事件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | room_event_handler | IRTCRoomEventHandler * | 参见 [IRTCRoomEventHandler](85517#IRTCRoomEventHandler) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### joinRoom ```cpp virtual int bytertc::IRTCRoom::joinRoom( const char* token, const UserInfo &user_info, const RTCRoomConfig &config )=0 ``` 加入房间。调用 [createRTCRoom](#IRTCVideo-creatertcroom) 创建房间后，调用此方法加入房间，同房间内其他用户进行音视频通话。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | const char * | 动态密钥，用于对登录用户进行鉴权验证。
进入房间需要携带 Token。测试时可使用控制台生成临时 Token，正式上线需要使用密钥 SDK 在您的服务端生成并下发 Token。Token 有效期及生成方式参看[使用 Token 完成鉴权](70121)。

使用不同 App ID 的 App 是不能互通的。
请务必保证生成 Token 使用的 App ID 和创建引擎时使用的 App ID 相同，否则会导致加入房间失败。

| | user_info | const UserInfo & | 用户信息，参看 [UserInfo](85519#UserInfo)。 | | config | const RTCRoomConfig & | 房间参数配置，设置房间模式以及是否自动发布或订阅流。具体配置模式参看 [RTCRoomConfig](85519#RTCRoomConfig)。 | **返回值** 方法调用结果。 - `0`: 调用成功。 - `-1`,`-2`,或 `-4`: 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得错误说明。 **注意** - 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 [onRoomStateChanged](85517#IRTCRoomEventHandler-onroomstatechanged) 回调通知，错误类型详见 [ErrorCode](85518#ErrorCode) 中的 kErrorCodeDuplicateLogin。 - 本地用户调用此方法加入房间成功后，会收到 [onRoomStateChanged](85517#IRTCRoomEventHandler-onroomstatechanged) 回调通知。若本地用户同时为可见用户，加入房间时远端用户会收到 [onUserJoined](85517#IRTCRoomEventHandler-onuserjoined) 回调通知。 - 房间内不可见用户的容量远远大于可见用户，而且用户默认可见，因此对于不参与互动的用户，你需要在其进房后调用 setUserVisibility(https://www.volcengine.com/docs/6348/257549)。用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，并触发 [onConnectionStateChanged](85517#IRTCVideoEventHandler-onconnectionstatechanged) 回调。此时 SDK 会自动重试，直到成功重连。重连成功后，本地会收到 [onRoomStateChanged](85517#IRTCRoomEventHandler-onroomstatechanged) 回调通知。 ### leaveRoom ```cpp virtual int bytertc::IRTCRoom::leaveRoom()=0 ``` 离开房间。调用此方法结束通话过程，并释放所有通话相关的资源。 **返回值** - 0: 调用成功。 - < 0: 调用失败，查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 加入房间后，必须调用此方法结束通话，否则无法开始下一次通话。 - 此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 [onLeaveRoom](85517#IRTCRoomEventHandler-onleaveroom) 回调通知。你必须在收到 [onLeaveRoom](85517#IRTCRoomEventHandler-onleaveroom) 回调后，再销毁房间或引擎，或调用 [joinRoom](#IRTCRoom-joinroom) 再次加入房间。 - 调用 [setUserVisibility](#IRTCRoom-setuservisibility) 将自身设为可见的用户离开房间后，房间内其他用户会收到 [onUserLeave](85517#IRTCRoomEventHandler-onuserleave) 回调通知。 ### updateToken ```cpp virtual int bytertc::IRTCRoom::updateToken(const char* token)=0 ``` 更新 Token。收到 [onTokenWillExpire](85517#IRTCRoomEventHandler-ontokenwillexpire)， [onPublishPrivilegeTokenWillExpire](85517#IRTCRoomEventHandler-onpublishprivilegetokenwillexpire)，或 [onSubscribePrivilegeTokenWillExpire](85517#IRTCRoomEventHandler-onsubscribeprivilegetokenwillexpire) 时，你必须重新获取 Token，并调用此方法更新 Token，以保证通话的正常进行。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | token | const char * | 重新获取的有效 Token。
如果 Token 无效，你会收到 [onRoomStateChanged](85517#IRTCRoomEventHandler-onroomstatechanged)，错误码是 `-1010`。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 3.50（不含）以前的版本中，Token 中的发布和订阅权限为保留参数，无实际控制权限；3.50 及以后版本开放 Token 发布订阅控制权限，如需通过 Token 控制连麦权限，请联系技术支持团队开通白名单后支持。 - 请勿同时调用 [updateToken](#IRTCRoom-updatetoken) 和 [joinRoom](#IRTCRoom-joinroom) 方法更新 Token。若因 Token 过期或无效导致加入房间失败或已被移出房间，你应该在获取新的有效 Token 后调用 [joinRoom](#IRTCRoom-joinroom) 重新加入房间。 ### sendUserMessage ```cpp virtual int64_t bytertc::IRTCRoom::sendUserMessage( const char* uid, const char* message, MessageConfig config=kMessageConfigReliableOrdered )=0 ``` 给房间内指定的用户发送点对点文本消息（P2P）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | const char * |
消息接收用户的 ID | | message | const char * |
发送的文本消息内容。
消息不超过 64 KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](85519#MessageConfig)。 | **返回值** 这次发送消息的编号，从 1 开始递增。 **注意** - 在发送房间内文本消息前，必须先调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 调用该函数后会收到一次 [onUserMessageSendResult](85517#IRTCRoomEventHandler-onusermessagesendresult) 回调，通知消息发送方发送成功或失败； - 若文本消息发送成功，则 uid 所指定的用户会收到 [onUserMessageReceived](85517#IRTCRoomEventHandler-onusermessagereceived) 回调。 ### sendUserBinaryMessage ```cpp virtual int64_t bytertc::IRTCRoom::sendUserBinaryMessage( const char* uid, int length, const uint8_t* message, MessageConfig config=kMessageConfigReliableOrdered )=0 ``` 给房间内指定的用户发送点对点二进制消息（P2P）。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | uid | const char * |
消息接收用户的 ID | | length | int |
二进制字符串的长度。 | | message | const uint8_t * |
二进制消息的内容。
消息不超过 46KB。 | | config | MessageConfig | 消息类型，参看 [MessageConfig](85519#MessageConfig)。 | **返回值** 这次发送消息的编号，从 1 开始递增。 **注意** - 在发送房间内二进制消息前，必须先调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 调用该函数后会收到一次 [onUserMessageSendResult](85517#IRTCRoomEventHandler-onusermessagesendresult) 回调，通知消息发送方发送成功或失败； - 若二进制消息发送成功，则 uid 所指定的用户会收到 [onUserBinaryMessageReceived](85517#IRTCRoomEventHandler-onuserbinarymessagereceived) 回调。 ### sendRoomMessage ```cpp virtual int64_t bytertc::IRTCRoom::sendRoomMessage(const char* message)=0 ``` 给房间内的所有其他用户群发文本消息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | message | const char * |
用户发送的广播消息
消息不超过 64 KB。 | **注意** - 在发送房间内二进制消息前，必须先调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 调用该函数后，会收到一次 [onRoomMessageSendResult](85517#IRTCRoomEventHandler-onroommessagesendresult) 回调。 - 同一房间内的其他用户会收到 [onRoomMessageReceived](85517#IRTCRoomEventHandler-onroommessagereceived) 回调。 ### sendRoomBinaryMessage ```cpp virtual int64_t bytertc::IRTCRoom::sendRoomBinaryMessage( int size, const uint8_t* message )=0 ``` 给房间内的所有其他用户群发二进制消息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | size | int |
发送的二进制消息长度 | | message | const uint8_t * |
用户发送的二进制广播消息
消息不超过 46KB。 | **返回值** 这次发送消息的编号，从 1 开始递增。 **注意** - 在发送房间内二进制消息前，必须先调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 调用该函数后，会收到一次 [onRoomMessageSendResult](85517#IRTCRoomEventHandler-onroommessagesendresult) 回调。 - 同一房间内的其他用户会收到 [onRoomBinaryMessageReceived](85517#IRTCRoomEventHandler-onroombinarymessagereceived) 回调。 ### publishStream ```cpp virtual int bytertc::IRTCRoom::publishStream(MediaStreamType type)=0 ``` 在当前所在房间内发布本地通过摄像头/麦克风采集的媒体流 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定发布音频/视频，参看 [MediaStreamType](85519#MediaStreamType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 如果你已经在用户进房时通过调用 [joinRoom](#IRTCRoom-joinroom) 成功选择了自动发布，则无需再调用本接口。 - 调用 [setUserVisibility](#IRTCRoom-setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布摄像头音视频流。 - 如果你需要发布屏幕共享流，调用 [publishScreen](#IRTCRoom-publishscreen)。(Linux 不适用) - 如果你需要向多个房间发布流，调用 [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms)。 - 调用此方法后，房间中的所有远端用户会收到 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream) 回调通知，其中成功收到了音频流的远端用户会收到 [onFirstRemoteAudioFrame](85517#IRTCVideoEventHandler-onfirstremoteaudioframe) 回调，订阅了视频流的远端用户会收到 [onFirstRemoteVideoFrameDecoded](85517#IRTCVideoEventHandler-onfirstremotevideoframedecoded) 回调。 - 调用 [unpublishStream](#IRTCRoom-unpublishstream) 取消发布。 ### unpublishStream ```cpp virtual int bytertc::IRTCRoom::unpublishStream(MediaStreamType type)=0 ``` 停止将本地摄像头/麦克风采集的媒体流发布到当前所在房间中 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定停止发布音频/视频，参看 [MediaStreamType](85519#MediaStreamType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [publishStream](#IRTCRoom-publishstream) 手动发布摄像头音视频流后，你需调用此接口停止发布。 - 调用此方法停止发布音视频流后，房间中的其他用户将会收到 [onUserUnpublishStream](85517#IRTCRoomEventHandler-onuserunpublishstream) 回调通知。 ### publishScreen ```cpp virtual int bytertc::IRTCRoom::publishScreen(MediaStreamType type)=0 ``` 在当前所在房间内手动发布本地屏幕共享音视频流。如果你需要手动向多个房间发布屏幕共享流，可以使用同样的 uid 加入多个房间，并在每个房间调用该方法。同时，你可以在不同的房间发布不同的屏幕共享流类型。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定发布屏幕音频/视频，参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 即使你已经在用户进房时通过调用 [joinRoom](#IRTCRoom-joinroom) 成功选择了自动发布，也需要调用本接口。 - 调用 [setUserVisibility](#IRTCRoom-setuservisibility) 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布屏幕流。 - 调用该方法后，房间中的所有远端用户会收到 [onUserPublishScreen](85517#IRTCRoomEventHandler-onuserpublishscreen) 回调，其中成功收到音频流的远端用户会收到 [onFirstRemoteAudioFrame](85517#IRTCVideoEventHandler-onfirstremoteaudioframe) 回调，订阅了视频流的远端用户会收到 [onFirstRemoteVideoFrameDecoded](85517#IRTCVideoEventHandler-onfirstremotevideoframedecoded) 回调。 - 调用该方法后，本地用户会收到 [onScreenVideoFrameSendStateChanged](85517#IRTCVideoEventHandler-onscreenvideoframesendstatechanged)。 - 调用 [unpublishScreen](#IRTCRoom-unpublishscreen) 取消发布。 - 对 Linux，仅支持发布视频流。 - 查看 [PC 端屏幕共享](https://www.volcengine.com/docs/6348/70144)，获取更多信息。 ### unpublishScreen ```cpp virtual int bytertc::IRTCRoom::unpublishScreen(MediaStreamType type)=0 ``` 停止将本地屏幕共享音视频流发布到当前所在房间中 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定停止发布屏幕音频/视频，参看 [MediaStreamType](85519#MediaStreamType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [publishScreen](#IRTCRoom-publishscreen) 发布屏幕流后，你需调用此接口停止发布。 - 调用此方法停止发布屏幕音视频流后，房间中的其他用户将会收到 [onUserUnpublishScreen](85517#IRTCRoomEventHandler-onuserunpublishscreen) 回调。 ### setRemoteVideoConfig ```cpp virtual int bytertc::IRTCRoom::setRemoteVideoConfig( const char* user_id, const RemoteVideoConfig &remote_video_config )=0 ``` 设置期望订阅的远端视频流的参数。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 期望配置订阅参数的远端视频流发布用户的 ID。 | | remote_video_config | const RemoteVideoConfig & | 期望配置的远端视频流参数，参看 [RemoteVideoConfig](85519#RemoteVideoConfig)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 若使用 342 及以前版本的 SDK，调用该方法前请联系技术支持人员开启按需订阅功能。 - 该方法仅在发布端调用 [enableSimulcastMode](#IRTCVideo-enablesimulcastmode) 开启了发送多路视频流的情况下生效，此时订阅端将收到来自发布端与期望设置的参数最相近的一路流；否则订阅端只会收到一路参数为分辨率 640px × 360px、帧率 15fps 的视频流。 - 若发布端开启了推送多路流功能，但订阅端不对流参数进行设置，则默认接受发送端设置的分辨率最大的一路视频流。 - 该方法需在进房后调用，若想进房前设置，你需调用 [joinRoom](#IRTCRoom-joinroom)，并对 `room_config` 中的 `remote_video_config` 进行设置。 - SDK 会根据发布端和所有订阅端的设置灵活调整视频流的参数，具体调整策略详见[推送多路流](https://www.volcengine.com/docs/6348/70139)文档。 ### subscribeStream ```cpp virtual int bytertc::IRTCRoom::subscribeStream( const char* user_id, MediaStreamType type )=0 ``` 订阅房间内指定的通过摄像头/麦克风采集的媒体流，或更新对指定远端用户的订阅选项 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 指定订阅的远端发布音视频流的用户 ID。 | | type | MediaStreamType | 媒体流类型，用于指定订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 若当前用户在调用本接口时已经订阅该远端用户（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 - 你必须先通过 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream) 回调获取当前房间里的远端摄像头音视频流信息，然后调用本方法按需订阅。 - 调用该方法后，你会收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 通知方法调用结果。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeStream](#IRTCRoom-unsubscribestream) 取消订阅或本端用户退房。 - 关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85518#ErrorCode)。 ### subscribeAllStreams ```cpp virtual int bytertc::IRTCRoom::subscribeAllStreams(MediaStreamType type)=0 ``` 订阅房间内所有通过摄像头/麦克风采集的媒体流，或更新订阅选项。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 多次调用订阅接口时，将根据末次调用接口和传入的参数，更新订阅配置。 - 开启音频选路后，如果房间内的媒体流超过上限，建议通过调用 [subscribeStream](#IRTCRoom-subscribestream) 逐一指定需要订阅的媒体流。 - 调用该方法后，你会收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 通知方法调用结果。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeStream](#IRTCRoom-unsubscribestream) 取消订阅或本端用户退房。 - 关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85518#ErrorCode)。 ### unsubscribeStream ```cpp virtual int bytertc::IRTCRoom::unsubscribeStream( const char* user_id, MediaStreamType type )=0 ``` 取消订阅房间内指定的通过摄像头/麦克风采集的媒体流。该方法对自动订阅和手动订阅模式均适用。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 指定取消订阅的远端发布音视频流的用户 ID。 | | type | MediaStreamType | 媒体流类型，用于指定取消订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** 方法调用结果： - 0：成功；如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85518#ErrorCode)。 ### unsubscribeAllStreams ```cpp virtual int bytertc::IRTCRoom::unsubscribeAllStreams(MediaStreamType type)=0 ``` 取消订阅房间内所有的通过摄像头/麦克风采集的媒体流。自动订阅和手动订阅的流都可以通过本方法取消订阅。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | MediaStreamType | 媒体流类型，用于指定取消订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** 方法调用结果： - 0：成功；如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85518#ErrorCode)。 ### subscribeScreen ```cpp virtual int bytertc::IRTCRoom::subscribeScreen( const char* user_id, MediaStreamType type )=0 ``` 订阅房间内指定的远端屏幕共享音视频流，或更新对指定远端用户的订阅选项 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 指定订阅的远端发布屏幕流的用户 ID。 | | type | MediaStreamType | 媒体流类型，用于指定订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** 方法调用结果： - 0：成功； - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。 **注意** - 若当前用户在调用本接口时已经订阅该远端用户（手动订阅或自动订阅），则将根据本次传入的参数，更新订阅配置。 - 你必须先通过 [onUserPublishScreen](85517#IRTCRoomEventHandler-onuserpublishscreen) 回调获取当前房间里的远端屏幕流信息，然后调用本方法按需订阅。 - 调用该方法后，你会收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 通知方法调用结果。 - 成功订阅远端用户的媒体流后，订阅关系将持续到调用 [unsubscribeScreen](#IRTCRoom-unsubscribescreen) 取消订阅或本端用户退房。 - 关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体异常原因参看 [ErrorCode](85518#ErrorCode)。 ### unsubscribeScreen ```cpp virtual int bytertc::IRTCRoom::unsubscribeScreen( const char* user_id, MediaStreamType type )=0 ``` 取消订阅房间内指定的远端屏幕共享音视频流。该方法对自动订阅和手动订阅模式均适用。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 指定取消订阅的远端发布屏幕流的用户 ID。 | | type | MediaStreamType | 媒体流类型，用于指定取消订阅音频/视频。参看 [MediaStreamType](85519#MediaStreamType)。 | **返回值** 方法调用结果： - 0：成功；如果此时本端用户仍订阅了该远端用户的其他媒体流，将会触发 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。否则不会收到此回调。比如，本端同时订阅了用户 A 的音频和视频流，通过本方法取消订阅 A 的视频流时，收到 [onStreamSubscribed](85517#IRTCRoomEventHandler-onstreamsubscribed) 回调。再次调用本方法，取消订阅 A 的音频流，则取消成功时不会收到该回调。 - <0：失败。具体失败原因参看 [ReturnStatus](85519#ReturnStatus)。关于其他调用异常，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85518#ErrorCode)。 ### pauseAllSubscribedStream ```cpp virtual int bytertc::IRTCRoom::pauseAllSubscribedStream(PauseResumeControlMediaType media_type)=0 ``` 暂停接收来自远端的媒体流。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | media_type | PauseResumeControlMediaType | 媒体流类型，指定需要暂停接收音频还是视频流，参看 [PauseResumeControlMediaType](85519#PauseResumeControlMediaType)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法仅暂停远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 - 若想恢复接收远端流，需调用 [resumeAllSubscribedStream](#IRTCRoom-resumeallsubscribedstream)。 - 多房间场景下，仅暂停接收发布在当前所在房间的流。 ### resumeAllSubscribedStream ```cpp virtual int bytertc::IRTCRoom::resumeAllSubscribedStream(PauseResumeControlMediaType media_type)=0 ``` 恢复接收来自远端的媒体流 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | media_type | PauseResumeControlMediaType | 媒体流类型，指定需要暂停接收音频还是视频流，参看 [PauseResumeControlMediaType](85519#PauseResumeControlMediaType) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 该方法仅恢复远端流的接收，并不影响远端流的采集和发送； - 该方法不改变用户的订阅状态以及订阅流的属性。 ### setMultiDeviceAVSync ```cpp virtual int bytertc::IRTCRoom::setMultiDeviceAVSync(const char* audio_user_id)=0 ``` 设置发流端音画同步。当同一用户同时使用两个通话设备分别采集发送音频和视频时，有可能会因两个设备所处的网络环境不一致而导致发布的流不同步，此时你可以在视频发送端调用该接口，SDK 会根据音频流的时间戳自动校准视频流，以保证接收端听到音频和看到视频在时间上的同步性。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_user_id | const char * | 音频发送端的用户 ID，将该参数设为空则可解除当前音视频的同步关系。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 该方法在进房前后均可调用。 - 进行音画同步的音频发布用户 ID 和视频发布用户 ID 须在同一个 RTC 房间内。 - 调用该接口后音画同步状态发生改变时，你会收到 [onAVSyncStateChange](85517#IRTCRoomEventHandler-onavsyncstatechange) 回调。 - 同一 RTC 房间内允许存在多个音视频同步关系，但需注意单个音频源不支持与多个视频源同时同步。 - 如需更换同步音频源，再次调用该接口传入新的 `audio_user_id` 即可；如需更换同步视频源，需先解除当前的同步关系，后在新视频源端开启同步。 ### startForwardStreamToRooms ```cpp virtual int bytertc::IRTCRoom::startForwardStreamToRooms(const ForwardStreamConfiguration &configuration)=0 ``` 开始跨房间转发媒体流。在调用 [joinRoom](#IRTCRoom-joinroom) 后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | configuration | const ForwardStreamConfiguration & | 跨房间媒体流转发指定房间的信息。参看 [ForwardStreamConfiguration](85519#ForwardStreamConfiguration)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 调用本方法后，将在本端触发 [onForwardStreamStateChanged](85517#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调。 - 调用本方法后，你可以通过监听 [onForwardStreamEvent](85517#IRTCRoomEventHandler-onforwardstreamevent) 回调来获取各个目标房间在转发媒体流过程中的相关事件。 - 开始转发后，目标房间中的用户将接收到本地用户进房 [onUserJoined](85517#IRTCRoomEventHandler-onuserjoined) 和发流 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream)/ [onUserPublishScreen](85517#IRTCRoomEventHandler-onuserpublishscreen) 的回调。 - 调用本方法后，可以调用 [updateForwardStreamToRooms](#IRTCRoom-updateforwardstreamtorooms) 更新目标房间信息，例如，增加或减少目标房间等。 - 调用本方法后，可以调用 [stopForwardStreamToRooms](#IRTCRoom-stopforwardstreamtorooms) 停止向所有房间转发媒体流。 - 调用本方法后，可以调用 [pauseForwardStreamToAllRooms](#IRTCRoom-pauseforwardstreamtoallrooms) 暂停向所有房间转发媒体流。 ### updateForwardStreamToRooms ```cpp virtual int bytertc::IRTCRoom::updateForwardStreamToRooms(const ForwardStreamConfiguration &configuration)=0 ``` 更新跨房间媒体流转发信息。通过 [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。调用本方法增加或删减房间后，将在本端触发 [onForwardStreamStateChanged](85517#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调，包含发生了变动的目标房间中媒体流转发状态。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | configuration | const ForwardStreamConfiguration & | 跨房间媒体流转发目标房间信息。参看 [ForwardStreamConfiguration](85519#ForwardStreamConfiguration)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 [onUserJoined](85517#IRTCRoomEventHandler-onuserjoined) 和发布 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream)/ [onUserPublishScreen](85517#IRTCRoomEventHandler-onuserpublishscreen) 的回调。 - 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85517#IRTCRoomEventHandler-onuserunpublishstream)/ [onUserUnpublishScreen](85517#IRTCRoomEventHandler-onuserunpublishscreen) 和退房 [onUserLeave](85517#IRTCRoomEventHandler-onuserleave) 的回调。 ### stopForwardStreamToRooms ```cpp virtual int bytertc::IRTCRoom::stopForwardStreamToRooms()=0 ``` 停止跨房间媒体流转发。通过 [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本方法后，将在本端触发 [onForwardStreamStateChanged](85517#IRTCRoomEventHandler-onforwardstreamstatechanged) 回调。 - 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85517#IRTCRoomEventHandler-onuserunpublishstream)/ [onUserUnpublishScreen](85517#IRTCRoomEventHandler-onuserunpublishscreen) 和退房 [onUserLeave](85517#IRTCRoomEventHandler-onuserleave) 的回调。 - 如果需要停止向指定的房间转发媒体流，请调用 [updateForwardStreamToRooms](#IRTCRoom-updateforwardstreamtorooms) 更新房间信息。 - 如果需要暂停转发，请调用 [pauseForwardStreamToAllRooms](#IRTCRoom-pauseforwardstreamtoallrooms)，并在之后随时调用 [resumeForwardStreamToAllRooms](#IRTCRoom-resumeforwardstreamtoallrooms) 快速恢复转发。 ### pauseForwardStreamToAllRooms ```cpp virtual int bytertc::IRTCRoom::pauseForwardStreamToAllRooms()=0 ``` 暂停跨房间媒体流转发。通过 [startForwardStreamToRooms](#IRTCRoom-startforwardstreamtorooms) 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。调用本方法暂停向所有目标房间转发后，你可以随时调用 [resumeForwardStreamToAllRooms](#IRTCRoom-resumeforwardstreamtoallrooms) 快速恢复转发。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用本方法后，目标房间中的用户将接收到本地用户停止发布 [onUserUnpublishStream](85517#IRTCRoomEventHandler-onuserunpublishstream)/ [onUserUnpublishScreen](85517#IRTCRoomEventHandler-onuserunpublishscreen) 和退房 [onUserLeave](85517#IRTCRoomEventHandler-onuserleave) 的回调。 ### resumeForwardStreamToAllRooms ```cpp virtual int bytertc::IRTCRoom::resumeForwardStreamToAllRooms()=0 ``` 恢复跨房间媒体流转发。调用 [pauseForwardStreamToAllRooms](#IRTCRoom-pauseforwardstreamtoallrooms) 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 目标房间中的用户将接收到本地用户进房 [onUserJoined](85517#IRTCRoomEventHandler-onuserjoined) 和发布 [onUserPublishStream](85517#IRTCRoomEventHandler-onuserpublishstream)/ [onUserPublishScreen](85517#IRTCRoomEventHandler-onuserpublishscreen) 的回调。 ### setRemoteRoomAudioPlaybackVolume ```cpp virtual int bytertc::IRTCRoom::setRemoteRoomAudioPlaybackVolume(int volume)=0 ``` 调节某个房间内所有远端用户的音频播放音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 音频播放音量值和原始音量的比值，范围是 [0, 400]，单位为 %，自带溢出保护。为保证更好的通话质量，建议将 volume 值设为 [0,100]。

0: 静音
100: 原始音量，默认值
400: 最大可为原始音量的 4 倍(自带溢出保护)

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 假设某远端用户 A 始终在被调节的目标用户范围内， - 该方法与 [setRemoteAudioPlaybackVolume](#IRTCVideo-setremoteaudioplaybackvolume) 互斥，最新调用的任一方法设置的音量将覆盖此前已设置的音量，效果不叠加； - 当该方法与 [setPlaybackVolume](#IRTCVideo-setplaybackvolume) 方法共同使用时，本地收听用户 A 的音量将为两次设置的音量效果的叠加。 ### setAudioSelectionConfig ```cpp virtual int bytertc::IRTCRoom::setAudioSelectionConfig(AudioSelectionPriority audio_selection_priority)=0 ``` > Available since 3.52. 设置本端发布流在音频选路中的优先级。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_selection_priority | AudioSelectionPriority | 本端发布流在音频选路中的优先级，默认正常参与音频选路。参见 [AudioSelectionPriority](85519#AudioSelectionPriority)。 | **注意** - 在控制台上为本 appId 开启音频选路后，调用本接口才会生效。进房前后调用均可生效。更多信息参见[音频选路](https://www.volcengine.com/docs/6348/113547)。 - 如果本端用户同时加入不同房间，使用本接口进行的设置相互独立。 ### setRoomExtraInfo ```cpp virtual int64_t bytertc::IRTCRoom::setRoomExtraInfo( const char* key, const char* value )=0 ``` > Available since 3.52. 设置/更新房间附加信息，可用于标识房间状态或属性，或灵活实现各种业务逻辑。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | key | const char * | 房间附加信息键值，长度小于 10 字节。
同一房间内最多可存在 5 个 key，超出则会从第一个 key 起进行替换。 | | value | const char * | 房间附加信息内容，长度小于 128 字节。 | **返回值** - 0: 方法调用成功，返回本次调用的任务编号； - <0: 方法调用失败，具体原因详见 [SetRoomExtraInfoResult](85519#SetRoomExtraInfoResult)。 **注意** - 在设置房间附加信息前，必须先调用 [joinRoom](#IRTCRoom-joinroom) 加入房间。 - 调用该方法后，会收到一次 [onSetRoomExtraInfoResult](85517#IRTCRoomEventHandler-onsetroomextrainforesult) 回调，提示设置结果。 - 调用该方法成功设置附加信息后，同一房间内的其他用户会收到关于该信息的回调 [onRoomExtraInfoUpdate](85517#IRTCRoomEventHandler-onroomextrainfoupdate)。 - 新进房的用户会收到进房前房间内已有的全部附加信息通知。 ### startSubtitle ```cpp virtual int bytertc::IRTCRoom::startSubtitle(const SubtitleConfig &subtitle_config)=0 ``` > Available since 3.52 识别或翻译房间内所有用户的语音，形成字幕。调用该方法时，可以在 [SubtitleMode](85519#SubtitleMode) 中选择语音识别或翻译模式。如果选择识别模式，语音识别文本会通过 [onSubtitleMessageReceived](85517#IRTCRoomEventHandler-onsubtitlemessagereceived) 事件回调给你；如果选择翻译模式，你会同时收到两个 [onSubtitleMessageReceived](85517#IRTCRoomEventHandler-onsubtitlemessagereceived) 回调，分别包含字幕原文及字幕译文。调用该方法后，用户会收到 [onSubtitleStateChanged](85517#IRTCRoomEventHandler-onsubtitlestatechanged) 回调，通知字幕是否开启。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | subtitle_config | const SubtitleConfig & | 字幕配置信息。参看 [SubtitleConfig](85519#SubtitleConfig)。 | **返回值** - 0: 调用成功。 - !0: 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 使用字幕功能前，你需要在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle&from=doc) 开启实时字幕功能。 - 如果你需要使用流式语音识别模式，你应在 [语音技术控制台](https://console.volcengine.com/speech/service/16) 创建流式语音识别应用。创建时，服务类型应选择 `流式语音识别`，而非 `音视频字幕生成`。创建后，在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle&from=doc) 上启动流式语音识别，并填写创建语音技术应用时获取的相关信息，包括：APP ID，Access Token，和 Cluster ID。 - 如果你需要使用实时语音翻译模式，你应开通机器翻译服务，参考 [开通服务](https://www.volcengine.com/docs/4640/130262)。完成开通后，在 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle&from=doc) 上启用实时语音翻译模式。 - 此方法需要在进房后调用。 - 如需指定源语言，你需要在调用 `joinRoom` 接口进房时，通过 extraInfo 参数传入格式为`"语种英文名": "语种代号"` JSON 字符串，例如设置源语言为英文时，传入 `"source_language": "en"`。如未指定源语言，SDK 会将系统语种设定为源语言。如果你的系统语种不是中文、英文和日文，此时 SDK 会自动将中文设为源语言。 - 识别模式下，你可以传入 [RTC 控制台](https://console.volcengine.com/rtc/cloudRTC?tab=subtitle&from=doc)上预设或自定义的语种英文名和语种代号。识别模式下支持的语言参看[识别模式语种支持](https://www.volcengine.com/docs/6561/109880#场景-语种支持)。 - 翻译模式下，你需要传入机器翻译规定的语种英文名和语种代号。翻译模式下支持的语言及对应的代号参看[翻译模式语言支持](https://www.volcengine.com/docs/4640/35107)。 ### stopSubtitle ```cpp virtual int bytertc::IRTCRoom::stopSubtitle()=0 ``` > Available since 3.52 关闭字幕。调用该方法后，用户会收到 [onSubtitleStateChanged](85517#IRTCRoomEventHandler-onsubtitlestatechanged) 回调，通知字幕是否关闭。 **返回值** - 0: 调用成功。 - !0: 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 ### getRoomId ```cpp virtual const char * bytertc::IRTCRoom::getRoomId()=0 ``` > Available since 3.53 获取房间 ID。 **返回值** 房间 ID。 ### subscribeUserStream ```cpp virtual int bytertc::IRTCRoom::subscribeUserStream( const char* user_id, StreamIndex stream_type, SubscribeMediaType media_type, const SubscribeVideoConfig &video_config )=0 ``` > Deprecated since 3.36 and will be deleted in 3.51, use [subscribeStream](#IRTCRoom-subscribestream), [unsubscribeStream](#IRTCRoom-unsubscribestream), [subscribeScreen](#IRTCRoom-subscribescreen) and [unsubscribeScreen](#IRTCRoom-unsubscribescreen) instead. 订阅房间内指定的远端音视频流。无论是自动订阅还是手动订阅模式，你都可以调用此方法按需订阅房间中的音视频流。该方法也可用于更新已经订阅的流的属性、媒体类型等配置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | user_id | const char * | 指定订阅的远端发布音视频流的用户 ID。 | | stream_type | StreamIndex | 流属性，用于指定订阅主流/屏幕流，参看 [StreamIndex](85519#StreamIndex)。 | | media_type | SubscribeMediaType | 媒体类型，用于指定订阅音/视频，参看 [SubscribeMediaType](85519#SubscribeMediaType)。 | | video_config | const SubscribeVideoConfig & | 视频订阅配置，参看 [SubscribeVideoConfig](85519#SubscribeVideoConfig)。 | **注意** - 若订阅失败，你会收到 [onStreamStateChanged](85517#IRTCRoomEventHandler-onstreamstatechanged) 回调通知，具体失败原因参看 [ErrorCode](85518#ErrorCode)。 - 若调用 [pauseAllSubscribedStream](#IRTCRoom-pauseallsubscribedstream) 暂停接收远端音视频流，此时仍可使用该方法对暂停接收的流进行设置，你会在调用 [resumeAllSubscribedStream](#IRTCRoom-resumeallsubscribedstream) 恢复接收流后收到修改设置后的流。 # Public API ## 成员变量 | 类型 | 名称 | | --- | --- | | void* | [view_t](#view_t) | ## 函数 | 返回 | 名称 | | --- | --- | | BYTERTC_API bytertc::IRTCVideo * | [createRTCVideo](#creatertcvideo) | | BYTERTC_API void | [destroyRTCVideo](#destroyrtcvideo) | | BYTERTC_API const char * | [getErrorDescription](#geterrordescription) | | BYTERTC_API const char * | [getSDKVersion](#getsdkversion) | | BYTERTC_API int | [setLogConfig](#setlogconfig) | | BYTERTC_API IAudioFrame * | [buildAudioFrame](#buildaudioframe) | | BYTERTC_API IPublicStreamParam * | [createPublicStreamParam](#createpublicstreamparam) | | BYTERTC_API ITranscoderParam * | [createTranscoderParam](#createtranscoderparam) | | BYTERTC_API IMixedStreamConfig * | [createMixedStreamConfig](#createmixedstreamconfig) | | BYTERTC_API IVideoFrame * | [buildVideoFrame](#buildvideoframe) | | BYTERTC_API IEncodedVideoFrame * | [buildEncodedVideoFrame](#buildencodedvideoframe) | ## 变量说明 ### view_t ```cpp typedef void* bytertc::view_t ``` Windows 窗口 id, Windows 平台下传 Windows 窗口句柄 ## 函数说明 ### createRTCVideo ```cpp BYTERTC_API bytertc::IRTCVideo * bytertc::createRTCVideo( const char* app_id, bytertc::IRTCVideoEventHandler* event_handler, const char* parameters ) ``` 创建 IRTCVideo 实例。如果当前进程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。如果当前进程中已创建了引擎实例，再次调用此方法时，会返回已创建的引擎实例。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | app_id | const char * | 每个应用的唯一标识符。只有使用相同的 app_id 生成的实例，才能够进行音视频通信。 | | event_handler | bytertc::IRTCVideoEventHandler * | SDK 回调给应用层的 Callback 对象，详见 [IRTCVideoEventHandler](85517#IRTCVideoEventHandler) 。 | | parameters | const char * | 私有参数。如需使用请联系技术支持人员。 | **返回值** - IRTCVideo：创建成功。返回一个可用的 [IRTCVideo](#IRTCVideo) 实例 - Null：app_id 或者 event_handler 为空, event_handler 为空。 ### destroyRTCVideo ```cpp BYTERTC_API void bytertc::destroyRTCVideo() ``` 销毁由 [createRTCVideo](#creatertcvideo) 所创建的引擎实例，并释放所有相关资源。 **注意** - 请确保和需要销毁的 [IRTCVideo](#IRTCVideo) 实例相关的业务场景全部结束后，才调用此方法。如果在多线程场景下，调用此接口后，又调用了其他 [IRTCVideo](#IRTCVideo) 相关接口，可能导致 SDK 崩溃。该方法在调用之后，会销毁所有和此 [IRTCVideo](#IRTCVideo) 实例相关的内存，并且停止与媒体服务器的任何交互。 - 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，会导致死锁。同时此方法是耗时操作，不建议在主线程调用本方法，避免主线程阻塞。 ### getErrorDescription ```cpp BYTERTC_API const char * bytertc::getErrorDescription(int code) ``` 获取 SDK 内各种错误码、警告码的描述文字。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | code | int | 需要获取描述的错误码 | **返回值** 错误码的描述 **注意** 该接口是通用功能，调用时不需要依赖引擎对象。 ### getSDKVersion ```cpp BYTERTC_API const char * bytertc::getSDKVersion() ``` 获取当前 SDK 版本信息。 **返回值** 当前 SDK 版本信息。 ### setLogConfig ```cpp BYTERTC_API int bytertc::setLogConfig(const LogConfig &log_config) ``` 自定义 SDK 日志配置，包括日志输出等级、存储路径、日志文件总大小上限、日志文件名前缀。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | log_config | const LogConfig & | 日志配置，参看 [LogConfig](85519#LogConfig)。 | **返回值** - 0：成功。 - –1：失败，本方法必须在创建引擎前调用。 - –2：失败，参数填写错误。 **注意** 本方法必须在调用 [createRTCVideo](#creatertcvideo) 之前调用。 ### buildAudioFrame ```cpp BYTERTC_API IAudioFrame * bytertc::buildAudioFrame(const AudioFrameBuilder &builder) ``` 创建 IAudioFrame **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | builder | const AudioFrameBuilder & | 音频帧构建实例，参看 [AudioFrameBuilder](85519#audioframebuilder) | **返回值** 详见 [IAudioFrame](85519#IAudioFrame) ### createPublicStreamParam ```cpp BYTERTC_API IPublicStreamParam * bytertc::createPublicStreamParam() ``` 创建公共流参数实例 ### createTranscoderParam ```cpp BYTERTC_API ITranscoderParam * bytertc::createTranscoderParam() ``` 创建合流参数实例 ### createMixedStreamConfig ```cpp BYTERTC_API IMixedStreamConfig * bytertc::createMixedStreamConfig() ``` 创建合流参数实例(新) ### buildVideoFrame ```cpp BYTERTC_API IVideoFrame * bytertc::buildVideoFrame(const VideoFrameBuilder &builder) ``` 创建 IVideoFrame **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | builder | const VideoFrameBuilder & | 视频帧构建实例，参看 [VideoFrameBuilder](85519#VideoFrameBuilder) | **返回值** [IVideoFrame](85519#IVideoFrame) 实例 ### buildEncodedVideoFrame ```cpp BYTERTC_API IEncodedVideoFrame * bytertc::buildEncodedVideoFrame(const EncodedVideoFrameBuilder &builder) ``` 创建 IEncodedVideoFrame **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | builder | const EncodedVideoFrameBuilder & | 编码后的视频帧构建实例，参看 [EncodedVideoFrameBuilder](85519#EncodedVideoFrameBuilder) | **返回值** [IEncodedVideoFrame](85519#IEncodedVideoFrame) 实例 # IMediaPlayer ```cpp class bytertc::IMediaPlayer ``` > Available since 3.53 音乐播放器调用 [setEventHandler](#IMediaPlayer-seteventhandler) 设置回调句柄以获取相关回调。 ## 成员函数 | 返回 | 名称 | | --- | --- | | IMediaPlayer | [IMediaPlayer](#IMediaPlayer-imediaplayer) | | virtual | [~IMediaPlayer](#IMediaPlayer-~imediaplayer) | | virtual int | [open](#IMediaPlayer-open) | | virtual int | [start](#IMediaPlayer-start) | | virtual int | [openWithCustomSource](#IMediaPlayer-openwithcustomsource) | | virtual int | [stop](#IMediaPlayer-stop) | | virtual int | [pause](#IMediaPlayer-pause) | | virtual int | [resume](#IMediaPlayer-resume) | | virtual int | [setVolume](#IMediaPlayer-setvolume) | | virtual int | [getVolume](#IMediaPlayer-getvolume) | | virtual int | [getTotalDuration](#IMediaPlayer-gettotalduration) | | virtual int | [getPlaybackDuration](#IMediaPlayer-getplaybackduration) | | virtual int | [getPosition](#IMediaPlayer-getposition) | | virtual int | [setAudioPitch](#IMediaPlayer-setaudiopitch) | | virtual int | [setPosition](#IMediaPlayer-setposition) | | virtual int | [setAudioDualMonoMode](#IMediaPlayer-setaudiodualmonomode) | | virtual int | [getAudioTrackCount](#IMediaPlayer-getaudiotrackcount) | | virtual int | [selectAudioTrack](#IMediaPlayer-selectaudiotrack) | | virtual int | [setPlaybackSpeed](#IMediaPlayer-setplaybackspeed) | | virtual int | [setProgressInterval](#IMediaPlayer-setprogressinterval) | | virtual int | [setLoudness](#IMediaPlayer-setloudness) | | virtual int | [registerAudioFrameObserver](#IMediaPlayer-registeraudioframeobserver) | | virtual int | [pushExternalAudioFrame](#IMediaPlayer-pushexternalaudioframe) | | virtual int | [setEventHandler](#IMediaPlayer-seteventhandler) | ## 函数说明 ### IMediaPlayer ```cpp bytertc::IMediaPlayer::IMediaPlayer() ``` ### ~IMediaPlayer ```cpp virtual bytertc::IMediaPlayer::~IMediaPlayer() ``` ### open ```cpp virtual int bytertc::IMediaPlayer::open( const char* file_path, const MediaPlayerConfig &config )=0 ``` 打开音乐文件。一个播放器实例仅能够同时打开一个音乐文件。如果需要同时打开多个音乐文件，请创建多个音乐播放器实例。要播放 PCM 格式的音频数据，参看 [openWithCustomSource](#IMediaPlayer-openwithcustomsource)。`openWithCustomSource` 和此 API 互斥。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | file_path | const char * | 音乐文件路径。
支持在线文件的 URL、本地文件的 URI、或本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。
推荐的采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。
不同平台支持的本地文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线文件格式:

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

| | config | const MediaPlayerConfig & | 详见 [MediaPlayerConfig](85519#MediaPlayerConfig)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### start ```cpp virtual int bytertc::IMediaPlayer::start()=0 ``` 播放音乐。你仅需要在调用 [open](#IMediaPlayer-open)，且未开启自动播放时，调用此方法。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 要播放 PCM 格式的音频数据，参看 [openWithCustomSource](#IMediaPlayer-openwithcustomsource)。`openWithCustomSource` 和此 API 互斥。 - 调用本方法播放音频文件后，可调用 [stop](#IMediaPlayer-stop) 方法暂停播放。 ### openWithCustomSource ```cpp virtual int bytertc::IMediaPlayer::openWithCustomSource( const MediaPlayerCustomSource &source, const MediaPlayerConfig &config )=0 ``` 启动音频裸数据混音。要播放音乐文件，参看 [open](#IMediaPlayer-open)。`open` 与此 API 互斥。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | source | const MediaPlayerCustomSource & | 数据源，详见 [MediaPlayerCustomSource](85519#MediaPlayerCustomSource) | | config | const MediaPlayerConfig & | 详见 [MediaPlayerConfig](85519#MediaPlayerConfig) | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本方法启动后，再调用 [pushExternalAudioFrame](#IMediaPlayer-pushexternalaudioframe) 推送音频数据，才会开始混音。 - 如要结束 PCM 音频数据混音，调用 [stop](#IMediaPlayer-stop)。 ### stop ```cpp virtual int bytertc::IMediaPlayer::stop()=0 ``` 调用 [open](#IMediaPlayer-open), [start](#IMediaPlayer-start), 或 [openWithCustomSource](#IMediaPlayer-openwithcustomsource) 开始播放后，可以调用本方法停止。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### pause ```cpp virtual int bytertc::IMediaPlayer::pause()=0 ``` 调用 [open](#IMediaPlayer-open)，或 [start](#IMediaPlayer-start) 开始播放音频文件后，调用本方法暂停播放。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用本方法暂停播放后，可调用 [resume](#IMediaPlayer-resume) 恢复播放。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### resume ```cpp virtual int bytertc::IMediaPlayer::resume()=0 ``` 调用 [pause](#IMediaPlayer-pause) 暂停音频播放后，调用本方法恢复播放。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 此接口仅支持音频文件，不支持 PCM 数据。 ### setVolume ```cpp virtual int bytertc::IMediaPlayer::setVolume( int volume, AudioMixingType type )=0 ``` 调节指定混音的音量大小，包括音乐文件混音和 PCM 混音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | | type | AudioMixingType | 详见 [AudioMixingType](85519#AudioMixingType)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 仅在音频播放进行状态时，调用此方法。 ### getVolume ```cpp virtual int bytertc::IMediaPlayer::getVolume(AudioMixingType type)=0 ``` 获取当前音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | type | AudioMixingType | 详见 [AudioMixingType](85519#AudioMixingType)。 | **返回值** - \>0: 成功, 当前音量值。 - < 0: 失败 **注意** 仅在音频播放进行状态时，调用此方法。包括音乐文件混音和 PCM 混音。 ### getTotalDuration ```cpp virtual int bytertc::IMediaPlayer::getTotalDuration()=0 ``` 获取音乐文件时长。 **返回值** - \>0: 成功, 音乐文件时长，单位为毫秒。 - < 0: 失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### getPlaybackDuration ```cpp virtual int bytertc::IMediaPlayer::getPlaybackDuration()=0 ``` 获取混音音乐文件的实际播放时长，单位为毫秒。 **返回值** - \>0: 实际播放时长。 - < 0: 失败。 **注意** - 实际播放时长指的是歌曲不受停止、跳转、倍速、卡顿影响的播放时长。例如，若歌曲正常播放到 1:30 时停止播放 30s 或跳转进度到 2:00, 随后继续正常播放 2 分钟，则实际播放时长为 3 分 30 秒。 - 仅在音频播放进行状态，且 [setProgressInterval](#IMediaPlayer-setprogressinterval) 设置间隔大于 `0` 时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### getPosition ```cpp virtual int bytertc::IMediaPlayer::getPosition()=0 ``` 获取音乐文件播放进度。 **返回值** - \>0: 成功, 音乐文件播放进度，单位为毫秒。 - < 0: 失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此接口仅支持音频文件，不支持 PCM 数据。 ### setAudioPitch ```cpp virtual int bytertc::IMediaPlayer::setAudioPitch(int pitch)=0 ``` 开启变调功能，多用于 K 歌场景。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | pitch | int | 与音乐文件原始音调相比的升高/降低值，取值范围为 `[-12，12]`，默认值为 0。每相邻两个值的音高距离相差半音，正值表示升调，负值表示降调。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 仅在音频播放进行状态时，调用此方法。 - 仅支持音乐文件混音，不支持 PCM 数据。 ### setPosition ```cpp virtual int bytertc::IMediaPlayer::setPosition(int position)=0 ``` 设置音乐文件的起始播放位置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | position | int | 音乐文件起始播放位置，单位为毫秒。
你可以通过 [getTotalDuration](#IMediaPlayer-gettotalduration) 获取音乐文件总时长，position 的值应小于音乐文件总时长。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 此接口仅支持音频文件，不支持 PCM 数据。 - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 ### setAudioDualMonoMode ```cpp virtual int bytertc::IMediaPlayer::setAudioDualMonoMode(AudioMixingDualMonoMode mode)=0 ``` 设置当前音乐文件的声道模式 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mode | AudioMixingDualMonoMode | 声道模式。默认的声道模式和源文件一致，详见 [AudioMixingDualMonoMode](85519#AudioMixingDualMonoMode)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 仅在音频播放进行状态时，调用此方法。 - 仅支持音频文件，不支持 PCM 数据。 ### getAudioTrackCount ```cpp virtual int bytertc::IMediaPlayer::getAudioTrackCount()=0 ``` 获取当前音乐文件的音轨数 **返回值** + \>= 0：成功，返回当前音乐文件的音轨数 - < 0：方法调用失败 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法仅支持音乐文件，不支持 PCM 数据。 ### selectAudioTrack ```cpp virtual int bytertc::IMediaPlayer::selectAudioTrack(int index)=0 ``` 指定当前音乐文件的播放音轨 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 指定的播放音轨，从 0 开始，取值范围为 `[0, getAudioTrackCount()-1]`。
设置的参数值需要小于 [getAudioTrackCount](#IMediaPlayer-getaudiotrackcount) 的返回值 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 - 此方法仅支持音乐文件，不支持 PCM 数据。 **注意** - 仅在音频播放进行状态时，调用此方法。 ### setPlaybackSpeed ```cpp virtual int bytertc::IMediaPlayer::setPlaybackSpeed(int speed)=0 ``` 设置播放速度 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | speed | int | 播放速度与原始文件速度的比例，单位：%，取值范围为 `[50,200]`，默认值为 100。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法对音频文件可用，不支持 PCM 数据。 ### setProgressInterval ```cpp virtual int bytertc::IMediaPlayer::setProgressInterval(int64_t interval)=0 ``` 设置音频文件混音时，收到 [onMediaPlayerPlayingProgress](85517#IMediaPlayerEventHandler-onmediaplayerplayingprogress) 的间隔。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | interval | int64_t | 时间间隔，单位毫秒。

interval > 0 时，触发回调。实际间隔为 10 的倍数。如果输入数值不能被 10 整除，将自动向上取整。例如传入 `52`，实际间隔为 60 ms。
interval <= 0 时，不会触发回调。

| **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法仅支持音频文件，不支持 PCM 数据。 ### setLoudness ```cpp virtual int bytertc::IMediaPlayer::setLoudness(float loudness)=0 ``` 如果你需要使用 [enableVocalInstrumentBalance](#IRTCVideo-enablevocalinstrumentbalance) 对音频文件/PCM 音频数据设置音量均衡，你必须通过此接口传入其原始响度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | loudness | float | 原始响度，单位：lufs，取值范围为 `[-70.0, 0.0]`。
当设置的值小于 -70.0lufs 时，则默认调整为 -70.0lufs，大于 0.0lufs 时，则不对该响度做音量均衡处理。默认值为 1.0lufs，即不做处理。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 仅在音频播放进行状态时，调用此方法。 - 此方法对音频文件和音频裸数据播放都可用。 ### registerAudioFrameObserver ```cpp virtual int bytertc::IMediaPlayer::registerAudioFrameObserver(IMediaPlayerAudioFrameObserver* observer)=0 ``` 注册回调句柄以在本地音乐文件混音时，收到相关回调。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | observer | IMediaPlayerAudioFrameObserver * | 参看 [IMediaPlayerAudioFrameObserver](85517#IMediaPlayerAudioFrameObserver)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** 此接口仅支持音频文件，不支持 PCM 数据。 ### pushExternalAudioFrame ```cpp virtual int bytertc::IMediaPlayer::pushExternalAudioFrame(IAudioFrame* audio_frame)=0 ``` 推送用于混音的 PCM 音频帧数据 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | audio_frame | IAudioFrame * | 音频帧，详见 [IAudioFrame](85519#IAudioFrame)。

音频采样格式必须为 S16。音频缓冲区内的数据格式必须为 PCM，其容量大小应该为 audioFrame.samples × audioFrame.channel × 2。
必须指定具体的采样率和声道数，不支持设置为自动。

| **返回值** - 0: 成功 - < 0: 失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明。 **注意** - 调用该方法前，须通过 [openWithCustomSource](#IMediaPlayer-openwithcustomsource) 启动外部音频流混音。 - 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 200 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。 - 如果要暂停播放，暂停推送即可。 ### setEventHandler ```cpp virtual int bytertc::IMediaPlayer::setEventHandler(IMediaPlayerEventHandler* handler)=0 ``` 设置回调句柄。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IMediaPlayerEventHandler * | 参看 [IMediaPlayerEventHandler](85517#IMediaPlayerEventHandler)。 | **返回值** - 0: 成功。 - < 0: 失败。 # IAudioEffectPlayer ```cpp class bytertc::IAudioEffectPlayer ``` > Available since 3.53 音效播放器调用 [setEventHandler](#IAudioEffectPlayer-seteventhandler) 设置回调句柄以获取相关回调。 ## 成员函数 | 返回 | 名称 | | --- | --- | | IAudioEffectPlayer | [IAudioEffectPlayer](#IAudioEffectPlayer-iaudioeffectplayer) | | virtual | [~IAudioEffectPlayer](#IAudioEffectPlayer-~iaudioeffectplayer) | | virtual int | [start](#IAudioEffectPlayer-start) | | virtual int | [stop](#IAudioEffectPlayer-stop) | | virtual int | [stopAll](#IAudioEffectPlayer-stopall) | | virtual int | [preload](#IAudioEffectPlayer-preload) | | virtual int | [unload](#IAudioEffectPlayer-unload) | | virtual int | [unloadAll](#IAudioEffectPlayer-unloadall) | | virtual int | [pause](#IAudioEffectPlayer-pause) | | virtual int | [pauseAll](#IAudioEffectPlayer-pauseall) | | virtual int | [resume](#IAudioEffectPlayer-resume) | | virtual int | [resumeAll](#IAudioEffectPlayer-resumeall) | | virtual int | [setPosition](#IAudioEffectPlayer-setposition) | | virtual int | [getPosition](#IAudioEffectPlayer-getposition) | | virtual int | [setVolume](#IAudioEffectPlayer-setvolume) | | virtual int | [setVolumeAll](#IAudioEffectPlayer-setvolumeall) | | virtual int | [getVolume](#IAudioEffectPlayer-getvolume) | | virtual int | [getDuration](#IAudioEffectPlayer-getduration) | | virtual int | [setEventHandler](#IAudioEffectPlayer-seteventhandler) | ## 函数说明 ### IAudioEffectPlayer ```cpp bytertc::IAudioEffectPlayer::IAudioEffectPlayer() ``` ### ~IAudioEffectPlayer ```cpp virtual bytertc::IAudioEffectPlayer::~IAudioEffectPlayer() ``` ### start ```cpp virtual int bytertc::IAudioEffectPlayer::start( int effect_id, const char* file_path, const AudioEffectPlayerConfig &config )=0 ``` 开始播放音效文件。可以通过传入不同的 ID 和 filepath 多次调用本方法，以实现同时播放多个音效文件，实现音效叠加。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID。用于标识音效，请保证音效 ID 唯一性。
如果使用相同的 ID 重复调用本方法后，上一个音效会停止，下一个音效开始，并收到 [onAudioEffectPlayerStateChanged](85517#IAudioEffectPlayerEventHandler-onaudioeffectplayerstatechanged)。 | | file_path | const char * | 音效文件路径。
支持在线文件的 URL、本地文件的 URI、或本地文件的绝对路径。对于在线文件的 URL，仅支持 https 协议。
推荐的音效文件采样率：8KHz、16KHz、22.05KHz、44.1KHz、48KHz。
不同平台支持的本地音效文件格式:

	mp3	mp4	aac	m4a	3gp	wav	ogg	ts	wma
Android	Y	Y	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y	Y	Y	Y
Windows	Y	Y	Y	Y	Y	Y		Y	Y

不同平台支持的在线音效文件格式:

	mp3	aac	m4a	3gp	wav	ts	wma
Android	Y	Y	Y	Y	Y
iOS/macOS	Y	Y	Y		Y
Windows	Y	Y	Y	Y	Y	Y	Y

| | config | const AudioEffectPlayerConfig & | 音效配置，详见 [AudioEffectPlayerConfig](85519#AudioEffectPlayerConfig)。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 如果已经通过 [preload](#IAudioEffectPlayer-preload) 将文件加载至内存，确保此处的 ID 与 [preload](#IAudioEffectPlayer-preload) 设置的 ID 相同。 - 开始播放音效文件后，可以调用 [stop](#IAudioEffectPlayer-stop) 方法停止播放音效文件。 ### stop ```cpp virtual int bytertc::IAudioEffectPlayer::stop(int effect_id)=0 ``` 停止播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以调用本方法停止播放音效文件。 - 调用本方法停止播放音效文件后，该音效文件会被自动卸载。 ### stopAll ```cpp virtual int bytertc::IAudioEffectPlayer::stopAll()=0 ``` 停止播放所有音效文件。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以调用本方法停止播放所有音效文件。 - 调用本方法停止播放所有音效文件后，该音效文件会被自动卸载。 ### preload ```cpp virtual int bytertc::IAudioEffectPlayer::preload( int effect_id, const char* file_path )=0 ``` 预加载指定音乐文件到内存中，以避免频繁播放同一文件时的重复加载，减少 CPU 占用。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID。用于标识音效，请保证音效 ID 唯一性。
如果使用相同的 ID 重复调用本方法，后一次会覆盖前一次。
如果先调用 [start](#IAudioEffectPlayer-start)，再使用相同的 ID 调用本方法，会收到回调 [onAudioEffectPlayerStateChanged](85517#IAudioEffectPlayerEventHandler-onaudioeffectplayerstatechanged)，通知前一个音效停止，然后加载下一个音效。
调用本方法预加载 A.mp3 后，如果需要使用相同的 ID 调用 [start](#IAudioEffectPlayer-start) 播放 B.mp3，请先调用 [unload](#IAudioEffectPlayer-unload) 卸载 A.mp3 ，否则会报错 AUDIO_MIXING_ERROR_LOAD_CONFLICT。 | | file_path | const char * | 音效文件路径。支持本地文件的 URI。
预加载的文件长度不得超过 20s。
不同平台支持的音效文件格式和 [start](#IAudioEffectPlayer-start) 一致。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 本方法只是预加载指定音效文件，只有调用 [start](#IAudioEffectPlayer-start) 方法才开始播放指定音效文件。 - 调用本方法预加载的指定音效文件可以通过 [unload](#IAudioEffectPlayer-unload) 卸载。 ### unload ```cpp virtual int bytertc::IAudioEffectPlayer::unload(int effect_id)=0 ``` 卸载指定音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 或 [preload](#IAudioEffectPlayer-preload) 后调用此接口。 ### unloadAll ```cpp virtual int bytertc::IAudioEffectPlayer::unloadAll()=0 ``` 卸载所有音效文件。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 ### pause ```cpp virtual int bytertc::IAudioEffectPlayer::pause(int effect_id)=0 ``` 暂停播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放音效文件。 - 调用本方法暂停播放音效文件后，可调用 [resume](#IAudioEffectPlayer-resume) 方法恢复播放。 ### pauseAll ```cpp virtual int bytertc::IAudioEffectPlayer::pauseAll()=0 ``` 暂停播放所有音效文件。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 调用 [start](#IAudioEffectPlayer-start) 方法开始播放音效文件后，可以通过调用本方法暂停播放所有音效文件。 - 调用本方法暂停播放所有音效文件后，可调用 [resumeAll](#IAudioEffectPlayer-resumeall) 方法恢复所有播放。 ### resume ```cpp virtual int bytertc::IAudioEffectPlayer::resume(int effect_id)=0 ``` 恢复播放音效文件。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用 [pause](#IAudioEffectPlayer-pause) 方法暂停播放音效文件后，可以通过调用本方法恢复播放。 ### resumeAll ```cpp virtual int bytertc::IAudioEffectPlayer::resumeAll()=0 ``` 恢复播放所有音效文件。 **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 调用 [pauseAll](#IAudioEffectPlayer-pauseall) 方法暂停所有正在播放音效文件后，可以通过调用本方法恢复播放。 ### setPosition ```cpp virtual int bytertc::IAudioEffectPlayer::setPosition( int effect_id, int pos )=0 ``` 设置音效文件的起始播放位置。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | | pos | int | 音效文件起始播放位置，单位为毫秒。
你可以通过 [getDuration](#IAudioEffectPlayer-getduration) 获取音效文件总时长，pos 的值应小于音效文件总时长。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### getPosition ```cpp virtual int bytertc::IAudioEffectPlayer::getPosition(int effect_id)=0 ``` 获取音效文件播放进度。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - \>0: 成功, 音效文件播放进度，单位为毫秒。 - < 0: 失败 **注意** - 在播放在线文件时，调用此接口可能造成播放延迟的现象。 - 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setVolume ```cpp virtual int bytertc::IAudioEffectPlayer::setVolume( int effect_id, int volume )=0 ``` 调节指定音效的音量大小，包括音效文件和 PCM 音频。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | | volume | int | 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setVolumeAll ```cpp virtual int bytertc::IAudioEffectPlayer::setVolumeAll(int volume)=0 ``` 设置所有音效的音量大小，包括音效文件和 PCM 音效。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | int | 播放音量相对原音量的比值。单位为 %。范围为 `[0, 400]`，建议范围是 `[0, 100]`。带溢出保护。 | **返回值** - 0: 调用成功。 - < 0 : 调用失败。查看 [ReturnStatus](85519#ReturnStatus) 获得更多错误说明 **注意** 该接口的优先级低于 [setVolume](#IAudioEffectPlayer-setvolume)，即通过 [setVolume](#IAudioEffectPlayer-setvolume) 单独设置了音量的音效 ID，不受该接口设置的影响。 ### getVolume ```cpp virtual int bytertc::IAudioEffectPlayer::getVolume(int effect_id)=0 ``` 获取当前音量。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - \>0: 成功, 当前音量值。 - < 0: 失败 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### getDuration ```cpp virtual int bytertc::IAudioEffectPlayer::getDuration(int effect_id)=0 ``` 获取音效文件时长。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | effect_id | int | 音效 ID | **返回值** - \>0: 成功, 音效文件时长，单位为毫秒。 - < 0: 失败 **注意** 仅在调用 [start](#IAudioEffectPlayer-start) 后调用此接口。 ### setEventHandler ```cpp virtual int bytertc::IAudioEffectPlayer::setEventHandler(IAudioEffectPlayerEventHandler* handler)=0 ``` 设置回调句柄。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | handler | IAudioEffectPlayerEventHandler * | 参看 [IAudioEffectPlayerEventHandler](85517#IAudioEffectPlayerEventHandler)。 | **返回值** - 0: 成功。 - < 0: 失败。 # IVideoProcessor ```cpp class bytertc::IVideoProcessor ``` 视频处理接口类 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual IVideoFrame * | [processVideoFrame](#IVideoProcessor-processvideoframe) | ## 函数说明 ### processVideoFrame ```cpp virtual IVideoFrame * bytertc::IVideoProcessor::processVideoFrame(IVideoFrame* src_frame)=0 ``` 获取 RTC SDK 采集得到的视频帧，根据 [registerLocalVideoProcessor](#IRTCVideo-registerlocalvideoprocessor) 设置的视频前处理器，进行视频前处理，最终将处理后的视频帧给到 RTC SDK 用于编码传输。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | src_frame | IVideoFrame * | RTC SDK 采集得到的视频帧，参看 [IVideoFrame](85519#IVideoFrame)。 | **返回值** 经过视频前处理后的视频帧，返回给 RTC SDK 供编码和传输，参看 [IVideoFrame](85519#IVideoFrame)。 **注意** - 在进行视频前处理前，你需要调用 [registerLocalVideoProcessor](#IRTCVideo-registerlocalvideoprocessor) 设置视频前处理器。 - 如果需要取消视频前处理，可以将视频前处理器设置为 nullptr。 # IAudioDeviceManager ```cpp class bytertc::IAudioDeviceManager ``` 音频设备管理类 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual IAudioDeviceCollection * | [enumerateAudioPlaybackDevices](#IAudioDeviceManager-enumerateaudioplaybackdevices) | | virtual IAudioDeviceCollection * | [enumerateAudioCaptureDevices](#IAudioDeviceManager-enumerateaudiocapturedevices) | | virtual void | [followSystemPlaybackDevice](#IAudioDeviceManager-followsystemplaybackdevice) | | virtual void | [followSystemCaptureDevice](#IAudioDeviceManager-followsystemcapturedevice) | | virtual int | [setAudioPlaybackDevice](#IAudioDeviceManager-setaudioplaybackdevice) | | virtual int | [setAudioCaptureDevice](#IAudioDeviceManager-setaudiocapturedevice) | | virtual int | [setAudioPlaybackDeviceVolume](#IAudioDeviceManager-setaudioplaybackdevicevolume) | | virtual int | [getAudioPlaybackDeviceVolume](#IAudioDeviceManager-getaudioplaybackdevicevolume) | | virtual int | [setAudioCaptureDeviceVolume](#IAudioDeviceManager-setaudiocapturedevicevolume) | | virtual int | [getAudioCaptureDeviceVolume](#IAudioDeviceManager-getaudiocapturedevicevolume) | | virtual int | [setAudioPlaybackDeviceMute](#IAudioDeviceManager-setaudioplaybackdevicemute) | | virtual int | [getAudioPlaybackDeviceMute](#IAudioDeviceManager-getaudioplaybackdevicemute) | | virtual int | [setAudioCaptureDeviceMute](#IAudioDeviceManager-setaudiocapturedevicemute) | | virtual int | [getAudioCaptureDeviceMute](#IAudioDeviceManager-getaudiocapturedevicemute) | | virtual int | [getAudioPlaybackDevice](#IAudioDeviceManager-getaudioplaybackdevice) | | virtual int | [getAudioCaptureDevice](#IAudioDeviceManager-getaudiocapturedevice) | | virtual int | [initAudioPlaybackDeviceForTest](#IAudioDeviceManager-initaudioplaybackdevicefortest) | | virtual int | [initAudioCaptureDeviceForTest](#IAudioDeviceManager-initaudiocapturedevicefortest) | | virtual int | [startAudioPlaybackDeviceTest](#IAudioDeviceManager-startaudioplaybackdevicetest) | | virtual int | [stopAudioPlaybackDeviceTest](#IAudioDeviceManager-stopaudioplaybackdevicetest) | | virtual int | [enableFilterSilentDevice](#IAudioDeviceManager-enablefiltersilentdevice) | ## 函数说明 ### enumerateAudioPlaybackDevices ```cpp virtual IAudioDeviceCollection * bytertc::IAudioDeviceManager::enumerateAudioPlaybackDevices()=0 ``` 获取当前系统内音频播放设备列表。如果后续设备有变更，你会收到 `onAudioMediaDeviceStateChanged` 回调通知，然后需要重新调用本接口以获得新的设备列表。 **返回值** 包含系统中所有音频播放设备的列表，参看 [IAudioDeviceCollection](#IAudioDeviceCollection)。等待超时后会返回空列表。超时时间默认为 10 s。建议通过 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 监听到 `kMediaDeviceListUpdated` 后，再次调用本接口获取。 **注意** 你可以在收到 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 了解设备变更后，重新调用本接口以获得新的设备列表。 ### enumerateAudioCaptureDevices ```cpp virtual IAudioDeviceCollection * bytertc::IAudioDeviceManager::enumerateAudioCaptureDevices()=0 ``` 获取当前系统内音频采集设备列表。如果后续设备有变更，你需要重新调用本接口以获得新的设备列表。 **返回值** 一个包含系统中所有音频采集设备列表的对象，详见 [IAudioDeviceCollection](#IAudioDeviceCollection)。等待超时后会返回空列表。超时时间默认为 10 s。建议通过 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 监听到 `kMediaDeviceListUpdated` 后，再次调用本接口获取。 **注意** 你可以在收到 [onAudioDeviceStateChanged](85517#IRTCVideoEventHandler-onaudiodevicestatechanged) 了解设备变更后，重新调用本接口以获得新的设备列表。 ### followSystemPlaybackDevice ```cpp virtual void bytertc::IAudioDeviceManager::followSystemPlaybackDevice(bool followed)=0 ``` 设置音频播放路由是否跟随系统。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | followed | bool |

true: 跟随。此时，调用 [setAudioPlaybackDevice](#IAudioDeviceManager-setaudioplaybackdevice) 会失败。默认值。
false: 不跟随系统。此时，可以调用 [setAudioPlaybackDevice](#IAudioDeviceManager-setaudioplaybackdevice) 进行设置。

| ### followSystemCaptureDevice ```cpp virtual void bytertc::IAudioDeviceManager::followSystemCaptureDevice(bool followed)=0 ``` 设置音频采集路由是否跟随系统。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | followed | bool |

true: 跟随。此时，调用 [setAudioCaptureDevice](#IAudioDeviceManager-setaudiocapturedevice) 会失败。默认值。
false: 不跟随系统。此时，可以调用 [setAudioCaptureDevice](#IAudioDeviceManager-setaudiocapturedevice) 进行设置。

| ### setAudioPlaybackDevice ```cpp virtual int bytertc::IAudioDeviceManager::setAudioPlaybackDevice(const char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 设置音频播放设备。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | const char[MAX_DEVICE_ID_LENGTH] | 音频播放设备 ID，可通过 [enumerateAudioPlaybackDevices](#IAudioDeviceManager-enumerateaudioplaybackdevices)
获取。 | **返回值** - 0：方法调用成功 - < 0：方法调用失败 **注意** 当你调用 [followSystemPlaybackDevice](#IAudioDeviceManager-followsystemplaybackdevice) 设置音频播放设备跟随系统后，将无法调用此接口设置音频播放设备。 ### setAudioCaptureDevice ```cpp virtual int bytertc::IAudioDeviceManager::setAudioCaptureDevice(const char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 设置音频采集设备。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | const char[MAX_DEVICE_ID_LENGTH] | 音频采集设备 ID，可通过 [enumerateAudioCaptureDevices](#IAudioDeviceManager-enumerateaudiocapturedevices) 获取。 | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** 当你调用 [followSystemCaptureDevice](#IAudioDeviceManager-followsystemcapturedevice) 设置音频采集设备跟随系统后，将无法调用此接口设置音频采集设备。 ### setAudioPlaybackDeviceVolume ```cpp virtual int bytertc::IAudioDeviceManager::setAudioPlaybackDeviceVolume(unsigned int volume)=0 ``` 设置当前音频播放设备音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | unsigned int | 音频播放设备音量，取值范围为 [0,255], 超出此范围设置无效。

[0,25] 接近无声；
[25,75] 为低音量；
[76,204] 为中音量；
[205,255] 为高音量。

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### getAudioPlaybackDeviceVolume ```cpp virtual int bytertc::IAudioDeviceManager::getAudioPlaybackDeviceVolume(unsigned int* volume)=0 ``` 获取当前音频播放设备音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | unsigned int * | 音频播放设备音量，范围应在 [0,255] 内。

[0,25] 接近无声；
[25,75] 为低音量；
[76,204] 为中音量；
[205,255] 为高音量。

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### setAudioCaptureDeviceVolume ```cpp virtual int bytertc::IAudioDeviceManager::setAudioCaptureDeviceVolume(unsigned int volume)=0 ``` 设置当前音频采集设备音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | unsigned int | 音频采集设备音量，取值范围为 [0,255], 超出此范围设置无效。

[0,25] 接近无声；
[25,75] 为低音量；
[76,204] 为中音量；
[205,255] 为高音量。

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** 调用 [setAudioCaptureDeviceMute](#IAudioDeviceManager-setaudiocapturedevicemute) 设为 `true` 静音采集设备后的音量调节会在取消静音后生效。 ### getAudioCaptureDeviceVolume ```cpp virtual int bytertc::IAudioDeviceManager::getAudioCaptureDeviceVolume(unsigned int* volume)=0 ``` 获取当前音频采集设备音量 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | volume | unsigned int * | 音频采集设备音量，范围应在 [0,255] 内。

[0,25] 接近无声；
[25,75] 为低音量；
[76,204] 为中音量；
[205,255] 为高音量。

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### setAudioPlaybackDeviceMute ```cpp virtual int bytertc::IAudioDeviceManager::setAudioPlaybackDeviceMute(bool mute)=0 ``` 设置当前音频播放设备静音状态，默认为非静音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | bool |

true：静音
false：非静音

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### getAudioPlaybackDeviceMute ```cpp virtual int bytertc::IAudioDeviceManager::getAudioPlaybackDeviceMute(bool* mute)=0 ``` 获取当前音频播放设备是否静音的信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | bool * |

true：静音
false：非静音

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### setAudioCaptureDeviceMute ```cpp virtual int bytertc::IAudioDeviceManager::setAudioCaptureDeviceMute(bool mute)=0 ``` 设置当前音频采集设备静音状态，默认为非静音。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | bool |

true：静音
false：非静音

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** - 该方法用于静音整个系统的音频采集。你也可以仅对麦克风采集到的音频信号做静音处理，而不影响媒体播放器的音乐声音，具体参看 [muteAudioCapture](#IRTCVideo-muteaudiocapture) 方法说明。 - 设该方法为 `true` 静音后仍可通过 [setAudioCaptureDeviceVolume](#IAudioDeviceManager-setaudiocapturedevicevolume) 调整采集音量，调整后的音量会在取消静音后生效。 ### getAudioCaptureDeviceMute ```cpp virtual int bytertc::IAudioDeviceManager::getAudioCaptureDeviceMute(bool* mute)=0 ``` 获取当前音频采集设备是否静音的信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | mute | bool * |

true：静音
false：非静音

| **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### getAudioPlaybackDevice ```cpp virtual int bytertc::IAudioDeviceManager::getAudioPlaybackDevice(char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 获取当前音频播放设备 ID。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | char[MAX_DEVICE_ID_LENGTH] | 音频播放设备 ID | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### getAudioCaptureDevice ```cpp virtual int bytertc::IAudioDeviceManager::getAudioCaptureDevice(char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 获取当前音频采集设备 ID。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | char[MAX_DEVICE_ID_LENGTH] | 音频采集设备 ID，使用方负责按 MAX_DEVICE_ID_LENGTH 大小，分配与释放内存 | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 ### initAudioPlaybackDeviceForTest ```cpp virtual int bytertc::IAudioDeviceManager::initAudioPlaybackDeviceForTest(const char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | const char[MAX_DEVICE_ID_LENGTH] | 设备索引号 | **返回值** 设备状态错误码 - 0: 设备检测结果正常 - -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测 - -2: 采集设备无麦克风权限，尝试初始化设备失败 - -3: 设备不存在，当前没有设备或设备被移除时返回 - -4: 设备音频格式不支持 - -5: 其它原因错误 **注意** 1. 该接口需在进房前调用； 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。 ### initAudioCaptureDeviceForTest ```cpp virtual int bytertc::IAudioDeviceManager::initAudioCaptureDeviceForTest(const char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 尝试初始化音频采集设备，可检测设备不存在、权限被拒绝/禁用等异常问题。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | const char[MAX_DEVICE_ID_LENGTH] | 设备索引 | **返回值** 设备状态错误码 - 0: 设备检测结果正常 - -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测 - -2: 采集设备无麦克风权限，尝试初始化设备失败 - -3: 设备不存在，当前没有设备或设备被移除时返回 - -4: 设备音频格式不支持 - -5: 其它原因错误 **注意** 1. 该接口需在进房前调用; 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。 ### startAudioPlaybackDeviceTest ```cpp virtual int bytertc::IAudioDeviceManager::startAudioPlaybackDeviceTest( const char* test_audio_file_path, int indication_interval )=0 ``` 启动音频播放设备检测。测试启动后，循环播放指定的音频文件，同时将通过 `onAudioPlaybackDeviceTestVolume` 回调播放时的音量信息。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | test_audio_file_path | const char * | 指定播放设备检测的音频文件网络地址。支持的格式包括 mp3，aac，m4a，3gp 和 wav。 | | indication_interval | int | 设置 `onAudioPlaybackDeviceTestVolume` 音量回调的时间间隔，推荐设置为 200 毫秒或以上。单位为毫秒。最小值为 10 毫秒。 | **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** - 该方法可在进房前和进房后调用，不可与其它音频设备测试功能同时应用。 - 调用 [stopAudioPlaybackDeviceTest](#IAudioDeviceManager-stopaudioplaybackdevicetest) 可以停止测试。 ### stopAudioPlaybackDeviceTest ```cpp virtual int bytertc::IAudioDeviceManager::stopAudioPlaybackDeviceTest()=0 ``` 停止音频播放测试。 **返回值** 方法调用结果 - 0：方法调用成功 - < 0：方法调用失败 **注意** 调用 [startAudioPlaybackDeviceTest](#IAudioDeviceManager-startaudioplaybackdevicetest) 后，调用本方法停止测试。 ### enableFilterSilentDevice ```cpp virtual int bytertc::IAudioDeviceManager::enableFilterSilentDevice(bool enable)=0 ``` 开启/关闭过滤无声设备功能。 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | enable | bool | 是否开启过滤无声设备功能:

1: 是。
0: 否。

| **返回值** + 0：方法调用成功。 # IVideoDeviceManager ```cpp class bytertc::IVideoDeviceManager ``` 主要用于枚举、设置视频采集设备 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual IVideoDeviceCollection * | [enumerateVideoCaptureDevices](#IVideoDeviceManager-enumeratevideocapturedevices) | | virtual int | [setVideoCaptureDevice](#IVideoDeviceManager-setvideocapturedevice) | | virtual int | [getVideoCaptureDevice](#IVideoDeviceManager-getvideocapturedevice) | ## 函数说明 ### enumerateVideoCaptureDevices ```cpp virtual IVideoDeviceCollection * bytertc::IVideoDeviceManager::enumerateVideoCaptureDevices()=0 ``` 获取当前系统内视频采集设备列表。 **返回值** 包含系统中所有视频采集设备的列表，参看 [IVideoDeviceCollection](#IVideoDeviceCollection)。等待超时后会返回空列表。超时时间默认为 10 s。建议通过 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 监听到 `kMediaDeviceListUpdated` 后，再次调用本接口获取。 **注意** 你可以在收到 [onVideoDeviceStateChanged](85517#IRTCVideoEventHandler-onvideodevicestatechanged) 了解设备变更后，重新调用本接口以获得新的设备列表。 ### setVideoCaptureDevice ```cpp virtual int bytertc::IVideoDeviceManager::setVideoCaptureDevice(const char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 设置当前视频采集设备 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | const char[MAX_DEVICE_ID_LENGTH] | 视频设备 ID，可以通过 [enumerateVideoCaptureDevices](#IVideoDeviceManager-enumeratevideocapturedevices) 获取 | **返回值** - 0：方法调用成功 - !0：方法调用失败 ### getVideoCaptureDevice ```cpp virtual int bytertc::IVideoDeviceManager::getVideoCaptureDevice(char device_id[MAX_DEVICE_ID_LENGTH])=0 ``` 获取当前 SDK 正在使用的视频采集设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | device_id | char[MAX_DEVICE_ID_LENGTH] | 视频设备 ID。此参数同时是入参和出参。 | **返回值** - 0：方法调用成功 - !0：方法调用失败 # IDeviceCollection ```cpp class bytertc::IDeviceCollection ``` > Deprecated since 3.42 and will be deleted in 3.51, use [IAudioDeviceCollection](#IAudioDeviceCollection) and [IVideoDeviceCollection](#IVideoDeviceCollection) instead. 音视频设备相关的信息 ## 成员函数 | 返回 | 名称 | | --- | --- | | virtual int | [getCount](#IDeviceCollection-getcount) | | virtual int | [getDevice](#IDeviceCollection-getdevice) | | virtual void | [release](#IDeviceCollection-release) | ## 函数说明 ### getCount ```cpp virtual int bytertc::IDeviceCollection::getCount()=0 ``` 获取当前系统内音视频设备数量 **返回值** 音视频设备数量 ### getDevice ```cpp virtual int bytertc::IDeviceCollection::getDevice( int index, char device_name[MAX_DEVICE_ID_LENGTH], char device_id[MAX_DEVICE_ID_LENGTH] )=0 ``` 根据索引号，获取设备信息 **传入参数** | 参数名 | 类型 | 说明 | | --- | --- | --- | | index | int | 设备索引号，从 0 开始，注意需小于 [getCount](#IAudioDeviceCollection-getcount) 返回值。 | | device_name | char[MAX_DEVICE_ID_LENGTH] | 设备名称 | | device_id | char[MAX_DEVICE_ID_LENGTH] | 设备 ID | **返回值** - 0：方法调用成功，从已设定好的内容中成功读取设备信息。 - !0：方法调用失败 ### release ```cpp virtual void bytertc::IDeviceCollection::release()=0 ``` 释放当前 [IAudioDeviceCollection](#IAudioDeviceCollection) 对象占用的资源。 **注意** 不需要返回音视频设备相关信息列表时应该调用本方法释放相关资源。