A user connected with EnableX session with “Moderator” role has additional privileges over that of a “Participant” for the session. The Moderator exercises his privileges by executing exclusive methods designed to work from his End Point only, are known as Moderator Controls.

Table of Contents

Record a Session

Using EnableX you may get a RTC session recorded as individual streams and later be transcoded through a post-session service to create a single video file which can be retrieved and re-played using any Video Player. Recording can be started in 2 ways, viz.

Auto-Recording

You may define a room to start recording automatically as and when a session starts in the room. You may pass { settings: { auto_recording: true }} in the JSON Payload while creating a room to ensure a session is recorded automatically.

On-Demand Recording

Client API call helps you start and stop recording as and when needed. The available methods are accessible to Moderator only. Therefore, on the Moderator End-Point, you may require to create UI to use the methods to start or stop recording a session.

To start session recording on demand you may use EnxRoom.startRecord() method, and to stop may use EnxRoom.stopRecord() method. On successful initiation of recording and stopping of recording all client end point will be notified using room-record-on and room-record-off respectively. You need to listen to these events to do UI updates.

Methods:

  • EnxRoom.startRecord(Callback) to start recording
  • EnxRoom.stopRecord(Callback) to stop recording

Event Notifications:

  • room-record-on to all; with Moderator ID who started recording
  • room-record-off to all; with Moderator ID who stopped recording
// To start recording
room.startRecord( function( result, error ) {
     if (result == 0) {
         // Recording started
     } 
});
 
// To stop recording
room.stopRecord( function( result, error ) {
     if (result == 0){
         // Recording stopped
     }  
});

// Notification recording started to all
room.addEventListener( "room-record-on", function(event) {
     // Recording started, Update UI
     // event.message.moderatorId = Moderator who stated recording.
}); 
    
// Notification recording stopped to all
room.addEventListener( "room-record-off", function(event) {
     // Recording stopped, Update UI
     // event.message.moderatorId = Moderator who stopped recording. 
});

Note:

  • Moderator can start/stop recording any number of time during a session as he wishes.
  • Moderator can stop recording in a room defined with auto-recording feature.

Refer: How to fetch Recordings?

Hard Mute / Unmute Room

Moderator may put the room in a hard-mute state when he wishes no-one else to be audible in the Room. Any new user who joins the room when the room is in hard-mute state will also be inaudible

To put room into hard mute state, you may use EnxRoom.hardMute() method; and to disable you may use EnxRoom.hardUnmute() method. All users connected to the room are notified with events hard-mute-room when enforcing hard mute. Users are notified with event hard-unmute-room on lifting the imposed restriction.

Methods:

  • EnxRoom.hardMute(Callback) to hard mute room
  • EnxRoom.hardUnmute(Callback) to hard unmute room

Event Notifications:

  • hard-mute-room to all; with Moderator ID who hard-muted Room
  • hard-unmute-room to all; with Moderator ID who hard-unmuted Room
// Moderator hard-mutes room
room.hardMute(function (result, error) {
 /* result JSON
 { "result": 0,
 "msg": "Room is muted"
 }
 */
});

// Moderator hard-unmutes room
room.hardUnmute(function (result, error) {
 /*Result JSON
 { "result": 0,
 "msg": "Room is un-muted"
 }
 */
});

// Partipants are notifed on room being hard-muted
room.addEventListener("hard-mute-room", function (res) {
   // res.moderator = Moderator who hard-muted Room. 
});

// Partipants are notifed on room being hard-unmuted
room.addEventListener("hard-unmute-room", function (res) {
 // res.moderator = Moderator who hard-unmuted Room.  
});

Hard Mute / Unmute Participant

Moderator may enforce hard-mute audio/video on any specific participant in the room. The affected participant will not be able to talk or may not be able to publish his video until the imposed state is lifted.

Web SDK offers hard muting audio and force dropping the video of a participant using EnxRoom.hardMuteUserAudio() and EnxRoom.hardMuteUserVideo() methods respectively. You may lift the enforced muting state of Audio or Video using EnxRoom.hardUnmuteUserAudio() and EnxRoom.hardUnmuteUserVideo() methods respectively. The affected participant is notified using related events, viz. hardmute-user-audio, hardunmute-user-audio, hardmute-user-video, hardunmute-user-video. All participants are notified about the mute status of the affected participant using related events, viz. user-audio-muted, user-audio-unmuted, user-video-muted and user-video-unmuted.

Methods:

  • EnxRoom.hardMuteUserAudio(clientId, Callback) to hard mute audio
  • EnxRoom.hardMuteUserVideo(clientId, Callback) to hard mute video
  • EnxRoom.hardUnmuteUserAudio(clientId, Callback) to hard unmute audio
  • EnxRoom.hardUnmuteUserVideo(clientId, Callback) to hard unmute video

Parameters: clientId – The target user who will be hard muted/unmuted for audio/video

Event Notifications:

  • hardmute-user-audio to the participant whose audio is hard muted
  • hardunmute-user-audio to the participant whose audio is hard unmuted
  • hardmute-user-video to the participant whose video is hard muted
  • hardunmute-user-video to the participant whose video is hard unmuted
  • user-audio-muted to all users about the participant’s audio-mute status
  • user-audio-unmuted to all users about the participant’s audio-unmute status
  • user-video-muted to all users about the participant’s video-mute status
  • user-video-unmuted to all users about the participant’s video-unmute status

All the above events message will have Moderator ID who hard-muted or hard-unmuted Audio/Video of a Participant.

// Hard mute User's audio     
room.hardMuteUserAudio(clientId, function(response) {
     if (response.result === 0) {
         // Success
     }
     else {      
         // Failed
     }
});

// Hard mute User's video*/    
room.hardMuteUserVideo (clientId, function(response) {
     if (response.result === 0) {
         // Success
     }
     else {      
         // Failed
     }
});

room.addEventListener('hardmute-user-audio', function(event) { 
     // Your audio is hard muted
     // event.moderator = Moderator who hard-muted user's Audio.
});

room.addEventListener('hardmute-user-video', function(event) {
      // Your video is hard muted 
});

room.addEventListener('user-audio-muted', function(event) {      
      // User's audio muted     
      // Info about user event.stream.attributes
}); 

room.addEventListener('user-video-muted', function(event) {      
      // User's video muted     
      // Info about user event.stream.attributes
});

// Similarly you may code for hard unmute User's audio/video  
// using related methods and event notifications

Lock / Unlock Room

Moderator may lock the Room forbidding any new person from joining the Session. To allow subsequent users to join session, Moderator need to unlock the Room.

To put room into Lock State, you use EnxRoom.lock() method; and to unlock the Room you use EnxRoom.unlock() method.

Methods:

  • EnxRoom.lock() – To lock Room
  • EnxRoom.unlock()  – To unlock Room

Event Notifications:

  • room-locked: To notify all participants that the room has been locked. Event will has JSON with Moderator-ID who locked the Room.
  • room-unlocked: To notify all participants that the room has been unlocked. Event will has JSON with Moderator-ID who unlocked the Room.
room.lock();

// Participants are notified that room has been locked
room.addEventListener('room-locked', function(event) {             	 
});  

room.unlock();

// Participants are notified that room has been unlocked
room.addEventListener('room-locked', function(event) {              
});

Disconnect User

Moderation may wish to disconnect or force-drop a participant from the Session by using EnxRoom.dropUser() method. The same method may be used to disconnect all participants from the Session.

Method: EnxRoom.dropUser(ClientIds, Callback)

Parameters:

  • ClientId: Required. Array of CientId to be disconnected. You may pass empty array “[]” to disconnect all users.
  • Callback: A JSON received with status of Action.

Event Notification: room-disconnected to all users with JSON stating reason for disconnection.

// To disconnect specified user
room.dropUser([ClientId], function(res) {
    if (res.result == 0) {
        // Request processed 
    }
});

// To disconnect all usuers. pass empty Array
room.dropUser([], function(res) {
    if (res.result == 0) {
        // Request processed 
    }
});

// All users are notified disconnection with reason
room.addEventListener("room-disconnected", function(event) {
	// Event may be processed to know reason
	if (event.message.cause.msg === 'disconnected-by-moderator')	{
		// Show message to user
	}
});

Destroy Session

Moderation may wish to conclude an ongoing session by using using EnxRoom.destroy() method.

Method: EnxRoom.destroy()

Event Notification: room-disconnected:  To notify all users that Session is closed.

room.destroy();
 
// All users are notified disconnection with reason
room.addEventListener("room-disconnected", function(event) {
 // Event may be processed to know reason
 if (event.message.cause.msg === 'disconnected-by-moderator') {
 // Show message to user
 }
}); 
 

Allow / Deny awaited User to get into Room

In a knock-enabled Room, when a participant is connected to a room, he needs to wait until the Moderator grants him access to join the Room. The Moderator may grant or deny the partipant’s entry.

Methods:

  • EnxRoom.approveAwaitedUser(ClientID, Callback) to approve user’s entry to room
  • EnxRoom.denyAwaitedUser(ClientID, Callback) to deny user’s entry to room

Event Notifications:

  • user-awaited – moderator is notified about a user is awaited to join room
// Moderator is notified about awaited user
room.addEventListener("user-awaited", function(event, user) {
      // Client Info: user.clientId
      // Create UI for Moderator Interaction to allow or deny 

	// To allow
	room.approveAwaitedUser(clientId, function(success, error) {
	     // Check Success / Error result
	});

	// To deny
	/*
	room.approveAwaitedUser(clientId", function(success, error) {
	     // Check Success / Error result
	});
	*/
});

To manage awaited users when moderator joins late

If moderator joins later than all the participants in a Knock-enabled Room, then his end-point needs to handle all the waiting participants to allow or deny entry to  the room individually or collectively. To do this, you need to get a list of participants who are waiting for access to the Room using  room.awaitedParticipants. You may need to build UI to allow or deny participant to join Room.

Floor Access Control in Lecture Mode

In Lecture Mode, only the Moderator publishes a stream to the room whereas all other participants subscribe to see and listen to the Moderator. If participants have questions to ask during the session, the Moderator can grant the floor to the participant to publish his stream.

The following steps to deploy Control Floor Access by moderator:

Request Floor Access

A participant requests for Floor access is forwarded to the Moderator using a notification event.

Method: EnxRoom.requestFloor(Callback) – participant requests floor access

Notification Event: floor-requested – moderator receives floor request

room.requestFloor(function (arg) {
        if(arg.result == 1701) { /* Success */  }
        else { /* Error - Print arg.msg */ }
});

// Moderator receives Floor Access Request
room.addEventListener("floor-requested", function (evt) {             
        /*  evt.users.clientId, evt.users.name */
}); 

Cancel Requested Floor Access

A participant may cancel his request for Floor access which is pending at Moderator Side.

Method: EnxRoom.cancelFloor(Callback) - Participant cancels request for floor access

Callbacks: To know status of Cancellation process.

Event Notifications:

  • floor-cancelled: Moderator receives cancellation notification for already posted Floor Access Request from Participant
room.cancelFloor(function (arg) {
        if(arg.result == 0) {
		// Floor Reqeust is cancelled
	}
});

// Moderator receives Floor Cancellattion Notification
room.addEventListener("floor-cancelled", function (evt) {             
        // evt.msg.clientId = The participant who cancelled
}); 

Deny Floor Access

The Moderator may also deny a request for floor access to a participant.

Method: EnxRoom.denyFloor(ClientID, Callback) – moderator denies floor access

Notification Event: floor-denied – Affected Participant and Moderator(s) are notified that floor access request has been denied. The Event Message carries the Moderator Id who denied request

room.denyFloor(clientId, function (arg) {
    if (arg) { /* Success */  }
    else { /* Error - Print arg.msg */ }
});

// Affected Participant and Moderator(s) are notified about denied request
room.addEventListener("floor-denied", function (evt) {
   // evt.msg.moderatorId = The modeator who denied
   // evt.msg.clientId = The Participan who is denied 
}); 

Grant Floor Access

Moderator might grant floor access to one or many users one by one. Note that at any given point of time, only one person may be granted floor access. To grant access to others, moderator must release floor access from the participant who is currently granted floor access. Once granted floor access, the designated participant will be notified using an event and he can publish his stream.

Method: EnxRoom.grantFloor(ClientID, Callback) – moderator grants floor access

Parameters:

  • ClientID: Client-ID of the Participant who is granted Floor Access.
  • Callback: To know that floor access has been granted.

Notification Event: floor-granted – Participant receives Floor ccess and all moderator(s) gets to know the Moderator ID who granted Floor Access to the Participant.

room.grantFloor(clientId, function (arg) {
    if (arg) { /* Success */  }
    else { /* Error - Print arg.msg */ }
});

// Moderators and the Participant is notified about granted Floor Access 
room.addEventListener("floor-granted", function (evt) {
     // room.publish(localStream); // Publish stream 
     // evt.msg.moderatorId = Moderator who granted Floor Access
}); 

Finish Granted Floor Access

The Participant can finish floor access granted to him by Moderator.

Method: EnxRoom.finishFloor(Callback) – Participant finishes his granted Floor Access

Callback: To know that Floor Access is finished.

Event Notification

  • floor-finished: All moderators will be notified that the Participant has finished his granted floor access.
room.finishFloor(function (arg) {
        if(arg.result == 0) {
		// Floor Access is finished
	}
});

// Moderators receive notification
room.addEventListener("floor-finished", function (evt) {             
        // evt.msg.clientId = The participant who finished floor access
}); 

Release Floor Access

Moderator may terminate floor access granted to some participant. Upon termination, the user’s stream(s) is unpublished. It is necessary to terminate floor access of a participant before giving out floor access to another participant.

Method: EnxRoom.releaseFloor(ClientID, Callback) – moderator asks to release floor

Parameters:

  • ClientID: Client ID of the Participant whose granted floor access has been released.
  • Callback: To know that floor has been released.

Notification Event:

  • release-floor – Affected Participant and Moderator(s) are notified that floor access has been released with thee Moderator ID who released it.
room.relaseFloor(clientId, function (arg) {
        if (arg) { /* Success */ }
        else { /* Error - Print arg.msg */ }
});

// Notificatation that floor access is released
room.addEventListener("release-floor", function (evt) {
	// evt.msg.moderatorId = The moderator who released floor access
	// evt.msg.clientId = The Participant whose floor access is released
}); 

Restore Moderator Session

In case the Moderator is disconnected during a session, the list of received floor requests and participant currently with floor access can be retrieved when connection is restored to the room in the Room-Meta viz.

Structured Data JSON

  • room.raisedHands– An Array of Client-IDs who requested floor-access
  • room.approvedHandsAn Array of Client-IDs who currently has floor access

Change Participant’s Role

A Moderator can designate a connected Participant to act as a Moderator during the session. Doing so, the promoted Participant would get access to all the rights of the Moderator, i.e. accesses all features listed under Moderator Controls; and the old Moderator who had promoted him becomes a Participant. Similarly, the new Moderator can further grant Moderator Role to other participant if needed.

Method: EnxRoom.switchUserRole(ParticipantId, Callback)

Parameters: ParticipantID – Client ID of the participant who is being designated as Moderator

Notification Event:

  • user-role-changed – Notifying all connected participants and moderators with a message that a new user has been appointed as moderator. Also, the newly appointed moderator is notified with extra information. Refer in example given below:
room.switchUserRole (participantId, function(status) { 
     if ( status.result == 0) {
         // Succeeded
     }
     else {
         // Failed message: status.msg
     }
 });
 
 room.addEventListener('user-role-changed', function (evt) {
      // evt JSON Structure
      /*
      {		raisedHands: [], //Raised Hand Requests
		approvedHands: [],  // Who has floor control
		moderator: {
			new : new client_id, // New Moderartor
			old : old clientId   // Old Moderartor
		} 
	}
	*/
 }

Start / Stop Live Streaming

EnableX supports forwarding live Video Sessions over RTMP to any live streaming CDNs which support this protocol.

To start forwarding RTMP stream you use EnxRoom.startStreaming() method; and to stop you use EnxRoom.stopStreaming() method.

Methods:

  • EnxRoom.startStreaming(streamingConfig, callback) – To start forwarding RTMP Stream
  • EnxRoom.stopForwarding(callback)  – To stop forwarding RTMP Stream

Parameters:

  • streamingConfig – Configuration, Options for forwarding streams
    • rtmpDetails.rtmpUrl – Use “RTM-URL/RTMP-KEY” from CDN Provider
    • rtmpDetails.urlDetails.url – Optional. Its RTMP Streaming View URL. If not given, a default Streaming View will be applied.

Event Notifications:

  • streaming-started: To notify all that a RTMP Streaming has started.
  • streaming-stopped: To notify all that the ongoing RTMP Streaming has stopped.
var streamingConfig = {	
	rtmpDetails: {
		rtmpUrl: "RTMP_URL/RTMP_KEY"
	},
	urlDetails: {
		url: "URL-TO-USE-AS-STREAMING-VIEW"
	}
};

// Start Streaming
room.startStreaming(streamingConfig, function(resp) {
	if (resp.status.resultCode === 0) {
		console.log('Streaming started. You are live.');
	}
	else {	// Streaming failed
		console.log(resp.status.error.errorDesc)
	}

});

// Stop Streaming
room.stopStreaming(function(resp) {
	console.log('Streaming Stopped.');
})

room.addEventListener('streaming-started', function(event) {
	// All are notified that streaming has started
	// event.message.startedBy : who started the streaming
});

room.addEventListener('streaming-stopped', function(event) {
	// All are notified that streaming has stopped
	// event.message.stoppedBy : who stopped the streaming
});

Explore Web SDK