mediasfu-shared 1.1.0 → 1.2.1

package/dist/validateAlphanumeric-DKn5BsUP.cjs

@@ -0,0 +1,15 @@
+"use strict";
+const validateAlphanumeric = async ({ str }) => {
+  let code, i, len;
+  for (i = 0, len = str.length; i < len; i++) {
+    code = str.charCodeAt(i);
+    if (!(code > 47 && code < 58) && // numeric (0-9)
+    !(code > 64 && code < 91) && // upper alpha (A-Z)
+    !(code > 96 && code < 123)) {
+      return false;
+    }
+  }
+  return true;
+};
+exports.validateAlphanumeric = validateAlphanumeric;
+//# sourceMappingURL=validateAlphanumeric-DKn5BsUP.cjs.map

package/dist/validateAlphanumeric-DKn5BsUP.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateAlphanumeric-DKn5BsUP.cjs","sources":["../src/methods/utils/validateAlphanumeric.ts"],"sourcesContent":["\nexport interface ValidateAlphanumericOptions {\n  str: string;\n}\n\n// Export the type definition for the function\nexport type ValidateAlphanumericType = (options: ValidateAlphanumericOptions) => Promise<boolean>;\n\n/**\n * Validates if the given string contains only alphanumeric characters.\n *\n * @param {ValidateAlphanumericOptions} options - The options containing the string to validate.\n * @param {string} options.str - The string to be validated.\n * @returns {Promise<boolean>} - A promise that resolves to `true` if the string is alphanumeric, otherwise `false`.\n * \n * @example\n * ```typescript \n * const isValid = await validateAlphanumeric({ str: \"abc123\" });\n * console.log(isValid);\n * // Output: true\n * ```\n */\n\n\nconst validateAlphanumeric = async ({ str }: ValidateAlphanumericOptions): Promise<boolean> => {\n  let code: number, i: number, len: number;\n\n  for (i = 0, len = str.length; i < len; i++) {\n    code = str.charCodeAt(i);\n    if (\n      !(code > 47 && code < 58) && // numeric (0-9)\n      !(code > 64 && code < 91) && // upper alpha (A-Z)\n      !(code > 96 && code < 123)   // lower alpha (a-z)\n    ) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport { validateAlphanumeric };\n"],"names":[],"mappings":";AAwBA,MAAM,uBAAuB,OAAO,EAAE,UAAyD;AAC7F,MAAI,MAAc,GAAW;AAE7B,OAAK,IAAI,GAAG,MAAM,IAAI,QAAQ,IAAI,KAAK,KAAK;AAC1C,WAAO,IAAI,WAAW,CAAC;AACvB,QACE,EAAE,OAAO,MAAM,OAAO;AAAA,IACtB,EAAE,OAAO,MAAM,OAAO;AAAA,IACtB,EAAE,OAAO,MAAM,OAAO,MACtB;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;;"}

package/dist/validateAlphanumeric-Dk1JB80W.js

@@ -0,0 +1,16 @@
+const validateAlphanumeric = async ({ str }) => {
+  let code, i, len;
+  for (i = 0, len = str.length; i < len; i++) {
+    code = str.charCodeAt(i);
+    if (!(code > 47 && code < 58) && // numeric (0-9)
+    !(code > 64 && code < 91) && // upper alpha (A-Z)
+    !(code > 96 && code < 123)) {
+      return false;
+    }
+  }
+  return true;
+};
+export {
+  validateAlphanumeric as v
+};
+//# sourceMappingURL=validateAlphanumeric-Dk1JB80W.js.map

package/dist/validateAlphanumeric-Dk1JB80W.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validateAlphanumeric-Dk1JB80W.js","sources":["../src/methods/utils/validateAlphanumeric.ts"],"sourcesContent":["\nexport interface ValidateAlphanumericOptions {\n  str: string;\n}\n\n// Export the type definition for the function\nexport type ValidateAlphanumericType = (options: ValidateAlphanumericOptions) => Promise<boolean>;\n\n/**\n * Validates if the given string contains only alphanumeric characters.\n *\n * @param {ValidateAlphanumericOptions} options - The options containing the string to validate.\n * @param {string} options.str - The string to be validated.\n * @returns {Promise<boolean>} - A promise that resolves to `true` if the string is alphanumeric, otherwise `false`.\n * \n * @example\n * ```typescript \n * const isValid = await validateAlphanumeric({ str: \"abc123\" });\n * console.log(isValid);\n * // Output: true\n * ```\n */\n\n\nconst validateAlphanumeric = async ({ str }: ValidateAlphanumericOptions): Promise<boolean> => {\n  let code: number, i: number, len: number;\n\n  for (i = 0, len = str.length; i < len; i++) {\n    code = str.charCodeAt(i);\n    if (\n      !(code > 47 && code < 58) && // numeric (0-9)\n      !(code > 64 && code < 91) && // upper alpha (A-Z)\n      !(code > 96 && code < 123)   // lower alpha (a-z)\n    ) {\n      return false;\n    }\n  }\n  return true;\n};\n\nexport { validateAlphanumeric };\n"],"names":[],"mappings":"AAwBA,MAAM,uBAAuB,OAAO,EAAE,UAAyD;AAC7F,MAAI,MAAc,GAAW;AAE7B,OAAK,IAAI,GAAG,MAAM,IAAI,QAAQ,IAAI,KAAK,KAAK;AAC1C,WAAO,IAAI,WAAW,CAAC;AACvB,QACE,EAAE,OAAO,MAAM,OAAO;AAAA,IACtB,EAAE,OAAO,MAAM,OAAO;AAAA,IACtB,EAAE,OAAO,MAAM,OAAO,MACtB;AACA,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mediasfu-shared",
-  "version": "1.1.0",
+  "version": "1.2.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",
@@ -37,6 +37,7 @@
     "src",
     "README.md",
     "HEADLESS_GUIDE.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {

package/src/ProducerClient/producerClientEmits/createDeviceClient.ts

@@ -1,5 +1,5 @@
 import * as mediasoupClient from "mediasoup-client";
-import type { RtpCapabilities, Device } from 'mediasoup-client/lib/types';
+import type { RtpCapabilities, Device } from 'mediasoup-client/types';
 
 export interface CreateDeviceClientOptions {
   rtpCapabilities: RtpCapabilities | null;
@@ -65,4 +65,3 @@ export const createDeviceClient = async ({
 };
 
 
-

package/src/ProducerClient/producerClientEmits/updateRoomParametersClient.ts

@@ -1,5 +1,5 @@
 /* eslint-disable eqeqeq */
-import { RtpCapabilities } from 'mediasoup-client/lib/types';
+import { RtpCapabilities } from 'mediasoup-client/types';
 import {
   QnHDCons,
   sdCons,

package/src/consumers/connectIps.ts

@@ -3,7 +3,7 @@ import { connectSocket } from "../../src/sockets/SocketManager";
 import { newPipeProducer } from "./socketReceiveMethods/newPipeProducer";
 import { producerClosed } from "./socketReceiveMethods/producerClosed";
 import { joinConsumeRoom } from "./socketReceiveMethods/joinConsumeRoom";
-import type { Device } from 'mediasoup-client/lib/types';
+import type { Device } from 'mediasoup-client/types';
 import {
   ReorderStreamsParameters, ReorderStreamsType, NewPipeProducerParameters, NewPipeProducerType, ProducerClosedType,
   ProducerClosedParameters, JoinConsumeRoomType, JoinConsumeRoomParameters, ConsumeSocket
@@ -36,6 +36,63 @@ 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.
+const pendingConsumeConnections = new WeakMap<
+  object,
+  Map<string, Promise<boolean>>
+>();
+
+const normalizeConsumeEndpoint = (ip: string): string =>
+  ip.trim().toLowerCase().replace(/\.$/, "");
+
+const hasConsumeEndpoint = (
+  consumeSockets: ConsumeSocket[],
+  endpoint: string
+): boolean => consumeSockets.some((socketObj) => {
+  const ip = Object.keys(socketObj)[0];
+  return Boolean(ip) && normalizeConsumeEndpoint(ip) === endpoint;
+});
+
+async function reserveConsumeEndpoint(
+  consumeSockets: ConsumeSocket[],
+  ip: string,
+  reservationOwner: object = consumeSockets
+): Promise<((connected?: boolean) => void) | null> {
+  const endpoint = normalizeConsumeEndpoint(ip);
+  if (!endpoint || endpoint === "none") return null;
+
+  let pendingForSockets = pendingConsumeConnections.get(reservationOwner);
+  if (!pendingForSockets) {
+    pendingForSockets = new Map<string, Promise<boolean>>();
+    pendingConsumeConnections.set(reservationOwner, pendingForSockets);
+  }
+
+  while (true) {
+    if (hasConsumeEndpoint(consumeSockets, endpoint)) return null;
+
+    const pending = pendingForSockets.get(endpoint);
+    if (pending) {
+      if (await pending) return null;
+      continue;
+    }
+
+    let resolvePending!: (connected: boolean) => void;
+    const reservation = new Promise<boolean>((resolve) => {
+      resolvePending = resolve;
+    });
+    pendingForSockets.set(endpoint, reservation);
+
+    return (didConnect = false) => {
+      if (pendingForSockets?.get(endpoint) === reservation) {
+        pendingForSockets.delete(endpoint);
+      }
+      resolvePending(didConnect === true);
+    };
+  }
+}
+
 /**
  * Connects to remote IPs and manages socket connections.
  *
@@ -105,15 +162,15 @@ export const connectIps = async ({
     }
 
     for (const ip of remIP) {
-      try {
-        // Check if the IP is already connected
-        const matching = consume_sockets.find((socketObj) => Object.keys(socketObj)[0] === ip);
-
-        if (matching || !ip) {
-          // Skip if the IP is already connected or invalid
-          continue;
-        }
+      const releaseReservation = await reserveConsumeEndpoint(
+        consume_sockets,
+        ip,
+        parameters?.socket || consume_sockets
+      );
+      if (!releaseReservation) continue;
 
+      let connected = false;
+      try {
         // Connect to the remote socket using socket.io-client
         const remote_sock = await connectSocket({ apiUserName, apiKey, apiToken, link: `https://${ip}.mediasfu.com` });
 
@@ -161,10 +218,13 @@ export const connectIps = async ({
           // Add the remote socket to the consume_sockets array
           consume_sockets.push({ [ip]: remote_sock });
           updateConsume_sockets(consume_sockets);
+          connected = true;
         }
       } catch (error) {
         // Handle the error
         console.log("connectIps error", error);
+      } finally {
+        releaseReservation(connected);
       }
     }
 

package/src/consumers/connectRecvTransport.ts

@@ -1,6 +1,6 @@
 import { Socket } from "socket.io-client";
 import { ConsumerResumeType, ConsumerResumeParameters, Transport as TransportType, Participant } from "../types/types";
-import type { Consumer, Device, Transport } from "mediasoup-client/lib/types";
+import type { Consumer, Device, Transport } from "mediasoup-client/types";
 
 interface SpeakerTranslationState {
   speakerId: string;

package/src/consumers/connectSendTransport.ts

@@ -1,4 +1,4 @@
-import type { ProducerOptions } from 'mediasoup-client/lib/types';
+import type { ProducerOptions } from 'mediasoup-client/types';
 import { ConnectSendTransportAudioType, ConnectSendTransportVideoType, ConnectSendTransportScreenType, ConnectSendTransportAudioParameters, ConnectSendTransportVideoParameters, ConnectSendTransportScreenParameters } from '../types/types';
 export interface ConnectSendTransportParameters extends ConnectSendTransportAudioParameters, ConnectSendTransportVideoParameters, ConnectSendTransportScreenParameters {
   audioParams: ProducerOptions 

package/src/consumers/connectSendTransportAudio.ts

@@ -1,4 +1,4 @@
-import type { Transport, Producer, ProducerOptions } from 'mediasoup-client/lib/types';
+import type { Transport, Producer, ProducerOptions } from 'mediasoup-client/types';
 
 export interface ConnectSendTransportAudioParameters {
   audioProducer: Producer | null;

package/src/consumers/connectSendTransportScreen.ts

@@ -1,4 +1,4 @@
-import type { Transport, Producer, Device, ProducerOptions } from 'mediasoup-client/lib/types';
+import type { Transport, Producer, Device, ProducerOptions } from 'mediasoup-client/types';
 
 export interface ConnectSendTransportScreenParameters {
   screenProducer: Producer | null;

package/src/consumers/connectSendTransportVideo.ts

@@ -1,4 +1,4 @@
-import type { Device, Producer, ProducerOptions, Transport } from 'mediasoup-client/lib/types';
+import type { Device, Producer, ProducerOptions, Transport } from 'mediasoup-client/types';
 
 export interface ConnectSendTransportVideoParameters {
   videoProducer: Producer | null;

package/src/consumers/createSendTransport.ts

@@ -1,4 +1,4 @@
-import type { Device, Transport, DtlsParameters } from 'mediasoup-client/lib/types';
+import type { Device, Transport, DtlsParameters } from 'mediasoup-client/types';
 import { Socket } from "socket.io-client";
 import {
   ConnectSendTransportParameters,

package/src/consumers/disconnectSendTransportAudio.ts

@@ -1,6 +1,6 @@
 import { Socket } from "socket.io-client";
 import { PrepopulateUserMediaType, PrepopulateUserMediaParameters } from "../types/types";
-import type { Producer } from 'mediasoup-client/lib/types';
+import type { Producer } from 'mediasoup-client/types';
 
 export interface DisconnectSendTransportAudioParameters extends PrepopulateUserMediaParameters {
   audioProducer: Producer | null;

package/src/consumers/disconnectSendTransportScreen.ts

@@ -1,4 +1,4 @@
-import type { Producer } from 'mediasoup-client/lib/types';
+import type { Producer } from 'mediasoup-client/types';
 import { Socket } from "socket.io-client";
 
 export interface DisconnectSendTransportScreenParameters {

package/src/consumers/disconnectSendTransportVideo.ts

@@ -1,4 +1,4 @@
-import type { Producer } from 'mediasoup-client/lib/types';
+import type { Producer } from 'mediasoup-client/types';
 import { Socket } from 'socket.io-client';
 import { ReorderStreamsType, ReorderStreamsParameters } from '../types/types';
 

package/src/consumers/index.ts

@@ -0,0 +1,61 @@
+export * from './autoAdjust';
+export * from './calculateRowsAndColumns';
+export * from './changeVids';
+export * from './checkGrid';
+export * from './checkPermission';
+export * from './checkScreenShare';
+export * from './closeAndResize';
+export * from './compareActiveNames';
+export * from './compareScreenStates';
+export * from './connectIps';
+export * from './connectLocalIps';
+export * from './connectRecvTransport';
+export * from './connectSendTransport';
+export * from './connectSendTransportAudio';
+export * from './connectSendTransportScreen';
+export * from './connectSendTransportVideo';
+export * from './consumerResume';
+export * from './controlMedia';
+export * from './createSendTransport';
+export * from './disconnectSendTransportAudio';
+export * from './disconnectSendTransportScreen';
+export * from './disconnectSendTransportVideo';
+export * from './dispStreams';
+export * from './generatePageContent';
+export * from './getEstimate';
+export * from './getPipedProducersAlt';
+export * from './getProducersPiped';
+export * from './getVideos';
+export * from './mixStreams';
+export * from './onScreenChanges';
+export * from './processConsumerTransports';
+export * from './processConsumerTransportsAudio';
+export * from './readjust';
+export * from './receiveAllPipedTransports';
+export * from './receiveRoomMessages';
+export * from './reorderStreams';
+export * from './rePort';
+export * from './requestScreenShare';
+export * from './resumePauseAudioStreams';
+export * from './resumePauseStreams';
+export * from './resumeSendTransportAudio';
+export * from './reUpdateInter';
+export * from './signalNewConsumerTransport';
+export * from './startShareScreen';
+export * from './stopShareScreen';
+export * from './streamSuccessAudio';
+export * from './streamSuccessAudioSwitch';
+export * from './streamSuccessScreen';
+export * from './streamSuccessVideo';
+export * from './switchUserAudio';
+export * from './switchUserVideo';
+export * from './switchUserVideoAlt';
+export * from './translationConsumerSwitch';
+export * from './trigger';
+export * from './updateMiniCardsGrid';
+export * from './updateParticipantAudioDecibels';
+export * from './gridLayout/addVideosGrid.engine';
+export * from './gridLayout/prepopulateUserMedia.engine';
+export * from './socketReceiveMethods/joinConsumeRoom';
+export * from './socketReceiveMethods/newPipeProducer';
+export * from './socketReceiveMethods/producerClosed';

package/src/consumers/resumeSendTransportAudio.ts

@@ -1,4 +1,4 @@
-import type { Producer } from 'mediasoup-client/lib/types';
+import type { Producer } from 'mediasoup-client/types';
 import { PrepopulateUserMediaParameters, PrepopulateUserMediaType } from "../types/types";
 
 export interface ResumeSendTransportAudioParameters extends PrepopulateUserMediaParameters {

package/src/consumers/signalNewConsumerTransport.ts

@@ -1,7 +1,7 @@
 import { Socket } from "socket.io-client";
 import { ReorderStreamsParameters, ReorderStreamsType, ConnectRecvTransportType,
    ConnectRecvTransportParameters, CreateWebRTCTransportResponse } from "../types/types";
-import type { Device, DtlsParameters  } from 'mediasoup-client/lib/types';
+import type { Device, DtlsParameters  } from 'mediasoup-client/types';
 
 export interface SignalNewConsumerTransportParameters extends ReorderStreamsParameters, ConnectRecvTransportParameters {
   device: Device | null;
@@ -176,4 +176,3 @@ export const signalNewConsumerTransport = async ({
     return;
   }
 };
-

package/src/consumers/socketReceiveMethods/joinConsumeRoom.ts

@@ -1,5 +1,5 @@
 import { joinConRoom } from '../../producers/producerEmits/joinConRoom';
-import type { Device, RtpCapabilities } from 'mediasoup-client/lib/types';
+import type { Device, RtpCapabilities } from 'mediasoup-client/types';
 import { Socket } from 'socket.io-client';
 import { ReceiveAllPipedTransportsParameters, ReceiveAllPipedTransportsType, CreateDeviceClientType } from '../../types/types';
 

package/src/consumers/socketReceiveMethods/newPipeProducer.ts

@@ -1,7 +1,7 @@
 import { Socket } from 'socket.io-client';
 import { signalNewConsumerTransport } from '../signalNewConsumerTransport';
 import { ReorderStreamsParameters, ReorderStreamsType, SignalNewConsumerTransportParameters, ConnectRecvTransportParameters, ConnectRecvTransportType, ShowAlert } from '../../types/types';
-import type { Device } from 'mediasoup-client/lib/types';
+import type { Device } from 'mediasoup-client/types';
 
 export interface TranslationMeta {
   speakerId: string;

package/src/consumers/streamSuccessAudio.ts

@@ -1,7 +1,7 @@
  
 
 import { Socket } from "socket.io-client";
-import type { ProducerOptions } from 'mediasoup-client/lib/types';
+import type { ProducerOptions } from 'mediasoup-client/types';
 import { Participant, PrepopulateUserMediaParameters, ShowAlert, CreateSendTransportParameters, ConnectSendTransportAudioParameters, ResumeSendTransportAudioParameters, PrepopulateUserMediaType, CreateSendTransportType, ConnectSendTransportAudioType, ResumeSendTransportAudioType } from "../types/types";
 export interface StreamSuccessAudioParameters extends CreateSendTransportParameters, ConnectSendTransportAudioParameters, ResumeSendTransportAudioParameters, PrepopulateUserMediaParameters {
   socket: Socket;
@@ -294,4 +294,3 @@ export const streamSuccessAudio = async ({
     }
   }
 };
-

package/src/consumers/streamSuccessAudioSwitch.ts

@@ -1,6 +1,6 @@
 
 
-import type { Producer, ProducerCodecOptions, ProducerOptions } from 'mediasoup-client/lib/types';
+import type { Producer, ProducerCodecOptions, ProducerOptions } from 'mediasoup-client/types';
 import { Socket } from "socket.io-client";
 import { PrepopulateUserMediaParameters, PrepopulateUserMediaType, CreateSendTransportParameters, CreateSendTransportType, ConnectSendTransportAudioParameters, ConnectSendTransportAudioType, SleepType } from "../types/types";
 
@@ -312,4 +312,3 @@ export const streamSuccessAudioSwitch = async ({
     }
   }
 };
-

package/src/consumers/streamSuccessVideo.ts

@@ -1,4 +1,4 @@
-import type { Device, Producer, ProducerOptions, RtpCodecCapability } from 'mediasoup-client/lib/types';
+import type { Device, Producer, ProducerOptions, RtpCodecCapability } from 'mediasoup-client/types';
 import { Socket } from "socket.io-client";
 import { ConnectSendTransportVideoParameters, Participant, ShowAlert, CreateSendTransportParameters, ReorderStreamsParameters, SleepType, CreateSendTransportType, ConnectSendTransportVideoType, ReorderStreamsType, HParamsType, VParamsType } from "../types/types";
 

package/src/index.ts

@@ -228,3 +228,5 @@ export * from './methods/stream/clickVideo';
 // virtualBackground, which requires an offscreen canvas and captureStream().
 export * from './methods/utils/headless';
 export * from './methods/utils/getParticipantMedia';
+// Shared web compositor used by headless virtual-background processing.
+export * from './methods/utils/virtualBackgroundCompositor';

package/src/methods/socketReceive/getDomains.ts

@@ -1,4 +1,4 @@
-import type { RtpCapabilities } from 'mediasoup-client/lib/types';
+import type { RtpCapabilities } from 'mediasoup-client/types';
 import type {
   AltDomains,
   ConsumeSocket,

package/src/methods/utils/headless/virtualBackground.ts

@@ -3,6 +3,7 @@ import { HeadlessOptions } from './headlessTypes';
 import { getCurrentParams } from './getCurrentParams';
 import { getLocalVideoStream } from './getMediaStreams';
 import { HeadlessActionResult } from './roomActions';
+import { compositeVirtualBackgroundFrame } from '../virtualBackgroundCompositor';
 
 const MEDIAPIPE_CDN = 'https://cdn.jsdelivr.net/npm/@mediapipe/selfie_segmentation';
 
@@ -15,7 +16,8 @@ const MEDIAPIPE_CDN = 'https://cdn.jsdelivr.net/npm/@mediapipe/selfie_segmentati
 interface BackgroundSession {
   stop: () => void;
   stream: MediaStream;
-  sourceTrack: MediaStreamTrack | null;
+  /** A live raw-camera clone that can be returned to the producer on clear. */
+  restoreTrack: MediaStreamTrack | null;
 }
 let session: BackgroundSession | null = null;
 
@@ -71,8 +73,8 @@ export type ApplyVirtualBackgroundType = (
  * without mounting the modal off-screen and simulating a click.
  *
  * This runs the same MediaPipe pipeline the modal uses — identical compositing:
- * draw the segmentation mask, `source-out` fill with the background pattern,
- * then `destination-atop` the camera frame — against an offscreen video and
+ * draw the segmentation mask, retain the person with `source-in`, then paint
+ * the replacement behind them with `destination-over` — against an offscreen video and
  * canvas it creates and owns.
  *
  * It also keeps the SDK's own state honest (`virtualStream`, `processedStream`,
@@ -115,21 +117,32 @@ export async function applyVirtualBackground({
     return { ok: false, error: 'Turn your camera on before applying a background.', stream: null };
   }
 
-  // Replacing an existing session must not leave the old loop running.
-  if (session) { session.stop(); session = null; }
-
+  const previousSession = session;
+  let candidateStop: (() => void) | null = null;
   try {
     const settings = sourceTrack.getSettings ? sourceTrack.getSettings() : {};
     const width = Number(settings.width) || 640;
     const height = Number(settings.height) || 360;
 
     const backgroundImage = typeof image === 'string' ? await loadImage(image) : image;
+    const producer = publish ? (live.videoProducer || live.localVideoProducer) : null;
+
+    // mediasoup Producers normally own their track (`stopTracks: true`). Their
+    // replaceTrack operation therefore stops the old raw track. Keep MediaPipe
+    // on an isolated clone and retain a second live clone for a clean clear.
+    const processingTrack = sourceTrack.clone?.();
+    if (!processingTrack) throw new Error('This camera cannot create the isolated track required for a virtual background.');
+    const restoreTrack = producer ? sourceTrack.clone?.() : sourceTrack;
+    if (!restoreTrack) {
+      processingTrack.stop();
+      throw new Error('This camera cannot preserve a track for restoring the original view.');
+    }
 
     const video = document.createElement('video');
     video.autoplay = true;
     video.muted = true;
     video.playsInline = true;
-    video.srcObject = new MediaStream([sourceTrack]);
+    video.srcObject = new MediaStream([processingTrack]);
     await video.play().catch(() => {});
 
     const canvas = document.createElement('canvas');
@@ -149,18 +162,14 @@ export async function applyVirtualBackground({
     segmentation.onResults((results: any) => {
       try {
         if (!canvas.width || !canvas.height) return;
-        ctx.save();
-        ctx.clearRect(0, 0, canvas.width, canvas.height);
-        ctx.drawImage(results.segmentationMask, 0, 0, canvas.width, canvas.height);
-        ctx.globalCompositeOperation = 'source-out';
-        if (backgroundImage) {
-          const pattern = ctx.createPattern(backgroundImage as CanvasImageSource, 'repeat');
-          ctx.fillStyle = pattern || 'transparent';
-          ctx.fillRect(0, 0, canvas.width, canvas.height);
-        }
-        ctx.globalCompositeOperation = 'destination-atop';
-        ctx.drawImage(results.image, 0, 0, canvas.width, canvas.height);
-        ctx.restore();
+        compositeVirtualBackgroundFrame({
+          ctx,
+          segmentationMask: results.segmentationMask,
+          sourceImage: results.image,
+          backgroundImage: backgroundImage as CanvasImageSource | null,
+          width: canvas.width,
+          height: canvas.height,
+        });
       } catch {
         // A dropped frame must never kill the loop.
       }
@@ -190,29 +199,35 @@ export async function applyVirtualBackground({
       window.cancelAnimationFrame(frameHandle);
       try { segmentation.close(); } catch { /* already closed */ }
       processed.getTracks().forEach((track) => track.stop());
+      processingTrack.stop();
       video.srcObject = null;
     };
-    session = { stop, stream: processed, sourceTrack };
-
-    // Keep the SDK's own view of the world correct, so getLocalVideoStream and
-    // getVirtualBackgroundState stay accurate without the caller intervening.
-    live.updateVirtualStream?.(processed);
-    live.updateProcessedStream?.(processed);
-    live.updateKeepBackground?.(true);
+    candidateStop = stop;
 
-    if (publish) {
-      const producer = live.videoProducer || live.localVideoProducer;
+    if (producer) {
       const track = processed.getVideoTracks()[0];
       if (producer && typeof producer.replaceTrack === 'function' && track) {
         // replaceTrack avoids renegotiation, so remote viewers see the
         // background appear without the call visibly reconnecting.
         await producer.replaceTrack({ track });
       }
+      if (camera?.removeTrack && camera?.addTrack && restoreTrack !== sourceTrack) {
+        camera.removeTrack(sourceTrack);
+        camera.addTrack(restoreTrack);
+        if (sourceTrack.readyState === 'live') sourceTrack.stop();
+      }
     }
 
+    previousSession?.stop();
+    session = { stop, stream: processed, restoreTrack };
+    candidateStop = null;
+    live.updateVirtualStream?.(processed);
+    live.updateProcessedStream?.(processed);
+    live.updateKeepBackground?.(true);
+
     return { ok: true, error: '', stream: processed };
   } catch (error: any) {
-    if (session) { session.stop(); session = null; }
+    candidateStop?.();
     return {
       ok: false,
       error: error?.message || 'The virtual background could not be applied.',
@@ -243,7 +258,7 @@ export async function clearVirtualBackground({
   }
   try {
     const producer = live.videoProducer || live.localVideoProducer;
-    const original = active.sourceTrack;
+    const original = active.restoreTrack;
     if (producer && typeof producer.replaceTrack === 'function'
       && original && original.readyState === 'live') {
       await producer.replaceTrack({ track: original });

package/src/methods/utils/virtualBackgroundCompositor.ts

@@ -0,0 +1,53 @@
+/** Options for composing one segmented camera frame. */
+export interface CompositeVirtualBackgroundFrameOptions {
+  ctx: CanvasRenderingContext2D;
+  segmentationMask: CanvasImageSource;
+  sourceImage: CanvasImageSource;
+  backgroundImage?: CanvasImageSource | null;
+  width: number;
+  height: number;
+  repeatPattern?: 'repeat' | 'repeat-x' | 'repeat-y' | 'no-repeat';
+  blurFallbackPixels?: number;
+}
+
+/**
+ * Paint the segmented person over a replacement background.
+ *
+ * Keeping this operation in the shared runtime makes headless web adapters and
+ * the React SDK use the same compositing contract. It is deliberately not
+ * exported from the native entry point; native platforms use their camera
+ * processor instead of a browser canvas.
+ */
+export function compositeVirtualBackgroundFrame({
+  ctx,
+  segmentationMask,
+  sourceImage,
+  backgroundImage = null,
+  width,
+  height,
+  repeatPattern = 'repeat',
+  blurFallbackPixels = 0,
+}: CompositeVirtualBackgroundFrameOptions): void {
+  const previousFilter = ctx.filter;
+  ctx.save();
+  try {
+    ctx.clearRect(0, 0, width, height);
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.drawImage(segmentationMask, 0, 0, width, height);
+    ctx.globalCompositeOperation = 'source-in';
+    ctx.drawImage(sourceImage, 0, 0, width, height);
+    ctx.globalCompositeOperation = 'destination-over';
+    if (backgroundImage) {
+      const pattern = ctx.createPattern(backgroundImage, repeatPattern);
+      ctx.fillStyle = pattern || 'transparent';
+      ctx.fillRect(0, 0, width, height);
+    } else if (blurFallbackPixels > 0) {
+      ctx.filter = `blur(${blurFallbackPixels}px)`;
+      ctx.drawImage(sourceImage, 0, 0, width, height);
+    }
+  } finally {
+    ctx.filter = previousFilter || 'none';
+    ctx.globalCompositeOperation = 'source-over';
+    ctx.restore();
+  }
+}

package/src/methods/whiteboard/captureCanvasStream.ts

@@ -1,4 +1,4 @@
-import type { Producer } from 'mediasoup-client/lib/types';
+import type { Producer } from 'mediasoup-client/types';
 import type {
   ConnectSendTransportScreenParameters,
   ConnectSendTransportScreenType,
@@ -125,4 +125,4 @@ export const captureCanvasStream = async ({
   } catch (error) {
     console.error(error, 'error in captureCanvasStream');
   }
-};
+};

package/src/producers/producerEmits/joinConRoom.ts

@@ -1,6 +1,6 @@
 import { Socket } from "socket.io-client";
 import { validateAlphanumeric } from "../../methods/utils/validateAlphanumeric"; // Import the validateAlphanumeric function from the validateAlphanumeric file
-import type { RtpCapabilities } from "mediasoup-client/lib/types";
+import type { RtpCapabilities } from "mediasoup-client/types";
 
 export interface JoinConRoomOptions {
   socket: Socket;