• 实时音视频
    • 实时音视频>客户端 API>C++

    全平台 (C++)

    编辑文档 更新于
    概况BRTCBRTCCallBackBRTCDeviceManagerBRTCMediaPlayerManager对象和枚举错误码

    BRTC 是 BRTC SDK 的入口类,它为 App 提供了快速搭建音视频通信的 API。
    BRTCCallback 包含 App 调用的主要方法,调用 BRTC 的接口最好在同一个线程进行,不建议在不同的线程同时调用。

    基础函数  
    static BRTC_API brtc::BRTC * getBRTCShareInstance()
    static BRTC_API void destroyBRTCShareInstance()
    virtual void setCallback(BRTCCallback *callback)=0
    房间相关接口函数  
    virtual void enterRoom(const BRTCParams &params)=0
    virtual void exitRoom()=0
    视频相关接口函数  
    virtual void startLocalPreview(BRTCView rendView)=0
    virtual void stopLocalPreview()=0
    virtual void muteLocalVideo(bool mute)=0
    virtual void startRemoteView(const char *userId, BRTCVideoStreamType streamType, BRTCView rendView)=0
    virtual void updateRemoteView(const char *userId, BRTCVideoStreamType streamType, BRTCView rendView)=0
    virtual void stopRemoteView(const char *userId, BRTCVideoStreamType streamType)=0
    virtual void muteRemoteVideoStream(const char *userId, bool mute)=0
    virtual void muteAllRemoteVideoStreams(bool mute)=0
    virtual void setVideoEncoderParam(const BRTCVideoEncParam &params)=0
    virtual void setNetworkQosParam(const BRTCNetworkQosParam &params)=0
    virtual void setLocalRenderParams(const BRTCRenderParams &params)=0
    virtual void setRemoteRenderParams(const char *userId, BRTCVideoStreamType streamType, const BRTCRenderParams &params)=0
    virtual void setVideoEncoderMirror(bool mirror)=0
    virtual void enableEncSmallVideoStream(bool enable, const BRTCVideoEncParam &smallVideoParam)=0
    virtual void setRemoteVideoStreamType(const char *userId, BRTCVideoStreamType type)=0
    virtual void snapshotVideo(const char *userId, BRTCVideoStreamType streamType, BRTCSnapshotSourceType sourceType)=0
    音频相关接口  
    virtual void startLocalAudio()=0
    virtual void stopLocalAudio()=0
    virtual void muteLocalAudio(bool mute)=0
    virtual void muteRemoteAudio(const char *userId, bool mute)=0
    virtual void setAudioCaptureVolume(int volume)=0
    virtual int getAudioCaptureVolume()=0
    virtual void setAudioPlayoutVolume(int volume)=0
    virtual int getAudioPlayoutVolume()=0
    virtual void enableAudioVolumeEvaluation(uint32_t interval)=0
    设备管理相关接口  
    virtual BRTCDeviceManager* getDeviceManager()=0
    媒体播放器相关接口  
    virtual BRTCMediaPlayerManager* getMediaPlayerManager()=0
    自定义消息发送  
    virtual bool sendCustomCmdMsg(uint32_t cmdId, const uint8_t *data, uint32_t dataSize, bool reliable, bool ordered)=0
    virtual bool sendSEIMsg(const uint8_t *data, uint32_t dataSize, int32_t repeatCount)=0
    Log 相关接口函数  
    virtual const char * getSDKVersion()=0
    virtual void setLogLevel(BRTCLogLevel level)=0
    virtual void setConsoleEnabled(bool enabled)=0
    virtual void setLogDirPath(const char *path)=0
    virtual void setLogCallback(IBRTCLogCallback *callback)=0
    virtual void callExperimentalAPI(const char *jsonStr)=0

    详细信息

    创建 BRTC 单例 

    BRTC_API brtc::BRTC* getBRTCShareInstance();

    返回

    • 返回 BRTC 单例对象的指针，注意，delete BRTC*会编译错误，需要调用

    详情

    • 用于动态加载 dll 时，获取 BRTC 对象指针

    销毁 BRTC 单例 

    BRTC_API void destroyBRTCShareInstance();

    详情

    • 释放单例指针对象
    • 该方法释放 BRTC SDK 使用的所有资源
    • 调用 destroySharedIntance 方法后,你将无法再使用 SDK 的其它方法和回调
    • 如需再次使用实时音视频通信功能,你必须重新调用 getBRTCShareInstance 方法创建一个新的 BRTC 实例
    • 如需在销毁后再次创建 BRTC 单例,需要等待 destroySharedIntance 方法执行结束后再创建实例

    设置回调接口 

    virtual void setCallback(BRTCCallback* callback) = 0;

    详情

    • 您可以通过 setCallback 获得来自 SDK 的各种状态通知,详见 BRTCCallback|

    加入房间 

    virtual void enterRoom(const BRTCParams& param) = 0;

    参数

    名称 描述
    param 进房参数，详见 BRTCParams

    详情

    • 调用接口后，您会收到来自 BRTCCallback 中的 onEnterRoom(result) 回调
    • 如果加入成功，result 会是一个正数（result > 0），表示加入房间的时间消耗，单位是毫秒（ms）
    • 如果加入失败，result 会是一个负数（result < 0），表示进房失败的错误码
    • 不管进房是否成功，enterRoom() 都必须与 exitRoom() 配对使用，在调用 exitRoom() 前再次调用 enterRoom() 函数会导致不可预期的错误问题

    离开房间 

    virtual void exitRoom() = 0;

    详情

    • 调用 exitRoom() 接口会执行退出房间的相关逻辑，例如释放音视频设备资源和编解码器资源等
    • 待资源释放完毕，SDK 会通过 BRTCCallback 中的 onExitRoom() 回调通知到您
    • 如果您要再次调用 enterRoom() 或者切换到其他的音视频 SDK，请等待 onExitRoom() 回调到来之后再执行相关操作，否则可能会遇到摄像头或麦克风被占用等各种异常问题

    开启本地视频的预览画面 

    virtual void startLocalPreview(BRTCView rendView) = 0;

    参数

    名称 描述
    frontCamera true：前置摄像头；false：后置摄像头
    view 承载视频画面的控件

    详情

    • 这个接口会启动默认的摄像头，可以通过 BRTCDeviceManager::setCurrentDevice 接口选用其他摄像头
    • 当开始渲染首帧摄像头画面时，你会收到 BRTCCallback 中的 onFirstVideoFrame(nullptr) 回调

    停止本地视频采集及预览 

    virtual void stopLocalPreview() = 0;

    暂停/恢复推送本地的视频数据 

    virtual void muteLocalVideo(bool mute) = 0;

    参数

    名称 描述
    mute true：暂停；false：恢复

    详情

    • 当暂停推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userid, false)回调通知
    • 当恢复推送本地视频后，房间里的其它成员将会收到 onUserVideoAvailable(userid, true)回调通知

    开始拉取并显示指定用户的远端画面 

    virtual void startRemoteView(const char* userId, BRTCVideoStreamType streamType, BRTCView rendView) = 0;

    参数

    名称 描述
    userId 指定远端用户的 userId
    streamType 指定要观看 userId 的视频流类型:
    高清大画面：BRTCVideoStreamTypeBig
    低清小画面：BRTCVideoStreamTypeSmall
    辅流（屏幕分享）：BRTCVideoStreamTypeSub
    view 承载视频画面的控件

    详情

    • 该函数会拉取指定 userid 的视频流显示在您指定的 view 控件上，您可以通过 setRemoteRenderParams 设置显示模式
    • 如果您提前知道房间中某个 userid 正在推流，可以直接调用 startRemoteView 显示该用户的远端画面。
    • 如果您不知道房间中有哪些用户开启了视频，可以在 enterRoom 后等待来自 SDK 的 onUserVideoAvailable(userId, true) 回调通知
    • 调用 startRemoteView 只是启动拉取，此时画面还需要加载，当加载完毕后会通过 onFirstVideoFrame(userId) 通知您
    • SDK 支持同时观看某 userid 的大画面和辅路，或者小画面和辅路，但不支持同时观看大画面和小画面
    • 只有当指定的 userid 通过 enableEncSmallVideoStream 开启双路编码后，才能观看该用户的小画面
    • 如果该用户的小画面不存在，则默认切换到大画面

    停止显示远端视频画面，同时不再拉取该远端用户的视频数据流 

    virtual void stopRemoteView(const char* userId, BRTCVideoStreamType streamType) = 0;

    参数

    名称 描述
    userId 指定远端用户的 userId
    streamType 指定要观看 userId 的视频流类型:
    高清大画面：BRTCVideoStreamTypeBig
    低清小画面：BRTCVideoStreamTypeSmall
    辅流（屏幕分享）：BRTCVideoStreamTypeSub

    详情

    • 调用此接口后，SDK 会停止接收该用户的远程视频流，同时会清理相关的视频显示资源

    暂停/恢复接收指定的远端视频流 

    virtual void muteRemoteVideoStream(const char* userId, bool mute) = 0;

    参数

    名称 描述
    userId 对方的用户标识
    mute true：暂停；false：恢复

    详情

    • 该接口仅暂停/恢复接收指定的远端用户的视频流，但并不释放显示资源，视频画面会冻屏在 mute 前的最后一帧
    • 在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false

    暂停/恢复接收所有远端视频流 

    virtual void muteAllRemoteVideoStreams(bool mute) = 0;

    参数

    名称 描述
    mute true：暂停；false：恢复

    详情

    • 该接口仅暂停/恢复接收所有远端用户的视频流，但并不释放显示资源，视频画面会冻屏在 mute 前的最后一帧
    • 在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false

    设置视频编码器相关参数 

    virtual void setVideoEncoderParam(const BRTCVideoEncParam& config) = 0;

    参数

    名称 描述
    param 视频编码参数，详情 BRTCVideoEncParam

    详情

    • 该设置决定了远端用户看到的画面质量（同时也是云端录制出的视频文件的画面质量）

    本地图像的渲染设置 

    virtual void setLocalRenderParams(const BRTCRenderParams& params) = 0;

    参数

    名称 描述
    params 详见 BRTCRenderParams

    远端图像的渲染设置 

    virtual void setRemoteRenderParams(const char* userId, BRTCVideoStreamType streamType, const BRTCRenderParams& params) = 0;

    参数

    名称 描述
    userId 用户 ID
    type 指定要观看 userId 的视频流类型:
    高清大画面：BRTCVideoStreamTypeBig
    低清小画面：BRTCVideoStreamTypeSmall
    辅流（屏幕分享）：BRTCVideoStreamTypeSub
    params 详见 BRTCRenderParams

    详情

    • 开启后会在 onUserVoiceVolume 中获取到 SDK 对音量大小值的评估。如需打开此功能,请在 startLocalAudio() 之前调用
    • intervalMs 决定了 onUserVoiceVolume 回调的触发间隔,单位为ms,最小间隔为100ms,如果小于等于0则会关闭回调,建议设置为300ms

    设置编码器输出的画面镜像模式

    virtual void setVideoEncoderMirror(bool mirror) = 0;

    参数

    名称 描述
    mirror true：开启远端画面镜像；false：关闭远端画面镜像，默认值：false

    详情

    • 该接口不改变本地摄像头的预览画面，但会改变另一端用户看到的（以及服务器录制的）画面效果

    开启大小画面双路编码模式 

    virtual void enableEncSmallVideoStream(bool enable, const BRTCVideoEncParam& smallVideoEncParam) = 0;

    参数

    名称 描述
    enable true：开启；false：不开启，默认值：false
    smallVideoEncParam 详见 BRTCVideoEncParam

    返回

    • 0：成功；-1：大画面已经是最低画质

    详情

    • 如果当前用户是房间中的主要角色（例如主播、老师、主持人等），并且使用 PC 或者 Mac 环境，可以开启该模式
    • 开启该模式后，当前用户会同时输出【高清大画面】和【低清小画面】两路视频流（但只有一路音频流）
    • 对于开启该模式的当前用户，会占用更多的网络带宽，并且会更加消耗 CPU 计算资源
    • 对于同一房间的远程观众而言：
      • 如果下行网络很好，可以选择观看【高清大画面】
      • 如果下行网络较差，可以选择观看【低清小画面】
    • 双路编码开启后，会消耗更多的 CPU 和 网络带宽，所以对于 iMac、Windows 或者高性能 Pad 可以考虑开启，但请不要在手机端开启

    切换指定远端用户的大小画面 

    virtual void setRemoteVideoStreamType(const char* userId, BRTCVideoStreamType type) = 0;

    参数

    名称 描述
    userId 用于指定要观看的 userId
    type 视频流类型，即选择看大画面或小画面，默认为大画面

    详情

    • 此功能需要该 userId 通过 enableEncSmallVideoStream 提前开启双路编码模式
    • 如果该 userId 没有开启双路编码模式，则此操作将无任何反应
    • 在不通过此接口进行设置的情况下，startRemoteView 默认观看的画面为大画面

    设置网络流控相关参数 

    virtual void setNetworkQosParam(const BRTCNetworkQosParam& params) = 0;

    参数

    名称 描述
    param 网络流控参数，详见 BRTCNetworkQosParam

    详情

    • 该设置决定 SDK 在各种网络环境下的调控策略（例如弱网下选择“保清晰”或“保流畅”）

    视频画面截图 

    virtual void snapshotVideo(const char* userId, BRTCVideoStreamType streamType, BRTCSnapshotSourceType sourceType) = 0;

    参数

    名称 描述
    userId 用户 ID，nil 表示截取本地视频画面
    type 视频流类型，支持主路画面（BRTCVideoStreamTypeBig，一般用于摄像头）和 辅路画面（BRTCVideoStreamTypeSub，一般用于屏幕分享）
    sourceType 截图画面来源，支持视频流（BRTCSnapshotSourceTypeStream）和视频渲染画面（BRTCSnapshotSourceTypeView）
    completionBlock 画面截取后的回调

    详情

    • 截取本地、远程主路和远端辅流的视频画面，并通过 UIImage(c++) 或 NSImage(macOS) 对象返回

    开启本地音频的采集和上行 

    virtual void startLocalAudio(BRTCAudioQuality quality) = 0;

    参数

    名称 描述
    quality 声音音质，详见 BRTCAudioQuality

    详情

    • SDK 默认不采集声音，您需要调用该函数启动麦克风采集，并将音频数据传输给房间里的其他用户
    • 该函数会检查麦克风的使用权限，如果当前 App 没有麦克风权限，SDK 会向用户申请开启

    关闭本地音频的采集和上行 

    virtual void stopLocalAudio() = 0;

    详情

    • 当关闭本地音频的采集和上行，房间里的其它成员会收到 onUserAudioAvailable(false) 回调通知

    静音/取消静音本地的音频 

    virtual void muteLocalAudio(bool mute) = 0;

    参数

    名称 描述
    mute true：静音；false：取消静音

    详情

    • 当静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, false) 回调通知
    • 当取消静音本地音频后，房间里的其它成员会收到 onUserAudioAvailable(userId, true) 回调通知
    • 与 stopLocalAudio 不同之处在于，muteLocalAudio:true 并不会停止发送音视频数据，而是继续发送码率极低的静音包

    静音/取消静音指定的远端用户的声音 

    virtual void muteRemoteAudio(const char* userId, bool mute) = 0;

    参数

    名称 描述
    userId 对方的用户 ID
    mute true：静音；false：取消静音

    详情

    • 静音时会停止接收该用户的远端音频流并停止播放，取消静音时会自动拉取该用户的远端音频流并进行播放
    • 在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false

    静音/取消静音所有用户的声音 

    virtual void muteAllRemoteAudio(bool mute) = 0;

    参数

    名称 描述
    mute true：静音；false：取消静音

    详情

    • 静音时会停止接收所有用户的远端音频流并停止播放，取消静音时会自动拉取所有用户的远端音频流并进行播放
    • 在 enterRoom 之前或之后调用此 API 均会进入屏蔽状态，屏蔽状态在您调用 exitRoom 之后会被重置为 false

    设置 SDK 采集音量 

    virtual void setAudioCaptureVolume(uint32_t volume) = 0;

    参数

    名称 描述
    volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100

    获取 SDK 采集音量 

    virtual int getAudioCaptureVolume() = 0;

    设置 SDK 播放音量 

    virtual void setAudioPlayoutVolume(uint32_t volume) = 0;

    参数

    名称 描述
    volume 音量大小，100为原始音量，范围是：[0 ~ 150]，默认值为100

    详情

    • 该函数会控制最终交给系统播放的声音音量，会影响录制本地音频文件的音量大小，但不会影响耳返的音量

    获取 SDK 播放音量 

    virtual int getAudioPlayoutVolume() = 0;

    启用音量大小提示 

    virtual void enableAudioVolumeEvaluation(uint32_t interval) = 0;

    参数

    名称 描述
    interval 设置 onUserVoiceVolume 回调的触发间隔，单位为ms，最小间隔为100ms，如果小于等于0则会关闭回调，建议设置为300ms

    详情

    • 开启此功能后，SDK 会在 onUserVoiceVolume() 中反馈对每一路声音音量大小值的评估
    • 如需打开此功能，请在 startLocalAudio 之前调用

    获取设备管理类 BRTCDeviceManager 

    virtual BRTCDeviceManager *getDeviceManager() = 0;

    获取媒体播放器管理类 BRTCMediaPlayerManager 

    virtual BRTCMediaPlayerManager *getMediaPlayerManager() = 0;

    关于 BRTCMediaPlayerManager 提供的接口、回调及相关数据结构，请参考 BRTCMediaPlayerManager

    自定义消息发送 

    virtual bool sendCustomCmdMsg(uint32_t cmdId, const uint8_t* data, uint32_t dataSize, bool reliable, bool ordered) = 0;

    参数

    名称 描述
    cmdID 消息 ID，取值范围为1 - 10
    data 待发送的消息，最大支持 1KB（1000 字节）的数据大小
    reliable 是否可靠发送，可靠发送的代价是会引入一定的延时，因为接收端要暂存一段时间的数据来等待重传
    ordered 是否要求有序，即是否要求接收端接收的数据顺序和发送端发送的顺序一致，这会带来一定的接收延时，因为在接收端需要暂存并排序这些消息

    返回

    • true：消息已经发出；false：消息发送失败。0则会关闭回调，建议设置为300ms

    详情

    • 该接口可以借助音视频数据通道向当前房间里的其他用户广播您自定义的数据，但因为复用了音视频数据通道
    • 请务必严格控制自定义消息的发送频率和消息体的大小，否则会影响音视频数据的质量控制逻辑，造成不确定性的问题

    将小数据量的自定义数据嵌入视频帧中 

    virtual bool sendSEIMsg(const uint8_t* data, uint32_t dataSize, int32_t repeatCount) = 0;

    参数

    名称 描述
    data 待发送的消息，最大支持 1KB（1000 字节）的数据大小
    repeatCount 发送数据次数

    返回

    • true：消息已通过限制，等待后续视频帧发送；false：消息被限制发送

    详情

    • sendSEIMsg 是将数据直接塞入视频数据头中。因此，即使视频帧被旁路到了直播 CDN 上
    • 这些数据也会一直存在。由于需要把数据嵌入视频帧中，建议尽量控制数据大小，推荐使用几个字节大小的数据
    • 最常见的用法是把自定义的时间戳（timstamp）用 sendSEIMsg 嵌入视频帧中，实现消息和画面的完美对齐
    • 数据在接口调用完后不会被即时发送出去，而是从下一帧视频帧开始带在视频帧中发送
    • 发送消息到房间内所有用户，每秒最多能发送 30 条消息（与 sendCustomCmdMsg 共享限制）
    • 每个包最大为 1KB，若发送大量数据，会导致视频码率增大，可能导致视频画质下降甚至卡顿（与 sendCustomCmdMsg 共享限制）
    • 每个客户端每秒最多能发送总计8KB数据（与 sendCustomCmdMsg 共享限制）
    • 若指定多次发送（repeatCount > 1），则数据会被带在后续的连续 repeatCount 个视频帧中发送出去，同样会导致视频码率增大
    • 如果 repeatCount > 1，多次发送，接收消息 onRecvSEIMsg 回调也可能会收到多次相同的消息，需要去重

    获取 SDK 版本信息 

    virtual const char* getSDKVersion() = 0;

    设置log输出级别 

    virtual void setLogLevel(BRTCLogLevel level) = 0;

    参数

    名称 描述
    level log级别,详见 BRTCLogLevel

    启用或禁用控制台日志打印 

    virtual void setConsoleEnabled(bool enabled) = 0;

    参数

    名称 描述
    enabled 指定是否启用，默认为禁止状态

    修改日志保存路径 

    virtual void setLogDirPath(const char* path) = 0;

    参数

    名称 描述
    path log级别,存储日志路径

    详情

    • 日志文件默认保存在 C:/Users/[系统用户名]/AppData/Roaming/BRTC/log，即 %appdata%/BRTC/log 下，如需修改，必须在所有方法前调用

    设置日志回调 

    virtual void setLogCallback(BRTCLogCallback* callback) = 0;

    调用实验性 API 接口 

    virtual void callExperimentalAPI(const char* jsonStr) = 0;

    参数

    名称 描述
    jsonStr 接口及参数描述的 JSON 字符串

    详情

    • 该接口用于调用一些实验性功能
    {{allComment[version]}} ×
    • 暂无评论
    • {{comment.author}}
      {{ comment.createdAt | date: 'yyyy-MM-dd HH:mm:ss '}}
      {{comment.content}}
    您需要 后才能评论