Break-Out Room: Android SDK – Video API

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

Create Break-Out Room
Invite Users to join a Break-Out Room
Create Break-Out Room & Auto-Invite Users
Join Break-Out Room
Reject Break-Out Room Invitation
Pause / Resume Parent Room
Mute / Unmute Parent Room
Disconnect from Break-Out Room
Cancel 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 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.

Create Break-Out Room

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

Class: EnxRoom

Method: public void createBreakOutRoom(JSONObject RoomDefinition);

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-Sharing in Break-Out Room.
- max_rooms – Numeric. Required. The total number of Break-Out rooms to be created.

Callbacks:

onAckCreateBreakOutRoom – Acknowledgment to the creator with Break-Out Room returned as a JSON object when created.

Response Body:

{	msg: {
		rooms: [ 
			  xxx, xxx
		       ]
	     },
			result: 0
}

onBreakoutRoomCreated – Notification to all the Moderators in the Parent Room when a Break-Out Room is created.

Response Body:

{ 
    id = "breakout-room-created"; 
    msg =     { 
        clientId = "68d0388c-5630-4f16-883a-8bc2a138a905"; 
        roomId = 61249702a7282c251ec8d840;
    }; 
},

JSONObject  RoomDefinition = {
	"participants" :2, 
	"audio" : true,
	"video": false , 
	"canvas": false, 
	"share": false, 
	"max_rooms": 1
};
// Create Break-Out Room
enxRoom.createBreakOutRoom(RoomDefinition);

// Acknowledgment to the creator
public void onAckCreateBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is JSON with created Break-Out Room Information
	
}

// Notification to all the Moderators
public void onBreakoutRoomCreated(JSONObject jsonObject);

Error Codes / Exceptions

Code	Description
5067	Break-Out Room not supported in a Room in `lecture-`mode.

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. In case, if the force_join feature is enabled, the invitee automatically joins the Break-Out Room.

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

Class: EnxRoom

Method: public void inviteToBreakOutRoom(JSONObject invitee)

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: Android SDK 2.0.1+.

Callbacks:

onAckInviteBreakOutRoom – Acknowledgment to the Creator with JSON object returned as a response to the invitation process.

Response Body:

{	
      "msg": "Success",
      "result": 0,
}

onInvitationForBreakoutRoom – Notification to the invited users when they are invited to join a Break-Out Room.

Response Body:

{	
     "result": 0,
}

onBreakoutRoomInvited – Notification to all the Moderators in the Parent Room when a user is invited to a Break-Out Room.

Response Body:

{ 

    id = "breakout-room-invited"; 
    msg =     { 
                   clientId = "12f31157-e62a-43f6-8719-f98b3da40978"; 
                   roomId = 6124b82e98533871c791a788; 
              }; 
}

didBreakoutroomjoining – Notification sent to the invited Participant that he has to join the Break-Out Room.

onBreakoutroomjoining – Notification sent to the invited Participant when he gets connected to the Break-Out Room.

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

// Invite user to Break-Out Room.
enxRoom.inviteToBreakOutRoom(invitee);
 
// Acknowledgment to the Creator
public void onAckInviteBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is the result of invitation process, e.g.
} 

// Notification to the invited users
public void onInvitationForBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries the invitation details, e.g.
}

// Notification to the Moderator(s)
public void onBreakoutRoomInvited(JSONObject jsonObject); {
}

// Notification to the Participant(s) 
public void didBreakoutroomjoining(JSONObject jsonObject); {
}

// Notification to the Participant(s) 
public void onBreakoutroomjoining(JSONObject jsonObject); {
}

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: public void createAndInviteBreakoutRoom (JSONObject roomDefinition)

Parameters:

roomDefinition – JSON object with Room definition parameters as explained in Create Break-Out Room.

Callbacks:

onAckCreateAndInviteBreakOutRoom – Acknowledgment to the creator with the result of invitation in a JSON Array.

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

enxRoom.createAndInviteBreakoutRoom(RoomDefinition);

public void onAckCreateAndInviteBreakOutRoom(JSONObject jsonObject) {
	// jsonObject is JSON with created Break-Out Room Information, e.g.
	/*		
	
		{	msg: {
					rooms: [ 
						xxx, xxx
					]
			},
			result: 0
		|
	
	*/
}

Error Codes / Exceptions

Code	Description
5067	Break-Out Room not supported in a Room in `lecture` mode.

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.

Class: EnxRoom

Method: public void joinBreakOutRoom(JSONObject Joinee, JSONObject streamInfo)

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.

Callbacks:

onConnectedBreakoutRoom – Acknowledgment to the Joiner when Break-Out Room joined successfully.
onFailedJoinBreakOutRoom – Notification to the Joiner when fails to join the Break-Out Room.
onUserJoinedBreakoutRoom – Notification to everyone in the Break-Out Room when a new user joins the Room.

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

JSONObject StreamInfo = {
	"audio" : true, 
	"room_id" : false
};

enxRoom.joinBreakOutRoom(Joinee, StreamInfo);

public void onConnectedBreakoutRoom(JSONObject roomMetadata)  {
	// roomMetadata contains meta information of the Room 
} 

public void onFailedJoinBreakOutRoom(JSONObject jsonObject) {
	// data contains reasons for failed connection
}

public void onUserJoinedBreakoutRoom(EnxRoom room, JSONObject jsonObject) {
	// jsonObject contains new joiner's information 
	/*
	{	"clientId": "String",
		"room": "String";
	}
	*/
}

Reject Break-Out Room Invitation

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

Class: EnxRoom

Method: public void rejectBreakOutRoom(String roomId)

Parameter:

roomId – The Break-Out Room identifier to which the user is invited.

Callbacks:

onAckRejectBreakOutRoom – Acknowledgment to the user who rejected the invitation when the request to reject is successfully processed.

Response Body:

{ 
         “result” : 0/1,   // 0 for success and 1 for failure 
         “msg” : “success/failure” 
}

onBreakoutRoomInviteRejected – Notification to all the Moderators in the Parent Room when a user rejects an invitation to a Break-Out Room.

// User rejects break-out room invitation.
EnxRoom. rejectBreakOutRoom(" roomId”); 

// Acknowledgment to the user when invitation rejected.
public void onAckRejectBreakOutRoom(JSONObject jsonObject); 

// Notification to the Moderators in the Parent Room when invitation rejected.
public void onBreakoutRoomInviteRejected(JSONObject jsonObject);

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:

public void pause()
public void resume()

Callbacks:

onAckPause – Acknowledgment to the user when the Parent Room is paused.
onAckResume – Acknowledgment to the user when the Parent Room is resumed.

enxRoom.pause();	// Pause Parent Room
enxRoom.resume();	// Resume Parent Room

public void onAckPause(JSONObject jsonObject) {
	// jsonObject carries info related to pausing
	/*
	{	"msg": "Room muted",
		"result": 0
	}
	*/
};

public void onAckResume(JSONObject jsonObject) {
	// jsonObject carries info related to resume
	/*
	{	"msg": "Room unmuted",
		"result": 0
	}
	*/
};

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:

public void muteRoom(JSONObject muteInfo)
public void unmuteRoom(JSONObject unmuteInfo)

Parameters:

muteInfo – JSON object with options to mute Audio and Video separately.
- audio – Boolean. Set to true to mute Audio.
- video – Boolean. Set to true to mute Video.
unmuteInfo – JSON Object with options to unmute Audio and Video separately.
- audio – Boolean. Set to true unmute Audio.
- video – Boolean. Set to true to unmute Video.

Callbacks:

onAckMuteRoom – Acknowledgment to the user when the Parent Room is muted.
onAckUnmuteRoom – Acknowledgment to the user when the Parent Room is unmuted.

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

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

enxRoom muteRoom(MuteInfo);
enxRoom unmuteRoom(UnmuteInfo);

public void onAckMuteRoom(JSONObject jsonObject) {
	// jsonObject contains muting status
} 

public void onAckUnmuteRoom(JSONObject jsonObject) {
	// jsonObject contains unmuting status
}

Disconnect from Break-Out Room

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

Class: EnxRoom

Method: public void disconnect()

Callbacks:

onDisconnectedBreakoutRoom – Acknowledgment to the user when successfully disconnected from the Break-Out Room.
onUserDisconnectedFromBreakoutRoom – Notification to everyone in the Break-Out Room when a user gets disconnected from the Room.

enxRoom.disconnect(); 

public void onDisconnectedBreakoutRoom(JSONObject jsonObject) {
	// jsonObject carries info related to disconnection
	/*
	{	"moderatorId": "String",
		"msg": "Breakout Room disconnected",
		"result": 0
	}
	*/
};

public void onUserDisconnectedFromBreakoutRoom(EnxRoom room,JSONObject jsonObject) {
	// jsonObject carries info related to disconnected user
	/*
	{	"clientId": "String",
		"name": "String",
		"room": "breakout-Development"
	}
	*/
};

Clear All Break-Out Rooms

Availability: Android 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:

onDisconnectedBreakoutRoom – Notification to the Moderator/Owner of the Break-Out Room with information of the disconnected participant(s).

public void onDisconnectedBreakoutRoom(JSONObject jsonObject) {
	// JSON Object carries disconnected participants information 
	/* 
	{	"room_id": "String"
	}
	*/
}

Handle All Destroyed Break-Out Rooms

Availability: Android 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 Participants get disconnected and the Parent Room is automatically resumed and unmuted.

Class: EnxRoom

Method: EnxRoom.destroyAllBreakOutSession() – No Parameter required

Event Listeners:

onDisconnectedBreakoutRoom – Notification to the owner when the Breakout Room gets destroyed.

public void onDisconnectedBreakoutRoom(JSONObject jsonObject) {
	// JSON Object carries destroyed room information 
	/* 
	{	"room_id": "String"
	}
	*/
}

← Room Mode Switch

Index

Join Aside Room →

Table of Contents

Create Break-Out Room

Invite Users to join a Break-Out Room

Create Break-Out Room & Auto-Invite Users

Join a 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