@voltkit-rtc/client 0.7.2 → 0.8.0

package/dist/esm/devices.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/** The browser's device list, optionally of one kind. Empty outside a browser. */
+export 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. */
+export 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.
+ */
+export 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). */
+export function deviceIdOf(track) {
+    const id = track?.getSettings?.().deviceId;
+    return typeof id === 'string' && id.length > 0 ? id : null;
+}
+//# sourceMappingURL=devices.js.map

package/dist/esm/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.js","sourceRoot":"","sources":["../../src/devices.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH,kFAAkF;AAClF,MAAM,CAAC,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,MAAM,UAAU,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,MAAM,UAAU,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,MAAM,UAAU,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/esm/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/esm/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/esm/diagnostics.js

@@ -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 const SDK_VERSION = '0.8.0';
+/** How many recent events the log keeps. */
+export const 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. */
+export 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 > DIAGNOSTICS_LOG_SIZE)
+            this.entries.shift();
+    }
+    list() {
+        return this.entries.map((e) => ({ ...e }));
+    }
+}
+//# sourceMappingURL=diagnostics.js.map

package/dist/esm/diagnostics.js.map

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

package/dist/esm/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/esm/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"}

package/dist/esm/fallback.js

@@ -0,0 +1,142 @@
+/** How often the received audio is sampled while the fallback could be needed. */
+export const PROTECT_SAMPLE_MS = 3000;
+/** This share of the audio lost (RTP sequence gaps) over the window: fall back. */
+export const FALLBACK_LOSS = 0.25;
+/** Below this share lost over the recovery window: video may come back. */
+export const RECOVER_LOSS = 0.05;
+/** Samples judged for falling back (15 s at 3 s) -- at least 3 of them. */
+export const FALLBACK_SAMPLES = 5;
+/** Samples judged for coming back (12 s). */
+export const RECOVER_SAMPLES = 4;
+/** Fewer audio packets than this over the fallback window are too few to judge. */
+export const MIN_PACKETS = 150;
+/** Fewer than this over the recovery window: nobody spoke enough to tell. */
+export const MIN_RECOVER_PACKETS = 30;
+/** The first fallback lasts at least this long. */
+export const FIRST_HOLD_MS = 20_000;
+/** A relapse doubles the hold, up to this. */
+export const MAX_HOLD_MS = 160_000;
+/** Falling back again within this long of coming back is a relapse. */
+export const RELAPSE_MS = 120_000;
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+/** The received-audio counters of a receive transport's report, summed over its audio streams. */
+export function readInboundAudio(report) {
+    let received = 0;
+    let lost = 0;
+    for (const e of report) {
+        if (typeof e !== 'object' || e === null || e.type !== 'inbound-rtp')
+            continue;
+        if (e.kind !== 'audio' && e.mediaType !== 'audio')
+            continue;
+        received += num(e.packetsReceived);
+        lost += Math.max(0, num(e.packetsLost));
+    }
+    return { received, lost };
+}
+/**
+ * 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 function readOutboundAudio(report) {
+    let sent = 0;
+    let lost = 0;
+    for (const e of report) {
+        if (typeof e !== 'object' || e === null)
+            continue;
+        const audio = e.kind === 'audio' || e.mediaType === 'audio';
+        if (!audio)
+            continue;
+        if (e.type === 'outbound-rtp')
+            sent += num(e.packetsSent);
+        else if (e.type === 'remote-inbound-rtp')
+            lost += Math.max(0, num(e.packetsLost));
+    }
+    return { received: Math.max(0, sent - lost), lost };
+}
+/** Decides when to fall back to audio only and when video may come back. */
+export class AudioProtection {
+    onChange;
+    now;
+    samples = [];
+    previous = null;
+    activeSince = null;
+    hold = FIRST_HOLD_MS;
+    recoveredAt = null;
+    constructor(onChange, now = Date.now) {
+        this.onChange = onChange;
+        this.now = now;
+    }
+    /** Whether remote camera videos are held back now. */
+    get active() {
+        return this.activeSince !== null;
+    }
+    /** How long the current (or next first) fallback holds, in ms. */
+    get holdMs() {
+        return this.hold;
+    }
+    /**
+     * 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) {
+        const before = this.previous;
+        this.previous = counters;
+        if (before === null || counters.received < before.received || counters.lost < before.lost) {
+            this.samples = [];
+            return;
+        }
+        this.samples.push({ received: counters.received - before.received, lost: counters.lost - before.lost });
+        if (this.samples.length > Math.max(FALLBACK_SAMPLES, RECOVER_SAMPLES))
+            this.samples.shift();
+        if (this.activeSince === null) {
+            const window = this.samples.slice(-FALLBACK_SAMPLES);
+            if (window.length < 3)
+                return;
+            const { total, lost } = sum(window);
+            if (total >= MIN_PACKETS && lost / total >= FALLBACK_LOSS)
+                this.activate();
+            return;
+        }
+        if (this.now() - this.activeSince < this.hold || this.samples.length < RECOVER_SAMPLES)
+            return;
+        const { total, lost } = sum(this.samples.slice(-RECOVER_SAMPLES));
+        if (total < MIN_RECOVER_PACKETS || lost / total < RECOVER_LOSS)
+            this.recover();
+    }
+    /** Come back now (the app turned the fallback off). */
+    release() {
+        if (this.activeSince !== null)
+            this.recover();
+    }
+    /** The transports went away (reconnect, close): forget everything, without telling. */
+    reset() {
+        this.activeSince = null;
+        this.samples = [];
+        this.previous = null;
+    }
+    activate() {
+        const now = this.now();
+        const relapse = this.recoveredAt !== null && now - this.recoveredAt < RELAPSE_MS;
+        this.hold = relapse ? Math.min(this.hold * 2, MAX_HOLD_MS) : FIRST_HOLD_MS;
+        this.activeSince = now;
+        this.samples = [];
+        this.onChange(true);
+    }
+    recover() {
+        this.activeSince = null;
+        this.recoveredAt = this.now();
+        this.samples = [];
+        this.onChange(false);
+    }
+}
+function sum(samples) {
+    let total = 0;
+    let lost = 0;
+    for (const s of samples) {
+        total += s.received + s.lost;
+        lost += s.lost;
+    }
+    return { total, lost };
+}
+//# sourceMappingURL=fallback.js.map

package/dist/esm/fallback.js.map

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

package/dist/esm/health.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Media health warnings (docs/implementation-progress/RTC_PERF_PROGRESS.md K1).
+ *
+ * - Agora's `exception` event pairs each problem with its recovery: FRAMERATE_INPUT_TOO_LOW / _RECOVER (the camera
+ *   delivers too few frames), AUDIO_INPUT_LEVEL_TOO_LOW / _RECOVER, ...
+ * - LiveKit's `AudioSilenceDetected`: a microphone that delivers nothing but silence (a hardware mute switch, a
+ *   broken device) right after it starts.
+ * - LiveKit watches the track's `mute` event (the OS took the device: a phone call, another app) and reacts after 5 s.
+ *
+ * Each warning is reported once when it starts (`active: true`) and once when it clears (`active: false`).
+ * Pure: the decisions take samples.
+ */
+export type MediaWarningCode = 
+/** The microphone is on but delivers exact digital silence: a mute switch, a broken or wrongly chosen device. */
+'mic-silent'
+/** The camera delivers far fewer frames than asked: usually a dark room (the camera exposes longer), or a busy device. */
+ | 'camera-fps-low'
+/** The system took the camera from this page for now (a phone call, another app, a locked screen). */
+ | 'camera-interrupted'
+/** The system took the microphone (a phone call, another app). */
+ | 'mic-interrupted';
+export interface MediaWarning {
+    code: MediaWarningCode;
+    /** true when it starts, false when it clears. */
+    active: boolean;
+}
+/** How often the published camera and microphone are sampled while someone listens. */
+export declare const HEALTH_SAMPLE_MS = 2000;
+/** Samples of exact silence before mic-silent (6 s). */
+export declare const SILENT_SAMPLES = 3;
+/** Below this the level counts as exact digital silence (a real room's noise floor is well above it). */
+export declare const SILENCE_LEVEL = 0.0001;
+/** Fewer frames than this per second, when 24 or more were asked, is camera-fps-low. */
+export declare const LOW_FPS = 15;
+/** Samples below LOW_FPS before warning (6 s); samples at RECOVERED_FPS or more before clearing. */
+export declare const LOW_FPS_SAMPLES = 3;
+export declare const RECOVERED_FPS = 20;
+export declare const RECOVER_SAMPLES = 2;
+/** A system mute shorter than this is a glitch, not an interruption. */
+export declare const INTERRUPTED_AFTER_MS = 2000;
+/** One reading of the published devices. null: not published (or nothing measured). */
+export interface HealthSample {
+    /** The microphone's level, while it is on. */
+    micLevel: number | null;
+    /** The frames per second the camera delivers, while it is on, and what was asked. */
+    cameraFps: number | null;
+    askedFps: number;
+}
+/** Decides mic-silent and camera-fps-low from samples. */
+export declare class HealthDecisions {
+    private readonly report;
+    private silent;
+    private lowFps;
+    private goodFps;
+    private readonly activeNow;
+    constructor(report: (warning: MediaWarning) => void);
+    isActive(code: MediaWarningCode): boolean;
+    feed(sample: HealthSample): void;
+    /** A system interruption started or ended (decided by the caller's timer). */
+    interrupted(code: 'camera-interrupted' | 'mic-interrupted', active: boolean): void;
+    /** Everything clears (unpublished, closed): each active warning is reported cleared. */
+    clearAll(): void;
+    private set;
+}
+/** The microphone level and camera frame rate from a producer's statistics (media-source). */
+export declare function readMediaSource(report: Iterable<Record<string, unknown>>): {
+    level: number | null;
+    fps: number | null;
+};
+//# sourceMappingURL=health.d.ts.map

package/dist/esm/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,MAAM,gBAAgB;AAC1B,iHAAiH;AAC/G,YAAY;AACd,0HAA0H;GACxH,gBAAgB;AAClB,sGAAsG;GACpG,oBAAoB;AACtB,kEAAkE;GAChE,iBAAiB,CAAC;AAEtB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,OAAO,CAAC;AACrC,wDAAwD;AACxD,eAAO,MAAM,cAAc,IAAI,CAAC;AAChC,yGAAyG;AACzG,eAAO,MAAM,aAAa,SAAS,CAAC;AACpC,wFAAwF;AACxF,eAAO,MAAM,OAAO,KAAK,CAAC;AAC1B,oGAAoG;AACpG,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,aAAa,KAAK,CAAC;AAChC,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,wEAAwE;AACxE,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,uFAAuF;AACvF,MAAM,WAAW,YAAY;IAC3B,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0DAA0D;AAC1D,qBAAa,eAAe;IAMd,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+B;gBAE5B,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,IAAI;IAEpE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO;IAIzC,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IA6BhC,8EAA8E;IAC9E,WAAW,CAAC,IAAI,EAAE,oBAAoB,GAAG,iBAAiB,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAIlF,wFAAwF;IACxF,QAAQ,IAAI,IAAI;IAOhB,OAAO,CAAC,GAAG;CAMZ;AAED,8FAA8F;AAC9F,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CASvH"}

package/dist/esm/health.js

@@ -0,0 +1,111 @@
+/**
+ * Media health warnings (docs/implementation-progress/RTC_PERF_PROGRESS.md K1).
+ *
+ * - Agora's `exception` event pairs each problem with its recovery: FRAMERATE_INPUT_TOO_LOW / _RECOVER (the camera
+ *   delivers too few frames), AUDIO_INPUT_LEVEL_TOO_LOW / _RECOVER, ...
+ * - LiveKit's `AudioSilenceDetected`: a microphone that delivers nothing but silence (a hardware mute switch, a
+ *   broken device) right after it starts.
+ * - LiveKit watches the track's `mute` event (the OS took the device: a phone call, another app) and reacts after 5 s.
+ *
+ * Each warning is reported once when it starts (`active: true`) and once when it clears (`active: false`).
+ * Pure: the decisions take samples.
+ */
+/** How often the published camera and microphone are sampled while someone listens. */
+export const HEALTH_SAMPLE_MS = 2000;
+/** Samples of exact silence before mic-silent (6 s). */
+export const SILENT_SAMPLES = 3;
+/** Below this the level counts as exact digital silence (a real room's noise floor is well above it). */
+export const SILENCE_LEVEL = 0.0001;
+/** Fewer frames than this per second, when 24 or more were asked, is camera-fps-low. */
+export const LOW_FPS = 15;
+/** Samples below LOW_FPS before warning (6 s); samples at RECOVERED_FPS or more before clearing. */
+export const LOW_FPS_SAMPLES = 3;
+export const RECOVERED_FPS = 20;
+export const RECOVER_SAMPLES = 2;
+/** A system mute shorter than this is a glitch, not an interruption. */
+export const INTERRUPTED_AFTER_MS = 2000;
+/** Decides mic-silent and camera-fps-low from samples. */
+export class HealthDecisions {
+    report;
+    silent = 0;
+    lowFps = 0;
+    goodFps = 0;
+    activeNow = new Set();
+    constructor(report) {
+        this.report = report;
+    }
+    isActive(code) {
+        return this.activeNow.has(code);
+    }
+    feed(sample) {
+        // mic-silent: exact silence held; any sound clears it. Off or unpublished: not a warning.
+        if (sample.micLevel === null) {
+            this.silent = 0;
+            this.set('mic-silent', false);
+        }
+        else if (sample.micLevel <= SILENCE_LEVEL) {
+            this.silent += 1;
+            if (this.silent >= SILENT_SAMPLES)
+                this.set('mic-silent', true);
+        }
+        else {
+            this.silent = 0;
+            this.set('mic-silent', false);
+        }
+        // camera-fps-low: only when a smooth rate was asked; cleared once it holds again.
+        if (sample.cameraFps === null || sample.askedFps < 24) {
+            this.lowFps = 0;
+            this.goodFps = 0;
+            this.set('camera-fps-low', false);
+        }
+        else if (sample.cameraFps < LOW_FPS) {
+            this.goodFps = 0;
+            this.lowFps += 1;
+            if (this.lowFps >= LOW_FPS_SAMPLES)
+                this.set('camera-fps-low', true);
+        }
+        else {
+            this.lowFps = 0;
+            if (sample.cameraFps >= RECOVERED_FPS)
+                this.goodFps += 1;
+            if (this.goodFps >= RECOVER_SAMPLES)
+                this.set('camera-fps-low', false);
+        }
+    }
+    /** A system interruption started or ended (decided by the caller's timer). */
+    interrupted(code, active) {
+        this.set(code, active);
+    }
+    /** Everything clears (unpublished, closed): each active warning is reported cleared. */
+    clearAll() {
+        for (const code of [...this.activeNow])
+            this.set(code, false);
+        this.silent = 0;
+        this.lowFps = 0;
+        this.goodFps = 0;
+    }
+    set(code, active) {
+        if (this.activeNow.has(code) === active)
+            return;
+        if (active)
+            this.activeNow.add(code);
+        else
+            this.activeNow.delete(code);
+        this.report({ code, active });
+    }
+}
+/** The microphone level and camera frame rate from a producer's statistics (media-source). */
+export function readMediaSource(report) {
+    let level = null;
+    let fps = null;
+    for (const s of report) {
+        if (s.type !== 'media-source')
+            continue;
+        if (typeof s.audioLevel === 'number')
+            level = s.audioLevel;
+        if (typeof s.framesPerSecond === 'number')
+            fps = s.framesPerSecond;
+    }
+    return { level, fps };
+}
+//# sourceMappingURL=health.js.map

package/dist/esm/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","sourceRoot":"","sources":["../../src/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkBH,uFAAuF;AACvF,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,wDAAwD;AACxD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAChC,yGAAyG;AACzG,MAAM,CAAC,MAAM,aAAa,GAAG,MAAM,CAAC;AACpC,wFAAwF;AACxF,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,CAAC;AAC1B,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,CAAC;AAChC,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,CAAC;AACjC,wEAAwE;AACxE,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAWzC,0DAA0D;AAC1D,MAAM,OAAO,eAAe;IAMG;IALrB,MAAM,GAAG,CAAC,CAAC;IACX,MAAM,GAAG,CAAC,CAAC;IACX,OAAO,GAAG,CAAC,CAAC;IACH,SAAS,GAAG,IAAI,GAAG,EAAoB,CAAC;IAEzD,YAA6B,MAAuC;QAAvC,WAAM,GAAN,MAAM,CAAiC;IAAG,CAAC;IAExE,QAAQ,CAAC,IAAsB;QAC7B,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,IAAI,CAAC,MAAoB;QACvB,0FAA0F;QAC1F,IAAI,MAAM,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC7B,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;aAAM,IAAI,MAAM,CAAC,QAAQ,IAAI,aAAa,EAAE,CAAC;YAC5C,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,IAAI,IAAI,CAAC,MAAM,IAAI,cAAc;gBAAE,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;QAClE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAChB,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QAChC,CAAC;QAED,kFAAkF;QAClF,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI,IAAI,MAAM,CAAC,QAAQ,GAAG,EAAE,EAAE,CAAC;YACtD,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAChB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC;aAAM,IAAI,MAAM,CAAC,SAAS,GAAG,OAAO,EAAE,CAAC;YACtC,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;YACjB,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACjB,IAAI,IAAI,CAAC,MAAM,IAAI,eAAe;gBAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,CAAC,CAAC;QACvE,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;YAChB,IAAI,MAAM,CAAC,SAAS,IAAI,aAAa;gBAAE,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC;YACzD,IAAI,IAAI,CAAC,OAAO,IAAI,eAAe;gBAAE,IAAI,CAAC,GAAG,CAAC,gBAAgB,EAAE,KAAK,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,WAAW,CAAC,IAA8C,EAAE,MAAe;QACzE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACzB,CAAC;IAED,wFAAwF;IACxF,QAAQ;QACN,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QAC9D,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;QAChB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;IAEO,GAAG,CAAC,IAAsB,EAAE,MAAe;QACjD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,MAAM;YAAE,OAAO;QAChD,IAAI,MAAM;YAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;;YAChC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,CAAC;CACF;AAED,8FAA8F;AAC9F,MAAM,UAAU,eAAe,CAAC,MAAyC;IACvE,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,GAAG,GAAkB,IAAI,CAAC;IAC9B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc;YAAE,SAAS;QACxC,IAAI,OAAO,CAAC,CAAC,UAAU,KAAK,QAAQ;YAAE,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC;QAC3D,IAAI,OAAO,CAAC,CAAC,eAAe,KAAK,QAAQ;YAAE,GAAG,GAAG,CAAC,CAAC,eAAe,CAAC;IACrE,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AACxB,CAAC"}