mediasfu-shared 1.2.6 → 1.3.0

package/src/consumers/screenAudio.ts

@@ -0,0 +1,132 @@
+import type { Producer } from "mediasoup-client/types";
+import { Participant } from "../types/types";
+
+/**
+ * Screen audio: the audio of a shared tab, window or screen, published as its own producer tagged
+ * `appData.mediaTag === "screen-audio"`. It belongs to the screen share (starts, pauses, resumes and stops with it),
+ * never to the sharer's microphone, so it never marks the sharer as speaking.
+ *
+ * A client only publishes it when the media server says so in the join response (`supportsScreenAudio`), so new
+ * clients keep today's video-only screen share on older servers.
+ */
+export const SCREEN_AUDIO_MEDIA_TAG = "screen-audio";
+
+/** Opus settings for shared media (music, video soundtracks) rather than voice. */
+export const SCREEN_AUDIO_CODEC_OPTIONS = {
+  opusStereo: true,
+  opusDtx: false,
+  opusFec: true,
+  opusMaxAverageBitrate: 128000,
+};
+
+// Producer ids are globally unique, so one registry serves every room instance on the page.
+const screenAudioProducerIds = new Set<string>();
+
+/** Records a producer announced by the server as screen audio (`mediaTag: "screen-audio"`). */
+export const markScreenAudioProducer = (producerId?: string | null, mediaTag?: string | null): void => {
+  if (producerId && mediaTag === SCREEN_AUDIO_MEDIA_TAG) screenAudioProducerIds.add(producerId);
+};
+
+export const forgetScreenAudioProducer = (producerId?: string | null): void => {
+  if (producerId) screenAudioProducerIds.delete(producerId);
+};
+
+export interface IsScreenAudioProducerOptions {
+  producerId: string;
+  participants?: Participant[];
+  appData?: Record<string, unknown> | null;
+}
+
+/** True when the producer is screen audio, by server tag, consumer appData or the sharer's `ScreenAudioID`. */
+export const isScreenAudioProducer = ({ producerId, participants = [], appData }: IsScreenAudioProducerOptions): boolean => {
+  if (!producerId) return false;
+  if (screenAudioProducerIds.has(producerId)) return true;
+  if (appData?.mediaTag === SCREEN_AUDIO_MEDIA_TAG) return true;
+  return participants.some((participant) => participant?.ScreenAudioID === producerId);
+};
+
+/**
+ * How a screen share treats audio: `ask` (default) shows a choice before the browser's picker, `always` requests audio
+ * without asking, `never` shares video only.
+ */
+export type ScreenAudioMode = "ask" | "always" | "never";
+
+export interface ScreenAudioSettings {
+  supportsScreenAudio?: boolean;
+  screenAudioEnabled?: boolean;
+  screenAudioMode?: ScreenAudioMode;
+}
+
+/** Screen audio is requested only when the server supports it and the app has not turned it off. */
+export const shouldShareScreenAudio = ({ supportsScreenAudio, screenAudioEnabled, screenAudioMode }: ScreenAudioSettings): boolean =>
+  supportsScreenAudio === true && screenAudioEnabled !== false && screenAudioMode !== "never";
+
+/**
+ * Whether this browser can capture the audio of a shared tab or screen. Chromium desktop browsers (Chrome, Edge,
+ * Opera, Brave) can; Firefox, Safari and mobile browsers return video only.
+ */
+export const canCaptureDisplayAudio = (nav: Partial<Navigator> | undefined = typeof navigator !== "undefined" ? navigator : undefined): boolean => {
+  if (!nav) return false;
+  const ua = String(nav.userAgent || "");
+  if (/Mobi|Android|iPhone|iPad|iPod/i.test(ua)) return false;
+  const brands: string[] = ((nav as any).userAgentData?.brands || []).map((entry: { brand?: string }) => String(entry?.brand || ""));
+  if (brands.some((brand) => /Chromium|Google Chrome|Microsoft Edge|Opera|Brave/i.test(brand))) return true;
+  return /(Chrome|Chromium|Edg)\//.test(ua) && !/Firefox|FxiOS|OPiOS/.test(ua);
+};
+
+/** The user's answer to "share audio too?": `audio`, `video` (screen only) or `null` (cancelled). */
+export type ScreenAudioChoice = "audio" | "video" | null;
+
+/** Mutes or unmutes the sharer's screen audio without stopping the screen share. Returns the new paused state. */
+export const setScreenAudioPaused = (producer: Producer | null | undefined, paused: boolean): boolean => {
+  if (!producer || producer.closed) return false;
+  if (paused && !producer.paused) producer.pause();
+  if (!paused && producer.paused) producer.resume();
+  return producer.paused;
+};
+
+export interface DisplayMediaOptionsInput {
+  targetWidth: number;
+  targetHeight: number;
+  withAudio: boolean;
+}
+
+/**
+ * Options for `getDisplayMedia`. With audio, the browser's picker shows its own "share audio" choice, which is the
+ * user's consent; browsers that cannot capture display audio (Firefox, Safari) return a video-only stream.
+ */
+export const buildDisplayMediaOptions = ({ targetWidth, targetHeight, withAudio }: DisplayMediaOptionsInput) => {
+  const options: Record<string, unknown> = {
+    video: { width: targetWidth, height: targetHeight, frameRate: 30 },
+    audio: withAudio
+      ? { echoCancellation: false, noiseSuppression: false, autoGainControl: false }
+      : false,
+  };
+  if (withAudio) {
+    // Chromium hints; other browsers ignore unknown members.
+    options.systemAudio = "include";
+    options.suppressLocalAudioPlayback = false;
+  }
+  return options as DisplayMediaStreamOptions;
+};
+
+// Fallback holder for apps whose parameters have no `screenAudioProducer` state.
+const producersBySocket = new WeakMap<object, Producer>();
+
+export const rememberScreenAudioProducer = (socket: object | null | undefined, producer: Producer | null): void => {
+  if (!socket) return;
+  if (producer) producersBySocket.set(socket, producer);
+  else producersBySocket.delete(socket);
+};
+
+export const recallScreenAudioProducer = (socket: object | null | undefined): Producer | null =>
+  (socket && producersBySocket.get(socket)) || null;
+
+/** Sets the listening volume (0..1) of every screen-audio player on the page. */
+export const setScreenAudioVolume = (volume: number, root: ParentNode | null = typeof document !== "undefined" ? document : null): void => {
+  if (!root) return;
+  const value = Math.min(1, Math.max(0, Number.isFinite(volume) ? volume : 1));
+  root.querySelectorAll<HTMLAudioElement>('audio[data-screen-audio="true"]').forEach((element) => {
+    element.volume = value;
+  });
+};

package/src/consumers/socketReceiveMethods/producerClosed.ts

@@ -1,4 +1,5 @@
 import { Transport, CloseAndResizeParameters, CloseAndResizeType } from '../../types/types';
+import { forgetScreenAudioProducer } from '../screenAudio';
 
 export interface ProducerClosedParameters extends CloseAndResizeParameters {
   consumerTransports: Transport[];
@@ -63,6 +64,8 @@ export const producerClosed = async ({
 }: ProducerClosedOptions): Promise<void> => {
   let { consumerTransports, closeAndResize, screenId, updateConsumerTransports } = parameters;
 
+  forgetScreenAudioProducer(remoteProducerId);
+
   const activeTranslationProducerIds = parameters.activeTranslationProducerIds;
   const isTranslationProducer = activeTranslationProducerIds?.has?.(remoteProducerId);
 

package/src/consumers/startShareScreen.ts

@@ -1,5 +1,12 @@
 
 import { StreamSuccessScreenType, StreamSuccessScreenParameters, ShowAlert } from "../types/types";
+import {
+  buildDisplayMediaOptions,
+  canCaptureDisplayAudio,
+  shouldShareScreenAudio,
+  ScreenAudioChoice,
+  ScreenAudioMode,
+} from "./screenAudio";
 export interface StartShareScreenParameters extends StreamSuccessScreenParameters {
   shared: boolean;
   showAlert?: ShowAlert;
@@ -8,6 +15,19 @@ export interface StartShareScreenParameters extends StreamSuccessScreenParameter
   onWeb: boolean;
   targetWidth?: number;
   targetHeight?: number;
+  /** Set from the join response: the media server accepts screen audio. */
+  supportsScreenAudio?: boolean;
+  /** Ask the browser for the screen's audio too (default true; the browser's picker still lets the user decide). */
+  screenAudioEnabled?: boolean;
+  /** `ask` (default): offer "Screen + audio" / "Screen only" first; `always`: request audio; `never`: video only. */
+  screenAudioMode?: ScreenAudioMode;
+  /**
+   * The "share audio too?" dialog: resolve `audio`, `video` or `null` (cancel). Each UI SDK supplies its own. Without
+   * one, `ask` requests audio and leaves the choice to the browser picker's own "share audio" checkbox.
+   */
+  screenAudioPrompt?: () => Promise<ScreenAudioChoice>;
+  /** Override browser detection of display-audio capture (Chromium desktop by default). */
+  displayAudioCapable?: boolean;
 
   // mediasfu functions
   streamSuccessScreen: StreamSuccessScreenType;
@@ -71,6 +91,11 @@ export async function startShareScreen({ parameters }: StartShareScreenOptions):
     onWeb,
     targetWidth = 1280,
     targetHeight = 720,
+    supportsScreenAudio,
+    screenAudioEnabled,
+    screenAudioMode = "ask",
+    screenAudioPrompt,
+    displayAudioCapable,
 
     streamSuccessScreen,
   } = parameters;
@@ -86,16 +111,27 @@ export async function startShareScreen({ parameters }: StartShareScreenOptions):
     }
 
     if (mediaDevices && mediaDevices.getDisplayMedia) {
+      // Screen audio needs a server that accepts it and a browser that can capture it (Chromium desktop).
+      let withAudio =
+        shouldShareScreenAudio({ supportsScreenAudio, screenAudioEnabled, screenAudioMode }) &&
+        (displayAudioCapable ?? canCaptureDisplayAudio());
+      if (withAudio && screenAudioMode === "ask" && screenAudioPrompt) {
+        const choice = await screenAudioPrompt();
+        if (choice === null) {
+          updateShared(false);
+          return;
+        }
+        withAudio = choice === "audio";
+      }
       shared = true;
       await mediaDevices
-        .getDisplayMedia({
-          video: {
-            width: targetWidth,
-            height: targetHeight,
-            frameRate: 30,
-          },
-          audio: false,
-        })
+        .getDisplayMedia(
+          buildDisplayMediaOptions({
+            targetWidth,
+            targetHeight,
+            withAudio,
+          })
+        )
         .then(async (stream: MediaStream) => {
           await streamSuccessScreen({ stream, parameters });
         })

package/src/consumers/streamSuccessScreen.ts

@@ -1,6 +1,7 @@
  
 
 import { Socket } from "socket.io-client";
+import { connectSendTransportScreenAudio } from "./connectSendTransportScreenAudio";
 import {
   SleepType, CreateSendTransportType, ConnectSendTransportScreenType, DisconnectSendTransportScreenType, StopShareScreenType, ReorderStreamsType, PrepopulateUserMediaType, RePortType,
   ShowAlert, CreateSendTransportParameters, ConnectSendTransportScreenParameters, DisconnectSendTransportScreenParameters, StopShareScreenParameters, ReorderStreamsParameters, PrepopulateUserMediaParameters, RePortParameters,
@@ -179,6 +180,16 @@ export const streamSuccessScreen = async ({
 
     // Alert the socket that you are sharing the screen
     socket.emit("startScreenShare");
+
+    // Share the screen's audio too, when the browser captured it and the server supports it.
+    try {
+      await connectSendTransportScreenAudio({
+        stream: localStreamScreen,
+        parameters: getUpdatedAllParams() as any,
+      });
+    } catch (error) {
+      console.log("Screen audio not shared:", error);
+    }
   } catch (error: any) {
     showAlert?.({
       message: error.message,

package/src/index.native.ts

@@ -17,6 +17,9 @@ export * from './consumers/connectSendTransport';
 export * from './consumers/connectSendTransportAudio';
 export * from './consumers/consumerResume';
 export * from './consumers/connectSendTransportScreen';
+export * from './consumers/connectSendTransportScreenAudio';
+export * from './consumers/screenAudio';
+export * from './consumers/consumerBackupPreference';
 export * from './consumers/connectSendTransportVideo';
 export * from './consumers/controlMedia';
 export * from './consumers/createSendTransport';
@@ -217,6 +220,7 @@ export * from './producers/producerEmits/joinLocalRoom';
 export * from './producers/producerEmits/joinRoom';
 
 export * from './sockets/SocketManager';
+export * from './sockets/mediaSocketErrors';
 
 export * from './methods/stream/clickVideo';
 

package/src/index.ts

@@ -20,6 +20,9 @@ export * from './consumers/connectSendTransport';
 export * from './consumers/connectSendTransportAudio';
 export * from './consumers/consumerResume';
 export * from './consumers/connectSendTransportScreen';
+export * from './consumers/connectSendTransportScreenAudio';
+export * from './consumers/screenAudio';
+export * from './consumers/consumerBackupPreference';
 export * from './consumers/connectSendTransportVideo';
 export * from './consumers/controlMedia';
 export * from './consumers/createSendTransport';
@@ -222,6 +225,7 @@ export * from './producers/producerEmits/joinLocalRoom';
 export * from './producers/producerEmits/joinRoom';
 // Socket exports
 export * from './sockets/SocketManager';
+export * from './sockets/mediaSocketErrors';
 // Stream method exports (clickVideo)
 export * from './methods/stream/clickVideo';
 

package/src/methods/socketReceive/getDomains.ts

@@ -3,6 +3,7 @@ import type {
   AltDomains,
   ConsumeSocket,
 } from '../../types/types';
+import { rememberConsumerBackups } from "../../consumers/consumerBackupPreference";
 
 export interface ConnectIpsLikeOptions<
   TParameters = unknown,
@@ -88,6 +89,9 @@ export const getDomains = async <
   let { roomRecvIPs, consume_sockets, connectIps } = parameters;
   const ipsToConnect: string[] = [];
 
+  // Busy node -> backup map: new streams are preferred from the backup (consumer-backup-v1).
+  rememberConsumerBackups(alt_domains);
+
   try {
     consume_sockets = parameters.getUpdatedAllParams().consume_sockets;
 

package/src/methods/utils/checkLimitsAndMakeRequest.ts

@@ -1,4 +1,9 @@
 import { PreJoinPageParameters } from "../../types/types";
+import {
+  describeMediaSocketError,
+  isMediaSocketConnectError,
+  isNetworkOnlyMediaSocketError,
+} from "../../sockets/mediaSocketErrors";
 import type { Socket } from "socket.io-client";
 import Cookies from "universal-cookie";
 
@@ -148,15 +153,19 @@ export const checkLimitsAndMakeRequestWithStorage: CheckLimitsAndMakeRequestWith
   } catch (error) {
     console.error('Error connecting to socket:', error);
     parameters.showAlert?.({
-      message: 'Unable to connect. Check your credentials and try again.',
+      message: describeMediaSocketError(error),
       type: 'danger',
-      duration: 3000,
+      duration: isMediaSocketConnectError(error) ? 6000 : 3000,
     });
 
-    let unsuccessfulAttempts = await readStoredNumber(storageAdapter, 'unsuccessfulAttempts');
-    unsuccessfulAttempts += 1;
-    await writeStoredNumber(storageAdapter, 'unsuccessfulAttempts', unsuccessfulAttempts);
-    await writeStoredNumber(storageAdapter, 'lastRequestTimestamp', Date.now());
+    // Only a refusal or an unknown failure counts toward the attempt limit; a device/network problem is not a
+    // credential guess.
+    if (!isNetworkOnlyMediaSocketError(error)) {
+      let unsuccessfulAttempts = await readStoredNumber(storageAdapter, 'unsuccessfulAttempts');
+      unsuccessfulAttempts += 1;
+      await writeStoredNumber(storageAdapter, 'unsuccessfulAttempts', unsuccessfulAttempts);
+      await writeStoredNumber(storageAdapter, 'lastRequestTimestamp', Date.now());
+    }
     parameters.updateIsLoadingModalVisible(false);
   }
 };
@@ -244,14 +253,18 @@ export const checkLimitsAndMakeRequest = async ({
           duration: 3000,
         });
       }
-    } catch {
+    } catch (error) {
       parameters.showAlert?.({
-        message: "Unable to connect. Check your credentials and try again.",
+        message: describeMediaSocketError(error),
         type: "danger",
-        duration: 3000,
+        duration: isMediaSocketConnectError(error) ? 6000 : 3000,
       });
-      unsuccessfulAttempts += 1;
-      cookies.set("unsuccessfulAttempts", unsuccessfulAttempts.toString());
+      // Only a refusal or an unknown failure counts toward the attempt limit; a device/network problem is not a
+      // credential guess.
+      if (!isNetworkOnlyMediaSocketError(error)) {
+        unsuccessfulAttempts += 1;
+        cookies.set("unsuccessfulAttempts", unsuccessfulAttempts.toString());
+      }
       parameters.updateIsLoadingModalVisible(false);
     }
   };

package/src/methods/utils/createResponseJoinRoom.ts

@@ -27,6 +27,7 @@ export const createResponseJoinRoom: CreateResponseJoinRoomType = async ({
   localRoom,
 }: CreateResponseJoinRoomOptions): Promise<ResponseJoinRoom> => {
   return {
+    capacity: localRoom.capacity,
     rtpCapabilities: localRoom.rtpCapabilities ?? null,
     success: localRoom.rtpCapabilities !== null,
     roomRecvIPs: [],
@@ -44,4 +45,4 @@ export const createResponseJoinRoom: CreateResponseJoinRoomType = async ({
     suspended: false,
     noAdmin: localRoom.hostNotJoined,
   };
-};
+};

package/src/methods/welcome/handleWelcomeRequest.ts

@@ -1,4 +1,9 @@
 import type { Socket } from 'socket.io-client';
+import {
+  describeMediaSocketError,
+  isMediaSocketConnectError,
+  isNetworkOnlyMediaSocketError,
+} from '../../sockets/mediaSocketErrors';
 import Cookies from 'universal-cookie';
 import type { PreJoinPageParameters } from '../../types/types';
 
@@ -183,16 +188,20 @@ export async function handleWelcomeRequest({
         });
       }
     }
-  } catch {
+  } catch (error) {
     showAlert?.({
-      message: 'Unable to connect. Check your credentials and try again.',
+      message: describeMediaSocketError(error),
       type: 'danger',
-      duration: 3000,
+      duration: isMediaSocketConnectError(error) ? 6000 : 3000,
     });
 
-    unsuccessfulAttempts += 1;
-    cookies.set('unsuccessfulAttempts', unsuccessfulAttempts.toString());
-    cookies.set('lastRequestTimestamp', Date.now().toString());
+    // Only a refusal or an unknown failure counts toward the attempt limit; a device/network problem is not a
+    // credential guess.
+    if (!isNetworkOnlyMediaSocketError(error)) {
+      unsuccessfulAttempts += 1;
+      cookies.set('unsuccessfulAttempts', unsuccessfulAttempts.toString());
+      cookies.set('lastRequestTimestamp', Date.now().toString());
+    }
     updateIsLoadingModalVisible(false);
   }
 }

package/src/sockets/SocketManager.ts

@@ -2,6 +2,13 @@
 // Socket manager for media socket.
 import { MeetingRoomParams, RecordingParams } from '../types/types';
 import io, { Socket } from 'socket.io-client'; // Importing socket type
+import {
+  MediaSocketConnectError,
+  MediaSocketConnectPhase,
+  MediaConnectionRejectionReason,
+  currentOnlineState,
+  normalizeRejectionReason,
+} from './mediaSocketErrors';
 
 /**
  * Validates the provided API key or token.
@@ -62,6 +69,10 @@ export type ConnectLocalSocketType = (options: ConnectLocalSocketOptions) => Pro
  * @param {string} options.link - The socket link.
  *
  * @returns {Promise<Socket>} A promise that resolves to the connected socket.
+ * @throws {MediaSocketConnectError} When the connection fails. `phase` says where (`before-open`, `after-open`,
+ *   `rejected`, `timeout`), `reason`/`stage` carry the server's `connection-rejected` verdict, `elapsedMs` and `online`
+ *   help tell a device/network problem from a refusal, and `retryable` is false for rejections that cannot succeed
+ *   with the same credentials. `describeMediaSocketError(error)` turns it into a user-facing sentence.
  *
  * @example
  * ```typescript
@@ -135,16 +146,32 @@ async function connectSocket(
       });
     }
 
-    // Dispose failed handshakes immediately. Otherwise Socket.IO continues
-    // reconnecting a client that was never handed to the room lifecycle.
+    // Every path below runs at most once, clears handshake listeners/timers,
+    // and closes failed clients so Socket.IO cannot keep reconnecting an
+    // orphan that the room lifecycle never received.
     let settled = false;
     let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+    const startedAt = Date.now();
+    let transportOpened = false;
+    let rejection: { reason: MediaConnectionRejectionReason; stage?: string } | null = null;
     const cleanupHandshake = () => {
       if (timeoutHandle) clearTimeout(timeoutHandle);
       socket.off('connection-success', handleConnectionSuccess);
       socket.off('connect_error', handleConnectError);
       socket.off('disconnect', handleDisconnectBeforeReady);
+      socket.off('connect', handleTransportOpen);
+      socket.off('connection-rejected', handleConnectionRejected);
     };
+    const failure = (phase: MediaSocketConnectPhase, transportError?: string) =>
+      new MediaSocketConnectError({
+        phase: rejection ? 'rejected' : phase,
+        reason: rejection?.reason,
+        stage: rejection?.stage,
+        elapsedMs: Date.now() - startedAt,
+        online: currentOnlineState(),
+        transportError,
+        link,
+      });
     const settle = (action: () => void) => {
       if (settled) return;
       settled = true;
@@ -152,6 +179,7 @@ async function connectSocket(
       action();
     };
 
+    // Handle socket connection events
     const handleConnectionSuccess = ({ socketId }: { socketId: string }) => {
       //check if link contains mediasfu.com and contains more than one c
       let conn = 'media';
@@ -170,24 +198,47 @@ async function connectSocket(
     const handleConnectError = (error: Error) => {
       settle(() => {
         socket.disconnect();
-        reject(new Error('Error connecting to media socket: ' + error.message));
+        reject(failure(transportOpened ? 'after-open' : 'before-open', error?.message));
       });
     };
 
+    const handleTransportOpen = () => {
+      transportOpened = true;
+    };
+
+    // Media admission v2: the node says why before it closes the handshake. Socket.IO's own reconnection never
+    // retries a server-side close, and settling here stops this attempt from being retried as a network error.
+    const handleConnectionRejected = (payload?: { reason?: string; stage?: string }) => {
+      rejection = {
+        reason: normalizeRejectionReason(payload?.reason),
+        stage: typeof payload?.stage === 'string' ? payload.stage : undefined,
+      };
+      settle(() => {
+        try {
+          socket.disconnect();
+        } catch {
+          // Already closing.
+        }
+        reject(failure('rejected'));
+      });
+    };
+
+    // The transport can connect and then be dropped by the server before it
+    // ever sends `connection-success` — a rejected room, an expired token, a
+    // bad handshake. Without this the promise stayed pending forever, so the
+    // caller's loading modal never came down and no error was ever surfaced.
     const handleDisconnectBeforeReady = (reason: string) => {
-      settle(() =>
-        reject(
-          new Error(
-            'Media socket closed before the room was ready (' + reason + ').'
-          )
-        )
-      );
+      settle(() => reject(failure('after-open', reason)));
     };
 
     socket.on('connection-success', handleConnectionSuccess);
     socket.on('connect_error', handleConnectError);
     socket.on('disconnect', handleDisconnectBeforeReady);
+    socket.on('connect', handleTransportOpen);
+    socket.on('connection-rejected', handleConnectionRejected);
 
+    // Last resort, for the case where the socket neither connects, errors nor
+    // disconnects. Nothing above guarantees a settle on its own.
     timeoutHandle = setTimeout(() => {
       settle(() => {
         try {
@@ -195,7 +246,7 @@ async function connectSocket(
         } catch {
           // Nothing useful to do here.
         }
-        reject(new Error('Timed out connecting to media socket.'));
+        reject(failure('timeout'));
       });
     }, CONNECT_TIMEOUT_MS);
   });
@@ -237,6 +288,11 @@ async function connectLocalSocket({ link }: ConnectLocalSocketOptions): Promise<
     socket = io(`${link}/media`, {
       transports: ['websocket'],
     });
+    const startedAt = Date.now();
+    let transportOpened = false;
+    socket.on('connect', () => {
+      transportOpened = true;
+    });
 
 
     // Handle socket connection events
@@ -245,7 +301,15 @@ async function connectLocalSocket({ link }: ConnectLocalSocketOptions): Promise<
     });
 
     socket.on('connect_error', (error: Error) => {
-      reject(new Error('Error connecting to media socket: ' + error.message));
+      reject(
+        new MediaSocketConnectError({
+          phase: transportOpened ? 'after-open' : 'before-open',
+          elapsedMs: Date.now() - startedAt,
+          online: currentOnlineState(),
+          transportError: error?.message,
+          link,
+        })
+      );
     });
   });
 }