Utilities

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

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

CodeDescription
1141The dial-out request is already in process.
1142The CLI does not match with the configured phone number.
4124The dialed-out phone number does not exist.

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

CodeDescription
1155Invalid options/parameters/values.
1201Invalid Dial-State.
1202Outbound Dial Request not found.

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.
Level NumberConstants
0DEBUG
1TRACE
2INFO
3WARNING
4ERROR
5NONE

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 SDK Method can be executed in 3 different ways:

  • Use Case:1 Elaborated Test and Async Response
  • Use Case:2 Short & Quick Test Result on Callback

Both types of usage of the method explained below:

Use Case:1 Elaborated Test and Async Response

When called a callback, it runs through predefined or given 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(Options)

  • Parameters:
    • Options is a 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

Test Group Test Case Server Result Message
Microphone Audio Capture Not Applicable Success Audio track created using device #device#.
Success Active audio input channels #channel#.
Failure Web audio run failure.
Failure No audio track in the returned stream.
Failure No active input channels detected.
Failure No active input channels detected. Microphone is most likely muted or broken. Check if it is muted in the sound settings or physically on the device, then rerun the test.
Failure Microphone input level is low. Increase the input volume or move closer to the microphone.
Failure getUserMedia failed with the #error# error.
Camera check resolution 240 Not Applicable Success Captured the video using the expected resolution.
Success The average FPS is above the threshold value.
Failure getUserMedia failed with a #error# error.
Failure No video track is found in the returned stream.
Failure The video track has ended and the camera has stopped working.
Failure Low average is sent to FPS.
Failure Incorrect video resolution is captured.
Failure Could not analyze any video frame.
Failure The camera is delivering a lot of black frames.
Failure The camera is delivering a lot of frozen frames.
Camera check resolution 480 Not Applicable Success Captured the video using the expected resolution.
Success The average FPS is above the threshold value.
Failure getUserMedia failed with error #error#
Failure No video track is found in the returned stream.
Failure Video track has ended, and the camera stopped working.
Failure Low average is sent to FPS.
Failure Incorrect video resolution is captured.
Failure Could not analyze any video frame.
Failure Camera is delivering a lot of black frames.
Failure Camera is delivering a lot of frozen frames.
Camera check resolution 720 Not Applicable Success Captured video using expected resolution
Success The average FPS is above the threshold value.
Failure getUserMedia failed with error #error#
Failure No video track is found in the returned stream.
Failure Video track has ended and the camera stopped working.
Failure Low average is sent to FPS.
Failure Incorrect video resolution is captured.
Failure Could not analyze any video frame.
Failure Camera is delivering a lot of black frames.
Failure Camera is delivering a lot of frozen frames.
Camera Check supported resolutions. Not Applicable Success Success supported resolution #resolution#.
Failure No video track is found in the returned stream.
Failure Video track has ended, and the camera stopped working.
Network udp enabled TURN Success Supported resolution #resolution#
Failure No video track is found in the returned stream.
Failure Video track has ended, and the camera stopped working.
Network tcp enabled TURN Success Gathered the candidate of Type: relay Protocol: udp Address: #IP#.
Failure Failed to gather specified candidates.
Failure Failed to create peer connection: #error#.
Network ipv6 enabled TURN Success Gathered candidate of Type: relay Protocol: udp Address: #IP#.
Failure Failed to gather IPv6 candidates, the candidates might not be setup/supported on the network.
Failure Failed to gather IPv6 candidates, the candidates might not be setup/supported on the network.
Connectivity relay connectivity TURN Success Data is successfully transmitted between peers.
Failure Invalid data is transmitted.
Failure Time out
Connectivity reflexive connectivity TURN Success Data is successfully transmitted between peers.
Failure Invalid data is transmitted.
Failure Time out
Connectivity host connectivity TURN Success Data is successfully transmitted between peers.
Failure Invalid data is transmitted.
Failure Time out
Throughput Data Throughput TURN Success Total transmitted: #n# kilo-bits in #t# seconds.
Failure Timed out
Bandwidth Video Bandwidth TURN Success Video resolution: #Width# x #Height#.
Failure Camera failure: #Width# x #Height#. Cannot test the bandwidth without a working camera.
Failure getUserMedia failed with error #error#.
Failure The frame rate mean is 0 (zero). Cannot test the bandwidth without a working camera.
Failure Could not gather statistics.
Failure Only Firefox and Chrome browser getStats implementation is supported.
Bandwidth Audio Bandwidth TURN Subject to quality Average audio bandwidth value
Subject to quality Packets lost: value
Subject to quality RTT Average: value
Failure getUserMedia() failed with an error.
Failure Only Firefox and Chrome browser getStats() implementation is supported.
Signaling Signaling Connectivity Not Applicable Success The token is successfully created.
Failure Token creation failed due to error: #error#.
Failure Room is not joined due to error: #error#.
Success Room is successfully joined.

Use Case:2 Short & Quick Test Result on Callback

This method can also be used to carry our a quick and test with shorter Test Options to get a limited resultset on callback of the method call.

-Method: EnxRtc.clientDiagnostics(Options, Callback)

  • Parameters:
    • Options is an optional JSON Array. If not specified it runs all the given tests below. Alternately, you can use one or more of these test cases as Array Element to run related tests only.
      • microphone : This is to test Microphone
      • camera: This is to test Camera
      • connection: This is to test connectivity
      • bandwidth: This is to test bandwidth for optimum communiction.
    • Callback : This is callback function to receive quick and short response on all or given tests.

**Sample Code: ** To run through all test cases to get quick reply

// To run through all test cases to get quick reply
client = EnxRtc.clientDiagnostics(function(response){
// Response JSON explained below
}
});

**Sample Code: ** To run through few few test-cases to get quick reply

var Options = [ 'microphone', 'camera'];
client = EnxRtc.clientDiagnostics(Options, function(response){
// Response JSON is explained below.
});

**Response JSON: ** Given below complete JSON Object received for full test

{
"browser": {
"supported": true,
"reason": "Reason if unsupported"
},
"microphone": {
"state": "passed/failed",
"reason": "Reason if failed"
},
"camera": {
"state": "passed/failed",
"reason": "Reason if failed"
},
"connection": {
"state": "passed/failed",
"reason": "Reason if failed"
},
"bandwidth": {
"video": {
"send": 80, // BW in kbps
"recv": 92, // BW in kbps
"error": "If error"
},
"audio": {
"send": 80, // BW in kbps /
"recv": 92, // BW in kbps /
"error": "If error"
}
}
}

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

Test Group Test Case Server Result Messsage
Bandwidth Video Bandwidth TURN Success Video resolution: Width x Height.
Failure Camera failure: Width x Height. Cannot test the bandwidth without a working camera.
Subject to quality. Average video bandwidth "value".
Subject to quality Packets lost: "value"
Subject to quality. RTT Average: "value"
Failure getUserMedia() failed with error "error"
Failure The frame rate mean is 0 (zero). Cannot test the bandwidth without a working camera.
Failure Only Firefox and Chrome browser getStats() implementation is supported.
Audio Bandwidth TURN Subject to quality Average Audio bandwidth "value".
Subject to quality Packets lost: "value"
Subject to quality RTT Average: "value"
Failure The getUserMedia() failed with error "error".
Failure Only Firefox and Chrome browser getStats() implementation is supported.

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