mediasfu-shared 1.0.6 → 1.2.0

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

@@ -0,0 +1,49 @@
+import { HeadlessOptions, RoomReadiness } from './headlessTypes';
+
+export type GetRoomReadinessType = (options: HeadlessOptions) => RoomReadiness;
+
+/**
+ * Is the room actually usable yet?
+ *
+ * Headless consumers repeatedly re-derive this same predicate and each one picks
+ * a slightly different subset, so a control fires before the transport exists
+ * and fails silently. The five conditions below are the real gate: a room name,
+ * a member identity, server-side validation, a connected emittable socket, and a
+ * loaded mediasoup device.
+ *
+ * `reason` is safe to show a user — it names what is still pending, never an
+ * endpoint, credential, or internal identifier.
+ *
+ * @example
+ * ```ts
+ * import { getRoomReadiness } from 'mediasfu-shared';
+ *
+ * const { ready, reason } = getRoomReadiness({ parameters });
+ * if (!ready) return <p>{reason}</p>;
+ * ```
+ */
+export function getRoomReadiness({ parameters }: HeadlessOptions): RoomReadiness {
+  const source = parameters || {};
+  if (!source.roomName) {
+    return { ready: false, reason: 'Waiting for the room name.' };
+  }
+  if (!source.member) {
+    return { ready: false, reason: 'Waiting for the participant identity.' };
+  }
+  if (source.validated !== true) {
+    return { ready: false, reason: 'Waiting for MediaSFU to validate the room.' };
+  }
+  const socket = source.socket;
+  if (!socket || socket.connected !== true) {
+    return { ready: false, reason: 'Connecting to the MediaSFU room.' };
+  }
+  if (typeof socket.emit !== 'function') {
+    return { ready: false, reason: 'The room signal is not ready yet.' };
+  }
+  if (source.device?.loaded !== true) {
+    return { ready: false, reason: 'Waiting for the MediaSFU media device.' };
+  }
+  return { ready: true, reason: '' };
+}
+
+export default getRoomReadiness;

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

@@ -0,0 +1,102 @@
+import { Participant, Stream } from '../../../types/types';
+
+/**
+ * The MediaSFU parameter bag.
+ *
+ * This is the object handed to `updateSourceParameters`. Every field on it is a
+ * snapshot of an internal ref (`allVideoStreams.current`, `localStreamVideo.current`,
+ * …) taken at publish time, and the SDK **reassigns** those refs rather than
+ * mutating them — so a bag you hold onto goes stale as soon as a producer or
+ * consumer changes. Always read from the most recent publication.
+ */
+export interface HeadlessParameters {
+  // Room identity / readiness
+  roomName?: string;
+  member?: string;
+  islevel?: string;
+  validated?: boolean;
+  socket?: any;
+  localSocket?: any;
+  device?: { loaded?: boolean; [key: string]: any };
+
+  // Participants
+  participants?: Participant[];
+  participantsAll?: Participant[];
+
+  // Media collections
+  allVideoStreams?: (Participant | Stream)[];
+  allAudioStreams?: (Participant | Stream)[];
+  oldAllStreams?: (Participant | Stream)[];
+  audioOnlyStreams?: any[];
+  translationStreams?: any[];
+
+  // Local media
+  localStream?: MediaStream | null;
+  localStreamVideo?: MediaStream | null;
+  localStreamAudio?: MediaStream | null;
+  localStreamScreen?: MediaStream | null;
+  virtualStream?: MediaStream | null;
+  keepBackground?: boolean;
+  audioAlreadyOn?: boolean;
+  videoAlreadyOn?: boolean;
+
+  // Screen share
+  remoteScreenStream?: (Participant | Stream)[] | { stream?: MediaStream } | null;
+  shareScreenStarted?: boolean;
+  shared?: boolean;
+
+  // Chat
+  messages?: any[];
+  coHost?: string;
+  coHostResponsibility?: any[];
+  chatSetting?: string;
+  showAlert?: (options: any) => void;
+
+  // Audio activity
+  audioLevel?: number;
+  audioDecibels?: { name: string; averageLoudness: number }[];
+
+  // SDK function map
+  /** Republishes as a side effect — prefer `getCurrentParams`. */
+  getUpdatedAllParams?: () => any;
+  /** Pure read of the current bag. No republish. */
+  getCurrentParams?: () => any;
+  getParticipantMedia?: (...args: any[]) => Promise<MediaStream | null>;
+  getMediaDevicesList?: (
+    kind: 'videoinput' | 'audioinput'
+  ) => Promise<MediaDeviceInfo[]>;
+  updateAutoWave?: (value: boolean) => void;
+
+  /**
+   * Server-provided playback URLs, when the room has them provisioned.
+   *
+   * Unlike WebRTC media these are never consumed automatically — see
+   * getPlaybackSources/attachPlayback. Absence means the room has no HLS or
+   * WHEP egress, not an error.
+   */
+  hlsUrl?: string;
+  hlsPlaybackUrl?: string;
+  playbackUrl?: string;
+  whepUrl?: string;
+  whepPlaybackUrl?: string;
+  [key: string]: any;
+}
+
+export interface HeadlessOptions {
+  /** The most recent parameter bag from `updateSourceParameters`. */
+  parameters: HeadlessParameters;
+}
+
+/** A resolved media entry with the producer reference that identifies it. */
+export interface ResolvedMedia {
+  stream: MediaStream;
+  producerId: string;
+  /** Participant display name when the SDK exposes one for this producer. */
+  name: string;
+}
+
+export interface RoomReadiness {
+  ready: boolean;
+  /** Empty when ready; otherwise a short, user-safe explanation. */
+  reason: string;
+}

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

@@ -0,0 +1,28 @@
+/**
+ * Headless helpers for `returnUI={false}` integrations.
+ *
+ * These exist because every headless consumer was re-deriving the same handful
+ * of rules from the raw parameter bag, and getting them subtly wrong in ways
+ * that only show up on a live call: a host whose video vanishes when the SDK
+ * moves their stream to `oldAllStreams`, participants who are silently
+ * inaudible because the audio element list was truncated, a self-view showing
+ * the unprocessed camera when a virtual background is on, or a tab that locks
+ * because `getUpdatedAllParams()` was called from a click handler.
+ *
+ * Import the individual helpers when your adapter needs finer control.
+ */
+export * from './headlessTypes';
+export * from './getRoomReadiness';
+export * from './getMediaStreams';
+export * from './getCurrentParams';
+export * from './roomActions';
+export * from './participantState';
+export * from './mediaPermissions';
+export * from './moderation';
+export * from './sessionFeatures';
+export * from './sessionExtras';
+export * from './virtualBackground';
+export * from './sessionControls';
+export * from './playback';
+export * from './viewerSession';
+export * from './mediaProduction';

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

@@ -0,0 +1,124 @@
+import { HeadlessOptions, HeadlessParameters } from './headlessTypes';
+
+export interface MediaPermission {
+  /** True when turning this media ON would be accepted right now. */
+  allowed: boolean;
+  /** Empty when allowed; otherwise the reason, phrased for a user. */
+  reason: string;
+  /**
+   * True when enabling is possible but needs the host to approve first
+   * (`audioSetting`/`videoSetting` of 'approval'). The control still works —
+   * it raises a request rather than turning media on immediately.
+   */
+  needsApproval: boolean;
+}
+
+export interface MediaPermissions {
+  microphone: MediaPermission;
+  camera: MediaPermission;
+  screenShare: MediaPermission;
+  /** True when the local user is a host (islevel '2') and bypasses most gates. */
+  isHost: boolean;
+  /** True when focus mode is on and the local user is not a panelist. */
+  focusModeBlocked: boolean;
+}
+
+export type GetMediaPermissionsType = (
+  options: HeadlessOptions
+) => MediaPermissions;
+
+function isPanelist(parameters: HeadlessParameters): boolean {
+  const panelists = Array.isArray(parameters.panelists) ? parameters.panelists : [];
+  return panelists.some((entry: any) => entry?.name === parameters.member);
+}
+
+/**
+ * Can this user turn their mic, camera or screen share on *right now*?
+ *
+ * MediaSFU decides this inside `clickAudio` / `clickVideo` / `clickScreenShare`,
+ * which return `void` and report a refusal only through `showAlert`. That means
+ * a headless surface finds out a control was blocked *after* the user pressed
+ * it — the button looks broken. This evaluates the same gates up front so you
+ * can disable the control and say why instead.
+ *
+ * The branches mirror the SDK's own order: audio-only rooms, host recording
+ * locks, `adminRestrictSetting`, focus-mode panelist restrictions, and the
+ * `allow` / `approval` / `disallow` settings. Host (`islevel === '2'`) bypasses
+ * the participant-level gates, exactly as the controls do.
+ *
+ * Note this cannot predict two cases: room capacity checks, which the SDK
+ * resolves by asking the server (`checkProduce`), and OS-level device
+ * permission, which only surfaces when capture is attempted. Treat a `false`
+ * here as authoritative and a `true` as "nothing known blocks it".
+ *
+ * @example
+ * ```tsx
+ * const perms = getMediaPermissions({ parameters });
+ * <button disabled={!perms.microphone.allowed} title={perms.microphone.reason}>
+ *   {perms.microphone.needsApproval ? 'Ask to unmute' : 'Unmute'}
+ * </button>
+ * ```
+ */
+export function getMediaPermissions({ parameters }: HeadlessOptions): MediaPermissions {
+  const source: HeadlessParameters = parameters || {};
+  const isHost = String(source.islevel) === '2';
+  const recording = Boolean(source.recordStarted || source.recordResumed)
+    && !(source.recordPaused || source.recordStopped);
+  const focusModeBlocked = Boolean(source.panelistsFocused) && !isHost && !isPanelist(source);
+
+  const evaluate = (
+    kind: 'audio' | 'video' | 'screenshare'
+  ): MediaPermission => {
+    const allow = (): MediaPermission => ({ allowed: true, reason: '', needsApproval: false });
+    const deny = (reason: string): MediaPermission => ({ allowed: false, reason, needsApproval: false });
+
+    // An audio-only room refuses every visual producer outright.
+    if (source.audioOnlyRoom && kind !== 'audio') {
+      return deny('This is an audio-only event.');
+    }
+    // The host cannot drop media the recording depends on.
+    if (isHost && recording) {
+      if (kind === 'audio' && source.recordingMediaOptions === 'audio') {
+        return deny('Pause or stop the recording before changing your microphone.');
+      }
+      if (kind === 'video' && source.recordingMediaOptions === 'video') {
+        return deny('Pause or stop the recording before changing your camera.');
+      }
+    }
+    if (isHost) return allow();
+
+    if (source.adminRestrictSetting) {
+      return deny('Access denied by the host.');
+    }
+    if (focusModeBlocked && kind === 'audio' && source.muteOthersMic) {
+      return deny('Only panelists can unmute while focus mode is active.');
+    }
+    if (focusModeBlocked && kind === 'video' && source.muteOthersCamera) {
+      return deny('Only panelists can enable video while focus mode is active.');
+    }
+
+    const setting = kind === 'audio'
+      ? source.audioSetting
+      : kind === 'video'
+        ? source.videoSetting
+        : source.screenshareSetting;
+    if (setting === 'disallow') {
+      return deny('The host has disabled this for participants.');
+    }
+    if (setting === 'approval') {
+      // Not a refusal: the control raises a request to the host.
+      return { allowed: true, reason: 'The host must approve this.', needsApproval: true };
+    }
+    return allow();
+  };
+
+  return {
+    microphone: evaluate('audio'),
+    camera: evaluate('video'),
+    screenShare: evaluate('screenshare'),
+    isHost,
+    focusModeBlocked,
+  };
+}
+
+export default getMediaPermissions;