@voltkit-rtc/client 0.7.3 → 0.8.0

package/dist/cjs/fallback.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AudioProtection = exports.RELAPSE_MS = exports.MAX_HOLD_MS = exports.FIRST_HOLD_MS = exports.MIN_RECOVER_PACKETS = exports.MIN_PACKETS = exports.RECOVER_SAMPLES = exports.FALLBACK_SAMPLES = exports.RECOVER_LOSS = exports.FALLBACK_LOSS = exports.PROTECT_SAMPLE_MS = void 0;
+exports.readInboundAudio = readInboundAudio;
+exports.readOutboundAudio = readOutboundAudio;
+/** How often the received audio is sampled while the fallback could be needed. */
+exports.PROTECT_SAMPLE_MS = 3000;
+/** This share of the audio lost (RTP sequence gaps) over the window: fall back. */
+exports.FALLBACK_LOSS = 0.25;
+/** Below this share lost over the recovery window: video may come back. */
+exports.RECOVER_LOSS = 0.05;
+/** Samples judged for falling back (15 s at 3 s) -- at least 3 of them. */
+exports.FALLBACK_SAMPLES = 5;
+/** Samples judged for coming back (12 s). */
+exports.RECOVER_SAMPLES = 4;
+/** Fewer audio packets than this over the fallback window are too few to judge. */
+exports.MIN_PACKETS = 150;
+/** Fewer than this over the recovery window: nobody spoke enough to tell. */
+exports.MIN_RECOVER_PACKETS = 30;
+/** The first fallback lasts at least this long. */
+exports.FIRST_HOLD_MS = 20_000;
+/** A relapse doubles the hold, up to this. */
+exports.MAX_HOLD_MS = 160_000;
+/** Falling back again within this long of coming back is a relapse. */
+exports.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. */
+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.
+ */
+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. */
+class AudioProtection {
+    onChange;
+    now;
+    samples = [];
+    previous = null;
+    activeSince = null;
+    hold = exports.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(exports.FALLBACK_SAMPLES, exports.RECOVER_SAMPLES))
+            this.samples.shift();
+        if (this.activeSince === null) {
+            const window = this.samples.slice(-exports.FALLBACK_SAMPLES);
+            if (window.length < 3)
+                return;
+            const { total, lost } = sum(window);
+            if (total >= exports.MIN_PACKETS && lost / total >= exports.FALLBACK_LOSS)
+                this.activate();
+            return;
+        }
+        if (this.now() - this.activeSince < this.hold || this.samples.length < exports.RECOVER_SAMPLES)
+            return;
+        const { total, lost } = sum(this.samples.slice(-exports.RECOVER_SAMPLES));
+        if (total < exports.MIN_RECOVER_PACKETS || lost / total < exports.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 < exports.RELAPSE_MS;
+        this.hold = relapse ? Math.min(this.hold * 2, exports.MAX_HOLD_MS) : exports.FIRST_HOLD_MS;
+        this.activeSince = now;
+        this.samples = [];
+        this.onChange(true);
+    }
+    recover() {
+        this.activeSince = null;
+        this.recoveredAt = this.now();
+        this.samples = [];
+        this.onChange(false);
+    }
+}
+exports.AudioProtection = AudioProtection;
+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/cjs/fallback.js.map

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

package/dist/cjs/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/cjs/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/cjs/health.js

@@ -0,0 +1,116 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HealthDecisions = exports.INTERRUPTED_AFTER_MS = exports.RECOVER_SAMPLES = exports.RECOVERED_FPS = exports.LOW_FPS_SAMPLES = exports.LOW_FPS = exports.SILENCE_LEVEL = exports.SILENT_SAMPLES = exports.HEALTH_SAMPLE_MS = void 0;
+exports.readMediaSource = readMediaSource;
+/** How often the published camera and microphone are sampled while someone listens. */
+exports.HEALTH_SAMPLE_MS = 2000;
+/** Samples of exact silence before mic-silent (6 s). */
+exports.SILENT_SAMPLES = 3;
+/** Below this the level counts as exact digital silence (a real room's noise floor is well above it). */
+exports.SILENCE_LEVEL = 0.0001;
+/** Fewer frames than this per second, when 24 or more were asked, is camera-fps-low. */
+exports.LOW_FPS = 15;
+/** Samples below LOW_FPS before warning (6 s); samples at RECOVERED_FPS or more before clearing. */
+exports.LOW_FPS_SAMPLES = 3;
+exports.RECOVERED_FPS = 20;
+exports.RECOVER_SAMPLES = 2;
+/** A system mute shorter than this is a glitch, not an interruption. */
+exports.INTERRUPTED_AFTER_MS = 2000;
+/** Decides mic-silent and camera-fps-low from samples. */
+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 <= exports.SILENCE_LEVEL) {
+            this.silent += 1;
+            if (this.silent >= exports.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 < exports.LOW_FPS) {
+            this.goodFps = 0;
+            this.lowFps += 1;
+            if (this.lowFps >= exports.LOW_FPS_SAMPLES)
+                this.set('camera-fps-low', true);
+        }
+        else {
+            this.lowFps = 0;
+            if (sample.cameraFps >= exports.RECOVERED_FPS)
+                this.goodFps += 1;
+            if (this.goodFps >= exports.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 });
+    }
+}
+exports.HealthDecisions = HealthDecisions;
+/** The microphone level and camera frame rate from a producer's statistics (media-source). */
+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/cjs/health.js.map

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