@voltkit-rtc/client 0.7.3 → 0.9.0

package/dist/cjs/adaptive.js

@@ -0,0 +1,263 @@
+"use strict";
+/**
+ * Adaptive stream: receive each remote video at the size it is shown, and not
+ * at all while nobody can see it.
+ *
+ * The app attaches the element that shows a video (`attachVideo`). From that
+ * element's size on screen (CSS pixels × devicePixelRatio, at most 2) the
+ * smallest simulcast layer that fills it sharply is chosen; while no attached
+ * element is visible (scrolled away, `display: none`, the tab in the
+ * background) the video is paused at the media server, so it costs no
+ * bandwidth and no decoding. This is what LiveKit calls adaptiveStream and
+ * Tencent TRTC "small stream + receiveWhenViewVisible": the single biggest
+ * saving on a viewer with several tiles, where every tile otherwise decodes
+ * the publisher's full-size layer.
+ *
+ * Pure decisions are exported for tests; the browser parts (observers,
+ * timers) are injected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdaptiveVideos = exports.LOWER_AFTER_MS = exports.PAUSE_AFTER_MS = exports.MAX_UPSCALE = exports.MAX_PIXEL_RATIO = void 0;
+exports.layerForBox = layerForBox;
+exports.wantFor = wantFor;
+exports.pageIsVisible = pageIsVisible;
+/** Never ask for more than twice the CSS size: a 3× phone screen gains nothing visible from it. */
+exports.MAX_PIXEL_RATIO = 2;
+/** A layer shown at most this much bigger than it is still looks sharp: avoids a whole layer for a few pixels. */
+exports.MAX_UPSCALE = 1.15;
+/**
+ * The smallest layer that fills `box` sharply, or null when the layers are
+ * not known (an older publisher): then the server chooses, as before.
+ *
+ * With `cover` the picture is scaled until it fills the box (a part is
+ * cropped), with `contain` until it fits. Either way the scale is measured
+ * against each layer's own size, so a portrait layer list works too.
+ */
+function layerForBox(layers, box, pixelRatio = 1) {
+    const usable = layers.filter((l) => l.width > 0 && l.height > 0).sort((a, b) => a.width * a.height - b.width * b.height);
+    if (!usable.length || box.width <= 0 || box.height <= 0)
+        return null;
+    const ratio = Math.min(exports.MAX_PIXEL_RATIO, Math.max(1, pixelRatio || 1));
+    const w = box.width * ratio;
+    const h = box.height * ratio;
+    for (const layer of usable) {
+        const scale = box.fit === 'cover' ? Math.max(w / layer.width, h / layer.height) : Math.min(w / layer.width, h / layer.height);
+        // The layer is at most slightly upscaled on screen.
+        if (scale <= exports.MAX_UPSCALE)
+            return layer.spatialLayer;
+    }
+    return usable[usable.length - 1].spatialLayer;
+}
+/**
+ * The largest view among the visible ones decides; any visible view keeps the video flowing. A view not measured
+ * yet (just attached, before layout) counts as shown at the server's choice, so attaching never pauses a video
+ * for the moment before the browser has sized the element.
+ */
+function wantFor(views, layers, pixelRatio, pageVisible) {
+    if (pageVisible && views.some((v) => v.measured === false))
+        return { visible: true, spatialLayer: null };
+    const shown = pageVisible ? views.filter((v) => v.visible && v.box.width > 0 && v.box.height > 0) : [];
+    if (!shown.length)
+        return { visible: false, spatialLayer: null };
+    let best = null;
+    for (const view of shown) {
+        const layer = layerForBox(layers, view.box, pixelRatio);
+        if (layer === null)
+            return { visible: true, spatialLayer: null };
+        best = best === null ? layer : Math.max(best, layer);
+    }
+    return { visible: true, spatialLayer: best };
+}
+/** Pause a hidden video only after this long, so scrolling past or a quick tab switch does not stop it. */
+exports.PAUSE_AFTER_MS = 1500;
+/** Go down a layer only after this long (going up is immediate): a tile shrinking for a moment keeps its picture. */
+exports.LOWER_AFTER_MS = 1200;
+const FLOWING = { visible: true, spatialLayer: null };
+const sameWant = (a, b) => a !== null && a.visible === b.visible && a.spatialLayer === b.spatialLayer;
+/**
+ * The videos being shown, by producer id. Decisions are applied through the
+ * host; going up (or becoming visible) is applied at once, going down (or
+ * hiding) after a short delay.
+ */
+class AdaptiveVideos {
+    host;
+    entries = new Map();
+    stopPage = null;
+    constructor(host) {
+        this.host = host;
+    }
+    /** Show `producerId` in `element`; returns the function that stops. */
+    attach(producerId, element) {
+        let entry = this.entries.get(producerId);
+        if (!entry) {
+            entry = { views: new Map(), applied: null, timer: null };
+            this.entries.set(producerId, entry);
+        }
+        if (entry.views.has(element))
+            return () => this.detach(producerId, element);
+        const view = { box: { width: 0, height: 0, fit: 'contain' }, visible: true, measured: false, stop: () => undefined };
+        entry.views.set(element, view);
+        view.stop = this.observe(element, (box, visible) => {
+            if (box) {
+                view.box = box;
+                view.measured = true;
+            }
+            if (visible !== null)
+                view.visible = visible;
+            this.update(producerId);
+        });
+        if (!this.stopPage)
+            this.stopPage = this.watchPage(() => { for (const id of this.entries.keys())
+                this.update(id); });
+        this.update(producerId);
+        return () => this.detach(producerId, element);
+    }
+    detach(producerId, element) {
+        const entry = this.entries.get(producerId);
+        const view = entry?.views.get(element);
+        if (!entry || !view)
+            return;
+        view.stop();
+        entry.views.delete(element);
+        if (entry.views.size) {
+            this.update(producerId);
+            return;
+        }
+        // Nothing shows it any more: back to how it was before (flowing, the server's choice).
+        this.clear(entry);
+        this.entries.delete(producerId);
+        if (entry.applied && !sameWant(entry.applied, { visible: true, spatialLayer: null }))
+            this.host.apply(producerId, { visible: true, spatialLayer: null });
+        if (!this.entries.size) {
+            this.stopPage?.();
+            this.stopPage = null;
+        }
+    }
+    /** Whether the app shows this video through attachVideo (its decisions then apply to new consumers too). */
+    has(producerId) {
+        return this.entries.has(producerId);
+    }
+    /** The decision in force, for a consumer made (or made again) after it: null when the app does not attach it. */
+    current(producerId) {
+        const entry = this.entries.get(producerId);
+        return entry ? this.decide(producerId, entry) : null;
+    }
+    /**
+     * A new consumer was made with `current()` applied (its layers, and paused when hidden): record that as applied,
+     * so nothing is sent twice, and drop a pending change made for the old one.
+     */
+    consumed(producerId) {
+        const entry = this.entries.get(producerId);
+        if (!entry)
+            return;
+        this.clear(entry);
+        entry.applied = this.decide(producerId, entry);
+    }
+    /** Stop everything (the session closed). */
+    dispose() {
+        for (const entry of this.entries.values()) {
+            this.clear(entry);
+            for (const view of entry.views.values())
+                view.stop();
+        }
+        this.entries.clear();
+        this.stopPage?.();
+        this.stopPage = null;
+    }
+    decide(producerId, entry) {
+        return wantFor([...entry.views.values()], this.host.layers(producerId), this.host.pixelRatio?.() ?? 1, this.host.pageVisible?.() ?? true);
+    }
+    update(producerId) {
+        const entry = this.entries.get(producerId);
+        if (!entry)
+            return;
+        const want = this.decide(producerId, entry);
+        // Nothing applied yet is the server's choice, flowing: asking for exactly that sends nothing.
+        if (sameWant(entry.applied ?? FLOWING, want)) {
+            this.clear(entry);
+            entry.applied ??= want;
+            return;
+        }
+        // Nothing applied yet means the video flows at the server's choice.
+        const prev = entry.applied ?? { visible: true, spatialLayer: null };
+        // Hiding, or a smaller layer than one applied, waits; anything else (showing, a bigger layer, a first layer) is at once.
+        const lower = (prev.visible && !want.visible) ||
+            (want.visible && prev.visible && want.spatialLayer !== null && prev.spatialLayer !== null && want.spatialLayer < prev.spatialLayer);
+        // Already waiting to lower: a repeated report must not restart the wait; it applies what is wanted when it runs out.
+        if (lower && entry.timer !== null)
+            return;
+        this.clear(entry);
+        if (!lower) {
+            entry.applied = want;
+            this.host.apply(producerId, want);
+            return;
+        }
+        const delay = want.visible ? exports.LOWER_AFTER_MS : exports.PAUSE_AFTER_MS;
+        entry.timer = (this.host.setTimer ?? ((fn, ms) => setTimeout(fn, ms)))(() => {
+            entry.timer = null;
+            const now = this.decide(producerId, entry);
+            if (sameWant(entry.applied, now))
+                return;
+            entry.applied = now;
+            this.host.apply(producerId, now);
+        }, delay);
+    }
+    clear(entry) {
+        if (entry.timer !== null)
+            (this.host.clearTimer ?? ((h) => clearTimeout(h)))(entry.timer);
+        entry.timer = null;
+    }
+    observe(element, onChange) {
+        if (this.host.observe)
+            return this.host.observe(element, onChange);
+        return observeElement(element, onChange);
+    }
+    watchPage(listener) {
+        if (this.host.onPageVisibility)
+            return this.host.onPageVisibility(listener);
+        if (typeof document === 'undefined')
+            return () => undefined;
+        document.addEventListener('visibilitychange', listener);
+        return () => document.removeEventListener('visibilitychange', listener);
+    }
+}
+exports.AdaptiveVideos = AdaptiveVideos;
+/** How an element fits its picture: a video's object-fit, else contain. */
+function fitOf(element) {
+    try {
+        const fit = typeof getComputedStyle === 'function' ? getComputedStyle(element).objectFit : '';
+        return fit === 'cover' || fit === 'fill' ? 'cover' : 'contain';
+    }
+    catch {
+        return 'contain';
+    }
+}
+/** The browser's observers: size (ResizeObserver) and visibility on screen (IntersectionObserver). */
+function observeElement(element, onChange) {
+    const stops = [];
+    const measure = () => {
+        const rect = element.getBoundingClientRect();
+        onChange({ width: rect.width, height: rect.height, fit: fitOf(element) }, null);
+    };
+    if (typeof ResizeObserver !== 'undefined') {
+        const resize = new ResizeObserver(() => measure());
+        resize.observe(element);
+        stops.push(() => resize.disconnect());
+    }
+    if (typeof IntersectionObserver !== 'undefined') {
+        const seen = new IntersectionObserver((entries) => {
+            const last = entries[entries.length - 1];
+            if (last)
+                onChange(null, last.isIntersecting);
+        });
+        seen.observe(element);
+        stops.push(() => seen.disconnect());
+    }
+    measure();
+    return () => stops.forEach((stop) => stop());
+}
+/** The page is visible (not a background tab). */
+function pageIsVisible() {
+    return typeof document === 'undefined' || document.visibilityState !== 'hidden';
+}
+//# sourceMappingURL=adaptive.js.map

package/dist/cjs/adaptive.js.map

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

package/dist/cjs/devices.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Cameras, microphones and speakers (docs/implementation-progress/RTC_PERF_PROGRESS.md I1).
+ *
+ * What the big SDKs do, read from their code:
+ * - Amazon Chime (`DefaultDeviceController`): lists devices by kind, watches `devicechange` and tells observers
+ *   which lists changed; a microphone that ends is replaced so audio keeps flowing, a camera that ends is stopped and
+ *   reported (`audioInputStreamEnded` / `videoInputStreamEnded`) -- never swapped for another camera on its own.
+ * - LiveKit (`Room.handleDeviceChange`, `switchActiveDevice`): switches the published track to a chosen device; when
+ *   the active audio device disappears it moves to the first available one.
+ * - Tencent TRTC: `DEVICE_CHANGED {type, action: add | remove | active}`.
+ *
+ * This module holds the pure parts: comparing device lists and building the constraints for a chosen device.
+ */
+export type DeviceKind = 'audioinput' | 'videoinput' | 'audiooutput';
+/** A camera, microphone or speaker, as the browser lists it. Labels are empty until a permission was granted. */
+export interface MediaDevice {
+    deviceId: string;
+    groupId: string;
+    kind: DeviceKind;
+    label: string;
+}
+export interface DevicesChangedEvent {
+    /** Every device now. */
+    devices: MediaDevice[];
+    added: MediaDevice[];
+    removed: MediaDevice[];
+}
+/** The browser's device list, optionally of one kind. Empty outside a browser. */
+export declare function enumerate(kind?: DeviceKind): Promise<MediaDevice[]>;
+/** What appeared and what went between two lists. */
+export declare function diffDevices(before: readonly MediaDevice[], after: readonly MediaDevice[]): {
+    added: MediaDevice[];
+    removed: MediaDevice[];
+};
+/**
+ * The constraints for capturing `deviceId` (or the system default when null), keeping everything else the app asked
+ * for: size, frame rate, echo cancellation. `base` is what publish was given for that kind.
+ */
+export declare function constraintsFor(base: boolean | MediaTrackConstraints | undefined, deviceId: string | null): MediaTrackConstraints;
+/** The device a live track captures, when it is a device capture at all (a canvas or a processed track has none). */
+export declare function deviceIdOf(track: MediaStreamTrack | null | undefined): string | null;
+//# sourceMappingURL=devices.d.ts.map

package/dist/cjs/devices.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.d.ts","sourceRoot":"","sources":["../../src/devices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,YAAY,GAAG,aAAa,CAAC;AAErE,iHAAiH;AACjH,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,UAAU,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB;AAED,kFAAkF;AAClF,wBAAsB,SAAS,CAAC,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAQzE;AAID,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG;IAAE,KAAK,EAAE,WAAW,EAAE,CAAC;IAAC,OAAO,EAAE,WAAW,EAAE,CAAA;CAAE,CAO3I;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,qBAAqB,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,qBAAqB,CAKhI;AAED,qHAAqH;AACrH,wBAAgB,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGpF"}

package/dist/cjs/devices.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Cameras, microphones and speakers (docs/implementation-progress/RTC_PERF_PROGRESS.md I1).
+ *
+ * What the big SDKs do, read from their code:
+ * - Amazon Chime (`DefaultDeviceController`): lists devices by kind, watches `devicechange` and tells observers
+ *   which lists changed; a microphone that ends is replaced so audio keeps flowing, a camera that ends is stopped and
+ *   reported (`audioInputStreamEnded` / `videoInputStreamEnded`) -- never swapped for another camera on its own.
+ * - LiveKit (`Room.handleDeviceChange`, `switchActiveDevice`): switches the published track to a chosen device; when
+ *   the active audio device disappears it moves to the first available one.
+ * - Tencent TRTC: `DEVICE_CHANGED {type, action: add | remove | active}`.
+ *
+ * This module holds the pure parts: comparing device lists and building the constraints for a chosen device.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enumerate = enumerate;
+exports.diffDevices = diffDevices;
+exports.constraintsFor = constraintsFor;
+exports.deviceIdOf = deviceIdOf;
+/** The browser's device list, optionally of one kind. Empty outside a browser. */
+async function enumerate(kind) {
+    const md = typeof navigator !== 'undefined' ? navigator.mediaDevices : undefined;
+    if (!md?.enumerateDevices)
+        return [];
+    const all = await md.enumerateDevices();
+    return all
+        .filter((d) => d.kind === 'audioinput' || d.kind === 'videoinput' || d.kind === 'audiooutput')
+        .filter((d) => !kind || d.kind === kind)
+        .map((d) => ({ deviceId: d.deviceId, groupId: d.groupId, kind: d.kind, label: d.label }));
+}
+const key = (d) => `${d.kind}:${d.deviceId}`;
+/** What appeared and what went between two lists. */
+function diffDevices(before, after) {
+    const was = new Set(before.map(key));
+    const now = new Set(after.map(key));
+    return {
+        added: after.filter((d) => !was.has(key(d))),
+        removed: before.filter((d) => !now.has(key(d))),
+    };
+}
+/**
+ * The constraints for capturing `deviceId` (or the system default when null), keeping everything else the app asked
+ * for: size, frame rate, echo cancellation. `base` is what publish was given for that kind.
+ */
+function constraintsFor(base, deviceId) {
+    const rest = typeof base === 'object' && base !== null ? { ...base } : {};
+    delete rest.deviceId;
+    delete rest.groupId;
+    return deviceId === null ? rest : { ...rest, deviceId: { exact: deviceId } };
+}
+/** The device a live track captures, when it is a device capture at all (a canvas or a processed track has none). */
+function deviceIdOf(track) {
+    const id = track?.getSettings?.().deviceId;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+//# sourceMappingURL=devices.js.map

package/dist/cjs/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.js","sourceRoot":"","sources":["../../src/devices.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;AAoBH,8BAQC;AAKD,kCAOC;AAMD,wCAKC;AAGD,gCAGC;AAtCD,kFAAkF;AAC3E,KAAK,UAAU,SAAS,CAAC,IAAiB;IAC/C,MAAM,EAAE,GAAG,OAAO,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,IAAI,CAAC,EAAE,EAAE,gBAAgB;QAAE,OAAO,EAAE,CAAC;IACrC,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,gBAAgB,EAAE,CAAC;IACxC,OAAO,GAAG;SACP,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,YAAY,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC;SAC7F,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;SACvC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAkB,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAC5G,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,CAAc,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;AAE1D,qDAAqD;AACrD,SAAgB,WAAW,CAAC,MAA8B,EAAE,KAA6B;IACvF,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACrC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IACpC,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;KAChD,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc,CAAC,IAAiD,EAAE,QAAuB;IACvG,MAAM,IAAI,GAA0B,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjG,OAAO,IAAI,CAAC,QAAQ,CAAC;IACrB,OAAO,IAAI,CAAC,OAAO,CAAC;IACpB,OAAO,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,CAAC;AAC/E,CAAC;AAED,qHAAqH;AACrH,SAAgB,UAAU,CAAC,KAA0C;IACnE,MAAM,EAAE,GAAG,KAAK,EAAE,WAAW,EAAE,EAAE,CAAC,QAAQ,CAAC;IAC3C,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC"}

package/dist/cjs/diagnostics.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Diagnostics for support (docs/implementation-progress/RTC_PERF_PROGRESS.md S4).
+ *
+ * Agora uploads its SDK log on request (`enableLogUpload`), Twilio sends call telemetry to Insights, Stream Video
+ * traces session events to its servers. Shipping telemetry needs a backend; what helps today is a snapshot an app can
+ * attach to a support ticket: the SDK's recent events (a ring buffer) and its state now.
+ */
+/** This package's version; kept equal to package.json by a test. */
+export declare const SDK_VERSION = "0.9.0";
+/** How many recent events the log keeps. */
+export declare const DIAGNOSTICS_LOG_SIZE = 200;
+export interface DiagnosticsEntry {
+    /** Unix ms. */
+    at: number;
+    event: string;
+    /** A short summary of what the event carried (no media objects). */
+    detail?: string;
+}
+/** A ring buffer of the SDK's recent events. */
+export declare class DiagnosticsLog {
+    private readonly now;
+    private readonly entries;
+    constructor(now?: () => number);
+    /** Keep an emitted event, when it is one worth keeping. */
+    record(event: string, args: unknown[]): void;
+    list(): DiagnosticsEntry[];
+}
+export interface DiagnosticsTransport {
+    state: string;
+    path: {
+        protocol: 'udp' | 'tcp' | null;
+        relayed: boolean;
+    } | null;
+}
+export interface Diagnostics {
+    sdk: string;
+    at: number;
+    userAgent: string;
+    connectionState: string;
+    room: string | null;
+    identity: string | null;
+    role: string | null;
+    transports: {
+        send: DiagnosticsTransport | null;
+        recv: DiagnosticsTransport | null;
+    };
+    network: {
+        rttMs: number | null;
+        availableKbps: number | null;
+    } | null;
+    published: {
+        source: string;
+        kind: string;
+        paused: boolean;
+    }[];
+    received: {
+        identity: string;
+        source: string;
+        kind: string;
+        paused: boolean;
+    }[];
+    /** Recent events, oldest first. */
+    log: DiagnosticsEntry[];
+}
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/cjs/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oEAAoE;AACpE,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,4CAA4C;AAC5C,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,MAAM,WAAW,gBAAgB;IAC/B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AA6BD,gDAAgD;AAChD,qBAAa,cAAc;IAGb,OAAO,CAAC,QAAQ,CAAC,GAAG;IAFhC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;gBAErB,GAAG,GAAE,MAAM,MAAiB;IAEzD,2DAA2D;IAC3D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAa5C,IAAI,IAAI,gBAAgB,EAAE;CAG3B;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE;QAAE,QAAQ,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CACnE;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,UAAU,EAAE;QAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;QAAC,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAA;KAAE,CAAC;IACrF,OAAO,EAAE;QAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI,CAAC;IACvE,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAC/D,QAAQ,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC;IAChF,mCAAmC;IACnC,GAAG,EAAE,gBAAgB,EAAE,CAAC;CACzB"}

package/dist/cjs/diagnostics.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Diagnostics for support (docs/implementation-progress/RTC_PERF_PROGRESS.md S4).
+ *
+ * Agora uploads its SDK log on request (`enableLogUpload`), Twilio sends call telemetry to Insights, Stream Video
+ * traces session events to its servers. Shipping telemetry needs a backend; what helps today is a snapshot an app can
+ * attach to a support ticket: the SDK's recent events (a ring buffer) and its state now.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnosticsLog = exports.DIAGNOSTICS_LOG_SIZE = exports.SDK_VERSION = void 0;
+/** This package's version; kept equal to package.json by a test. */
+exports.SDK_VERSION = '0.9.0';
+/** How many recent events the log keeps. */
+exports.DIAGNOSTICS_LOG_SIZE = 200;
+/** The events worth keeping for support, and how to summarise each. */
+const SUMMARY = {
+    connectionStateChanged: ([e]) => { const s = e; return `${s.previous} → ${s.state}`; },
+    disconnected: ([reason]) => String(reason),
+    closed: ([reason]) => String(reason),
+    mustReconnect: ([e]) => e.reason,
+    mediaReconnecting: ([e]) => { const m = e; return `${m.transportId} ${m.reconnecting ? 'recovering' : 'recovered'}`; },
+    error: ([e]) => {
+        const err = e;
+        const message = err.message ?? '';
+        // RpcError's message already starts with its code.
+        return (err.code && !message.startsWith(`${err.code}:`) ? `${err.code}: ${message}` : message).slice(0, 300);
+    },
+    streamFallback: ([e]) => { const f = e; return `${f.producerId} ${f.fallback ? 'held' : 'back'} (${f.reason})`; },
+    mediaWarning: ([e]) => { const w = e; return `${w.code} ${w.active ? 'started' : 'cleared'}`; },
+    cpuConstrained: ([e]) => String(e.constrained),
+    videoLimited: ([e]) => e.reason,
+    localTrackEnded: ([e]) => { const t = e; return `${t.kind} ${t.recovered ? 'recovered' : 'off'}`; },
+    devicesChanged: ([e]) => { const d = e; return `+${d.added?.length ?? 0} -${d.removed?.length ?? 0}`; },
+    kicked: ([e]) => e.reason,
+    roomClosed: ([e]) => e.reason,
+    usageLimit: ([e]) => e.reason,
+    autoplayFailed: () => undefined,
+    trackEnded: ([e]) => e.producerId,
+    track: ([e]) => { const t = e; return `${t.identity} ${t.source}`; },
+};
+/** A ring buffer of the SDK's recent events. */
+class DiagnosticsLog {
+    now;
+    entries = [];
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Keep an emitted event, when it is one worth keeping. */
+    record(event, args) {
+        const summarize = SUMMARY[event];
+        if (!summarize)
+            return;
+        let detail;
+        try {
+            detail = summarize(args);
+        }
+        catch {
+            detail = undefined;
+        }
+        this.entries.push(detail === undefined ? { at: this.now(), event } : { at: this.now(), event, detail });
+        if (this.entries.length > exports.DIAGNOSTICS_LOG_SIZE)
+            this.entries.shift();
+    }
+    list() {
+        return this.entries.map((e) => ({ ...e }));
+    }
+}
+exports.DiagnosticsLog = DiagnosticsLog;
+//# sourceMappingURL=diagnostics.js.map

package/dist/cjs/diagnostics.js.map

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

package/dist/cjs/effects-core.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Video effects, the parts that need no browser (docs/implementation-progress/RTC_PERF_PROGRESS.md P3-5): settings,
+ * fitting a background image, the size segmentation runs at, and pacing it on a slow device. Kept apart from the
+ * WebGL and MediaPipe code so they are tested in Node.
+ */
+/** A background picture: a URL, or anything the browser can draw. */
+export type BackgroundImageSource = string | Blob | ImageBitmap | HTMLImageElement | HTMLCanvasElement | OffscreenCanvas;
+/** What happens behind the person: nothing, a blur, or a picture. */
+export type BackgroundSetting = 'none' | 'blur' | {
+    image: BackgroundImageSource;
+};
+/** Beauty, each 0-1 (Agora's beauty effect has the same four). */
+export interface BeautyOptions {
+    /** Skin smoothing. Default 0.5. */
+    smooth?: number;
+    /** Brightening. Default 0.3. */
+    brighten?: number;
+    /** A rosier skin. Default 0.1. */
+    redness?: number;
+    /** Sharper eyes, hair and edges (not skin). Default 0.3. */
+    sharpen?: number;
+}
+export interface BeautySettings {
+    smooth: number;
+    brighten: number;
+    redness: number;
+    sharpen: number;
+}
+export declare const DEFAULT_BEAUTY: Readonly<BeautySettings>;
+/** The blur behind the person, 1 (light) to 10 (strong). */
+export declare const DEFAULT_BLUR = 5;
+/** Beauty settings from what the app passed: `true` is the defaults, `false`/`null` is off. */
+export declare function beautySettings(options: BeautyOptions | boolean | null | undefined): BeautySettings | null;
+/** A blur level from what the app passed: 1-10, rounded; anything else is the default. */
+export declare function blurLevel(value: unknown): number;
+/**
+ * The blur's Gaussian sigma, in texels of the quarter-size picture it is computed on: a share of the picture's height,
+ * so a level looks the same at 480p and 1080p.
+ */
+export declare function blurSigma(level: number, blurHeight: number): number;
+/** What the background setting asks of the pipeline. */
+export declare function backgroundMode(setting: BackgroundSetting | undefined | null): 'none' | 'blur' | 'image';
+/**
+ * Fit a background picture to the frame the way CSS `object-fit: cover` does: it fills the frame, cropped evenly on
+ * the long side, never stretched. Returns the texture transform `imageUv = frameUv * scale + offset`.
+ */
+export declare function coverFit(imageWidth: number, imageHeight: number, frameWidth: number, frameHeight: number): {
+    sx: number;
+    sy: number;
+    ox: number;
+    oy: number;
+};
+/** The size the person is found at: the frame scaled so its longer side is `longSide` (the model's input). */
+export declare function segmentationSize(width: number, height: number, longSide?: number): {
+    width: number;
+    height: number;
+};
+/** How fast the mask follows a new one: lower is steadier between frames, higher follows movement sooner. */
+export declare const MASK_FOLLOW = 0.65;
+/**
+ * Smooth the person mask between frames (Stream's temporal smoothing), against flicker at the edges, and write it as
+ * bytes for the GPU. `steady` keeps the running mask; a new size starts it over.
+ */
+export declare function smoothMask(confidence: Float32Array, steady: Float32Array | null, out: Uint8Array, follow?: number): Float32Array;
+/** The most frames a mask is reused for before the device is called overloaded. */
+export declare const MAX_SEGMENT_EVERY = 6;
+/**
+ * Amazon Chime's adaptive background filter: finding the person is the expensive part, so when it takes too much of
+ * each frame's time it runs only every Nth frame and the last mask is reused -- the picture still runs at the camera's
+ * rate. N comes back down once it is cheap again. `overloaded` is the point where even that is not enough.
+ */
+export declare class SegmentationPacer {
+    private readonly maxEvery;
+    private average;
+    private changedAt;
+    private every;
+    constructor(maxEvery?: number);
+    /** Run segmentation on every this-many frames. */
+    get interval(): number;
+    /** Average milliseconds one segmentation takes. */
+    get segmentMs(): number;
+    shouldSegment(frameIndex: number): boolean;
+    /** The share of the frame time segmentation takes now, given how often it runs. */
+    load(frameIntervalMs: number): number;
+    /** Whether segmenting even this rarely still takes too long. */
+    overloaded(frameIntervalMs: number): boolean;
+    /** One segmentation took `ms`, at a frame interval of `frameIntervalMs`. */
+    report(ms: number, frameIntervalMs: number, now: number): void;
+}
+/** Timestamps MediaPipe's video mode accepts: in milliseconds and always increasing. */
+export declare class MonotonicClock {
+    private last;
+    next(now: number): number;
+}
+//# sourceMappingURL=effects-core.d.ts.map

package/dist/cjs/effects-core.d.ts.map

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