This is a work-in-progress VoIP test utility for Matrix.

There is the opportunity to build on it programatically, but the project also includes a web frontend that runs in-browser.

It tests your homeserver's STUN/TURN servers and generates a report and score.

mxvoiptestd (test daemon)

How it's used

The user accesses the test utility page in their web browser. (Their web browser must support WebRTC.)

The user logs in to an account on their homeserver and their web browser requests the homeserver's ICE (STUN/TURN) server details.

The browser contacts the TURN servers and gathers ICE candidates. Once this is done, the browser offers the candidates to the mxvoiptestd server and waits for an answer.

mxvoiptestd begins gathering its own candidates and answers.

The browser and the server connect to each other and exchange a greeting over an RTCDataChannel.

This process is repeated for every TURN URI and in both IPv4 and IPv6 to build up a report.

Current scoring system

Overall scores for IPv4 and IPv6 support:

• Fail: No STUN or TURN support whatsoever.
• Poor: Either only STUN or only TURN.
• Good: STUN and TURN supported over at least one protocol.
• Great: STUN and TURN over both TCP and UDP, both secure and insecure.
• Excellent: In addition to great, there is a secure TURN service over TCP port 443 (which looks like HTTPS traffic and will likely get through more firewalls).

Note: The requirement to have insecure transports to get a 'Great' score is likely to go away.

Scores for individual TURN URIs:

• Fail: Neither STUN candidates nor (working) TURN candidates found.
• Poor: Either only STUN candidates found, or only (working) TURN candidates found.
• Excellent: Both STUN candidates and TURN candidates found — and the TURN candidate was tested to work.

Note: Currently, only unencrypted UDP TURN URIs seem to generate STUN URIs and thus other TURN URIs fail to achieve Excellent — even on reputable servers. This is being investigated and may be a bug in the tester.

Warning

This utility is not yet finished and is not known to behave or report correctly; please see the list of issues for points of needed development and investigation.

Notably, there is doubt about the grades assigned by this tool, so there is not necessarily anything wrong if you receive poor and only good scores on some aspects.

Thoughts on further directions

The browser WebRTC API is quite restrictive; e.g. it does not allow changing the candidates in use (even by attempting to alter the SDP).

We also can't access any of the information needed to deeply diagnose STUN and TURN errors.

Ultimately, I would loved to have taken this further but I think that needs to go out of the browser.

(With the user's consent, the TURN credentials could be shared with the server to do this testing and have the results show up in the report.)

Notes on deployment

Install into a venv and run with hypercorn:

VOIPTEST_CONFIG=/path/to/config.toml hypercorn mxvoiptestd.webapi:app --log-level info --error-logfile -

Note that a configuration file is optional — but you will need one if you need to use a TURN server for your mxvoiptestd (such as if mxvoiptestd is behind NAT).

Development instructions

Set up

You may need some dependencies which can be installed on Debian and Ubuntu with:

sudo apt install libavdevice-dev libavfilter-dev libopus-dev libvpx-dev pkg-config

These dependencies may be required for aiortc, which has instructions for other operating systems here.

(In some cases, binary releases are available for aiortc so you may not need to install these manually.)

Create a venv for this project and pip install -e /path/to/mxvoiptestd whilst having the venv activated.

Compiling SCSS

scss scss/tester.scss -t compressed > mxvoiptestd/static/tester.css

Currently, to avoid hassle, the resultant tester.css should be committed in this repository whenever tester.scss is updated.