mediasfu-shared 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasfu-shared",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "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",

package/src/consumers/audioProcessing.ts

@@ -0,0 +1,26 @@
+export type AudioProcessingOptions = {
+  echoCancellation?: boolean;
+  noiseSuppression?: boolean;
+  autoGainControl?: boolean;
+};
+
+export function audioProcessingConstraints(options?: AudioProcessingOptions): MediaTrackConstraints {
+  const result: MediaTrackConstraints = {};
+  if (options === undefined) return result;
+  if (!options || typeof options !== 'object' || Array.isArray(options)) throw new TypeError('Invalid audioProcessing');
+  for (const key of Object.keys(options)) {
+    if (!['echoCancellation', 'noiseSuppression', 'autoGainControl'].includes(key)) throw new TypeError('Unsupported audioProcessing option');
+    const value = options[key as keyof AudioProcessingOptions];
+    if (value !== undefined && typeof value !== 'boolean') throw new TypeError('Audio processing options must be boolean');
+    if (value !== undefined) result[key as keyof AudioProcessingOptions] = value;
+  }
+  return result;
+}
+
+// applyConstraints replaces the constraint set: merge to retain device and
+// capture choices unrelated to the three processing preferences.
+export async function applyAudioProcessing(track: MediaStreamTrack, options?: AudioProcessingOptions): Promise<void> {
+  const selected = audioProcessingConstraints(options);
+  if (!Object.keys(selected).length) return;
+  await track.applyConstraints({ ...track.getConstraints(), ...selected });
+}

package/src/consumers/connectIps.ts

@@ -50,10 +50,22 @@ const normalizeConsumeEndpoint = (ip: string): string =>
 const hasConsumeEndpoint = (
   consumeSockets: ConsumeSocket[],
   endpoint: string
-): boolean => consumeSockets.some((socketObj) => {
-  const ip = Object.keys(socketObj)[0];
-  return Boolean(ip) && normalizeConsumeEndpoint(ip) === endpoint;
-});
+): boolean => {
+  for (let index = consumeSockets.length - 1; index >= 0; index -= 1) {
+    const socketObj = consumeSockets[index];
+    const ip = Object.keys(socketObj)[0];
+    if (!ip || normalizeConsumeEndpoint(ip) !== endpoint) continue;
+
+    const socket = socketObj[ip];
+    if (socket?.connected && socket.id) return true;
+
+    socket?.removeAllListeners?.();
+    socket?.disconnect?.();
+    consumeSockets.splice(index, 1);
+  }
+
+  return false;
+};
 
 async function reserveConsumeEndpoint(
   consumeSockets: ConsumeSocket[],
@@ -87,6 +99,9 @@ async function reserveConsumeEndpoint(
     return (didConnect = false) => {
       if (pendingForSockets?.get(endpoint) === reservation) {
         pendingForSockets.delete(endpoint);
+        if (pendingForSockets.size === 0) {
+          pendingConsumeConnections.delete(reservationOwner);
+        }
       }
       resolvePending(didConnect === true);
     };
@@ -170,9 +185,10 @@ export const connectIps = async ({
       if (!releaseReservation) continue;
 
       let connected = false;
+      let remote_sock: Awaited<ReturnType<typeof connectSocket>> | null = null;
       try {
         // Connect to the remote socket using socket.io-client
-        const remote_sock = await connectSocket({ apiUserName, apiKey, apiToken, link: `https://${ip}.mediasfu.com` });
+        remote_sock = await connectSocket({ apiUserName, apiKey, apiToken, link: `https://${ip}.mediasfu.com` });
 
         if (remote_sock.id) {
           // Check if the IP is in the roomRecvIPs, if not, add it
@@ -187,7 +203,7 @@ export const connectIps = async ({
               await newProducerMethod({
                 producerId,
                 islevel,
-                nsock: remote_sock,
+                nsock: remote_sock!,
                 parameters,
                 isTranslation,
                 translationMeta,
@@ -211,7 +227,7 @@ export const connectIps = async ({
               parameters,
             });
             if (!data.rtpCapabilities) {
-              return [consume_sockets, roomRecvIPs];
+              throw new Error(`Consume room ${ip} did not return RTP capabilities.`);
             }
           }
 
@@ -219,11 +235,34 @@ export const connectIps = async ({
           consume_sockets.push({ [ip]: remote_sock });
           updateConsume_sockets(consume_sockets);
           connected = true;
+
+          remote_sock.on("disconnect", () => {
+            const socketIndex = consume_sockets.findIndex(
+              (socketObj) => socketObj[ip] === remote_sock
+            );
+            if (socketIndex >= 0) {
+              consume_sockets.splice(socketIndex, 1);
+              updateConsume_sockets(consume_sockets);
+            }
+
+            const recvIndex = roomRecvIPs.indexOf(ip);
+            if (recvIndex >= 0) {
+              roomRecvIPs.splice(recvIndex, 1);
+              updateRoomRecvIPs(roomRecvIPs);
+            }
+
+            remote_sock?.removeAllListeners?.();
+            remote_sock?.disconnect();
+          });
         }
       } catch (error) {
         // Handle the error
         console.log("connectIps error", error);
       } finally {
+        if (!connected && remote_sock) {
+          remote_sock.removeAllListeners?.();
+          remote_sock.disconnect();
+        }
         releaseReservation(connected);
       }
     }

package/src/consumers/createSendTransport.ts

@@ -1,4 +1,5 @@
 import type { Device, Transport, DtlsParameters } from 'mediasoup-client/types';
+import { attachTransportRecovery, clearFailedSendState } from './transportRecovery';
 import { Socket } from "socket.io-client";
 import {
   ConnectSendTransportParameters,
@@ -151,12 +152,8 @@ const createLocalSendTransport = async ({
           }
         );
 
-        createdLocalTransport.on("connectionstatechange", (state: string) => {
-          if (state === "failed") {
-            console.error("Local transport connection failed.");
-            createdLocalTransport.close();
-          }
-        });
+        attachTransportRecovery(createdLocalTransport, localSocket, () =>
+          clearFailedSendState(parameters, createdLocalTransport, true));
 
         // Mark local transport as created
         localTransportCreated = true;
@@ -330,20 +327,8 @@ export const createSendTransport: CreateSendTransportType = async ({
         );
 
         // Handle 'connectionstatechange' event
-        createdProducerTransport.on("connectionstatechange", async (state: string) => {
-          switch (state) {
-            case "connecting":
-              break;
-            case "connected":
-              break;
-            case "failed":
-              console.log("Transport connection failed.");
-              createdProducerTransport.close();
-              break;
-            default:
-              break;
-          }
-        });
+        attachTransportRecovery(createdProducerTransport, socket, () =>
+          clearFailedSendState(parameters, createdProducerTransport));
 
         // Update transport creation state
         transportCreated = true;

package/src/consumers/gridLayout/addVideosGrid.engine.ts

@@ -14,6 +14,19 @@ export interface AddVideosGridPlan<T> {
   altEntries: GridPlanEntry<T>[];
 }
 
+/** A lone side-panel tile must remain fully visible during screen sharing. */
+export function resolveSidePanelForceFullDisplay({
+  forceFullDisplay,
+  screenShareActive,
+  itemCount,
+}: {
+  forceFullDisplay: boolean;
+  screenShareActive: boolean;
+  itemCount: number;
+}): boolean {
+  return forceFullDisplay && !(screenShareActive && itemCount < 2);
+}
+
 /**
  * Pure planning engine for addVideosGrid.
  * Produces deterministic main/alt stream iteration plans without rendering concerns.

package/src/consumers/signalNewConsumerTransport.ts

@@ -1,4 +1,5 @@
 import { Socket } from "socket.io-client";
+import { attachTransportRecovery } from './transportRecovery';
 import { ReorderStreamsParameters, ReorderStreamsType, ConnectRecvTransportType,
    ConnectRecvTransportParameters, CreateWebRTCTransportResponse } from "../types/types";
 import type { Device, DtlsParameters  } from 'mediasoup-client/types';
@@ -128,31 +129,12 @@ export const signalNewConsumerTransport = async ({
           );
 
           // Listen for connection state change
-          consumerTransport.on("connectionstatechange", async (state: string) => {
-            switch (state) {
-              case "connecting":
-                // Handle connecting state
-                break;
-
-              case "connected":
-                // Handle connected state
-                break;
-
-              case "failed":
-                // Handle failed state
-                consumerTransport.close();
-
-                // Reorder streams based on conditions
-                if (lock_screen) {
-                  await reorderStreams({ add: true, parameters });
-                } else {
-                  await reorderStreams({ add: false, parameters });
-                }
-                break;
-
-              default:
-                break;
-            }
+          attachTransportRecovery(consumerTransport, nsock, () => {
+            const live: any = parameters.getCurrentParams?.() ?? parameters.getUpdatedAllParams?.() ?? parameters;
+            live.updateConsumingTransports?.((live.consumingTransports || []).filter((id: string) => id !== remoteProducerId));
+            live.updateConsumerTransports?.((live.consumerTransports || []).filter((entry: any) => entry.consumerTransport !== consumerTransport));
+            live.showAlert?.({ message: 'A remote media connection could not recover. Rejoin to restore it.', type: 'danger', duration: 10000 });
+            void Promise.resolve(reorderStreams({ add: Boolean(lock_screen), parameters })).catch(() => {});
           });
 
           // Connect the receiving transport

package/src/consumers/switchUserAudio.ts

@@ -17,7 +17,10 @@ export interface SwitchUserAudioParameters extends StreamSuccessAudioSwitchParam
   [key: string]: any;
 }
 
+import { AudioProcessingOptions, audioProcessingConstraints } from './audioProcessing';
+
 export interface SwitchUserAudioOptions {
+  audioProcessing?: AudioProcessingOptions;
   audioPreference: string;
   parameters: SwitchUserAudioParameters;
 }
@@ -63,7 +66,7 @@ export type SwitchUserAudioType = (options: SwitchUserAudioOptions) => Promise<v
  */
 
 
-export async function switchUserAudio({ audioPreference, parameters }: SwitchUserAudioOptions): Promise<void> {
+export async function switchUserAudio({ audioPreference, parameters, audioProcessing }: SwitchUserAudioOptions): Promise<void> {
   const {
     mediaDevices,
     prevAudioInputDevice,
@@ -94,12 +97,23 @@ export async function switchUserAudio({ audioPreference, parameters }: SwitchUse
       }
     }
 
+    // Preserve the microphone's processing policy, not its old deviceId.
+    // Omit unknown values so the browser retains its normal defaults.
+    const track = parameters.localStreamAudio?.getAudioTracks?.()[0]
+      ?? parameters.localStream?.getAudioTracks?.()[0]
+      ?? parameters.audioProducer?.track;
+    const previousConstraints = track?.getConstraints?.() ?? {};
+    const previousSettings = track?.getSettings?.() ?? {};
+    const processing: MediaTrackConstraints = {};
+    for (const key of ['echoCancellation', 'noiseSuppression', 'autoGainControl'] as const) {
+      const value = previousConstraints[key] ?? previousSettings[key];
+      if (value !== undefined) processing[key] = value;
+    }
     const mediaConstraints: MediaStreamConstraints = {
       audio: {
         deviceId: { exact: audioPreference },
-        echoCancellation: false,
-        noiseSuppression: false,
-        autoGainControl: false,
+        ...processing,
+        ...audioProcessingConstraints(audioProcessing),
       },
       video: false,
     };
@@ -137,4 +151,3 @@ export async function switchUserAudio({ audioPreference, parameters }: SwitchUse
 
   }
 }
-

package/src/consumers/transportRecovery.ts

@@ -0,0 +1,170 @@
+/**
+ * Bounded ICE recovery shared by sending and receiving transports.
+ * Keeps tracks/producers alive while ICE is restarted on both endpoints.
+ */
+export function attachTransportRecovery(transport: any, socket: any, onFailure: () => void) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let disposed = false;
+  let recovering = false;
+  let attempts = 0;
+  const socketId = socket.id;
+  const listeners: Array<() => void> = [];
+  const report = (state: string) => {
+    transport.appData = { ...transport.appData, recoveryState: state };
+    transport.observer?.emit('recoverychange', state);
+  };
+  const clearTimer = () => { if (timer) clearTimeout(timer); timer = undefined; };
+  const current = () => !disposed && !transport.closed && socket.connected !== false && socket.id === socketId;
+  const dispose = () => {
+    disposed = true;
+    clearTimer();
+    listeners.splice(0).forEach(cancel => cancel());
+    socket.off?.('disconnect', dispose);
+    transport.off?.('connectionstatechange', changed);
+    transport.observer?.off?.('close', dispose);
+  };
+  const failed = () => {
+    if (disposed) return;
+    report('failed');
+    try { onFailure(); } catch (_) { /* UI callbacks must not prevent teardown. */ }
+    try { transport.close(); } finally { dispose(); }
+  };
+  const waitConnected = () => new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const finish = (error?: Error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(deadline);
+      transport.off?.('connectionstatechange', connected);
+      const i = listeners.indexOf(cancel);
+      if (i >= 0) listeners.splice(i, 1);
+      error ? reject(error) : resolve();
+    };
+    const connected = (state: string) => { if (state === 'connected') finish(); };
+    const cancel = () => finish(new Error('Recovery cancelled'));
+    const deadline = setTimeout(() => finish(new Error('ICE recovery timed out')), 10000);
+    listeners.push(cancel);
+    transport.on('connectionstatechange', connected);
+    if (transport.connectionState === 'connected') finish();
+  });
+  const restart = async () => {
+    if (!current() || recovering) return;
+    recovering = true;
+    report('recovering');
+    try {
+      while (current() && attempts < 2) {
+        attempts++;
+        try {
+          const iceParameters = await new Promise<any>((resolve, reject) => {
+            let settled = false;
+            const finish = (error?: Error, value?: any) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(deadline);
+              const i = listeners.indexOf(cancel);
+              if (i >= 0) listeners.splice(i, 1);
+              error ? reject(error) : resolve(value);
+            };
+            const cancel = () => finish(new Error('Recovery cancelled'));
+            const deadline = setTimeout(() => finish(new Error('ICE restart acknowledgement timed out')), 8000);
+            listeners.push(cancel);
+            socket.emit('transport-restart-ice', { transportId: transport.id }, (response: any) => {
+              if (!response?.iceParameters || response.error) finish(new Error(response?.error || 'Invalid ICE response'));
+              else finish(undefined, response.iceParameters);
+            });
+          });
+          if (!current()) return;
+          await new Promise<void>((resolve, reject) => {
+            let settled = false;
+            const finish = (error?: Error) => {
+              if (settled) return;
+              settled = true;
+              clearTimeout(deadline);
+              const i = listeners.indexOf(cancel);
+              if (i >= 0) listeners.splice(i, 1);
+              error ? reject(error) : resolve();
+            };
+            const cancel = () => finish(new Error('Recovery cancelled'));
+            const deadline = setTimeout(() => finish(new Error('Local ICE restart timed out')), 8000);
+            listeners.push(cancel);
+            Promise.resolve().then(() => {
+              if (!current()) throw new Error('Recovery cancelled');
+              return transport.restartIce({ iceParameters });
+            }).then(() => finish(), error => finish(error));
+          });
+          if (!current()) return;
+          await waitConnected();
+          if (!current()) return;
+          attempts = 0;
+          report('connected');
+          return;
+        } catch (_) {
+          if (!current()) return;
+          if (transport.connectionState === 'connected') {
+            attempts = 0;
+            report('connected');
+            return;
+          }
+          if (attempts < 2) {
+            // Respect the server's two-second restart throttle, including
+            // immediate acknowledgement failures. Teardown cancels the wait.
+            await new Promise<void>(resolve => {
+              const cancel = () => {
+                clearTimeout(delay);
+                const i = listeners.indexOf(cancel);
+                if (i >= 0) listeners.splice(i, 1);
+                resolve();
+              };
+              const delay = setTimeout(cancel, 2100);
+              listeners.push(cancel);
+            });
+          }
+        }
+      }
+      if (current()) failed();
+    } finally {
+      recovering = false;
+    }
+  };
+  const changed = (state: string) => {
+    if (disposed) return;
+    if (state === 'connected') {
+      clearTimer();
+      if (!recovering) { attempts = 0; report('connected'); }
+    } else if (state === 'disconnected') {
+      if (recovering || timer) return;
+      report('waiting');
+      timer = setTimeout(() => { timer = undefined; void restart(); }, 3000);
+    } else if (state === 'failed') {
+      clearTimer();
+      void restart();
+    } else if (state === 'closed') dispose();
+  };
+  socket.on?.('disconnect', dispose);
+  transport.on('connectionstatechange', changed);
+  transport.observer?.once('close', dispose);
+  return dispose;
+}
+
+/** Clear publishing indicators only if this is still the active transport. */
+export function clearFailedSendState(parameters: any, transport: any, local = false) {
+  const live = parameters.getCurrentParams?.() ?? parameters.getUpdatedAllParams?.() ?? parameters;
+  if ((local ? live.localProducerTransport : live.producerTransport) !== transport) return;
+  if (local) {
+    live.updateLocalProducerTransport?.(null);
+    live.updateLocalTransportCreated?.(false);
+    return;
+  }
+  for (const kind of ['Audio', 'Video', 'Screen']) {
+    const key = kind.toLowerCase();
+    live['update' + kind + 'Producer']?.(null);
+    live['updateTransportCreated' + kind]?.(false);
+    live['update' + kind + 'AlreadyOn']?.(false);
+    // Notify room membership using the existing pause protocol, preserving
+    // users' local tracks for an explicit retry.
+    live.socket?.emit('pauseProducerMedia', { mediaTag: key, roomName: live.roomName });
+  }
+  live.updateProducerTransport?.(null);
+  live.updateTransportCreated?.(false);
+  live.showAlert?.({ message: 'Media connection could not recover. Rejoin the room to restore audio and video.', type: 'danger', duration: 10000 });
+}

package/src/index.ts

@@ -117,6 +117,7 @@ export * from './methods/stream/switchAudio';
 export * from './methods/stream/switchVideo';
 export * from './methods/stream/switchVideoAlt';
 export * from './methods/stream/clickAudio';
+export type { AudioProcessingOptions } from './consumers/audioProcessing';
 export * from './methods/stream/clickChat';
 export * from './methods/stream/clickScreenShare';
 export * from './methods/utils/liveSubtitle';
@@ -230,3 +231,4 @@ export * from './methods/utils/headless';
 export * from './methods/utils/getParticipantMedia';
 // Shared web compositor used by headless virtual-background processing.
 export * from './methods/utils/virtualBackgroundCompositor';
+export * from './methods/utils/virtualBackgroundFrameLoop';

package/src/methods/stream/clickAudio.ts

@@ -72,7 +72,10 @@ export interface ClickAudioParameters
   [key: string]: any;
 }
 
+import { AudioProcessingOptions, audioProcessingConstraints, applyAudioProcessing } from '../../consumers/audioProcessing';
+
 export interface ClickAudioOptions {
+  audioProcessing?: AudioProcessingOptions;
   parameters: ClickAudioParameters;
 }
 
@@ -88,7 +91,7 @@ export type ClickAudioType = (options: ClickAudioOptions) => Promise<void>;
  * @param options Function options containing the full runtime parameter bag.
  * @returns A promise that resolves after the microphone action has been processed.
  */
-export const clickAudio = async ({ parameters }: ClickAudioOptions): Promise<void> => {
+export const clickAudio = async ({ parameters, audioProcessing }: ClickAudioOptions): Promise<void> => {
   let {
     checkMediaPermission,
     hasAudioPermission,
@@ -307,6 +310,7 @@ export const clickAudio = async ({ parameters }: ClickAudioOptions): Promise<voi
 
       case 0:
         if (audioPaused) {
+          await applyAudioProcessing(localStream!.getAudioTracks()[0], audioProcessing);
           if (localStream && localStream.getAudioTracks().length > 0) {
             localStream.getAudioTracks()[0].enabled = true;
           }
@@ -355,9 +359,13 @@ export const clickAudio = async ({ parameters }: ClickAudioOptions): Promise<voi
             }
           }
 
-          const mediaConstraints = userDefaultAudioInputDevice
-            ? { audio: { deviceId: userDefaultAudioInputDevice }, video: false }
-            : { audio: true, video: false };
+          const processing = audioProcessingConstraints(audioProcessing);
+          const mediaConstraints = {
+            audio: userDefaultAudioInputDevice || Object.keys(processing).length
+              ? { ...(userDefaultAudioInputDevice ? { deviceId: userDefaultAudioInputDevice } : {}), ...processing }
+              : true,
+            video: false,
+          };
 
           try {
             const stream = await mediaDevices.getUserMedia(mediaConstraints);
@@ -377,4 +385,4 @@ export const clickAudio = async ({ parameters }: ClickAudioOptions): Promise<voi
       default:
     }
   }
-};
+};

package/src/methods/stream/switchAudio.ts

@@ -14,7 +14,10 @@ export interface SwitchAudioParameters extends SwitchUserAudioParameters {
   [key: string]: any
 }
 
+import { AudioProcessingOptions, applyAudioProcessing } from '../../consumers/audioProcessing';
+
 export interface SwitchAudioOptions {
+  audioProcessing?: AudioProcessingOptions;
   audioPreference: string
   parameters: SwitchAudioParameters
 }
@@ -47,6 +50,7 @@ export type SwitchAudioType = (options: SwitchAudioOptions) => Promise<void>
 
 export const switchAudio = async ({
   audioPreference,
+  audioProcessing,
   parameters
 }: SwitchAudioOptions): Promise<void> => {
   let {
@@ -67,7 +71,12 @@ export const switchAudio = async ({
     updateUserDefaultAudioInputDevice(userDefaultAudioInputDevice)
 
     if (defAudioID) {
-      await switchUserAudio({ audioPreference, parameters })
+      await switchUserAudio({ audioPreference, parameters, audioProcessing })
     }
+  } else if (audioProcessing !== undefined) {
+    const track = parameters.localStreamAudio?.getAudioTracks?.()[0]
+      ?? parameters.localStream?.getAudioTracks?.()[0]
+      ?? parameters.audioProducer?.track;
+    if (track) await applyAudioProcessing(track, audioProcessing);
   }
 }