mediasfu-shared 1.0.6 → 1.2.0

package/dist/methods/utils/headless/getMediaStreams.d.ts

@@ -0,0 +1,96 @@
+import { HeadlessOptions, ResolvedMedia } from './headlessTypes';
+export type GetRemoteVideoStreamsType = (options: HeadlessOptions) => ResolvedMedia[];
+/**
+ * Every remote camera in the room, in render order.
+ *
+ * Two details make this hard to get right by hand, and both are why headless
+ * integrations lose the host's video:
+ *
+ *  - **`oldAllStreams` matters.** During normal conference layout processing the
+ *    SDK moves a stream out of `allVideoStreams` into `oldAllStreams`. Reading
+ *    only `allVideoStreams` makes the host disappear mid-call.
+ *  - **The self marker must go.** `allVideoStreams` is seeded with a
+ *    `producerId: 'youyou'` placeholder for the local user.
+ *
+ * Entries are de-duplicated by `producerId`, falling back to the stream id, so a
+ * stream present in both collections is returned once.
+ *
+ * @example
+ * ```ts
+ * import { getRemoteVideoStreams } from 'mediasfu-shared';
+ *
+ * const remotes = getRemoteVideoStreams({ parameters });
+ * const primary = remotes[0]?.stream ?? null;
+ * ```
+ */
+export declare function getRemoteVideoStreams({ parameters, }: HeadlessOptions): ResolvedMedia[];
+export type GetRemoteAudioStreamsType = (options: HeadlessOptions) => ResolvedMedia[];
+/**
+ * Every remote audio producer in the room.
+ *
+ * Note that for *hearing* participants you normally want
+ * {@link getAudioGridComponents} instead — MediaSFU prepares its own audio
+ * elements and mounting those is what actually plays sound. This helper is for
+ * cases where you need the raw `MediaStream` (recording, analysis, metering).
+ */
+export declare function getRemoteAudioStreams({ parameters, }: HeadlessOptions): ResolvedMedia[];
+export type GetLocalVideoStreamType = (options: HeadlessOptions) => MediaStream | null;
+/**
+ * The local camera stream to render as the self-view.
+ *
+ * The virtual-background case is the one everyone misses: when `keepBackground`
+ * is on, the stream that carries the processed frames is `virtualStream`, and
+ * `localStreamVideo` still holds the raw camera. Rendering the wrong one shows
+ * the user their unprocessed background. This mirrors the SDK's own grid rule.
+ *
+ * Returns `null` when the camera is off, so a falsy result is a truthful
+ * "no self-view" rather than something to paint black.
+ *
+ * Note: transport state such as `videoParams` or `videoProducer` is **not**
+ * renderable media and is deliberately never consulted here.
+ */
+export declare function getLocalVideoStream({ parameters, }: HeadlessOptions): MediaStream | null;
+export type GetLocalAudioStreamType = (options: HeadlessOptions) => MediaStream | null;
+/** The local microphone stream, or `null` when the mic is off. */
+export declare function getLocalAudioStream({ parameters, }: HeadlessOptions): MediaStream | null;
+export interface ScreenShareState {
+    /** The stream to render, local or remote, or `null` when nobody is sharing. */
+    stream: MediaStream | null;
+    /** True when the stream is this user's own screen. */
+    isLocal: boolean;
+    /** True when any screen share is active in the room. */
+    active: boolean;
+}
+export type GetScreenShareStreamType = (options: HeadlessOptions) => ScreenShareState;
+/**
+ * The active screen share, remote first.
+ *
+ * `remoteScreenStream` is an array in some SDK paths and a bare object in
+ * others; both shapes are handled here so callers do not have to guess.
+ *
+ * @example
+ * ```ts
+ * const share = getScreenShareStream({ parameters });
+ * const primary = share.stream ?? remotes[0]?.stream ?? localVideo;
+ * ```
+ */
+export declare function getScreenShareStream({ parameters, }: HeadlessOptions): ScreenShareState;
+export type GetAudioGridComponentsType = (options: HeadlessOptions) => any[];
+/**
+ * The prepared audio elements to mount so participants are actually audible.
+ *
+ * Mount **all** of them. Truncating this list to the participants you happen to
+ * draw on screen silently mutes everyone else — audio playback is decoupled from
+ * your video layout. The usual pattern is a visually hidden container:
+ *
+ * @example
+ * ```tsx
+ * import { getAudioGridComponents } from 'mediasfu-shared';
+ *
+ * <div style={{ position: 'absolute', width: 1, height: 1, opacity: 0 }}>
+ *   <AudioGrid componentsToRender={getAudioGridComponents({ parameters })} />
+ * </div>
+ * ```
+ */
+export declare function getAudioGridComponents({ parameters }: HeadlessOptions): any[];
+//# sourceMappingURL=getMediaStreams.d.ts.map

package/dist/methods/utils/headless/getMediaStreams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getMediaStreams.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/getMediaStreams.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAsB,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAyErF,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,eAAe,KACrB,aAAa,EAAE,CAAC;AAErB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,GACX,EAAE,eAAe,GAAG,aAAa,EAAE,CAMnC;AAED,MAAM,MAAM,yBAAyB,GAAG,CACtC,OAAO,EAAE,eAAe,KACrB,aAAa,EAAE,CAAC;AAErB;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,EACpC,UAAU,GACX,EAAE,eAAe,GAAG,aAAa,EAAE,CAGnC;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,eAAe,KACrB,WAAW,GAAG,IAAI,CAAC;AAExB;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,UAAU,GACX,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,CAUtC;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,eAAe,KACrB,WAAW,GAAG,IAAI,CAAC;AAExB,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,EAClC,UAAU,GACX,EAAE,eAAe,GAAG,WAAW,GAAG,IAAI,CAMtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,+EAA+E;IAC/E,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;IACjB,wDAAwD;IACxD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,eAAe,KACrB,gBAAgB,CAAC;AAEtB;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,EACnC,UAAU,GACX,EAAE,eAAe,GAAG,gBAAgB,CAyBpC;AAED,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,GAAG,EAAE,CAAC;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,GAAG,EAAE,CAM7E"}

package/dist/methods/utils/headless/getRoomReadiness.d.ts

@@ -0,0 +1,25 @@
+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 declare function getRoomReadiness({ parameters }: HeadlessOptions): RoomReadiness;
+export default getRoomReadiness;
+//# sourceMappingURL=getRoomReadiness.d.ts.map

package/dist/methods/utils/headless/getRoomReadiness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getRoomReadiness.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/getRoomReadiness.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEjE,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,aAAa,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,aAAa,CAsB/E;AAED,eAAe,gBAAgB,CAAC"}

package/dist/methods/utils/headless/headlessTypes.d.ts

@@ -0,0 +1,89 @@
+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 {
+    roomName?: string;
+    member?: string;
+    islevel?: string;
+    validated?: boolean;
+    socket?: any;
+    localSocket?: any;
+    device?: {
+        loaded?: boolean;
+        [key: string]: any;
+    };
+    participants?: Participant[];
+    participantsAll?: Participant[];
+    allVideoStreams?: (Participant | Stream)[];
+    allAudioStreams?: (Participant | Stream)[];
+    oldAllStreams?: (Participant | Stream)[];
+    audioOnlyStreams?: any[];
+    translationStreams?: any[];
+    localStream?: MediaStream | null;
+    localStreamVideo?: MediaStream | null;
+    localStreamAudio?: MediaStream | null;
+    localStreamScreen?: MediaStream | null;
+    virtualStream?: MediaStream | null;
+    keepBackground?: boolean;
+    audioAlreadyOn?: boolean;
+    videoAlreadyOn?: boolean;
+    remoteScreenStream?: (Participant | Stream)[] | {
+        stream?: MediaStream;
+    } | null;
+    shareScreenStarted?: boolean;
+    shared?: boolean;
+    messages?: any[];
+    coHost?: string;
+    coHostResponsibility?: any[];
+    chatSetting?: string;
+    showAlert?: (options: any) => void;
+    audioLevel?: number;
+    audioDecibels?: {
+        name: string;
+        averageLoudness: number;
+    }[];
+    /** 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;
+}
+//# sourceMappingURL=headlessTypes.d.ts.map

package/dist/methods/utils/headless/headlessTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headlessTypes.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/headlessTypes.ts"],"names":[],"mappings":"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"}

package/dist/methods/utils/headless/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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';
+//# sourceMappingURL=index.d.ts.map

package/dist/methods/utils/headless/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC"}

package/dist/methods/utils/headless/mediaPermissions.d.ts

@@ -0,0 +1,53 @@
+import { HeadlessOptions } 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;
+/**
+ * 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 declare function getMediaPermissions({ parameters }: HeadlessOptions): MediaPermissions;
+export default getMediaPermissions;
+//# sourceMappingURL=mediaPermissions.d.ts.map

package/dist/methods/utils/headless/mediaPermissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaPermissions.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/mediaPermissions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AAEtE,MAAM,WAAW,eAAe;IAC9B,mEAAmE;IACnE,OAAO,EAAE,OAAO,CAAC;IACjB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,eAAe,CAAC;IACxB,WAAW,EAAE,eAAe,CAAC;IAC7B,gFAAgF;IAChF,MAAM,EAAE,OAAO,CAAC;IAChB,uEAAuE;IACvE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,eAAe,KACrB,gBAAgB,CAAC;AAOtB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,gBAAgB,CA4DrF;AAED,eAAe,mBAAmB,CAAC"}

package/dist/methods/utils/headless/mediaProduction.d.ts

@@ -0,0 +1,177 @@
+import { HeadlessOptions } from './headlessTypes';
+import { HeadlessActionResult } from './roomActions';
+export type ProducerKind = 'video' | 'audio' | 'screen';
+export interface CaptureLimits {
+    width: number;
+    height: number;
+    frameRate: number;
+}
+export interface GetCaptureLimitsOptions extends HeadlessOptions {
+    /** Camera and screen share have separate ceilings. Defaults to camera. */
+    kind?: ProducerKind;
+}
+export type GetCaptureLimitsType = (options: GetCaptureLimitsOptions) => CaptureLimits;
+/**
+ * The room's allowed capture ceiling — the same `vidCons` / `frameRate` that
+ * `clickVideo` feeds to `getUserMedia`. Zero means "no ceiling published".
+ */
+export declare function getCaptureLimits({ parameters, kind }: GetCaptureLimitsOptions): CaptureLimits;
+export interface ProduceMediaOptions extends HeadlessOptions {
+    /** The stream to publish. Must carry at least one live track of the right kind. */
+    stream: MediaStream;
+    /** What to publish it as. */
+    kind: ProducerKind;
+    /**
+     * Publish even when the source exceeds the room's `vidCons`/`frameRate`
+     * ceiling and cannot be clamped. Off by default: the ceiling is a room
+     * entitlement, so bypassing it must be a deliberate, visible choice.
+     */
+    allowUnconstrained?: boolean;
+}
+export type ProduceMediaType = (options: ProduceMediaOptions) => Promise<HeadlessActionResult>;
+/**
+ * Publish **any** MediaStream to the room — not just the camera or microphone.
+ *
+ * `clickVideo` / `clickAudio` call `getUserMedia` internally, so they can only
+ * ever publish a real device. Anything else — a `<canvas>` capture, a `<video>`
+ * element playing a file, a Web Audio destination, a processed or synthesised
+ * track, a virtual camera — previously required monkey-patching
+ * `navigator.mediaDevices.getUserMedia` around the call, which is racy and
+ * leaks if the control throws. This publishes your stream directly.
+ *
+ * The stream stays yours: stop its tracks when you are done, or call
+ * {@link stopProducing} to tear the producer down first.
+ *
+ * @example Publish a canvas as your camera
+ * ```ts
+ * import { produceMedia } from 'mediasfu-shared';
+ *
+ * const canvas = document.querySelector('canvas')!;
+ * const stream = canvas.captureStream(30);
+ * await produceMedia({ parameters, stream, kind: 'video' });
+ * ```
+ *
+ * @example Publish a video file's audio and video
+ * ```ts
+ * const el = document.querySelector('video')!;
+ * const stream = (el as any).captureStream();
+ * await produceMedia({ parameters, stream, kind: 'video' });
+ * await produceMedia({ parameters, stream, kind: 'audio' });
+ * ```
+ */
+export declare function produceMedia({ parameters, stream, kind, allowUnconstrained, }: ProduceMediaOptions): Promise<HeadlessActionResult>;
+export interface StopProducingOptions extends HeadlessOptions {
+    kind: ProducerKind;
+}
+export type StopProducingType = (options: StopProducingOptions) => Promise<HeadlessActionResult>;
+/**
+ * Tear down one of your producers without touching the others.
+ *
+ * `clickVideo`/`clickAudio` toggle capture *and* transport together. When you
+ * published a custom stream you usually want to stop only the transport and
+ * keep owning the stream (to swap sources without a visible gap, for example).
+ *
+ * @example Swap the published camera for a canvas without dropping the call
+ * ```ts
+ * await stopProducing({ parameters, kind: 'video' });
+ * await produceMedia({ parameters, stream: canvasStream, kind: 'video' });
+ * ```
+ */
+export declare function stopProducing({ parameters, kind, }: StopProducingOptions): Promise<HeadlessActionResult>;
+export interface ProduceCanvasOptions extends HeadlessOptions {
+    canvas: HTMLCanvasElement;
+    /** Capture frame rate. Defaults to 30. */
+    frameRate?: number;
+    /** Publish as the camera (default) or as a screen share. */
+    as?: 'video' | 'screen';
+}
+export type ProduceCanvasType = (options: ProduceCanvasOptions) => Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+/**
+ * Publish a `<canvas>` as video — slides, a whiteboard, a game, a generated
+ * overlay, a test pattern.
+ *
+ * Returns the captured stream so you can stop its tracks when finished.
+ *
+ * @example
+ * ```ts
+ * const { ok, stream } = await produceCanvas({ parameters, canvas, frameRate: 15 });
+ * // later
+ * stream?.getTracks().forEach((track) => track.stop());
+ * ```
+ */
+export declare function produceCanvas({ parameters, canvas, frameRate, as, }: ProduceCanvasOptions): Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+export interface ProduceElementOptions extends HeadlessOptions {
+    /** A playing `<video>` or `<audio>` element. */
+    element: HTMLMediaElement;
+    /** Publish the video track. Defaults to true for `<video>`. */
+    withVideo?: boolean;
+    /** Publish the audio track. Defaults to true. */
+    withAudio?: boolean;
+}
+export type ProduceElementType = (options: ProduceElementOptions) => Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+/**
+ * Publish a playing `<video>` or `<audio>` element — media co-watching, a
+ * pre-recorded intro, background music, an HLS or MP4 source.
+ *
+ * The element must actually be playing: a paused element captures no frames, and
+ * browsers block autoplay with audio until the user has interacted with the page.
+ *
+ * @example
+ * ```ts
+ * const el = document.querySelector('video')!;
+ * await el.play();
+ * await produceElement({ parameters, element: el });
+ * ```
+ */
+export declare function produceElement({ parameters, element, withVideo, withAudio, }: ProduceElementOptions): Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+export interface ProduceDisplayOptions extends HeadlessOptions {
+    /** Passed to `getDisplayMedia`. Defaults to `{ video: true }`. */
+    constraints?: DisplayMediaStreamOptions;
+    /** Also publish the captured system/tab audio when the user shares it. */
+    withAudio?: boolean;
+}
+export type ProduceDisplayType = (options: ProduceDisplayOptions) => Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+/**
+ * Start a screen share from a headless surface.
+ *
+ * `getDisplayMedia` must be called from a user gesture, so invoke this directly
+ * in a click handler — not after an `await`.
+ *
+ * @example
+ * ```tsx
+ * <button onClick={() => produceDisplay({ parameters })}>Share screen</button>
+ * ```
+ */
+export declare function produceDisplay({ parameters, constraints, withAudio, }: ProduceDisplayOptions): Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+export interface ReplaceProducerTrackOptions extends HeadlessOptions {
+    /** The replacement track. Its kind decides which producer is swapped. */
+    track: MediaStreamTrack;
+}
+export type ReplaceProducerTrackType = (options: ReplaceProducerTrackOptions) => Promise<HeadlessActionResult>;
+/**
+ * Swap the track on a live producer without renegotiating.
+ *
+ * This is the seamless path for switching camera, applying or removing a
+ * background effect, or moving between media sources: remote participants see
+ * no interruption, because the producer and its transport stay up.
+ *
+ * @example
+ * ```ts
+ * const processed = applyBackgroundBlur(cameraTrack);
+ * await replaceProducerTrack({ parameters, track: processed });
+ * ```
+ */
+export declare function replaceProducerTrack({ parameters, track, }: ReplaceProducerTrackOptions): Promise<HeadlessActionResult>;
+//# sourceMappingURL=mediaProduction.d.ts.map

package/dist/methods/utils/headless/mediaProduction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mediaProduction.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/mediaProduction.ts"],"names":[],"mappings":"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"}

package/dist/methods/utils/headless/moderation.d.ts

@@ -0,0 +1,157 @@
+import { HeadlessOptions } from './headlessTypes';
+import { HeadlessActionResult } from './roomActions';
+/** The co-host responsibility keys MediaSFU recognises. */
+export type ModerationArea = 'media' | 'participants' | 'chat' | 'waiting';
+export interface ModerationPermissions {
+    /** True when the local user is the host (islevel '2'). */
+    isHost: boolean;
+    /** True when the local user is the room's co-host. */
+    isCoHost: boolean;
+    /** Turn other participants' camera/mic/screen off. */
+    canControlMedia: boolean;
+    /** Remove or ban participants. */
+    canManageParticipants: boolean;
+    /** Moderate chat. */
+    canManageChat: boolean;
+    /** Admit or deny people in the waiting room. */
+    canManageWaitingRoom: boolean;
+}
+export type GetModerationPermissionsType = (options: HeadlessOptions) => ModerationPermissions;
+/**
+ * What the local user is allowed to moderate.
+ *
+ * MediaSFU's rule is `islevel === '2' || (coHost === member && <area>.value)`,
+ * and it is enforced *inside* each action — an unauthorised call is swallowed
+ * with an alert rather than returning an error. That makes it very easy to ship
+ * a moderation button that silently does nothing for co-hosts. Gate your UI on
+ * this instead.
+ *
+ * @example
+ * ```ts
+ * import { getModerationPermissions } from 'mediasfu-shared';
+ *
+ * const perms = getModerationPermissions({ parameters });
+ * <button disabled={!perms.canControlMedia}>Mute everyone</button>
+ * ```
+ */
+export declare function getModerationPermissions({ parameters, }: HeadlessOptions): ModerationPermissions;
+export interface SetParticipantMediaOptions extends HeadlessOptions {
+    /** Participant display name. */
+    name?: string;
+    /** Participant id. Takes precedence over `name`. */
+    id?: string;
+    /** Which media to switch off. */
+    kind: 'audio' | 'video' | 'screenshare' | 'all';
+}
+export type SetParticipantMediaType = (options: SetParticipantMediaOptions) => Promise<HeadlessActionResult>;
+/**
+ * Turn a participant's media off as host or authorised co-host.
+ *
+ * This is one-directional by design: MediaSFU lets a moderator *stop* someone's
+ * camera, microphone or screen share, but cannot start it on their behalf — the
+ * participant must re-enable it themselves.
+ *
+ * The SDK's own `controlMedia` consumer only emits for `type: 'audio'` and
+ * `type: 'video'`; `'all'` and `'screenshare'` fall through its guard and do
+ * nothing. This helper emits the `controlMedia` event directly with the same
+ * permission and self-protection checks applied uniformly, so every kind works.
+ * Hosts (`islevel === '2'`) cannot be muted by anyone, including other hosts.
+ *
+ * @example
+ * ```ts
+ * import { setParticipantMedia } from 'mediasfu-shared';
+ *
+ * await setParticipantMedia({ parameters, name: 'Paul', kind: 'video' });
+ * await setParticipantMedia({ parameters, name: 'Paul', kind: 'all' });
+ * ```
+ */
+export declare function setParticipantMedia({ parameters, name, id, kind, }: SetParticipantMediaOptions): Promise<HeadlessActionResult>;
+export interface ModerateParticipantOptions extends HeadlessOptions {
+    name?: string;
+    id?: string;
+}
+/** Mute a participant's microphone. See {@link setParticipantMedia}. */
+export declare function muteParticipant(options: ModerateParticipantOptions): Promise<HeadlessActionResult>;
+/** Turn a participant's camera off. See {@link setParticipantMedia}. */
+export declare function disableParticipantVideo(options: ModerateParticipantOptions): Promise<HeadlessActionResult>;
+/** Stop a participant's screen share. See {@link setParticipantMedia}. */
+export declare function stopParticipantScreenShare(options: ModerateParticipantOptions): Promise<HeadlessActionResult>;
+export interface MuteEveryoneOptions extends HeadlessOptions {
+    /** Which media to switch off for everyone. Defaults to `audio`. */
+    kind?: 'audio' | 'video' | 'screenshare' | 'all';
+}
+export type MuteEveryoneType = (options: MuteEveryoneOptions) => Promise<HeadlessActionResult>;
+/**
+ * Turn media off for every non-host participant.
+ *
+ * MediaSFU has no bulk primitive, so this fans out per participant. Hosts and
+ * the local user are skipped. Succeeds if at least one participant was
+ * actioned; reports the failure otherwise.
+ */
+export declare function muteEveryone({ parameters, kind, }: MuteEveryoneOptions): Promise<HeadlessActionResult>;
+export type RemoveParticipantType = (options: ModerateParticipantOptions) => Promise<HeadlessActionResult>;
+/**
+ * Remove a participant from the room.
+ *
+ * @example
+ * ```ts
+ * await removeParticipant({ parameters, name: 'Paul' });
+ * ```
+ */
+export declare function removeParticipant({ parameters, name, id, }: ModerateParticipantOptions): Promise<HeadlessActionResult>;
+export interface RespondToWaitingParticipantOptions extends HeadlessOptions {
+    name?: string;
+    id?: string;
+    /** True to admit, false to deny. */
+    admit: boolean;
+}
+export type RespondToWaitingParticipantType = (options: RespondToWaitingParticipantOptions) => Promise<HeadlessActionResult>;
+/**
+ * Admit or deny somebody waiting to join.
+ *
+ * Reads `waitingRoomList` off the bag, so you only supply the person's name or
+ * id and whether to let them in.
+ *
+ * @example
+ * ```ts
+ * for (const person of parameters.waitingRoomList ?? []) {
+ *   await respondToWaitingParticipant({ parameters, id: person.id, admit: true });
+ * }
+ * ```
+ */
+export declare function respondToWaitingParticipant({ parameters, name, id, admit, }: RespondToWaitingParticipantOptions): Promise<HeadlessActionResult>;
+export interface RespondToParticipantRequestOptions extends HeadlessOptions {
+    /** The request id from `parameters.requestList`. */
+    requestId?: string;
+    /** Or match by requester name. */
+    name?: string;
+    /** True to approve, false to reject. */
+    approve: boolean;
+}
+export type RespondToParticipantRequestType = (options: RespondToParticipantRequestOptions) => Promise<HeadlessActionResult>;
+/**
+ * Approve or reject a participant request (raise hand, ask to share, ask to
+ * speak). Requests live on `parameters.requestList`; each carries an `icon`
+ * naming the capability being asked for.
+ */
+export declare function respondToParticipantRequest({ parameters, requestId, name, approve, }: RespondToParticipantRequestOptions): Promise<HeadlessActionResult>;
+export interface SetCoHostOptions extends HeadlessOptions {
+    /** Participant to promote. Pass '' to clear the current co-host. */
+    name: string;
+    /** Areas the co-host may moderate. Defaults to media + participants. */
+    areas?: ModerationArea[];
+}
+export type SetCoHostType = (options: SetCoHostOptions) => Promise<HeadlessActionResult>;
+/**
+ * Promote a participant to co-host and choose what they may moderate.
+ *
+ * Only the host may do this. Areas not listed are explicitly disabled, so this
+ * sets the complete responsibility set rather than merging with the previous one.
+ *
+ * @example
+ * ```ts
+ * await setCoHost({ parameters, name: 'Paul', areas: ['media', 'waiting'] });
+ * ```
+ */
+export declare function setCoHost({ parameters, name, areas, }: SetCoHostOptions): Promise<HeadlessActionResult>;
+//# sourceMappingURL=moderation.d.ts.map