mediasfu-shared 1.0.6 → 1.1.0

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

@@ -0,0 +1,159 @@
+import { HeadlessOptions } from './headlessTypes';
+import { HeadlessActionResult } from './roomActions';
+export type RecordingStatus = 'unavailable' | 'idle' | 'recording' | 'paused' | 'stopped';
+export interface RecordingState {
+    status: RecordingStatus;
+    /** True while frames are being captured right now. */
+    active: boolean;
+    /** The local user may start/stop recording. */
+    canRecord: boolean;
+    /** 'video' | 'audio' — what the room is configured to capture. */
+    mediaOptions: string;
+    /** Seconds elapsed, as reported by the SDK. */
+    elapsedSeconds: number;
+}
+export type GetRecordingStateType = (options: HeadlessOptions) => RecordingState;
+/**
+ * Collapse MediaSFU's four recording booleans into one status.
+ *
+ * The SDK tracks `recordStarted`, `recordPaused`, `recordResumed` and
+ * `recordStopped` independently, and they overlap — after a pause/resume cycle
+ * `recordStarted` and `recordResumed` are both true. Deriving "is it recording?"
+ * from any single flag gives the wrong answer at least once per session.
+ *
+ * @example
+ * ```ts
+ * const recording = getRecordingState({ parameters });
+ * if (recording.status === 'paused') showResumeButton();
+ * ```
+ */
+export declare function getRecordingState({ parameters }: HeadlessOptions): RecordingState;
+export type RecordingActionType = (options: HeadlessOptions) => Promise<HeadlessActionResult>;
+/**
+ * Start recording.
+ *
+ * MediaSFU requires `confirmRecording` before `startRecording` — it validates
+ * the room's recording settings against the current layout and populates the
+ * state `startRecording` then reads. Calling `startRecording` alone appears to
+ * do nothing. This runs both steps in order.
+ *
+ * @example
+ * ```ts
+ * import { startRoomRecording } from 'mediasfu-shared';
+ *
+ * const result = await startRoomRecording({ parameters });
+ * if (!result.ok) setNotice(result.error);
+ * ```
+ */
+export declare function startRoomRecording({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+/** Pause an active recording. */
+export declare function pauseRoomRecording({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+/** Resume a paused recording. */
+export declare function resumeRoomRecording({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+/** Stop recording. The file becomes available through the MediaSFU API. */
+export declare function stopRoomRecording({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+export interface WhiteboardState {
+    /** True while a whiteboard session is running. */
+    active: boolean;
+    /** The local user may start one. */
+    canStart: boolean;
+    /** Participants granted drawing rights. */
+    users: any[];
+    /** Maximum participants the room's plan allows on a whiteboard. */
+    limit: number;
+    /** The live canvas element, when the SDK has created one. */
+    canvas: HTMLCanvasElement | null;
+}
+export type GetWhiteboardStateType = (options: HeadlessOptions) => WhiteboardState;
+/**
+ * Current whiteboard session state.
+ *
+ * `whiteboardStarted` alone is not enough — the SDK leaves it true after a
+ * session ends and sets `whiteboardEnded` alongside it, so "active" is
+ * `started && !ended`.
+ */
+export declare function getWhiteboardState({ parameters }: HeadlessOptions): WhiteboardState;
+export interface StartWhiteboardOptions extends HeadlessOptions {
+    /** Participants allowed to draw. Defaults to the room's current selection. */
+    users?: any[];
+}
+export type StartWhiteboardType = (options: StartWhiteboardOptions) => Promise<HeadlessActionResult>;
+/**
+ * Start (or reconfigure) the shared whiteboard.
+ *
+ * Emits `startWhiteboard` for a new session and `updateWhiteboard` when one is
+ * already running, matching the SDK's own modal. Breakout rooms and the
+ * whiteboard are mutually exclusive, which is checked here.
+ *
+ * This applies the session state only. Layout follow-up (`onScreenChanges`,
+ * `prepopulateUserMedia`, main-pane sizing) is deliberately left to you, since a
+ * headless surface owns its own layout.
+ *
+ * @example
+ * ```ts
+ * await startWhiteboard({ parameters, users: [{ name: 'Paul' }] });
+ * ```
+ */
+export declare function startWhiteboard({ parameters, users, }: StartWhiteboardOptions): Promise<HeadlessActionResult>;
+export type StopWhiteboardType = (options: HeadlessOptions) => Promise<HeadlessActionResult>;
+/** End the shared whiteboard session. */
+export declare function stopWhiteboard({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+export interface PollState {
+    /** Every poll the room has seen. */
+    polls: any[];
+    /** The poll currently open for voting, if any. */
+    active: any | null;
+}
+export type GetPollStateType = (options: HeadlessOptions) => PollState;
+/** Polls in the room, plus whichever one is currently open. */
+export declare function getPollState({ parameters }: HeadlessOptions): PollState;
+export interface CreatePollOptions extends HeadlessOptions {
+    question: string;
+    options: string[];
+    /** Defaults to 'custom'. */
+    type?: string;
+}
+export type CreateRoomPollType = (options: CreatePollOptions) => Promise<HeadlessActionResult>;
+/**
+ * Open a poll.
+ *
+ * @example
+ * ```ts
+ * await createRoomPoll({
+ *   parameters,
+ *   question: 'Ship on Friday?',
+ *   options: ['Yes', 'No'],
+ * });
+ * ```
+ */
+export declare function createRoomPoll({ parameters, question, options, type, }: CreatePollOptions): Promise<HeadlessActionResult>;
+export interface VotePollOptions extends HeadlessOptions {
+    pollId: string;
+    optionIndex: number;
+}
+/** Cast a vote in an open poll. */
+export declare function voteInRoomPoll({ parameters, pollId, optionIndex, }: VotePollOptions): Promise<HeadlessActionResult>;
+export interface EndPollOptions extends HeadlessOptions {
+    pollId: string;
+}
+/** Close a poll. Host only. */
+export declare function endRoomPoll({ parameters, pollId, }: EndPollOptions): Promise<HeadlessActionResult>;
+export interface BreakoutState {
+    /** True while breakout rooms are running. */
+    active: boolean;
+    /** The local user may start them. */
+    canStart: boolean;
+    /** Room composition as the SDK holds it. */
+    rooms: any[];
+    /** The breakout room the local user is in, or -1. */
+    currentRoom: number;
+}
+export type GetBreakoutStateType = (options: HeadlessOptions) => BreakoutState;
+/**
+ * Breakout-room state.
+ *
+ * Same `started && !ended` shape as the whiteboard, and the two are mutually
+ * exclusive — check this before offering a whiteboard control.
+ */
+export declare function getBreakoutState({ parameters }: HeadlessOptions): BreakoutState;
+//# sourceMappingURL=sessionFeatures.d.ts.map

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

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

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

@@ -0,0 +1,125 @@
+/**
+ * Viewers who are part of a session without joining the room.
+ *
+ * **Why this exists.** Joining a MediaSFU room auto-consumes WebRTC: the SDK
+ * creates consumers from the server's `newProducer` events, unconditionally —
+ * there is no receive-nothing mode. For a large passive audience watching over
+ * HLS that is pure waste: transports, consumers and layout churn for media they
+ * will never render. Joining and then pausing the consumers is worse than it
+ * looks, because the layout pass keeps resuming them.
+ *
+ * So an HLS viewer does not join at all. They hold a *viewer session* instead —
+ * enough to be counted, to raise a hand, and to be told when the host approves —
+ * and they only perform a real SDK join at the moment they reach the floor.
+ *
+ * How that session is stored is deliberately not decided here. The transport,
+ * lifecycle and state machine are the SDK's business; issuing playback URLs and
+ * tracking presence belong to whatever backend you run. You supply a
+ * `ViewerSessionProvider`; this drives it. Same reasoning as `hlsFactory`: the
+ * SDK owns the mechanism, the app owns the dependency.
+ */
+export type ViewerSessionPhase = 'idle' | 'joining' | 'watching' | 'requested' | 'approved' | 'left' | 'error';
+export interface ViewerSessionIdentity {
+    /** Opaque id for this viewer, issued by the provider. */
+    viewerId: string;
+    /** The room being watched. */
+    roomName: string;
+    /** Where to play from. Absent until the provider issues one. */
+    playbackUrl?: string;
+    /** 'hls' or 'whep'; inferred from the URL when omitted. */
+    protocol?: 'hls' | 'whep';
+    /** Anything the provider needs handed back on later calls. */
+    token?: string;
+    [key: string]: any;
+}
+export interface ViewerSessionStatus {
+    /** True once the host has approved this viewer for the floor. */
+    approved: boolean;
+    /** True while a request is outstanding. */
+    pending?: boolean;
+    /** Free-text reason when a request was refused. */
+    reason?: string;
+    /** Provider may refresh the playback URL (signed URLs expire). */
+    playbackUrl?: string;
+}
+/**
+ * What your backend has to do. Only `join` is required — a provider that just
+ * hands back a playback URL is a valid provider, it simply cannot support
+ * promotion.
+ */
+export interface ViewerSessionProvider {
+    join(options: {
+        roomName: string;
+        displayName?: string;
+        signal?: AbortSignal;
+    }): Promise<ViewerSessionIdentity>;
+    /** Keep the viewer counted as present. */
+    heartbeat?(options: {
+        session: ViewerSessionIdentity;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Raise a hand for the floor. */
+    requestPromotion?(options: {
+        session: ViewerSessionIdentity;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** Has the host decided yet? */
+    poll?(options: {
+        session: ViewerSessionIdentity;
+        signal?: AbortSignal;
+    }): Promise<ViewerSessionStatus>;
+    /** Release the session. */
+    leave?(options: {
+        session: ViewerSessionIdentity;
+    }): Promise<void>;
+}
+export interface ViewerSessionSnapshot {
+    phase: ViewerSessionPhase;
+    session: ViewerSessionIdentity | null;
+    status: ViewerSessionStatus | null;
+    error: string;
+    /** True when the provider can accept a promotion request at all. */
+    canRequestPromotion: boolean;
+}
+export interface CreateViewerSessionOptions {
+    provider: ViewerSessionProvider;
+    roomName: string;
+    displayName?: string;
+    /** Poll interval for approval, ms. Defaults to 5000. */
+    pollIntervalMs?: number;
+    /** Heartbeat interval, ms. Defaults to 30000. Ignored without a heartbeat. */
+    heartbeatIntervalMs?: number;
+    /** Called on every state change. */
+    onChange?: (snapshot: ViewerSessionSnapshot) => void;
+}
+export interface ViewerSessionHandle {
+    /** Current state, readable at any time. */
+    getSnapshot: () => ViewerSessionSnapshot;
+    /** Register with the provider and begin watching. */
+    start: () => Promise<ViewerSessionSnapshot>;
+    /** Raise a hand for the floor. */
+    requestPromotion: () => Promise<ViewerSessionSnapshot>;
+    /** Stop everything and release the session. */
+    stop: () => Promise<void>;
+}
+/**
+ * Drive a viewer session.
+ *
+ * Deliberately framework-agnostic — no hooks, no observables — so the same
+ * implementation serves React, Vue and Angular. Wrap it in whatever your
+ * framework prefers.
+ *
+ * @example
+ * ```ts
+ * const viewer = createViewerSession({
+ *   provider: myProvider,
+ *   roomName,
+ *   onChange: (snapshot) => setState(snapshot),
+ * });
+ * await viewer.start();                     // watching over HLS, never joined
+ * await viewer.requestPromotion();          // hand raised
+ * // when snapshot.phase === 'approved', perform a real SDK join.
+ * ```
+ */
+export declare function createViewerSession({ provider, roomName, displayName, pollIntervalMs, heartbeatIntervalMs, onChange, }: CreateViewerSessionOptions): ViewerSessionHandle;
+//# sourceMappingURL=viewerSession.d.ts.map

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

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

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

@@ -0,0 +1,72 @@
+import { HeadlessOptions } from './headlessTypes';
+import { HeadlessActionResult } from './roomActions';
+export interface ApplyVirtualBackgroundOptions extends HeadlessOptions {
+    /**
+     * Background image URL, or a ready `HTMLImageElement` / `HTMLCanvasElement`.
+     * Pass `null` to segment the person onto a transparent background.
+     */
+    image: string | HTMLImageElement | HTMLCanvasElement | null;
+    /** Capture frame rate for the processed stream. Defaults to 30. */
+    frameRate?: number;
+    /** MediaPipe model: 0 = general, 1 = landscape (faster). Defaults to 1. */
+    modelSelection?: 0 | 1;
+    /**
+     * Replace the live producer's track so remote viewers see the background
+     * immediately. Defaults to true; set false to preview locally first.
+     */
+    publish?: boolean;
+    /**
+     * Where to load the MediaPipe model and wasm from. Defaults to the jsDelivr
+     * CDN. Point this at a self-hosted copy of
+     * `node_modules/@mediapipe/selfie_segmentation` for offline or air-gapped
+     * deployments, or where a Content-Security-Policy forbids the CDN.
+     * A trailing slash is added if missing.
+     */
+    assetPath?: string;
+}
+export type ApplyVirtualBackgroundType = (options: ApplyVirtualBackgroundOptions) => Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+/**
+ * Apply a virtual background headlessly — no modal, no DOM of your own.
+ *
+ * The SDK's own background support lives inside `BackgroundModal`, whose apply
+ * path is bound to that component's refs (a preview `<video>` and a `<canvas>`)
+ * and is driven by `autoClickBackground` / `isBackgroundModalVisible`. A
+ * `returnUI={false}` surface therefore had no way to turn a background on
+ * 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
+ * canvas it creates and owns.
+ *
+ * It also keeps the SDK's own state honest (`virtualStream`, `processedStream`,
+ * `keepBackground`), so `getLocalVideoStream` keeps returning the right
+ * self-view without the caller choosing. Callers should not select the
+ * processed stream themselves.
+ *
+ * The camera must already be on: this processes `localStreamVideo`, it does not
+ * acquire one.
+ *
+ * @example
+ * ```ts
+ * await applyVirtualBackground({ parameters, image: '/backgrounds/office.jpg' });
+ * await clearVirtualBackground({ parameters });
+ * ```
+ */
+export declare function applyVirtualBackground({ parameters, image, frameRate, modelSelection, publish, assetPath, }: ApplyVirtualBackgroundOptions): Promise<HeadlessActionResult & {
+    stream: MediaStream | null;
+}>;
+export type ClearVirtualBackgroundType = (options: HeadlessOptions) => Promise<HeadlessActionResult>;
+/**
+ * Remove the virtual background and go back to the raw camera.
+ *
+ * Restores the original camera track on the live producer before tearing the
+ * pipeline down, so viewers transition straight from processed to raw rather
+ * than through a frozen or black frame.
+ */
+export declare function clearVirtualBackground({ parameters, }: HeadlessOptions): Promise<HeadlessActionResult>;
+/** True while a headless background pipeline is running in this tab. */
+export declare function isVirtualBackgroundRunning(): boolean;
+//# sourceMappingURL=virtualBackground.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"virtualBackground.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/virtualBackground.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAGlD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AA8BrD,MAAM,WAAW,6BAA8B,SAAQ,eAAe;IACpE;;;OAGG;IACH,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,IAAI,CAAC;IAC5D,mEAAmE;IACnE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,cAAc,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IACvB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,6BAA6B,KACnC,OAAO,CAAC,oBAAoB,GAAG;IAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,UAAU,EACV,KAAK,EACL,SAAc,EACd,cAAkB,EAClB,OAAc,EACd,SAAyB,GAC1B,EAAE,6BAA6B,GAAG,OAAO,CAAC,oBAAoB,GAAG;IAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC,CA2HhG;AAED,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,UAAU,GACX,EAAE,eAAe,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAuBjD;AAED,wEAAwE;AACxE,wBAAgB,0BAA0B,IAAI,OAAO,CAEpD"}