Utilities

The Web SDK provides the following methods for managing different aspects of video sessions:

• extendConferenceDuration(): To extend the duration of a session.
• destroy(): To conclude an ongoing session.
• makeOutboundCall(): To initiate an outbound call to a PSTN number or a SIP URI while being in a session.
• setLogLevel(): To write logs.
• setOutputFunction(): To obtain logs in addition to the logs printed in the browser console.
• postClientLogs(): To send the most recent 500 lines of console logs to EnableX.
• clientDiagnostics(): To detect issues that cause WebRTC to fail.
• clientBitrate(): To fetch the bitrate status of clients.
• getVideoFrameImage(): To take a snapshot of a video stream.
• setAudioOnlyMode(): To switch to an audio-only call.

Session Extension and Closure

Extend a Session

The length of a video session allowed in a Video Room is calculated in minutes and defined during the room creation using settings.duration. It is counted from the time the first user joins a session.

The EnxRoom.extendConferenceDuration() allows you to extend the duration of a session beyond the configured value. 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 extendConferenceDuration(). Once triggered, the Extension window is closed, thus preventing the subsequent extension requests.
3. If 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 the session closure. 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.
4. When a session is extended, the previous steps are repeated.

• Method: EnxRoom.extendConferenceDuration(Callback)
• Parameterd:
  • Callback: Callback Funtion. To receive result of the rquest. It returns JSON. If extended, includes the extendedTime key to show the number of minutes the extension has been granted.
• Event Notifications:
  • conference-remaining-duration: Notification to everyone in the room when an Extension window is open. It includes a JSON to show how many minutes are left before the scheduled session will be closed.

Sample Code

// Notification: To all. Extension window is open
room.addEventListener('conference-remaining-duration', function(event) {
        var timeLeft = event.message.timeLeft;

        // Show UI to all users or to participants to
	// trigger EXTEND by caling method.
});

// To request session extension 
room.extendConferenceDuration( function(message) {
	if(message.result== 0)
	{	var extended_minutes = message.extendedTime;
	}
});

Destroy a Session

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

• Method: EnxRoom.destroy()
• Event Notifications:
  • room-disconnected: Notification to all users in the room when the session is destroyed.

Sample Code

room.destroy();
 
// Notification: To all. Room Disconnected with a reason.
room.addEventListener("room-disconnected", function(event) {
	// Event carries the reason
	if (event.message.cause.msg === 'disconnected-by-moderator') {
		// Show message to user
	}
});

Dialing Out to Phone and SIP Endpoint from a Video Room

Dial-Out Phone

This functionality is available from Web SDK 1.5.3 onwards.

The EnxRoom.makeOutboundCall() method allows you to initiate an outbound call to a PSTN number or a SIP URI while being in a session, thus inviting the called participants to join the session on accepting the call.

• Method: EnxRoom.makeOutboundCall(dialout_number, cli_number, options, callback)
• Parameters:
  • dialout_number : String It can be a PSTN number or a SIP URI. If you are dialing a phone number, use a country code without 00 or +.
  • cli_number : String. You are calling the Line Identification Number to add it as the originator of the call. In case of PSTN phone numbers, this is validated against your purchased number or the opted shared number. If the CLI does not match, the call fails with the "CLI mismatch" error.
  • options : Dial-Out options. This parameter is available from Web SDK 2.0.2 onwards.
    • name : String. Name of the dialled participant. If it is omitted, the dialled phone number is used as the name of the dialled participant.
    • early_media: Boolean. The default value is false. With this setting, the ringer is not placed in the room when the dial-out is in progress.
      If it is set to true, the ringer is played in the room when the dial-out is initiated.
    • silent_join : Boolean. The default value is false. With this setting, the dialled participant is admitted to a room as soon as the dial-out is in progress and the ringer is played. If it is set to true, the dialled participant is not admitted to a room until the participant answers the call.
  • callback : Callback Function. To know the dial-out request result. Error codes are included in failure notifications.
• Event Listeners:
  • dial-state-events: Notification to the call initiator about the state of the dial-out process as received from the gateway. The JSON response returns the states as: initiated, dialing, connected, dtmf-collected, and disconnected.

Note: The early_media and silent_join parameters are mutually exclusive and cannot be used together.

Sample Code

var dialout_option = {
	"name": "John",
	"early_media": false,
	"silent_join": true
};

room.makeOutboundCall('91999999999', '918888888888', dialout_option, function(resp) {
	// resp JSON example
	/*
	{ 	"result": 0,  
		"msg": "Success"  
	}
	*/ 
}); 

room.addEventListener("dial-state-events ", function(evt) {
	// evt JSON: State of dial-out process 

	/*
	{	number: "9999999999",	 
		state: "connected", 	 
		description: "Detailed description"
	} 

	evt state may be initiated, dialing, connected, 
	dtmf-collected & disconnected
	*/
});

Error Codes

Send DTMF Response

This functionality is available from Web SDK v2.3.26+ onwards.

The EnxRoom.sendDTMF() method allows send DTMF response to pass through an IVR if dialed out PSTN Call is connected to IVR. This method can be executed repeatedly to pass single digit or multiple digits in a single call.

An outbound PSTN Call must have been answered first to make use of sendDTMF() method to pass DTMF digits on the same PSTN channel.

• Method: EnxRoom.sendDTMF(options, callback)
• Parameters::
  • options :
    • number : String. It's the same dialout_number used with makeOutboundCall() method. It can be either a PSTN Number or a SIP URI to dial out. For Phone Number, use country code without 00 or +.
    • digits : String. Digit(s) to pass on to Voice Service as DTMF digits.
  • callback : Callback Function. To know the dial-out request result. Error codes are included in failure notifications.

Sample Code

var dtmf_option = {
	"number": "91999999999",
	"digits": "1"
};

room.sendDTMF(dtmf_option, function(resp) {
	// resp JSON
	/*
	{ 	"result": 0,  
		"msg": "Success"  
	}
	*/  
});

Error Codes

Console Logging

The Web SDK logs printed in the browser console help you debug the application during the development process. Using the following methods, you can access and control the amount of logs generated for efficient debugging.

Set Log Level

The input and output operations to write logs is a time-consuming task. Therefore, you need granular control over the logs that the SDK writes on the browser console to:

• Print optimum log entries for debugging or audit processes.
• Ensure faster communication and media flow with EnableX.

• Method: EnxRtc.Logger.setLogLevel(Level)
• Parameters:
  • Level : Number. 0-5 in descending order of log detail. The default level is 0.

Sample Code

// Using Level Number
EnxRtc.Logger.setLogLevel(3); 

// Alternate: Using related Constants
EnxRtc.Logger.setLogLevel(WARNING);

Get a Log Dump

The Logger.setOutputFunction() provides access to logs in addition to the logs that are printed in the browser console by sending them via email or creating a UI.

• Method: EnxRtc.Logger.setOutputFunction(Callback)
• Parameters:
  • Callback : Callback Function. To receive status of the request.

Sample Code

EnxRtc.Logger.setOutputFunction( function(response) {
       // Use response
});

Share Logs with EnableX for Auditing

The EnxRtc.postClientLogs() method allows you to send most recent 500 lines of the console logs to EnableX using an HTTP POST request. Ideally, you should request user's consent before posting the log to EnableX.

• Method: EnxRtc.postClientLogs(Token, Callback) Parameters:
  • Token : The same token used to connect or join Room.
  • Callback : Callback Function. To receive status of the request.

Sample Code

if( confirm("You are posting Browser Console Log to audit.nSure?")) {
      room.postClientLogs(token, function(res) {
           Logger.info(res.message);    
      });
}

Pre-Call Test

This functionality is available from Web SDK 1.9.5 onwards.

The EnxRtc.clientDiagnostics() method acts as a Diagnostic Tool to detect issues that may cause WebRTC failure. The API runs through predefined test cases related to WebRTC issues and asynchronously reports through an event as it runs each test case. These test cases are organized in the below test groups.

• Microphone
  • Audio capture
• Camera
  • Check resolution 320×240
  • Check resolution 640×480
  • Check resolution 1280×720
  • Check supported resolutions
• Network
  • UDP enabled with TURN server
  • TCP enabled with TURN server
  • IPv6 enabled with TURN server
• Connectivity
  • Relay connectivity with TURN server
  • Reflexive connectivity with TURN server
  • Host connectivity with TURN server
• Throughput
  • Data throughput with TURN server
• Bandwidth
  • Video bandwidth with TURN server
  • Audio bandwidth with TURN Server
• Signalling
  • Signalling connectivity with TURN server

Using this API, you can also build a UI to initiate the tests and generate a diagnostic report.

-Method: EnxRtc.clientDiagnostics(ClientInfo)

• Parameters:
  • ClientInfo : JSON object with Client preferences for the execution of Test cases. JSON Keys are explained below:
    • testNames : Array of Test Group names. e.g. [ "microphone", "camera", "network", "connectivity", "throughput", "bandwidth", "signalling"]
      • To test only selected Test Groups, add selected Test Group names e.g., ["microphone", "camera"].
      • To test all the Test Groups, use ["all"].
    • audioDeviceId : Optional. Device Id of input audio device.
    • videoDeviceId : Optional. Device Id of input video device.
    • regionId : Optional. Array of region Ids of ICE Servers, e.g. ["IN", "SG", "US", "DE"]. Get Region-ID list from Portal.
    • testDurationDataThroughput : Optional. Test duration of data throughput in seconds. [Range: 1-30 sec. Default: 2 sec].
    • testDurationVideoBandwidth : Optional. Test duration of video bandwidth in seconds. [Range: 1-30 sec. Default: 10 sec].
    • testDurationAudioBandwidth : Optional. Test duration of audio bandwidth in seconds. [Range: 1-30 sec. Default: 10 sec].
    • stop : Optional. Boolean. Set to true to stop the test cases which are already in execution.
• Event Notifications:
  • client-diagnosis-failed : Notification of diagnosis failure when the API is called with a wrong parameter or a repeated attempt to call the API is made while the previous request is still in progress.
  • client-diagnosis-stopped : Notification sent when the API execution is explicitly stopped through a method call.
  • client-diagnosis-finished : Notification sent when the API completes execution of all the test cases. A JSON object with the results of all the test cases is returned.
  • client-diagnosis-status : Notification sent with the test result of each test case when the API passes through the execution of each test until completion or explicitly stopped. A JSON object with test results is returned.

Sample Code

var Options = {
     testNames: ['microphone', 'camera'],
     audioDeviceId: 'XXX',
     videoDeviceId: 'XXX',
     regionId: ['IN'],
     testDurationDataThroughput: 2,
     testDurationVideoBandwidth: 30,
     testDurationAudioBandwidth: 30,
     stop: false
};

// Execute Test 
client = EnxRtc.clientDiagnostics(Options); 

// Notification: Test Execution finished
client.addEventListener("client-diagnosis-finished", function(response) {
	// Handle JSON from response.message.
	// It contains complete test result. 
	// A response example given later
});

// Notification:  Test Execution has failed
client.addEventListener("client-diagnosis-failed", function(response) {
	// Handle error message from response.message.
	// Response example:
	/* 
	- Invalid argument.
	- Diagnosis is already in progress. 
          A few resources are in use and may not be accessible.
	*/
});

// Notification: Test Execution has stopped
client.addEventListener('client-diagnosis-stopped', function(response) {
	// Handle info message from response.message
	// Response example:
	/* 
	- Diagnosis stopped.
	- Diagnosis not running.
	*/
});

// Notification: Intermediate Test Result of each Test Case 
client.addEventListener("client-diagnosis-status", function(response) {
	// Handle JSON in response.message
	// It contains complete test result. 
	// A response example is provided later
});

Sample JSON Response: At beginning of client-diagnosis-status

{
	"test_group": "microphone",
	"test_case": "audio_capture",
	"status": "started",
	"output": ""
}

Sample JSON Response: Intermediate response after finishing the client-diagnosis-status

{
  "test_group": "microphone",
  "test_case": "audio_capture",
  "status": "finished",
  "output": {
    "audio_capture": {
      "result": "success",
      "execution_time": "241 ms",
      "success": [
        {
          "message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
        },
        {
          "message": "Active audio input channels: 2"
        }
      ],
      "error": [],
      "warning": [],
      "info": [
        {
          "message": "Channel 0 levels: -38.3 dB (peak), -48.4 dB (RMS)"
        },
        {
          "message": "Channel 1 levels: -38.3 dB (peak), -48.4 dB (RMS)"
        },
        {
          "message": "Stereo microphone detected."
        }
      ]
    }
  }
}

Sample JSON Response: After completion of all test cases with client-diagnosis-finished

{
  "microphone": {
    "audio_capture": {
      "result": "success",
      "execution_time": "241 ms",
      "success": [
        {
          "message": "Audio track created using device=Default - Microphone Array (Synaptics Audio)"
        },
        {
          "message": "Active audio input channels: 2"
        }
      ],
      "error": [],
      "warning": []
    }
  },
  "network": {
    "udp_enabled": {
      "IN": {
        "TURN": {
          "result": "success",
          "execution_time": "241 ms",
          "success": [
            {
              "message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
            }
          ],
          "error": [],
          "warning": [],
          "server": {
            "region": "IN",
            "url": "turns:ts.enablex.io:443"
          }
        }
      }
    },
    "tcp_enabled": {
      "IN": {
        "TURN": {
          "result": "success",
          "execution_time": "241 ms",
          "success": [
            {
              "message": "Gathered candidate of Type: relay Protocol: udp Address: 104.211.155.197"
            }
          ],
          "error": [],
          "warning": [],
          "server": {
            "region": "IN",
            "url": "turns:ts.enablex.io:443"
          }
        }
      }
    }
  }
}

Explanation of Test Results

Get Bitrate Status of a Client

This functionality is available from Web SDK version 1.9.8 onwards

The EnxRtc.clientBitrate() method provides the bitrate status of the clients. It performs the following tests to generate a response:

• Bandwidth
  • Video bandwidth with TURN server
  • Audio bandwidth with TURN Server

You can also build a UI to initiate the tests and generate a diagnostic report using this API.

• Method: EnxRtc.clientBitrate(clientInfo)
• Parameter:
  • clientInfo: Optional. JSON Object with Client preferences for the execution of test cases.
    • region : String. Region Id of the ICE server. for example, IN, SG, US, DE. The default Region ID is DE.
  • Event Notifications:
    • client-bitrate-finished : Notification sent on execution completion of the test case.
    • client-bitrate-status : Notification sent with the test results at the beginning and at end of the test.

Sample Code

var clientInfo = {
     "region": 'IN'
};

let client = EnxRtc.clientBitrate(clientInfo);

// Notification: At beginning and completion
client.addEventListener("client-bitrate-status", function(response) {
     // handle info message from response.message
});

// Notification: On execution completion  
client.addEventListener("client-bitrate-finished", function(response) {
     // handle json from response.message
});

Sample JSON Response: With event client-bitrate-status

//Status at the start of test 
{
	"status": "started",
	"test_case": "video_bandwidth",
	"test_group": "bandwidth",
	"test_region": "IN",
	"test_server": "TURN"
}

// Status at the end of test
{
	"test_group": "bandwidth",
	"test_case": "video_bandwidth",
	"status": "finished",
	"output": {
		"video_bandwidth": {
			"result": "success",
			"bandwidth_bps": 2221949,
			"packets_lost_percentage": "0.99",
			"execution_time": "31566 ms",
			"success": [],
			"error": [],
			"warning": [],
			"info": [],
			"server": {
			"region": "IN",
			"url": "turns:ts.enablex.io:443"
		}
	}
	},
	"test_region": "IN",
	"test_server": "TURN"
}

Sample JSON Response: With event client-bitrate-finished

{
	"video": {
		"bitrate_bps": 2221949,
		"connection": "stable"
	},
	"audio": {
		"bitrate_bps": 278067,
		"connection": "stable"
	}
}

Sample JSON Explanation

Note: Currently this SDK does not work for Safari browsers.

Take Snapshot

The EnxStream.getVideoFrameImage() method allows you to take a snapshot of video streams in your application. The image from a video stream is captured as a raw bitmap data into the Canvas DOM element.

• Method: EnxStream.getVideoFrameImage()

Sample Code

var myBitmap;
var canvas = document.createElement('canvas');
var context = canvas.getContext('2d');

canvas.id = "myCanvas";
document.body.appendChild(canvas);
myBitmap = stream.getVideoFrameImage();

canvas.width = myBitmap.width;
canvas.height = myBitmap.height;
context.putImageData(myBitmap, 0, 0);

Audio Only Mode for Video Rooms

The EnxRoom.setAudioOnlyMode() method allows you to switch to an audio-only call where you can neither receive video from any participant nor publish your video. You can use this method to switch between audio-only and audio-video calls. It does not affect video streams from others or the ability to publish/receive screen sharing in the room.

• Method: EnxRoom.setAudioOnlyMode(AudioOnly)
• Parameters:
  • AudioOnly: Boolean. Set it to true to switch to an audio-only call.
    Set it to false to switch to an audio-video call.

Sample Code

room.setAudioOnlyMode(true);   // Switched to Audio-Only call
room.setAudioOnlyMode(false);  // Switched back to Audio-Video call