How is Connection Quality determined?

Within LiveKit, connection quality is continuously monitored and reported to help you understand the health of participant connections in real-time. This article explains how connection quality is calculated and what factors influence the score.

Connection Quality Values

LiveKit defines connection quality in the protocol definition:

enum ConnectionQuality {
  POOR = 0;
  GOOD = 1;
  EXCELLENT = 2;
  LOST = 3;
}

Participants connected to a LiveKit room receive events from the server whenever a participant's connection quality changes. You can subscribe to these events to display connection indicators in your UI or trigger adaptive behavior.

How Quality is Calculated

The calculation for quality is made up of three main components:

1. Packet Loss

Packet loss is a primary indicator of connection health. Higher packet loss rates result in lower quality scores. The calculation measures the percentage of packets that fail to arrive at their destination.

2. Video Layers Status

For video tracks, the calculation checks whether all expected video layers (simulcast layers) are being successfully sent. If layers are missing or not being transmitted, this negatively impacts the quality score.

3. Bitrates

The actual bitrate achieved compared to the expected or requested bitrate factors into the quality calculation. Significant drops in bitrate indicate network constraints.

What's NOT Included

It's worth noting that jitter and RTT (round-trip time) are currently disabled in the calculatePacketScore function. While these metrics are commonly used in other WebRTC quality assessments, LiveKit's current implementation focuses on the three factors above.

Subscribing to Quality Changes

You can listen for connection quality changes in your client application:

room.on(RoomEvent.ConnectionQualityChanged, (quality, participant) => {
  console.log(`${participant.identity} quality changed to: ${quality}`);
  // quality is one of: ConnectionQuality.Excellent, ConnectionQuality.Good, ConnectionQuality.Poor
});

Key Takeaways

• Connection quality is reported as one of four values: POOR, GOOD, EXCELLENT, or LOST
• The score is calculated server-side using packet loss, video layer status, and bitrates
• Jitter and RTT are not currently factored into the calculation
• Subscribe to ConnectionQualityChanged events to react to quality changes in your application