Welcome to the new Mux Docs.
The old version is still available here

Controlling participant subscription behavior

In this guide, you will learn about the different subscription modes in the Spaces SDKs and how to set them for the session.

In this guide:

Using automatic subscriptions

Subscribe to an actively managed list of up to 20 participants.

Using manual subscriptions

Use this mode for programmatic control over which participants you subscribe to.

Spaces SDKs offer an automatic mode and a manual mode for subscribing to participants. The SDKs only receive media from subscribed participants. By default, the SDKs operate under the automatic mode as it covers the majority of use cases.

Using automatic subscriptions

The automatic subscription mode works by subscribing to a maximum of 20 participants which have the highest priority server-side. For example, recently speaking participants have higher priority than non-speaking participants, and you will automatically be subscribed to such participants if you're unsubscribed. Should you need more manual control, take a look at Using manual subscriptions.

The SDKs use the automatic subscription mode by default, so no configuration is required. Developers have the option to set their own automatic participant limit, which can be a number between 1 and 20, inclusive.

import { Space, SubscriptionMode } from "@mux/spaces-web";

// Initialize Space using Automatic mode and subscribe to 5 participants
const space = new Space(JWT, {
  subscriptionMode: SubscriptionMode.Automatic,
  automaticParticipantLimit: 5,
});

Using manual subscriptions

Developers can use the manual subscription mode for when they need programmatic control over which participants to subscribe to and receive media from.

import { Space, SubscriptionMode, SpaceEvent } from "@mux/spaces-web";

let alice;
const aliceUserId = "some-uuid";

// Initialize Space using Manual mode
const space = new Space(JWT, {
  subscriptionMode: SubscriptionMode.Manual,
});

space.on(SpaceEvent.ParticipantJoined, async (participant) => {
  // Manually subscribing to participant
  if (participant.id === aliceUserId) {
    await participant.subscribe();
    alice = participant;
  }

  // Manually unsubscribing from the participant after another participant joins
  if (alice && alice.isSubscribed()) {
    await alice.unsubscribe();
  }
});

space.on(SpaceEvent.ParticipantLeft, async (participant) => {
  if (participant.id === aliceUserId) {
    alice = null;
  }
});

// Attach participant's media to the <video> element
space.on(SpaceEvent.ParticipantTrackSubscribed, (participant, track) => {
  // Get participant's <video> element
  const el = document.querySelector(`#${participant.connectionId} video`);

  if (el) {
    track.attach(el);
  }
});

// Detach participant's media from the <video> element
space.on(SpaceEvent.ParticipantTrackUnsubscribed, (participant, track) => {
  track.detach();
});

// Join the space
await space.join();