Managing Video Quality During Network Congestion

LiveKit provides automatic video quality management during network congestion to help maintain session stability and audio quality. When enabled, the system will automatically pause video streams during periods of significant network congestion while maintaining audio communication.

Enabling the feature

In your project settings, enable the Allow pausing videos when subscribers are congested option. When enabled, LiveKit will automatically manage video streams during network congestion.

How it works

When network congestion is detected:

• Video streams will automatically pause
• Audio streams continue unaffected
• Video will automatically resume when network conditions improve
• On the client, the camera indicator will remain active as the publisher's camera is still enabled

Server signaling

The server sends a stream_state_update signal to the client when pausing or resuming video. This event indicates which participant and track were affected along with the current state (Paused or Active).

Customizing the user experience

You can implement custom UI feedback using the TrackStreamStateChanged event. This event fires when a remote participant's track state changes, with two possible states:

• Paused — When the server pauses the track due to congestion
• Active — When the stream initially starts or resumes after congestion

JavaScript example

import { RoomEvent, Track, StreamState } from 'livekit-client';

room.on(RoomEvent.TrackStreamStateChanged, (publication, streamState, participant) => {
  if (publication.kind === Track.Kind.Video) {
    if (streamState === StreamState.Paused) {
      // Video has been paused due to network congestion
      showPausedIndicator(participant.identity);
    } else if (streamState === StreamState.Active) {
      // Video has resumed
      hidePausedIndicator(participant.identity);
    }
  }
});

UI implementation suggestions

Consider implementing one of these common UI patterns to indicate paused video:

The exact UI implementation is up to your application. Consider your users' needs when choosing how to indicate paused video states.