@voltkit-rtc/client 0.7.3 → 0.8.0

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":"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"}