Public API

函数

函数说明

BuildVideoFrame

BYTERTC_API IVideoFrame* bytertc::BuildVideoFrame(
    const VideoFrameBuilder& builder)

创建 IVideoFrame

传入参数

PushExternalVideoFrame

BYTERTC_API bool bytertc::PushExternalVideoFrame(
    IRtcEngine* engine,
    const IVideoFrame* frame)

发送外部源视频数据

传入参数

注意 1.支持 YUV420P，NV12，D3D texture，Cuda 内存，OpenGL texture等格式的视频帧。 2.该函数运行在用户调用线程内

BuildAudioFrame

BYTERTC_API IAudioFrame* bytertc::BuildAudioFrame(
    const AudioFrameBuilder& builder)

创建 IAudioFrame

传入参数

CreateRtcEngine

BYTERTC_API bytertc::IRtcEngine* bytertc::CreateRtcEngine(
    const char* app_id,
    bytertc::IRtcEngineEventHandler* event_handler,
    const char* parameters)

创建 RTCEngine 实例。
如果当前线程中未创建引擎实例，那么你必须先使用此方法，以使用 RTC 提供的各种音视频能力。
如果当前线程中已创建了引擎实例，再次调用此方法时，会创建另一个独立的引擎实例。

传入参数

返回值

• IRtcEngine：创建成功。返回一个可用的 IRtcEngine 实例
• Null：创建失败。

注意

• 如果你在同一个线程中创建了多个引擎实例，这些实例必须分别调用 DestroyRtcEngine 销毁。
• 在 Linux 平台上创建引擎实例的数量取决于系统的硬件性能。

DestroyRtcEngine

BYTERTC_API void bytertc::DestroyRtcEngine(
    bytertc::IRtcEngine* engine)

销毁由 CreateRtcEngine 创建的 RTCEngine 实例，并释放所有相关资源。

传入参数

注意

• 请确保和需要销毁的 IRtcEngine 实例相关的业务场景全部结束后，才调用此方法。
• 该方法在调用之后，会销毁所有和此 IRtcEngine 实例相关的内存，并且停止与媒体服务器的任何交互。
• 调用本方法会启动 SDK 退出逻辑。引擎线程会保留，直到退出逻辑完成。因此，不要在回调线程中直接调用此 API，也不要在回调中等待主线程的执行，并同时在主线程调用本方法。不然会造成死锁。

GetErrorDescription

BYTERTC_API const char* bytertc::GetErrorDescription(
    int code)

获取错误码的描述

传入参数

返回值 错误码的描述

注意 该接口是通用功能，调用时不需要依赖引擎对象。

GetSDKVersion

BYTERTC_API const char* bytertc::GetSDKVersion();

获取当前 SDK 版本信息。

返回值 当前 SDK 版本信息。

IAudioMixingManager

class bytertc::IAudioMixingManager

混音管理类

成员函数

函数说明

StartAudioMixing

virtual void bytertc::IAudioMixingManager::StartAudioMixing(
    int mix_id,
    const char * file_path,
    const AudioMixingConfig& config)

开始播放音乐文件及混音

传入参数

注意

• 调用本方法成功播放音乐文件后，SDK 会向本地回调当前的混音状态，见 OnAudioMixingStateChanged。
• 开始播放音乐文件及混音后，可以调用 StopAudioMixing 方法停止播放音乐文件。
• 本方法混音数据来源于外部文件，而 EnableAudioMixingFrame 的混音数据来源于外部缓存且音频格式为 PCM；这两种混音方式可以共存。

StopAudioMixing

virtual void bytertc::IAudioMixingManager::StopAudioMixing(
    int mix_id)

停止播放音乐文件及混音

传入参数

注意

• 调用 StartAudioMixing 方法开始播放音乐文件及混音后，可以调用本方法停止播放音乐文件及混音。
• 调用本方法停止播放音乐文件后，SDK 会向本地回调通知已停止混音，见 OnAudioMixingStateChanged。
• 调用本方法停止播放音乐文件后，该音乐文件会被自动卸载。

PauseAudioMixing

virtual void bytertc::IAudioMixingManager::PauseAudioMixing(
    int mix_id)

暂停播放音乐文件及混音

传入参数

注意

• 调用 StartAudioMixing 方法开始播放音乐文件及混音后，可以通过调用本方法暂停播放音乐文件及混音。
• 调用本方法暂停播放音乐文件及混音后，可调用 ResumeAudioMixing 方法恢复播放及混音。
• 调用本方法暂停播放音乐文件后，SDK 会向本地回调通知已暂停混音，见 OnAudioMixingStateChanged。

ResumeAudioMixing

virtual void bytertc::IAudioMixingManager::ResumeAudioMixing(
    int mix_id)

恢复播放音乐文件及混音

传入参数

注意

• 调用 PauseAudioMixing 方法暂停播放音乐文件及混音后，可以通过调用本方法恢复播放及混音。
• 调用本方法恢复播放音乐文件及混音后，SDK 会向本地回调通知音乐文件正在播放中，见 OnAudioMixingStateChanged。

PreloadAudioMixing

virtual void bytertc::IAudioMixingManager::PreloadAudioMixing(
    int mix_id,
    const char* file_path)

预加载指定音乐文件到内存中

传入参数

注意

• 需要频繁播放某个音乐文件的时候，调用本方法预加载该文件，在播放的时候可以只加载一次该文件，减少 CPU 占用。
• 本方法只是预加载指定音乐文件，只有调用 StartAudioMixing 方法才开始播放指定音乐文件。
• 调用本方法预加载音乐文件后，SDK 会回调通知音乐文件已加载，见 OnAudioMixingStateChanged。
• 调用本方法预加载的指定音乐文件可以通过 UnloadAudioMixing 卸载。

UnloadAudioMixing

virtual void bytertc::IAudioMixingManager::UnloadAudioMixing(
    int mix_id)

卸载指定音乐文件

传入参数

注意 不论音乐文件是否播放，调用本方法卸载该文件后，SDK 会回调通知混音已停止，见 OnAudioMixingStateChanged。

SetAudioMixingVolume

virtual void bytertc::IAudioMixingManager::SetAudioMixingVolume(
    int mix_id,
    int volume,
    AudioMixingType type)

调节混音的音量大小，包括音频文件混音和 PCM 混音。

传入参数

GetAudioMixingDuration

virtual int bytertc::IAudioMixingManager::GetAudioMixingDuration(
    int mix_id)

获取音乐文件时长

传入参数

返回值

• >0: 成功, 音乐文件时长，单位为毫秒。
• < 0: 失败

注意 调用本方法获取音乐文件时长前，需要先调用 PreloadAudioMixing 或 StartAudioMixing。

GetAudioMixingCurrentPosition

virtual int bytertc::IAudioMixingManager::GetAudioMixingCurrentPosition(
    int mix_id)

获取音乐文件播放进度

传入参数

返回值

• >0: 成功, 音乐文件播放进度，单位为毫秒。
• < 0: 失败

注意 调用本方法获取音乐文件播放进度前，需要先调用 StartAudioMixing 开始播放音乐文件。

SetAudioMixingPosition

virtual void bytertc::IAudioMixingManager::SetAudioMixingPosition(
    int mix_id,
    int position)

设置音频文件的起始播放位置

传入参数

注意

• 调用本方法你可以根据实际情况从指定的位置播放音频文件，无需从头到尾完整播放一个音频文件。
• 调用本方法设置音频文件起始播放位置前，需要先调用 StartAudioMixing 开始播放音频文件。

SetAudioMixingDualMonoMode

virtual void bytertc::IAudioMixingManager::SetAudioMixingDualMonoMode(
    int mix_id,
    AudioMixingDualMonoMode mode)

设置当前音频文件的声道模式

传入参数

注意

• 调用本方法设置音频文件的声道模式前，需要先调用 StartAudioMixing 开始播放音频文件。
• 此方法对 EnableAudioMixingFrame 播放的音乐无效。

SetAudioMixingPitch

virtual void bytertc::IAudioMixingManager::SetAudioMixingPitch(
    int mix_id,
    int pitch)

开启本地播放音乐文件变调功能，多用于 K 歌场景。
使用该方法，你可以对本地播放音乐文件的音调进行升调或降调等调整。

传入参数

注意 本方法需要在调用 StartAudioMixing 开始播放音频文件后、调用 StopAudioMixing 停止播放音频文件前使用，否则会触发 OnAudioMixingStateChanged 回调报错

SetAudioMixingProgressInterval

virtual void bytertc::IAudioMixingManager::SetAudioMixingProgressInterval(
    int mix_id,
    int64_t interval)

设置混音时音频文件播放进度回调的间隔

传入参数

注意 本方法需要在调用 StartAudioMixing 开始播放音频文件后、调用 StopAudioMixing 停止播放音频文件前使用，否则会触发 OnAudioMixingStateChanged 回调报错。 若想在音乐文件开始播放前设置播放进度回调间隔，你需调用 StartAudioMixing 在 AudioMixingConfig 中设置时间间隔，开始播放后可以通过此接口更新回调间隔。

SetAudioMixingLoudness

virtual void bytertc::IAudioMixingManager::SetAudioMixingLoudness(
    int mix_id,
    float loudness)

如果你需要使用 EnableVocalInstrumentBalance 对混音使音频文件/PCM 音频数据进行音量调整，你必须通过此接口传入其原始响度。

传入参数

注意 建议在 StartAudioMixing 开始播放音频文件之前调用该接口，以免播放过程中的音量突变导致听感体验下降。

EnableAudioMixingFrame

virtual void bytertc::IAudioMixingManager::EnableAudioMixingFrame(
    int mix_id,
    AudioMixingType type)

启动外部音频流混音 启动 PCM 音频数据混音。
要实现多个 PCM 音频数据混音，多次调用本方法，并传入不同的 mix_id。

传入参数

注意

• 必须先调用本方法启动 PCM 音频数据混音，随后调用 PushAudioMixingFrame 方法，才会开始混音。
• 如要结束 PCM 音频数据混音，使用 DisableAudioMixingFrame。

DisableAudioMixingFrame

virtual void bytertc::IAudioMixingManager::DisableAudioMixingFrame(
    int mix_id)

关闭 PCM 混音

传入参数

PushAudioMixingFrame

virtual int bytertc::IAudioMixingManager::PushAudioMixingFrame(
    int mix_id,
    IAudioFrame* audio_frame)

推送 PCM 音频帧数据用于混音

传入参数

返回值

• 0: 成功
• < 0: 失败

注意

• 调用该方法前，须通过 EnableAudioMixingFrame 启动外部音频流混音。
• 使用参考建议：首次推送数据，请在应用侧先缓存一定数据（如 100 毫秒），然后一次性推送过去；此后的推送操作定时 10 毫秒一次，并且每次的音频数据量为 10 毫秒数据量。要暂停播放，暂停推送即可。

GetAudioTrackCount

virtual int bytertc::IAudioMixingManager::GetAudioTrackCount(
    int mix_id)

获取当前音频文件的音轨索引

传入参数

返回值 方法调用结果

• ≥ 0：成功，返回当前音频文件的音轨索引
• < 0：方法调用失败

注意

• 调用本方法获取音频文件的音轨前，需要先调用 StartAudioMixing 开始播放音频文件。
• 此方法对 EnableAudioMixingFrame 播放的音频无效。

SelectAudioTrack

virtual void bytertc::IAudioMixingManager::SelectAudioTrack(
    int mix_id,
    int audio_track_index)

指定当前音频文件的播放音轨

传入参数

注意

• 调用本方法设置音频文件的音轨前，需要先调用 StartAudioMixing 开始播放音频文件。
• 此方法对 EnableAudioMixingFrame 播放的音乐无效。

IEncryptHandler

class bytertc::IEncryptHandler

加密/解密处理函数

成员函数

函数说明

OnEncryptData

virtual unsigned int bytertc::IEncryptHandler::OnEncryptData(
    const unsigned char* data,
    unsigned int length,
    unsigned char* buf,
    unsigned int buf_len)

自定义加密。
使用设定的自定义加密方式，对传输前的音视频帧数据进行加密。

传入参数

返回值 加密后的数据

• ≥ 0：加密后实际写入缓冲区的数据大小
• 0：丢弃该帧

注意

• 使用此接口进行自定义加密前，你必须先设置自定义加密方式，参看 SetCustomizeEncryptHandler。
• 使用 OnDecryptData 对已加密的音视频帧数据进行解密。
• 返回的数据大小应控制在原始数据的 90% ~ 120% 范围以内，不然将被丢弃。

OnDecryptData

virtual unsigned int bytertc::IEncryptHandler::OnDecryptData(
    const unsigned char* data,
    unsigned int length,
    unsigned char* buf,
    unsigned int buf_len)

自定义解密。
对自定义加密后的音视频帧数据进行解密。关于自定义加密，参看 OnEncryptData。

传入参数

返回值 加密后的数据

• ≥ 0：加密后实际写入缓冲区的数据大小
• 0：丢弃该帧

注意

• 使用此接口进行解密前，你必须先设定解密方式，参看 SetCustomizeEncryptHandler。
• 返回的数据大小应控制在原始数据的 90% ~ 120% 范围以内，不然将被丢弃。

IDeviceCollection

class bytertc::IDeviceCollection

音视频设备相关的信息

成员函数

函数说明

GetCount

virtual int bytertc::IDeviceCollection::GetCount()

获取当前系统内音视频设备数量

返回值 音视频设备数量

GetDevice

virtual int bytertc::IDeviceCollection::GetDevice(
    int index,
    char device_name[MAX_DEVICE_ID_LENGTH],
    char device_id[MAX_DEVICE_ID_LENGTH])

根据索引号，获取设备信息

传入参数

返回值

• 0：方法调用成功
• !0：方法调用失败

Release

virtual void bytertc::IDeviceCollection::Release()

释放当前 IDeviceCollection 对象占用的资源。

注意 不需要返回音视频设备相关信息列表时应该调用本方法释放相关资源。

IVideoDeviceManager

class bytertc::IVideoDeviceManager

主要用于枚举、设置视频采集设备

成员函数

函数说明

EnumerateVideoCaptureDevices

virtual IDeviceCollection* bytertc::IVideoDeviceManager::EnumerateVideoCaptureDevices()

获取当前系统内视频采集设备列表。

返回值 包含系统中所有视频采集设备的列表，参看 IDeviceCollection。

SetVideoCaptureDevice

virtual int bytertc::IVideoDeviceManager::SetVideoCaptureDevice(
    const char device_id[MAX_DEVICE_ID_LENGTH])

设置当前视频采集设备

传入参数

返回值

• 0：方法调用成功
• !0：方法调用失败

GetVideoCaptureDevice

virtual int bytertc::IVideoDeviceManager::GetVideoCaptureDevice(
    char device_id[MAX_DEVICE_ID_LENGTH])

获取当前 SDK 正在使用的视频采集设备信息

传入参数

返回值

• 0：方法调用成功
• !0：方法调用失败

IAudioDeviceManager

class bytertc::IAudioDeviceManager

音频设备管理类

成员函数

函数说明

EnumerateAudioPlaybackDevices

virtual IDeviceCollection* bytertc::IAudioDeviceManager::EnumerateAudioPlaybackDevices()

获取当前系统内音频播放设备列表。如果后续设备有变更，你会收到 OnMediaDeviceStateChanged 回调通知，然后需要重新调用本接口以获得新的设备列表。

返回值 包含系统中所有音频播放设备的列表，参看 IDeviceCollection。

EnumerateAudioCaptureDevices

virtual IDeviceCollection* bytertc::IAudioDeviceManager::EnumerateAudioCaptureDevices()

获取当前系统内音频采集设备列表。如果后续设备有变更，你需要重新调用本接口以获得新的设备列表。

返回值 一个包含系统中所有音频采集设备列表的对象，详见 IDeviceCollection。

注意 当不再使用返回的对象时，你需要调用 Release 进行释放。

SetAudioPlaybackDevice

virtual int bytertc::IAudioDeviceManager::SetAudioPlaybackDevice(
    const char device_id[MAX_DEVICE_ID_LENGTH])

设置音频播放设备。

传入参数

返回值

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

SetAudioCaptureDevice

virtual int bytertc::IAudioDeviceManager::SetAudioCaptureDevice(
    const char device_id[MAX_DEVICE_ID_LENGTH])

设置音频采集设备。

传入参数

返回值 方法调用结果

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

SetAudioPlaybackDeviceVolume

virtual int bytertc::IAudioDeviceManager::SetAudioPlaybackDeviceVolume(
    unsigned int volume)

设置当前音频播放设备音量

传入参数

返回值 方法调用结果

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

GetAudioPlaybackDeviceVolume

virtual int bytertc::IAudioDeviceManager::GetAudioPlaybackDeviceVolume(
    unsigned int* volume)

获取当前音频播放设备音量

传入参数

返回值 方法调用结果

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

SetAudioCaptureDeviceVolume

virtual int bytertc::IAudioDeviceManager::SetAudioCaptureDeviceVolume(
    unsigned int volume)

设置当前音频采集设备音量

传入参数

返回值 方法调用结果

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

GetAudioCaptureDeviceVolume

virtual int bytertc::IAudioDeviceManager::GetAudioCaptureDeviceVolume(
    unsigned int* volume)

获取当前音频采集设备音量

传入参数

返回值 方法调用结果

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

SetAudioPlaybackDeviceMute

virtual int bytertc::IAudioDeviceManager::SetAudioPlaybackDeviceMute(
    bool mute)

设置当前音频播放设备静音状态，默认为非静音。

传入参数

返回值 方法调用结果

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

GetAudioPlaybackDeviceMute

virtual int bytertc::IAudioDeviceManager::GetAudioPlaybackDeviceMute(
    bool* mute)

获取当前音频播放设备是否静音的信息。

传入参数

返回值 方法调用结果

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

SetAudioCaptureDeviceMute

virtual int bytertc::IAudioDeviceManager::SetAudioCaptureDeviceMute(
    bool mute)

设置当前音频采集设备静音状态，默认为非静音。

传入参数

返回值 方法调用结果

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

GetAudioCaptureDeviceMute

virtual int bytertc::IAudioDeviceManager::GetAudioCaptureDeviceMute(
    bool* mute)

获取当前音频采集设备是否静音的信息。

传入参数

返回值 方法调用结果

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

GetAudioPlaybackDevice

virtual int bytertc::IAudioDeviceManager::GetAudioPlaybackDevice(
    char device_id[MAX_DEVICE_ID_LENGTH])

获取当前音频播放设备 ID。

传入参数

返回值 方法调用结果

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

GetAudioCaptureDevice

virtual int bytertc::IAudioDeviceManager::GetAudioCaptureDevice(
    char device_id[MAX_DEVICE_ID_LENGTH])

获取当前音频采集设备 ID。

传入参数

返回值 方法调用结果

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

StartAudioPlaybackDeviceTest

virtual int bytertc::IAudioDeviceManager::StartAudioPlaybackDeviceTest(
    const char* test_audio_file_path)

启动音频播放设备测试。
该方法测试播放设备是否能正常工作。SDK 播放指定的音频文件，测试者如果能听到声音，说明播放设备能正常工作。

传入参数

返回值 方法调用结果

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

注意

• 该方法必须在 JoinRoom 前调用，且不可与其它音频设备测试功能同时应用。
• 你需调用 StopAudioPlaybackDeviceTest 停止测试。

StopAudioPlaybackDeviceTest

virtual int bytertc::IAudioDeviceManager::StopAudioPlaybackDeviceTest()

停止音频播放设备测试。

返回值 方法调用结果

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

注意 调用 StartAudioPlaybackDeviceTest 后，需调用本方法停止测试。

StartAudioCaptureDeviceTest

virtual int bytertc::IAudioDeviceManager::StartAudioCaptureDeviceTest(
    int indication_interval)

启动音频采集设备测试。
该方法测试音频采集设备是否能正常工作。启动测试后，会收到 OnLocalAudioPropertiesReport 回调上报的音量信息。

传入参数

返回值 方法调用结果

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

注意

• 该方法必须在 JoinRoom 前调用，且不可与其它音频设备测试功能同时应用。
• 你需调用 StopAudioCaptureDeviceTest 停止测试。

StopAudioCaptureDeviceTest

virtual int bytertc::IAudioDeviceManager::StopAudioCaptureDeviceTest()

停止音频采集设备测试。

返回值 方法调用结果

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

注意 调用 StartAudioCaptureDeviceTest 后，需调用本方法停止测试。

StartAudioDeviceLoopbackTest

virtual int bytertc::IAudioDeviceManager::StartAudioDeviceLoopbackTest(
    int indication_interval)

开始音频设备回路测试。
该方法测试音频采集设备和音频播放设备是否能正常工作。一旦测试开始，音频采集设备会采集本地声音 并通过音频播放设备播放出来，同时用户 App 会收到 OnLocalAudioPropertiesReport 回调上报的音量信息。

传入参数

返回值 方法调用结果

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

注意

• 该方法必须在 JoinRoom 前调用。且不可与其它音频设备测试功能同时应用。
• 你需调用 StopAudioDeviceLoopbackTest 停止测试。
• 该方法仅在本地进行音频设备测试，不涉及网络连接。

StopAudioDeviceLoopbackTest

virtual int bytertc::IAudioDeviceManager::StopAudioDeviceLoopbackTest()

停止音频设备回路测试。

返回值 方法调用结果

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

注意 调用 StartAudioDeviceLoopbackTest 后，需调用本方法停止测试。

InitAudioPlaybackDeviceForTest

virtual int bytertc::IAudioDeviceManager::InitAudioPlaybackDeviceForTest(
    const char deviceId[MAX_DEVICE_ID_LENGTH])

尝试初始化音频播放设备，可检测出设备不存在、权限被拒绝/禁用等异常问题。

传入参数

返回值 设备状态错误码

• 0: 设备检测结果正常
• -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测
• -2: 采集设备无麦克风权限，尝试初始化设备失败
• -3: 设备不存在，当前没有设备或设备被移除时返回
• -4: 设备音频格式不支持
• -5: 其它原因错误

注意 1. 该接口需在进房前调用； 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。

InitAudioCaptureDeviceForTest

virtual int bytertc::IAudioDeviceManager::InitAudioCaptureDeviceForTest(
    const char deviceId[MAX_DEVICE_ID_LENGTH])

尝试初始化音频采集设备，可检测设备不存在、权限被拒绝/禁用等异常问题。

传入参数

返回值 设备状态错误码

• 0: 设备检测结果正常
• -1: 接口状态不正确，例如在正常启动采集后再调用该接口进行检测
• -2: 采集设备无麦克风权限，尝试初始化设备失败
• -3: 设备不存在，当前没有设备或设备被移除时返回
• -4: 设备音频格式不支持
• -5: 其它原因错误

注意 1. 该接口需在进房前调用; 2. 检测成功不代表设备一定可以启动成功，还可能因设备被其他应用进程独占，或 CPU/内存不足等原因导致启动失败。

IRtcEngine

class bytertc::IRtcEngine

引擎API IRtcEngine用IRtcEngineEventHandler 注册接口类方法向应用程序发送回调通知

成员函数

函数说明

JoinRoom

virtual int bytertc::IRtcEngine::JoinRoom(
    const char* token,
    const char* room_id,
    const UserInfo& user_info,
    const RTCRoomConfig& room_config)

创建/加入房间：房间不存在时即创建房间；房间存在时即加入这个房间。
同一房间内的用户间可以相互通话。
进房后重复调用无效，用户必须调用 LeaveRoom 退出当前房间后，才能加入下一个房间。

传入参数

返回值

• 0: 成功
• -1：失败。room_id / user_info.uid 包含了无效的参数
• -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 LeaveRoom:LeaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。

注意

• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 OnError 回调通知，错误类型详见 ErrorCode 中的 kErrorCodeDuplicateLogin。
• 本地用户调用此方法加入房间成功后，会收到 OnJoinRoomResult 回调通知。
• 本地用户调用 SetUserVisibility 将自身设为可见后加入房间，远端用户会收到 OnUserJoined。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 OnJoinRoomResult 回调通知；如果加入房间的用户可见，远端用户会收到 OnUserJoined。

IScreenCaptureSourceList

class bytertc::IScreenCaptureSourceList

屏幕源类型信息列表

成员函数

函数说明

GetCount

virtual int32_t bytertc::IScreenCaptureSourceList::GetCount()

获取列表大小

返回值 获取列表大小

GetSourceInfo

virtual ScreenCaptureSourceInfo bytertc::IScreenCaptureSourceList::GetSourceInfo(
    int32_t index)

根据索引，获取屏幕共享列表中的元素

传入参数

返回值 屏幕源类型信息

注意 返回类型中有char*类型的字符串，该字符串在本对象Release后释放，请注意内存管理。

Release

virtual void bytertc::IScreenCaptureSourceList::Release()

析构当前对象，释放内存

注意 严禁调用 delete 该结构体，该结构不需要的时候应该调用本函数释放资源

IRtcEngineLite

class bytertc::IRtcEngineLite

引擎 API

成员函数

函数说明

SetEarMonitorMode

virtual void bytertc::IRtcEngineLite::SetEarMonitorMode(
    EarMonitorMode mode)

开启/关闭耳返功能

传入参数

SetEarMonitorVolume

virtual void bytertc::IRtcEngineLite::SetEarMonitorVolume(
    const int volume)

设置耳返的音量

传入参数

注意

• 设置耳返音量前，你必须先调用 SetEarMonitorMode 打开耳返功能。
• 耳返功能仅在使用 RTC SDK 提供的内部音频采集功能，并连接了有线耳机时有效。

SetVoiceChangerType

virtual int bytertc::IRtcEngineLite::SetVoiceChangerType(
    VoiceChangerType voice_changer)

设置变声特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 SetVoiceReverbType 互斥，后设置的特效会覆盖先设置的特效。

SetVoiceReverbType

virtual int bytertc::IRtcEngineLite::SetVoiceReverbType(
    VoiceReverbType voice_reverb)

设置混响特效类型

传入参数

注意

• 在进房前后都可设置。
• 对 RTC SDK 内部采集的音频和自定义采集的音频都生效。
• 只对单声道音频生效。
• 只在包含美声特效能力的 SDK 中有效。
• 与 SetVoiceChangerType 互斥，后设置的特效会覆盖先设置的特效。

SetAudioProfile

virtual void bytertc::IRtcEngineLite::SetAudioProfile(
    AudioProfileType audio_profile)

设置音质档位。你应根据业务场景需要选择适合的音质档位。

传入参数

注意

• 该方法在进房前后均可调用；
• 支持通话过程中动态切换音质档位。

MuteLocalAudio

virtual void bytertc::IRtcEngineLite::MuteLocalAudio(
    MuteState mute_state)

控制本地音频流的发送状态：发送/不发送
非隐身用户使用此方法后，房间中的其他用户会收到回调： OnUserMuteAudio

传入参数

注意

• 本方法仅控制本地音频流的发送状态，并不影响本地音频采集状态。
• 无论是否开启音频采集，你都可以启动发送本地音频流。如果在采集前启用发送，音频将在采集开始后立即发送。

EnableExternalAudioDevice

virtual void bytertc::IRtcEngineLite::EnableExternalAudioDevice(
    const AudioFormat &recording_format,
    const AudioFormat &playback_format)

启用自定义音频采集渲染

传入参数

注意

• 该方法需要在进房前调用。
• 启用自定义音频采集渲染的状态在离开房间后仍然有效，会一直持续到调用 DisableExternalAudioDevice 关闭自定义音频采集渲染为止。
• 必须同时启用自定义音频采集和自定义音频渲染，或同时启用内部音频采集和内部音频渲染。默认使用内部音频采集和渲染。
• 启用自定义音频采集渲染后，仍需要使用 PushExternalAudioFrame，推送外部音频数据，再使用 PullExternalAudioFrame 拉取外部音频数据。
• 当你调用此 API 由内部采集切换至自定义音频采集时，SDK 会自动关闭内部采集。
• 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用 DisableExternalAudioDevice 关闭自定义采集，然后调用 StartAudioCapture 手动开启内部采集。

DisableExternalAudioDevice

virtual void bytertc::IRtcEngineLite::DisableExternalAudioDevice()

禁用自定义音频采集和渲染。

注意

• 如果已开启自定义采集，需要切换至内部采集，必须禁用已开启的自定义音频采集和渲染，然后调用 StartAudioCapture 手动开启内部采集。
• 要启用自定义音频采集和渲染，调用 EnableExternalAudioDevice。

PushExternalAudioFrame

virtual bool bytertc::IRtcEngineLite::PushExternalAudioFrame(
    int8_t* data,
    int samples)

推送自定义音频数据。

传入参数

返回值 方法调用结果

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

注意

• 推送自定义采集的音频数据前，必须先调用 EnableExternalAudioDevice 开启自定义采集。
• 你必须每 10 us 推送一次数据
• 该函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。

PullExternalAudioFrame

virtual bool bytertc::IRtcEngineLite::PullExternalAudioFrame(
    int8_t* data,
    int samples)

拉取远端音频数据。使用 EnableExternalAudioDevice 启用自定义音频采集渲染后，可以使用本方法拉取远端音频数据。

传入参数

返回值 方法调用结果

• true:方法调用成功
• false：方法调用失败

注意

• 必须是 pcm 数据，拉取间隔是 10ms，音频采样格式为 s16。
• 该函数运行在用户调用线程内，是一个同步函数

SetVideoEncoderConfig

virtual int bytertc::IRtcEngineLite::SetVideoEncoderConfig(
    StreamIndex index,
    const VideoSolution* solutions,
    int solution_num)

设置推送多路流时的各路视频参数，包括分辨率、帧率、码率、缩放模式、网络不佳时的回退策略等。

传入参数

返回值

• 0：成功
• !0：失败

注意

• 当使用内部采集时，视频采集的分辨率、帧率会根据最大的编码分辨率、帧率进行适配
• 默认的视频编码参数为：分辨率 640px
• 变更编码分辨率后马上生效，可能会引发相机重启。
• 屏幕流只取视频参数数组的第一组数据。

MuteLocalVideo

virtual void bytertc::IRtcEngineLite::MuteLocalVideo(
    MuteState muteState)

停止/启动发送本地视频流，默认不发送。
无论你使用内部视频采集，还是自定义视频采集，你都应使用此接口启动发送本地视频流。
调用该方法后，房间中的其他用户会收到 OnUserMuteVideo 的回调。

传入参数

注意

• 本方法只是停止/启动本地视频流的发送，不影响视频采集状态。
• 无论是否开启视频采集，你都可以启动发送本地视频流。如果在采集前启用发送，视频将在采集开始后立即发送。

PushScreenFrame

virtual bool bytertc::IRtcEngineLite::PushScreenFrame(
    IVideoFrame* frame)

推送屏幕视频帧

传入参数

返回值

• true: 成功；
• false: 失败；

注意

• 暂时只支持 YUV420P 格式的视频帧。
• 该函数运行在用户调用线程内，即将销毁 RtcEngine 实例前，请停止调用该函数推送屏幕共享数据

StartScreenCaptureByDisplayId

virtual int bytertc::IRtcEngineLite::StartScreenCaptureByDisplayId(
    unsigned int display_id,
    const Rectangle& region_rect,
    const DesktopCaptureParameters& capture_params)

废弃
since 327.1, use StartScreenVideoCapture and PublishScreen instead

通过屏幕 id 共享屏幕，共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 id 。

传入参数

返回值

• 0: 成功；
• -1: 失败；

注意 共享一个窗口或该窗口的部分区域。需要在该方法中指定想要共享的窗口 id 。

StartScreenCapture

virtual int bytertc::IRtcEngineLite::StartScreenCapture(
    void* context,
    const char* group_id,
    const DesktopCaptureParameters& capture_params)

废弃
since 327.1, use StartScreenVideoCapture and PublishScreen instead

通过传入的Context开启屏幕共享。

传入参数

返回值

• 0: 成功；
• -1: 失败；

注意 开启屏幕共享，移动端专用接口。

StopScreenCapture

virtual void bytertc::IRtcEngineLite::StopScreenCapture()

废弃
since 327.1, use StopScreenVideoCapture instead

停止屏幕或者窗口共享。

注意

• 本函数必须在 StartScreenVideoCapture 之后调用
• 本函数不可和 PublishScreen 、UnpublishScreen 混用。

SetVideoSourceType

virtual void bytertc::IRtcEngineLite::SetVideoSourceType(
    StreamIndex stream_index,
    VideoSourceType type)

设置向 SDK 输入的视频源 默认使用内部采集。内部采集指：使用 RTC SDK 内置的视频采集机制进行视频采集。

传入参数

注意

• 该方法进房前后均可调用。
• 当你已调用 StartVideoCapture 开启内部采集后，再调用此方法切换至自定义采集时，SDK 会自动关闭内部采集。
• 当你调用此方法开启自定义采集后，想要切换至内部采集，你必须先调用此方法关闭自定义采集，然后调用 StartVideoCapture 手动开启内部采集。
• 当你需要向 SDK 推送自定义编码后的视频帧，你需调用该方法将视频源切换至自定义编码视频源。

PushExternalVideoFrame

virtual bool bytertc::IRtcEngineLite::PushExternalVideoFrame(
    IVideoFrame* frame)

发送外部源视频数据

传入参数

注意 推送外部视频帧前，必须调用 SetVideoSourceType 开启外部视频源采集。

SetAudioPlaybackDevice

virtual int bytertc::IRtcEngineLite::SetAudioPlaybackDevice(
    AudioPlaybackDevice device)

设置音频播放设备，默认使用扬声器。
音频播放设备发生变化时，会收到 OnAudioPlaybackDeviceChanged 回调。

传入参数

返回值 方法调用结果

• 0: 方法调用成功
• < 0: 方法调用失败

注意

• 1. 该接口仅适用于移动设备。
• 1. 该方法只支持将音视频播放设备设置为听筒或者扬声器。当 App 连接有线或蓝牙音频播放设备时，SDK 会自动切换到有线或蓝牙音频播放设备。主动设置为有线或蓝牙音频播放设备，会返回调用失败。

• 3. 若连接有线或者蓝牙音频播放设备时，将音频播放设备设置为扬声器或听筒将调用成功，但不会立马切换到扬声器或听筒，会在有线或者蓝牙音频播放设备移除后，根据设置自动切换到听筒或者扬声器。

• 1. 通话前和通话中都可以调用该方法。

CreateRtcRoom

virtual IRtcRoom* bytertc::IRtcEngineLite::CreateRtcRoom(
    const char* room_id)

创建房间 多次调用此方法以创建多个 IRTCRoom 实例。分别调用各 IRTCRoom 实例中的 JoinRoom 方法，同时加入多个房间。多房间模式下，用户可以同时订阅各房间的音视频流。

传入参数

返回值 IRtcRoom 实例

注意 如果你需要在多个房间发布音视频流，无须创建多房间，直接调用 startForwardStreamToRooms。

SetPublishFallbackOption

virtual int bytertc::IRtcEngineLite::SetPublishFallbackOption(
    PublishFallbackOption option)

设置发布的音视频流回退选项
你可以调用这个接口来设置网络情况不佳或设备性能不足时只发送小流，以保证通话质量。

传入参数

返回值

• 0: 方法调用成功
• < 0: 方法调用失败

注意

• 这个方法只在设置了发送多个流的情况下有效。
• 你必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，本端发布的音视频流发生回退或从回退中恢复时，订阅该音视频流的客户端会收到 OnSimulcastSubscribeFallback 回调通知。
• 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

SetSubscribeFallbackOption

virtual int bytertc::IRtcEngineLite::SetSubscribeFallbackOption(
    SubscribeFallbackOption option)

设置订阅的音视频流回退选项
你可以通过调用该接口来设置网络情况不佳或性能不足时只订阅小流或音频流，以保证通话流畅。

传入参数

返回值 0: 方法调用成功

• < 0: 方法调用失败

注意

• 你必须在进房前设置，进房后设置或更改设置无效。
• 设置回退选项后，本端订阅的音视频流发生回退或从回退中恢复时,会收到 OnSimulcastSubscribeFallback 回调通知。
• 设置回退选项后，本端订阅的视频流因为回退分辨率发生变化时,会收到 OnRemoteVideoSizeChanged 回调通知。
• 你可以调用 API 或者在服务端下发策略设置回退。当使用服务端下发配置实现时，下发配置优先级高于在客户端使用 API 设定的配置。

SetRemoteUserPriority

virtual int bytertc::IRtcEngineLite::SetRemoteUserPriority(
    const char* user_id,
    RemoteUserPriority priority)

设置用户优先级

传入参数

返回值 0: 方法调用成功

• < 0: 方法调用失败

注意

• 1. 该方法与 SetSubscribeFallbackOption 搭配使用。
• 1. 如果开启了订阅流回退选项，弱网或性能不足时会优先保证收到的高优先级用户的流的质量。
• 1. 该方法在进房前后都可以使用，可以修改远端用户的优先级。

SetBusinessId

virtual int bytertc::IRtcEngineLite::SetBusinessId(
    const char* business_id)

设置业务标识参数
可通过 businessId 区分不同的业务场景。businessId 由客户自定义，相当于一个“标签”，可以分担和细化现在 AppId 的逻辑划分的功能，但不需要鉴权。

传入参数

返回值

• 0： 成功
• < 0： 失败，具体原因参照 BusinessCheckCode 。
• -6001： 用户已经在房间中。
• -6002： 输入非法，合法字符包括所有小写字母、大写字母和数字，除此外还包括四个独立字符，分别是：英文句号，短横线，下划线和 @ 。

注意

• 需要在调用 JoinRoom 之前调用，JoinRoom之后调用该方法无效。

SetLocalVideoMirrorMode

virtual void bytertc::IRtcEngineLite::SetLocalVideoMirrorMode(
    MirrorMode mirrorMode)

废弃
since 329.1, use SetLocalVideoMirrorType instead

设置采用前置摄像头采集时，是否开启镜像模式。

传入参数

SetLocalVideoMirrorType

virtual void bytertc::IRtcEngineLite::SetLocalVideoMirrorType(
    MirrorType mirrorType)

为采集到的视频流开启镜像

传入参数

注意

• 切换视频源不影响镜像设置。
• 屏幕视频流始终不受镜像设置影响。
• 该接口调用前，各视频源的初始状态如下：

SetEncryptInfo

virtual void bytertc::IRtcEngineLite::SetEncryptInfo(
    EncryptType encrypt_type,
    const char* key,
    int key_size)

设置传输时使用内置加密的方式

传入参数

注意

• 使用传输时内置加密时，使用此方法；如果需要使用传输时自定义加密，参看 OnEncryptData。 内置加密和自定义加密互斥，根据最后一个调用的方法确定传输是加密的方案。
• 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。

SetCustomizeEncryptHandler

virtual void bytertc::IRtcEngineLite::SetCustomizeEncryptHandler(
    IEncryptHandler* handler)

设置自定义加密
需要实现对应的加密/解密方法，详情参考 EncryptType 。

传入参数

注意

• 该方法与 SetEncryptInfo 为互斥关系， 只能选择自定义加密方式或者默认加密方式。最终生效的加密方式取决于最后一个调用的方法。

• 该方法必须在进房之前调用，可重复调用，以最后调用的参数作为生效参数。

• 无论加密或者解密，其对原始数据的长度修改，需要控制在 90% ~ 120% 之间，即如果输入数据为 100 字节，则处理完成后的数据必须在 90 至 120 字节之间，如果加密或解密结果超出该长度限制，则该音视频帧会被丢弃。

+ 数据加密/解密为串行执行，因而视实现方式不同，可能会影响到最终渲染效率。是否使用该方法，需要由使用方谨慎评估。

RegisterAudioFrameObserver

virtual void bytertc::IRtcEngineLite::RegisterAudioFrameObserver(
    IAudioFrameObserver* observer)

注册音频数据回调观察者。
成功注册后，IAudioFrameObserver 会触发相关回调。

传入参数

注意 通过以下的三个 API，你可以对回调的音频数据进行相关设置：SetRecordingAudioFrameParameters、 SetPlaybackAudioFrameParameters、 SetMixedAudioFrameParameters

RegisterLocalAudioProcessor

virtual void bytertc::IRtcEngineLite::RegisterLocalAudioProcessor(
    IAudioProcessor* processor,
    AudioFormat audioFormat)

设置自定义音频处理器。
使用该处理器，你可以调用 ProcessAudioFrame 对 RTC SDK 采集得到的音频帧进行自定义处理，并将处理后的音频帧用于 RTC 音视频通信。
SDK 只持有 processor 的弱引用，你应保证其生命周期。

传入参数

注意 重复调用此接口时，仅最后一次调用生效。效果不会叠加。

RegisterVideoFrameObserver

virtual void bytertc::IRtcEngineLite::RegisterVideoFrameObserver(
    IVideoFrameObserver* observer)

注册视频数据回调观察者

传入参数

注意 该方法可以在任意时间调用，建议在 JoinRoom 前。

RegisterLocalVideoProcessor

virtual int bytertc::IRtcEngineLite::RegisterLocalVideoProcessor(
    IVideoProcessor* processor,
    VideoPreprocessorConfig config)

设置自定义视频前处理器。
使用这个视频前处理器，你可以调用 ProcessVideoFrame 对 RTC SDK 采集得到的视频帧进行前处理，并将处理后的视频帧用于 RTC 音视频通信。

传入参数

返回值

• 0：方法调用成功
• !0：方法调用失败

注意

• 对于 Windows 平台，经前处理返回的视频帧格式仅支持 kVideoPixelFormatI420
• 对于 Windows 平台，将 config 中的 required_pixel_format 设置为 kVideoPixelFormatI420，可以通过避免格式转换带来一些性能优化。
• 重复调用此接口时，仅最后一次调用生效。效果不会叠加。

SendSEIMessage

virtual int bytertc::IRtcEngineLite::SendSEIMessage(
    StreamIndex stream_index,
    const uint8_t* message,
    int length,
    int repeat_count)

在视频通信时，通过视频帧发送 SEI 数据。

传入参数

返回值

• >=0: 将被添加到视频帧中的 SEI 的数量
• < 0: 发送失败

注意

• 你可以通过此接口对 RTC SDK 内部采集的视频帧添加 SEI。对于采用自定义采集获得的视频帧：如果原视频帧中没有添加 SEI 数据，那么你可以调用此接口为其中添加 SEI 信息后，进行编码传输；如果原视频帧中已添加了 SEI 数据，那么，调用此接口不生效。
• 如果调用此接口之后的 2s 内，没有可带 SEI 的视频帧（比如没有开启视频采集和传输），那么，SEI 数据不会被加进视频帧中。
• 消息发送成功后，远端会收到 OnSEIMessageReceived 回调。

GetPositionAudioRender

virtual IPositionAudioRenderInterface* bytertc::IRtcEngineLite::GetPositionAudioRender()

获取位置音频接口实例，包括范围语音、空间语音等和位置相关的音频接口。

返回值 位置音频管理接口实例。如果返回 NULL，则表示不支持空间音频，详见 IPositionAudioRenderInterface 。

注意

• 只有在使用支持真双声道播放的设备时，才能开启空间音频效果；
• 在网络状况不佳的情况下，即使开启了这一功能，也不会产生空间音频效果；
• 机型性能不足可能会导致音频卡顿，使用低端机时，不建议开启空间音频效果；
• 空间音频效果在启用服务端选路功能时，不生效。

StartFileRecording

virtual int bytertc::IRtcEngineLite::StartFileRecording(
    StreamIndex type,
    RecordingConfig config)

该方法将通话过程中的音视频数据录制到本地的文件中。

传入参数

返回值

• 0: 正常
• -1: 参数设置异常
• -2: 当前版本 SDK 不支持该特性，请联系技术支持人员

注意

• 调用该方法后，你会收到 OnRecordingStateUpdate 回调。
• 如果录制正常，系统每秒钟会通过 OnRecordingProgressUpdate 回调通知录制进度。

StopFileRecording

virtual void bytertc::IRtcEngineLite::StopFileRecording(
    StreamIndex type)

停止本地录制

传入参数

注意

• 调用 StartFileRecording 开启本地录制后，你必须调用该方法停止录制。
• 调用该方法后，你会收到 OnRecordingStateUpdate 回调提示录制结果。

SetRuntimeParameters

virtual void bytertc::IRtcEngineLite::SetRuntimeParameters(
    const char * json_string)

设置运行时的参数

传入参数

StartASR

virtual void bytertc::IRtcEngineLite::StartASR(
    const RTCASRConfig& asr_config,
    IRTCASREngineEventHandler* handler)

开启自动语音识别服务。该方法将识别后的用户语音转化成文字，并通过 OnMessage 事件回调给用户。

传入参数

StopASR

virtual void bytertc::IRtcEngineLite::StopASR()

关闭语音识别服务

Feedback

virtual int bytertc::IRtcEngineLite::Feedback(
    const char* data)

本次通话质量打分评价

传入参数

返回值

• 0: 上报成功
• -1: 上报失败，还没加入过房间
• -2: 上报失败，传入 JSON 解析失败
• -3: 上报失败，传入 JSON 字段缺失

注意 如果用户上报时在房间内，那么问题会定位到用户当前所在的一个或多个房间；如果用户上报时不在房间内，那么问题会定位到引擎此前退出的房间。

GetAudioMixingManager

virtual IAudioMixingManager* bytertc::IRtcEngineLite::GetAudioMixingManager()

混音管理接口创建

返回值 混音管理实例，详见IAudioMixingManager

Login

virtual void bytertc::IRtcEngineLite::Login(
    const char* token,
    const char* uid)

必须先登录注册一个 uid，才能发送房间外消息和向业务服务器发送消息

传入参数

注意

• 在调用本接口登录后，如果想要登出，需要调用 Logout。
• 本地用户调用此方法登录后，会收到 OnLoginResult 回调通知登录结果，远端用户不会收到通知。

Logout

virtual void bytertc::IRtcEngineLite::Logout()

调用本接口登出后，无法调用房间外消息以及端到服务器消息相关的方法或收到相关回调。

注意

• 调用本接口登出前，必须先调用 Login 登录。
• 本地用户调用此方法登出后，会收到 OnLogout 回调通知结果，远端用户不会收到通知。

UpdateLoginToken

virtual void bytertc::IRtcEngineLite::UpdateLoginToken(
    const char* token)

更新用户用于登录的 Token
Token 有一定的有效期，当 Token 过期时，需调用此方法更新登录的 Token 信息。
调用 Login 方法登录时，如果使用了过期的 Token 将导致登录失败，并会收到 OnLoginResult 回调通知，错误码为 kLoginErrorCodeInvalidToken。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意

• 如果 Token 无效导致登录失败，则调用此方法更新 Token 后，SDK 会自动重新登录，而用户不需要自己调用 Login 方法。
• Token 过期时，如果已经成功登录，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 登录时，或因本地网络状况不佳导致断网重新登录时通知给用户。

SetServerParams

virtual void bytertc::IRtcEngineLite::SetServerParams(
    const char* signature,
    const char* url)

设置业务服务器参数
客户端调用 SendServerMessage 或 SendServerBinaryMessage 发送消息给业务服务器之前，必须设置有效签名和业务服务器地址。

传入参数

注意

• 用户必须调用 Login 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 OnServerParamsSetResult 返回相应结果。

GetPeerOnlineStatus

virtual void bytertc::IRtcEngineLite::GetPeerOnlineStatus(
    const char* peer_user_id)

查询对端用户或本端用户的登录状态

传入参数

注意

• 必须调用 Login 登录后，才能调用本接口。
• 调用本接口后，SDK 会使用 OnGetPeerOnlineStatus 回调通知查询结果。
• 在发送房间外消息之前，用户可以通过本接口了解对端用户是否登录，从而决定是否发送消息。也可以通过本接口查询自己查看自己的登录状态。

SendUserMessageOutsideRoom

virtual int64_t bytertc::IRtcEngineLite::SendUserMessageOutsideRoom(
    const char* uid,
    const char* message)

给房间外指定的用户发送文本消息（P2P）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，RtcEngine 实例未创建
• -2：发送失败，uid 为空

注意

• 在发送房间外文本消息前，必须先调用 Login 完成登录。
• 用户调用本接口发送文本信息后，会收到一次 OnUserMessageSendResultOutsideRoom 回调，得知消息是否成功发送。
• 若文本消息发送成功，则 uid 所指定的用户会通过 OnUserMessageReceivedOutsideRoom 回调收到该消息。

SendUserBinaryMessageOutsideRoom

virtual int64_t bytertc::IRtcEngineLite::SendUserBinaryMessageOutsideRoom(
    const char* uid,
    int length,
    const uint8_t* message)

给房间外指定的用户发送二进制消息（P2P）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，RtcEngine 实例未创建
• -2：发送失败，uid 为空

注意

• 在发送房间外二进制消息前，必须先调用 Login 完成登录。
• 用户调用本接口发送二进制消息后，会收到一次 OnUserMessageSendResultOutsideRoom 回调，通知消息是否发送成功。
• 若二进制消息发送成功，则 uid 所指定的用户会通过 OnUserBinaryMessageReceivedOutsideRoom 回调收到该条消息。

SendServerMessage

virtual int64_t bytertc::IRtcEngineLite::SendServerMessage(
    const char* message)

客户端给业务服务器发送文本消息（P2Server）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，RtcEngine 实例未创建

注意

• 在向业务服务器发送文本消息前，必须先调用 Login 完成登录，随后调用 SetServerParams 设置业务服务器。
• 调用本接口后，会收到一次 OnServerMessageSendResult 回调，通知消息发送方是否发送成功。
• 若文本消息发送成功，则之前调用 SetServerParams 设置的业务服务器会收到该条消息。

SendServerBinaryMessage

virtual int64_t bytertc::IRtcEngineLite::SendServerBinaryMessage(
    int length,
    const uint8_t* message)

客户端给业务服务器发送二进制消息（P2Server）

传入参数

返回值

• >0：发送成功，返回这次发送消息的编号，从 1 开始递增
• -1：发送失败，RtcEngine 实例未创建

注意

• 在向业务服务器发送二进制消息前，必须先调用 Login 完成登录，随后调用 SetServerParams 设置业务服务器。
• 调用本接口后，会收到一次 OnServerMessageSendResult 回调，通知消息发送方发送成功或失败。
• 若二进制消息发送成功，则之前调用 SetServerParams 设置的业务服务器会收到该条消息。

StartNetworkDetection

virtual NetworkDetectionStartReturn bytertc::IRtcEngineLite::StartNetworkDetection(
    bool is_test_uplink,
    int expected_uplink_bitrate,
    bool is_test_downlink,
    int expected_downlink_biterate)

开启通话前网络探测

传入参数

返回值 开启通话前网络探测结果，详见 NetworkDetectionStartReturn

注意

• 成功调用本接口后，每 2s 会收到一次 OnNetworkDetectionResult 回调，通知探测结果；
• 若探测停止，则会收到一次 OnNetworkDetectionStopped 通知探测停止。

StopNetworkDetection

virtual void bytertc::IRtcEngineLite::StopNetworkDetection()

停止通话前网络探测

注意

• 调用本接口后，会收到一次 OnNetworkDetectionStopped 回调通知探测停止。

SetScreenAudioSourceType

virtual void bytertc::IRtcEngineLite::SetScreenAudioSourceType(
    AudioSourceType source_type)

在屏幕共享时，设置屏幕音频的采集方式（内部采集/自定义采集）

传入参数

注意

• 默认采集方式是 RTC SDK 内部采集。
• 你应该在 PublishScreen 前，调用此方法。否则，你将收到 OnWarning 的报错：kWarningCodeSetScreenAudioSourceTypeFailed
• 如果设定为内部采集，你必须再调用 StartScreenAudioCapture 开始采集；
• 如果设定为自定义采集，你必须再调用 PushScreenAudioFrame 将自定义采集到的屏幕音频帧推送到 RTC SDK。
• 无论是内部采集还是自定义采集，你都必须调用 PublishScreen 将采集到的屏幕音频推送到远端。

SetScreenAudioStreamIndex

virtual void bytertc::IRtcEngineLite::SetScreenAudioStreamIndex(
    StreamIndex index)

在屏幕共享时，设置屏幕音频流和麦克风采集到的音频流的混流方式

传入参数

注意 你应该在 PublishScreen 之前，调用此方法。否则，你将收到 OnWarning 的报错：kWarningCodeSetScreenAudioStreamIndexFailed

PushScreenAudioFrame

virtual int bytertc::IRtcEngineLite::PushScreenAudioFrame(
    IAudioFrame* frame)

使用自定义采集方式，采集屏幕共享时的屏幕音频时，将音频帧推送至 RTC SDK 处进行编码等处理。

传入参数

返回值 方法调用结果

• 0: 设置成功
• < 0: 设置失败

注意

• 调用此接口推送屏幕共享时的自定义采集的音频数据前，必须调用 SetScreenAudioSourceType 开启屏幕音频自定义采集。
• 你应每隔 10 毫秒，调用一次此方法推送一次自定义采集的音频帧。一次推送的音频帧中应包含 frame.sample_rate / 100 个音频采样点。比如，假如采样率为 48000Hz，则每次应该推送 480 个采样点。
• 音频采样格式为 S16。音频缓冲区内的数据格式必须为 PCM 数据，其容量大小应该为 samples
• 此函数运行在用户级线程内。若同时运行其他进程，将导致本进程中断。
• 调用此接口将自定义采集的音频帧推送到 RTC SDK 后，你必须调用 PublishScreen 将采集到的屏幕音频推送到远端。在调用 PublishScreen 前，推送到 RTC SDK 的音频帧信息会丢失。

EnableAudioPropertiesReport

virtual void bytertc::IRtcEngineLite::EnableAudioPropertiesReport(
    const AudioPropertiesConfig& config)

启用音频信息提示。

传入参数

注意 开启提示后，你可以： + 通过 OnLocalAudioPropertiesReport 回调获取本地麦克风和屏幕音频流采集的音频信息；

• 通过 OnRemoteAudioPropertiesReport 回调获取订阅的远端用户的音频信息。

EnableVocalInstrumentBalance

virtual void bytertc::IRtcEngineLite::EnableVocalInstrumentBalance(
    bool enable)

开启/关闭音量均衡功能。
开启音量均衡功能后，人声的响度会调整为 -16lufs。如果已调用 SetAudioMixingLoudness 传入了混音音乐的原始响度，此音乐播放时，响度会调整为 -20lufs。

传入参数

注意 该接口须在调用 StartAudioMixing 开始播放音频文件之前调用。

EnablePlaybackDucking

virtual void bytertc::IRtcEngineLite::EnablePlaybackDucking(
    bool enable)

打开/关闭音量闪避功能，适用于“一起看”等场景。
开启该功能后，当检测到远端人声时，本地的媒体播放音量会自动减弱，从而保证远端人声的清晰可辨；当远端人声消失时，本地媒体音量会恢复到闪避前的音量水平。

传入参数

RegisterLocalEncodedVideoFrameObserver

virtual void bytertc::IRtcEngineLite::RegisterLocalEncodedVideoFrameObserver(
    ILocalEncodedVideoFrameObserver* observer)

注册本地视频帧监测器。
无论使用内部采集还是自定义采集，调用该方法后，SDK 每监测到一帧本地视频帧时，都会将视频帧信息通过 OnLocalEncodedVideoFrame 回调给用户

传入参数

注意 该方法可在进房前后的任意时间调用，在进房前调用可保证尽可能早地监测视频帧并触发回调

RegisterRemoteEncodedVideoFrameObserver

virtual void bytertc::IRtcEngineLite::RegisterRemoteEncodedVideoFrameObserver(
    IRemoteEncodedVideoFrameObserver* observer)

注册远端编码后视频数据回調。
完成注册后，当 SDK 监测到远端编码后视频帧时，会触发 OnRemoteEncodedVideoFrame 回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

SetExternalVideoEncoderEventHandler

virtual void bytertc::IRtcEngineLite::SetExternalVideoEncoderEventHandler(
    IExternalVideoEncoderEventHandler* encoder_handler)

注册自定义编码帧推送事件回调

传入参数

注意

• 该方法需在进房前调用。
• 引擎销毁前需取消注册，调用该方法将参数设置为 nullptr 即可。

PushExternalEncodedVideoFrame

virtual bool bytertc::IRtcEngineLite::PushExternalEncodedVideoFrame(
    StreamIndex index,
    int video_index,
    IEncodedVideoFrame* video_stream)

推送自定义编码后的视频流

传入参数

注意

• 目前仅支持推送 H264 和 ByteVC1 格式的视频帧。
• 该函数运行在用户调用线程内
• 推送自定义编码视频帧前，必须调用 SetVideoSourceType 将视频输入源切换至自定义编码视频源。

SetVideoDecoderConfig

virtual void bytertc::IRtcEngineLite::SetVideoDecoderConfig(
    RemoteStreamKey key,
    VideoDecoderConfig config)

在订阅远端视频流之前，设置远端视频数据解码方式

传入参数

注意

• 该方法近适用于手动订阅模式，并且在订阅远端流之前使用。
• 当你想要对远端流进行自定义解码时，你需要先调用 RegisterRemoteEncodedVideoFrameObserver 注册远端视频流监测器，然后再调用该接口将解码方式设置为自定义解码。监测到的视频数据会通过 OnRemoteEncodedVideoFrame 回调出来。

RequestRemoteVideoKeyFrame

virtual void bytertc::IRtcEngineLite::RequestRemoteVideoKeyFrame(
    const RemoteStreamKey& stream_info)

在订阅远端视频流之后，向远端请求关键帧

传入参数

注意

• 该方法仅适用于手动订阅模式，并且在成功订阅远端流之后使用。
• 该方法适用于调用 SetVideoDecoderConfig 开启自定义解码功能后，并且自定义解码失败的情况下使用

SendStreamSyncInfo

virtual int bytertc::IRtcEngineLite::SendStreamSyncInfo(
    const uint8_t* data,
    int32_t length,
    const StreamSycnInfoConfig& config)

发送音频流同步信息。将消息通过音频流发送到远端，并实现与音频流同步，该接口调用成功后，远端用户会收到 OnStreamSyncInfoReceived 回调。

传入参数

返回值

• >=0: 消息发送成功。返回成功发送的次数。
• -1: 消息发送失败。消息长度大于 16 字节。
• -2: 消息发送失败。传入的消息内容为空。
• -3: 消息发送失败。通过屏幕流进行消息同步时，此屏幕流还未发布。
• -4: 消息发送失败。通过用麦克风或自定义设备采集到的音频流进行消息同步时，此音频流还未发布，详见错误码 ErrorCode。

SetLocalVoicePitch

virtual void bytertc::IRtcEngineLite::SetLocalVoicePitch(
    int pitch)

开启本地语音变调功能，多用于 K 歌场景。
使用该方法，你可以对本地语音的音调进行升调或降调等调整。

传入参数

MuteAudioPlayback

virtual void bytertc::IRtcEngineLite::MuteAudioPlayback(
    MuteState mute_state)

控制本地音频流播放状态：播放/不播放

传入参数

注意 本方法仅控制本地收到音频流的播放状态，并不影响本地音频播放设备。

IPositionAudioRenderInterface

class bytertc::IPositionAudioRenderInterface

空间音频接口

成员函数

函数说明

EnableAudioSpatialRender

virtual void bytertc::IPositionAudioRenderInterface::EnableAudioSpatialRender(
    bool enable)

开启或关闭空间音频效果。

传入参数

UpdatePosition

virtual int bytertc::IPositionAudioRenderInterface::UpdatePosition(
    const Position& pos)

更新自己的位置坐标。

传入参数

返回值

• 0: 参数检查通过，但不代表更新成功；
• 其他: 更新失败。

UpdateSelfOrientation

virtual int bytertc::IPositionAudioRenderInterface::UpdateSelfOrientation(
    const HumanOrientation& orientation)

更新自己的朝向。本地朝向的设置只影响本地听到的音频效果，不影响本地发出的音频效果。

传入参数

返回值 0: 朝向更新成功。

注意 本地用户调用 EnableAudioSpatialRender 使用空间音频功能时，需要调用 UpdatePosition 接口更新位置坐标后，才能调用此接口。

RegisterRemoteInfoObserver

virtual void bytertc::IPositionAudioRenderInterface::RegisterRemoteInfoObserver(
    IRemotePositionInfoObserver* observer)

注册远端用户位置信息回调

传入参数

注意 只有在远端用户调用 EnableAudioSpatialRender 使用空间音频效果时，调用 UpdatePosition 更新位置坐标，本地用户才可以通过本接口注册的回调获取远端用户的位置信息。

ITranscoderParam

class bytertc::ITranscoderParam

成员函数

函数说明

RoomID

virtual const char* bytertc::ITranscoderParam::RoomID()

获取合流房间 ID

返回值 合流房间 ID

UserID

virtual const char* bytertc::ITranscoderParam::UserID()

获取合流用户 ID

返回值 合流用户 ID

ExpectedMixingType

virtual StreamMixingType bytertc::ITranscoderParam::ExpectedMixingType()

获取合流类型

返回值 合流类型，参看 StreamMixingType

Uri

virtual const char* bytertc::ITranscoderParam::Uri()

获取推流地址

返回值 推流地址

JsonContent

virtual const char* bytertc::ITranscoderParam::JsonContent()

获取通过 Flatten 方法转换得到的 json 格式内容

返回值 json 格式数据

AudioParam

virtual TranscoderAudioParam bytertc::ITranscoderParam::AudioParam()

获取合流音频参数

返回值 合流音频参数内容，参看 TranscoderAudioParam

VideoParam

virtual TranscoderVideoParam bytertc::ITranscoderParam::VideoParam()

获取合流视频参数

返回值 合流视频参数内容，参看 TranscoderVideoParam

LayoutRegionsSize

virtual int32_t bytertc::ITranscoderParam::LayoutRegionsSize()

获取合流参数中视窗的数量

返回值 合流参数中视窗的数量

LayoutRegionByIndex

virtual TranscoderLayoutRegion bytertc::ITranscoderParam::LayoutRegionByIndex(
    int32_t index)

获取合流视窗布局信息

传入参数

返回值 合流视窗布局信息，参看 TranscoderLayoutRegion

BackgroundColor

virtual const char* bytertc::ITranscoderParam::BackgroundColor()

获取背景颜色

返回值 背景颜色

AppData

virtual const char* bytertc::ITranscoderParam::AppData()

获取 SEI 信息

返回值 SEI 信息

SetRoomID

virtual void bytertc::ITranscoderParam::SetRoomID(
    const char* room_id)

设置合流房间 ID

传入参数

SetUserID

virtual void bytertc::ITranscoderParam::SetUserID(
    const char* user_id)

设置合流用户 ID

传入参数

SetExpectedMixingType

virtual void bytertc::ITranscoderParam::SetExpectedMixingType(
    StreamMixingType expected_mix_type)

设置合流类型

传入参数

SetUri

virtual void bytertc::ITranscoderParam::SetUri(
    const char* uri)

设置推流地址

传入参数

SetJsonContent

virtual void bytertc::ITranscoderParam::SetJsonContent(
    const char* json_content)

设置 jsonContent
传入通过 Flatten 方法转换得到的 json 格式内容

传入参数

SetAudioParam

virtual void bytertc::ITranscoderParam::SetAudioParam(
    const TranscoderAudioParam&)

设置音频参数

传入参数

SetVideoParam

virtual void bytertc::ITranscoderParam::SetVideoParam(
    const TranscoderVideoParam&)

设置视频参数

传入参数

SetLayoutParam

virtual void bytertc::ITranscoderParam::SetLayoutParam(
    TranscoderLayoutRegion regions[],
    int32_t regions_size,
    const char* bg_color,
    const char* app_data)

设置合流布局参数

传入参数

Flatten

virtual const char* bytertc::ITranscoderParam::Flatten(
    const char* contentType,
    const char* action)

将合流参数转成 json 字符串

传入参数

返回值 转换后的 json 字符串

Inflatten

virtual ITranscoderParam* bytertc::ITranscoderParam::Inflatten(
    const char* json_str)

将输入的 json 格式的字符串转成 ITranscoderParam 结构体

传入参数

返回值 转换后的 ITranscoderParam 结构体

IVideoEffect

class bytertc::IVideoEffect

视频特效接口

成员函数

函数说明

CheckLicense

virtual int bytertc::IVideoEffect::CheckLicense(
    void* androidContext,
    void* jnienv,
    const char* licensePath)

视频特效许可证检查

传入参数

返回值

• 0: 调用成功
• 1000: 未集成cvsdk
• 1001: 本RTC版本不支持cv功能
• < 0: 调用失败，具体错误码请参考 CV 错误码表。

注意 开始使用视频特效前，你必须先调用这个方法进行许可证验证

GetAuthMessage

virtual int bytertc::IVideoEffect::GetAuthMessage(
    char ** ppmsg,
    int * len)

从 CV SDK 获取授权消息，用于获取在线许可证。

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

注意

• 使用 CV 的功能前，你必须获取 CV SDK 的在线许可证。
  通过此接口获取授权消息后，你必须参考 在线授权说明。 自行实现获取在线许可证的业务逻辑。获取许可证后，你必须调用 CheckLicense 确认许可证有效。然后，你才可以使用 CV 功能。

• 获取授权消息后，调用 FreeAuthMessage 释放内存。

FreeAuthMessage

virtual int bytertc::IVideoEffect::FreeAuthMessage(
    char * pmsg)

使用完授权消息字符串后，释放内存。

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

EnableEffect

virtual int bytertc::IVideoEffect::EnableEffect(
    bool enabled)

开启关闭视频特效

传入参数

返回值

• 0: 成功
• 1000: 未集成 CV SDK
• 1001: 当前 RTC 版本不支持 CV 功能
• <0: 其他错误，具体参看CV 错误码表

注意 在调用CheckLicense和SetAlgoModelPath后调用此方法

SetAlgoModelPath

virtual void bytertc::IVideoEffect::SetAlgoModelPath(
    const char* modelPath)

设置视频特效算法模型路径

传入参数

SetEffectNodes

virtual int bytertc::IVideoEffect::SetEffectNodes(
    const char** effectNodePaths,
    int nodeNum)

设置视频特效素材包

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

UpdateNode

virtual int bytertc::IVideoEffect::UpdateNode(
    const char* nodePath,
    const char* nodeKey,
    float nodeValue)

设置特效强度

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

SetColorFilter

virtual int bytertc::IVideoEffect::SetColorFilter(
    const char* resPath)

设置颜色滤镜

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

SetColorFilterIntensity

virtual int bytertc::IVideoEffect::SetColorFilterIntensity(
    float intensity)

设置已启用颜色滤镜的强度

传入参数

返回值

• 0: 调用成功
• 1000: 未集成 CV SDK
• 1001: 本 RTC 版本不支持 CV 功能
• < 0: 调用失败，具体错误码，请参考 CV 错误码表。

InitVirtualBackground

virtual int bytertc::IVideoEffect::InitVirtualBackground(
    void* androidContext,
    void* jnienv,
    const char* licensePath,
    const char* modelPath)

虚拟背景功能初始化。

传入参数

返回值

• 0: 调用成功。
• 1000: 调用失败，未集成 CV SDK 。
• 1001: 调用失败，本 SDK 版本不支持 CV 功能。
• > 40000: 调用失败，CV SDK 授权错误，具体错误码请参考 CV 错误码表。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 CV 错误码表。

EnableVirtualBackground

virtual int bytertc::IVideoEffect::EnableVirtualBackground(
    const VirtualBackgroundSource& source)

开启虚拟背景。

传入参数

返回值

• 0: 调用成功。
• < 0: 调用失败，CV SDK 内部错误，具体错误码请参考 CV SDK 文档。
• -1: 调用失败，未调用 InitVirtualBackground 或调用失败，导致 license 验证失败。
• -4: 调用失败，自定义背景图片打开失败。
• -37: 调用失败，自定义背景图片解码失败。
• -38: 调用失败，图片格式不支持。支持的图片格式是 jpg、jpeg、和 png。

注意

• 调用此接口前，需要先调用 InitVirtualBackground 初始化 CV 环境；
• 虚拟背景仅支持摄像头采集的视频流，包括 RTC SDK 内部机制采集的方式和自定义采集的方式。虚拟背景不支持屏幕视频流。

DisableVirtualBackground

virtual int bytertc::IVideoEffect::DisableVirtualBackground()

关闭虚拟背景。

返回值

• 0: 调用成功。
• < 0: 调用失败，具体错误码请参考 CV SDK 文档。

注意 调用 EnableVirtualBackground 开启虚拟背景后，可以调用此接口关闭虚拟背景。

IVideoProcessor

class bytertc::IVideoProcessor

成员函数

函数说明

ProcessVideoFrame

virtual IVideoFrame* bytertc::IVideoProcessor::ProcessVideoFrame(
    IVideoFrame* src_frame)

获取 RTC SDK 采集得到的视频帧，根据 RegisterLocalVideoProcessor 设置的视频前处理器，进行视频前处理，最终将处理后的视频帧给到 RTC SDK 用于编码传输。

传入参数

返回值 经过视频前处理后的视频帧，返回给 RTC SDK 供编码和传输，参看 IVideoFrame。

注意

• 在进行视频前处理前，你需要调用 RegisterLocalVideoProcessor 设置视频前处理器。
• 如果需要取消视频前处理，可以将视频前处理器设置为 nullptr。

IRtcRoom

class bytertc::IRtcRoom

房间接口

成员函数

函数说明

SetUserVisibility

virtual void bytertc::IRtcRoom::SetUserVisibility(
    bool enable)

设置用户可见性。默认可见。

传入参数

返回值

• 0: 方法调用成功
• < 0: 方法调用失败

注意

• 该方法在加入房间前后均可调用。
• 在房间内调用此方法，房间内其他用户会收到相应的回调通知：
• 从 false 切换至 true 时，房间内其他用户会收到 OnUserJoined 回调通知；
• 从 true 切换至 false 时，房间内其他用户会收到 OnUserLeave 回调通知。
• 若调用该方法将可见性设为 false，此时尝试发布流会收到 kWarningCodePublishStreamForbiden 警告。

JoinRoom

virtual int bytertc::IRtcRoom::JoinRoom(
    const char* token,
    const UserInfo& user_info,
    const MultiRoomConfig& config)

创建/加入房间：房间不存在时即创建房间；房间存在时，未加入房间的用户可加入这个房间。
同一房间内的用户间可以相互通话。
进房后重复调用无效，用户必须调用 LeaveRoom 退出当前房间后，才能加入下一个房间。

传入参数

返回值

• 0: 成功
• -1：room_id / user_info.uid 包含了无效的参数。
• -2：已经在房间内。接口调用成功后，只要收到返回值为 0 ，且未调用 LeaveRoom:LeaveRoom 成功，则再次调用进房接口时，无论填写的房间 ID 和用户 ID 是否重复，均触发此返回值。

注意

• 同一个 App ID 的同一个房间内，每个用户的用户 ID 必须是唯一的。如果两个用户的用户 ID 相同，则后进房的用户会将先进房的用户踢出房间，并且先进房的用户会收到 OnError 回调通知，错误类型详见 ErrorCode 中的 kErrorCodeDuplicateLogin。
• 本地用户调用此方法加入房间成功后，会收到 OnJoinRoomResult 回调通知。
• 本地用户调用 SetUserVisibility 将自身设为可见后加入房间，远端用户会收到 OnUserJoined。
• 用户加入房间成功后，在本地网络状况不佳的情况下，SDK 可能会与服务器失去连接，此时 SDK 将会自动重连。重连成功后，本地会收到 OnJoinRoomResult 回调通知。

LeaveRoom

virtual void bytertc::IRtcRoom::LeaveRoom()

离开房间。
用户调用此方法离开房间，结束通话过程，释放所有通话相关的资源。
加入房间后，必须调用此方法结束通话，否则无法开始下一次通话。无论当前是否在房间内，都可以调用此方法。重复调用此方法没有负面影响。
此方法是异步操作，调用返回时并没有真正退出房间。真正退出房间后，本地会收到 OnLeaveRoom 回调通知。

注意

• 可见的用户离开房间后，房间内其他用户会收到 OnUserLeave 回调通知。
• 如果调用此方法后立即销毁引擎，SDK 将无法触发 OnLeaveRoom 回调。
• 调用 JoinRoom 方法加入房间后，必须调用此方法离开房间，否则无法进入下一个房间。无论当前是否在房间内，都可以调用此方法。重复调用此方法没有负面影响。

UpdateToken

virtual void bytertc::IRtcRoom::UpdateToken(
    const char* token)

更新 Token。
Token 有一定的有效期，当 Token 过期时，用户需调用此方法更新房间的 Token 信息。
用户调用 JoinRoom 方法加入房间时，如果使用了过期的 Token 将导致加入房间失败，并会收到 OnJoinRoomResult 回调通知，错误码为 ErrorCode 中的 kErrorCodeInvalidToken 。此时需要重新获取 Token，并调用此方法更新 Token。

传入参数

注意

• 如果用户因 Token 过期导致加入房间失败，则调用此方法更新 Token 后，SDK 会自动重新加入房间，而不需要用户自己调用 JoinRoom 方法。
• Token 过期时，如果已经加入房间成功，则不会受到影响。Token 过期的错误会在下一次使用过期 Token 加入房间时，或因本地网络状况不佳导致断网重新连入房间时通知给用户。

SendUserMessage

virtual int64_t bytertc::IRtcRoom::SendUserMessage(
    const char* uid,
    const char* message)

给房间内指定的用户发送文本消息（P2P）

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意

• 在发送房间内文本消息前，必须先调用 JoinRoom 加入房间。
• 调用该函数后会收到一次 OnUserMessageSendResult 回调，通知消息发送方发送成功或失败；
• 若文本消息发送成功，则 uid 所指定的用户会收到 OnUserMessageReceived 回调。

SendUserBinaryMessage

virtual int64_t bytertc::IRtcRoom::SendUserBinaryMessage(
    const char* uid,
    int length,
    const uint8_t* message)

给房间内指定的用户发送二进制消息（P2P）

传入参数

返回值 这次发送消息的编号，从 1 开始递增。

注意

• 在发送房间内二进制消息前，必须先调用 JoinRoom 加入房间。
• 调用该函数后会收到一次 OnUserMessageSendResult 回调，通知消息发送方发送成功或失败；
• 若二进制消息发送成功，则 uid 所指定的用户会收到 OnUserBinaryMessageReceived 回调。

SendRoomMessage

virtual int64_t bytertc::IRtcRoom::SendRoomMessage(
    const char* message)

给房间内的所有其他用户发送广播消息。

传入参数

注意

• 在发送房间内二进制消息前，必须先调用 JoinRoom 加入房间。
• 调用该函数后，会收到一次 OnRoomMessageSendResult 回调。
• 同一房间内的其他用户会收到 OnRoomMessageReceived 回调。

SendRoomBinaryMessage

virtual int64_t bytertc::IRtcRoom::SendRoomBinaryMessage(
    int size,
    const uint8_t* message)

给房间内的所有其他用户发送广播消息。

传入参数

注意

• 在发送房间内二进制消息前，必须先调用 JoinRoom 加入房间。
• 调用该函数后，会收到一次 OnRoomMessageSendResult 回调。
• 同一房间内的其他用户会收到 OnRoomBinaryMessageReceived 回调。

Publish

virtual void bytertc::IRtcRoom::Publish()

在当前所在房间内停止发布本地音视频流

注意

• 多房间模式下，默认音视频流不自动发布。你必须调用此接口，进行手动发布。
• 调用 SetUserVisibility 方法将自身设置为不可见后无法调用该方法，需将自身切换至可见后方可调用该方法发布音视频流。
• 如果你需要发布屏幕共享流，调用 PublishScreen。
• 如果你需要向多个房间发布音视频流，调用 StartForwardStreamToRooms。
• 用户调用此方法成功发布音视频流后，房间中的其他用户将会收到 OnStreamAdd 回调通知。

Unpublish

virtual void bytertc::IRtcRoom::Unpublish()

停止将本端音视频流发布到此房间

注意

• 在多房间模式下，调用 Publish 手动发布音视频流后，调用此接口停止发布。
• 房间内用户调用此方法停止发布音视频流后，房间中的其他用户将会收到 OnStreamRemove 回调通知。

PublishScreen

virtual void bytertc::IRtcRoom::PublishScreen()

发布本地屏幕共享流到房间。

注意

• 你必须先加入房间，才能调用此方法。
• 直播、游戏、云游戏房间模式下，仅可见的用户可以调用此方法。你可以调用 SetUserVisibility 方法设置用户在房间中的可见性。
• 此方法只影响屏幕共享视频流的发布状态，并不影响屏幕视频流的采集情况。你可以通过两种方式进行采集：
• RTC SDK 内部采集：参看 StartScreenVideoCapture 和 StartScreenAudioCapture
• RTC SDK 外部采集：你可以自行采集屏幕音视频流，并周期性调用 PushScreenFrame 和 PushScreenAudioFrame 将采集得到的音视频帧推送到 RTC SDK 用于编码传输。
• 发布成功后，远端会收到 OnStreamAdd 回调；如果调用 RegisterVideoFrameObserver 注册了视频帧回调观察者，那么也会收到 OnRemoteScreenFrame 回调。
• 调用 UnpublishScreen 取消发布。

UnpublishScreen

virtual void bytertc::IRtcRoom::UnpublishScreen()

停止发布本地屏幕共享流到房间。

注意

• 此方法只影响屏幕共享视频流的发布状态，并不影响屏幕视频流的采集情况。
• 调用 PublishScreen 启动发布。

SubscribeUserStream

virtual void bytertc::IRtcRoom::SubscribeUserStream(
    const char* user_id,
    StreamIndex stream_type,
    SubscribeMediaType media_type,
    const SubscribeVideoConfig& video_config)

订阅房间内指定的远端音视频流。
无论是自动订阅还是手动订阅模式，你都可以调用此方法按需订阅房间中的音视频流。
该方法也可用于更新已经订阅的流的属性、媒体类型等配置。

传入参数

注意

• 你必须通过 OnStreamAdd 和 OnStreamRemove 两个回调获取当前房间里的音视频流信息，并调用本方法按需订阅流或修改订阅配置。
• 若订阅失败，你会收到 OnRoomError 回调通知，具体失败原因参看 ErrorCode。
• 若调用 PauseAllSubscribedStream 暂停接收远端音视频流，此时仍可使用该方法对暂停接收的流进行设置，你会在调用 ResumeAllSubscribedStream 恢复接收流后收到修改设置后的流。

Unsubscribe

virtual void bytertc::IRtcRoom::Unsubscribe(
    const char* user_id,
    bool is_screen)

停止订阅指定的房间内远端音视频流。
关闭自动订阅功能，使用手动订阅模式时用户调用此方法停止订阅已订阅的音视频流。
此方法仅在关闭自动订阅功能时生效。用户需在加入房间时设置 config 关闭自动订阅功能以使用手动订阅模式。

传入参数

注意

• 不管是否订阅了指定的远端音视频流，都可以调用此方法停止订阅。停止订阅的 stream_id 无效或未订阅时，SDK不会做任何处理，没有负面影响。

SetRemoteAudioPlaybackVolume

virtual void bytertc::IRtcRoom::SetRemoteAudioPlaybackVolume(
    const char* user_id,
    int volume)

调节来自远端用户的音频播放音量

传入参数

PauseAllSubscribedStream

virtual void bytertc::IRtcRoom::PauseAllSubscribedStream(
    PauseResumeControlMediaType media_type)

暂停接收来自远端的媒体流。

传入参数

注意

• 该方法仅暂停远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。
• 若想恢复接收远端流，需调用 ResumeAllSubscribedStream。

ResumeAllSubscribedStream

virtual void bytertc::IRtcRoom::ResumeAllSubscribedStream(
    PauseResumeControlMediaType media_type)

恢复接收来自远端的媒体流

传入参数

注意

• 该方法仅恢复远端流的接收，并不影响远端流的采集和发送；
• 该方法不改变用户的订阅状态以及订阅流的属性。

StartLiveTranscoding

virtual void bytertc::IRtcRoom::StartLiveTranscoding(
    ITranscoderParam* param,
    ITranscoderObserver* observer)

开启转推直播，并设置合流的视频视图布局和音频属性。

传入参数

注意

• 只有房间模式为直播模式的用户才能调用此方法。
• 调用该方法后，关于启动结果和推流过程中的错误，会收到 OnStreamMixingEvent 回调。
• 调用 StopLiveTranscoding 停止转推直播。

StopLiveTranscoding

virtual void bytertc::IRtcRoom::StopLiveTranscoding()

停止转推直播。
关于启动转推直播，参看 StartLiveTranscoding。

UpdateLiveTranscoding

virtual void bytertc::IRtcRoom::UpdateLiveTranscoding(
    ITranscoderParam* param)

更新转推直播参数。
使用 StartLiveTranscoding 启用转推直播功能后，使用此方法更新功能配置参数。

传入参数

SetRemoteVideoCanvas

virtual void bytertc::IRtcRoom::SetRemoteVideoCanvas(
    const char* user_id,
    StreamIndex index,
    const VideoCanvas& canvas)

设置来自指定远端用户 user_id 的视频渲染时，使用的视图，并设置渲染模式。
如果需要解除某个用户的绑定视图，你可以把 view 设置为空。

传入参数

返回值

• 0：成功
• !0：失败

注意

• 你应在加入房间后，绑定视图。退出房间后，此设置不失效。
• 实际使用时，你可以在收到回调 OnUserJoined 或 OnFirstRemoteVideoFrameRendered 时获得远端用户 user_id。
• 这两个回调的差别是：如果启用了视频录制功能，视频录制服务会作为一个哑客户端加入房间，因此其他客户端会收到对应的 OnUserJoined 回调，而不会收到 onFirstRemoteVideoFrame 回调。你不应给录制的哑亚客户端绑定视图（因为它不会发送视频流）。

StartForwardStreamToRooms

virtual int bytertc::IRtcRoom::StartForwardStreamToRooms(
    const ForwardStreamConfiguration& configuration)

开始跨房间转发媒体流。 在用户进入房间后调用本接口，实现向多个房间转发媒体流，适用于跨房间连麦等场景。

传入参数

返回值

0: 方法调用成功
<0: 方法调用失败

注意

• 调用本方法后，将在本端触发 OnForwardStreamStateChanged 回调。
• 调用本方法后，你可以通过监听 OnForwardStreamEvent 回调来获取各个目标房间在转发媒体流过程中的相关事件。
• 开始转发后，目标房间中的用户将接收到本地用户进房 OnUserJoined 和发流 OnStreamAdd 的回调。
• 调用本方法后，可以调用 UpdateForwardStreamToRooms 更新目标房间信息，例如，增加或减少目标房间等。
• 调用本方法后，可以调用 StopForwardStreamToRooms 停止向所有房间转发媒体流。
• 调用本方法后，可以调用 PauseForwardStreamToAllRooms 暂停向所有房间转发媒体流。

UpdateForwardStreamToRooms

virtual int bytertc::IRtcRoom::UpdateForwardStreamToRooms(
    const ForwardStreamConfiguration& configuration)

更新跨房间媒体流转发信息。
通过 StartForwardStreamToRooms 发起媒体流转发后，可调用本方法增加或者减少目标房间，或更新房间密钥。 调用本方法增加或删减房间后，将在本端触发 OnForwardStreamStateChanged 回调，包含发生了变动的目标房间中媒体流转发状态。

传入参数

返回值

0: 方法调用成功
<0: 方法调用失败

注意

• 增加目标房间后，新增目标房间中的用户将接收到本地用户进房 OnUserJoined 和发布 OnStreamAdd 的回调。
• 删减目标房间后，原目标房间中的用户将接收到本地用户停止发布 OnStreamRemove 和退房 OnUserLeave 的回调。

StopForwardStreamToRooms

virtual void bytertc::IRtcRoom::StopForwardStreamToRooms()

停止跨房间媒体流转发。 通过 StartForwardStreamToRooms 发起媒体流转发后，可调用本方法停止向所有目标房间转发媒体流。

注意

• 调用本方法后，将在本端触发 OnForwardStreamStateChanged 回调。
• 调用本方法后，原目标房间中的用户将接收到本地用户停止发布 OnStreamRemove 和退房 OnUserLeave 的回调。
• 如果需要停止向指定的房间转发媒体流，请调用 UpdateForwardStreamToRooms 更新房间信息。
• 如果需要暂停转发，请调用 PauseForwardStreamToAllRooms，并在之后随时调用 ResumeForwardStreamToAllRooms 快速恢复转发。

PauseForwardStreamToAllRooms

virtual void bytertc::IRtcRoom::PauseForwardStreamToAllRooms()

暂停跨房间媒体流转发。 通过 StartForwardStreamToRooms 发起媒体流转发后，可调用本方法暂停向所有目标房间转发媒体流。 调用本方法暂停向所有目标房间转发后，你可以随时调用 ResumeForwardStreamToAllRooms 快速恢复转发。

注意 调用本方法后，目标房间中的用户将接收到本地用户停止发布 OnStreamRemove 和退房 OnUserLeave 的回调。

ResumeForwardStreamToAllRooms

virtual void bytertc::IRtcRoom::ResumeForwardStreamToAllRooms()

恢复跨房间媒体流转发。 调用 PauseForwardStreamToAllRooms 暂停转发之后，调用本方法恢复向所有目标房间转发媒体流。

注意 目标房间中的用户将接收到本地用户进房 OnUserJoined 和发布 OnStreamAdd 的回调。