@voltkit-rtc/client 0.7.3 → 0.8.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":";AAAA;;;;;;;;;;;;;;;;GAgBG;;;AAwBH,kCAYC;AAaD,0BAWC;AAwND,sCAEC;AA3QD,mGAAmG;AACtF,QAAA,eAAe,GAAG,CAAC,CAAC;AACjC,kHAAkH;AACrG,QAAA,WAAW,GAAG,IAAI,CAAC;AAEhC;;;;;;;GAOG;AACH,SAAgB,WAAW,CAAC,MAA6B,EAAE,GAAY,EAAE,UAAU,GAAG,CAAC;IACrF,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC;IACzH,IAAI,CAAC,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACrE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,uBAAe,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;IACtE,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;IAC5B,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,GAAG,KAAK,CAAC;IAC7B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC9H,oDAAoD;QACpD,IAAI,KAAK,IAAI,mBAAW;YAAE,OAAO,KAAK,CAAC,YAAY,CAAC;IACtD,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,YAAY,CAAC;AACjD,CAAC;AAQD;;;;GAIG;AACH,SAAgB,OAAO,CAAC,KAAwE,EAAE,MAA6B,EAAE,UAAkB,EAAE,WAAoB;IACvK,IAAI,WAAW,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,KAAK,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACzG,MAAM,KAAK,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvG,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACjE,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC;QACxD,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACjE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AAC/C,CAAC;AAED,2GAA2G;AAC9F,QAAA,cAAc,GAAG,IAAI,CAAC;AACnC,qHAAqH;AACxG,QAAA,cAAc,GAAG,IAAI,CAAC;AA+BnC,MAAM,OAAO,GAAiB,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;AACpE,MAAM,QAAQ,GAAG,CAAC,CAAsB,EAAE,CAAe,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY,CAAC;AAEzI;;;;GAIG;AACH,MAAa,cAAc;IAII;IAHZ,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAC;IAC5C,QAAQ,GAAwB,IAAI,CAAC;IAE7C,YAA6B,IAAkB;QAAlB,SAAI,GAAJ,IAAI,CAAc;IAAG,CAAC;IAEnD,uEAAuE;IACvE,MAAM,CAAC,UAAkB,EAAE,OAAgB;QACzC,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACzC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,GAAG,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACzD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACtC,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC;YAAE,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAC5E,MAAM,IAAI,GAAS,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAC;QAC3H,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE;YACjD,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC;gBACf,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;YACvB,CAAC;YACD,IAAI,OAAO,KAAK,IAAI;gBAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;YAC7C,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,IAAI,CAAC,QAAQ;YAAE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,EAAE,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE;gBAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrH,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAChD,CAAC;IAED,MAAM,CAAC,UAAkB,EAAE,OAAgB;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,IAAI,CAAC,IAAI;YAAE,OAAO;QAC5B,IAAI,CAAC,IAAI,EAAE,CAAC;QACZ,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC5B,IAAI,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;YACxB,OAAO;QACT,CAAC;QACD,uFAAuF;QACvF,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;QAChC,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;YAAE,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QACzJ,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YACvB,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;YAClB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACvB,CAAC;IACH,CAAC;IAED,4GAA4G;IAC5G,GAAG,CAAC,UAAkB;QACpB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACtC,CAAC;IAED,iHAAiH;IACjH,OAAO,CAAC,UAAkB;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACvD,CAAC;IAED;;;OAGG;IACH,QAAQ,CAAC,UAAkB;QACzB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;IAED,4CAA4C;IAC5C,OAAO;QACL,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;YAC1C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE;gBAAE,IAAI,CAAC,IAAI,EAAE,CAAC;QACvD,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC,QAAQ,EAAE,EAAE,CAAC;QAClB,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;IACvB,CAAC;IAEO,MAAM,CAAC,UAAkB,EAAE,KAAY;QAC7C,OAAO,OAAO,CAAC,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC;IAC5I,CAAC;IAEO,MAAM,CAAC,UAAkB;QAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,KAAK;YAAE,OAAO;QACnB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QAC5C,8FAA8F;QAC9F,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,IAAI,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;YAC7C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAClB,KAAK,CAAC,OAAO,KAAK,IAAI,CAAC;YACvB,OAAO;QACT,CAAC;QACD,oEAAoE;QACpE,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACpE,yHAAyH;QACzH,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC;YAC3C,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,IAAI,IAAI,CAAC,YAAY,KAAK,IAAI,IAAI,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC,CAAC;QACtI,qHAAqH;QACrH,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;YAAE,OAAO;QAC1C,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;YACrB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;YAClC,OAAO;QACT,CAAC;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAc,CAAC,CAAC,CAAC,sBAAc,CAAC;QAC7D,KAAK,CAAC,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE;YAC1E,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;YACnB,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;YAC3C,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,GAAG,CAAC;gBAAE,OAAO;YACzC,KAAK,CAAC,OAAO,GAAG,GAAG,CAAC;YACpB,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;QACnC,CAAC,EAAE,KAAK,CAAC,CAAC;IACZ,CAAC;IAEO,KAAK,CAAC,KAAY;QACxB,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI;YAAE,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,CAAkC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3H,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC;IACrB,CAAC;IAEO,OAAO,CAAC,OAAgB,EAAE,QAAgE;QAChG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACnE,OAAO,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAC3C,CAAC;IAEO,SAAS,CAAC,QAAoB;QACpC,IAAI,IAAI,CAAC,IAAI,CAAC,gBAAgB;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,CAAC,CAAC;QAC5E,IAAI,OAAO,QAAQ,KAAK,WAAW;YAAE,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QAC5D,QAAQ,CAAC,gBAAgB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;QACxD,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,mBAAmB,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;IAC1E,CAAC;CACF;AAvID,wCAuIC;AAED,2EAA2E;AAC3E,SAAS,KAAK,CAAC,OAAgB;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,OAAO,gBAAgB,KAAK,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9F,OAAO,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,sGAAsG;AACtG,SAAS,cAAc,CAAC,OAAgB,EAAE,QAAgE;IACxG,MAAM,KAAK,GAAmB,EAAE,CAAC;IACjC,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,MAAM,IAAI,GAAG,OAAO,CAAC,qBAAqB,EAAE,CAAC;QAC7C,QAAQ,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IAClF,CAAC,CAAC;IACF,IAAI,OAAO,cAAc,KAAK,WAAW,EAAE,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;QACnD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACxB,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,IAAI,OAAO,oBAAoB,KAAK,WAAW,EAAE,CAAC;QAChD,MAAM,IAAI,GAAG,IAAI,oBAAoB,CAAC,CAAC,OAAO,EAAE,EAAE;YAChD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YACzC,IAAI,IAAI;gBAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,cAAc,CAAC,CAAC;QAChD,CAAC,CAAC,CAAC;QACH,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IACtC,CAAC;IACD,OAAO,EAAE,CAAC;IACV,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED,kDAAkD;AAClD,SAAgB,aAAa;IAC3B,OAAO,OAAO,QAAQ,KAAK,WAAW,IAAI,QAAQ,CAAC,eAAe,KAAK,QAAQ,CAAC;AAClF,CAAC"}

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.8.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.8.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/fallback.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Audio-only fallback (docs/implementation-progress/RTC_PERF_PROGRESS.md H1).
+ *
+ * When this viewer's connection is so poor that even the sound breaks up, remote camera videos are paused at the
+ * server so what bandwidth there is goes to the audio, and they come back once the connection has recovered.
+ *
+ * - Agora's `setStreamFallbackOption(uid, AUDIO_ONLY)` drops to the low stream and then to audio only, and reports
+ *   `stream-fallback` (fallback / recover).
+ * - Amazon Chime watches the audio it receives (`UnusableAudioWarningConnectionHealthPolicy`): about half of the
+ *   expected packets missing over 15 one-second samples suggests stopping video, with a 60 s cool-down.
+ *
+ * This follows Chime's signal -- the audio actually received -- measured as RTP loss (sequence gaps) rather than
+ * packet counts, because Opus DTX sends almost nothing during silence and a count would read silence as loss.
+ * Extreme only: {@link FALLBACK_LOSS} of the audio lost over {@link FALLBACK_SAMPLES} samples, with at least
+ * {@link MIN_PACKETS} packets to judge by. Back after a hold ({@link FIRST_HOLD_MS}, doubled for each relapse within
+ * {@link RELAPSE_MS}, up to {@link MAX_HOLD_MS}) once the loss is under {@link RECOVER_LOSS} -- or nobody spoke
+ * enough to tell, in which case video comes back and a still-bad connection falls back again, holding longer.
+ *
+ * The SFU cutting a video for bandwidth by itself is reported separately, by the server (`reason: 'bandwidth'`).
+ * Pure: the decisions take counters and a clock.
+ */
+import type { StatsEntry } from './stats.js';
+/** How often the received audio is sampled while the fallback could be needed. */
+export declare const PROTECT_SAMPLE_MS = 3000;
+/** This share of the audio lost (RTP sequence gaps) over the window: fall back. */
+export declare const FALLBACK_LOSS = 0.25;
+/** Below this share lost over the recovery window: video may come back. */
+export declare const RECOVER_LOSS = 0.05;
+/** Samples judged for falling back (15 s at 3 s) -- at least 3 of them. */
+export declare const FALLBACK_SAMPLES = 5;
+/** Samples judged for coming back (12 s). */
+export declare const RECOVER_SAMPLES = 4;
+/** Fewer audio packets than this over the fallback window are too few to judge. */
+export declare const MIN_PACKETS = 150;
+/** Fewer than this over the recovery window: nobody spoke enough to tell. */
+export declare const MIN_RECOVER_PACKETS = 30;
+/** The first fallback lasts at least this long. */
+export declare const FIRST_HOLD_MS = 20000;
+/** A relapse doubles the hold, up to this. */
+export declare const MAX_HOLD_MS = 160000;
+/** Falling back again within this long of coming back is a relapse. */
+export declare const RELAPSE_MS = 120000;
+export interface AudioCounters {
+    received: number;
+    lost: number;
+}
+/** The received-audio counters of a receive transport's report, summed over its audio streams. */
+export declare function readInboundAudio(report: Iterable<StatsEntry>): AudioCounters;
+/**
+ * The sent-audio counters of a send transport's report: packets sent, and how many of them the server reported
+ * lost (its RTCP receiver reports). For the publisher side (Agora's setLocalPublishFallbackOption): `received` is what
+ * got through.
+ */
+export declare function readOutboundAudio(report: Iterable<StatsEntry>): AudioCounters;
+/** Decides when to fall back to audio only and when video may come back. */
+export declare class AudioProtection {
+    private readonly onChange;
+    private readonly now;
+    private samples;
+    private previous;
+    private activeSince;
+    private hold;
+    private recoveredAt;
+    constructor(onChange: (active: boolean) => void, now?: () => number);
+    /** Whether remote camera videos are held back now. */
+    get active(): boolean;
+    /** How long the current (or next first) fallback holds, in ms. */
+    get holdMs(): number;
+    /**
+     * One reading of the cumulative counters. They only go up on one transport; lower ones are a new transport, and
+     * judging starts over from them.
+     */
+    feed(counters: AudioCounters): void;
+    /** Come back now (the app turned the fallback off). */
+    release(): void;
+    /** The transports went away (reconnect, close): forget everything, without telling. */
+    reset(): void;
+    private activate;
+    private recover;
+}
+//# sourceMappingURL=fallback.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../src/fallback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,mFAAmF;AACnF,eAAO,MAAM,aAAa,OAAO,CAAC;AAClC,2EAA2E;AAC3E,eAAO,MAAM,YAAY,OAAO,CAAC;AACjC,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,6CAA6C;AAC7C,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,mFAAmF;AACnF,eAAO,MAAM,WAAW,MAAM,CAAC;AAC/B,6EAA6E;AAC7E,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,mDAAmD;AACnD,eAAO,MAAM,aAAa,QAAS,CAAC;AACpC,8CAA8C;AAC9C,eAAO,MAAM,WAAW,SAAU,CAAC;AACnC,uEAAuE;AACvE,eAAO,MAAM,UAAU,SAAU,CAAC;AAElC,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;CACd;AAID,kGAAkG;AAClG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAU5E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,aAAa,CAW7E;AAED,4EAA4E;AAC5E,qBAAa,eAAe;IAQxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,GAAG;IARtB,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,WAAW,CAAuB;IAC1C,OAAO,CAAC,IAAI,CAAiB;IAC7B,OAAO,CAAC,WAAW,CAAuB;gBAGvB,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,EACnC,GAAG,GAAE,MAAM,MAAiB;IAG/C,sDAAsD;IACtD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,kEAAkE;IAClE,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;OAGG;IACH,IAAI,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI;IAsBnC,uDAAuD;IACvD,OAAO,IAAI,IAAI;IAIf,uFAAuF;IACvF,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,OAAO;CAMhB"}