@tribe-nest/media-client 0.1.1 → 0.2.1

package/src/room/room.ts

@@ -81,15 +81,99 @@ 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: LocalPublicationSource;
+  source: PublishSourceLabel;
   track: MediaStreamTrack;
   handle: MediaProducerHandle;
   /**
@@ -188,7 +272,15 @@ export class MediaRoom {
     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`).
-    const wasPublishing = [...new Set([...this.publications.values()].map((p) => p.source))];
+    // 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();
@@ -422,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: LocalPublicationSource): 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,
@@ -450,7 +557,7 @@ export class MediaRoom {
         void this.unpublish(handle.id);
       }),
     );
-    if (this.lostSources.includes(source)) {
+    if (source !== "program" && this.lostSources.includes(source)) {
       this.lostSources = this.lostSources.filter((s) => s !== source);
       if (this.lostSources.length === 0) this.lostSources = NO_SOURCES;
     }
@@ -458,6 +565,35 @@ export class MediaRoom {
     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;
@@ -569,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
@@ -774,3 +911,45 @@ export async function connectToRoom(options: MediaRoomOptions): Promise<MediaRoo
   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);
+  }
+}