Thursday, 9 September, 2021 UTC
Summary
The reality when building and operating real-time video applications is that sometimes the device, software, and network conditions of your end users, variables seemingly outside your control, can negatively impact their perception of the quality of your video service. Thus, to help your customers have high-quality video experiences, it is important to take the necessary steps to ensure users are set up to have a successful first video call experience during onboarding or to be able to quickly diagnose end users' issues when they arise.
To help you with this, we are excited to announce the release of the Video Diagnostics Web App, an open source ReactJS application demonstrating how to test a participant’s ability to have a high-quality video call with the Twilio platform - now available in Public Beta for WebRTC Go, P2P, and Group room developers. It can be used as part of onboarding or as a troubleshooting page.
The application can be deployed in minutes, is built using Twilio's RTC Diagnostics SDK and Twilio's JS Video SDK, and is designed so that each component can be easily themed, altered, and embedded into your application. It’s free to deploy and free to use.
Diagnosing the issue When your users reach out claiming they had a poor video experience, diagnosing what happened and helping these users rectify issues can be extremely time-consuming. Minimal device and network information about the end user, long wait times to hear back, and lack of resolution can lead to frustrations for all parties involved. Furthermore, it’s essential to be able to quickly identify whether the problem is entirely on the end user’s side or if there could be an issue with your application that may be affecting other users.
Typically, issues on the end user’s side fit into one or more of the following categories:
- Device and software setup - Sometimes end users don’t provide access to the camera or microphone or are using an unsupported browser.
- Connectivity - Sometimes end users are behind firewalls that block connection to the Twilio Servers altogether.
- Network performance - Sometimes limitations of the end users’ network performance prohibits the ability to have high-quality video calls.
The Video Diagnostics Application is an open source ReactJS application that tests participants’ device and software setup, connectivity with the Twilio Cloud, and network performance.
The application has a number of major benefits, including:
- Stepwise tests to diagnose issues due to the local environment of a participant
- Provides a recommended course of action when tests fail
- Approachable UX for non-technical end users with access to network-related statistics for those who need it
- Easy to download JSON-formatted test report for simplified sharing and integration into support workflows
- Showcases how to utilize the RTC Diagnostics SDK and call-readiness features within the JS Video SDK
- Easily customizable and ready for self hosting or embedding into other web applications
- Free to deploy and free to use
What does it test?
The screenshot in the previous section represents the results of the happy path, but let’s run through the tests as a user may experience them.
Let’s get started. The first step is checking access and permissions to the camera and microphone. In this case, we will have to update our browser settings to allow access to the resources.
Next, we have a series of interactive camera, microphone, and speaker tests, and we’ll also include the test to ensure we are using a supported operating system and browser. The audio test allows users to record and playback media to ensure there are no issues with the hardware, such as the notorious “robotic voice”. It will also check the input and output audio levels using
testInputDevice() and testOutputDevice(), which power the volume indicator, and notify the user if we don’t detect any audio. The gif below shows shows these tests:No problems there. Next is checking connectivity with the Twilio Cloud.
While we were going through the above tests, we were actually already running the Preflight API in the background. The Preflight API was recently released in public beta and works by connecting two peer connections using Twilio's Signaling and TURN servers. It then publishes synthetic audio and video tracks from one connection and ensures that the other connection receives media on those tracks. After successfully verifying connectivity, it generates a report with statistics about the connection. Here is an example of how it can be used:
const { runPreflight } = require('twilio-video'); const token = getAccessToken(); const preflightTest = runPreflight(token); preflightTest.on('progress', (progress: string) => { console.log('preflight progress:', progress); }); preflightTest.on('failed', (error: Error) => { console.error('preflight error:', error); deferred.reject && deferred.reject(error); }); preflightTest.on('completed', (report: PreflightTestReport) => { console.log("Test completed in " + report.testTiming.duration + " milliseconds."); console.log(" It took " + report.networkTiming.connect?.duration + " milliseconds to connect"); console.log(" It took " + report.networkTiming.media?.duration + " milliseconds to receive media"); }); Okay, moving forward. The connectivity test uses the
progress events from the above API to ensure that the end user can communicate with our Signaling and TURN servers and uses the Twilio Status API to confirm that the relevant Twilio services are up and running. This connectivity test can be seen below:Nice, we're all set as far as connectivity to the Twilio Cloud.
The last test provides an overall expected call quality and the associated network statistics. The expected quality is determined using the round trip time, jitter, and packet loss stats from the PreflightTestReport and the bitrate observed from
testMediaConnectionBitrate(). You may want to customize the thresholds based on your use-case and/or your application configuration.For example purposes, we will use the tool Throttle to simulate higher-than-desired network latency (as measured by round trip time) and see how this impacts our expected call quality. From there, we will see if we can do anything to improve our performance (hint: VPNs can introduce latency) and then we will get our final results. Check it out in action below:
And that concludes our diagnostics tests!
In this particular case, we had to update our browser permissions and work to minimize our round trip time. By providing end users simple recommendations, such as disconnecting from their VPN during the video call (obviously, only if they are open to it), you can potentially improve conditions just enough to help them have a quality call.
Making the most of the JSON report
The application also provides a downloadable JSON representation of the report for easy sharing between an end user and someone from your support team or a network administrator. The JSON report includes the test results, along with additional device and network information. Some of the useful stats are as follows:
- Input and output audio levels observed and the captured video resolution
- ICE candidate and selected ICE candidate stats
- Network timing measurements, such as time to connect and time to receive media
We hope that you can utilize and customize the JSON report to fit your unique workflows, whether that be attaching the report when a user submits a support ticket or crafting auto-generated responses based on the results.
Try it out now You can get started with the Video Diagnostics ReactJS application by visiting the README, or deploy the application using the following 4 steps:
# Clone the web application $ git clone https://github.com/twilio/twilio-video-diagnostics-react-app.git # Navigate to application directory $ cd twilio-video-diagnostics-react-app # Install dependencies $ npm install # Deploy to Twilio Serverless $ npm run serverless:deploy ... App deployed to: https://rtc-diagnostics-video-yiwwvd2q-6118-dev.twil.io/ That’s it! You are now up and running with your own diagnostics application. We designed this app to serve as a reference or launching off point as you look to build tooling to reduce your support effort and retain customers. If you have questions or ideas on how we can improve this experience, we welcome any feedback!
Sean Coleman is a Product Manager on the Programmable Video team, focused on Developer Experience and tooling. He can be reached at scoleman [at] twilio.com.