订阅音视频流

本文详细介绍如何使用百家云 C++ SDK 订阅和取消订阅远端音视频。

设定订阅模式

您可以通过调用 setDefaultStreamRecvMode 接口设置订阅模式。
⚠️ 注意需要在进入房间前调用该接口，设置才能生效。

BRTC 提供了两种订阅模式：

• 自动订阅：SDK的默认订阅模式。在这种模式下，SDK 会自动拉取远端用户的音视频流，并自动播放声音。在这种模式下，即便您不进行任何接口调用，也会占用下行带宽。
• 手动订阅：与自动订阅模式相反，SDK 不会自动拉取远端用户的音视频流，需要您手动调用相关接口完成音视频流的订阅和渲染、播放。在这种模式下，不会占用下行带宽。

您可以根据您的实际业务场景来决定采用哪种模式。例如，当房间内人数超过 6 人同时推流时，采用手动订阅模式，以节省每个设备的下行带宽。

虽然手动订阅可以节省下行带宽，但由于发起订阅并渲染播放需要消耗一定时间，因此从接口调用到实际看到（听到），会比自动订阅模式下慢一些。

音频流的播放

无论是在手动还是自动订阅模式下，您都可以通过调用接口 muteRemoteAudio 来静音或恢复某个远端用户的声音。

• 自动订阅模式下，还会继续拉取该远端用户的音频数据。需要恢复播放时速度较快。
• 手动订阅模式下，会停止拉取该用户的音频数据数据。恢复播放的速度比自动订阅模式下慢一些。
• 在调用了 muteAllRemoteAudio 后，仍然可以调用 muteRemoteAudio 方法单独针对某一个远端用户进行设置

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

视频流的播放

您可以通过调用接口 startRemoteView 来显示远端用户的视频画面。 startRemoteView 需要您指定几个必要的参数，主要包括：用户ID，流类型以及用来渲染视频画面的视图封装类对象。 其中流类型有三个可选的值，分别是：

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

⚠️ 注意事项

• 该函数会拉取指定 userid 的视频流显示在您指定的 view 控件上，您可以通过 setRemoteRenderParams 设置显示模式
• 如果您提前知道房间中某个 userid 正在推流，可以直接调用 startRemoteView 显示该用户的远端画面
• 如果您不知道房间中有哪些用户开启了视频，可以监听 onUserVideoAvailable 回调通知，当可用状态变为 true 时，就可以调用此方法来显示该用户的视频了
• 调用 startRemoteView 后，如果没有异常情况，视频画面在开始渲染时，会通过 onFirstVideoFrame 通知您
• SDK 支持同时观看某 userid 的大画面和辅路画面，或者小画面和辅路画面，但不支持同时观看大画面和小画面
• 只有当指定的 userid 通过 enableEncSmallVideoStream 开启双路编码后，才能观看该用户的小画面
• 如果该用户的小画面不存在，则默认显示大画面

// 恢复指定用户userID的视频流（即通知服务器继续下发视频数据）
m_pBrtc->muteRemoteVideoStream(userId,  false);
// 指定渲染远端用户的大流画面（可选）
m_pBrtc->setRemoteVideoStreamType(userId, BRTCVideoStreamTypeBig);
// 渲染用户的主画面
m_pBrtc->startRemoteView(userId, BRTCVideoStreamTypeBig, view);

// 改变远端用户视频的渲染参数（可选）
BRTCRenderParams remoteRenderParams;
remoteRenderParams.fillMode = BRTCVideoFillMode_Fit;
remoteRenderParams.rotation = BRTCVideoRotation_0;
remoteRenderParams.mirrorType = BRTCVideoMirrorTypeDisable;
m_pBrtc->setRemoteRenderParams(userId, BRTCVideoStreamTypeBig, remoteRenderParams);

// 显示远端用户视频后，还可以暂停或恢复
m_pBrtc->muteRemoteVideoStream(userId, true or false);

视频流停止播放

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

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

设置播放参数

通过 setRemoteRenderParams 您可以设置画面的填充模式、旋转角度和镜像模式。

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

BRTCRenderParams remoteRenderParams;
remoteRenderParams.fillMode = BRTCVideoFillMode_Fit;
remoteRenderParams.rotation = BRTCVideoRotation_0;
remoteRenderParams.mirrorType = BRTCVideoMirrorTypeDisable;
m_pBrtc->setRemoteRenderParams(userId, BRTCVideoStreamTypeBig, remoteRenderParams);

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

您可以通过 onUserAudioAvailable 和 onUserVideoAvailable 监听远端用户的音频和视频状态变化。

音频频状态变化通知
当远端用户开启或关闭麦克风时，您可以通过监听 onUserAudioAvailable 来感知到这个状态的变化。其中：

• 自动订阅模式下，收到此通知表示远端用户的音频流已经到达并随后马上播放出来
• 手动订阅模式下，收到此通知表示远端用户的音频流已经可用，但还需要主动触发订阅才能解码播放

视频状态变化通知
当收到 onUserVideoAvailable 通知时，表示远端用户的主视频流可用状态发生变化。如需显示，您需要调用 startRemoteView 接口加载该用户的视频画面。

• 自动订阅模式下，收到此通知表示远端用户的视频流已经到达并会被自动拉取并解码
• 手动订阅模式下，收到此通知表示远端用户的视频流已经可用，但还需要主动触发订阅才会拉取
• 收到 onUserVideoAvailable(userid, false) 通知时，通常这代表用户关闭了自己的视频

屏幕共享流可用状态通知

当您收到 onUserSubStreamAvailable 通知时，表示远端用户的辅流（通常是屏幕共享）可用状态发生了变化。当变为可用时，startRemoteView 接口加载该用户的辅流画面。其他逻辑与 onUserVideoAvailable 相同。

📝 只有当远端用户调用 startScreenCapture 接口设置的流类型为 BRTCVideoStreamTypeSub 时，您才会收到 onUserSubStreamAvailable 回调通知。

用户进出房间的通知

• 当有远端用户进入当前房间时，您可以通过 onRemoteUserEnterRoom 来监听到回调通知
• 当有远端用户离开当前房间时，您可以通过 onRemoteUserLeaveRoom 来监听到回调通知
• onRemoteUserEnterRoom 和 onRemoteUserLeaveRoom 只适用于维护当前房间里的“成员列表”，并不代表此用户的音视频可用状态
• 如果房间人数较多时，可能会存在较为频繁的远端用户进退通知，如果你的业务场景需要采用静默模式，可以与我们联系进行配置。

class BRTCCore : public BRTCCallback {
 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;

 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 会停止拉取该用户的音频数据流，下行的音频流数据变为 0。当您希望再次播放该用户的声音时，SDK 会重新发送信令，请求服务器下发音频数据，这个会消耗一点时间。

• 第二种：调用 setRemoteAudioVolume
  这种方法是将某个远端用户的音频数据在混音前清零，从而达到静音的效果。这种方式，拉流并未停止，还会继续占用下行带宽。

如果您使用 muteRemoteAudio 或者 setRemoteAudioVolume 来静音，您将无法通过 onPlayAudioFrame 来获取远端用户的音频 PCM 数据，因为他们已经被置为 0 了。