mediasfu-shared 1.0.6 → 1.1.0

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

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

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

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

@@ -0,0 +1,128 @@
+import { Participant } from '../../../types/types';
+import { HeadlessOptions } from './headlessTypes';
+export interface ParticipantMediaState {
+    participant: Participant | null;
+    /** The participant's own display name, or '' when unresolved. */
+    name: string;
+    /** True when this row is the local user. */
+    isSelf: boolean;
+    /** True when the participant is a host (islevel '2'). */
+    isHost: boolean;
+    /** True when the participant is publishing a camera. */
+    hasVideo: boolean;
+    /** True when the participant is publishing a microphone. */
+    hasAudio: boolean;
+    /** True when the participant's microphone is muted. */
+    muted: boolean;
+    /** The camera producer id, or '' when not publishing. */
+    videoProducerId: string;
+    /** The microphone producer id, or '' when not publishing. */
+    audioProducerId: string;
+}
+export interface GetParticipantMediaStateOptions extends HeadlessOptions {
+    /** Match by display name. */
+    name?: string;
+    /** Match by participant id. Takes precedence over `name`. */
+    id?: string;
+}
+export type GetParticipantMediaStateType = (options: GetParticipantMediaStateOptions) => ParticipantMediaState;
+/**
+ * Whether a participant is publishing, and what to label them.
+ *
+ * "Is this person on camera?" is not `participant.muted` and not the presence of
+ * a stream in your grid — it is whether `videoID` holds a real producer
+ * reference. MediaSFU writes the string `'none'` rather than an empty value when
+ * there is no producer, which is why a naive truthiness check reports everyone
+ * as publishing.
+ *
+ * @example
+ * ```ts
+ * import { getParticipantMediaState } from 'mediasfu-shared';
+ *
+ * const paul = getParticipantMediaState({ parameters, name: 'Paul' });
+ * if (paul.hasVideo) renderCamera(paul.videoProducerId);
+ * ```
+ */
+export declare function getParticipantMediaState({ parameters, name, id, }: GetParticipantMediaStateOptions): ParticipantMediaState;
+export type ListParticipantMediaStatesType = (options: HeadlessOptions) => ParticipantMediaState[];
+/** {@link getParticipantMediaState} for everyone currently in the room. */
+export declare function listParticipantMediaStates({ parameters, }: HeadlessOptions): ParticipantMediaState[];
+export interface ActiveSpeaker {
+    /** Loudest participant's display name, or '' when the room is quiet. */
+    name: string;
+    /** That participant's average loudness. */
+    level: number;
+    participant: Participant | null;
+}
+export type GetActiveSpeakerType = (options: HeadlessOptions) => ActiveSpeaker;
+/**
+ * The loudest participant right now.
+ *
+ * Reads `audioDecibels`, which the SDK maintains per participant. MediaSFU's own
+ * grids treat roughly 127.5 as the noise floor, so quieter rooms report no
+ * active speaker rather than flickering between people.
+ *
+ * @example
+ * ```ts
+ * const speaker = getActiveSpeaker({ parameters });
+ * if (speaker.name) highlight(speaker.name);
+ * ```
+ */
+export declare function getActiveSpeaker({ parameters }: HeadlessOptions): ActiveSpeaker;
+export interface MediaDeviceList {
+    cameras: MediaDeviceInfo[];
+    microphones: MediaDeviceInfo[];
+}
+export type ListMediaDevicesType = (options: HeadlessOptions) => Promise<MediaDeviceList>;
+/**
+ * Cameras and microphones available for a device picker.
+ *
+ * Uses the SDK's own `getMediaDevicesList` when the bag exposes it, so the
+ * result reflects the same `mediaDevices` instance the SDK captures with;
+ * otherwise falls back to `navigator.mediaDevices.enumerateDevices()`.
+ *
+ * Labels are blank until the user has granted permission once — call this after
+ * the first successful capture if you need readable device names.
+ *
+ * @example
+ * ```ts
+ * const { cameras } = await listMediaDevices({ parameters });
+ * await runMediaControl({
+ *   parameters,
+ *   control: 'switchVideo',
+ *   extra: { videoPreference: cameras[1].deviceId },
+ * });
+ * ```
+ */
+export declare function listMediaDevices({ parameters, }: HeadlessOptions): Promise<MediaDeviceList>;
+export interface SelectedDevices {
+    /** Device id of the camera currently in use, or '' when none is selected. */
+    cameraId: string;
+    /** Device id of the microphone currently in use, or '' when none is selected. */
+    microphoneId: string;
+    /** Cameras the SDK has enumerated for this room. */
+    cameras: MediaDeviceInfo[];
+    /** Microphones the SDK has enumerated for this room. */
+    microphones: MediaDeviceInfo[];
+}
+export type GetSelectedDevicesType = (options: HeadlessOptions) => SelectedDevices;
+/**
+ * Which camera and microphone the SDK is actually using, plus the device lists
+ * it has already enumerated.
+ *
+ * Unlike {@link listMediaDevices} this is synchronous and needs no permission
+ * prompt: it reads `userDefaultVideoInputDevice` / `userDefaultAudioInputDevice`
+ * and the `videoInputs` / `audioInputs` the SDK populated during setup. Use it
+ * to mark the current entry in a device picker; use `listMediaDevices` when you
+ * need a freshly enumerated list.
+ *
+ * @example
+ * ```tsx
+ * const { cameras, cameraId } = getSelectedDevices({ parameters });
+ * <select value={cameraId} onChange={(e) => room.controls.selectCamera(e.target.value)}>
+ *   {cameras.map((d) => <option key={d.deviceId} value={d.deviceId}>{d.label}</option>)}
+ * </select>
+ * ```
+ */
+export declare function getSelectedDevices({ parameters }: HeadlessOptions): SelectedDevices;
+//# sourceMappingURL=participantState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"participantState.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/participantState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AAkBtE,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAChC,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,QAAQ,EAAE,OAAO,CAAC;IAClB,uDAAuD;IACvD,KAAK,EAAE,OAAO,CAAC;IACf,yDAAyD;IACzD,eAAe,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,+BAAgC,SAAQ,eAAe;IACtE,6BAA6B;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,4BAA4B,GAAG,CACzC,OAAO,EAAE,+BAA+B,KACrC,qBAAqB,CAAC;AAE3B;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,wBAAwB,CAAC,EACvC,UAAU,EACV,IAAS,EACT,EAAO,GACR,EAAE,+BAA+B,GAAG,qBAAqB,CA0BzD;AAED,MAAM,MAAM,8BAA8B,GAAG,CAC3C,OAAO,EAAE,eAAe,KACrB,qBAAqB,EAAE,CAAC;AAE7B,2EAA2E;AAC3E,wBAAgB,0BAA0B,CAAC,EACzC,UAAU,GACX,EAAE,eAAe,GAAG,qBAAqB,EAAE,CAS3C;AAED,MAAM,WAAW,aAAa;IAC5B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,aAAa,CAAC;AAE/E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,aAAa,CAkB/E;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,oBAAoB,GAAG,CACjC,OAAO,EAAE,eAAe,KACrB,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,UAAU,GACX,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAqB5C;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,wDAAwD;IACxD,WAAW,EAAE,eAAe,EAAE,CAAC;CAChC;AAED,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,eAAe,KAAK,eAAe,CAAC;AAEnF;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,eAAe,CAQnF"}

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

@@ -0,0 +1,106 @@
+import { HeadlessOptions } from './headlessTypes';
+/**
+ * Explicit playback: HLS and WHEP.
+ *
+ * **This is deliberately not part of the media-card surface.** WebRTC media is
+ * *auto-consumed* — the SDK subscribes for you, and `getRemoteVideoStreams` /
+ * `getAudioGridComponents` hand you what already arrived. HLS and WHEP are the
+ * opposite: nothing is consumed until you ask, because each one opens a
+ * connection the room did not ask for and would otherwise pay for.
+ *
+ * So the API here is imperative — `attachPlayback` / `detachPlayback` — rather
+ * than a reactive getter. Mixing these into the media cards would mean every
+ * room silently opened an HLS or WHEP connection whether or not anything
+ * rendered it.
+ *
+ * When to reach for which:
+ *
+ * | | latency | cost per viewer | use it for |
+ * | --- | --- | --- | --- |
+ * | WebRTC (auto) | sub-second | an SFU consumer | anyone who takes part |
+ * | WHEP | sub-second | an SFU consumer | standards-based egress to non-SDK players |
+ * | HLS | seconds | a CDN request | audiences too large to fan out over the SFU |
+ *
+ * A large passive audience on HLS is the reason this exists: it moves the
+ * expensive part — media fan-out — off the SFU.
+ */
+export type PlaybackProtocol = 'hls' | 'whep';
+export interface PlaybackSource {
+    protocol: PlaybackProtocol;
+    url: string;
+}
+/**
+ * Playback URLs the server has published for this room.
+ *
+ * Returns nothing when the room has none — HLS and WHEP are provisioned
+ * server-side, so absence means "not enabled for this room", not an error.
+ */
+export declare function getPlaybackSources({ parameters }: HeadlessOptions): PlaybackSource[];
+/** A running playback. Always `detachPlayback` it — none of this is garbage-collected. */
+export interface PlaybackHandle {
+    protocol: PlaybackProtocol;
+    url: string;
+    /** The media, when the protocol produces one directly (WHEP). */
+    stream: MediaStream | null;
+    /** Release the connection, the player, and the element's source. */
+    detach: () => void;
+}
+export interface AttachPlaybackOptions {
+    /** Playback URL, or a `PlaybackSource` from `getPlaybackSources`. */
+    source: string | PlaybackSource;
+    /** The element to play into. Required for HLS; optional for WHEP. */
+    video?: HTMLVideoElement | null;
+    /** Force a protocol. Inferred from the URL when omitted. */
+    protocol?: PlaybackProtocol;
+    /**
+     * Factory returning an hls.js instance, e.g. `() => new Hls({ lowLatencyMode: true })`.
+     *
+     * Required for HLS anywhere except Safari, and injected rather than imported
+     * so hls.js never becomes a dependency of this SDK — most rooms never play
+     * HLS, and React Native cannot use it at all.
+     */
+    hlsFactory?: () => any;
+    /** Extra headers for the WHEP POST, e.g. an auth token. */
+    headers?: Record<string, string>;
+    /** ICE servers for WHEP. Defaults to the room's own when available. */
+    iceServers?: RTCIceServer[];
+}
+export type AttachPlaybackType = (options: AttachPlaybackOptions) => Promise<PlaybackHandle>;
+/**
+ * Start an explicit playback.
+ *
+ * @example
+ * ```ts
+ * import Hls from 'hls.js';
+ *
+ * const [source] = getPlaybackSources({ parameters });
+ * const handle = await attachPlayback({
+ *   source,
+ *   video: videoRef.current,
+ *   hlsFactory: () => new Hls({ lowLatencyMode: true }),
+ * });
+ * // later, always:
+ * detachPlayback(handle);
+ * ```
+ */
+export declare function attachPlayback({ source, video, protocol, hlsFactory, headers, iceServers, }: AttachPlaybackOptions): Promise<PlaybackHandle>;
+/** Stop a playback and release everything it holds. Safe to call twice. */
+export declare function detachPlayback(handle: PlaybackHandle | null | undefined): void;
+export interface PublishWhipOptions {
+    /** The WHIP endpoint. */
+    url: string;
+    /** The stream to publish. */
+    stream: MediaStream;
+    headers?: Record<string, string>;
+    iceServers?: RTCIceServer[];
+}
+/**
+ * Publish a stream to a WHIP endpoint.
+ *
+ * The symmetric counterpart of WHEP, and equally explicit. This is *not* how
+ * you publish into a MediaSFU room — use `produceMedia` for that, which goes
+ * through the room's own transport and respects its capture entitlements. WHIP
+ * is for pushing to a standards-based ingest that is not this room.
+ */
+export declare function publishWhip({ url, stream, headers, iceServers, }: PublishWhipOptions): Promise<PlaybackHandle>;
+//# sourceMappingURL=playback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"playback.d.ts","sourceRoot":"","sources":["../../../../src/methods/utils/headless/playback.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAsB,MAAM,iBAAiB,CAAC;AAEtE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,UAAU,EAAE,EAAE,eAAe,GAAG,cAAc,EAAE,CASpF;AAED,0FAA0F;AAC1F,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAC3B,oEAAoE;IACpE,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC;IAChC,qEAAqE;IACrE,KAAK,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,gBAAgB,CAAC;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,CAAC;IACvB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uEAAuE;IACvE,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;CAC7B;AAkJD,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAE7F;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,cAAc,CAAC,EACnC,MAAM,EACN,KAAK,EACL,QAAQ,EACR,UAAU,EACV,OAAO,EACP,UAAU,GACX,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,CAAC,CAUjD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI,CAG9E;AAMD,MAAM,WAAW,kBAAkB;IACjC,yBAAyB;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,6BAA6B;IAC7B,MAAM,EAAE,WAAW,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,UAAU,CAAC,EAAE,YAAY,EAAE,CAAC;CAC7B;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,EAChC,GAAG,EACH,MAAM,EACN,OAAY,EACZ,UAAU,GACX,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,CAAC,CAsC9C"}