@tribe-nest/forge 3.37.0 → 3.39.0

package/src/ui/styled/broadcast/BroadcastPlayer.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType, type ReactNode } from "react";
 import { Maximize, Pause, Pin, Play, Send } from "lucide-react";
 import { io, type Socket } from "socket.io-client";
 import type { IBroadcastPass, ILiveBroadcast } from "../../../types/models";
@@ -10,12 +10,25 @@ import {
   useBroadcastComments,
   useBroadcastSessionApi,
   type BroadcastComment,
+  type BroadcastViewerCredentials,
 } from "../../../data/queries/useBroadcasts";
 import { useForgeT } from "../../../i18n";
 import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { CallHelpHint } from "../../media/CallHelpHint";
 import { timeAgo } from "../community/util";
 import { buttonStyle } from "../Button";
 import { Loading } from "../Loading";
+import {
+  broadcastFellBack,
+  chooseBroadcastStage,
+  type BroadcastCredentialsError,
+  type BroadcastRoomState,
+} from "./broadcastStage";
+// Type-only, and it has to stay that way: the module it names imports
+// `mediasoup-client`, and a value import here would put a browser-only package
+// on the server path of every site that loads `@tribe-nest/forge/ui`. It is
+// reached through the `import()` in the effect below, which no server runs.
+import type { BroadcastRealtimeStageProps } from "./BroadcastRealtimeStage";
 
 /** The socket messages a watching browser sends and receives. */
 const SocketEvent = {
@@ -35,6 +48,26 @@ const SIMULCAST_QUALITIES = [
   { label: "forge.broadcast_player.quality_low", value: "q" },
 ] as const;
 
+/**
+ * The token endpoint's refusal, reduced to what the decision needs.
+ *
+ * Nothing here distinguishes a 409 from a 500 from a dead network, and that is
+ * the point: every one of them means this viewer is not getting into the live
+ * room, and every one of them ends with them watching the stream instead. The
+ * status and the message are carried so a site can log which it was.
+ */
+function credentialsRefusal(error: unknown): BroadcastCredentialsError {
+  const response = (error as { response?: { status?: number; data?: { reason?: unknown; message?: unknown } } } | null)
+    ?.response;
+  const status = response?.status;
+  // The 409 answers with `{ reason }` (`full` or `unavailable`); everything
+  // else on this API answers with `{ message }`. Either is worth keeping for a
+  // log, and neither changes what happens next.
+  const detail = response?.data?.reason ?? response?.data?.message;
+  const message = typeof detail === "string" ? detail : undefined;
+  return { ...(typeof status === "number" ? { status } : {}), ...(message ? { message } : {}) };
+}
+
 const newId = (): string => {
   if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
   return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
@@ -65,9 +98,35 @@ export interface BroadcastPlayerProps {
 /**
  * The watch surface: the stream, who else is here, and the chat.
  *
- * Mounted ONLY behind a validated pass. Two playback paths, chosen by the
- * broadcast itself: a WebRTC subscription when the broadcast carries a realtime
- * config (sub-second, with a quality picker), and HLS otherwise.
+ * Mounted ONLY behind a validated pass. Three playback paths, chosen by the
+ * broadcast itself and never by the viewer:
+ *
+ * 1. **The media plane** (`realtime.available`). A v2 broadcast whose live room
+ *    is open, watched over WebRTC in well under a second. This is the path that
+ *    can be REFUSED: the room has a hard cap, so being turned away is ordinary.
+ * 2. **Cloudflare Calls** (`realtimeConfig`). The v1 realtime path, unchanged
+ *    and still carrying its quality picker, until v1 itself is retired.
+ * 3. **HLS.** Six to ten seconds behind and always available.
+ *
+ * ## Falling back is the feature, not the error path
+ *
+ * A viewer who cannot get onto the plane must end up watching the broadcast,
+ * without doing anything and without being asked anything. So every uncertain
+ * state resolves to HLS, and the four ways the plane can fail (the token
+ * endpoint answering 409, any other failure fetching one, the room closing, and
+ * the SDK giving up) all land in the same place. `chooseBroadcastStage` holds
+ * the rule and `broadcastStage.spec.ts` walks every combination of it.
+ *
+ * The one thing the viewer is told is a single line saying which stream they
+ * are on, because a stream that is suddenly eight seconds behind a chat they
+ * are reading is something a person needs an explanation for. Why it happened
+ * is behind the `?`, per the house design law.
+ *
+ * ## Why the quality picker is not on the new path
+ *
+ * The plane has no simulcast. Every viewer receives the program feed's single
+ * encoding, so High, Medium and Low would be three controls that change
+ * nothing. A control that lies about what it does is worse than no control.
  */
 export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: BroadcastPlayerProps) {
   const t = useForgeT();
@@ -92,10 +151,124 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   const [realtimeSessionId, setRealtimeSessionId] = useState<string | null>(null);
   const isSubscribingRef = useRef(false);
 
-  const isRealtime = useMemo(
-    () => !!broadcast.realtimeConfig && Object.keys(broadcast.realtimeConfig).length > 0,
-    [broadcast.realtimeConfig],
+  const realtimeAvailable = broadcast.realtime?.available === true;
+
+  /**
+   * The v1 Cloudflare path, and it yields to the plane rather than competing
+   * with it. A broadcast carries one or the other in practice; if one ever
+   * carried both, the newer plane is the one to attempt, and a plane that
+   * refuses falls back to HLS as the contract says rather than sideways into a
+   * v1 session that will not exist.
+   */
+  const isLegacyRealtime = useMemo(
+    () => !realtimeAvailable && !!broadcast.realtimeConfig && Object.keys(broadcast.realtimeConfig).length > 0,
+    [realtimeAvailable, broadcast.realtimeConfig],
+  );
+
+  // ── The media plane ────────────────────────────────────────────────────────
+  const [PlaneStage, setPlaneStage] = useState<ComponentType<BroadcastRealtimeStageProps> | null>(null);
+  const [credentialsReady, setCredentialsReady] = useState(false);
+  const [credentialsError, setCredentialsError] = useState<BroadcastCredentialsError | null>(null);
+  const [roomState, setRoomState] = useState<BroadcastRoomState | undefined>(undefined);
+  /** The ticket the probe already minted, spent on the SDK's FIRST attempt. */
+  const primedCredentials = useRef<BroadcastViewerCredentials | null>(null);
+
+  // `sessionApi` is rebuilt every render, so it is read through a ref rather
+  // than depended on: as a dependency it would re-mint a ticket on every render.
+  const sessionApiRef = useRef(sessionApi);
+  sessionApiRef.current = sessionApi;
+
+  /**
+   * The pass is the credential this endpoint takes, and `sessionId` is the id
+   * the pass is known by everywhere else on this surface (it is what
+   * `validate-session` is given, and `viewer-token` validates the pass the same
+   * way before minting).
+   */
+  const passId = broadcastPass.sessionId;
+
+  const mintCredentials = useCallback(
+    () => sessionApiRef.current.viewerToken({ broadcastId: broadcast.id, ...(passId ? { passId } : {}) }),
+    [broadcast.id, passId],
+  );
+
+  /**
+   * Load the SDK and mint a ticket, together, in an effect.
+   *
+   * The effect is what makes this safe on a server: Forge renders inside
+   * TanStack Start on Cloudflare Workers, `BroadcastRealtimeStage` imports
+   * `mediasoup-client`, and an effect is code no server ever runs. Nothing on
+   * the module path of this file touches the media SDK.
+   *
+   * They are fetched together because neither is any use without the other, and
+   * because a viewer must not be moved onto the plane until BOTH are in hand:
+   * mounting the provider first would show a black rectangle for as long as the
+   * chunk took to arrive. A chunk that never arrives lands in the same `catch`
+   * as a refused ticket and falls back the same way.
+   */
+  useEffect(() => {
+    if (!realtimeAvailable) return;
+    let cancelled = false;
+
+    Promise.all([import("./BroadcastRealtimeStage"), mintCredentials()])
+      .then(([module, credentials]) => {
+        if (cancelled) return;
+        primedCredentials.current = credentials;
+        setPlaneStage(() => module.BroadcastRealtimeStage);
+        setCredentialsReady(true);
+      })
+      .catch((error: unknown) => {
+        if (cancelled) return;
+        setCredentialsError(credentialsRefusal(error));
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [realtimeAvailable, mintCredentials]);
+
+  /**
+   * Handed to the provider, which calls it before EVERY attempt rather than
+   * once. A viewer ticket expires in ten minutes and a broadcast runs longer,
+   * so a token fetched once means the first reconnect presents a dead one.
+   *
+   * The probe's ticket is spent here on the first call, so one viewer does not
+   * mint two identities to watch one broadcast.
+   */
+  const getCredentials = useCallback(async () => {
+    const primed = primedCredentials.current;
+    primedCredentials.current = null;
+    if (primed) return primed;
+    try {
+      return await mintCredentials();
+    } catch (error) {
+      // A refusal on a reconnect says the same thing as a refusal on the first
+      // attempt: this viewer is not getting back into the room. Recording it is
+      // what moves them onto HLS instead of leaving the SDK knocking.
+      setCredentialsError(credentialsRefusal(error));
+      throw error;
+    }
+  }, [mintCredentials]);
+
+  /**
+   * Never cleared back to `undefined` when the stage unmounts, and that is
+   * load-bearing. A room that has closed is the reason we left it, so forgetting
+   * it would choose the plane again, mount the provider again, and watch it
+   * close again, for ever.
+   */
+  const handleRoomState = useCallback((next: BroadcastRoomState) => setRoomState(next), []);
+
+  const stageInput = useMemo(
+    () => ({ realtimeAvailable, credentialsReady, credentialsError, roomState }),
+    [realtimeAvailable, credentialsReady, credentialsError, roomState],
   );
+  const stage = chooseBroadcastStage(stageInput);
+  const showPlane = stage === "realtime" && !!PlaneStage;
+  // Nothing is mounted while the ticket is in flight. `react-player` builds an
+  // hls.js instance on mount and starts fetching immediately, so rendering the
+  // HLS stage "meanwhile" made every realtime viewer download the broadcast a
+  // second time, over the CDN, for a stage that was about to be replaced.
+  const showHls = stage === "hls" && !isLegacyRealtime;
+  const fellBack = broadcastFellBack(stageInput);
 
   const { data: audienceData } = useBroadcastAudience(broadcast.id, !broadcast.endedAt);
   const { data: initialComments } = useBroadcastComments(broadcast.id);
@@ -113,10 +286,10 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     });
   }, [comments]);
 
-  // ── WebRTC subscription ────────────────────────────────────────────────────
+  // ── WebRTC subscription, v1 (Cloudflare Calls) ─────────────────────────────
   useEffect(() => {
     const config = broadcast.realtimeConfig;
-    if (!isRealtime || !config) return;
+    if (!isLegacyRealtime || !config) return;
     if (isSubscribingRef.current) return;
     isSubscribingRef.current = true;
 
@@ -150,6 +323,10 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         type: local?.type,
         trackIds: config.tracks.map((track) => track.trackName),
         sessionId: config.sessionId,
+        // The pass, because subscribing IS playback: this endpoint used to
+        // take a session id and a track name from anybody and hand back the
+        // stream, which made the ticket box in front of it decoration.
+        passId,
       });
 
       setRealtimeSessionId(answer.sessionId);
@@ -166,7 +343,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     // `sessionApi` is rebuilt each render and is deliberately not a dependency:
     // including it would re-negotiate the peer connection on every render.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isRealtime, broadcast.realtimeConfig]);
+  }, [isLegacyRealtime, broadcast.realtimeConfig]);
 
   // ── Chat socket ────────────────────────────────────────────────────────────
   useEffect(() => {
@@ -213,7 +390,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   };
 
   const togglePlay = () => {
-    if (!isRealtime || !isAudioLoaded || !isVideoLoaded) return;
+    if (!isLegacyRealtime || !isAudioLoaded || !isVideoLoaded) return;
     if (isPlaying) {
       audioRef.current?.pause();
       videoRef.current?.pause();
@@ -239,6 +416,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     const videoTrack = config.tracks.find((track) => track.mid === "0");
     try {
       await sessionApi.switchQuality({
+        passId,
         track: {
           ...videoTrack,
           sessionId: realtimeSessionId,
@@ -283,7 +461,15 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
       }}
     >
       <div style={{ flex: "1 1 520px", minWidth: 0, ...panel }}>
-        {!isRealtime && (
+        {showPlane && PlaneStage && <PlaneStage getCredentials={getCredentials} onRoomState={handleRoomState} />}
+
+        {stage === "pending" && (
+          <div style={{ aspectRatio: "16/9", display: "grid", placeItems: "center" }}>
+            <Loading />
+          </div>
+        )}
+
+        {showHls && (
           <div data-testid="broadcast-hls-stage" style={{ aspectRatio: "16/9" }}>
             {renderPlayer ? (
               renderPlayer({ src: broadcast.liveUrl })
@@ -299,7 +485,34 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
           </div>
         )}
 
-        {isRealtime && (
+        {/*
+          Which stream they ended up on. This is STATE, not an explanation, so
+          it stays visible: a viewer whose picture is suddenly eight seconds
+          behind the chat beside it needs to know that before they go looking
+          for a fault. The reason it happened is help, so it is behind the `?`.
+        */}
+        {fellBack && (
+          <div
+            role="status"
+            data-testid="broadcast-fallback-notice"
+            style={{
+              display: "flex",
+              alignItems: "center",
+              gap: 6,
+              padding: "8px 16px 0",
+              fontSize: 13,
+              color: theme.colors.text,
+              opacity: 0.75,
+            }}
+          >
+            <span>{t("forge.broadcast_player.fallback_notice")}</span>
+            <CallHelpHint label={t("forge.broadcast_player.fallback_help_label")}>
+              {t("forge.broadcast_player.fallback_help")}
+            </CallHelpHint>
+          </div>
+        )}
+
+        {isLegacyRealtime && (
           <div
             ref={videoContainerRef}
             data-testid="broadcast-realtime-stage"
@@ -403,7 +616,13 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
             </div>
           </div>
 
-          {isRealtime && (
+          {/*
+            v1 only. The media plane has no simulcast, so on that path these
+            four options would all resolve to the one encoding the program feed
+            publishes, and a picker that cannot change anything is a lie about
+            what the viewer is receiving.
+          */}
+          {isLegacyRealtime && (
             <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
               <label htmlFor="broadcast-quality">{t("forge.broadcast_player.quality")}</label>
               <select

package/src/ui/styled/broadcast/BroadcastRealtimeStage.tsx

@@ -0,0 +1,260 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Maximize, Volume2, VolumeX } from "lucide-react";
+
+import type { MediaRoomCredentials } from "@tribe-nest/media-client";
+import {
+  MediaRoomProvider,
+  useMediaRoom,
+  useRemoteTrack,
+  useRoomState,
+  useVisibleProducers,
+} from "@tribe-nest/media-client/react";
+
+import { useForgeT } from "../../../i18n";
+import { useForgeTheme } from "../../theme/ForgeThemeProvider";
+import { Loading } from "../Loading";
+import { programTracks, type BroadcastRoomState } from "./broadcastStage";
+
+/**
+ * A live broadcast, received over the platform's own media plane.
+ *
+ * ## Why this is its own file, and why nothing imports it directly
+ *
+ * `@tribe-nest/media-client/react` pulls in `mediasoup-client`, which touches
+ * `RTCPeerConnection` at module scope and does not exist on a server. Forge
+ * renders inside TanStack Start on Cloudflare Workers, and `BroadcastPlayer`
+ * lives in the `./ui` entry that every site loads on every page, so a static
+ * import of the SDK from the player would put a browser-only module on the
+ * server path of sites that have never held a broadcast. So the player reaches
+ * this file through a dynamic `import()` fired from an effect, which is code
+ * that cannot run anywhere but a browser. `./media` (the coaching call surface)
+ * is a separate entry that a site opts into, which is why it may import the SDK
+ * at module scope and this may not.
+ *
+ * ## What it renders
+ *
+ * One publisher, `program:<broadcastId>`, with one video producer and one audio
+ * producer. The viewer's token can subscribe to that identity and nothing else,
+ * so the producers this sees ARE the broadcast (see `programTracks`).
+ *
+ * ## Sound is a toggle, and play/pause is not offered
+ *
+ * The picture starts on its own, muted, because a muted autoplay is the one
+ * thing every browser allows without a gesture and a viewer who has arrived at
+ * a live stream should see it. Sound needs the gesture, so it gets the control.
+ *
+ * What it deliberately does NOT get is a pause button. There is nothing to
+ * resume: this is a subscription to what is happening now, so a "pause" is a
+ * mute plus a blank screen plus a lie about being able to go back. The HLS
+ * stage keeps its transport controls because there the buffer makes them true.
+ *
+ * There is no quality selector either. The plane has no simulcast: every viewer
+ * receives the program feed's single encoding, so a picker offering High,
+ * Medium and Low would be three buttons that all do the same nothing.
+ */
+
+export type BroadcastRealtimeStageProps = {
+  /**
+   * Called before EVERY attempt, not once, which is why it is a callback. A
+   * viewer credential expires in ten minutes and a broadcast runs for longer,
+   * so a token fetched once means the first reconnect presents a dead one.
+   */
+  getCredentials: () => Promise<MediaRoomCredentials>;
+  /**
+   * The room, reported upward on every change.
+   *
+   * The decision to fall back to HLS is made by the PLAYER, above the provider,
+   * because falling back means unmounting the provider and a component cannot
+   * unmount itself. So this reports and the player decides, and there is one
+   * `chooseBroadcastStage` rather than one here and another one up there.
+   */
+  onRoomState: (state: BroadcastRoomState) => void;
+};
+
+export function BroadcastRealtimeStage({ getCredentials, onRoomState }: BroadcastRealtimeStageProps) {
+  return (
+    <MediaRoomProvider getCredentials={getCredentials} autoSubscribe>
+      <ProgramStage onRoomState={onRoomState} />
+    </MediaRoomProvider>
+  );
+}
+
+function ProgramStage({ onRoomState }: { onRoomState: (state: BroadcastRoomState) => void }) {
+  const t = useForgeT();
+  const theme = useForgeTheme();
+  const { connectionState, error, recovering } = useMediaRoom();
+  const state = useRoomState();
+  const producers = useVisibleProducers();
+
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [soundOn, setSoundOn] = useState(false);
+  const [showControls, setShowControls] = useState(false);
+
+  // Memoised on the room's own snapshot, which is a stable reference while
+  // nothing has changed. Rebuilding it per render is what turns a stage into a
+  // component that re-renders per frame.
+  const tracks = useMemo(() => programTracks(producers), [producers]);
+  const { track, attach } = useRemoteTrack(tracks.videoProducerId ?? "");
+  const hasPicture = !!tracks.videoProducerId && !!track && !tracks.videoPaused;
+
+  useEffect(() => {
+    onRoomState({ connectionState, phase: state.phase, recovering, ...(error ? { error } : {}) });
+  }, [onRoomState, connectionState, state.phase, recovering, error]);
+
+  const toggleFullscreen = () => {
+    if (!containerRef.current) return;
+    if (document.fullscreenElement) void document.exitFullscreen();
+    else void containerRef.current.requestFullscreen();
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      data-testid="broadcast-plane-stage"
+      onMouseEnter={() => setShowControls(true)}
+      onMouseLeave={() => setShowControls(false)}
+      // The ratio is on BOTH this box and the video inside it, and that is not
+      // redundancy for its own sake. The container's ratio is what guarantees
+      // the panel has a height at all, including before a single frame has
+      // arrived; removing it once collapsed the stage and the chat beside it
+      // rode up into the gap. The video's own ratio (below) is what keeps that
+      // height still while simulcast changes the resolution underneath it.
+      // They compute to the same box, so nothing fights.
+      style={{ aspectRatio: "16 / 9", position: "relative", background: "#000", lineHeight: 0 }}
+    >
+      {/*
+        Muted, always, and that is not the sound control. The audio arrives as
+        its own producer on its own element, so a viewer who unmuted THIS would
+        hear nothing and conclude the stream is silent.
+      */}
+      {/*
+        The RATIO is on the video itself, which is what keeps the box still.
+
+        Simulcast changes the incoming resolution underneath us as the node
+        moves a viewer between layers (1080p to 540p to 270p). A replaced
+        element takes its box partly from the track's intrinsic size, and
+        `height: 100%` did not save it: a percentage height needs a definite
+        parent height, and one derived from the container's own `aspect-ratio`
+        is not reliably that. So the element fell back to intrinsic height and
+        the whole panel jumped on every layer switch, at the one moment a
+        viewer should notice nothing.
+
+        `aspect-ratio` on the element with `height: auto` overrides the
+        intrinsic ratio outright: the box is 16/9 of whatever width it is
+        given, whatever arrives on the wire. `height: 100%` is deliberately
+        NOT used, because that is the thing that failed.
+      */}
+      <video
+        ref={attach}
+        autoPlay
+        playsInline
+        muted
+        style={{ display: "block", width: "100%", height: "auto", aspectRatio: "16 / 9", objectFit: "contain" }}
+      />
+
+      {tracks.audioProducerIds.map((producerId) => (
+        <ProgramAudio key={producerId} producerId={producerId} soundOn={soundOn} />
+      ))}
+
+      {!hasPicture && (
+        <div
+          style={{
+            position: "absolute",
+            top: "50%",
+            left: "50%",
+            transform: "translate(-50%, -50%)",
+            pointerEvents: "none",
+          }}
+        >
+          <Loading />
+        </div>
+      )}
+
+      {hasPicture && (
+        <button
+          type="button"
+          onClick={() => setSoundOn((was) => !was)}
+          aria-label={soundOn ? t("forge.broadcast_player.sound_off") : t("forge.broadcast_player.sound_on")}
+          style={{
+            position: "absolute",
+            bottom: 16,
+            left: 16,
+            padding: 8,
+            borderRadius: theme.cornerRadius,
+            border: "none",
+            cursor: "pointer",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "#ffffff",
+            zIndex: 1,
+            // Kept on screen while the sound is off, because it is the control
+            // a viewer arriving at a silent stream is looking for. Once the
+            // sound is on it behaves like the rest of the chrome.
+            opacity: soundOn && !showControls ? 0 : 1,
+            transition: "opacity 150ms",
+          }}
+        >
+          {soundOn ? <Volume2 size={20} /> : <VolumeX size={20} />}
+        </button>
+      )}
+
+      {hasPicture && (
+        <button
+          type="button"
+          onClick={toggleFullscreen}
+          aria-label={t("forge.broadcast_player.fullscreen")}
+          style={{
+            position: "absolute",
+            bottom: 16,
+            right: 16,
+            padding: 8,
+            borderRadius: theme.cornerRadius,
+            border: "none",
+            cursor: "pointer",
+            background: "rgba(0, 0, 0, 0.5)",
+            color: "#ffffff",
+            zIndex: 1,
+          }}
+        >
+          <Maximize size={20} />
+        </button>
+      )}
+    </div>
+  );
+}
+
+/**
+ * The program's audio, attached and never drawn.
+ *
+ * Held on its own element rather than on the `<video>`, because the two arrive
+ * as separate producers and the video element is muted for good (see above).
+ *
+ * `play()` is called from an effect rather than through `autoPlay` so that a
+ * producer arriving AFTER the viewer turned the sound on is audible too: an
+ * `autoPlay` attribute is read when the element mounts, and a track that lands
+ * later would leave a broadcast playing in silence with the speaker icon on.
+ * The rejection is swallowed on purpose: a browser refusing to play unprompted
+ * audio is the ordinary case this control exists to get past, not an error.
+ */
+function ProgramAudio({ producerId, soundOn }: { producerId: string; soundOn: boolean }) {
+  const { track, attach } = useRemoteTrack(producerId);
+  const elementRef = useRef<HTMLAudioElement | null>(null);
+
+  const setElement = useCallback(
+    (element: HTMLAudioElement | null) => {
+      elementRef.current = element;
+      attach(element);
+    },
+    [attach],
+  );
+
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) return;
+    if (soundOn) void element.play().catch(() => undefined);
+    else element.pause();
+  }, [soundOn, track]);
+
+  return <audio ref={setElement} style={{ display: "none" }} />;
+}
+
+export default BroadcastRealtimeStage;