mediasfu-shared 1.2.6 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasfu-shared",
-  "version": "1.2.6",
+  "version": "1.3.0",
   "description": "mediasfu-shared – framework-agnostic WebRTC runtime for MediaSFU. Room helpers, mediasoup signaling, socket management, media state, and TypeScript types for React, Vue, Angular, Svelte, and plain TS.",
   "main": "dist/index.cjs",
   "module": "dist/index.js",
@@ -45,7 +45,8 @@
     "build-docs": "typedoc",
     "dev": "vite build --watch",
     "test:staging:smoke": "npm run build && node ./scripts/staging-room-smoke-test.cjs",
-    "type-check": "tsc --noEmit"
+    "type-check": "tsc --noEmit",
+    "test:sdk-parity": "node tests/sdkParity.test.cjs"
   },
   "keywords": [
     "mediasfu",

package/src/ProducerClient/producerClientEmits/roomVideoPolicy.ts

@@ -0,0 +1,41 @@
+/**
+ * Camera-only policy. Screen-sharing and audio encodings are unchanged.
+ * Server capacity wins over a hint; recording does not increase camera bitrate.
+ */
+export interface CameraEncodingPolicy {
+  simulcastOff?: boolean;
+  roomCapacity?: number;
+}
+
+export function cameraSimulcastOff(
+  eventType: string,
+  capacity: number | undefined,
+  options: CameraEncodingPolicy = {},
+): boolean {
+  const roomCapacity = capacity ?? options.roomCapacity;
+  return options.simulcastOff === true || eventType === 'chat' || roomCapacity === 2;
+}
+
+type CameraEncoding = {
+  rid?: string;
+  scaleResolutionDownBy?: number;
+  scalabilityMode?: string;
+};
+
+/** Mutate only the fresh room preset, preserving its original-preset lineage. */
+export function applyCameraEncodingPolicy<T extends { encodings: CameraEncoding[] }>(
+  params: T,
+  singleEncoding: boolean,
+): T {
+  if (!singleEncoding || !params.encodings.length) return params;
+  // Presets conventionally put the full-resolution layer last. Do not assume
+  // that order for custom presets; select the least downscaled encoding.
+  const full = params.encodings.reduce((best, encoding) =>
+    (encoding.scaleResolutionDownBy ?? 1) <= (best.scaleResolutionDownBy ?? 1)
+      ? encoding : best);
+  const encoding = { ...full, scaleResolutionDownBy: 1 };
+  delete encoding.rid;
+  if (encoding.scalabilityMode) encoding.scalabilityMode = 'L1T3';
+  params.encodings = [encoding];
+  return params;
+}

package/src/ProducerClient/producerClientEmits/updateRoomParametersClient.ts

@@ -1,3 +1,4 @@
+import { applyCameraEncodingPolicy, cameraSimulcastOff } from './roomVideoPolicy';
 /* eslint-disable eqeqeq */
 import { RtpCapabilities } from 'mediasoup-client/types';
 import {
@@ -69,6 +70,10 @@ export interface UpdateRoomParametersClientParameters {
   islevel: string;
   showAlert?: ShowAlert;
   data: ResponseJoinRoom;
+  /** Disable camera simulcast even in larger rooms. */
+  simulcastOff?: boolean;
+  /** Capacity hint used only when the server does not return capacity. */
+  roomCapacity?: number;
   updateRtpCapabilities: (rtpCapabilities: RtpCapabilities | null) => void;
   updateRoomRecvIPs: (roomRecvIPs: string[]) => void;
   updateMeetingRoomParams: (meetingRoomParams: MeetingRoomParams | null) => void;
@@ -112,17 +117,23 @@ export interface UpdateRoomParametersClientParameters {
   updateRecordingPreferredOrientation: (orientation: string) => void;
   updateRecordingSupportForOtherOrientation: (support: boolean) => void;
   updateRecordingMultiFormatsSupport: (support: boolean) => void;
+  /** Records whether the media server accepts screen-share audio (join response `supportsScreenAudio`). */
+  updateSupportsScreenAudio?: (supported: boolean) => void;
   updateRecordingVideoOptions: (options: string) => void;
   updateRecordingAudioOptions: (options: string) => void;
 }
 
 export type UpdateRoomParametersClientOptions = {
   parameters: UpdateRoomParametersClientParameters;
+  /** Disable camera simulcast even in larger rooms. */
+  simulcastOff?: boolean;
+  /** Capacity hint used only when the server does not return capacity. */
+  roomCapacity?: number;
 };
 
 export type UpdateRoomParametersClientType = (options: UpdateRoomParametersClientOptions) => void;
 
-export const updateRoomParametersClient = ({ parameters }: UpdateRoomParametersClientOptions): void => {
+export const updateRoomParametersClient = ({ parameters, simulcastOff = parameters.simulcastOff, roomCapacity = parameters.roomCapacity }: UpdateRoomParametersClientOptions): void => {
   try {
     const {
       screenPageLimit,
@@ -175,6 +186,7 @@ export const updateRoomParametersClient = ({ parameters }: UpdateRoomParametersC
       updateRecordingPreferredOrientation,
       updateRecordingSupportForOtherOrientation,
       updateRecordingMultiFormatsSupport,
+      updateSupportsScreenAudio,
       updateRecordingVideoOptions,
       updateRecordingAudioOptions,
       updateMainHeightWidth,
@@ -212,6 +224,7 @@ export const updateRoomParametersClient = ({ parameters }: UpdateRoomParametersC
     updateRecordingPreferredOrientation(data.recordingParams.recordingPreferredOrientation);
     updateRecordingSupportForOtherOrientation(data.recordingParams.recordingSupportForOtherOrientation);
     updateRecordingMultiFormatsSupport(data.recordingParams.recordingMultiFormatsSupport);
+    updateSupportsScreenAudio?.(data.supportsScreenAudio === true);
 
     updateItemPageLimit(data.meetingRoomParams.itemPageLimit);
     updateEventType(data.meetingRoomParams.type);
@@ -354,26 +367,11 @@ export const updateRoomParametersClient = ({ parameters }: UpdateRoomParametersC
       });
     }
 
-    if (data.recordingParams.recordingVideoSupport) {
-      vParamsValue.encodings.forEach((encoding: Partial<VParamsType['encodings'][0]>) => {
-        if (encoding.maxBitrate) {
-          encoding.maxBitrate = Math.floor(encoding.maxBitrate * 1.2);
-        }
-      });
-
-      hParamsValue.encodings.forEach((encoding: Partial<HParamsType['encodings'][0]>) => {
-        if (encoding.maxBitrate) {
-          encoding.maxBitrate = Math.floor(encoding.maxBitrate * 1.2);
-        }
-      });
-
-      if (hParamsValue.codecOptions && hParamsValue.codecOptions.videoGoogleStartBitrate) {
-        hParamsValue.codecOptions.videoGoogleStartBitrate = Math.floor(hParamsValue.codecOptions.videoGoogleStartBitrate * 1.2);
-      }
-      if (vParamsValue.codecOptions && vParamsValue.codecOptions.videoGoogleStartBitrate) {
-        vParamsValue.codecOptions.videoGoogleStartBitrate = Math.floor(vParamsValue.codecOptions.videoGoogleStartBitrate * 1.2);
-      }
-    }
+    const singleCameraEncoding = cameraSimulcastOff(data.meetingRoomParams.type, data.capacity, {
+      simulcastOff, roomCapacity,
+    });
+    applyCameraEncodingPolicy(hParamsValue, singleCameraEncoding);
+    applyCameraEncodingPolicy(vParamsValue, singleCameraEncoding);
 
     updateVidCons(vidCons);
     updateFrameRate(frameRateValue);

package/src/consumers/closeAndResize.ts

@@ -8,6 +8,8 @@ import {
 
 export interface CloseAndResizeParameters extends ReorderStreamsParameters, PrepopulateUserMediaParameters, RePortParameters {
   allAudioStreams: (Stream | Participant)[];
+  /** Rendered audio-only players (React elements, Vue/Angular component descriptors). */
+  audioOnlyStreams?: any[];
   allVideoStreams: (Stream | Participant)[];
   activeNames: string[];
   participants: Participant[];
@@ -32,6 +34,7 @@ export interface CloseAndResizeParameters extends ReorderStreamsParameters, Prep
   updateMainWindow: boolean;
   updateActiveNames: (activeNames: string[]) => void;
   updateAllAudioStreams: (allAudioStreams: (Stream | Participant)[]) => void;
+  updateAudioOnlyStreams?: (audioOnlyStreams: any[]) => void;
   updateShareScreenStarted: (shareScreenStarted: boolean) => void;
   updateUpdateMainWindow: (updateMainWindow: boolean) => void;
   updateNewLimitedStreams: (newLimitedStreams: (Stream | Participant)[]) => void;
@@ -176,6 +179,7 @@ export const closeAndResize = async ({ producerId, kind, parameters }: CloseAndR
 
   let {
     allAudioStreams,
+    audioOnlyStreams = [],
     allVideoStreams,
     activeNames,
     participants,
@@ -201,6 +205,7 @@ export const closeAndResize = async ({ producerId, kind, parameters }: CloseAndR
     updateMainWindow,
     updateActiveNames,
     updateAllAudioStreams,
+    updateAudioOnlyStreams,
     updateAllVideoStreams,
 
     updateShareScreenStarted,
@@ -235,6 +240,15 @@ export const closeAndResize = async ({ producerId, kind, parameters }: CloseAndR
 
     updateAllAudioStreams(allAudioStreams);
 
+    // Audio-only players (mic and screen audio) are stored separately from allAudioStreams. Leaving one mounted after
+    // its producer closes means a rejoin adds a second player, heard as echo or duplicate speech.
+    const playerProducerId = (element: any): string =>
+      String(element?.props?.remoteProducerId ?? element?.inputs?.remoteProducerId ?? element?.key ?? '');
+    if (audioOnlyStreams.some((element: any) => playerProducerId(element) === producerId)) {
+      audioOnlyStreams = audioOnlyStreams.filter((element: any) => playerProducerId(element) !== producerId);
+      updateAudioOnlyStreams?.(audioOnlyStreams);
+    }
+
     if (recordingDisplayType == "video" && recordingVideoOptimized == true) {
       // optimize the video display
     } else {

package/src/consumers/connectIps.ts

@@ -1,8 +1,11 @@
  
-import { connectSocket } from "../../src/sockets/SocketManager";
+import { connectSocket } from "../sockets/SocketManager";
 import { newPipeProducer } from "./socketReceiveMethods/newPipeProducer";
 import { producerClosed } from "./socketReceiveMethods/producerClosed";
 import { joinConsumeRoom } from "./socketReceiveMethods/joinConsumeRoom";
+import { markScreenAudioProducer } from "./screenAudio";
+import { consumerBackupPreferDelay } from "./consumerBackupPreference";
+import { isMediaSocketConnectError } from "../sockets/mediaSocketErrors";
 import type { Device } from 'mediasoup-client/types';
 import {
   ReorderStreamsParameters, ReorderStreamsType, NewPipeProducerParameters, NewPipeProducerType, ProducerClosedType,
@@ -36,9 +39,9 @@ export interface ConnectIpsOptions {
 // Export the type definition for the function
 export type ConnectIpsType = (options: ConnectIpsOptions) => Promise<[Record<string, any>[], string[]]>;
 
-// Keep the reservation local to one room engine's socket collection. Separate
-// rooms may legitimately consume from the same endpoint and must not share a
-// socket, while overlapping updates for one room must serialize that endpoint.
+// Scope pending connections to the caller's socket collection. This prevents
+// overlapping room/domain updates from opening the same consume endpoint more
+// than once without sharing sockets between independent room engines.
 const pendingConsumeConnections = new WeakMap<
   object,
   Map<string, Promise<boolean>>
@@ -47,6 +50,28 @@ const pendingConsumeConnections = new WeakMap<
 const normalizeConsumeEndpoint = (ip: string): string =>
   ip.trim().toLowerCase().replace(/\.$/, "");
 
+/**
+ * Consume endpoints that refused these credentials (`connection-rejected` with a permanent reason). Domain updates call
+ * connectIps again and again; without this every update would retry the same refusal. Keyed by the caller's socket
+ * collection so another room (new credentials) starts clean.
+ */
+export const CONSUME_REJECTION_COOLDOWN_MS = 60000;
+const rejectedConsumeEndpoints = new WeakMap<object, Map<string, number>>();
+
+const consumeEndpointRecentlyRejected = (owner: object, endpoint: string): boolean => {
+  const at = rejectedConsumeEndpoints.get(owner)?.get(endpoint);
+  return at !== undefined && Date.now() - at < CONSUME_REJECTION_COOLDOWN_MS;
+};
+
+const rememberConsumeEndpointRejection = (owner: object, endpoint: string): void => {
+  let byEndpoint = rejectedConsumeEndpoints.get(owner);
+  if (!byEndpoint) {
+    byEndpoint = new Map<string, number>();
+    rejectedConsumeEndpoints.set(owner, byEndpoint);
+  }
+  byEndpoint.set(endpoint, Date.now());
+};
+
 const hasConsumeEndpoint = (
   consumeSockets: ConsumeSocket[],
   endpoint: string
@@ -59,6 +84,7 @@ const hasConsumeEndpoint = (
     const socket = socketObj[ip];
     if (socket?.connected && socket.id) return true;
 
+    // A dead entry must not suppress the next room's connection attempt.
     socket?.removeAllListeners?.();
     socket?.disconnect?.();
     consumeSockets.splice(index, 1);
@@ -176,7 +202,9 @@ export const connectIps = async ({
       return [consume_sockets, roomRecvIPs];
     }
 
+    const rejectionOwner: object = parameters?.socket || consume_sockets;
     for (const ip of remIP) {
+      if (consumeEndpointRecentlyRejected(rejectionOwner, normalizeConsumeEndpoint(ip))) continue;
       const releaseReservation = await reserveConsumeEndpoint(
         consume_sockets,
         ip,
@@ -191,6 +219,20 @@ export const connectIps = async ({
         remote_sock = await connectSocket({ apiUserName, apiKey, apiToken, link: `https://${ip}.mediasfu.com` });
 
         if (remote_sock.id) {
+          let consumeRoomReady = false;
+          const pendingProducers: Array<{
+            producerId: string;
+            islevel: string;
+            isTranslation?: boolean;
+            translationMeta?: {
+              speakerId: string;
+              speakerName: string;
+              language: string;
+              originalProducerId?: string;
+              isSpeakerControlled?: boolean;
+            };
+          }> = [];
+
           // Check if the IP is in the roomRecvIPs, if not, add it
           if (!roomRecvIPs.includes(ip)) {
             roomRecvIPs.push(ip);
@@ -198,7 +240,21 @@ export const connectIps = async ({
           }
 
           // Handle new pipe producer event
-          remote_sock.on("new-pipe-producer", async ({ producerId, islevel, isTranslation, translationMeta }: { producerId: string; islevel: string; isTranslation?: boolean; translationMeta?: { speakerId: string; speakerName: string; language: string; originalProducerId?: string; isSpeakerControlled?: boolean } }) => {
+          const consumeProducer = async ({ producerId, islevel, isTranslation, translationMeta, mediaTag }: { producerId: string; islevel: string; isTranslation?: boolean; translationMeta?: { speakerId: string; speakerName: string; language: string; originalProducerId?: string; isSpeakerControlled?: boolean }; mediaTag?: string }) => {
+            // Screen-share audio is tagged by the server; remember it before the consumer resumes.
+            markScreenAudioProducer(producerId, mediaTag);
+            if (!consumeRoomReady) {
+              pendingProducers.push({ producerId, islevel, isTranslation, translationMeta });
+              return;
+            }
+            // A busy node with a connected backup: give the backup's announcement a moment to win (same producer id).
+            const preferDelay = isTranslation ? 0 : consumerBackupPreferDelay(
+              ip,
+              (parameters.getUpdatedAllParams?.() as any)?.consume_sockets as any
+            );
+            if (preferDelay > 0) {
+              await new Promise((resolve) => setTimeout(resolve, preferDelay));
+            }
             if (newProducerMethod) {
               await newProducerMethod({
                 producerId,
@@ -209,7 +265,8 @@ export const connectIps = async ({
                 translationMeta,
               });
             }
-          });
+          };
+          remote_sock.on("new-pipe-producer", consumeProducer);
 
           // Handle producer closed event
           remote_sock.on("producer-closed", async ({ remoteProducerId }: { remoteProducerId: string }) => {
@@ -231,6 +288,18 @@ export const connectIps = async ({
             }
           }
 
+          // Events can arrive after the socket connects but before it has
+          // joined the consuming room. Emitting transport requests during that
+          // window receives no acknowledgement and poisons global de-duplication.
+          // The join's producer sweep covers current producers; flushing the
+          // queue closes the event/sweep gap, and signal-level de-duplication
+          // makes overlap harmless.
+          const queuedProducers = pendingProducers.splice(0);
+          consumeRoomReady = true;
+          for (const producer of queuedProducers) {
+            await consumeProducer(producer);
+          }
+
           // Add the remote socket to the consume_sockets array
           consume_sockets.push({ [ip]: remote_sock });
           updateConsume_sockets(consume_sockets);
@@ -256,8 +325,12 @@ export const connectIps = async ({
           });
         }
       } catch (error) {
-        // Handle the error
-        console.log("connectIps error", error);
+        if (isMediaSocketConnectError(error) && !error.retryable) {
+          rememberConsumeEndpointRejection(rejectionOwner, normalizeConsumeEndpoint(ip));
+          console.warn(`connectIps: ${ip} refused this room (${error.reason}); not retrying for ${CONSUME_REJECTION_COOLDOWN_MS / 1000} s.`, error.message);
+        } else {
+          console.log("connectIps error", error);
+        }
       } finally {
         if (!connected && remote_sock) {
           remote_sock.removeAllListeners?.();

package/src/consumers/connectSendTransportScreenAudio.ts

@@ -0,0 +1,184 @@
+import type { Producer, Transport } from "mediasoup-client/types";
+import { Socket } from "socket.io-client";
+import {
+  SCREEN_AUDIO_CODEC_OPTIONS,
+  SCREEN_AUDIO_MEDIA_TAG,
+  recallScreenAudioProducer,
+  rememberScreenAudioProducer,
+  shouldShareScreenAudio,
+} from "./screenAudio";
+
+export interface ScreenAudioParameters {
+  socket: Socket;
+  producerTransport: Transport | null;
+  screenProducer?: Producer | null;
+  screenAudioProducer?: Producer | null;
+  supportsScreenAudio?: boolean;
+  screenAudioEnabled?: boolean;
+  updateScreenAudioProducer?: (producer: Producer | null) => void;
+  getUpdatedAllParams: () => ScreenAudioParameters;
+  [key: string]: any;
+}
+
+export interface ConnectSendTransportScreenAudioOptions {
+  stream: MediaStream;
+  parameters: ScreenAudioParameters;
+  /** Wait before the single retry when the server has not registered the screen share yet. */
+  retryDelayMs?: number;
+}
+
+export type ConnectSendTransportScreenAudioType = (
+  options: ConnectSendTransportScreenAudioOptions
+) => Promise<Producer | null>;
+
+export interface DisconnectSendTransportScreenAudioOptions {
+  parameters: ScreenAudioParameters;
+  /** Also tell the server (the screen share continues). Not needed when the whole screen share stops. */
+  notifyServer?: boolean;
+}
+
+export type DisconnectSendTransportScreenAudioType = (
+  options: DisconnectSendTransportScreenAudioOptions
+) => Promise<void>;
+
+const currentScreenAudioProducer = (parameters: ScreenAudioParameters): Producer | null =>
+  parameters.screenAudioProducer || recallScreenAudioProducer(parameters.socket);
+
+const storeScreenAudioProducer = (parameters: ScreenAudioParameters, producer: Producer | null) => {
+  rememberScreenAudioProducer(parameters.socket, producer);
+  parameters.updateScreenAudioProducer?.(producer);
+};
+
+/**
+ * Closes the screen-audio producer, if any. Safe to call when none exists.
+ *
+ * @example
+ * ```typescript
+ * await disconnectSendTransportScreenAudio({ parameters, notifyServer: true });
+ * ```
+ */
+export const disconnectSendTransportScreenAudio: DisconnectSendTransportScreenAudioType = async ({
+  parameters,
+  notifyServer = false,
+}) => {
+  const params = parameters.getUpdatedAllParams ? parameters.getUpdatedAllParams() : parameters;
+  const producer = currentScreenAudioProducer(params);
+  if (!producer) return;
+  try {
+    if (!producer.closed) producer.close();
+  } catch {
+    // already closed
+  }
+  storeScreenAudioProducer(params, null);
+  if (notifyServer) {
+    try {
+      params.socket?.emit("closeScreenAudioProducer");
+    } catch {
+      // the server also closes it with the screen share
+    }
+  }
+};
+
+export interface ToggleScreenAudioOptions {
+  parameters: ScreenAudioParameters;
+  /** Force a state; omitted = toggle. */
+  paused?: boolean;
+}
+
+/**
+ * Mutes or unmutes the sharer's screen audio without stopping the screen share (listeners hear silence while muted).
+ * Returns the new muted state, or null when no screen audio is being shared.
+ *
+ * @example
+ * ```typescript
+ * const muted = toggleScreenAudio({ parameters });
+ * ```
+ */
+export const toggleScreenAudio = ({ parameters, paused }: ToggleScreenAudioOptions): boolean | null => {
+  const params = parameters.getUpdatedAllParams ? parameters.getUpdatedAllParams() : parameters;
+  const producer = currentScreenAudioProducer(params);
+  if (!producer || producer.closed) return null;
+  const next = paused ?? !producer.paused;
+  if (next && !producer.paused) producer.pause();
+  if (!next && producer.paused) producer.resume();
+  params.updateScreenAudioProducer?.(producer);
+  return producer.paused;
+};
+
+const produceOnce = async (transport: Transport, track: MediaStreamTrack): Promise<Producer | null> => {
+  const producer = await transport.produce({
+    track,
+    codecOptions: SCREEN_AUDIO_CODEC_OPTIONS,
+    appData: { mediaTag: SCREEN_AUDIO_MEDIA_TAG },
+    // The track belongs to the screen share stream, which stops it with the share.
+    stopTracks: false,
+  });
+  // A rejected produce resolves without a server id: drop the local sender.
+  if (!producer?.id) {
+    try { producer?.close(); } catch { /* nothing to close */ }
+    return null;
+  }
+  return producer;
+};
+
+/**
+ * Publishes the audio track of a screen-share stream as a "screen-audio" producer on the existing send transport.
+ * Call it after the screen video producer exists. It returns null (and the screen share continues without audio)
+ * when the stream has no audio, the server does not support screen audio, or the app turned it off.
+ *
+ * The producer mirrors the screen producer: it pauses, resumes and closes with it, and it closes alone (telling the
+ * server) when its own track ends.
+ *
+ * @example
+ * ```typescript
+ * const producer = await connectSendTransportScreenAudio({ stream: screenStream, parameters });
+ * ```
+ */
+export const connectSendTransportScreenAudio: ConnectSendTransportScreenAudioType = async ({
+  stream,
+  parameters,
+  retryDelayMs = 600,
+}) => {
+  const params = parameters.getUpdatedAllParams ? parameters.getUpdatedAllParams() : parameters;
+  const track = stream?.getAudioTracks?.()[0];
+  if (!track || track.readyState === "ended") return null;
+  if (!shouldShareScreenAudio(params)) return null;
+  const transport = params.producerTransport;
+  if (!transport || transport.closed) return null;
+
+  const existing = currentScreenAudioProducer(params);
+  if (existing && !existing.closed) return existing;
+
+  try {
+    let producer = await produceOnce(transport, track);
+    // The track may have ended while the first attempt was in flight.
+    const trackEnded = () => (track.readyState as MediaStreamTrackState) === "ended";
+    if (!producer && retryDelayMs > 0 && !trackEnded()) {
+      await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
+      producer = await produceOnce(transport, track);
+    }
+    if (!producer) return null;
+
+    storeScreenAudioProducer(params, producer);
+
+    const screenProducer = params.screenProducer;
+    if (screenProducer?.paused) producer.pause();
+    screenProducer?.observer?.on("pause", () => {
+      if (!producer!.closed) producer!.pause();
+    });
+    screenProducer?.observer?.on("resume", () => {
+      if (!producer!.closed) producer!.resume();
+    });
+    screenProducer?.observer?.on("close", () => {
+      void disconnectSendTransportScreenAudio({ parameters: params });
+    });
+
+    track.addEventListener("ended", () => {
+      void disconnectSendTransportScreenAudio({ parameters: params, notifyServer: true });
+    });
+    return producer;
+  } catch (error) {
+    console.log("connectSendTransportScreenAudio error", error);
+    return null;
+  }
+};

package/src/consumers/consumerBackupPreference.ts

@@ -0,0 +1,43 @@
+/**
+ * Consumer backup preference (server feature consumer-backup-v1).
+ *
+ * When a consuming node gets busy, the server attaches a backup node and tells every listener
+ * `alt_domains: { <busy node>: <backup node> }`. Listeners stay on the busy node for what they already receive, but a
+ * stream announced after that is taken from the backup: when the busy node announces it and the backup is connected,
+ * the client waits briefly for the backup's own announcement (the backup gets each new stream a moment later) and only
+ * falls back to the busy node if it does not come. Consumption is de-duplicated by producer id, so whichever node is
+ * used first wins and the other announcement is ignored.
+ *
+ * The request is never sent to the backup for a stream the backup has not announced: a consume the backup cannot serve
+ * fails without an error and the de-duplication would then skip the busy node's copy (staging test, Oct 9 2026).
+ */
+const backupByParent = new Map<string, string>();
+
+/** How long a busy node's announcement waits for the backup's (ms). */
+export const CONSUMER_BACKUP_PREFER_DELAY_MS = 1500;
+
+/** Records the server's `{ busy node: backup node }` map (from `updateConsumingDomains` / `getDomains`). */
+export const rememberConsumerBackups = (altDomains?: Record<string, string> | null): void => {
+  for (const [parent, backup] of Object.entries(altDomains || {})) {
+    if (parent && backup && parent !== backup) backupByParent.set(parent, backup);
+  }
+};
+
+export const forgetConsumerBackups = (): void => backupByParent.clear();
+
+type SocketEntry = Record<string, { connected?: boolean } | undefined>;
+
+/** The connected backup to prefer over `ip`, or null. */
+export const preferredConsumerBackup = (ip: string, consumeSockets?: SocketEntry[] | null): string | null => {
+  const backup = backupByParent.get(ip);
+  if (!backup) return null;
+  const connected = (consumeSockets || []).some((entry) => {
+    const socket = entry?.[backup];
+    return Boolean(socket) && socket!.connected !== false;
+  });
+  return connected ? backup : null;
+};
+
+/** Delay (ms) before consuming a stream announced by `ip`: non-zero only when a connected backup should win. */
+export const consumerBackupPreferDelay = (ip: string, consumeSockets?: SocketEntry[] | null): number =>
+  preferredConsumerBackup(ip, consumeSockets) ? CONSUMER_BACKUP_PREFER_DELAY_MS : 0;

package/src/consumers/disconnectSendTransportScreen.ts

@@ -1,5 +1,6 @@
 import type { Producer } from 'mediasoup-client/types';
 import { Socket } from "socket.io-client";
+import { disconnectSendTransportScreenAudio } from "./connectSendTransportScreenAudio";
 
 export interface DisconnectSendTransportScreenParameters {
     screenProducer: Producer | null;
@@ -94,6 +95,13 @@ export const disconnectSendTransportScreen = async ({ parameters }: DisconnectSe
     let { getUpdatedAllParams } = parameters;
     parameters = getUpdatedAllParams()
 
+    try {
+        // Screen audio stops with the screen share (the server closes its side on closeScreenProducer).
+        await disconnectSendTransportScreenAudio({ parameters: parameters as any });
+    } catch {
+        // nothing to close
+    }
+
     try {
         // Destructure parameters
         let {

package/src/consumers/getPipedProducersAlt.ts

@@ -1,5 +1,6 @@
 import { Socket } from "socket.io-client";
 import { SignalNewConsumerTransportParameters, SignalNewConsumerTransportType } from '../types/types';
+import { markScreenAudioProducer } from './screenAudio';
 
 interface TranslationMeta {
   speakerId: string;
@@ -12,6 +13,8 @@ interface TranslationMeta {
 interface ProducerInfo {
   id: string;
   translationMeta?: TranslationMeta | null;
+  /** "screen-audio" for audio shared with a screen share. */
+  mediaTag?: string;
 }
 
 export interface GetPipedProducersAltParameters extends Omit<SignalNewConsumerTransportParameters, 'getUpdatedAllParams'> {
@@ -151,6 +154,7 @@ export const getPipedProducersAlt = async ({
             } else {
               producerId = producer.id;
               translationMeta = producer.translationMeta || null;
+              markScreenAudioProducer(producerId, producer.mediaTag);
             }
 
             if (translationMeta) {

package/src/consumers/index.ts

@@ -13,6 +13,9 @@ export * from './connectRecvTransport';
 export * from './connectSendTransport';
 export * from './connectSendTransportAudio';
 export * from './connectSendTransportScreen';
+export * from './connectSendTransportScreenAudio';
+export * from './screenAudio';
+export * from './consumerBackupPreference';
 export * from './connectSendTransportVideo';
 export * from './consumerResume';
 export * from './controlMedia';