@tribe-nest/media-client 0.1.0 → 0.2.1

package/src/room/room.ts

@@ -2,6 +2,7 @@ import type { EventFrame, MediaGrants } from "@tribe-nest/media-protocol";
 
 import {
   MediaSignal,
+  causeFromError,
   decideReconnect,
   initialRoomState,
   reduceRoomState,
@@ -80,14 +81,106 @@ export type MediaTrack = {
   track: MediaStreamTrack;
   /** Paused at the SOURCE, as the publisher left it. */
   paused: boolean;
+  /** The publisher's declared label, when the node relayed one. Rendering only. */
+  source?: string;
 };
 
+/** What a local track is, in the vocabulary the node checks against `publishKinds`. */
+export type LocalPublicationSource = "camera" | "microphone" | "screen";
+
+/**
+ * Every label this SDK publishes under.
+ *
+ * `program` is a COMPOSED feed rather than a device: a broadcast studio's
+ * rendered output, published so a server-side egress can restream it. It is
+ * not a capture, so it is never a "lost source" to re-offer a person after a
+ * drop, and `useLocalMedia`'s device controls never touch it. The node treats
+ * it as its track's kind (`requiredPublishKind`), so a token needs only
+ * `publishKinds: ["audio", "video"]`.
+ */
+export type PublishSourceLabel = LocalPublicationSource | "program";
+
+/**
+ * How to encode one publication, where the default is wrong.
+ *
+ * A camera takes the browser's defaults. A composed program feed does not:
+ * an RTMP restream needs H.264 (RTMP carries nothing else, and the egress
+ * copies rather than transcodes), and a 1080p canvas at the default bitrate
+ * is a smear. Both are per-publication facts, not per-room ones.
+ */
+export type PublishOptions = {
+  /** Pick this codec from the router's list. Ignored when the router lacks it. */
+  codec?: "h264" | "vp8";
+  /** Cap for the encoder, in kbit/s. Read as the TOP layer under simulcast. */
+  maxBitrateKbps?: number;
+  /**
+   * Send three spatial layers instead of one, so each consumer can be served
+   * the one its connection can carry.
+   *
+   * The choosing is not ours and does not need to be: mediasoup picks a layer
+   * per consumer from that transport's own bandwidth estimate, so a viewer on
+   * a poor line gets 360p rather than a stall, with nothing to implement on
+   * either end. What we decide is only whether the layers exist to choose
+   * from.
+   *
+   * Use it for a feed with an AUDIENCE. It is wrong for a camera in a small
+   * call, where everyone can carry the one encoding and the extra layers are
+   * encoder time spent on nobody.
+   *
+   * ## Why VP8 and not H.264
+   *
+   * Browser simulcast is reliable on VP8 and is not on H.264, where it depends
+   * on the hardware encoder and quietly degrades to one layer. A caller that
+   * needs H.264 downstream (an RTMP restream copies rather than transcodes)
+   * should publish one encoding and leave this off. The two are exclusive by
+   * design rather than by accident.
+   */
+  simulcast?: boolean;
+};
+
+/**
+ * The three layers, quarter / half / full.
+ *
+ * `scaleResolutionDownBy` rather than three bitrates, so the shape holds
+ * whatever resolution the caller is publishing. The rids are the conventional
+ * one-letter names every SFU and every browser log uses, which is worth more
+ * than a more descriptive name nobody would recognise in a WebRTC dump.
+ */
+const SIMULCAST_LAYERS = [
+  { rid: "q", scaleResolutionDownBy: 4, scalabilityMode: "L1T1" },
+  { rid: "h", scaleResolutionDownBy: 2, scalabilityMode: "L1T1" },
+  { rid: "f", scaleResolutionDownBy: 1, scalabilityMode: "L1T1" },
+] as const;
+
+/**
+ * What each layer may spend, given the caller's cap for the top one.
+ *
+ * Quarter resolution is a sixteenth of the pixels, but not a sixteenth of the
+ * bits: an encoder needs proportionally more per pixel at small sizes, and a
+ * layer starved below what its resolution costs is a layer that looks worse
+ * than it should while still being sent. A quarter and a tenth are the
+ * conventional split and are what mediasoup's own examples use.
+ */
+function simulcastEncodings(maxBitrateKbps: number | undefined): unknown[] {
+  const top = (maxBitrateKbps ?? 0) * 1000;
+  const share = [0.1, 0.25, 1];
+  return SIMULCAST_LAYERS.map((layer, index) => ({
+    ...layer,
+    ...(top ? { maxBitrate: Math.round(top * share[index]!) } : {}),
+  }));
+}
+
 export type LocalPublication = {
   producerId: string;
   kind: "audio" | "video";
-  source: string;
+  source: PublishSourceLabel;
   track: MediaStreamTrack;
   handle: MediaProducerHandle;
+  /**
+   * Paused at the source by `setPaused`. The capture is still open and the
+   * producer still exists; nothing is being sent. This is what a mute is.
+   */
+  paused: boolean;
 };
 
 export type MediaRoomOptions = {
@@ -122,17 +215,27 @@ export type MediaRoomOptions = {
 
 type Listener = () => void;
 
+type TransportSlot = {
+  ready: MediaTransport | undefined;
+  creating: Promise<MediaTransport> | undefined;
+};
+
 export class MediaRoom {
   private readonly signal: MediaSignal;
   private readonly device: MediaDevice;
-  private sendTransport: MediaTransport | undefined;
-  private recvTransport: MediaTransport | undefined;
+  /** One slot per direction: the finished transport, or the creation in flight. */
+  private readonly transports: Record<"send" | "recv", TransportSlot> = {
+    send: { ready: undefined, creating: undefined },
+    recv: { ready: undefined, creating: undefined },
+  };
   private iceServers: IceServer[] = [];
   private grantsValue: MediaGrants | undefined;
 
   private readonly consumers = new Map<string, MediaConsumerHandle>();
   private readonly tracksByProducer = new Map<string, MediaTrack>();
   private readonly publications = new Map<string, LocalPublication>();
+  /** Per publication: stop listening for the track ending on its own. */
+  private readonly trackEndWatchers = new Map<string, () => void>();
   private readonly listeners = new Set<Listener>();
   /** One in-flight subscribe per producer, so a burst of activeSpeakers frames
    * does not race itself into two consumers for one producer. */
@@ -158,23 +261,50 @@ export class MediaRoom {
     });
 
     this.signal.onAny((frame) => this.onFrame(frame));
-    this.signal.onClose((cause) => {
-      this.lastError = cause;
-      // Before the decision, and unconditionally. The transports are dead
-      // whatever happens next, and so is every capture that was feeding them.
-      this.teardownMedia();
-
-      if (cause.type === "closed_by_client") {
-        this.connection = "closed";
-        this.recovering = false;
-        this.emit();
-        return;
-      }
+    this.signal.onClose((cause) => this.onDisconnect(cause));
+  }
+
+  /**
+   * The one place that decides what happens after a connection ends, whether
+   * it ended after an hour or before a socket was ever opened.
+   */
+  private onDisconnect(cause: DisconnectCause): void {
+    this.lastError = cause;
+    // What the person was sending, before it is torn down. Recorded so the
+    // screen can say so once the room is back (see `lostPublicationSources`).
+    // A program feed is excluded: it is a studio's output, not something a
+    // person switched on, so nobody should be asked to switch it back on.
+    const wasPublishing = [
+      ...new Set(
+        [...this.publications.values()]
+          .map((p) => p.source)
+          .filter((s): s is LocalPublicationSource => s !== "program"),
+      ),
+    ];
+    // Before the decision, and unconditionally. The transports are dead
+    // whatever happens next, and so is every capture that was feeding them.
+    this.teardownMedia();
+    // The active set was an instruction about consumers on THIS connection,
+    // and those are gone. Left standing, it would be mistaken by the next
+    // `joined` for a set the new node had sent ahead of the snapshot.
+    if (this.stateValue.activeSpeakers.length > 0) {
+      this.stateValue = { ...this.stateValue, activeSpeakers: [] };
+    }
 
-      this.connection = "reconnecting";
-      this.recovering = this.scheduleReconnect(cause);
+    // `disposed` as well as the cause: `close()` is a client close whatever the
+    // socket's own account of it, and a room that has been closed must never
+    // report itself as coming back.
+    if (cause.type === "closed_by_client" || this.disposed) {
+      this.connection = "closed";
+      this.recovering = false;
       this.emit();
-    });
+      return;
+    }
+
+    if (wasPublishing.length > 0) this.lostSources = wasPublishing;
+    this.connection = "reconnecting";
+    this.recovering = this.scheduleReconnect(cause);
+    this.emit();
   }
 
   get state(): RoomState {
@@ -219,6 +349,7 @@ export class MediaRoom {
    */
   private trackSnapshot: MediaTrack[] = [];
   private publicationSnapshot: LocalPublication[] = [];
+  private lostSources: readonly LocalPublicationSource[] = NO_SOURCES;
 
   get tracks(): MediaTrack[] {
     return this.trackSnapshot;
@@ -228,6 +359,26 @@ export class MediaRoom {
     return this.publicationSnapshot;
   }
 
+  /**
+   * What the person was sending when the connection dropped, and is not now.
+   *
+   * A drop tears down every local publication and STOPS its capture (see
+   * `teardownMedia`): the camera light goes out, which is the right thing for a
+   * capture whose session has ended and the wrong thing to do silently to a
+   * capture whose session is about to resume. The room does not republish on
+   * its own. Capture is a browser permission with a UI consequence, and turning
+   * a person's camera back on without a press, possibly minutes later, is not a
+   * decision this layer gets to make. So instead it says what was lost, and the
+   * screen tells the person, who presses the button.
+   *
+   * Cleared per source when that source is published again, and wholesale by
+   * `close()`. A stable reference while unchanged, like every other snapshot
+   * here, because `useSyncExternalStore` reads it.
+   */
+  get lostPublicationSources(): readonly LocalPublicationSource[] {
+    return this.lostSources;
+  }
+
   /** Subscribe to changes. Returns an unsubscribe. */
   onChange(listener: Listener): () => void {
     this.listeners.add(listener);
@@ -235,6 +386,14 @@ export class MediaRoom {
   }
 
   async connect(): Promise<void> {
+    // Refused BEFORE touching any state. The signal refuses this too, but by
+    // then `connection` would already read "connecting" over a socket that is
+    // joined, and nothing would ever put it back.
+    const phase = this.signal.phase;
+    if (phase === "connecting" || phase === "joining" || phase === "joined") {
+      throw new Error("connect() called on a room that is already connecting or connected");
+    }
+
     this.cancelReconnect();
     // A retry is not a first connection, and saying "Connecting to the call"
     // over a call somebody is already in reads as though they had been thrown
@@ -242,7 +401,26 @@ export class MediaRoom {
     this.connection = this.reconnectAttempt > 0 ? "reconnecting" : "connecting";
     this.emit();
 
-    const joined = await this.signal.connect();
+    // A failed attempt normally reports itself through `signal.onClose`, which
+    // routes to `onDisconnect`. This watches for that report so a rejection
+    // that arrives WITHOUT one (nothing in the signal does that today; this is
+    // the belt to its braces) is still counted as a failed attempt rather than
+    // leaving `connection` on "connecting" with no retry booked and no error
+    // to show.
+    let disconnectReported = false;
+    const stopWatching = this.signal.onClose(() => {
+      disconnectReported = true;
+    });
+
+    let joined: Awaited<ReturnType<MediaSignal["connect"]>>;
+    try {
+      joined = await this.signal.connect();
+    } catch (error) {
+      if (!disconnectReported) this.onDisconnect(causeFromError(error));
+      throw error;
+    } finally {
+      stopWatching();
+    }
 
     // RULE 1: the device loads first. Everything below needs its capabilities.
     if (!this.device.loaded) {
@@ -268,6 +446,7 @@ export class MediaRoom {
     this.cancelReconnect();
     this.recovering = false;
     this.connection = "closed";
+    this.lostSources = NO_SOURCES;
     await this.signal.leave().catch(() => undefined);
     this.teardownMedia();
     this.emit();
@@ -308,8 +487,10 @@ export class MediaRoom {
       this.reconnectTimer = undefined;
       if (this.disposed) return;
       this.reconnectAttempt += 1;
-      // A failed attempt comes back through `signal.onClose`, which is the only
-      // place that decides. Swallowed here so a retry does not surface as an
+      // A failed attempt comes back through `onDisconnect`, which is the only
+      // place that decides, and that holds for an attempt that fails BEFORE it
+      // has a socket (the ticket endpoint refusing) as much as for one that
+      // drops after an hour. Swallowed here so a retry does not surface as an
       // unhandled rejection in the host application's console.
       void this.connect().catch(() => undefined);
     }, decision.delayMs);
@@ -333,14 +514,29 @@ export class MediaRoom {
    * `publishKinds`: a token granting audio only must not be able to publish a
    * screen share by relabelling it, and the node is where that is decided.
    */
-  async publish(track: MediaStreamTrack, source: "camera" | "microphone" | "screen"): Promise<LocalPublication> {
+  async publish(
+    track: MediaStreamTrack,
+    source: PublishSourceLabel,
+    options: PublishOptions = {},
+  ): Promise<LocalPublication> {
     const kind = track.kind === "audio" ? "audio" : "video";
     if (!this.device.canProduce(kind)) {
       throw new Error(`this browser cannot produce ${kind}`);
     }
 
     const transport = await this.ensureSendTransport();
-    const handle = await transport.produce({ track, appData: { source } });
+    const handle = await transport.produce({
+      track,
+      appData: { source },
+      ...(options.codec ? { codec: options.codec } : {}),
+      ...(options.simulcast
+        ? { encodings: simulcastEncodings(options.maxBitrateKbps) }
+        : options.maxBitrateKbps
+          ? { encodings: [{ maxBitrate: options.maxBitrateKbps * 1000 }] }
+          : {}),
+    });
+
+    if (source === "program") await keepProgramResolution(handle, this.options.onLog);
 
     const publication: LocalPublication = {
       producerId: handle.id,
@@ -348,16 +544,62 @@ export class MediaRoom {
       source,
       track,
       handle,
+      paused: false,
     };
     this.publications.set(handle.id, publication);
+    // A track can end WITHOUT us: the browser's own "Stop sharing" bar, a
+    // camera unplugged, a device revoked from the OS. Nothing about that reaches
+    // `unpublish`, so the node kept a producer nobody was feeding and the
+    // control above still read "Stop sharing" about a share that had ended.
+    this.trackEndWatchers.set(
+      handle.id,
+      whenTrackEnds(track, () => {
+        void this.unpublish(handle.id);
+      }),
+    );
+    if (source !== "program" && this.lostSources.includes(source)) {
+      this.lostSources = this.lostSources.filter((s) => s !== source);
+      if (this.lostSources.length === 0) this.lostSources = NO_SOURCES;
+    }
     this.emit();
     return publication;
   }
 
+  /**
+   * Swap the capture behind a publication, keeping the producer.
+   *
+   * A device change (another camera, another microphone) is this, and it is
+   * deliberately NOT unpublish plus publish: that changes the producer id,
+   * which is the key every consumer's tile and every studio's scene holds, so
+   * a switched camera vanished from the stage until somebody re-added it.
+   * The old capture is stopped here; the new one is watched for ending the
+   * same way the first was.
+   */
+  async replaceTrack(producerId: string, track: MediaStreamTrack): Promise<void> {
+    const publication = this.publications.get(producerId);
+    if (!publication) throw new Error("no such publication");
+    if (track.kind !== publication.kind) throw new Error(`a ${publication.kind} publication cannot carry ${track.kind}`);
+    if (track === publication.track) return;
+
+    await publication.handle.replaceTrack(track);
+    this.trackEndWatchers.get(producerId)?.();
+    publication.track.stop();
+    this.trackEndWatchers.set(
+      producerId,
+      whenTrackEnds(track, () => {
+        void this.unpublish(producerId);
+      }),
+    );
+    this.publications.set(producerId, { ...publication, track });
+    this.emit();
+  }
+
   async unpublish(producerId: string): Promise<void> {
     const publication = this.publications.get(producerId);
     if (!publication) return;
 
+    this.trackEndWatchers.get(producerId)?.();
+    this.trackEndWatchers.delete(producerId);
     publication.handle.close();
     publication.track.stop();
     this.publications.delete(producerId);
@@ -367,16 +609,30 @@ export class MediaRoom {
     this.emit();
   }
 
+  /**
+   * Mute or unmute at the source, keeping the capture and the producer.
+   *
+   * This is what a Mute button does, and it is deliberately NOT unpublish plus
+   * publish. Every publish begins with `getUserMedia`, and Safari asks
+   * permission on every call to it, so a toggle built on republishing put a
+   * permission prompt in front of the person on every unmute. The producer is
+   * paused (mediasoup disables the track, so nothing is sent), the node is told
+   * so the other side sees `producerPaused`, and resuming is instant and asks
+   * nobody anything.
+   */
   async setPaused(producerId: string, paused: boolean): Promise<void> {
     const publication = this.publications.get(producerId);
-    if (!publication) return;
+    if (!publication || publication.paused === paused) return;
 
     if (paused) publication.handle.pause();
     else publication.handle.resume();
+    // A new object, so the snapshot moves and a screen reading `paused` follows.
+    // Emitted before the round trip: the local effect is already true.
+    this.publications.set(producerId, { ...publication, paused });
+    this.emit();
     await this.signal
       .request({ method: paused ? "pauseProducer" : "resumeProducer", producerId })
       .catch(() => undefined);
-    this.emit();
   }
 
   // -------------------------------------------------------------------------
@@ -449,6 +705,7 @@ export class MediaRoom {
       kind: response.kind,
       track: consumer.track,
       paused: entry.paused,
+      ...(entry.source ? { source: entry.source } : {}),
     });
 
     // RULE 3: resume LAST. The node creates every consumer paused, so media
@@ -463,22 +720,73 @@ export class MediaRoom {
   // transports
   // -------------------------------------------------------------------------
 
-  /** RULE 2: lazily, and once. */
-  private async ensureSendTransport(): Promise<MediaTransport> {
-    if (this.sendTransport) return this.sendTransport;
+  /**
+   * RULE 2: lazily, and once.
+   *
+   * "Once" has to hold under CONCURRENCY, not just in sequence. `createTransport`
+   * is a round trip to the node, and `syncSubscriptions` fans out with
+   * `Promise.all`, so one `activeSpeakers` frame naming four producers puts
+   * four callers through here in the same tick. A check of the finished
+   * transport followed by an await let all four pass the check and send four
+   * `createTransport(recv)`: the node caps transports per session, so the
+   * fourth was the last one this session would ever get and the person's own
+   * Unmute was refused with `capacity` for the rest of the call. So the thing
+   * memoised is the in-flight PROMISE, and it is memoised before anything is
+   * awaited.
+   *
+   * A creation that fails is forgotten, so the next caller tries again rather
+   * than inheriting a rejection for ever; and `teardownMedia` forgets both,
+   * because a transport created against a connection that has since died
+   * belongs to that connection, not to the one that replaces it.
+   */
+  private ensureSendTransport(): Promise<MediaTransport> {
+    return this.ensureTransport("send");
+  }
+
+  private ensureRecvTransport(): Promise<MediaTransport> {
+    return this.ensureTransport("recv");
+  }
+
+  private ensureTransport(direction: "send" | "recv"): Promise<MediaTransport> {
+    const slot = this.transports[direction];
+    if (slot.ready) return Promise.resolve(slot.ready);
+    if (slot.creating) return slot.creating;
+
+    const creating = this.createTransport(direction);
+    slot.creating = creating;
+    creating.then(
+      (transport) => {
+        if (slot.creating !== creating) {
+          // Torn down while the round trip was in flight. The connection this
+          // transport was created for is gone, so it is closed rather than kept
+          // for the next one.
+          transport.close();
+          return;
+        }
+        slot.ready = transport;
+        slot.creating = undefined;
+      },
+      () => {
+        if (slot.creating === creating) slot.creating = undefined;
+      },
+    );
+    return creating;
+  }
 
-    const description = (await this.signal.request({
-      method: "createTransport",
-      direction: "send",
-    })) as TransportDescription;
+  private async createTransport(direction: "send" | "recv"): Promise<MediaTransport> {
+    const description = (await this.signal.request({ method: "createTransport", direction })) as TransportDescription;
+    const onConnect = async (dtlsParameters: unknown) => {
+      await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
+    };
 
-    this.sendTransport = this.device.createSendTransport({
+    if (direction === "recv") {
+      return this.device.createRecvTransport({ description, iceServers: this.iceServers, handlers: { onConnect } });
+    }
+    return this.device.createSendTransport({
       description,
       iceServers: this.iceServers,
       handlers: {
-        onConnect: async (dtlsParameters) => {
-          await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
-        },
+        onConnect,
         onProduce: async ({ kind, rtpParameters, appData }) => {
           const produced = (await this.signal.request({
             method: "produce",
@@ -491,27 +799,6 @@ export class MediaRoom {
         },
       },
     });
-    return this.sendTransport;
-  }
-
-  private async ensureRecvTransport(): Promise<MediaTransport> {
-    if (this.recvTransport) return this.recvTransport;
-
-    const description = (await this.signal.request({
-      method: "createTransport",
-      direction: "recv",
-    })) as TransportDescription;
-
-    this.recvTransport = this.device.createRecvTransport({
-      description,
-      iceServers: this.iceServers,
-      handlers: {
-        onConnect: async (dtlsParameters) => {
-          await this.signal.request({ method: "connectTransport", transportId: description.transportId, dtlsParameters });
-        },
-      },
-    });
-    return this.recvTransport;
   }
 
   // -------------------------------------------------------------------------
@@ -564,16 +851,22 @@ export class MediaRoom {
     this.consumers.clear();
     this.tracksByProducer.clear();
 
+    for (const detach of this.trackEndWatchers.values()) detach();
+    this.trackEndWatchers.clear();
     for (const publication of this.publications.values()) {
       publication.handle.close();
       publication.track.stop();
     }
     this.publications.clear();
 
-    this.sendTransport?.close();
-    this.recvTransport?.close();
-    this.sendTransport = undefined;
-    this.recvTransport = undefined;
+    for (const slot of Object.values(this.transports)) {
+      slot.ready?.close();
+      slot.ready = undefined;
+      // A creation still in flight belongs to the connection that just died.
+      // Forgetting it here is what makes `ensureTransport` close the result
+      // when it lands, and what lets the next connection create its own.
+      slot.creating = undefined;
+    }
   }
 
   private emit(): void {
@@ -593,8 +886,70 @@ export class MediaRoom {
   }
 }
 
+const NO_SOURCES: readonly LocalPublicationSource[] = [];
+
+/**
+ * Call `onEnded` when a track ends on its own, and return the detach.
+ *
+ * `ended` fires when the SOURCE goes away (the browser's share bar, a device
+ * unplugged), and not for our own `track.stop()`, which is what lets
+ * `unpublish` stop the track without re-entering itself. Guarded because a
+ * track outside a browser (this package's specs hand the room bare objects) is
+ * not an `EventTarget`; in every browser it is.
+ */
+function whenTrackEnds(track: MediaStreamTrack, onEnded: () => void): () => void {
+  const target = track as Partial<Pick<EventTarget, "addEventListener" | "removeEventListener">>;
+  if (typeof target.addEventListener !== "function" || typeof target.removeEventListener !== "function") {
+    return () => undefined;
+  }
+  target.addEventListener("ended", onEnded);
+  return () => target.removeEventListener?.("ended", onEnded);
+}
+
 export async function connectToRoom(options: MediaRoomOptions): Promise<MediaRoom> {
   const room = new MediaRoom(options);
   await room.connect();
   return room;
 }
+
+/**
+ * The program feed keeps its RESOLUTION and gives up frame rate instead.
+ *
+ * Chrome's default for a video sender is `balanced`, which under a low
+ * bandwidth estimate or CPU pressure scales the encode down. For a camera tile
+ * that is the right trade. For the program feed it is wrong twice over.
+ *
+ * First, this feed is the broadcast: a 1080p composite arriving at Twitch as
+ * 270p is the product, not a degraded preview. Twitch reported exactly that.
+ *
+ * Second, and worse, the RTMP leg cannot survive the CHANGE. The egress muxes
+ * the feed with `-c:v copy`, and an FLV header carries the dimensions once, at
+ * the start. When Chrome adapts resolution mid-stream the SPS changes under a
+ * header that still describes the old size, and the player refuses the stream:
+ *
+ *   Your browser encountered an error while decoding the video. (Error #3000)
+ *
+ * while ffmpeg reports `drop_frames=0`, a healthy bitrate, and an established
+ * socket. Nothing on the server can see it.
+ *
+ * `maintain-resolution` makes the encoder drop frames rather than pixels, so
+ * the SPS stays put for the life of the broadcast.
+ *
+ * Best-effort: the setting is not universally implemented, and a browser that
+ * ignores it is no worse off than before. Only the program source, because a
+ * camera is better off shrinking than freezing.
+ */
+async function keepProgramResolution(
+  handle: MediaProducerHandle,
+  onLog?: (level: "warn" | "debug", message: string, detail?: unknown) => void,
+): Promise<void> {
+  const sender = handle.rtpSender;
+  if (!sender || handle.kind !== "video") return;
+  try {
+    const params = sender.getParameters() as RTCRtpSendParameters & { degradationPreference?: string };
+    params.degradationPreference = "maintain-resolution";
+    await sender.setParameters(params);
+  } catch (err) {
+    onLog?.("warn", "could not pin the program feed's resolution", err);
+  }
+}