Precall network test for applications using the Vonage Video API platform.
npm install @vonage/video-client-network-test
This Node module lets you check network connectivity to resources and services required
to use Vonage Video API. Run this on a web client to get the following information:
* Whether the client will be able to succeed in connecting to a Vonage Video API session
* MOS estimates for the audio and video quality
the client will experience
* A recommended frame rate and resolution to use for publishing to a session
For a sample that uses this module, see the Vonage Video API Pre-call Test
tool.
First, install the package:
``
$ npm install @vonage/video-client-network-test
Now load the Vonage Video API Network Test in your project. The module exports two objects:
* NetworkTest -- The class containing methods for testing your Vonage Video API connectivity and quality.
This is the default export.
* ErrorNames -- An object enumerating error name values
Using CommonJS:
`javascript`
const NetworkTest = require('@vonage/video-client-network-test').default;
const ErrorNames = require('@vonage/video-client-network-test').ErrorNames;
... or ES6 ...
`javascript`
import NetworkTest, { ErrorNames } from '@vonage/video-client-network-test';
Load the Vonage Video web client SDK library.
Instantiate an instance of the test object, passing in the Vonage Video web client SDK OT object and
a configuration object. The configuration object contains an application ID for your app's
Vonage Video web client SDK project, a session ID for a test session, and a token for that session:
`javascript`
const videoNetworkTest = new NetworkTest(OT, {
applicationId: '123456', // Add the application ID for your Vonage Video API application here.
sessionId: '1_MX40NzIwMzJ-fjE1MDElGQkJJfn4', // Add a test session ID for that project
token: 'eyJhbGciOiJSUzI1...' // Add a token for that session here
});
Use the Vonage Video API server SDKs to generate a
unique session ID for each client. This session ID is used for the network test, and it must
be different than the session ID used for communication in the app. The test session must be
a routed session -- one that uses the Vonage Video API Media
Router.
Also generate a test token that has publish privileges.
Then run the test methods:
`javascript`
videoNetworkTest.testConnectivity().then((results) => {
console.log('Vonage Video API connectivity test results', results);
videoNetworkTest.testQuality(function updateCallback(stats) {
console.log('intermediate testQuality stats', stats);
}).then((results) => {
// This function is called when the quality test is completed.
console.log('Vonage Video API quality results', results);
let publisherSettings = {};
if (results.video.reason) {
console.log('Video not supported:', results.video.reason);
publisherSettings.videoSource = null; // audio-only
} else {
publisherSettings.frameRate = results.video.recommendedFrameRate;
publisherSettings.resolution = results.video.recommendedResolution;
}
if (!results.audio.supported) {
console.log('Audio not supported:', results.audio.reason);
publisherSettings.audioSource = null;
// video-only, but you probably don't want this -- notify the user?
}
if (!publisherSettings.videoSource && !publisherSettings.audioSource) {
// Do not publish. Notify the user.
} else {
// Publish to the "real" session, using the publisherSettings object.
}
}).catch((error) => {
console.log('Vonage Video API quality test error', error);
});
}).catch(function(error) {
console.log('Vonage Video API connectivity test error', error);
});
You can also run the tests in audio-only mode by passing in an options objectaudioOnly
with set to true into the constructor:
`javascript
const sessionInfo = {
applicationId: '123456', // Add the application ID for your Vonage Video API application here.
sessionId: '1_MX40NzIwMzJ-fjE1MDElGQkJJfn4', // Add a test session ID for that project
token: 'eyJhbGciOiJSUzI1...' // Add a token for that session here
}
const options = {audioOnly: true};
const videoNetworkTest = new NetworkTest(OT, sessionInfo, options);
videoNetworkTest.testQuality(function updateCallback(stats) {
const currentStats = stats[stats.length - 1];
console.log('testQuality stats', currentStats);
}).then((results) => {
console.log('Vonage Video API quality results', results);
}).catch((error) => {
console.log('Vonage Video API quality test error', error);
});
`
This code uses Promises returned by the OTNetworkTest.testConnectivity()
and methods. Alternatively, you can pass completion
handler functions into each of these methods.
See the following section for details on using the test results.
See the /sample subdirectory (and the /sample/README.md file) for a sample app.
The OTNetworkTest.testConnectivity() method is supported in Chrome, Firefox, Safari,
Opera, and Edge.
The OTNetworkTest.testQuality() method is supported in Chrome, Safari,
Opera, and Chromium-based versions of Edge (versions 79+).
It is not supported in Firefox and non-Chromium-based versions of Edge.
Update: Firefox has been removed from the list of supported browsers for the testQuality feature since version 2.6.0 due to missing some important statistics. This could lead to inaccurate results.
The OTNetworkTest NPM module includes three public methods:
* The OTNetworkTest() constructor method
* The OTNetworkTest.testConnectivity() method
* The OTNetworkTest.testQuality() method
Note: Some API changes were introduced in v2. See the
[releases page][releases-page] for details.
The OTNetworkTest() constructor includes the following parameters:
* ot -- A reference to the Vonage Video web client SDK OT object. You must load Vonage Video web client SDK into theOT
web page and pass the Vonage Video web client SDK into the OTNetworkTest() constructor.
Note that you may load Vonage Video web client SDK from the Vonage Video API server
(https://unpkg.com/@vonage/client-sdk-video@2/dist/js/opentok.js) or via NPM
(https://www.npmjs.com/package/@vonage/server-sdk).
Passing the OT object into the OTNetworkTest() constructor ensures that the tests will
use the same version of Vonage Video API and the same Vonage Video API environment that will be used by the
main Vonage Video API session in your application.
* sessionInfo -- An object containing the following:
* applicationId -- The application ID corresponding to the Vonage Video API application the app uses.
* sessionId -- A test session ID. This must be an ID for a different session than
the one that your application will be used for communication. Generate a unique
session ID for each client. This session ID is used for the network test, and it
must be different than the session ID used for communication in the app.
The test session must be a routed session -- one that uses the Vonage Video API Media
Router.
To test connectivity
in a specific region, specify a location hint when creating the test
session.
* token -- A token corresponding to the test session. The role of the token must bepublisher
either or moderator.
The sessionInfo parameter is required.
* options --The options parameter is an object containing the following properties,
each of which are optional:
* audioOnly (Boolean) -- Set this property to true to run audio-only tests.
When this option is set to false (the default), the quality test will try to run
an audio-video quality test (using both the camera and microphone). If there is no
camera available, or if the results of the audio-video test do not support adequate
audio quality, the test continues in audio-only mode.
Setting the audioOnly to true will reduce the time of the quality test on systems that
have both a microphone and camera attached (since the audio-only test is shorter than the audio-video test).
* timeout (Number) -- Set this property to the maximum duration of the testQuality()
test, in milliseconds. Set this to a value greater than 5000 (5 seconds) but less than
30000 (30 seconds). (Values outside of this range are ignored.) If you do not set this value,
the test will run for approximately 30 seconds for an audio-video test or for 10 seconds for an audio-only test.
The timeout period begins when the quality test starts publishing (after the user grants
access to the camera and microphone).
Setting a lower timeout duration may result in less accurate results, including MOS ratings.
* audioSource (String) -- The ID of the audio input device (such as a microphone)OT.getDevices()
to be used by the test publisher. You can obtain a list of available devices,
including audio input devices, by calling the method.
You may want to set this to have the Vonage Video API Network Test use the same device that
will be used in the real Vonage Video API session. This way, the test prompts the end user
to grant permission to the correct device. Note that changing the audio device may not
influence the quality test score.
* videoSource (String) -- The ID of the video input device (such as a camera)OT.getDevices()
to be used by the test publisher. You can obtain a list of available devices,
including audio input devices, by calling the method.
You may want to set this to have the Vonage Video API Network Test use the same device that
will be used in the real Vonage Video API session. This way, the test prompts the end user
to grant permission to the correct device. Note that changing the video device may not
influence the quality test score.
* initSessionOptions (Object) -- An object that includes optional options ipWhitelist
for initializing the session
(Session Options).
This object includes the following properties:
* (Boolean) -- Set this to true if IP white listing iceConfig
is enabled for your project. The default value is false.
* (Object) -- This feature is part of the configurable TURN add-on feature.
* proxyServerUrl (String) -- (Optional) Set this to the proxy server URL OT.setProxyUrl()
you use in the Vonage Video API client SDKs (for example, when calling
in the Vonage Video web client SDK). For more information, please check the
IP Proxy Documentation.
* scalableVideo (Boolean) -- (Optional) Whether to usetrue
scalable video
() or not (false, the default). Disabling scalable video
was added in Vonage Video web client SDK version 2.24.7.
* fullHd (Boolean) -- (Optional) Allows publishing with a resolution of 1920x1080 (1080p).OTNetworkTest.testConnectivity()
If the camera does not support 1920x1080 resolution, the methodUNSUPPORTED_RESOLUTION_ERROR
is rejected with an error. We highly recommend set scalableVideo setting to true when testing full HD resolution. Without scalableVideo, the client may not reach full HD resolution during the test period.
The options parameter is optional.
The constructor throws an Error object with a message property and a name property. Thename
message property describes the error. You should check the property to determine thename
type of error. The property will be set to one of the values defined as properties ofErrorNames
the object (see ErrorNames). For example:
`javascript`
try {
const videoNetworkTest = new NetworkTest(OT, sessionInfo);
} catch (error) {
switch (error.name) {
case ErrorNames.MISSING_OPENTOK_INSTANCE:
console.error('Missing OT instance in constructor.');
break;
case ErrorNames.INCOMPLETE_SESSON_CREDENTIALS:
case ErrorNames.MISSING_SESSON_CREDENTIALS:
case ErrorNames.INVALID_SESSON_CREDENTIALS:
console.error('Missing or invalid Vonage Video API session credentials.');
break;
default:
console.error('Unknown error .');
}
}
This method checks to see if the client can connect to Vonage Video API servers. The method returns
a Promise that is resolved when the connectivity check completes. The promise is resolved
with a results object that has the following two properties:
* success (Boolean) -- true if connectivity to Vonage Video API servers succeeded; false if
any connectivity test failed.
* failedTests (Array) -- If connectivity failed, this array contains an object for eachtype
failure type. The object has two properties, and errors:
* type -- A sting defining the failure type. It will be set to one of the following values:
* 'api' -- The test could not connect to the Vonage Video API server. Connection to this
server is required to connect to a Vonage Video API session.
* 'messaging' -- The test could not establish a connection to the Vonage Video API messaging WebSocket.OTNetworkTest()
This connection is required to connect to an Vonage Video API session. In addition to other causes
for WebSocket connectivity failures, this failure type will occur if you pass an invalid
Vonage Video API application ID, session ID, or token into the constructor.
* 'media' -- The test could not connect to the Vonage Video API Media Router. If your app uses
a routed session, it will not succeed in using Vonage Video API. However, if your app uses
a relayed session, the client may still succeed in using the Vonage Video API session, although
it may fail if the relayed session requires use of a TURN server.
* 'logging' -- The test could not connect to the Vonage Video API logging server. The Vonage Video web client SDK
library periodically logs data (such as video and audio quality) to this server. The client
can still connect to a Vonage Video API session, however Vonage will not collect data that may help
you debug issues with the session, using tools like Vonage Video API
Inspector.
* error -- An object defining the reason for the type of failure. This object includesmessage
a property and a name property. The message property describes the error.name
You should check the property to determine the type of error. The name propertyErrorNames
will be set to one of the values defined as properties of the
object (see ErrorNames):
For example:
`javascript`
videoNetworkTest.testConnectivity(function(results) {
results.failedTests && results.failedTests.forEach(result) => {
switch (failedTest.error.name) {
case ErrorNames.FAILED_TO_OBTAIN_MEDIA_DEVICES:
// Display UI message about granting access to the microphone and camera
break;
case ErrorNames.NO_AUDIO_CAPTURE_DEVICES:
case ErrorNames.NO_VIDEO_CAPTURE_DEVICES:
// Display UI message about no available camera or microphone
break;
// Handle other errors, as needed
default:
console.error('Unknown error .');
}
}
});
If all connectivity tests succeed, the failedTests property is undefined.
This function runs a test publisher (using the application ID, session ID and token provided in the constructor). Based on the measured video bitrate, audio bitrate, and the audio packet loss for
the published stream, it provides the following results:
* Whether audio and video are supported and a reason why they aren't supported (if they aren't).
* The MOS estimate (from 0 - 4.5) for the the audio and video published by the client.
* Statistics for the test, including bitrate and packet loss ratio (for both audio and video),
as well as the video packet loss ratio.
* The recommended supported publisher settings. These settings include the recommended video
frame rate and resolution for a stream published by the client. Or, if the stats do not support
video, the results indicate whether an audio-only published is recommended or not, based on the
measured audio bitrate and packet loss.
This method takes one parameter: updateCallback. The method returns a Promise.
#### updateCallback
The updateCallback function is called periodically during the test (at a 1-second test interval).
The object passed into the updateCallback function includes statistics about the audio and
video in the test stream. The object has the following data:
`
{
audio: {
timestamp: 1509747314,
bytesSent:534349,// The total number of video bytes received, cumulative
bytesReceived: 434349, // The total number of audio bytes received, cumulative
packetsReceived: 24234, // The total number of audio packets received, cumulative
packetsLost: 0 // The total number of audio packets lost, cumulative
},
video: {
timestamp: 1509747314,
bytesReceived: 434349, // The total number of video bytes received, cumulative
bytesSent:434349, // The total number of video bytes sent
frameRate: 15, // The video frame rate
packetsReceived: 24234, // The total number of video packets received, cumulative
packetsLost: 0 // The total number of video packets lost, cumulative
},
timestamp: 1512679143897, // The timestamp of the sample
phase: 'audio-video' // Either 'audio-video' or 'audio-only'
}
The phase property is set to 'audio-video' during the initial audio-video test. If a
secondary audio-only test is required (because audio quality was not acceptable during the
audio-video test), the property is set to 'audio-only'.
Pass in a null value if you do not want to register an updateCallback function.
Update: We advise using 'bytesSent' to provide a more accurate result, especially if scalable video is enabled for the application ID
#### Promise returned
The Promise returned by the OTNetworkTest.testQuality() method is resolved whenresults
the connectivity check completes. The promise is resolved with a object that has the
following properties:
* video (Object) -- Contains the following properties:
* supported (Boolean) -- Whether the results indicate that video is supported.
* recommendedFrameRate (Number) -- The recommended video frame rate. However, ifnull
video is unsupported, this is set to . If the the test ran in audio-only mode
(for example, because no camera was found), this property is undefined.
* recommendedResolution (String) -- The recommended video resolution. This will be'1280x720'
set to , '640x480', or '320x240'. However, if video is unsupported,null
this is set to . If the the test ran in audio-only mode (for example, because
no camera was found), this property is undefined.
* reason (String) -- A string describing the reason for an unsupported video recommendation.'No camera was found.'
For example,
* (String) -- Indicates the reason behind'cpu'
the highest resolution tested failing. It can have values: for CPU overload, 'bandwidth' for insufficient network bandwidth, or value is null if there is no limitation.
* bitrate (Number) -- The average number of video bits per second during the last
five seconds of the test. If the the test ran in audio-only mode (for example, because
no camera was found), this property is undefined.
* frameRate (Number) -- The average number of frames per second during the last five secondsrecommendedFrameRate
of the test. Note that this is different than the . The frameRate
value is the actual frame rate observed during the test, and the
is the recommended frame rate. If the the test ran in audio-only mode (for example,
because no camera was found), this property is undefined.
* packetLossRatio (Number) -- The audio packet loss ratio during the last five seconds
of the test. If the the test ran in audio-only mode (for example, because no camera was
found), this property is undefined.
* mos (Number) -- The MOS estimate for the test video quality. This will be in a range from
1 to 4.5. See MOS estimates below for more information.
* audio (Object) -- Contains the following properties:
* supported (Boolean) -- Whether audio will be supported (true) or not (false).
* reason (String) -- A string describing the reason for an unsupported audio recommendation.'No microphone was found.'
For example,
* bitrate (Number) -- The average number of audio bits per second during the last five seconds
of the test.
* packetLossRatio (Number) -- The video packet loss ratio during the last five seconds
of the test.
* mos (Number) -- The MOS estimate for the test audio quality. This will be in a range from
1 to 4.5. See MOS estimates below for more information.
results is undefined if there was an error in running the tests (and the error parameter
is unset).
Important: v1 included a results.mos property (an overall MOS rating for the test). Thisresults.audio.mos
was removed in v2 and replaced with and results.video.mos properties.
The results, including the MOS estimates and the recommended video resolution and frame rate are
subjective. You can adjust the values used in the source code, or you can use the data passed into
the updateCallback() function and apply your own quality analysis algorithm.
The Promise returned by the OTNetworkTest.testQuality() method is rejected when the connectivityerror
check encounters an error. The promise is reject with an object that has two properties:message
a property and a name property. The message property describes the error.name
You should check the property to determine the type of error. The name propertyErrorNames
will be set to one of the values defined as properties of the object
(see Error.name values).
`javascript`
videoNetworkTest.testQuality(null, function updateCallback() {
// process intermediate results
}).then((results) => {
// Display UI based on results
}).catch((error) => {
switch (error.name) {
case ErrorNames.UNSUPPORTED_BROWSER:
// Display UI message about unsupported browser
break;
case ErrorNames.CONNECT_TO_SESSION_NETWORK_ERROR:
// Display UI message about network error
break;
case ErrorNames.FAILED_TO_OBTAIN_MEDIA_DEVICES:
// Display UI message about granting access to the microphone and camera
break;
case ErrorNames.NO_AUDIO_CAPTURE_DEVICES:
case ErrorNames.NO_VIDEO_CAPTURE_DEVICES:
// Display UI message about no available camera or microphone
break;
default:
console.error('Unknown error .');
}
});
Stops the testConnectivity() test if it is running. The test will not stop until it has beenstop()
running for at least 5 seconds (after the user has granted access to the camera and microphone).
While you can call prior to this, results will not be returned until the 5-second mark.
The ErrorNames object includes properties that enumerate values used in the
name property of OTNetworkTest error objects. You should check the name property of
an error object (against the values defined in ErrorNames) to determine the type of error.
#### Errors thrown by the OTNetworkTest() constructor
| Error.name property set
to this property of
ErrorNames ... | Description |
| ------------------------------------------------------------------ | ----------- |
| MISSING_OPENTOK_INSTANCE | An instance of OT, the Vonage Video web client SDK, was not passed into the constructor. |INCOMPLETE_SESSON_CREDENTIALS
| | The sessionInfo object passed into the constructor did not include an applicationId, sessionId, or token object. |MISSING_SESSON_CREDENTIALS
| | No sessionInfo object was passed into the constructor. |
#### testConnectivity() errors
The testConnectivity() returns a JavaScript promise that succeeds with a results object.results
The object contains a failedTests array, and each element of this array (if there areerror
any elements) has an property, which is error object has a name property set to one of
the following:
| Error.name property set to this property
of ErrorNames ... | Description |
| -------------------------------------------------------------- | ----------- |
| API_CONNECTIVITY_ERROR | The test failed to connect to Vonage Video API Server. | CONNECT_TO_SESSION_ERROR
| | The test failed to connect to the test Vonage Video API session due to a network error. | CONNECT_TO_SESSION_TOKEN_ERROR
| | The test failed to connect to the test Vonage Video API session due to an invalid token. | CONNECT_TO_SESSION_ID_ERROR
| | The test failed to connect to the test Vonage Video API session due to an invalid session ID. | CONNECT_TO_SESSION_NETWORK_ERROR
| | The test failed to connect to the test Vonage Video API session due to a network error. | FAILED_TO_OBTAIN_MEDIA_DEVICES
| | The test failed to obtain media devices (a camera or microphone). | NO_AUDIO_CAPTURE_DEVICES
| | The browser cannot access a microphone. | NO_VIDEO_CAPTURE_DEVICES
| | The browser cannot access a camera. | PUBLISH_TO_SESSION_ERROR
| | Encountered an unknown error while attempting to publish to a session. | FAILED_MESSAGING_SERVER_TEST
| | The test failed to connect to media server due to messaging server connection failure. | FAILED_TO_CREATE_LOCAL_PUBLISHER
| | The test failed to create a local publisher object. | PUBLISH_TO_SESSION_NOT_CONNECTED
| | The test failed to publish to the test session because the client was not connected to the session. | PUBLISH_TO_SESSION_PERMISSION_OR_TIMEOUT_ERROR
| | The test failed to publish to the test session due a permissions error or timeout. | PUBLISH_TO_SESSION_NETWORK_ERROR
| | The test failed to publish to the test session due a network error. | SUBSCRIBE_TO_SESSION_ERROR
| | The test encountered an unknown error while attempting to subscribe to a test stream. | LOGGING_SERVER_CONNECTION_ERROR
| | The test failed to connect to the Vonage Video API logging server. |
#### testQuality() errors
If the promised returned by the testQuality() is rejected, the error passed into the .catch()
method has a property set to one of the following:
| Error.name property set to this
property of ErrorNames ... | Description |
| -------------------------------------------------------------- | ----------- |
| INVALID_ON_UPDATE_CALLBACK | The updateCallback parameter is invalid. It must be a function that accepts a single parameter. |UNSUPPORTED_BROWSER
| | The test is running on an unsupported browser (see Supported browsers). | CONNECT_TO_SESSION_ERROR
| | The test failed to connect to the test Vonage Video API session due to a network error. | CONNECT_TO_SESSION_TOKEN_ERROR
| | The test failed to connect to the test Vonage Video API session due to an invalid token. | CONNECT_TO_SESSION_ID_ERROR
| | The test failed to connect to the test Vonage Video API session due to an invalid session ID. | CONNECT_TO_SESSION_NETWORK_ERROR
| | The test failed to connect to the test Vonage Video API session due to a network error. | FAILED_TO_OBTAIN_MEDIA_DEVICES
| | The test failed to obtain media devices (a camera or microphone). | NO_AUDIO_CAPTURE_DEVICES
| | The browser cannot access a microphone. | NO_VIDEO_CAPTURE_DEVICES
| | The browser cannot access a camera. | PUBLISH_TO_SESSION_ERROR
| | The test encountered an unknown error while attempting to publish to a session. | INIT_PUBLISHER_ERROR
| | The test failed to initialize a publisher. | PUBLISH_TO_SESSION_NOT_CONNECTED
| | The test failed to publish to the test session because the client was not connected to the session. | PUBLISH_TO_SESSION_PERMISSION_OR_TIMEOUT_ERROR
| | The test failed to publish to the test session due a permissions error or timeout. | SUBSCRIBE_TO_SESSION_ERROR
| | The test encountered an unknown error while attempting to subscribe to a test stream. | SUBSCRIBER_GET_STATS_ERROR
| | The test failed to get audio and video statistics for the test stream. |
#### Errors thrown by the OTNetworkTest.checkCameraSupport() method
| Error.name property set
to this property of
ErrorNames ... | Description |
| ------------------------------------------------------------------ | ----------------- |
| PERMISSION_DENIED_ERROR | The user denied access to the camera. |UNSUPPORTED_RESOLUTION_ERROR
| | The camera does not support the requested resolution. |
The testQuality() results include MOS estimates for video (if supported) and audio (if supported).
A MOS estimate is a rating of audio or video quality. In subjective scoring, a user is asked
to rate quality from 1 (bad) to 5 (excellent). This module uses an objective test, calculating
the MOS value based on bitrate, packet loss ratio, and (for video) resolution. For example,
the audio MOS calculation is based on the [ITU G.107 specification][itu-g107]. These algorithms
limit the range of scores from 1.0 to 4.5.
| MOS value | Meaning |
| ---------- | --------- |
| 3.8 - 4.5 | Excellent |
| 3.1 - 3.79 | Good |
| 2.4 - 3.09 | Fair |
| 1.7 - 2.39 | Poor |
| 1.0 - 1.69 | Bad |
Note: The audio MOS estimate is less accurate when using Vonage Video web client SDK version 2.17.5 or lower
or on Chrome version 57 or lower, because the Vonage Video API Network Test cannot access the round-trip time
for audio, which is factored into the MOS calculation.
To build the module:
`bash``
$ npm install
$ npm run build
See the /sample subdirectory (and the /sample/README.md file) for a sample app.
[itu-g107]: https://www.itu.int/rec/dologin_pub.asp?lang=s&id=T-REC-G.107-201402-S!!PDF-E
[releases-page]: https://github.com/vonage/vonage-video-js-api-network-test/releases