mediasfu-shared 1.0.6 → 1.2.0

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

@@ -0,0 +1,291 @@
+import { HeadlessOptions } from './headlessTypes';
+export interface RecordingNotice {
+    /** The SDK's current recording notice, or '' when there is none. */
+    message: string;
+    /** Formatted elapsed time as the SDK reports it (e.g. "00:12:04"). */
+    elapsed: string;
+    /** Elapsed seconds. */
+    elapsedSeconds: number;
+    /** True while pause/resume is permitted (the SDK enforces a cooldown). */
+    canPauseResume: boolean;
+    /** Pauses used so far. */
+    pausesUsed: number;
+    /** Pauses allowed for the active media type; 0 when unpublished. */
+    pauseLimit: number;
+    /** True when the pause allowance is exhausted. */
+    pauseLimitReached: boolean;
+}
+export type GetRecordingNoticeType = (options: HeadlessOptions) => RecordingNotice;
+/**
+ * The user-facing side of recording: the notice, the timer, and the pause
+ * allowance.
+ *
+ * Pause limits are per media type — `recordingAudioPausesLimit` vs
+ * `recordingVideoPausesLimit` — and the SDK picks by `recordingMediaOptions`.
+ * Reading the wrong one reports the wrong allowance, which is why this is a
+ * helper rather than a field read. Complements `getRecordingState`, which
+ * covers only the start/pause/resume/stop status.
+ */
+export declare function getRecordingNotice({ parameters }: HeadlessOptions): RecordingNotice;
+export interface RecordingCapabilities {
+    /** Recording audio at all. */
+    audio: boolean;
+    /** Recording video at all. */
+    video: boolean;
+    /** Recording every participant, not just the active speaker. */
+    allParticipants: boolean;
+    /** Recording every participant's video. */
+    videoParticipants: boolean;
+    /** Adding an HLS output. */
+    hls: boolean;
+    /** Max people included in an audio recording; 0 when unpublished. */
+    audioPeopleLimit: number;
+    /** Max people included in a video recording; 0 when unpublished. */
+    videoPeopleLimit: number;
+}
+export type GetRecordingCapabilitiesType = (options: HeadlessOptions) => RecordingCapabilities;
+/**
+ * What this room's plan actually permits recording.
+ *
+ * These are entitlement flags the server publishes per room, so a UI should
+ * gate on them rather than offering options the room will refuse.
+ */
+export declare function getRecordingCapabilities({ parameters, }: HeadlessOptions): RecordingCapabilities;
+export interface TranslationPreference {
+    /** Language applied to every speaker, or null when unset. */
+    globalLanguage: string | null;
+    /** Per-speaker overrides, keyed by speaker id. */
+    perSpeaker: {
+        speakerId: string;
+        language: string | null;
+        wantOriginal: boolean;
+    }[];
+}
+export interface TranslationState extends TranslationPreference {
+    /** True when any translation is currently being consumed. */
+    active: boolean;
+    /** Languages the room currently has translation producers for. */
+    availableLanguages: string[];
+}
+export type GetTranslationStateType = (options: HeadlessOptions) => TranslationState;
+/**
+ * What the listener is currently hearing, and what is on offer.
+ *
+ * `listenerTranslationPreferences.perSpeaker` is a `Map` on the bag, which does
+ * not survive serialisation or spread; this returns a plain array so it can be
+ * rendered and compared normally. Translation audio itself already reaches the
+ * user through `getAudioGridComponents`, which folds in `translationStreams`.
+ */
+export declare function getTranslationState({ parameters }: HeadlessOptions): TranslationState;
+export interface SetTranslationPreferenceOptions extends HeadlessOptions {
+    /** Language for every speaker. `null` restores the original audio. */
+    language?: string | null;
+    /** Limit the change to one speaker. */
+    speakerId?: string;
+    /** Explicitly prefer the untranslated audio for this speaker. */
+    wantOriginal?: boolean;
+}
+export type SetTranslationPreferenceType = (options: SetTranslationPreferenceOptions) => {
+    ok: boolean;
+    error: string;
+};
+/**
+ * Choose a translation language, globally or for one speaker.
+ *
+ * Delegates to the SDK's `updateListenerTranslationPreferences`, which is what
+ * syncs the choice to the server for routing and billing — setting the bag's
+ * fields directly would change local state without telling the server.
+ */
+export declare function setTranslationPreference({ parameters, language, speakerId, wantOriginal, }: SetTranslationPreferenceOptions): {
+    ok: boolean;
+    error: string;
+};
+export interface FocusModeState {
+    /** True while focus mode is active. */
+    active: boolean;
+    /** Participants permitted to speak/appear while focus mode is on. */
+    panelists: {
+        name: string;
+        [key: string]: any;
+    }[];
+    /** True when the local user is one of them. */
+    selfIsPanelist: boolean;
+    /** True when focus mode silences non-panelist microphones. */
+    mutesMicrophones: boolean;
+    /** True when focus mode blocks non-panelist cameras. */
+    mutesCameras: boolean;
+}
+export type GetFocusModeStateType = (options: HeadlessOptions) => FocusModeState;
+/**
+ * Focus-mode ("only panelists") state.
+ *
+ * The field is `muteOthersCamera`, not `muteOthersVideo` — worth stating,
+ * because the neighbouring flag is `muteOthersMic` and the asymmetry invites a
+ * wrong guess. {@link getMediaPermissions} already applies these rules to the
+ * local user; this exposes the room-level picture for a roster UI.
+ */
+export declare function getFocusModeState({ parameters }: HeadlessOptions): FocusModeState;
+export interface VirtualBackgroundState {
+    /** True when a processed (background-applied) stream is being published. */
+    active: boolean;
+    /** The processed stream, when one exists. */
+    stream: MediaStream | null;
+    /** The background currently applied, if the SDK reports one. */
+    appliedBackground: any;
+    /** The image the user selected, if any. */
+    selectedImage: string | null;
+}
+export type GetVirtualBackgroundStateType = (options: HeadlessOptions) => VirtualBackgroundState;
+/**
+ * Read-only virtual-background state.
+ *
+ * **You do not need this to render the right self-view.**
+ * `getLocalVideoStream` already returns the processed `virtualStream` whenever
+ * `keepBackground` is on, and the raw camera otherwise — the same rule the SDK's
+ * own grid uses. Rendering `localStreamVideo` directly is what shows a user
+ * their *unprocessed* background, so prefer the helper and ignore this.
+ *
+ * This exists for UI that needs to *describe* the state ("Background on"), not
+ * to choose a stream.
+ *
+ * Known gap: applying or clearing a background is still modal-driven in the SDK
+ * (`isBackgroundModalVisible` / `autoClickBackground`), so a `returnUI={false}`
+ * surface cannot currently turn a background on by itself. Reading works
+ * headlessly; controlling does not.
+ */
+export declare function getVirtualBackgroundState({ parameters, }: HeadlessOptions): VirtualBackgroundState;
+export interface SetParticipantPlaybackOptions extends HeadlessOptions {
+    /** Participant display name. */
+    name?: string;
+    /** Producer id, when you already hold one. */
+    producerId?: string;
+    /** Which of their tracks to affect. Defaults to both. */
+    kind?: 'audio' | 'video' | 'all';
+    /** True to stop receiving, false to resume. */
+    paused: boolean;
+}
+export type SetParticipantPlaybackType = (options: SetParticipantPlaybackOptions) => Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/**
+ * Stop or resume playing one participant's media **for you only**.
+ *
+ * This is a local, per-viewer control — "don't play this person to me right
+ * now". It pauses the mediasoup consumer, so the server stops sending that
+ * track to you: it saves bandwidth as well as silencing them, and it is
+ * invisible to everyone else. It is NOT moderation — the participant keeps
+ * publishing and other people keep receiving. Use `setParticipantMedia` from
+ * the moderation module to actually stop someone's media for the room.
+ *
+ * Note this is deliberately not `resumePauseStreams`, which the SDK drives from
+ * the active-speaker layout (`dispActiveNames`) and will happily undo a manual
+ * choice on its next pass. This targets the consumer directly.
+ *
+ * @example
+ * ```ts
+ * // Stop hearing and seeing Paul locally
+ * await setParticipantPlayback({ parameters, name: 'Paul', paused: true });
+ * // Just their audio
+ * await setParticipantPlayback({ parameters, name: 'Paul', kind: 'audio', paused: true });
+ * ```
+ */
+export declare function setParticipantPlayback({ parameters, name, producerId, kind, paused, }: SetParticipantPlaybackOptions): Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+export type BreakoutParticipantRef = {
+    name: string;
+    breakRoom: number;
+};
+export interface SetBreakoutRoomsOptions extends HeadlessOptions {
+    /** Room composition: index in the outer array is the room number. */
+    rooms: BreakoutParticipantRef[][];
+    /** What happens to people who join later. Defaults to the room's setting. */
+    newParticipantAction?: string;
+}
+export type SetBreakoutRoomsType = (options: SetBreakoutRoomsOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/**
+ * Publish a full breakout-room composition.
+ *
+ * The SDK models breakout rooms as an array of arrays — outer index is the room
+ * number, inner entries are `{ name, breakRoom }`. Adding, removing, or moving
+ * someone is therefore just editing that array and re-emitting it; there is no
+ * per-participant verb. `startBreakout` opens them, `updateBreakout` amends a
+ * running set, and the SDK picks by whether they are already started.
+ *
+ * Prefer {@link assignParticipantToBreakoutRoom} for single-person changes.
+ */
+export declare function setBreakoutRooms({ parameters, rooms, newParticipantAction, }: SetBreakoutRoomsOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export interface AssignParticipantToBreakoutRoomOptions extends HeadlessOptions {
+    /** Participant display name. */
+    name: string;
+    /** Destination room index, or `null` to remove them from breakout rooms. */
+    room: number | null;
+    newParticipantAction?: string;
+}
+export type AssignParticipantToBreakoutRoomType = (options: AssignParticipantToBreakoutRoomOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/**
+ * Add, move, or remove one participant, without rebuilding the whole array.
+ *
+ * Covers all three cases the composition array makes awkward by hand:
+ * `room: 1` adds them to room 1 (or moves them there from wherever they are),
+ * `room: null` removes them from breakout rooms entirely. Empty trailing rooms
+ * are preserved, because room numbers are positional and collapsing them would
+ * silently renumber everyone else.
+ *
+ * @example
+ * ```ts
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: 0 }); // add
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: 1 }); // move 0 -> 1
+ * await assignParticipantToBreakoutRoom({ parameters, name: 'Ada', room: null }); // remove
+ * ```
+ */
+export declare function assignParticipantToBreakoutRoom({ parameters, name, room, newParticipantAction, }: AssignParticipantToBreakoutRoomOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export type StopBreakoutRoomsType = (options: HeadlessOptions) => Promise<{
+    ok: boolean;
+    error: string;
+}>;
+/** Close every breakout room and return everyone to the main room. */
+export declare function stopBreakoutRooms({ parameters, }: HeadlessOptions): Promise<{
+    ok: boolean;
+    error: string;
+}>;
+export type ReapplyLocalPlaybackType = (options: HeadlessOptions) => Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/**
+ * Re-assert every local playback choice.
+ *
+ * Call this whenever media changes — `onMediaChanged` is the natural place. The
+ * SDK layout pass resumes consumers it believes should be visible, which would
+ * otherwise silently undo "do not play this person to me" the moment the active
+ * speaker changes. Without this the feature appears to work and then quietly
+ * stops working, which is worse than not having it.
+ *
+ * A no-op when nothing is locally paused.
+ */
+export declare function reapplyLocalPlayback({ parameters, }: HeadlessOptions): Promise<{
+    ok: boolean;
+    error: string;
+    affected: number;
+}>;
+/** Producer ids currently muted for this viewer only. */
+export declare function getLocallyPausedProducerIds(): string[];
+//# sourceMappingURL=sessionExtras.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"sessionExtras.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/sessionExtras.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AAMtE,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,uBAAuB;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,0EAA0E;IAC1E,cAAc,EAAE,OAAO,CAAC;IACxB,0BAA0B;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,eAAe,CAAC;AAEnF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,eAAe,CAgBnF;AAED,MAAM,WAAW,qBAAqB;IACpC,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,eAAe,EAAE,OAAO,CAAC;IACzB,2CAA2C;IAC3C,iBAAiB,EAAE,OAAO,CAAC;IAC3B,4BAA4B;IAC5B,GAAG,EAAE,OAAO,CAAC;IACb,qEAAqE;IACrE,gBAAgB,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,4BAA4B,GAAG,CACzC,OAAO,EAAE,eAAe,KACrB,qBAAqB,CAAC;AAE3B;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,UAAU,GACX,EAAE,eAAe,GAAG,qBAAqB,CAWzC;AAMD,MAAM,WAAW,qBAAqB;IACpC,6DAA6D;IAC7D,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kDAAkD;IAClD,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;CACrF;AAED,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,6DAA6D;IAC7D,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,kBAAkB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,gBAAgB,CAAC;AAErF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,gBAAgB,CA2BrF;AAED,MAAM,WAAW,+BAAgC,SAAQ,eAAe;IACtE,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,4BAA4B,GAAG,CACzC,OAAO,EAAE,+BAA+B,KACrC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpC;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,UAAU,EACV,QAAe,EACf,SAAS,EACT,YAAoB,GACrB,EAAE,+BAA+B,GAAG;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAqBlE;AAMD,MAAM,WAAW,cAAc;IAC7B,uCAAuC;IACvC,MAAM,EAAE,OAAO,CAAC;IAChB,qEAAqE;IACrE,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;KAAE,EAAE,CAAC;IAClD,+CAA+C;IAC/C,cAAc,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,wDAAwD;IACxD,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,cAAc,CAAC;AAEjF;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,cAAc,CAUjF;AAMD,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,MAAM,EAAE,OAAO,CAAC;IAChB,6CAA6C;IAC7C,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,gEAAgE;IAChE,iBAAiB,EAAE,GAAG,CAAC;IACvB,2CAA2C;IAC3C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,MAAM,6BAA6B,GAAG,CAC1C,OAAO,EAAE,eAAe,KACrB,sBAAsB,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,UAAU,GACX,EAAE,eAAe,GAAG,sBAAsB,CAS1C;AAMD,MAAM,WAAW,6BAA8B,SAAQ,eAAe;IACpE,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;IACjC,+CAA+C;IAC/C,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,MAAM,0BAA0B,GAAG,CACvC,OAAO,EAAE,6BAA6B,KACnC,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAW/D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,UAAU,EACV,IAAS,EACT,UAAe,EACf,IAAY,EACZ,MAAM,GACP,EAAE,6BAA6B,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C3F;AAMD,MAAM,MAAM,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzE,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,qEAAqE;IACrE,KAAK,EAAE,sBAAsB,EAAE,EAAE,CAAC;IAClC,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,uBAAuB,KAC7B,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7C;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,UAAU,EACV,KAAK,EACL,oBAAoB,GACrB,EAAE,uBAAuB,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsCnE;AAED,MAAM,WAAW,sCAAuC,SAAQ,eAAe;IAC7E,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,mCAAmC,GAAG,CAChD,OAAO,EAAE,sCAAsC,KAC5C,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7C;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,+BAA+B,CAAC,EACpD,UAAU,EACV,IAAI,EACJ,IAAI,EACJ,oBAAoB,GACrB,EAAE,sCAAsC,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAkBlF;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE7C,sEAAsE;AACtE,wBAAsB,iBAAiB,CAAC,EACtC,UAAU,GACX,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB3D;AAED,MAAM,MAAM,wBAAwB,GAAG,CACrC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/D;;;;;;;;;;GAUG;AACH,wBAAsB,oBAAoB,CAAC,EACzC,UAAU,GACX,EAAE,eAAe,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAqB7E;AAED,yDAAyD;AACzD,wBAAgB,2BAA2B,IAAI,MAAM,EAAE,CAEtD"}

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":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN,SAAS,GACT,UAAU,GACV,WAAW,GACX,UAAU,GACV,MAAM,GACN,OAAO,CAAC;AAEZ,MAAM,WAAW,qBAAqB;IACpC,yDAAyD;IACzD,QAAQ,EAAE,MAAM,CAAC;IACjB,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,QAAQ,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,mDAAmD;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,CAAC,OAAO,EAAE;QACZ,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACnC,0CAA0C;IAC1C,SAAS,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,qBAAqB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7F,kCAAkC;IAClC,gBAAgB,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,qBAAqB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpG,gCAAgC;IAChC,IAAI,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,qBAAqB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvG,2BAA2B;IAC3B,KAAK,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,qBAAqB,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,kBAAkB,CAAC;IAC1B,OAAO,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACtC,MAAM,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,mBAAmB,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,qBAAqB,KAAK,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,mBAAmB;IAClC,2CAA2C;IAC3C,WAAW,EAAE,MAAM,qBAAqB,CAAC;IACzC,qDAAqD;IACrD,KAAK,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC5C,kCAAkC;IAClC,gBAAgB,EAAE,MAAM,OAAO,CAAC,qBAAqB,CAAC,CAAC;IACvD,+CAA+C;IAC/C,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAID;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,QAAQ,EACR,QAAQ,EACR,WAAW,EACX,cAAqB,EACrB,mBAA2B,EAC3B,QAAQ,GACT,EAAE,0BAA0B,GAAG,mBAAmB,CA6GlD"}

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, 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`,
+ * `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