mediasfu-shared 1.2.7 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasfu-shared",
-  "version": "1.2.7",
+  "version": "1.3.1",
   "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/updateRoomParametersClient.ts

@@ -117,6 +117,8 @@ 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;
 }
@@ -184,6 +186,7 @@ export const updateRoomParametersClient = ({ parameters, simulcastOff = paramete
       updateRecordingPreferredOrientation,
       updateRecordingSupportForOtherOrientation,
       updateRecordingMultiFormatsSupport,
+      updateSupportsScreenAudio,
       updateRecordingVideoOptions,
       updateRecordingAudioOptions,
       updateMainHeightWidth,
@@ -221,6 +224,7 @@ export const updateRoomParametersClient = ({ parameters, simulcastOff = paramete
     updateRecordingPreferredOrientation(data.recordingParams.recordingPreferredOrientation);
     updateRecordingSupportForOtherOrientation(data.recordingParams.recordingSupportForOtherOrientation);
     updateRecordingMultiFormatsSupport(data.recordingParams.recordingMultiFormatsSupport);
+    updateSupportsScreenAudio?.(data.supportsScreenAudio === true);
 
     updateItemPageLimit(data.meetingRoomParams.itemPageLimit);
     updateEventType(data.meetingRoomParams.type);

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/connectSendTransportAudio.ts

@@ -1,4 +1,5 @@
 import type { Transport, Producer, ProducerOptions } from 'mediasoup-client/types';
+import { produceOnce } from "./sendTransportGuard";
 
 export interface ConnectSendTransportAudioParameters {
   audioProducer: Producer | null;
@@ -39,7 +40,7 @@ const connectLocalSendTransportAudio = async ({
     } = parameters;
 
     if (localProducerTransport) {
-      localAudioProducer = await localProducerTransport.produce(audioParams);
+      localAudioProducer = (await produceOnce(localProducerTransport, "audio", () => localProducerTransport!.produce(audioParams))).producer;
 
       updateLocalAudioProducer?.(localAudioProducer);
       updateLocalProducerTransport?.(localProducerTransport);
@@ -127,10 +128,12 @@ export const connectSendTransportAudio: ConnectSendTransportAudioType = async ({
 
     // Attempt to connect the primary send transport
     if (targetOption === "all" || targetOption === "remote") {
-      audioProducer = await producerTransport!.produce(audioParams);
+      // A concurrent call for the same transport shares the producer instead of creating a second one.
+      const produced = await produceOnce(producerTransport!, "audio", () => producerTransport!.produce(audioParams));
+      audioProducer = produced.producer;
 
-      // Update the audio level
-      updateMicLevel(audioProducer, parameters.updateAudioLevel);
+      // Update the audio level (once per producer)
+      if (!produced.joined) updateMicLevel(audioProducer, parameters.updateAudioLevel);
 
       // Update state with the new producer and transport
       updateAudioProducer(audioProducer);

package/src/consumers/connectSendTransportScreen.ts

@@ -1,4 +1,5 @@
 import type { Transport, Producer, Device, ProducerOptions } from 'mediasoup-client/types';
+import { produceOnce } from "./sendTransportGuard";
 
 export interface ConnectSendTransportScreenParameters {
   screenProducer: Producer | null;
@@ -48,11 +49,11 @@ const connectLocalSendTransportScreen = async ({
 
     // Produce local screen share data
     if (localProducerTransport) {
-      localScreenProducer = await localProducerTransport.produce({
+      localScreenProducer = (await produceOnce(localProducerTransport, "screen", () => localProducerTransport!.produce({
         track: stream.getVideoTracks()[0],
         codec,
         appData: { mediaTag: "screen-video" },
-      });
+      }))).producer;
 
       // Update the local producer and transport objects
       updateLocalScreenProducer?.(localScreenProducer);
@@ -144,12 +145,13 @@ export const connectSendTransportScreen: ConnectSendTransportScreenType = async
 
     // Produce screen share data using the producer transport
     if (targetOption === "remote" || targetOption === "all") {
-      screenProducer = await producerTransport!.produce({
+      // A concurrent call for the same transport shares the producer instead of creating a second one.
+      screenProducer = (await produceOnce(producerTransport!, "screen", () => producerTransport!.produce({
         track: stream.getVideoTracks()[0],
         ...params,
         codec,
         appData: { mediaTag: "screen-video" },
-      });
+      }))).producer;
 
       // Update the screen producer and producer transport objects
       updateScreenProducer(screenProducer);

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/connectSendTransportVideo.ts

@@ -1,4 +1,5 @@
 import type { Device, Producer, ProducerOptions, Transport } from 'mediasoup-client/types';
+import { produceOnce } from "./sendTransportGuard";
 
 export interface ConnectSendTransportVideoParameters {
   videoProducer: Producer | null;
@@ -39,7 +40,7 @@ const connectLocalSendTransportVideo = async ({
 
     // Produce local video data if transport exists
     if (localProducerTransport) {
-      localVideoProducer = await localProducerTransport.produce(videoParams);
+      localVideoProducer = (await produceOnce(localProducerTransport, "video", () => localProducerTransport!.produce(videoParams))).producer;
 
       // Update local producer and transport
       updateLocalVideoProducer?.(localVideoProducer);
@@ -121,7 +122,8 @@ export const connectSendTransportVideo: ConnectSendTransportVideoType = async ({
 
     // Produce video data using the primary transport
     if (targetOption === "all" || targetOption === "remote"){
-      videoProducer = await producerTransport!.produce(videoParams);
+      // A concurrent call for the same transport shares the producer instead of creating a second one.
+      videoProducer = (await produceOnce(producerTransport!, "video", () => producerTransport!.produce(videoParams))).producer;
 
       // Update main window state based on the video connection level
       if (islevel === "2") {

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;