@tribe-nest/forge 3.38.0 → 3.39.0

package/src/ui/styled/broadcast/broadcastStage.ts

@@ -0,0 +1,189 @@
+import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from "@tribe-nest/media-client";
+
+/**
+ * Which stage a live broadcast plays on, as pure functions.
+ *
+ * A v2 broadcast can be watched two ways. The platform's own media plane
+ * carries it over WebRTC in well under a second, and HLS carries it to
+ * everybody else six to ten seconds behind. The plane is the better picture and
+ * it is also the one with a hard cap on it (`STREAM_V2_REALTIME_VIEWER_CAP`,
+ * 100 by default), so being turned away from it is an ORDINARY outcome rather
+ * than an error, and the viewer who is turned away must simply end up watching
+ * the stream.
+ *
+ * That is the whole reason this is a pure function in its own file. The choice
+ * is made from four independent signals arriving at four different times (what
+ * the broadcast advertises, what the token endpoint answered, what the SDK is
+ * doing, and whether the room is still open), and a rule assembled inline out
+ * of four `if`s inside a component is a rule nobody can test and everybody
+ * edits. `callState.ts` splits the call screen's decisions out for the same
+ * reason.
+ *
+ * ## The bias, stated once
+ *
+ * Every uncertain state resolves to `hls`. A viewer on HLS is watching the
+ * broadcast a few seconds late; a viewer left on a realtime stage that is not
+ * going to connect is watching a black rectangle. Those are not comparable
+ * failures, so the ambiguity is spent in the direction that always shows a
+ * picture.
+ */
+
+/** `realtime` is the media plane. `hls` is the stream everybody can always watch. */
+/**
+ * Which stage the player shows.
+ *
+ * `pending` is the state between "this broadcast offers realtime" and knowing
+ * whether this viewer gets it. It draws nothing on purpose: the alternative
+ * was showing HLS meanwhile, and an HLS engine starts fetching the moment it
+ * mounts, so a realtime viewer pulled segments they would never watch.
+ */
+export type BroadcastStage = "realtime" | "hls" | "pending";
+
+/**
+ * The viewer-token endpoint said no.
+ *
+ * `409` is the designed refusal (the room is full, realtime is off, or nothing
+ * is live) and it is not special-cased below: a refusal is a refusal, and a
+ * network failure with no status at all falls back exactly the same way. The
+ * status is carried so a caller can log which one happened, never so this
+ * function can treat one as recoverable.
+ */
+export type BroadcastCredentialsError = {
+  /** The HTTP status when the server answered at all. Absent on a network failure. */
+  status?: number;
+  message?: string;
+};
+
+/** What the SDK says about the live room. Absent until the provider is mounted. */
+export type BroadcastRoomState = {
+  connectionState: ConnectionState;
+  /** The ROOM's phase. `closed` means the node said so, on a socket still open. */
+  phase: RoomState["phase"];
+  /**
+   * Is another attempt actually booked?
+   *
+   * `connectionState` is `reconnecting` both while the SDK is coming back and
+   * after its policy has given up, so without this a broadcast whose room died
+   * would sit on a frozen frame for ever rather than falling back.
+   */
+  recovering: boolean;
+  error?: DisconnectCause;
+};
+
+export type BroadcastStageInput = {
+  /** `broadcast.realtime.available`, as the public read reported it. */
+  realtimeAvailable: boolean;
+  /** A viewer credential has been minted. Nothing is mounted before it has. */
+  credentialsReady: boolean;
+  /** The refusal, when the fetch failed. `null` while it has not. */
+  credentialsError: BroadcastCredentialsError | null;
+  roomState?: BroadcastRoomState;
+};
+
+/**
+ * Is the realtime attempt over, as opposed to merely in progress?
+ *
+ * A drop that the SDK is recovering from is NOT over: it holds the last frame
+ * for a second or two and comes back, and tearing the room down to swap in an
+ * HLS player would turn a blink into a restart. A drain is the same, as long as
+ * the move is really happening. Everything else on this list is finished:
+ * refused, the room closed, the socket closed for good, or the reconnect policy
+ * exhausted with nothing booked.
+ */
+function realtimeIsOver(roomState: BroadcastRoomState | undefined): boolean {
+  if (!roomState) return false;
+  if (roomState.phase === "closed") return true;
+  if (roomState.connectionState === "closed") return true;
+  if (roomState.error?.type === "refused") return true;
+  if (roomState.error?.type === "room_closed") return true;
+  return roomState.connectionState === "reconnecting" && !roomState.recovering;
+}
+
+/**
+ * The stage to render right now.
+ *
+ * Read in order, and the order is the safety property: nothing reaches the
+ * realtime branch until the broadcast has offered it, a credential has actually
+ * been minted, and the room is still alive.
+ */
+export function chooseBroadcastStage(input: BroadcastStageInput): BroadcastStage {
+  if (!input.realtimeAvailable) return "hls";
+  if (input.credentialsError) return "hls";
+  // PENDING, not "hls". Answering "hls" here mounted the HLS engine for the
+  // moment the ticket was in flight, and an HLS engine does not idle: it
+  // fetched the playlist and started pulling segments for a stage that was
+  // about to be replaced, so a realtime viewer downloaded the broadcast twice.
+  // Nothing is drawn until the answer is known.
+  if (!input.credentialsReady) return "pending";
+  if (realtimeIsOver(input.roomState)) return "hls";
+  return "realtime";
+}
+
+/**
+ * Did this viewer come DOWN to HLS, or were they always going to be here?
+ *
+ * The distinction is the whole content of the line the player shows. A
+ * broadcast that never offered realtime has nothing to explain, and a page that
+ * says "watching the standard stream" on every ordinary stream is a page that
+ * has taught its viewers to ignore the one time it matters.
+ *
+ * A token fetch still in flight is deliberately NOT a fallback. It resolves in
+ * a moment, and announcing a fallback that is about to be withdrawn is a line
+ * that flickers on every single load.
+ */
+export function broadcastFellBack(input: BroadcastStageInput): boolean {
+  if (!input.realtimeAvailable) return false;
+  if (input.credentialsError) return true;
+  if (!input.credentialsReady) return false;
+  return realtimeIsOver(input.roomState);
+}
+
+/** The one program feed, split into the elements that carry it. */
+export type BroadcastProgramTracks = {
+  /** Attach with `useRemoteTrack`. Absent means no video has arrived yet. */
+  videoProducerId?: string;
+  /** The publisher paused it at source. Their choice, not a failure. */
+  videoPaused: boolean;
+  /** The one program soundtrack. An array because it may legitimately be empty. */
+  audioProducerIds: readonly string[];
+};
+
+/**
+ * What to render out of the producers this viewer may actually receive.
+ *
+ * The live room holds exactly one publisher, `program:<broadcastId>`, with one
+ * video producer and one audio producer, and a viewer token's subscribe rule
+ * names that identity and nothing else. So there is no filtering to do here and
+ * deliberately none attempted: re-deriving the identity in the browser would
+ * give a second answer to a question the node has already answered, and the
+ * wrong answer is a black stage on a broadcast that is playing perfectly.
+ *
+ * The FIRST video is taken rather than the last. A studio that briefly
+ * republishes leaves two announced for a frame or two, and picking the newer
+ * one would swap the element's stream under a viewer mid-sentence.
+ *
+ * Audio is returned as a list rather than as one id because the cost of being
+ * wrong is asymmetric: a spare `<audio>` with no track attached does nothing at
+ * all, and a missed one is a broadcast with no sound.
+ */
+export function programTracks(producers: readonly ProducerEntry[]): BroadcastProgramTracks {
+  const video = producers.find((producer) => producer.kind === "video");
+  const audio = producers.filter((producer) => producer.kind === "audio");
+  return {
+    ...(video ? { videoProducerId: video.producerId } : {}),
+    videoPaused: video?.paused ?? false,
+    // ONE, deliberately, not every audio producer in the room.
+    //
+    // A broadcast has a single soundtrack: the studio's mix, published once by
+    // the program feed. If the room ever holds two (a republish after a
+    // reconnect racing the old producer's teardown), playing both is never the
+    // right answer, so the newer publication wins and the stale one is dropped
+    // rather than mixed in.
+    //
+    // This is a guard, not the fix for the doubled audio that was reported
+    // during the build: THAT was the player mounting the HLS stage while the
+    // viewer ticket was still in flight, so the same broadcast arrived twice,
+    // seconds apart, over two transports. See `chooseBroadcastStage`.
+    audioProducerIds: audio.length > 0 ? [audio[audio.length - 1]!.producerId] : [],
+  };
+}