VideoStream interface

id

Server-assigned stream id (also called the SID). Stable across reconnects within the same publish.

codec

Codec currently in use. Useful for debug overlays and codec-specific UI.

dimensions

Current video dimensions. Null if not yet known (pre-first-frame).

frameRate

Current frames-per-second. Null if not yet known.

contentHint

Encoder hint. "motion" optimizes for high-motion content; "detail" for sharpness in static content (e.g. shared documents).

isPlaying / isPaused / isEnded

Sync booleans reflecting the local rendering state of this stream.

attach / detach

Render this stream into an HTML <video> element. attach is idempotent and time-independent — call any time, even before subscription completes; the SDK queues the attach and binds when media is available.

The same stream can be attached to multiple elements (main pane + thumbnail). When the underlying track is swapped (device change, reconnect), all attached elements continue to render — the SDK rebinds them transparently.

Auto-detach on stream end. The SDK tracks every element passed to attach(). When the stream transitions to 'ended' (publisher unpublished, you unsubscribed, network terminated), the SDK iterates the tracked elements and clears their srcObject automatically. You only need to call detach() when re-routing a still-active stream to a different element.

Lifecycle & flow

1. Create or obtain a <video> element. The SDK doesn't care if it's already in the DOM, mounted later, or has user-supplied style/class attributes. autoplay and (on mobile) playsinline should be set by you on the element.
2. Call stream.attach(el). SDK sets el.srcObject to a managed MediaStream wrapping the stream's track and registers the element internally.
3. Track changes (device swap, reconnect) are transparent. The SDK rebinds srcObject on every registered element when the underlying track is replaced — no app action required.
4. Call stream.detach(el) only to re-route. Removes el from the registry and clears its srcObject. Other attached elements keep rendering. You don't need to detach for cleanup — the SDK handles that on stream end (see auto-detach above).
5. Stream ends (publisher unpublished, network died, you unsubscribed). SDK iterates the registry, clears srcObject on every attached element, and fires video-unsubscribed on the participant. App removes the tile element in that handler.

// 1. Wire up the participant — fires retroactively for already-present participants too.
room.on('participant-joined', (p) => {

  // 2. When a stream is delivered, attach to your <video> element(s).
  p.on('stream-subscribed', (sub) => {
    if (!sub.video) return;                                  // we only handle video here
    const stream = sub.video;
    const tile   = createTile(p);                            // your UI factory
    const main   = tile.querySelector('video.main');
    const thumb  = tile.querySelector('video.thumb');

    stream.attach(main);                                      // primary render target
    stream.attach(thumb);                                     // optional thumbnail
    document.querySelector('#grid').appendChild(tile);

    // Optional: react to non-terminal transitions on the same stream.
    stream.on('state-changed', ({ state }) => {
      tile.classList.toggle('frozen', state === 'frozen');
      tile.classList.toggle('paused', state === 'paused');
    });
  });

  // 3. Re-route mid-call (e.g., user pinned this participant — promote to main pane).
  pinButton.onclick = () => {
    p.video?.detach(thumb);                                   // remove from thumbnail
    p.video?.attach(mainStageEl);                             // attach to main stage
    // SDK keeps `p.video` stable across the move; no re-subscribe needed.
  };

  // 4. Cleanup. Fires whether YOU unsubscribed or the publisher unpublished.
  //    By the time this runs, srcObject is already cleared on attached elements.
  p.on('stream-unsubscribed', ({ kind }) => {
    if (kind === MediaKind.Video) {
      document.querySelector(`[data-pid="${p.id}"]`)?.remove();
    }
  });
});

// 5. Drop the subscription explicitly (offscreen tile, leaving room) — Promise resolves
//    when server acks. The video-unsubscribed event fires immediately after.
await p.unsubscribe([MediaKind.Video]);

createElement

Convenience helper — SDK creates a pre-configured <video> element wrapped in a <div> container. Sets autoplay, mobile attributes (playsinline, x5-playsinline), srcObject, and IntersectionObserver-based adaptive subscription pause.

Use this when you don't need to control the element's attributes yourself.

const tile = p.video.createElement({
  containerStyle: { height: '300px', width: '300px' },
  videoStyle: { objectFit: 'cover' },
});
document.querySelector('#grid').appendChild(tile);

getStats async

One-shot statistics snapshot. Includes bitrate, framerate, packet loss, jitter, codec details, and resolution. For live monitoring (per-frame UI), poll at your desired interval.

setInterval(async () => {
  const stats = await p.video.getStats();
  document.querySelector('#kbps').textContent = `${(stats.bitrate / 1000) | 0} kbps`;
}, 2000);

getMediaStreamTrack escape hatch

Returns the underlying browser MediaStreamTrack for advanced use cases — MediaRecorder, Insertable Streams API, custom WebRTC integrations, computer vision pipelines.

const track = me.video.getMediaStreamTrack();
const recorder = new MediaRecorder(new MediaStream([track]));
recorder.ondataavailable = e => uploadChunk(e.data);
recorder.start(1000);