Scalability Guide for Large Participant Rooms

Overview

This guide explains how to optimize performance when hosting video rooms with 10+ participants by using a key feature:

Adaptive Subscriptions: Prioritizes audio/video streams based on who's speaking

These features help solve common challenges in large rooms, such as high bandwidth use and poor quality for users with network constraints.

note

This page uses the following asynchronous methods. Refer to their API reference for the errors each Promise may reject with, and handle these rejections appropriately based on your use case.

• enableAdaptiveSubscription()
• disableAdaptiveSubscription()

Common Challenges in Large Rooms

1. Ineffective Stream Prioritization

Problem: All streams receive equal treatment regardless of importance.

Impact:

• Users with limited bandwidth experience poor quality
• Audio quality suffers when competing with video for resources
• Important speakers may not be clearly heard or seen

Solution Features

Adaptive Subscriptions

This feature optimizes bandwidth by prioritizing active speakers and managing stream quality.

Key Benefits:

• Identifies and prioritizes dominant speakers
• Manages bandwidth constraints
• Keeps audio going when bandwidth is low
• Gives highest priority to pinned participants

How It Works:
Active speakers get priority. When a participant's bandwidth is low, VideoSDK pauses or lowers the quality of the other videos they receive. Pinned participants are kept at the highest priority.

Visual Illustration:

If a user experiences bandwidth constraints, Adaptive Subscriptions will pause the video streams in the following priority order:

1. Muted Participants
2. Least Dominant Speakers
3. Dominant Speakers

If you want to achieve pin/unpin functionality, you can refer to this documentation

Implementation Guide

Enabling Adaptive Subscriptions (BETA)

Turn on Adaptive Subscriptions with one call:

const { enableAdaptiveSubscription, disableAdaptiveSubscription } = useRoom();

// Enable adaptive subscriptions
enableAdaptiveSubscription();

// Disable adaptive subscriptions
disableAdaptiveSubscription();

Recommended Implementation:

// Enable on room join
const { join, participants, enableAdaptiveSubscription } = useRoom({
  // Callback for when the room is joined successfully
  onRoomJoined: () => {
    enableAdaptiveSubscription();
  },
});

Stream Pause/Resume Events

Stay informed when streams are paused or resumed with these event listeners:

useParticipant("participantId", {
  onStreamPaused: ({ kind, reason }) => {
    console.log(reason); // Possible values: "muted", "leastDominance"
  },
  onStreamResumed: ({ kind, reason }) => {
    console.log(reason); // Possible values: "adaptiveSubscriptionsDisabled", "networkStable"
  },
});

Pause Reasons:

• muted: The participant has turned off their audio.
• leastDominance: The participant hasn’t spoken much.

Resume Reasons:

• adaptiveSubscriptionsDisabled: The feature was disabled.
• networkStable: Network conditions have improved.

Developer Tip: Add a UI indicator to let users know when a stream is paused, like “Paused due to weak network.”

Best Practices

• Enable adaptive subscriptions at the start of every room
• Design your UI to display indicators when a stream is paused
• Pin important participants to ensure they receive the highest streaming priority