Skip to main content

Custom UI - Connection Info

· 4 min read
Stefan Benicke

From now on you can include a connection quality indicator in your custom UI. This will give your users a quick feedback about their current audio / video quality.

Cover image

In its simplest form, you can use it as a traffic-light display for good / ok / bad connection. We also provide some more details and value, like bitrate, jitter, packet loss, and round-trip time.

You can read more about the data in the help center article.

Initialize Statistics

You have to listen for the statistics_ready event and this event includes the statistics interface with its important method onUpdate.

onUpdate is triggered roughly every 1s and provides an object with all values.

eyeson.onEvent(event => {
if (event.type === 'statistics_ready') {
event.statistics.onUpdate(showStatistics);
}
});

function showStatistics(stats) {
/*...*/
}

eyeson.start(/*...*/);

Statistics data

The onUpdate function is called with a statistics object containing the following data:

  • status can be "good", "ok", "bad", or even "no connection" (please use Status.GOOD etc.)
  • bitrateSend and bitrateRecv are audio+video bitrates either send or received. Values are in kbps.
  • jitter is the sender's jitter and it takes the worse value, either audio or video. Values are in s.
  • packetLoss is the sender's packet loss and it takes the worse value, either audio or video. Values are between 0 and 1.0.
  • roundTripTime is the sender's round-trip time and it takes the worse value, either audio or video. Values are in s.
  • nack is the sender's video negative-acknowledge count rate. Values are between 0 and 1.0.
caution

In some cases values are null. There are browsers where not all parameters are available.

info

All values are the average over the last 3 entries (roughly last 3 seconds) to avoid high value jumps.

Quality status

As the simplest approach you might want to show only the connection quality status as a traffic-light indicator.

The ConnectionStatistics interface provides a Status object with named keys for the stats.status value.

Currently it contains 4 named keys: GOOD, OK, BAD, and NO_CONNECTION.

import { ConnectionStatistics } from 'eyeson';

const { Status } = ConnectionStatistics;

const connectionInfo = {};
connectionInfo[Status.GOOD] = { title: 'Excellent', className: 'good' };
connectionInfo[Status.OK] = { title: 'Unstable', className: 'ok' };
connectionInfo[Status.BAD] = { title: 'Poor', className: 'bad' };
connectionInfo[Status.NO_CONNECTION] = { title: 'No connection', className: 'none' };

function showStatistics(stats) {
indicator.className = connectionInfo[stats.status].className;
indicator.textContent = connectionInfo[stats.status].title;
}

Full example

The following example will show all available data and update automatically.

import { ConnectionStatistics } from 'eyeson';

const { Status } = ConnectionStatistics;
const numberFormat = new Intl.NumberFormat('en', { maximumFractionDigits: 0 });
const percentFormat = new Intl.NumberFormat('en', { style: 'percent', maximumFractionDigits: 0 });

const connectionInfo = {};
connectionInfo[Status.GOOD] = { title: 'Excellent', className: 'good' };
connectionInfo[Status.OK] = { title: 'Unstable', className: 'ok' };
connectionInfo[Status.BAD] = { title: 'Poor', className: 'bad' };
connectionInfo[Status.NO_CONNECTION] = { title: 'No connection', className: 'none' };

const showStatistics = stats => {
statisticsIcon.className = connectionInfo[stats.status].className;
outputStatus.textContent = connectionInfo[stats.status].title;
outputBitrateSend.textContent = numberFormat.format(stats.bitrateSend) + ' kbps';
outputBitrateReceive.textContent = numberFormat.format(stats.bitrateRecv) + ' kbps';
if (stats.jitter !== null) {
outputJitter.textContent = numberFormat.format(stats.jitter * 1000) + ' ms';
}
if (stats.packetLoss !== null) {
outputPacketLoss.textContent = percentFormat.format(stats.packetLoss);
}
if (stats.roundTripTime !== null) {
outputRoundTripTime.textContent = numberFormat.format(stats.roundTripTime * 1000) + ' ms';
}
if (stats.nack !== null) {
outputNack.textContent = percentFormat.format(stats.nack);
}
};

eyeson.onEvent(event => {
if (event.type === 'statistics_ready') {
event.statistics.onUpdate(showStatistics);
}
});

eyeson.start(/*...*/);

More info

Whenever eyeson.destroy() is called and the session ends, the statistics instance will automatically shutdown. So the onUpdate event is not triggered anymore.