Session Management

The Flutter SDK provides the following methods for managing video sessions:

• startRecord(): To start recording a session.
• stopRecord(): To stop recording a session.
• startLiveRecording(): To start live recording of a session.
• stopLiveRecording(): To stop live recording of a session.
• hardMute(): To hard-mute a room.
• hardUnMute(): To put the room off a hard-mute state.
• hardMuteAudio(): To hard-mute a participant's audio.
• hardMuteVideo(): To hard-mute a participant's video.
• hardUnMuteAudio(): To unmute a participant's audio.
• hardUnMuteVideo(): To unmute a participant's video.
• lockRoom(): To lock a room.
• unLockRoom(): To unlock a room.
• approveAwaitedUser(): To approve a user's entry.
• denyAwaitedUser(): To decline a user's entry.
• switchUserRole(): To promote a participant to act as a moderator in the ongoing session.
• pinUsers(): To pin a user to the Active Talker list.
• unpinUsers(): To unpin a user from the Active Talker list.
• addSpotlightUsers(): To spotlight a user.
• removeSpotlightUsers(): To remove the spotlight from users' streams.
• dropUser(): To disconnect/force-drop one or more participants from a session.
• switchRoomMode(): To switch the room mode.
• extendConferenceDuration(): To extend the duration of a session.
• destroy(): To conclude an ongoing session.

Record a Session

You can record an RTC session as individual streams and get it transcoded through a post-session service to create a single composite video file that can be retrieved and replayed using any video player. You can configure the room for auto-recording or invoke APIs to start recording when required. For details on fetching recorded sessions, refer to How to fetch Recordings?

Ways to Record a Session

A session can be recorded in the following ways:

Auto-Recording a Session

You can configure a Room with { settings: { auto_recording: true }} during Room Creation to automatically start recording the RTC session taking place in the room. The moderator of the room can stop the recording using the stopRecord() method.

On-Demand Recording

Client API call helps you start and stop recording. The available methods are accessible to users in the moderator role only. You can use this method to provide options on the UI for the moderator to access them.

The moderator can start recording anytime during a session. There is no limit to the number of times a moderator can start recording.

Start Recording a Session

The startRecord() method allows the moderator to start recording a session.

Class: EnxRtc

Method: static Future<void> startRecord()

Sample Code:

EnxRtc.startRecord(); // To start recording

EnxRtc.onRoomRecordingOn= (Map<dynamic, dynamic> map) {
	// To all participant to notify recording is on
	// map is {"msg":"Room Recording On","result":"0"}
};

EnxRtc.onStartRecordingEvent= (Map<dynamic, dynamic> map) {
	// To moderator to notify that recording has started
	// map is {"result":0","msg":"Success"}
};

Stop Recording a Session

The stopRecord() method allows the moderator to stop recording of a session. You can use this method to provide options on the UI for the moderator to access them.

The moderator can stop recording anytime during a session. There is no limit to the number of times a moderator can stop recording. The moderator can stop recording in a room defined with the auto-recording feature.

Class: EnxRtc

Method: static Future<void> stopRecord()

Sample Code:

EnxRtc.stopRecord(); // To stop recording

EnxRtc.onRoomRecordingOff= (Map<dynamic, dynamic> map) {
	// To all participant to notify recording is off
	// map is {"msg":"Room Recording Off","result":"0"}
};

EnxRtc.onStopRecordingEvent= (Map<dynamic, dynamic> map) {
	// To moderator to notify that recording has stopped
	// map is {"result":0","msg":"Success"}
};

EnxRtc. onRoomRecordingOff= (Map<dynamic, dynamic> map) {
  // To all participant to notify recording is 
   //where map is
  //{"msg":"Room Recording Off","result":"0"}

};

Get Recording Files

Type of Recording Files

1. Individual Participants' Stream Recordings: Each user's stream gets recorded individually and is made available for download. These files are in the .mkv format.
2. Transcoded Re-playable Session: It's a single composite video .mov file created from all the individual participant's streams in the proper playtime. If a moderator has recorded different segments of a video session, you get a file for each recorded segment. Transcoding is a subscription-based service with a predefined layout. The transcoded files are made available for download.

Note: Individual stream recordings are available for download minutes after the session ends. Transcoding files may be downloaded within 10-45 minutes post-session depending on the transcoding queue.

Use Server API to Get Files

Using Server API, you can fetch Archive Reports through an HTTP GET request to its archive route. You may use the following filters to get the right set of Archive Reports as designed:

• For a Period - For a given From and To date
• For a Room ID
• For a Room ID within a Period
• For a specific session - For a given Conference Number

After getting the Archive Report, you may need to do an HTTP GET to each URL given in the Report to download files individually. Please refer to the online documentation for a detailed explanation of API calls.

Get Files delivered

EnableX delivers your files to your location/server/storage using its Archive Delivery Service. You need to configure your Delivery Location using the Portal.

Portal Login > Video > Settings > Archive

Using this Tool, define your Delivery Server with Access Credentials. EnableX supports delivery to the following location:

• FTP / SFTP to your Server
• SCP to your Server
• Amazon S3
• Azure Blob Storage
• Google Drive

Once configured, EnableX transfers your files and keeps them organized in sub-folders in the folder you designated for delivery. File delivery is a batch process. You may face a significant delay in delivery. After a file is delivered to your location, EnableX notifies you through a Webhook Notification to help you automate workflow.

Get Webhook Notification When a Recording File is Available

EnableX may notify you as soon as any file is available for downloading or a file gets delivered to your location by HTTP POST to a designated Webhook URL. It would help if you had to set up the URL on your Project Server. To configure your Webhook URL, follow the path:

Portal Login > Video > Settings > Preferences > Webhook

Once configured, EnableX does HTTP POST with JSON Raw Body to the URL for you to process. Note that you need to do HTTP GET to each URL given in the JSON to download files individually.

Sample Code

// When a Recording files are ready 
{	
	"type": "recording",
	"trans_date": "Datetime",  /* In UTC */
	"app_id": "String",
	"room_id": "String",
	"conf_num": "String",
	"recording": [ 
		{ "url": "http://FQDN/path/file" }
	]
}

// When Transcoded Video files is ready
{	
	"type": "transcoded",
	"trans_date": "Datetime",  /* In UTC */
	"app_id": "String",
	"room_id": "String",
	"conf_num": "String",
	"transcoded": [ 
		{ "url": "http://FQDN/path/file" }
	]
}

// When Chat Scripts are ready 
{
	"type": "chatdata",
	"trans_date": "Datetime",  /* In UTC */
	"app_id": "String",
	"room_id": "String",
	"conf_num": "String",
	"chatdata": [ 
		{ "url": "http://FQDN/path/file" }
	]
}

Please refer to the online documentation for detailed explanation of Webhook Notification.

Live Recording with UI

Note: This functionality is available on the Flutter SDK version 2.1.5 and higher

Recording Live is a new process of creating a transcoded file in a live session with a custom layout without recording individual streams. So, using Live Recording has a double advantage:

• You get a transcoded file within minutes post-session. Not to wait longer like the previous transcoding process.
• Unlike previous transcoding processes created in a predefined layout, you can define your own layout for the live recording process.

Auto Live Recording

You can configure a Room with to start Live Recording automatically as soon as the first person joins the Room. This may be done while creating a Room with the following settings:

"settings": { 
	"live_recording": {
		"auto_recording: true, 
		"url": "https://your-custom-view-url"
	}
}

Notes:

• You can read the detailed information about room creating payload using our Server API here.
• Read the detailed information on how to create a custom view for the live recording here. It is the same way we create View for Live Streaming.
• URL is optional. If you skip it, EnableX uses a default layout.
• Moderator can still stop live recording in a Room by using the stopRecord() method given below.

On-Demand Live Recording

Using SDK methods, a Moderator can start / stop live recording whenever he demands.

Start Live Recording

The EnxRoom.startLiveRecording() method allows moderators to start live recording of video sessions.

Class: EnxRoom

Method: static Future startLiveRecording(Map <String, Dynamic> config)

Parameters

Sample Response

{
	data = {
		status =  {
			resultCode = 0,
                        success = true,
                        error = {
				errorCode = 0;
                                errorDesc = "";
			} 
		},
		startedBy = "7f0f2b04-1ad4-4231-8fdc-9f9e014053b4",
	},
        type = "room-live-recording-on";
}

Sample Code

Map<String, dynamic> config = {
	"urlDetails": {}
};

//Method calling
await EnxRtc.startLiveRecording(config);

// Acknowledgement
EnxRtc.onACKStartLiveRecording=(Map<dynamic, dynamic> map){
      print('onACKStartLiveRecording' + jsonEncode(map));
}

// Notification to all 
EnxRtc.onLiveRecordingNotification=(Map<dynamic, dynamic> map){
      print('onLiveRecordingNotification' + jsonEncode(map));
}

Error Codes and Exceptions

Stop Live Recording

The EnxRoom.stopLiveRecording() method allows moderators to stop live recording of video session.

Class: EnxRoom

Method: EnxRtc.stopLiveRecording()

Event Notifications: onACKStopLiveRecording: Acknowledgement that stop recording request is received

Sample Response

{
	data = {
		status: {
                        resultCode: 0,
                        success: true,
                        error: { errorCode: 0, errorDesc: '' }
		},                                         
                stoppedBy = "7f0f2b04-1ad4-4231-8fdc-9f9e014053b4",
	},
        type = "room-live-recording-off";
}

//Method calling
await EnxRtc.stopLiveRecording(config);

// Acknowledgement
EnxRtc.onACKStopLiveRecording=(Map<dynamic, dynamic> map){
      print('onACKStopLiveRecording' + jsonEncode(map));
}

Error Codes and Exceptions

Error codes

Call State Change Event:

Start Streaming:

Stop Streaming:

Generic Error:

Move File CallBack:

Live Recording Waiting Queue:

Other Error Codes:

Play a Recorded File

If you want to play a recorded file directly from the EnableX server, please note that those files are password protected. EnableX implemets HTTP Basic Authentication to secure the recorded file storage.

Therefore, any video player may not use the file paths. The player must provide access credentials to pass through the authentication process to play the file.

Sample Code:

# https://pub.dev/packages/video_player

// HTTP Basic Authentication Credentials
String username = 'Username';
String password = 'Password';
String videoFilePath = 'URL';

String basicAuth = 'Basic ' + base64Encode(utf8.encode('$username:$password'));

VideoPlayerController _controller;
_controller = VideoPlayerController.network(
	videoFilePath,
	httpHeaders: {'authorization': basicAuth},);

_controller.addListener(() {
	setState(() {});
});

_controller.setLooping(true);
_controller.initialize();

Note:

• As an alternate way, download the files from the EnableX server to your server and play the files with or without any security measures you may like to deploy.
• Files from EnableX's storage get deleted after 72 hours. So, accessing them from the EnableX server is not guaranteed beyond 72 hours.

Hard Mute or Unmute a Room

Hard Mute a Room

The EnxRtc.hardMute() method allows moderator to hard-mute a room where all the participants are muted. A new participant joining a room in a hard-mute state is automatically muted.

Class: EnxRtc

Method: hardMute()

Callbacks:

Sample Code:

EnxRtc.hardMute(); // To hard-mute Room

EnxRtc.onHardMuted= (Map<dynamic, dynamic> map) {
    // Moderators are notified that Room is hard-muted  
};

EnxRtc.onReceivedHardMute= (Map<dynamic, dynamic> map) {
    // Participants are notified that Room is hard-muted   
};

Hard Unmute a Room

The EnxRtc.hardUnMute() method is used to change the hard-mute state of a room. The right to unmute a hard-muted room lies only with the moderator. Participants can neither unmute a room or their local streams.

Class: EnxRtc

Method: hardUnMute()

Callbacks

Sample Code:

EnxRtc.hardUnMute(); // To hard-unmute Room

EnxRtc.onHardUnMuted = (Map<dynamic, dynamic> map) {
    // Moderators are notified that Room is hard-unmuted        
};

EnxRtc.onReceivedHardUnMute = (Map<dynamic, dynamic> map) {
     // Participants are notified that Room is hard-unmuted   
};

Hard Mute or Unmute a Participant

Hard Mute a Participant

The EnxRtc.hardMuteAudio() and EnxRtc.hardMuteVideo() methods allow the moderators to hard-mute the audio and video streams of participants. The affected participants cannot unmute their audio and video streams.

Class: EnxRtc

Methods:

• static Future<void> hardMuteAudio(String clientId)
• static Future<void> hardMuteVideo(String clientId)

Parameters: clientID: The user whose audio/video needs to be hard muted.

Callbacks:

Sample Code:

EnxRtc.hardMuteAudio(clientId)    // To hard-mute user's Audio Stream

EnxRtc.onHardMutedAudio=(Map<dynamic, dynamic> map){
// Your audio is hard-muted
 };
EnxRtc.onReceivedHardMuteAudio=(Map<dynamic, dynamic> map){
// A User's audio is hard-unmuted - to all
 };

EnxRtc.hardMuteVideo(clientId).  // To hard-mute user's Video Stream

EnxRtc.onHardMutedVideo=(Map<dynamic, dynamic> map){
// Your video is hard-muted

  };

EnxRtc.onReceivedHardMuteVideo=(Map<dynamic, dynamic> map){
// A User's video is hard-unmuted - to all
 };

Hard Unmute a Participant

Moderators can unmute a participant's audio or video streams using EnxRtc.hardUnMuteAudio() and EnxRtc.hardUnMuteVideo() methods respectively.

Class: EnxRtc

Methods:

• static Future<void> hardUnMuteAudio(String clientId)
• static Future<void> hardUnMuteVideo(String clientId)

Parameter: clientID: The user whose audio/video needs to be hard unmuted.

Callbacks:

Sample Code:

EnxRtc.hardUnMuteAudio(clientId)  // To hard-unmute user's Audio Stream

EnxRtc.onHardUnMutedAudio=(Map<dynamic, dynamic> map){
// Your audio is hard-unmuted
 };

EnxRtc.onReceivedHardUnMuteAudio=(Map<dynamic, dynamic> map){
// A User's audio is hardmuted - to all
 
};

EnxRtc.hardUnMuteVideo(clientId). //// To hard-unmute user's Video Stream

EnxRtc.onHardUnMutedVideo=(Map<dynamic, dynamic> map){
// Your video is hard-unmuted
 };
EnxRtc.onReceivedHardMuteVideo=(Map<dynamic, dynamic> map){
// A User's video is hard-unmuted - to all
};

Room Entry Restriction

Lock a Room

The lockRoom() method allows moderators to lock a room, which forbids any new user from joining the session.

Class: EnxRtc

Method: static Future<void> lockRoom()

Event Notifications

Sample Code:

EnxRtc.lockRoom();	// To lock room
EnxRtc.unLockRoom();	// To unlock room

EnxRtc.onAckLockRoom = (Map<dynamic, dynamic> map) {
	// Moderator is acknowledged that room has been locked 
};

EnxRtc.onLockedRoom = (Map<dynamic, dynamic> map) {
	// Participants are notified that room has been locked
};

Unlock a Room

Moderators can unlock a room using the unLockRoom() method to allow subsequent users to join the session.

Class: EnxRtc

Method: static Future<void> unLockRoom()

Callbacks:

Sample Code:

EnxRtc.unLockRoom();	// To unlock room
 
EnxRtc.onAckUnLockRoom = (Map<dynamic, dynamic> map) {
      // Moderator is acknowledged that room has been unlocked 
};

EnxRtc.onUnLockedRoom = (Map<dynamic, dynamic> map) {
	// Participants are notified that room has been unlocked
};

Moderate Participant's Entry to a Session

Approve User's Entry

In a knock-enabled Room, users must wait until the moderator permits them to join the session. The approveAwaitedUser() method allows the Moderator to approve a user's entry to join a room.

Class: EnxRtc

Method: static Future<void> approveAwaitedUser(String clientId)

Parameters: clientID: The client ID of the user is awaiting moderator's approval.

Callbacks:

Sample Code:

EnxRtc.approveAwaitedUser(clientId);     // method allows the Moderator to approve a user's entry

EnxRtc.onAckForApproveAwaitedUser=(Map<dynamic,dynamic> map){
 
};
EnxRtc.onRoomAwaited=(Map<dynamic,dynamic> map){

};
EnxRtc.onUserAwaited=(Map<dynamic,dynamic> map){

};

Decline a User's Entry to Join a Room

The denyAwaitedUser() method allows moderators to decline a user's entry to join a room.

Class: EnxRtc

Method: static Future<void> denyAwaitedUser(String clientId)

Callbacks:

Sample Code:

EnxRtc.denyAwaitedUser(clientId);     // method is used to decline a user's entry to the session

EnxRtc.onAckForDenyAwaitedUser=(Map<dynamic,dynamic> map){

};
EnxRtc.onRoomAwaited=(Map<dynamic,dynamic> map){

};
EnxRtc.onUserAwaited=(Map<dynamic,dynamic> map){

};

Switch Participant Roles

The EnxRtc.switchUserRole() method allows moderators to promote a participant to act as a moderator in an ongoing session. The newly appointed moderator is provided access to the moderator controls, and the former moderator becomes a participant in the session. If desired, the new moderator can grant the moderator role to another participant in the session.

Class: EnxRtc

Method: static Future<void> switchUserRole(String clientId)

Parameter: clientId: Client ID of the participant who is designated as moderator.

Callbacks:

Sample Code:

EnxRtc.switchUserRole('clientId'); // To assign Moderator Role to clientId

EnxRtc.onSwitchedUserRole = (Map<dynamic,dynamic> map) {
	// The moderator is notified that the request to role-switch has been received 
};

EnxRtc.onUserRoleChanged = (Map<dynamic,dynamic> map) {
	// Everyone is notified about the new Moderator
};

Pin or Unpin a User

Pin a User

The EnxRtc.pinUsers() method allows moderators to pin a user to the Active Talker List irrespective of the user's activity level. A pinned user's stream is always published in the room, even if the user is not talking. The inactive pinned users are placed in the Active Talker List after the actively talking users in a descending order based on the activity level, with the most active talkers at the top of the list. The total number of pinned users in a room is restricted to (max_active_talkers: 1) based on the room configuration.

On joining a Room, the user is notified via the onRoomConnected event with Room Meta Information, which contains the list of pinned users as "pinnedUsers": [ /*client-ids*/ ].

Class: EnxRtc

Method: static Future<void> pinUsers(List<dynamic> clientId)

Parameter: clientIds: Array of Client IDs of users whose streams need to be pinned.

Callbacks:

Sample Code:

EnxRtc.pinUsers(clientIds); // To pin

EnxRtc.onAckPinUsers=(Map<dynamic,dynamic> map){
// Moderator is acknowledged for pinning user
};

EnxRtc.onPinnedUsers=(Map<dynamic,dynamic> map){
// Everyone is notified wtih updated pinned list
};

Error Codes and Exceptions

Unpin a User

The EnxRtc.unpinUsers() method is used to unpin the users.

Class: EnxRtc

Method: static Future<void> unpinUsers(List<dynamic> clientId)

Parameters: clientIds: Array of Client IDs of users whose streams need to be unpinned.

Callbacks:

Sample Code

EnxRtc.unpinUsers(clientIds); //To Unpin

EnxRtc.onAckUnpinUsers=(Map<dynamic,dynamic> map){
  // Moderator is acknowledged for unpinning user
};
EnxRtc.onPinnedUsers=(Map<dynamic,dynamic> map){
// Everyone is notified wtih updated pinned list
};

Error Codes and Exceptions

Spotlight a User

The EnxRtc.addSpotlightUsers() method allows moderators to spotlight a user, pushing the user's stream to the top of the Active Talker List irrespective of the user's activity level. Spotlighting publishes the chosen user's stream in the room even if the user is not talking. The moderator can spotlight as many users as max_active_talkers defined in the Room Configuration.

On joining a room, the user is notified through a onRoomConnected event with Room Meta Information, which contains the list of spotlightUsers.

In addition, the JSON containing the active talkers list received with the onActiveTalkersUpdated callback includes a "spotlight" key with a boolean value. Spotlighted users have spotlight: true in the list.

Class: EnxRtc

Method: static Future<void> addSpotlightUsers(List<dynamic> clientIds)

Parameters: clientID: An array of Client IDs of users whose streams are spotlighted.

Callbacks:

Sample Code:

EnxRtc.addSpotlightUsers(clientIds) // To spotlight

EnxRtc.onAckAddSpotlightUsers=(Map<dynamic,dynamic> map){

// Moderator who spotlights users is acknowledged

};
EnxRtc.onUpdateSpotlightUsers=(Map<dynamic,dynamic> map){

// Everyone is notified with updated Spotlight list

};

Remove the Spotlight from a User

The EnxRtc.removeSpotlightUsers() method removes the spotlight from user streams.

Class: EnxRtc

Method: static Future<void> removeSpotlightUsers(List<dynamic> clientIds)

Parameters: clientID: An array of Client IDs of users whose streams are spotlighted.

Callbacks:

Sample Code:

EnxRtc.removeSpotlightUsers(clintIds) // To remove from spotlight

EnxRtc.onAckRemoveSpotlightUsers=(Map<dynamic,dynamic> map){

// Moderator who removes users from Spotlight is acknowledged

};
EnxRtc.onUpdateSpotlightUsers=(Map<dynamic,dynamic> map){

// Everyone is notified with updated Spotlight list

};

Disconnect a User

The dropUser() method allows moderators to disconnect or force-drop one or more participants from a session.

Class: EnxRtc

Method: static Future<void>dropUser(List<dynamic>clientIds)

Parameters

Sample Code:

EnxRtc.dropUser([clientIds]); // To drop clientIds from session

EnxRtc.onAckDropUser=(Map<dynamic,dynamic> map) {
	// Moderators are notified with a clientIds dropped
};

Switch the Room Mode

A room defined with group or lecture mode may be switched to the other mode at runtime, that is, in an ongoing session. The EnxRoom.switchRoomMode() method is executed by the moderator to switch to other modes instantly.

When a room is switched from group to lecture mode:

• The audio/video streams of all participants are dropped from the room with a notification to each participant.
• All the features of the Lecture mode, such as floor access control are activated.
• All active breakout rooms are terminated.

On the other hand, when a room is switched from lecture to group mode:

• A notification is sent to each participant, allowing them to publish their audio/video streams into the room.
• Due to privacy concerns, the SDK does not automatically start publishing audio/video streams, but application developers must decide whether to automatically publish the streams or prompt the participants to publish.

Class: EnxRtc

Method: static Future<void> switchRoomMode(String mode)

Parameter: mode: String. Enumerated values lecture, group
The mode to which you want to switch the room into.

Callbacks:

Sample Code:

EnxRtc.switchRoomMode(mode).   //To switch to group mode  mode =group/lecture

EnxRtc.onAckSwitchedRoom=(Map<dynamic,dynamic> map){
// Moderator is acknowledged
};
EnxRtc.onRoomModeSwitched=(Map<dynamic,dynamic> map){
// Everyone is notified
};

Error Codes and Exceptions

Session Extension and Closure

Extend a Session

Each Room is defined with a duration value in minutes. This duration defines the total length of a single session. This time is counted as soon as the first user joins the session. EnableX drops the session when the session duration elapses.

For practical reasons, a session may need to get extended. Therefore, EnableX allows users to extend a session duration at runtime. The extension process is explained below.

1. An Extension window opens 10 minutes before the specified closure time of a session. All the connected users are notified of this event.
2. Users can trigger an extension of the session by calling a method. Once triggered, the Extension Window is closed, thus preventing subsequent extension requests.
3. If the extension is not triggered, the final Extension window opens 5 minutes before the scheduled closure of the session. All the connected users are notified of this event.
4. The session can be extended by 10 to 30 minutes. The extended period can vary as there is no restriction on the number of times a session is extended.
5. When a session is extended, the previous steps are repeated.

Method: static Future<void> extendConferenceDuration()

Note: The method is available only when an Extension Window is open.

Callbacks:

Sample Code:

// Listen to event to know when Extension Window is open
EnxRtc.onConferenceRemainingDuration= (Map<dynamic, dynamic> map) {
};

EnxRtc.extendConferenceDuration(); // Extend Session

// Listen when Session is extended
EnxRtc.onConferencessExtended= (Map<dynamic, dynamic> map) {
};

Conclude an Ongoing Session

The destroy() method lets moderators to conclude an ongoing session.

Class: EnxRtc

Method: static Future<void> destroy()

Event Listener: onAckDestroy: To acknowledge that the session has been destroyed

Sample Code:

nxRtc.destroy(); // Destroy session

EnxRtc.onAckDestroy= (Map<dynamic, dynamic> map) {
	// Notification to all that session is destroyed.
};