Files of check-in [d26d71cd86] in directory wiki_references/2019/software/mail_and_messaging/matrix_org/src_from_GitHub/the_repository_clones/voip-tester [history]
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
mxvoiptestd begins gathering its own candidates and answers.
The browser and the server connect to each other and exchange a greeting over an
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.
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
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).
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.
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.