[bcostdolby]

Summary

Viewer apps have treated connected as "a source is active" and started playback there, or started it from the active broadcast event. Neither is reliable: connected comes from the browser's RTCPeerConnection while active is sent by the server, so they arrive in either order, and on active the Web SDK has not yet delivered the track event that carries the media. Result: media is decoded but the element never plays (black screen, no error).

• Broadcast Events page: new "Event ordering" note stating that connected and the first active are independent, that neither should start playback, and that the SDK emits track only after the first active.

• Web SDK "Track event" section: same explanation, plus the track example now shows the recommended pattern instead of a placeholder helper:

  millicastView.on('track', (event) => {
    videoElement.srcObject = event.streams[0]; // videoElement has the autoplay attribute set.
  });

  Assigning srcObject on every track event (audio and video, same stream) with autoplay on the element avoids a one-shot guard that would keep a stale stream after a reconnect, and avoids an explicit play() whose promise can be rejected by autoplay policy. The prose notes muted is needed without a prior user gesture, and that an explicit play() must be called right after assigning srcObject in this handler with its promise handled.

Verified against a live stream with SDK 0.4.0 and 0.9.3 source: the old connected-gated logic never plays when active trails connected; play() from the active handler is aborted by the subsequent srcObject assignment; the pattern above played in 6/6 trials including 3/3 with active forced to arrive 300 ms after connected.

Link to Devin session: https://dolby.devinenterprise.com/sessions/d8bbfd361f6242fb8feab68067e55d8c
Open in Devin Desktop: https://dolby.devinenterprise.com/desktop/session/d8bbfd361f6242fb8feab68067e55d8c?variant=devin
Requested by: @bcostdolby

---

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring

[theoplayer-bot]

Documentation preview
🚀 View preview at https://docs-preview.optiview.dolby.com/pr-926/
Deployed from commit cbd268e at 2026-10-19 22:16 UTC.