跨房间连麦

跨房间连麦中需要区分主房间和副房间概念。主副房间是相对概念，定义如下：

• 主房间：本端在最开始加入的房间。
• 副房间：在连麦邀请被接受后，双方均需要加入对方房间。

跨房间连麦前需要双方都已经加入自己的主房间，未加入主房间前无法进行连麦的邀请和被邀请。

处理连麦邀请

在建立连麦前，需要由一位主播发出邀请，另一位主播作出同意或拒绝连麦的应答。

设置连麦事件回调监听

方法

JavaScript

engine.setOnJoinSubRoomRequestedListener();

回调参数

参数	类型	说明
code	Number	错误码，0 表示成功
errMsg	String	错误信息

示例代码

JavaScript

// 邀请其他用户跨房间连麦的回调
engine.setOnJoinSubRoomRequestedListener(({code, errMsg}) => {
  if (code == 0) {
    // 邀请其他用户跨房间连麦成功, 等待对方处理
    console.log('连麦邀请发送成功');
  } else {
    // 邀请其他用户跨房间连麦失败
    console.log('连麦邀请发送失败:', errMsg);
  }
});

发起邀请

向指定用户发送跨房间连麦请求，调用 RCRTCEngine 对象的 requestJoinSubRoom 方法。请求发送成功后，被邀请人会通过 setOnJoinSubRoomRequestReceivedListener 回调收到通知。

方法

JavaScript

engine.requestJoinSubRoom();

参数说明

参数	类型	必填	说明
roomId	String	是	对方的房间 ID
userId	String	是	对方用户 ID
autoLayout	Boolean	是	是否采用悬浮布局。如为 true，服务端会在加入邀请方房间成功后，把受邀方的流资源合并到邀请方视图上（默认仅悬浮布局合流）。如受邀方未发布资源，则会在受邀方发布资源后进行视图合并。无论 autoLayout 为 true 或 false，双方都可以使用 setLiveMixCustomLayouts 方法主动设置合流布局。一旦主动设置过合流布局，后续音视频直播过程中设置的自动合流参数将失效。默认值：true
extra	String	否	附加信息

示例代码

JavaScript

// 邀请其他用户跨房间连麦
engine.requestJoinSubRoom(roomId, userId);
console.log('连麦邀请已发送');

设置收到连麦邀请监听

方法

JavaScript

engine.setOnJoinSubRoomRequestReceivedListener();

回调参数

参数	类型	说明
roomId	String	对方的房间 ID
userId	String	对方用户 ID
extra	String	附加信息

示例代码

JavaScript

// 收到其他用户发起的跨房间连麦邀请
engine.setOnJoinSubRoomRequestReceivedListener(({roomId, userId, extra}) => {
  console.log('收到连麦邀请:', userId);
  // 同意其他用户的跨房间连麦邀请
  engine.responseJoinSubRoomRequest(roomId, userId, true);
});

应答邀请

被邀请人端收到邀请后，SDK 会触发 RCRTCEngine 对象的 setOnJoinSubRoomRequestReceivedListener 回调方法。接收到邀请通知后，需要进行应答，可以同意连麦或拒绝连麦。

• 如果同意连麦，需调用 responseJoinSubRoomRequest 方法并将 agree 参数设置为 true，发送同意连麦的应答。后续需要调用 joinSubRoom 加入副房间。
• 如果拒绝连麦，需调用 responseJoinSubRoomRequest 方法并将 agree 参数设置为 false。

方法

JavaScript

engine.responseJoinSubRoomRequest();

参数说明

参数	类型	必填	说明
roomId	String	是	对方的房间 ID
userId	String	是	对方用户 ID
agree	Boolean	是	是否同意连麦
autoLayout	Boolean	是	是否采用悬浮布局。如为 true，服务端会在加入邀请方房间成功后，把受邀方的流资源合并到邀请方视图上（默认仅悬浮布局合流）。如受邀方未发布资源，则会在受邀方发布资源后进行视图合并。无论 autoLayout 为 true 或 false，双方都可以使用 setLiveMixCustomLayouts 方法主动设置合流布局。一旦主动设置过合流布局，后续音视频直播过程中设置的自动合流参数将失效。默认值：true
extra	String	否	附加信息

示例代码

JavaScript

// 同意其他用户的跨房间连麦邀请
engine.responseJoinSubRoomRequest(roomId, userId, true);
console.log('连麦邀请应答已发送');

设置应答结果监听

方法

JavaScript

engine.setOnJoinSubRoomRequestRespondedListener();

回调参数

参数	类型	说明
roomId	String	对方的房间 ID
userId	String	对方用户 ID
agree	Boolean	是否同意连麦
code	Number	错误码，0 表示成功
errMsg	String	错误信息

示例代码

JavaScript

// 同意其他用户的跨房间连麦邀请后触发的回调
engine.setOnJoinSubRoomRequestRespondedListener(({roomId, userId, agree, code, errMsg}) => {
  if (code == 0) {
    // 同意响应成功
    console.log('连麦邀请应答成功');
  } else {
    // 同意响应失败
    console.log('连麦邀请应答失败:', errMsg);
  }
});

对连麦邀请作出应答后，本端会通过 setOnJoinSubRoomRequestRespondedListener 回调方法收到来自融云服务端的通知，此时可认为应答成功。同时，邀请方会收到 setOnJoinSubRoomRequestResponseReceivedListener，此时表示已接收到对方对连麦邀请作出的回复。

提示

• 如果同意连麦，两个房间内的所有非观众用户（被邀请方除外）都会收到 setOnJoinSubRoomRequestResponseReceivedListener 应答回调。
• 如果拒绝连麦，只有邀请方会收到应答拒绝的回调 setOnJoinSubRoomRequestResponseReceivedListener，其他所有用户都不会收到该应答回调。

设置收到应答监听

方法

JavaScript

engine.setOnJoinSubRoomRequestResponseReceivedListener();

回调参数

参数	类型	说明
roomId	String	对方的房间 ID
userId	String	对方用户 ID
agree	Boolean	是否同意连麦

示例代码

JavaScript

// 收到其他用户对连麦邀请的应答
engine.setOnJoinSubRoomRequestResponseReceivedListener(({roomId, userId, agree}) => {
  if (agree) {
    console.log('对方同意连麦邀请');
  } else {
    console.log('对方拒绝连麦邀请');
  }
});

取消邀请

您的 App 用户可能在发起连麦邀请后改变主意，想要取消邀请，此时可调用 RCRTCEngine 对象的 cancelJoinSubRoomRequest 方法来取消正在进行中的跨房间连麦邀请。取消邀请时，被邀请人会收到 setOnCancelJoinSubRoomRequestReceivedListener 回调。

方法

JavaScript

engine.cancelJoinSubRoomRequest();

参数说明

参数	类型	必填	说明
roomId	String	是	对方的房间 ID
userId	String	是	对方用户 ID

示例代码

JavaScript

// 取消之间发起的跨房间连麦邀请
engine.cancelJoinSubRoomRequest(roomId, userId);
console.log('连麦邀请取消请求已发送');

设置取消邀请结果监听

方法

JavaScript

engine.setOnJoinSubRoomRequestCanceledListener();

回调参数

参数	类型	说明
roomId	String	对方的房间 ID
userId	String	对方用户 ID
code	Number	错误码，0 表示成功
errMsg	String	错误信息

示例代码

JavaScript

// 取消之间发起的跨房间连麦邀请的回调
engine.setOnJoinSubRoomRequestCanceledListener(({roomId, userId, code, errMsg}) => {
  if (code == 0) {
    // 取消成功
    console.log('连麦邀请取消成功');
  } else {
    // 取消失败
    console.log('连麦邀请取消失败:', errMsg);
  }
});

设置收到取消邀请监听

方法

JavaScript

engine.setOnCancelJoinSubRoomRequestReceivedListener();

回调参数

参数	类型	说明
roomId	String	对方的房间 ID
userId	String	对方用户 ID

示例代码

JavaScript

// 收到其他用户取消连麦邀请的通知
engine.setOnCancelJoinSubRoomRequestReceivedListener(({roomId, userId}) => {
  console.log('对方取消了连麦邀请');
});

加入副房间流程

在连麦邀请被接受后，双方均需要加入对方房间。相对在本端已加入直播房间主播用户来说，对方房间为副房间。加入副房间方法如下：

方法

JavaScript

engine.joinSubRoom();

参数说明

参数	类型	必填	说明
roomId	String	是	副房间 ID

示例代码

JavaScript

// 加入副房间
engine.joinSubRoom(roomId);
console.log('加入副房间请求已发送');

邀请方与受邀方加入副房间的时机如下：

• 受邀方：在作出同意连麦的应答成功后，调用 RCRTCEngine 对象的 joinSubRoom 方法加入副房间。
• 邀请方：在收到同意连麦的应达后（setOnJoinSubRoomRequestResponseReceivedListener），调用 RCRTCEngine 对象的 joinSubRoom 方法加入副房间。此时会触发 setOnSubRoomJoinedListener、setOnSubRoomBandedListener、setOnUserJoinedListener 回调。

设置加入副房间结果监听

方法

JavaScript

engine.setOnSubRoomJoinedListener();

回调参数

参数	类型	说明
roomId	String	副房间 ID
code	Number	错误码，0 表示成功
errMsg	String	错误信息

示例代码

JavaScript

// 加入副房间结果的回调
engine.setOnSubRoomJoinedListener(({roomId, code, errMsg}) => {
  if (code == 0) {
    // 加入副房间成功
    console.log('加入副房间成功');
  } else {
    // 加入副房间失败
    console.log('加入副房间失败:', errMsg);
  }
});

在超过两位主播连麦时，可能还会有以下两种场景：

• 场景 A：在当前用户加入主房间前，该主房间已有主播用户与其他房间另一用户成功建立跨房间连麦。当前用户可在加入主房间时收到 onSubRoomBanded 回调，用户可在此回调中选择是否加入其他副房间。详细流程如下：

  1. 调用 RCRTCEngine 中 joinRoom 方法加入主房间。

  2. setOnSubRoomBandedListener 事件回调方法被触发。

     JavaScript

     /**
     * 主房间中主播已经加入的副房间的回调
     */
     engine.setOnSubRoomBandedListener();

  3. 调用 RCRTCEngine 对象的 joinSubRoom 方法加入副房间。

• 场景 B：在当前用户加入主房间后，主房间内的另一主播用户发起了跨房间连麦并加入了其他房间，此时当前用户会收到 setOnSubRoomBandedListener 回调，用户可在此回调中选择是否加入其他副房间。

设置副房间绑定监听

方法

JavaScript

engine.setOnSubRoomBandedListener();

回调参数

参数	类型	说明
roomId	String	副房间 ID

示例代码

JavaScript

// 主房间中主播已经加入的副房间的回调
engine.setOnSubRoomBandedListener(({roomId}) => {
  console.log('检测到副房间绑定:', roomId);
});

订阅资源

在加入副房间成功后，需要订阅副房间主播的资源。有两种方式：

• 加入副房间后，通过 RCRTCEngine 对象的 subscribe 方法订阅副房间中远端用户已经发布的音视频资源。参考 订阅资源。

  JavaScript

  engine.setOnSubscribedListener(({id, type, code, message}) => {
    // 订阅远端用户的资源的回调
    if (code == 0) {
      // 订阅成功
      console.log('订阅成功');
    } else {
      // 订阅失败
      console.log('订阅失败:', message);
    }
  });
  
  // 订阅远端用户的资源
  engine.subscribe(userId, RCRTCMediaType.Video);

• 副房间主播发布资源时，setOnRemotePublishedListener 方法会被触发，可通过 roomId 判断是否为副房间。在该回调中调用 subscribe 方法订阅副房间中远端用户刚发布的音视频资源。

  JavaScript

  // 远端用户发布资源的回调
  engine.setOnRemotePublishedListener(({roomId, userId, type}) => {
    // 订阅远端用户发布的资源
    engine.subscribe(userId, type);
  });

如需取消订阅资源，可调用 unsubscribe 方法取消订阅的资源，可参考 取消订阅资源。

暂时中止连麦

当需要暂时中止连麦时，可离开副房间。调用 RCRTCEngine 对象的 leaveSubRoom 方法暂时离开副房间，

方法

JavaScript

engine.leaveSubRoom();

参数说明

参数	类型	必填	说明
roomId	String	是	副房间 ID
disband	Boolean	是	是否结束连麦，暂时中止连麦时设置为 false

示例代码

JavaScript

// 调用离开副房间, disband:boolean 离开副房间时是否结束连麦。
engine.leaveSubRoom(roomId, false);
console.log('暂时中止连麦请求已发送');

disband 指定是否要结束连麦，在暂时中止连麦的场景下必须设置为 false，仅代表调用方离开副房间，但不结束连麦。成功离开副房间后，调用者会收到 setOnUserLeftListener 回调。其他用户会收到 onUserLeft 回调，对端主播可在该回调中取消订阅离开的主播。

设置离开副房间结果监听

方法

JavaScript

engine.setOnUserLeftListener();

回调参数

参数	类型	说明
roomId	String	房间 ID
code	Number	错误码，0 表示成功
message	String	错误信息

示例代码

JavaScript

// 离开副房间的回调
engine.setOnUserLeftListener(({roomId, code, message}) => {
  if (code == 0) {
    // 离开成功
    console.log('离开副房间成功');
  } else {
    // 离开失败
    console.log('离开副房间失败:', message);
  }
});

暂时中止连麦后，融云服务会自动在合流中移除该主播资源。对端主播房间中订阅合流的观众拉流地址不变，可以看到本房间主播，但无法看到暂时离开的主播。需要恢复连麦时，当前主播可再次加入副房间，无需再执行邀请应答流程。

结束连麦

当连麦结束时，需要调用 RCRTCEngine 对象的 leaveSubRoom 方法离开副房间，同时指定连麦结束。

方法

JavaScript

engine.leaveSubRoom();

参数说明

参数	类型	必填	说明
roomId	String	是	副房间 ID
disband	Boolean	是	是否结束连麦，结束连麦时设置为 true

示例代码

JavaScript

// 结束连麦
engine.leaveSubRoom(roomId, true);
console.log('结束连麦请求已发送');

disband 指定是否要结束连麦，在此场景下必须设置为 true。此方法内部会取消订阅已经订阅的副房间所有用户音视频资源，上层无需自行取消订阅。成功结束连麦后，调用者会收到 setOnSubRoomLeftListener 回调，其他用户会收到 setOnSubRoomDisbandListener 回调。

设置离开副房间监听

方法

JavaScript

engine.setOnSubRoomLeftListener();

回调参数

参数	类型	说明
roomId	String	副房间 ID
code	Number	错误码，0 表示成功
errMsg	String	错误信息

示例代码

JavaScript

// 调用离开副房间的回调
engine.setOnSubRoomLeftListener(({roomId, code, errMsg}) => {
  if (code == 0) {
    console.log('离开副房间成功');
  } else {
    console.log('离开副房间失败:', errMsg);
  }
});

设置副房间解散监听

方法

JavaScript

engine.setOnSubRoomDisbandListener();

回调参数

参数	类型	说明
roomId	String	副房间 ID

示例代码

JavaScript

// 收到结束跨房间连麦的回调
engine.setOnSubRoomDisbandListener(({roomId}) => {
  console.log('副房间已解散:', roomId);
});

暂时中止连麦后，融云服务会自动在合流中移除该主播资源。对端主播房间中订阅合流的观众拉流地址不变，可以看到本房间主播，但无法看到暂时离开的主播。

被服务端踢出房间流程

提示

通过调用服务端 API 可以将指定房间的指定用户踢出该房间。

• 在踢出某个用户之前 ，建议先通过服务下发 IM 消息让此客户端执行结束跨房间连麦的流程 ，然后再从主房间踢出违禁用户。
• 如果将当前用户踢出主房间，该用户会收到 setOnKickedListener 回调，并且 RTC SDK 内部会调用 leaveRoom 方法先退出已经加入的副房间，再退出主房间并销毁资源。UI 层无需再次调用离开主、副房间的方法，只处理上层逻辑即可。内部自动调用 leaveRoom 后，在此房间的其他用户会收到 onUserLeft 回调。
• 如果将当前用户踢出跨房间连麦的副房间，该用户会收到 setOnKickedListener 回调，并且仅退出指定的副房间，并取消订阅该副房间中的音视频资源，UI 层无需再次调用离开副房间的方法，只处理上层逻辑即可。

设置被踢出房间监听

方法

JavaScript

engine.setOnKickedListener();

回调参数

参数	类型	说明
roomId	String	房间 ID，可通过 roomId 判断是否为主房间或副房间
code	Number	错误码
errMsg	String	错误信息

示例代码

JavaScript

/**
* 被服务端踢下线，可通过 roomId 判断是否为主房间或副房间
* 如果用户在房间内, 此时收到服务器踢出房间的通知, SDK 会关闭音视频连接, 释放资源,
* 将用户踢出房间, 回调通知用户被踢出房间
*/
engine.setOnKickedListener(({roomId, code, errMsg}) => {
  console.log('被踢出房间:', roomId, '原因:', errMsg);
});