跨房间连麦

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

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

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

设置连麦事件回调监听

设置邀请连麦事件回调

方法

Dart
RCRTCEngine.onJoinSubRoomRequested

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
code	接口结果码
message	失败原因

示例代码

Dart
engine.onJoinSubRoomRequested = (roomId, userId, code, message) {
  if (code == 0) {
    // 邀请其他用户跨房间连麦成功, 等待对方处理
    print('邀请用户 $userId 跨房间连麦成功');
  } else {
    // 邀请其他用户跨房间连麦失败
    print('邀请用户 $userId 跨房间连麦失败: $message');
  }
};

设置收到连麦邀请事件回调

方法

Dart
RCRTCEngine.onJoinSubRoomRequestReceived

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
extra	附加信息

示例代码

Dart
engine.onJoinSubRoomRequestReceived = (String roomId, String userId, String? extra) {
  // roomId 对方的房间 ID
  // userId 对方用户 ID
  // extra 附加信息
  print('收到用户 $userId 的跨房间连麦邀请');
};

设置连麦邀请应答事件回调

方法

Dart
RCRTCEngine.onJoinSubRoomRequestResponded

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
agree	是否同意连麦
code	接口结果码
errMsg	失败原因

示例代码

Dart
engine.onJoinSubRoomRequestResponded = (String roomId, String userId, bool agree, int code, String? errMsg) {
  if (code == 0) {
    // 同意响应成功
    print('同意用户 $userId 的跨房间连麦邀请成功');
  } else {
    // 同意响应失败
    print('同意用户 $userId 的跨房间连麦邀请失败: $errMsg');
  }
};

设置收到连麦邀请应答事件回调

方法

Dart
RCRTCEngine.onJoinSubRoomRequestResponseReceived

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
agree	是否同意连麦

示例代码

Dart
engine.onJoinSubRoomRequestResponseReceived = (String roomId, String userId, bool agree) {
  // roomId 对方的房间 ID
  // userId 对方用户 ID
  // agree 是否同意连麦
  if (agree) {
    print('用户 $userId 同意了跨房间连麦邀请');
  } else {
    print('用户 $userId 拒绝了跨房间连麦邀请');
  }
};

设置取消连麦邀请事件回调

方法

Dart
RCRTCEngine.onJoinSubRoomRequestCanceled

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
code	接口结果码
errMsg	失败原因

示例代码

Dart
engine.onJoinSubRoomRequestCanceled = (String roomId, String userId, int code, String? errMsg) {
  if (code == 0) {
    // 取消成功
    print('取消邀请用户 $userId 跨房间连麦成功');
  } else {
    // 取消失败
    print('取消邀请用户 $userId 跨房间连麦失败: $errMsg');
  }
};

设置收到取消连麦邀请事件回调

方法

Dart
RCRTCEngine.onCancelJoinSubRoomRequestReceived

返回值

参数	描述
roomId	对方的房间 ID
userId	对方用户 ID
extra	附加信息

示例代码

Dart
engine.onCancelJoinSubRoomRequestReceived = (String roomId, String userId, String? extra) {
  // roomId 对方的房间 ID
  // userId 对方用户 ID
  // extra 附加信息
  print('收到用户 $userId 取消跨房间连麦邀请的通知');
};

处理连麦邀请

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

发起邀请

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

方法

Dart
RCRTCEngine.requestJoinSubRoom();

参数说明

参数	类型	必填	说明
roomId	String	是	对方的房间 ID
userId	String	是	对方用户 ID
autoLayout	bool	否	是否采用悬浮布局，默认 true
extra	String	否	附加信息

示例代码

Dart
// 邀请其他用户跨房间连麦的回调
engine.onJoinSubRoomRequested = (roomId, userId, code, message) {
  if (code == 0) {
    // 邀请其他用户跨房间连麦成功, 等待对方处理
  } else {
    // 邀请其他用户跨房间连麦失败
  }
};
// 邀请其他用户跨房间连麦
engine.requestJoinSubRoom(roomId, userId);

应答邀请

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

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

方法

Dart
RCRTCEngine.responseJoinSubRoomRequest();

参数说明

参数	类型	必填	说明
roomId	String	是	对方的房间 ID
userId	String	是	对方用户 ID
agree	bool	是	是否同意连麦
autoLayout	bool	否	是否采用悬浮布局，默认 true
extra	String	否	附加信息

示例代码

Dart
// 收到其他用户发起的跨房间连麦邀请
engine.onJoinSubRoomRequestReceived = (String roomId, String userId, String? extra) {
  // 同意其他用户的跨房间连麦邀请后触发的回调
  engine.onJoinSubRoomRequestResponded = (String roomId, String userId, bool agree, int code, String? errMsg) {
    if (code == 0) {
      // 同意响应成功
    } else {
      // 同意响应失败
    }
  };

  // 同意其他用户的跨房间连麦邀请
  engine.responseJoinSubRoomRequest(roomId, userId, true);
};

提示

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

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

取消邀请

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

方法

Dart
RCRTCEngine.cancelJoinSubRoomRequest();

参数说明

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

示例代码

Dart
// 取消之间发起的跨房间连麦邀请的回调
engine.onJoinSubRoomRequestCanceled = (String roomId, String userId, int code, String? errMsg) {
  if (code == 0) {
    // 取消成功
  } else {
    // 取消失败
  }
};

// 取消之间发起的跨房间连麦邀请
engine.cancelJoinSubRoomRequest(roomId, userId);

加入副房间流程

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

设置副房间事件回调监听

设置加入副房间事件回调

方法

Dart
RCRTCEngine.onSubRoomJoined

返回值

参数	描述
roomId	副房间 ID
code	接口结果码
errMsg	失败原因

示例代码

Dart
engine.onSubRoomJoined = (String roomId, int code, String? errMsg) {
  if (code == 0) {
    // 加入副房间成功
    print('加入副房间 $roomId 成功');
  } else {
    // 加入副房间失败
    print('加入副房间 $roomId 失败: $errMsg');
  }
};

设置离开副房间事件回调

方法

Dart
RCRTCEngine.onSubRoomLeft

返回值

参数	描述
roomId	副房间 ID
code	接口结果码
errMsg	失败原因

示例代码

Dart
engine.onSubRoomLeft = (String roomId, int code, String? errMsg) {
  if (code == 0) {
    // 离开副房间成功
    print('离开副房间 $roomId 成功');
  } else {
    // 离开副房间失败
    print('离开副房间 $roomId 失败: $errMsg');
  }
};

设置副房间解散事件回调

方法

Dart
RCRTCEngine.onSubRoomDisband

返回值

参数	描述
roomId	副房间 ID
userId	解散连麦的用户 ID

示例代码

Dart
engine.onSubRoomDisband = (String roomId, String userId) {
  // roomId 副房间 ID
  // userId 解散连麦的用户 ID
  print('用户 $userId 解散了副房间 $roomId 的连麦');
};

设置副房间绑定事件回调

方法

Dart
RCRTCEngine.onSubRoomBanded

返回值

参数	描述
roomId	副房间 ID

示例代码

Dart
engine.onSubRoomBanded = (String roomId) {
  // roomId 副房间 ID
  print('副房间 $roomId 已绑定');
};

加入副房间

方法

Dart
RCRTCEngine.joinSubRoom();

参数说明

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

示例代码

Dart
// 加入副房间结果的回调
engine.onSubRoomJoined = (String roomId, int code, String? errMsg) {
  if (code == 0) {
    // 加入副房间成功
  } else {
    // 加入副房间失败
  }
}

// 加入副房间
engine.joinSubRoom(roomId);

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

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

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

场景 A：在当前用户加入主房间前，该主房间已有主播用户与其他房间另一用户成功建立跨房间连麦。当前用户可在加入主房间时收到 onSubRoomBanded 回调，用户可在此回调中选择是否加入其他副房间。详细流程如下：
1. 调用 RCRTCEngine 中 joinRoom 方法加入主房间。
2. onSubRoomBanded 事件回调方法被触发。
3. 调用 RCRTCEngine 对象的 joinSubRoom 方法加入副房间。
场景 B：在当前用户加入主房间后，主房间内的另一主播用户发起了跨房间连麦并加入了其他房间，此时当前用户会收到 onSubRoomBanded 回调，用户可在此回调中选择是否加入其他副房间。

订阅资源

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

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

Dart
engine.onSubscribed = (String id, RCRTCMediaType type, int code, String? message) {
  // 订阅远端用户的资源的回调
  if (code == 0) {
    // 订阅成功
  } else {
    // 订阅失败
  }
};

// 订阅远端用户的资源
engine.subscribe(userId, RCRTCMediaType.video);

副房间主播发布资源时，onRemotePublished 方法会被触发，可通过 roomId 判断是否为副房间。在该回调中调用 subscribe 方法订阅副房间中远端用户刚发布的音视频资源。
Dart
```
// 远端用户发布资源的回调
engine.onRemotePublished = (String roomId, String userId, RCRTCMediaType type) {
  // 订阅远端用户发布的资源
  engine.subscribe(userId, type);
}
```

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

暂时中止连麦

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

方法

Dart
RCRTCEngine.leaveSubRoom();

参数说明

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

示例代码

Dart
// 离开副房间的回调
engine.onSubRoomLeft = (roomId, code, message) {
  if (code == 0) {
    // 离开成功
  } else {
    // 离开失败
  }
}

// 调用离开副房间
// disband 离开副房间时是否结束连麦。
engine.leaveSubRoom(roomId, false);

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

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

结束连麦

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

方法

Dart
RCRTCEngine.leaveSubRoom();

参数说明

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

示例代码

Dart
// 调用离开副房间
engine.leaveSubRoom(roomId, true);

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

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

被服务端踢出房间流程

提示

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

设置被踢出房间事件回调

方法

Dart
RCRTCEngine.onKicked

返回值

参数	描述
roomId	房间 ID，null 表示主房间
errMsg	踢出原因

示例代码

Dart
engine.onKicked = (String? roomId, String? errMsg) {
  // roomId 房间 ID，null 表示主房间
  // errMsg 踢出原因
  if (roomId == null) {
    print('被踢出主房间: $errMsg');
  } else {
    print('被踢出副房间 $roomId: $errMsg');
  }
};

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

IMLib

IMKit

Global IM UIKit

推送服务

IMLib

IMKit

CallLib

CallKit

CallPlus

RTCLib

CallLib

CallPlus

RTCLib

IM 服务端

IM Server SDK

RTC 服务端

北极星数据查询

跨房间连麦

设置连麦事件回调监听​

设置邀请连麦事件回调​

方法​

返回值​

示例代码​

设置收到连麦邀请事件回调​

方法​

返回值​

示例代码​

设置连麦邀请应答事件回调​

方法​

返回值​

示例代码​

设置收到连麦邀请应答事件回调​

方法​

返回值​

示例代码​

设置取消连麦邀请事件回调​

方法​

返回值​

示例代码​

设置收到取消连麦邀请事件回调​

方法​

返回值​

示例代码​

处理连麦邀请​

发起邀请​

方法​

参数说明​

示例代码​

应答邀请​

方法​

参数说明​

示例代码​

取消邀请​

方法​

参数说明​

示例代码​

加入副房间流程​

设置副房间事件回调监听​

设置加入副房间事件回调​

方法​

返回值​

示例代码​

设置离开副房间事件回调​

方法​

返回值​

示例代码​

设置副房间解散事件回调​

方法​

返回值​

示例代码​

设置副房间绑定事件回调​

方法​

返回值​

示例代码​

加入副房间​

方法​

参数说明​

示例代码​

订阅资源​

暂时中止连麦​

设置连麦事件回调监听

设置邀请连麦事件回调

方法

返回值

示例代码

设置收到连麦邀请事件回调

方法

返回值

示例代码

设置连麦邀请应答事件回调

方法

返回值

示例代码

设置收到连麦邀请应答事件回调

方法

返回值

示例代码

设置取消连麦邀请事件回调

方法

返回值

示例代码

设置收到取消连麦邀请事件回调

方法

返回值

示例代码

处理连麦邀请

发起邀请

方法

参数说明

示例代码

应答邀请

方法

参数说明

示例代码

取消邀请

方法

参数说明

示例代码

加入副房间流程

设置副房间事件回调监听

设置加入副房间事件回调

方法

返回值

示例代码

设置离开副房间事件回调

方法

返回值

示例代码

设置副房间解散事件回调

方法

返回值

示例代码

设置副房间绑定事件回调

方法

返回值

示例代码

加入副房间

方法

参数说明

示例代码

订阅资源

暂时中止连麦

方法

参数说明

示例代码

结束连麦

方法

参数说明

示例代码

被服务端踢出房间流程

设置被踢出房间事件回调

方法

返回值

示例代码