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.
- An Extension window opens 10 minutes before the specified closure time of a session. All the connected users are notified of this event.
- Users can trigger an extension of the session by calling
extendConferenceDuration()
. Once triggered, the Extension window is closed, thus preventing the subsequent extension requests. - 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.
- 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 theextendedTime
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 openroom.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 extensionroom.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 reasonif (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
, anddisconnected
.
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
Code | Description |
---|---|
1141 | The dial-out request is already in process. |
1142 | The CLI does not match with the configured phone number. |
4124 | The 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 samedialout_number
used withmakeOutboundCall()
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
Code | Description |
---|---|
1155 | Invalid options/parameters/values. |
1201 | Invalid Dial-State. |
1202 | Outbound 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 Number | Constants |
---|---|
0 | DEBUG |
1 | TRACE |
2 | INFO |
3 | WARNING |
4 | ERROR |
5 | NONE |
Sample Code
// Using Level NumberEnxRtc.Logger.setLogLevel(3);// Alternate: Using related ConstantsEnxRtc.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"].
- To test only selected Test Groups, add selected Test Group names e.g.,
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 Testclient = EnxRtc.clientDiagnostics(Options);// Notification: Test Execution finishedclient.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 failedclient.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 stoppedclient.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 Caseclient.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 Microphonecamera
: This is to test Cameraconnection
: This is to test connectivitybandwidth
: 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 replyclient = 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 isDE
.
- 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 completionclient.addEventListener("client-bitrate-status", function(response) {// handle info message from response.message});// Notification: On execution completionclient.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 callroom.setAudioOnlyMode(false); // Switched back to Audio-Video call