Break-Out Room: Web SDK – Video API

Break-Out Rooms allow users to participate in a discussion outside of the main Video Room i.e. the Parent Room.

Table of Contents

• Create Break-Out Room
• Invite Users to join a Break-Out Room
• Create Break-Out Room & Auto-Invite Users to join
• Join Break-Out Room
• Reject Break-Out Room Invitation
• Pause/Resume Parent Room
• Mute/Unmute Parent Room
• Disconnect from Break-Out Room
• Clear All Break-Out Rooms
• Handle All Destroyed Break-Out Rooms

The process of breaking-out takes place in the following manner:

• A creator or owner of the Break-Out Room invites one or more users from the Parent Room to the Break-Out Room.
• The invited users get notified about the request and need to accept the request to join the Break-Out room.
• Users moving out of the Parent Room are treated as “paused” users in the Parent Room until they return.

The implementation of Break-Out Room must be carried out with the following considerations:

• Break-Out Room is available in Group Mode room only, not in Lecture Mode.
• Break-Out room can be created by a user from the Parent Room only. A user cannot create another Break-Out Room while being within a Break-Out Room.
• A Break-Out Room can be created with a limit to the maximum allowed participants in it. In any case, the maximum allowed participants in the Break-Out Room must be less than the maximum Active Talkers in the Parent Room.
• Break-Out room currently supports only Audio Call with Screen Share and Canvas Streaming support.
• Maximum 10 Break-Out Rooms are allowed for a Parent Room.

Create Break-Out Room

The EnxRoom.createBreakOutRoom() method is used to create a Break-Out Room.

Method: EnxRoom.createBreakoutRoom(RoomDefinition, Callback);

Parameters:

• RoomDefinition – Required. JSON Object with Room definition parameters defined as following keys:
  • participants – Numeric. Required. Total number of Participants in the Break-Out Room. Range: Min: 2. Max: max_active_talkers of Parent Room – 1
  • audio – Boolean. Required. Set to true to enable Audio Communication in Break-Out Room.
  • video – Boolean. Required. Set to true to enable Video Communication in Break-Out Room. (This is currently not supported).
  • canvas – Boolean. Required. Set to true to enable Canvas Streaming in Break-Out Room.
  • share – Boolean. Required. Set to true to enable Screen Share in Break-Out Room.
  • max_rooms – Numeric. Required. The total number of Break-Out rooms to be created.
• Callback – To get result of Create Break-Out Room as JSON Array

RoomDefinition = {
	"participants": 2, 
	"audio": true,
	"video": false, 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

room.createBreakoutRoom(RoomDefinition, function(data) {
	// data is JSON with created Break-Out Room Information, e.g.
	/*		
	{	msg: {​​
			rooms: [ 
				xxx, xxx
			]
		},
		result: 0
	}
	*/
});

Error Codes / Exception

Code	Description
1724	Participant Count not found.
1725	Participant Count is more than Parent Room Size.
1726	Permissible limit to create Break-Out Room has exceeded
1729	Failed to generate Token.
1731	Failed to create Break-Out Room.
1734	Required parameter missing. Participant count is mandatory

Invite Users to join a Break-Out Room

The EnxRoom.inviteToBreakOutRoom() method allows the Creator/Owner of a Break-Out Room to invite one or more users from the Parent Room to join the Break-Out Room.

This method must be invoked from the Parent Room and NOT from the Break-Out Room.

Class: EnxRoom

Method: EnxRoom.inviteToBreakoutRoom(invitee, Callback)

Parameters:

• invitee – JSON Object with invitation details.
  • clients – Array of Client IDs of users to be invited.
  • room_id – String. Room ID of the Break-Out Room to which the users are being invited.
  • force_join – Boolean. If set to true, the invited participant will be forced to join the Break-Out Room. Availability: Web SDK 2.0.1+.
• Callback – To get result of invitation process.

Event Listeners

• join-breakout-room – Notification sent to the invited users when they are invited to join a Break-Out Room.
• breakout-room-joining – Notification sent to the invited Participant that he has to join the breakout room.
• breakout-room-connected – Notification sent to the invited Participant when he gets connected to the Break-Out Room.

invitee = {
	"clients" : "[clientId1, clientId2]", 
	"room_id" : "RoomID",
        "force_join" : true
};

room.inviteToBreakoutRoom(invitee, function(resp) {
	// resp is the result of invitation process, e.g.
	/*		
	{	"msg": "Success",
		"result": 0,
	}
	*/
});
 
// Users get invite to join Break-Out Room. When "force_join: false" is used or omitted
room.addEventListener("join-breakout-room", function (event) {
	// event carries the invitation details, e.g.
	/*		
	{	type: 'join-breakout-room', 
		message: {
			room_id: "String",
			requestor: "String"
		}
	}
	*/

	// User may join room now. This is optional.  
	// User may be presented with UI to either Join or Reject
	// In case, he needs to join, Read JoinBreakOutRoom() later in the document
	Joinee = {
		"role" : "participant", 
		"room_id" : "RoomID"
	};

	StreamInfo = {
		"audio": true, 
		"video" : false,
		"canvas" : false,
		"screen" : false
	};
	
	room.joinBreakOutRoom(Joinee, StreamInfo, function(resp) {
		// Status 
	});
});

// Users get notification to join directly when invited with  "force_join: true".
room.addEventListener("breakout-room-joining", function (event) {
	// event carries the invitation details, e.g.
	/*		
	{	type: 'breakout-room-joining', 
		message: {
			room_id: "String",
			requestor: "String"
		}
	}
	*/

}

// Users get notification when connected with Break-Out Room with invited with "force_join: true".
room.addEventListener("breakout-room-connected", function (event) {
	// event carries the room meta 
	// Ref: https://www.enablex.io/developer/video-api/client-api/appendix/#room-meta

}

Create Break-Out Room & Auto-Invite Users

The EnxRoom.createAndInviteBreakoutRoom() is used to support certain use-cases where auto-assignment of users into different Break-Out Rooms is required. This method creates a Break-Out Room with given specifications and invites users to join a Break-Out Room randomly depending on the Room’s capacity.

Class: EnxRoom

Method: EnxRoom.createAndInviteBreakoutRoom(RoomDefinition, Callback)

Parameters:

• RoomDefinition – JSON object with Room definition parameters as explained in Create Breakout Room.
• Callback – To get result of Create Break-Out Room as JSON Array

RoomDefinition = {
	"participants": 2, 
	"audio": true,
	"video": false, 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};

room.createAndInviteBreakoutRoom(RoomDefinition, function(data) {
	// data is JSON with created Break-Out Room Information, e.g.
	/*		
	{	msg: {​​
			rooms: [ 
				xxx, xxx
			]
		},
		result: 0
	}
	*/
});

Join a Break-Out Room

The EnxRoom.joinBreakOutRoom() method allows users to join a Break-Out room on being invited by the creator. A user can join a Break-Out Room from the Parent Room only and can join only one Break-Out Room at a time, thus allowing the user to join another Break-Out Room only after rejoining the Parent Room first.

Method: EnxRoom.joinBreakOutRoom(Joinee, streamInfo, Callback);

Parameters:

• Joinee – JSON Object with details required to join the Break-Out Room.
  • role – String. Required. Enumerated Values: participant, moderator.
  • room_id – String. Required. Room-ID of the Break-Out Room being joined.
• streamInfo – JSON Object with Stream information while joining the Break-Out Room.
  • audio – Boolean. Set to true to join with Audio.
  • video – Boolean. Set to true to join with Video. This is currently not supported.
  • screen – Boolean. Set to true for screen sharing capability.
  • canvas – Boolen. Set to true for canvas streaming capability.
• Callback – To know result of the join Room call.

Event Listeners

• breakout-room-error – Notification to the Joiner on failure to join the Break-Out Room.
• breakout-room-connected – Acknowledgment to the Joiner when Break-Out Room joined successfully.
• user-joined-breakout-room – Notification to everyone in the Break-Out Room when a new user joins the Room.

Joinee = {
	"role" : "participant", 
	"room_id" : "RoomID"
};

StreamInfo = {
	"audio": true, 
	"video" : false,
	"canvas" : false,
	"screen" : false
};

room.joinBreakOutRoom(Joinee, StreamInfo, function(resp) {
	// Status 
});

// User gets connected to Break-Out Room 
room.addEventListener("breakout-room-connected", function (roomMeta) {
	// roomMetadata contains meta information of the Room 
});

// User fails to connect  to Break-Out Room 
room.addEventListener("breakout-room-error", function (result) {
	// result contains reasons of failed connection, e.g.
	/*
	{	"result": 1729,
		"msg": "Failed to generate Token"
	}
	*/
});

// Others are notified about the new joinee in Break-Out Room 
room.addEventListener("user-joined-breakout-room", function (result) {
	// result contains new joinee user's information 
	/*
	{	"clientId": "String",
		"room": "String";
	}
	*/
});

Reject Break-Out Room Invitation

The EnxRoom.rejectBreakOutRoomInvite() allows the invited user to reject the invitation to join a Break-Out Room.

Class: EnxRoom

Method: EnxRoom.rejectBreakOutRoomInvite(roomId, callback); 

Parameter:

• roomId – The Break-Out Room identifier to which the user is invited.
• callback – To know the result of the reject Break-out Room invite.

Event Listeners:

• breakout-invite-rejected – Notification to the moderator when a user rejects an invitation to a Break-Out Room.

// User rejects break-out room invitation.
EnxRoom.rejectBreakOutRoomInvitation(roomId, function(resp) {
	// Status 
}); 

// The moderator is notified when a user rejects an invitation to a Break-Out Room
room.addEventListener("breakout-invite-rejected", function (result) {
	
});

Pause/Resume Parent Room

The EnxRoom.pause() method allows the user to pause the Parent Room after joining the Break-Out Room.

The EnxRoom.resume() method is used to resume the Parent Room if it was paused while joining the Break-Out Room.

Method: 

• EnxRom.pauseRoom(Callback)
• EnxRom.resumeRoom(Callback)

Parameters:

• Callback – To know status of the pause/resume API call.

room.pauseRoom(function(resp) {
	// resp carries status
	/*
	{	"msg": "Room paused",
		"result": 0
	}
	*/
}

room.resumeRoom(function(resp) {
	// resp carries status
	/*
	{	"msg": "Room resumed",
		"result": 0
	}
	*/
}

Error Codes / Exceptions

Code	Description
1138	Internal Server Error.

Mute/Unmute Parent Room

The EnxRoom.muteRoom() method allows the user to mute Audio and/or Video of the Parent Room after joining the Break-Out Room.

The EnxRoom.unmuteRoom() is used to unmute Audio and/or Video of the Parent Room after disconnecting from Break-Out Room and resuming the Parent Room.

Class: EnxRoom

Methods: 

• EnxRoom.muteRoom(muteInfo, Callback)
• EnxRoom.unMuteRoom(unmuteInfo, Callback)

Parameters:

• mutetInfo – JSON object with options to mute Audio and Video separately.
  • audio – Boolean. Set true mute Audio.
  • video – Boolean. Set true to mute Video.
• unmuteInfo – JSON Object with options to unmute Audio and Video separately.
  • audio – Boolean. Set true unmute Audio.
  • video – Boolean. Set true to unmute Video.
• Callback – To know status of the API call.

MuteInfo = {
	"audio" : true, 
	"video" : true
};

UnmuteInfo = {
	"audio" : true, 
	"video" : true
};

room.muteRoom(MuteInfo, function(resp) {
	// resp carries status
	/*
	{	"msg": "Room muted",
		"result": 0
	}
	*/
}

room.unMuteRoom(function(resp) {
	// resp carries status
	/*
	{	"msg": "Room unmuted",
		"result": 0
	}
	*/
}

Disconnect from Break-Out Room

The EnxRoom.disconnect() method allows the user to disconnect from the Break-Out Room.

Class: EnxRoom

Method: EnxRoom.disconnect() – No Parameter required.

Event Listeners:

• breakout-room-disconnected – Acknowledgment to the user when successfully disconnected from the Break-Out Room.
• user-disconnected-breakout-room – Notification to everyone in the Break-Out Room when a user gets disconnected from the Room.

breakout_room.disconnect();

// User is notified that he is disconnected from Break-Out Room
room.addEventListener("breakout-room-disconnected", function (event) {
	 
});

// Others are notified about the user disconnected from Break-Out Room
room.addEventListener("user-disconnected-breakout-room", function (event) {
	 
});

Clear All Break-Out Rooms

Availability: Web SDK 2.0.1+

The EnxRoom.clearAllBreakOutSession() method allows the participant to clear all Break-Out Rooms. The Participant gets disconnected from all breakout instances and resumes with the Parent Room.

Class: EnxRoom

Method: EnxRoom.clearAllBreakOutSession() – No Parameter required.

Event Listeners:

• breakout-user-disconnected – Notification to the Moderator/Owner of the Break-Out Room with information of the disconnected participant.

room.addEventListener("breakout-user-disconnected", function (event) {
	/* event is JSON with information of disconnected participant		
	{	type: 'breakout-user-disconnected', 
		message: {
			room_id: "String",
			client_id: "String"
		}
	}
	*/
});

Handle All Destroyed Break-Out Rooms

Availability: Web SDK 2.0.1+

The EnxRoom.destroyAllBreakOutSession() method allows the moderator to destroy all the Breakout Room sessions. When all the Breakout Room sessions get destroyed, the Parent Room is automatically resumed and unmuted.

Class: EnxRoom

Method: EnxRoom.destroyAllBreakOutSession() – No Parameter required

Event Listeners:

• breakout-room-destroyed – Notification to the owner when the Breakout Room gets destroyed.

room.destroyAllBreakOutSession(); 

room.addEventListener("breakout-room-destroyed", function (event) {
	 
});

---