Availability: Web SDK v1.9.5+
The EnxRtc.clientDiagnostics()
method acts as a Diagnostic Tool to detect any issue causing the RTC to fail. The API runs through predefined test cases related to WebRTC issues and reports asynchronously through an Event as it passes through each test. These test cases are organized in “Test Groups” as shown below:
- 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
You can also build a UI to initiate the tests and generate a diagnostic report using this API.
Class: EnxRtc
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"]
.
- 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 API is called with the wrong parameter or a repeated attempt to call the API is made while the previous request is under process.client-diagnosis-stopped
– Notification sent when the API execution is stopped explicitly through Method Call.client-diagnosis-finished
– Notification sent when the API completes execution of all the test cases. This returns a JSON Object with a complete test result of all the test cases.client-diagnosis-status
– Notification sent with the test result of each test case as the API passes through the execution of each test till the completion or till stopped explicitly. This returns a JSON Object with test results.
Request for diagnostics:
var Options = {
testNames: ['microphone', 'camera'],
audioDeviceId: 'XXX',
videoDeviceId: 'XXX',
regionId: ['IN'],
testDurationDataThroughput: 2,
testDurationVideoBandwidth: 30,
testDurationAudioBandwidth: 30,
stop: false
};
client = EnxRtc.clientDiagnostics(Options); // Execute Test
// 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
});
// 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. Few resources are in use and may not be accessible.
*/
});
// Test Execution has stopped
client.addEventListener('client-diagnosis-stopped', function(response) {
// Handle info message from response.message
// Response example:
/*
- Diagnosis stopped.
- Diagnosis not running.
*/
});
// 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 given later
});
Response at the beginning of the Test: client-diagnosis-status
{ "test_group": "microphone", "test_case": "audio_capture", "status": "started", "output": "" }
Intermediate Response after finishing a test case: 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."
}
]
}
}
}
Final Response after completion of all the test cases: 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"
}
}
}
}
}
}
Test Result Explanation:
Test Group | Test Case | Server | Result | Message |
---|---|---|---|---|
Microphone | Audio Capture | N/A | Success | Audio track created using device #device# |
Success | Active audio input channels #channel# | |||
Failure | WebAudio run failure: | |||
Failure | No audio track in returned stream | |||
Failure | No active input channels detected | |||
Failure | No active input channels detected. Microphone is most likely muted or broken, please check if muted in the sound settings or physically on the device. Then re-run the test. | |||
Failure | Microphone input level is low, increase input volume or move closer to the microphone. | |||
Failure | getUserMedia failed with error #error# | |||
Camera | check resolution 240 | N/A | Success | Captured video using expected resolution |
Success | Average FPS above threshold | |||
Failure | getUserMedia failed with error #error# | |||
Failure | No video track in returned stream | |||
Failure | Video track ended, camera stopped working | |||
Failure | Low average sent FPS | |||
Failure | Incorrect captured resolution | |||
Failure | Could not analyze any video frame | |||
Failure | Camera delivering lots of black frames | |||
Failure | Camera delivering lots of frozen frames | |||
Camera | check resolution 480 | Success | Captured video using expected resolution | |
Success | Average FPS above threshold | |||
Failure | getUserMedia failed with error #error# | |||
Failure | No video track in returned stream | |||
Failure | Video track ended, camera stopped working | |||
Failure | Low average sent FPS | |||
Failure | Incorrect captured resolution | |||
Failure | Could not analyze any video frame | |||
Failure | Camera delivering lots of black frames | |||
Failure | Camera delivering lots of frozen frames | |||
Camera | check resolution 720 | Success | Captured video using expected resolution | |
Success | Average FPS above threshold | |||
Failure | getUserMedia failed with error #error# | |||
Failure | No video track in returned stream | |||
Failure | Video track ended, camera stopped working | |||
Failure | Low average sent FPS | |||
Faiiure | Incorrect captured resolution | |||
Failure | Could not analyze any video frame | |||
Failure | Camera delivering lots of black frames | |||
Failure | Camera delivering lots of frozen frames | |||
Camera | check supported resolutions | N/A | Success | Success Supported resolution #resolution# |
Failure | No video track in returned stream | |||
Failure | Video track ended, camera stopped working | |||
Network | udp enabled | TURN | Success | Supported resolution #resolution# |
Failure | No video track in returned stream | |||
Failure | Video track ended, camera stopped working | |||
Network | tcp enabled | TURN | Success | Gathered 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, it might not be setup/supported on the network | |||
Failure | Failed to gather IPv6 candidates, it might not be setup/supported on the network | |||
Connectivity | relay connectivity | TURN | Success | Data successfully transmitted between peers |
Failure | Invalid data transmitted | |||
Failure | Time out | |||
Connectivity | reflexive connectivity | TURN | Success | Data successfully transmitted between peers |
Failure | Invalid data transmitted | |||
Failure | Time out | |||
Connectivity | host connectivity | TURN | Success | Data successfully transmitted between peers |
Failure | Invalid data 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 bandwidth without a working camera | |||
Failure | getUserMedia failed with error #error# | |||
Failure | Frame rate mean is 0, cannot test bandwidth without a working camera | |||
Failure | Could not gather stats | |||
Failure | Only Firefox and Chrome getStats implementations are 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 error <error> | |||
Failure | Only Firefox and Chrome getStats() implementations are supported | |||
Signaling | Signaling Connectivity | Success | Token created successfully | |
Failure | Token creation failed due to error: #error# | |||
Failure | Room not joined due to error: #error# | |||
Success | Room joined successfully |
Get Bitrate Status of Client
Availability: Web SDK v1.9.8+
The EnxRtc.clientBitrate()
method provides bitrate status of the Client. It carries out 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.
Class: EnxRtc
Method: EnxRtc.clientBitrate(clientInfo)
Parameters:
clientInfo
– Optional. JSON object with Client preferences for the execution of test cases.region
– String. Region Id of ICE Server, e.g."IN", "SG", "US", "DE".
Default Region ID is “DE”.
Event Notifications:
client-bitrate-finished
– Notification sent when the API has completed the execution of the test case. This returns a JSON Object as the final result.client-bitrate-status
– Notification sent with the test results at the beginning and end of the test. This returns a JSON Object as the test result.
Request for diagnostics:
var clientInfo = { region: 'IN' }; let client = EnxRtc.clientBitrate(clientInfo); client.addEventListener("client-bitrate-status", function(response) { // handle info message from response.message }); client.addEventListener("client-bitrate-finished", function(response) { // handle json from response.message });
Response at the beginning and end of Test: 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" }
Final Response: client-bitrate-finished
{ "video": { "bitrate_bps": 2221949, "connection": "stable" }, "audio": { "bitrate_bps": 278067, "connection": "stable" } }
Test Result 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 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 | Frame Rate mean is 0, cannot test bandwidth without a working camera | |||
Failure | Only Firefox and Chrome getStats() implementations are supported | |||
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 error <error> | |||
Failure | Only Firefox and Chrome getStats() implementations are supported |
Note: Currently this API is not working for Firefox and safari browser.