订阅音视频流

本文详细介绍如何使用百家云 C++ SDK 订阅和取消订阅远端音视频。
相关函数接口在 c++-sdk 2.5.5 及以上版本支持。

设定订阅模式

您可以通过调用 BRTC 中的 setDefaultStreamRecvMode 接口设置订阅模式，需要在进入房间 enterRoom 前调用该接口，设置才能生效。BRTC 提供了两种订阅模式：

• 自动订阅：SDK 会自动播放远端用户的声音和视频，无需您进行额外操作，这是 SDK 的默认行为。在一个教室内的人数超过6人时，建议采用手动订阅模式，根据实际业务场景来判定是否需要订阅哪路流；也可以节省拉流端的带宽消耗，降低拉流的卡顿率。
• 手动订阅：SDK 不会自动拉取和播放远端用户的声音和视频，需要您手动调用 muteRemoteAudio 来触发声音的播放， muteRemoteVideoStream 或者 startRemoteViewx 来触发视频的播放。

需要您注意的是，如果您不调用 setDefaultStreamRecvMode 也是没有关系的，SDK 的默认行为是自动订阅。但如果您希望设置为手动订阅，请务必注意 setDefaultStreamRecvMode 只有在 enterRoom 之前调用才有效果。

音频流的播放

您可以通过调用接口 muteRemoteAudio 来静音远端用户的声音，之后也可以通过调用接口 muteRemoteAudio 来解除对他的静音。

• 当您静音某用户的远端音频时，SDK 会停止播放指定用户的声音。
• 在调用了 muteAllRemoteAudio 后，仍然可以调用此方法单独针对某一个当前已订阅的远端用户进行设置

// 静音指定用户 userId 的音频
m_pBrtc->muteRemoteAudio(userId, true);
// 恢复指定用户 userId 的音频播放
m_pBrtc->muteRemoteAudio(userId, false);
// 静音所有远端用户的音频流
m_pBrtc->muteAllRemoteAudio(true);
// 恢复播放所有远端用户的音频流
m_pBrtc->muteAllRemoteAudio(false);

视频流的播放

您可以通过调用接口 startRemoteView 来显示远端用户的视频画面，但前提是您需要传递给 SDK 一个 view 对象，用来作为承载该用户的视频画面的渲染控件。

startRemoteView 的第一个参数是远端用户的 userId，第二个参数是远端用户的流类型，第三个参数则是您需要传递的 view 对象。其中第二个参数 streamType(流类型) 有三个可选的值，分别是：

• BRTCVideoStreamTypeBig：用户的主路画面，一般用来传输用户摄像头的画面。
• BRTCVideoStreamTypeSmall：用户的低清小画面，这是相对于主路画面而言的
• BRTCVideoStreamTypeSub：用户的辅路画面，一般用来传输用户屏幕分享的画面。

注意事项

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

// 指定渲染远端用户的大流画面
m_pBrtc->setRemoteVideoStreamType(userId, BRTCVideoStreamTypeBig);

BRTCRenderParams remoteRenderParams;
// 适配长边模式，短边区域填充黑色
remoteRenderParams.fillMode = BRTCVideoFillMode_Fit;
// 画面不旋转
remoteRenderParams.rotation = BRTCVideoRotation_0;
// 摄像头画面不镜像
remoteRenderParams.mirrorType = BRTCVideoMirrorTypeDisable;
// 设置远端视频渲染参数
m_pBrtc->setRemoteRenderParams(userId, BRTCVideoStreamTypeBig, remoteRenderParams);
// 播放 userId 的主画面
m_pBrtc->startRemoteView(userId, BRTCVideoStreamTypeBig, view);
// 播放 userId 的低分辨率画面（主画面和低分辩率画面只能二选一）
// m_pBrtc->startRemoteView(userId, BRTCVideoStreamTypeSmall, view);
// 播放 userId 的屏幕分享画面，如果和主画面同时显示，需要配置不同的View对象
// m_pBrtc->startRemoteView(userId, BRTCVideoStreamTypeSub, view);
// 开始接收指定用户的远端视频流
m_pBrtc->muteRemoteVideoStream(userId,  false);

视频流停止播放

通过调用 stopRemoteView 接口，您可以停止播放某一个远端用户的视频。

m_pBrtc->muteRemoteVideoStream(userId, true);
m_pBrtc->stopRemoteView(userId, BRTCVideoStreamTypeBig);

设置播放参数

通过调用 updateRemoteView 接口，您可以在播放中变更 view 对象，这在切换视频渲染控件时非常有用。 通过 setRemoteRenderParams 您可以设置画面的填充模式、旋转角度和镜像模式。

• 填充模式：分为填充或者适应，如果画面的显示分辨率不等于画面的原始分辨率，就需要您设置画面的填充模式
  • BRTCVideoFillMode_Fill 图像铺满屏幕，超出显示视窗的视频部分将被裁剪，画面显示可能不完整;
    • 横向模式下采集的视频
    • 竖屏模式下采集的视频
  • BRTCVideoFillMode_Fit 图像长边填满屏幕，短边区域会被填充黑色
    • 横向模式下采集的视频
    • 竖屏模式下采集的视频
• 旋转角度：可以设置 0 度、90 度、180 度 和 270 度等四个旋转角度
• 镜像模式：即画面的左右镜像模式
  • BRTCVideoMirrorTypeEnable， 摄像头画面镜像
  • BRTCVideoMirrorTypeDisable， 摄像头画面不镜像

// 将 userId 的主路画面切换到一个悬浮的窗口中（假定该小窗口为 floatingView）
m_pBrtc->updateRemoteView(userId, BRTCVideoStreamTypeBig，floatingView);

BRTCRenderParams remoteRenderParams;
// 适配长边模式，短边区域填充黑色
remoteRenderParams.fillMode = BRTCVideoFillMode_Fit;
// 画面不旋转
remoteRenderParams.rotation = BRTCVideoRotation_0;
// 前后置摄像头画面均不镜像
remoteRenderParams.mirrorType = BRTCVideoMirrorTypeDisable;
// 设置远端视频渲染参数
m_pBrtc->setRemoteRenderParams(userId, BRTCVideoStreamTypeBig, remoteRenderParams);

感知房间中远端用户的音视频状态

您可以控制对远端用户的声音和视频的播放，需要通过如下接口获取房间中推流的用户信息、推流的摄像头和麦克风设备状态：

• 音频状态变化通知 当远端用户开启或关闭麦克风时，您可以通过监听 onUserAudioAvailable 来感知到这个状态的变化。
  • 自动订阅模式下，收到此通知表示远端用户的音频流已经到达并会被自动拉取并解码播放
  • 手动订阅模式下，收到此通知表示远端用户的音频流已经可用，但还需要主动触发订阅才能解码播放

• 视频状态变化通知

  • 远端用户是否存在可播放的主路画面（一般用于摄像头）
  • 收到 onUserVideoAvailable(userId, true) 通知时，表示该路画面已经有可用的视频数据帧到达，此时，您需要调用 startRemoteView 接口加载该用户的远程画面。
    • 自动订阅模式下，收到此通知表示远端用户的视频流已经到达并会被自动拉取并解码
    • 手动订阅模式下，收到此通知表示远端用户的视频流已经可用，但还需要主动触发订阅才会拉取
  • 收到 onUserVideoAvailable(userId, false) 通知时，表示该路远程画面已被关闭，可能由于您主动 mute 了该用户的视频，或者该用户关闭了自己的视频

• 屏幕共享流可用状态通知

  • 端用户的辅流（通常是屏幕共享）的可用或不可用状态发生状态变化时通知
  • “辅路画面”一般被用于承载屏幕分享的画面。当您收到 onUserSubStreamAvailable(userId, true) 通知时，表示该路画面已经有可用的视频数据帧到达。您可以调用 startRemoteView 传入 BRTCVideoStreamTypeSub 类型来请求预览。
• 用户进出房间的通知
  • 当有远端用户进入当前房间时，您可以通过 onRemoteUserEnterRoom(userId) 来感知到该用户的 userId，
  • 当有远端用户离开当前方式时，您可以通过 onRemoteUserLeaveRoom(userId, reason) 来感知到该用户的 userId 以及他/她离开的原因。
  • onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，如果需要显示远程画面，建议使用监听 onUserVideoAvailable() 事件回调

class BRTCCore : public BRTCCallback, public BRTCAudioFrameCallback {
 public:
   // interface BRTCCallback
   void onEnterRoom(int result) override;
   void onExitRoom(uint32_t reason) override;
   void onUserAudioAvailable(const char* userId, bool available) override;
   void onUserVideoAvailable(const char* userId, bool available) override;
   void onStatistics(const BRTCStatistics& statistics) override;
   void onError(BRTCAVError errCode, const char* errMsg, void* extraInfo) override;
   //...
   // interface BRTCAudioFrameCallback
   void onCapturedRawAudioFrame(BRTCAudioFrame* frame) override;
   void onLocalProcessedAudioFrame(BRTCAudioFrame* frame) override;
   void onCustomAudioRenderingFrame(BRTCAudioFrame* frame) override;

 private:
   BRTC* m_pBrtc = nullptr;
}

void BRTCCore::onRemoteUserEnterRoom(const char* userId) {
  LOG(INFO) << "a member enter, uid[" << userId << "]";
  // 添加远端用户进入房间处理逻辑
}
void BRTCCore::onRemoteUserLeaveRoom(const char* userId, uint32_t reason) {
  LOG(INFO) << "a member exit, uid[" << userId << "], reason[" << reason << "]";
  // 添加远端用户退出房间处理逻辑
}
void BRTCCore::onUserAudioAvailable(const char* userId, bool available) {
  LOG(INFO) << "uid[" << userId << "], audio available[" << available << "]";
  // 添加用户音频可用/不可用处理逻辑
}
void BRTCCore::onUserVideoAvailable(const char* userId, bool available) {
  LOG(INFO) << "uid[" << userId << "], video available[" << available << "]";
  // 添加用户视频可用/不可用处理逻辑
}
void BRTCCore::onUserSubStreamAvailable(const char* userId, bool available) {
  LOG(INFO) << "uid[" << userId << "], screen share available[" << available << "]";
  // 添加用户屏幕共享可用/不可用处理逻辑
}

三种不同的静音

随着您的业务需求不断深入，您会发现有三种不同的“静音”，虽然他们都叫“静音”，但是实现机制和效果完全不同

• 第一种：播放端停止订阅音频流 如果您调用了 muteRemoteAudio(userId, true) 函数，代表您不希望再播放该远端用户的声音，此时 SDK 会停止拉取该用户的音频数据流。这种模式是比较节省流量了。当时当您希望再次播放该用户的声音时，SDK 需要重新启动一次音频数据的拉取流程，所以从“静音”到“解除静音”的状态，恢复速度会比较慢。
• 第二种：将播放音量调整为零 如果您的业务场景需要静音切换有更快地反应速度，您可以通过 setRemoteAudioVolume(userId, 0) 将远端用户 userId 的播放音量设置为零，该接口由于不涉及网络操作，因此影响速度非常快。
• 第三种：远端用户自己关闭麦克风 上面两个操作都是在介绍播放端的操作，这些操作所产生的效果仅对当前用户生效，比如您通过 muteRemoteAudio(userId, true) 将远端用户设置为静音，房间中的其他用户还是能听到该用户的声音。 如果要让该用户彻底“闭嘴”，就需要调用 muteLocalAudio 影响该的音频发布行为。