@appsocom/client 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appsotech Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,30 @@
-# Temporary Holding Version
+# @appsocom/client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Browser client for [Appsocom Live](https://live.appsocom.com) video calls. It joins a room from any web app (React, Vue, Svelte or none), handles the media connection, reconnects and video quality, and gives you the room's events. You decide how it looks.
+
+```bash
+npm install @appsocom/client
+```
+
+```ts
+import { joinRoom, attachTrack } from "@appsocom/client";
+
+const { token } = await fetch("/api/join-token").then((r) => r.json()); // minted by your backend
+const room = await joinRoom({ url: "https://api.appsocom.dev", token, audio: true, video: true });
+
+room.on("local-track", (kind, track) => {
+  if (kind === "video") attachTrack(document.querySelector("#me"), track);
+});
+room.on("track", (participant, kind, track) => {
+  if (kind === "video") attachTrack(videoFor(participant.id), track); // remote audio plays by itself
+});
+
+document.querySelector("#mic").onclick = () => room.toggleMic();
+document.querySelector("#leave").onclick = () => room.leave();
+```
+
+Join tokens come from your backend with a server SDK such as [`@appsocom/node`](https://www.npmjs.com/package/@appsocom/node). Want a ready-made call screen? Use [`@appsocom/react`](https://www.npmjs.com/package/@appsocom/react).
+
+Guides: [Quickstart](https://docs.appsocom.dev/quickstart) · [Web client](https://docs.appsocom.dev/web-client)
+
+Docs: [docs.appsocom.dev](https://docs.appsocom.dev) · License: MIT

package/dist/adaptive.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Adaptive quality for weak connections. Pure logic (no DOM, no WebRTC objects),
+ * so it can be unit-tested: feed it LinkSample values, read back decisions.
+ */
+import type { ConnectionQuality, DataUsage, VideoLayer, VideoQuality } from "@appsocom/protocol";
+export type { DataUsage } from "@appsocom/protocol";
+/** Simulcast encodings for camera video. RIDs sort in quality order (see VideoLayer). */
+export declare const CAMERA_SIMULCAST: RTCRtpEncodingParameters[];
+export declare const CAMERA_LAYERS: VideoLayer[];
+/** Camera capture size when simulcast is on, so the layers are 720p / 360p / 180p. */
+export declare const CAMERA_CONSTRAINTS: MediaTrackConstraints;
+export declare const rank: (q: VideoQuality) => number;
+export declare const minQuality: (a: VideoQuality, b: VideoQuality) => VideoQuality;
+/** Which quality a <video> of this rendered height (CSS px × devicePixelRatio) needs. */
+export declare function qualityForHeight(pixels: number): VideoQuality;
+/** One measurement of the link, taken from RTCPeerConnection.getStats() every couple of seconds. */
+export interface LinkSample {
+    /** Fraction of incoming packets lost since the last sample (0–1). */
+    inboundLoss: number;
+    /** Fraction of our outgoing packets the SFU reports lost (0–1), if known. */
+    outboundLoss?: number;
+    /** Round-trip time to the SFU in seconds, if known. */
+    rtt?: number;
+    /** Browser's estimate of upload bandwidth in bits/s, if known. */
+    availableOutgoingBitrate?: number;
+}
+export interface AdaptiveState {
+    /** Highest video quality we currently allow ourselves to receive. */
+    receiveCap: VideoQuality;
+    /** Whether we currently send camera video. */
+    sendVideo: boolean;
+    badRecv: number;
+    goodRecv: number;
+    badSend: number;
+    goodSend: number;
+}
+export declare const initialAdaptiveState: () => AdaptiveState;
+/** Tuning. Samples are ~2s apart, so 3 samples ≈ 6s, 5 ≈ 10s. */
+export declare const ADAPTIVE: {
+    recvBadLoss: number;
+    recvGoodLoss: number;
+    badRtt: number;
+    goodRtt: number;
+    sendBadBitrate: number;
+    sendGoodBitrate: number;
+    sendBadLoss: number;
+    samplesToDegrade: number;
+    samplesToRecover: number;
+};
+/**
+ * Next adaptive state. Degrades one step at a time after sustained trouble and
+ * recovers one step at a time after a longer stretch of good samples (hysteresis,
+ * so it doesn't flap).
+ */
+export declare function nextAdaptiveState(prev: AdaptiveState, s: LinkSample, t?: {
+    recvBadLoss: number;
+    recvGoodLoss: number;
+    badRtt: number;
+    goodRtt: number;
+    sendBadBitrate: number;
+    sendGoodBitrate: number;
+    sendBadLoss: number;
+    samplesToDegrade: number;
+    samplesToRecover: number;
+}): AdaptiveState;
+/**
+ * Rate a link for the UI. Loss is the stronger signal (it's what people hear and
+ * see); RTT adds delay/echo. Thresholds roughly follow common WebRTC MOS buckets.
+ */
+export declare function connectionQualityFromSample(s: LinkSample): ConnectionQuality;
+/** Cumulative counters kept between samples to compute per-interval loss. */
+export interface StatsCursor {
+    inLost: number;
+    inReceived: number;
+    /** Per remote-inbound report: a marker that changes with each new RTCP report. */
+    outReports?: Record<string, number>;
+}
+/**
+ * Turns an RTCStatsReport into a LinkSample. `cursor` holds the previous totals;
+ * the function returns the new totals alongside the sample.
+ */
+export declare function sampleFromStats(report: RTCStatsReport, cursor: StatsCursor | null): {
+    sample: LinkSample;
+    cursor: StatsCursor;
+};
+/**
+ * Audio-first fallback: when the link stays very bad even after the normal
+ * adaptive steps, stop all camera video (both ways) so audio gets the whole
+ * link. Comes back after a long good stretch; every fallback within a few
+ * minutes of the last one doubles the wait (up to 4×), so it doesn't flap.
+ */
+export interface FallbackState {
+    active: boolean;
+    bad: number;
+    good: number;
+    /** How many times we fell back recently (sets the recovery wait). */
+    strikes: number;
+    /** When the last fallback ended (ms), for the strike decay. */
+    lastRecoveredAt: number;
+}
+export declare const initialFallbackState: () => FallbackState;
+export declare const FALLBACK: {
+    /** Loss (either way) that counts as severe. */
+    severeLoss: number;
+    /** RTT (s) that counts as severe. */
+    severeRtt: number;
+    /** Upload estimate (bits/s) that counts as severe. */
+    severeBitrate: number;
+    /** Severe samples in a row before falling back (~6 s at 2 s per sample). */
+    samplesToFallback: number;
+    /** Good samples in a row before trying video again (~30 s), × 2^strikes. */
+    samplesToRecover: number;
+    maxStrikes: number;
+    /** A fallback this long after the last recovery starts the count again. */
+    strikeResetMs: number;
+    /** Mic cap while fallen back (Opus stays clear at 24 kbit/s and leaves room on a weak link). */
+    audioBitrate: number;
+};
+/** Mic bitrate cap (0 = none): the data saver's, tightened while fallen back to audio. */
+export declare function micBitrateCap(saverCap: number, fallbackActive: boolean, t?: {
+    /** Loss (either way) that counts as severe. */
+    severeLoss: number;
+    /** RTT (s) that counts as severe. */
+    severeRtt: number;
+    /** Upload estimate (bits/s) that counts as severe. */
+    severeBitrate: number;
+    /** Severe samples in a row before falling back (~6 s at 2 s per sample). */
+    samplesToFallback: number;
+    /** Good samples in a row before trying video again (~30 s), × 2^strikes. */
+    samplesToRecover: number;
+    maxStrikes: number;
+    /** A fallback this long after the last recovery starts the count again. */
+    strikeResetMs: number;
+    /** Mic cap while fallen back (Opus stays clear at 24 kbit/s and leaves room on a weak link). */
+    audioBitrate: number;
+}): number;
+/** Severe: lossy or slow enough that even audio suffers. */
+export declare function isSevere(s: LinkSample, t?: {
+    /** Loss (either way) that counts as severe. */
+    severeLoss: number;
+    /** RTT (s) that counts as severe. */
+    severeRtt: number;
+    /** Upload estimate (bits/s) that counts as severe. */
+    severeBitrate: number;
+    /** Severe samples in a row before falling back (~6 s at 2 s per sample). */
+    samplesToFallback: number;
+    /** Good samples in a row before trying video again (~30 s), × 2^strikes. */
+    samplesToRecover: number;
+    maxStrikes: number;
+    /** A fallback this long after the last recovery starts the count again. */
+    strikeResetMs: number;
+    /** Mic cap while fallen back (Opus stays clear at 24 kbit/s and leaves room on a weak link). */
+    audioBitrate: number;
+}): boolean;
+/**
+ * Good enough to try video again: little loss either way and short round
+ * trips. The browser's upload estimate is ignored here: with audio alone it
+ * doesn't probe for more, so it stays as low as it fell (seen in tests: it
+ * never recovers on its own). If the upload really is still too small, video
+ * coming back pushes the link into trouble again and the next fallback waits
+ * twice as long.
+ */
+export declare function isClear(s: LinkSample, t?: {
+    recvBadLoss: number;
+    recvGoodLoss: number;
+    badRtt: number;
+    goodRtt: number;
+    sendBadBitrate: number;
+    sendGoodBitrate: number;
+    sendBadLoss: number;
+    samplesToDegrade: number;
+    samplesToRecover: number;
+}): boolean;
+/**
+ * Next fallback state. `adaptive` is the normal adaptive state after this
+ * sample: once it has already paused video both ways and the link is still
+ * not clear, that also counts toward falling back.
+ */
+export declare function nextFallbackState(prev: FallbackState, s: LinkSample, adaptive: AdaptiveState, now: number, t?: {
+    /** Loss (either way) that counts as severe. */
+    severeLoss: number;
+    /** RTT (s) that counts as severe. */
+    severeRtt: number;
+    /** Upload estimate (bits/s) that counts as severe. */
+    severeBitrate: number;
+    /** Severe samples in a row before falling back (~6 s at 2 s per sample). */
+    samplesToFallback: number;
+    /** Good samples in a row before trying video again (~30 s), × 2^strikes. */
+    samplesToRecover: number;
+    maxStrikes: number;
+    /** A fallback this long after the last recovery starts the count again. */
+    strikeResetMs: number;
+    /** Mic cap while fallen back (Opus stays clear at 24 kbit/s and leaves room on a weak link). */
+    audioBitrate: number;
+}): FallbackState;
+export interface SaverSendSettings {
+    maxSendHeight: number;
+    maxSendBitrate: number;
+    maxSendFramerate: number;
+}
+/**
+ * Camera send encodings and the layers to announce, for a data-saver setting.
+ * With simulcast, the transceiver keeps its three RIDs (they can't change
+ * after negotiation): only the best layer that fits `maxSendHeight` stays
+ * active, capped. Without simulcast, the one encoding is scaled and capped.
+ * `captureHeight` is the camera's actual height (for the non-simulcast scale).
+ */
+export declare function cameraEncodings(simulcast: boolean, saver: SaverSendSettings | null, sending: boolean, captureHeight?: number, 
+/** RIDs the sender actually has (browsers drop layers for small cameras). Default all three. */
+available?: readonly VideoLayer[]): {
+    encodings: RTCRtpEncodingParameters[];
+    layers: VideoLayer[];
+};
+/**
+ * Apply planned encodings onto a sender's current ones (matched by RID when
+ * simulcast, else the first). Returns null when nothing would change. The
+ * number and RIDs of encodings can't change after negotiation, so this keeps
+ * whatever the browser negotiated and only sets active / caps / scale.
+ */
+export declare function mergeEncodings(current: RTCRtpEncodingParameters[], planned: RTCRtpEncodingParameters[]): RTCRtpEncodingParameters[] | null;
+/**
+ * Who you receive camera video from when it's limited to recent speakers:
+ * `recent` is remote ids, most recent speaker first; `present` is everyone
+ * there in join order (fills the slots before anyone has spoken); spotlighted
+ * ids always count. Returns null when there is no limit.
+ */
+export declare function videoAllowList(count: number, recent: readonly string[], present: readonly string[], always?: readonly string[]): Set<string> | null;
+/** Bytes on the wire so far in this media connection (RTP + RTCP + ICE, from getStats). */
+export interface ByteTotals {
+    sent: number;
+    received: number;
+}
+export declare function bytesFromStats(report: RTCStatsReport): ByteTotals | null;
+export interface UsageMeter {
+    usage: DataUsage;
+    last: ByteTotals | null;
+    lastAt: number;
+    /** Recent (time, totalBytes) points for the per-hour rate. */
+    window: Array<[number, number]>;
+}
+export declare const initialUsageMeter: (now: number) => UsageMeter;
+/**
+ * Add a reading. Counters restart when the media connection is rebuilt
+ * (reconnect): a total lower than the last one is taken as all new.
+ */
+export declare function nextUsage(m: UsageMeter, totals: ByteTotals, now: number, windowMs?: number): UsageMeter;

package/dist/adaptive.js

@@ -0,0 +1,389 @@
+/** Simulcast encodings for camera video. RIDs sort in quality order (see VideoLayer). */
+export const CAMERA_SIMULCAST = [
+    { rid: "f", maxBitrate: 1_200_000, maxFramerate: 30 },
+    { rid: "h", maxBitrate: 450_000, maxFramerate: 30, scaleResolutionDownBy: 2 },
+    { rid: "q", maxBitrate: 150_000, maxFramerate: 15, scaleResolutionDownBy: 4 },
+];
+export const CAMERA_LAYERS = ["f", "h", "q"];
+/** Camera capture size when simulcast is on, so the layers are 720p / 360p / 180p. */
+export const CAMERA_CONSTRAINTS = {
+    width: { ideal: 1280 },
+    height: { ideal: 720 },
+    frameRate: { ideal: 30 },
+};
+const ORDER = ["off", "low", "medium", "high"];
+export const rank = (q) => ORDER.indexOf(q);
+export const minQuality = (a, b) => (rank(a) <= rank(b) ? a : b);
+const stepDown = (q) => ORDER[Math.max(0, rank(q) - 1)];
+const stepUp = (q) => ORDER[Math.min(ORDER.length - 1, rank(q) + 1)];
+/** Which quality a <video> of this rendered height (CSS px × devicePixelRatio) needs. */
+export function qualityForHeight(pixels) {
+    if (pixels <= 0)
+        return "low";
+    if (pixels > 400)
+        return "high";
+    if (pixels > 200)
+        return "medium";
+    return "low";
+}
+export const initialAdaptiveState = () => ({
+    receiveCap: "high",
+    sendVideo: true,
+    badRecv: 0,
+    goodRecv: 0,
+    badSend: 0,
+    goodSend: 0,
+});
+/** Tuning. Samples are ~2s apart, so 3 samples ≈ 6s, 5 ≈ 10s. */
+export const ADAPTIVE = {
+    recvBadLoss: 0.08,
+    recvGoodLoss: 0.02,
+    badRtt: 0.8,
+    goodRtt: 0.35,
+    sendBadBitrate: 120_000,
+    sendGoodBitrate: 350_000,
+    sendBadLoss: 0.15,
+    samplesToDegrade: 3,
+    samplesToRecover: 5,
+};
+/**
+ * Next adaptive state. Degrades one step at a time after sustained trouble and
+ * recovers one step at a time after a longer stretch of good samples (hysteresis,
+ * so it doesn't flap).
+ */
+export function nextAdaptiveState(prev, s, t = ADAPTIVE) {
+    const st = { ...prev };
+    const rttBad = s.rtt !== undefined && s.rtt > t.badRtt;
+    const rttGood = s.rtt === undefined || s.rtt < t.goodRtt;
+    // Receiving
+    if (s.inboundLoss > t.recvBadLoss || rttBad) {
+        st.badRecv++;
+        st.goodRecv = 0;
+    }
+    else if (s.inboundLoss < t.recvGoodLoss && rttGood) {
+        st.goodRecv++;
+        st.badRecv = 0;
+    }
+    else {
+        st.badRecv = 0;
+        st.goodRecv = 0;
+    }
+    if (st.badRecv >= t.samplesToDegrade && st.receiveCap !== "off") {
+        st.receiveCap = stepDown(st.receiveCap);
+        st.badRecv = 0;
+    }
+    else if (st.goodRecv >= t.samplesToRecover && st.receiveCap !== "high") {
+        st.receiveCap = stepUp(st.receiveCap);
+        st.goodRecv = 0;
+    }
+    // Sending
+    const bitrate = s.availableOutgoingBitrate;
+    const sendBad = (bitrate !== undefined && bitrate < t.sendBadBitrate) || (s.outboundLoss !== undefined && s.outboundLoss > t.sendBadLoss);
+    const sendGood = (bitrate === undefined || bitrate > t.sendGoodBitrate) && (s.outboundLoss === undefined || s.outboundLoss < t.recvGoodLoss * 2);
+    if (sendBad) {
+        st.badSend++;
+        st.goodSend = 0;
+    }
+    else if (sendGood) {
+        st.goodSend++;
+        st.badSend = 0;
+    }
+    else {
+        st.badSend = 0;
+        st.goodSend = 0;
+    }
+    if (st.sendVideo && st.badSend >= t.samplesToDegrade) {
+        st.sendVideo = false;
+        st.badSend = 0;
+    }
+    else if (!st.sendVideo && st.goodSend >= t.samplesToRecover) {
+        st.sendVideo = true;
+        st.goodSend = 0;
+    }
+    return st;
+}
+/**
+ * Rate a link for the UI. Loss is the stronger signal (it's what people hear and
+ * see); RTT adds delay/echo. Thresholds roughly follow common WebRTC MOS buckets.
+ */
+export function connectionQualityFromSample(s) {
+    const loss = Math.max(s.inboundLoss, s.outboundLoss ?? 0);
+    const rtt = s.rtt ?? 0;
+    if (loss > 0.1 || rtt > 0.8)
+        return "poor";
+    if (loss > 0.03 || rtt > 0.3)
+        return "good";
+    return "excellent";
+}
+/**
+ * Turns an RTCStatsReport into a LinkSample. `cursor` holds the previous totals;
+ * the function returns the new totals alongside the sample.
+ */
+export function sampleFromStats(report, cursor) {
+    let inLost = 0;
+    let inReceived = 0;
+    let rtt;
+    let bitrate;
+    let outLossSum = 0;
+    let outLossN = 0;
+    const outReports = {};
+    report.forEach((r) => {
+        if (r.type === "inbound-rtp") {
+            inLost += Math.max(0, r.packetsLost ?? 0);
+            inReceived += r.packetsReceived ?? 0;
+        }
+        else if (r.type === "remote-inbound-rtp" && typeof r.fractionLost === "number") {
+            // A paused sender (e.g. camera layers off in a fallback) gets no new
+            // receiver reports, so its last fractionLost stays frozen: skip reports
+            // that haven't changed since the previous sample.
+            const key = String(r.id ?? r.ssrc ?? "");
+            const marker = r.roundTripTimeMeasurements ?? r.timestamp;
+            if (typeof marker === "number")
+                outReports[key] = marker;
+            const stale = typeof marker === "number" && cursor?.outReports?.[key] === marker;
+            if (!stale) {
+                outLossSum += r.fractionLost;
+                outLossN++;
+            }
+        }
+        else if (r.type === "candidate-pair" && r.nominated && r.state === "succeeded") {
+            if (typeof r.currentRoundTripTime === "number")
+                rtt = r.currentRoundTripTime;
+            if (typeof r.availableOutgoingBitrate === "number")
+                bitrate = r.availableOutgoingBitrate;
+        }
+    });
+    const dLost = cursor ? inLost - cursor.inLost : 0;
+    const dRecv = cursor ? inReceived - cursor.inReceived : 0;
+    const total = dLost + dRecv;
+    return {
+        sample: {
+            inboundLoss: total > 0 ? Math.max(0, dLost) / total : 0,
+            outboundLoss: outLossN ? outLossSum / outLossN : undefined,
+            rtt,
+            availableOutgoingBitrate: bitrate,
+        },
+        cursor: { inLost, inReceived, outReports },
+    };
+}
+export const initialFallbackState = () => ({ active: false, bad: 0, good: 0, strikes: 0, lastRecoveredAt: 0 });
+export const FALLBACK = {
+    /** Loss (either way) that counts as severe. */
+    severeLoss: 0.15,
+    /** RTT (s) that counts as severe. */
+    severeRtt: 1.0,
+    /** Upload estimate (bits/s) that counts as severe. */
+    severeBitrate: 80_000,
+    /** Severe samples in a row before falling back (~6 s at 2 s per sample). */
+    samplesToFallback: 3,
+    /** Good samples in a row before trying video again (~30 s), × 2^strikes. */
+    samplesToRecover: 15,
+    maxStrikes: 2,
+    /** A fallback this long after the last recovery starts the count again. */
+    strikeResetMs: 5 * 60_000,
+    /** Mic cap while fallen back (Opus stays clear at 24 kbit/s and leaves room on a weak link). */
+    audioBitrate: 24_000,
+};
+/** Mic bitrate cap (0 = none): the data saver's, tightened while fallen back to audio. */
+export function micBitrateCap(saverCap, fallbackActive, t = FALLBACK) {
+    if (!fallbackActive)
+        return saverCap;
+    return saverCap > 0 ? Math.min(saverCap, t.audioBitrate) : t.audioBitrate;
+}
+/** Severe: lossy or slow enough that even audio suffers. */
+export function isSevere(s, t = FALLBACK) {
+    return (s.inboundLoss > t.severeLoss ||
+        (s.outboundLoss ?? 0) > t.severeLoss ||
+        (s.rtt ?? 0) > t.severeRtt ||
+        (s.availableOutgoingBitrate !== undefined && s.availableOutgoingBitrate < t.severeBitrate));
+}
+/**
+ * Good enough to try video again: little loss either way and short round
+ * trips. The browser's upload estimate is ignored here: with audio alone it
+ * doesn't probe for more, so it stays as low as it fell (seen in tests: it
+ * never recovers on its own). If the upload really is still too small, video
+ * coming back pushes the link into trouble again and the next fallback waits
+ * twice as long.
+ */
+export function isClear(s, t = ADAPTIVE) {
+    return s.inboundLoss < t.recvGoodLoss && (s.outboundLoss ?? 0) < t.recvGoodLoss * 2 && (s.rtt === undefined || s.rtt < t.goodRtt);
+}
+/**
+ * Next fallback state. `adaptive` is the normal adaptive state after this
+ * sample: once it has already paused video both ways and the link is still
+ * not clear, that also counts toward falling back.
+ */
+export function nextFallbackState(prev, s, adaptive, now, t = FALLBACK) {
+    const st = { ...prev };
+    if (!st.active) {
+        const exhausted = adaptive.receiveCap === "off" && !adaptive.sendVideo && !isClear(s);
+        if (isSevere(s, t) || exhausted)
+            st.bad++;
+        else
+            st.bad = 0;
+        if (st.bad >= t.samplesToFallback) {
+            const recent = st.lastRecoveredAt > 0 && now - st.lastRecoveredAt <= t.strikeResetMs;
+            st.strikes = recent ? Math.min(t.maxStrikes, st.strikes + 1) : 0;
+            st.active = true;
+            st.bad = 0;
+            st.good = 0;
+        }
+        return st;
+    }
+    if (isClear(s))
+        st.good++;
+    else
+        st.good = 0;
+    if (st.good >= t.samplesToRecover * 2 ** st.strikes) {
+        st.active = false;
+        st.good = 0;
+        st.lastRecoveredAt = now;
+    }
+    return st;
+}
+// ---------------- data saver: sending ----------------
+/** Camera layers with their output heights when capturing 720p. */
+const LAYER_HEIGHTS = { f: 720, h: 360, q: 180 };
+/**
+ * Camera send encodings and the layers to announce, for a data-saver setting.
+ * With simulcast, the transceiver keeps its three RIDs (they can't change
+ * after negotiation): only the best layer that fits `maxSendHeight` stays
+ * active, capped. Without simulcast, the one encoding is scaled and capped.
+ * `captureHeight` is the camera's actual height (for the non-simulcast scale).
+ */
+export function cameraEncodings(simulcast, saver, sending, captureHeight = 720, 
+/** RIDs the sender actually has (browsers drop layers for small cameras). Default all three. */
+available = CAMERA_LAYERS) {
+    const limited = saver && (saver.maxSendHeight < 720 || saver.maxSendBitrate > 0 || saver.maxSendFramerate > 0);
+    if (!simulcast) {
+        const e = { active: sending };
+        if (limited) {
+            if (saver.maxSendHeight > 0 && captureHeight > saver.maxSendHeight)
+                e.scaleResolutionDownBy = captureHeight / saver.maxSendHeight;
+            if (saver.maxSendBitrate > 0)
+                e.maxBitrate = saver.maxSendBitrate;
+            if (saver.maxSendFramerate > 0)
+                e.maxFramerate = saver.maxSendFramerate;
+        }
+        return { encodings: [e], layers: [] };
+    }
+    const have = CAMERA_LAYERS.filter((l) => available.includes(l));
+    if (!limited)
+        return { encodings: CAMERA_SIMULCAST.map((e) => ({ ...e, active: sending })), layers: have };
+    const keep = have.find((l) => LAYER_HEIGHTS[l] <= Math.max(saver.maxSendHeight, 180)) ?? have[have.length - 1] ?? "q";
+    const encodings = CAMERA_SIMULCAST.map((e) => {
+        if (e.rid !== keep)
+            return { ...e, active: false };
+        const out = { ...e, active: sending };
+        if (saver.maxSendBitrate > 0)
+            out.maxBitrate = Math.min(e.maxBitrate ?? Infinity, saver.maxSendBitrate);
+        if (saver.maxSendFramerate > 0)
+            out.maxFramerate = Math.min(e.maxFramerate ?? Infinity, saver.maxSendFramerate);
+        return out;
+    });
+    return { encodings, layers: [keep] };
+}
+/**
+ * Apply planned encodings onto a sender's current ones (matched by RID when
+ * simulcast, else the first). Returns null when nothing would change. The
+ * number and RIDs of encodings can't change after negotiation, so this keeps
+ * whatever the browser negotiated and only sets active / caps / scale.
+ */
+export function mergeEncodings(current, planned) {
+    let changed = false;
+    const keys = ["active", "maxBitrate", "maxFramerate", "scaleResolutionDownBy"];
+    const out = current.map((e, i) => {
+        const want = (e.rid ? planned.find((p) => p.rid === e.rid) : planned[0]) ?? planned[i] ?? planned[0] ?? {};
+        const next = { ...e };
+        for (const k of keys) {
+            const v = k === "active" ? (want.active ?? true) : want[k];
+            if (v === undefined) {
+                if (k === "scaleResolutionDownBy" && e.rid)
+                    continue; // keep the layer's size
+                if (next[k] !== undefined) {
+                    delete next[k];
+                    changed = true;
+                }
+            }
+            else if (next[k] !== v) {
+                next[k] = v;
+                changed = true;
+            }
+        }
+        return next;
+    });
+    return changed ? out : null;
+}
+// ---------------- data saver: receiving ----------------
+/**
+ * Who you receive camera video from when it's limited to recent speakers:
+ * `recent` is remote ids, most recent speaker first; `present` is everyone
+ * there in join order (fills the slots before anyone has spoken); spotlighted
+ * ids always count. Returns null when there is no limit.
+ */
+export function videoAllowList(count, recent, present, always = []) {
+    if (count <= 0 || present.length <= count)
+        return null;
+    const out = new Set(always.filter((id) => present.includes(id)));
+    const pick = [];
+    for (const id of [...recent, ...present]) {
+        if (pick.length >= count)
+            break;
+        if (present.includes(id) && !pick.includes(id))
+            pick.push(id);
+    }
+    for (const id of pick)
+        out.add(id);
+    return out;
+}
+export function bytesFromStats(report) {
+    let transport = null;
+    let pair = null;
+    report.forEach((r) => {
+        if (r.type === "transport" && typeof r.bytesSent === "number") {
+            transport = { sent: (transport?.sent ?? 0) + r.bytesSent, received: (transport?.received ?? 0) + (r.bytesReceived ?? 0) };
+        }
+        else if (r.type === "candidate-pair" && r.nominated && typeof r.bytesSent === "number") {
+            pair = { sent: (pair?.sent ?? 0) + r.bytesSent, received: (pair?.received ?? 0) + (r.bytesReceived ?? 0) };
+        }
+    });
+    return transport ?? pair;
+}
+export const initialUsageMeter = (now) => ({
+    usage: { sentBytes: 0, receivedBytes: 0, totalBytes: 0, sendBitrate: 0, receiveBitrate: 0, mbPerHour: 0, since: now },
+    last: null,
+    lastAt: now,
+    window: [[now, 0]],
+});
+/**
+ * Add a reading. Counters restart when the media connection is rebuilt
+ * (reconnect): a total lower than the last one is taken as all new.
+ */
+export function nextUsage(m, totals, now, windowMs = 30_000) {
+    const dSent = m.last && totals.sent >= m.last.sent ? totals.sent - m.last.sent : totals.sent;
+    const dRecv = m.last && totals.received >= m.last.received ? totals.received - m.last.received : totals.received;
+    const secs = Math.max(0.001, (now - m.lastAt) / 1000);
+    const sentBytes = m.usage.sentBytes + dSent;
+    const receivedBytes = m.usage.receivedBytes + dRecv;
+    const totalBytes = sentBytes + receivedBytes;
+    const window = [...m.window, [now, totalBytes]].filter(([t], i, a) => i === a.length - 1 || now - t <= windowMs);
+    if (window.length === 1)
+        window.unshift(m.window[m.window.length - 1]);
+    const [t0, b0] = window[0];
+    const rate = now > t0 ? ((totalBytes - b0) / ((now - t0) / 1000)) * 3600 / 1e6 : 0;
+    return {
+        usage: {
+            sentBytes,
+            receivedBytes,
+            totalBytes,
+            sendBitrate: m.last ? Math.round((dSent * 8) / secs) : 0,
+            receiveBitrate: m.last ? Math.round((dRecv * 8) / secs) : 0,
+            mbPerHour: Math.round(rate * 10) / 10,
+            since: m.usage.since,
+        },
+        last: totals,
+        lastAt: now,
+        window,
+    };
+}
+//# sourceMappingURL=adaptive.js.map