Media API v1 › Large Room

Large Room concept

v1's strategy for rooms that scale from 2 people to 10,000+. The SDK splits participants into two tiers — speakers (on-stage; individually tracked) and viewers (audience; count + pull). The split happens at token-mint time via the isViewer claim, not at runtime.

The tier is the *only* knob that controls fan-out scaling. Everything else — events, participant access, enumeration — derives from it. There is no second client-side flag, no "audience event opt-in," no participant-event flooding for large audiences.

The two tiers

Picked at token-mint time per participant via the token's isViewer claim. The tier decides both how the participant appears to other clients and which surfaces they're accessible through.

The isViewer claim

A boolean token claim — sibling of grant, not a flag inside it. Default false (speaker). The backend sets it per participant when minting the token.

Speakers — sync access + individual events

Treated exactly like a regular small-meeting participant. The SDK keeps a synchronous Map keyed by participant id, fires individual lifecycle events (lazy + retroactive for already-present speakers when you subscribe), and exposes the full RemoteParticipant surface.

Viewers — count + paginated pull

No per-member object on the client by default. Two surfaces give you everything you need: a coalesced live count, and a paginated method when you actually need the roster.

Event — participant-count-changed

Broken-out tier counts. Server-coalesced (~250 ms window) so a burst of joins / leaves becomes a small number of updates, not a flood. Always available (lazy — subscribed on first listener). One event covers both an "X attendees" total badge and a "Y speakers · Z viewers" breakdown.

room.getParticipants()

Cursor-paginated paginated method. Filter by tier with tier: 'speaker' | 'viewer'; omit for both (speakers first, then viewers). Mirrors the pagination shape of pubsub.getHistory.

One RemoteParticipant class for both tiers

Viewer-tier instances returned from getParticipants({ tier: 'viewer' }) share the RemoteParticipant class with speakers. The isViewer property is the discriminator. Calling subscribe-style methods on a viewer instance rejects.

The audience-token simplification

For broadcasts and webinars where every viewer needs the same access, mint one token without roomId and without participantId — distribute it to every viewer. The SDK generates a unique participantId per session, so each viewer still gets a distinct identity inside the room.

Examples

1 · Small meeting — everyone on stage

Default case. No tier choice needed — all tokens are isViewer: false.

const room = await VideoSDK.join({ token, roomId, name: 'Alice' });

// Subscribe in response to publish, NOT in participant-joined.
// stream-published fires retroactively for kinds already published when p joined,
// and live for kinds they publish later — one handler covers both.
room.on('participant-joined', (p) => {
  p.on('stream-published',  ({ kind }) => p.subscribe(kind));
  p.on('stream-subscribed', (sub) => {
    if (sub.video) document.querySelector('#grid').appendChild(sub.video.createElement());
    if (sub.audio) sub.audio.setVolume(0.7);
  });
});

// Don't call p.subscribe() inside participant-joined directly — the participant
// may not have published yet (NOT_PUBLISHED rejection). See RemoteParticipant.subscribe.

2 · Webinar — mixed tokens

Three token shapes for one room. Speakers and panelists are individually tracked; the audience is count-only.

// Host — speaker + moderator
const hostToken = generateToken({
  roomId: 'webinar-2026-05', participantId: 'host-1', name: 'Host',
  isViewer: false,
  grant: { canPublish: true, canSubscribe: true, canPublishData: true, canSubscribeData: true, canModerate: true, canHls: true },
});

// Panelist — speaker, no moderator privileges
const panelistToken = generateToken({
  roomId: 'webinar-2026-05', participantId: 'panelist-jane',
  isViewer: false,
  grant: { canPublish: true, canSubscribe: true, canPublishData: true, canSubscribeData: true },
});

// Audience — viewer; single reusable token (no participantId, SDK generates one per session)
const audienceToken = generateToken({
  roomId: 'webinar-2026-05',
  isViewer: true,
  grant: { canSubscribe: true, canSubscribeData: true },
});
// Distribute audienceToken to all 1,000+ viewers.

const room = await VideoSDK.join({ token: hostToken });

// Speakers — render tiles
room.on('participant-joined', (p) => renderSpeakerTile(p));   // speakers only

// Audience — count + breakdown
room.on('participant-count-changed', ({ speaker, viewer, total }) => {
  ui.attendeesBadge.text(`${total} attendees`);
  ui.tierBreakdown.text(`${speaker} speakers · ${viewer} viewers`);
});

3 · Large ILS audience — 10,000 viewers, one token

Domain-wide audience token + no participantId = one mint covers every viewer. The SDK generates a unique participantId per session, so 10,000 sessions still have 10,000 distinct identities inside the room.

// Backend — mint once, serve via static endpoint
const audienceToken = generateToken({
  isViewer: true,                                       // audience tier
  grant: { canSubscribe: true, canSubscribeData: true },
  // no roomId        → domain-wide (any room in the project)
  // no participantId → SDK generates one per session
});

// Frontend — every viewer uses the same token
const room = await VideoSDK.join({
  token: audienceToken,
  roomId: 'town-hall-2026-q3',
  name:   'Attendee',
});

room.on('participant-count-changed', ({ viewer }) => {
  ui.attendeesBadge.text(`${viewer.toLocaleString()} watching`);
});

4 · Host renders the audience roster (paginated)

A moderator UI that lets the host see who's watching. Paginated 50 at a time via getParticipants({ tier: 'viewer' }).

let cursor;
async function loadMoreViewers() {
  const page = await room.getParticipants({ tier: 'viewer', limit: 50, cursor });
  for (const viewer of page.participants) renderViewerRow(viewer);
  cursor = page.nextCursor;
  ui.loadMoreButton.disabled = !cursor;            // no more pages → disable
  ui.totalBadge.text(`${page.total} viewers total`);
}

ui.loadMoreButton.onClick(loadMoreViewers);
loadMoreViewers();   // first page

5 · Find a participant by id, tier unknown

If a moderator action arrives with an unknown participant id (e.g., a moderation webhook), check the speaker Map first (sync), then fall through to a paginated viewer search.

async function findParticipant(id) {
  // Speakers — sync, instant
  const speaker = room.remoteParticipants.get(id);
  if (speaker) return speaker;

  // Viewers — paginated; usually you'd index by id server-side instead,
  // this is the "I have nothing else" fallback
  let cursor;
  do {
    const page = await room.getParticipants({ tier: 'viewer', limit: 100, cursor });
    const found = page.participants.find(p => p.id === id);
    if (found) return found;
    cursor = page.nextCursor;
  } while (cursor);

  return null;
}

6 · Promoting an audience member to speaker — coming via Q2

The "audience member raises hand and is promoted to speaker" flow is not yet locked. It maps to Q2 — change grant mid-call in Authentication → Open Questions (because promotion is also a grant change: canPublish: false → true plus an isViewer flip). Three options are on the table — refresh-driven, server-side updateParticipant REST, hybrid. See the open-questions section for the trade-offs.

Errors specific to large rooms

Beyond the standard join rejections, two rejections are tier-specific:

When to use which tier

See also: Authentication → Tier & participant events Authentication → roomId scoping (audience token) Room → remoteParticipants Room → getParticipants Room → participant-count-changed Types → GetParticipantsOpts Types → GetParticipantsResult