@voltkit-rtc/client 0.7.3 → 0.8.0

package/dist/cjs/link.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * Keeping the connection alive between drops (docs/implementation-progress/RTC_PERF_PROGRESS.md G1, G2).
+ *
+ * Two failures the socket's own close never reports:
+ *
+ * - **The media path dies while the socket lives** (Wi-Fi to mobile data, a NAT rebinding, UDP blocked mid-call).
+ *   The video freezes for good. Twilio and LiveKit restart ICE on the same transports first -- new ICE credentials
+ *   from the server, the same producers and consumers -- and rejoin only when that does not bring the path back.
+ *   {@link MediaPathWatch} does the same: a transport `disconnected` for {@link DISCONNECTED_GRACE_MS} or `failed`
+ *   restarts ICE; not `connected` within {@link RESTART_TIMEOUT_MS} of starting recovery (including the request), or a server without `restartIce`, is a
+ *   full reconnect.
+ * - **The socket dies silently**: the network went away and TCP has not noticed yet, which can take minutes. The
+ *   server pings, but a browser cannot see those. LiveKit pings from the client and reconnects when no pong comes.
+ *   {@link SocketLiveness} sends `ping` after {@link IDLE_MS} with nothing received, and calls the socket dead when
+ *   nothing at all arrives within {@link PING_TIMEOUT_MS} of it. Any frame counts, so an older server's
+ *   `unknown-method` reply proves the socket as well as a pong.
+ *
+ * Pure: timers and the clock are injectable, so the decisions are unit-tested on their own.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SocketLiveness = exports.MediaPathWatch = exports.LIVENESS_TICK_MS = exports.PING_TIMEOUT_MS = exports.IDLE_MS = exports.RESTART_TIMEOUT_MS = exports.DISCONNECTED_GRACE_MS = void 0;
+/** A transport `disconnected` this long is restarted (it often recovers by itself within a second or two). */
+exports.DISCONNECTED_GRACE_MS = 3000;
+/** The whole ICE recovery, including the request, has this long before the session rejoins. */
+exports.RESTART_TIMEOUT_MS = 10_000;
+/** With nothing received for this long, the client pings. */
+exports.IDLE_MS = 15_000;
+/** A ping with nothing at all received for this long after it: the socket is dead. */
+exports.PING_TIMEOUT_MS = 8000;
+/** How often liveness is checked. Background tabs may run it less often; the decisions use the clock, not counts. */
+exports.LIVENESS_TICK_MS = 5000;
+/** Watches each media transport's connection state and recovers a dead path. */
+class MediaPathWatch {
+    host;
+    entries = new Map();
+    setTimer;
+    clearTimer;
+    constructor(host) {
+        this.host = host;
+        this.setTimer = host.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = host.clearTimer ?? ((h) => clearTimeout(h));
+    }
+    /** A transport's connection state changed (mediasoup-client `connectionstatechange`). */
+    update(transportId, state) {
+        let entry = this.entries.get(transportId);
+        if (!entry) {
+            entry = { state, timer: null, restarting: false, lost: false, revision: 0 };
+            this.entries.set(transportId, entry);
+        }
+        entry.state = state;
+        switch (state) {
+            case 'connected':
+                entry.revision++;
+                this.cancel(entry);
+                entry.restarting = false;
+                this.setLost(transportId, entry, false);
+                return;
+            case 'closed':
+                this.forget(transportId);
+                return;
+            case 'disconnected':
+                // A restart is already waiting for `connected`; its own deadline decides.
+                if (entry.restarting || entry.timer !== null)
+                    return;
+                entry.timer = this.setTimer(() => {
+                    entry.timer = null;
+                    if (entry.state === 'disconnected' || entry.state === 'failed')
+                        void this.restart(transportId, entry);
+                }, exports.DISCONNECTED_GRACE_MS);
+                return;
+            case 'failed':
+                if (entry.restarting)
+                    return; // duplicate notification; the deadline decides
+                this.cancel(entry);
+                void this.restart(transportId, entry);
+                return;
+            default:
+                // new / connecting: a fresh transport, or one mid-restart.
+                return;
+        }
+    }
+    /** The transport went away with its session (teardown): no more decisions for it. */
+    forget(transportId) {
+        const entry = this.entries.get(transportId);
+        if (!entry)
+            return;
+        this.cancel(entry);
+        this.entries.delete(transportId);
+        if (entry.lost)
+            this.host.onPathChange?.(transportId, false);
+    }
+    /** Every transport went away (teardown, close). */
+    reset() {
+        for (const id of [...this.entries.keys()])
+            this.forget(id);
+    }
+    /** For tests and the network-change nudge: is this transport being recovered now? */
+    restartingNow(transportId) {
+        return this.entries.get(transportId)?.restarting === true;
+    }
+    async restart(transportId, entry) {
+        if (!this.host.active() || this.entries.get(transportId) !== entry)
+            return;
+        entry.restarting = true;
+        const revision = ++entry.revision;
+        // Include both the RPC and the platform call in the deadline: neither is
+        // guaranteed to settle when a network/interface disappears.
+        this.cancel(entry);
+        entry.timer = this.setTimer(() => {
+            entry.timer = null;
+            if (!entry.restarting || this.entries.get(transportId) !== entry)
+                return;
+            entry.revision++;
+            entry.restarting = false;
+            if (this.host.active())
+                this.host.reconnect('media-timeout');
+        }, exports.RESTART_TIMEOUT_MS);
+        this.setLost(transportId, entry, true);
+        let outcome;
+        try {
+            outcome = await this.host.restartIce(transportId);
+        }
+        catch {
+            outcome = 'unsupported';
+        }
+        if (this.entries.get(transportId) !== entry || entry.revision !== revision)
+            return;
+        if (outcome === 'skipped') {
+            this.cancel(entry);
+            entry.restarting = false;
+            return;
+        }
+        if (outcome === 'unsupported') {
+            this.cancel(entry);
+            entry.restarting = false;
+            if (this.host.active())
+                this.host.reconnect('media-failed');
+            return;
+        }
+        // `connected` clears the deadline, including when it arrives during the await.
+    }
+    setLost(transportId, entry, lost) {
+        if (entry.lost === lost)
+            return;
+        entry.lost = lost;
+        this.host.onPathChange?.(transportId, lost);
+    }
+    cancel(entry) {
+        if (entry.timer !== null)
+            this.clearTimer(entry.timer);
+        entry.timer = null;
+    }
+}
+exports.MediaPathWatch = MediaPathWatch;
+/** Notices a socket that died without closing. */
+class SocketLiveness {
+    host;
+    lastReceived = 0;
+    pingSentAt = null;
+    timer = null;
+    now;
+    constructor(host) {
+        this.host = host;
+        this.now = host.now ?? Date.now;
+    }
+    /** Start watching a newly opened socket. */
+    start() {
+        this.stop();
+        this.lastReceived = this.now();
+        this.pingSentAt = null;
+        const every = this.host.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+        this.timer = every(() => this.check(), exports.LIVENESS_TICK_MS);
+        // A Node/SSR process with no other work need not stay alive for a browser
+        // connection watch. Browser timers are numbers and have no unref.
+        this.timer?.unref?.();
+    }
+    stop() {
+        if (this.timer !== null)
+            (this.host.clearInterval ?? ((h) => clearInterval(h)))(this.timer);
+        this.timer = null;
+        this.pingSentAt = null;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Any frame arrived on the socket. */
+    received() {
+        this.lastReceived = this.now();
+        this.pingSentAt = null;
+    }
+    /** Check now instead of at the next tick (the browser said the network changed). */
+    checkNow() {
+        if (this.timer === null || !this.host.active())
+            return;
+        if (this.pingSentAt === null) {
+            this.pingSentAt = this.now();
+            this.host.ping();
+        }
+    }
+    check() {
+        if (this.timer === null || !this.host.active())
+            return;
+        const now = this.now();
+        if (this.pingSentAt !== null) {
+            if (now - this.pingSentAt >= exports.PING_TIMEOUT_MS) {
+                this.stop();
+                this.host.dead();
+            }
+            return;
+        }
+        if (now - this.lastReceived >= exports.IDLE_MS) {
+            this.pingSentAt = now;
+            this.host.ping();
+        }
+    }
+}
+exports.SocketLiveness = SocketLiveness;
+//# sourceMappingURL=link.js.map

package/dist/cjs/link.js.map

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

package/dist/cjs/preflight.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pre-call check (docs/implementation-progress/RTC_PERF_PROGRESS.md L1).
+ *
+ * - Twilio's `runPreflight` (read from its code) joins a test room, publishes synthetic audio and video and reports
+ *   timings, the connection path, round trip, jitter and loss.
+ * - LiveKit's `ConnectionCheck` runs separate checks -- WebSocket, WebRTC, TURN, publishing audio and video, UDP
+ *   against TCP -- each with messages and warnings.
+ * - Agora's `startLastmileProbeTest` measures the last mile before a call.
+ *
+ * This joins the room the token names (mint one for a test room nobody else is in: the session is real, and billed
+ * like any other for its few seconds), publishes what it is given -- or a tone and a picture it makes -- and reports
+ * what it saw. The orchestration takes a small target interface, so it is tested without a browser.
+ */
+import { type NetworkQualityLevel } from './network.js';
+import type { StatsEntry } from './stats.js';
+import type { MediaWarningCode } from './health.js';
+export interface PreflightOptions {
+    /** What to publish (cloned; your tracks are left running). Without it, a tone and a moving picture are made. */
+    media?: MediaStream;
+    /** How long media is measured once it flows. Default 5 s. */
+    durationMs?: number;
+}
+export type PreflightStepName = 'join' | 'media';
+export interface PreflightStep {
+    name: PreflightStepName;
+    ok: boolean;
+    /** How long it took, in ms. */
+    ms: number | null;
+    error?: string;
+}
+export interface PreflightReport {
+    /** Joined, and media reached the server. */
+    ok: boolean;
+    steps: PreflightStep[];
+    /** How media travelled: UDP is best; TCP or a relay means a firewall in the way (it works, with more delay). */
+    path: {
+        protocol: 'udp' | 'tcp' | null;
+        relayed: boolean;
+    } | null;
+    rttMs: number | null;
+    lossPct: number | null;
+    /** The upload the browser estimated it could use, in kbps. */
+    uploadKbps: number | null;
+    level: NetworkQualityLevel | null;
+    /** Camera and microphone problems seen during the test (see the mediaWarning event). */
+    warnings: MediaWarningCode[];
+}
+/** What a pre-call check needs from a client. */
+export interface PreflightTarget {
+    connect(): Promise<unknown>;
+    publish(stream: MediaStream): Promise<void>;
+    /** The send transport's connection state, or null before there is one. */
+    sendState(): string | null;
+    /** The send transport's statistics, or null without one. */
+    sendStats(): Promise<Iterable<StatsEntry> | null>;
+    onWarning(listener: (code: MediaWarningCode, active: boolean) => void): () => void;
+    close(): void;
+}
+export interface PreflightEnv {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** Media has this long to connect once published. */
+export declare const MEDIA_CONNECT_TIMEOUT_MS = 10000;
+/** Statistics are read this often while measuring. */
+export declare const PREFLIGHT_SAMPLE_MS = 1000;
+/** The selected candidate pair's protocol, and whether either end is a relay. */
+export declare function connectionPath(report: Iterable<StatsEntry>): PreflightReport['path'];
+/** Run the check on `target`, closing it at the end whatever happens. */
+export declare function runPreflight(target: PreflightTarget, stream: MediaStream, options?: PreflightOptions, env?: PreflightEnv): Promise<PreflightReport>;
+/**
+ * A tone and a moving picture to publish when the app gives none (Twilio's preflight makes synthetic media too).
+ * Returns the stream and a function that stops everything it made. Browser only.
+ */
+export declare function syntheticMedia(): {
+    stream: MediaStream;
+    stop: () => void;
+};
+//# sourceMappingURL=preflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAwC,KAAK,mBAAmB,EAAwB,MAAM,cAAc,CAAC;AACpH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,gHAAgH;IAChH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,+BAA+B;IAC/B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,gHAAgH;IAChH,IAAI,EAAE;QAAE,QAAQ,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAClC,wFAAwF;IACxF,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,0EAA0E;IAC1E,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnF,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAID,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAgBpF;AAED,yEAAyE;AACzE,wBAAsB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,EAAE,GAAG,GAAE,YAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsDtK;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAqC1E"}

package/dist/cjs/preflight.js

@@ -0,0 +1,159 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PREFLIGHT_SAMPLE_MS = exports.MEDIA_CONNECT_TIMEOUT_MS = void 0;
+exports.connectionPath = connectionPath;
+exports.runPreflight = runPreflight;
+exports.syntheticMedia = syntheticMedia;
+/**
+ * Pre-call check (docs/implementation-progress/RTC_PERF_PROGRESS.md L1).
+ *
+ * - Twilio's `runPreflight` (read from its code) joins a test room, publishes synthetic audio and video and reports
+ *   timings, the connection path, round trip, jitter and loss.
+ * - LiveKit's `ConnectionCheck` runs separate checks -- WebSocket, WebRTC, TURN, publishing audio and video, UDP
+ *   against TCP -- each with messages and warnings.
+ * - Agora's `startLastmileProbeTest` measures the last mile before a call.
+ *
+ * This joins the room the token names (mint one for a test room nobody else is in: the session is real, and billed
+ * like any other for its few seconds), publishes what it is given -- or a tone and a picture it makes -- and reports
+ * what it saw. The orchestration takes a small target interface, so it is tested without a browser.
+ */
+const network_js_1 = require("./network.js");
+const realEnv = { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
+/** Media has this long to connect once published. */
+exports.MEDIA_CONNECT_TIMEOUT_MS = 10_000;
+/** Statistics are read this often while measuring. */
+exports.PREFLIGHT_SAMPLE_MS = 1000;
+/** The selected candidate pair's protocol, and whether either end is a relay. */
+function connectionPath(report) {
+    const entries = [...report];
+    const byId = new Map();
+    for (const e of entries)
+        if (typeof e.id === 'string')
+            byId.set(e.id, e);
+    let pair;
+    for (const t of entries.filter((e) => e.type === 'transport')) {
+        if (typeof t.selectedCandidatePairId === 'string')
+            pair = byId.get(t.selectedCandidatePairId);
+        if (pair)
+            break;
+    }
+    pair ??= entries.find((e) => e.type === 'candidate-pair' && e.nominated === true && e.state === 'succeeded');
+    if (!pair)
+        return null;
+    const local = typeof pair.localCandidateId === 'string' ? byId.get(pair.localCandidateId) : undefined;
+    const remote = typeof pair.remoteCandidateId === 'string' ? byId.get(pair.remoteCandidateId) : undefined;
+    const protocol = local?.protocol === 'udp' || local?.protocol === 'tcp' ? local.protocol : null;
+    const relayed = local?.candidateType === 'relay' || remote?.candidateType === 'relay';
+    return { protocol, relayed };
+}
+/** Run the check on `target`, closing it at the end whatever happens. */
+async function runPreflight(target, stream, options = {}, env = realEnv) {
+    const report = { ok: false, steps: [], path: null, rttMs: null, lossPct: null, uploadKbps: null, level: null, warnings: [] };
+    const seen = new Set();
+    const stopWarnings = target.onWarning((code, active) => { if (active)
+        seen.add(code); });
+    try {
+        let started = env.now();
+        try {
+            await target.connect();
+            report.steps.push({ name: 'join', ok: true, ms: env.now() - started });
+        }
+        catch (err) {
+            report.steps.push({ name: 'join', ok: false, ms: null, error: String(err?.message ?? err) });
+            return report;
+        }
+        started = env.now();
+        try {
+            await target.publish(stream);
+            while (target.sendState() !== 'connected') {
+                const state = target.sendState();
+                if (state === 'failed' || state === 'closed')
+                    throw new Error(`media connection ${state}`);
+                if (env.now() - started > exports.MEDIA_CONNECT_TIMEOUT_MS)
+                    throw new Error('media did not connect in time (a firewall blocking UDP and TCP?)');
+                await env.sleep(100);
+            }
+            report.steps.push({ name: 'media', ok: true, ms: env.now() - started });
+        }
+        catch (err) {
+            report.steps.push({ name: 'media', ok: false, ms: null, error: String(err?.message ?? err) });
+            return report;
+        }
+        // Measure: the worst round trip and loss over the run, the last upload estimate.
+        const duration = options.durationMs ?? 5000;
+        let previous = new Map();
+        const until = env.now() + duration;
+        while (env.now() < until) {
+            await env.sleep(exports.PREFLIGHT_SAMPLE_MS);
+            const stats = await target.sendStats().catch(() => null);
+            if (!stats)
+                continue;
+            const entries = [...stats];
+            report.path = connectionPath(entries) ?? report.path;
+            const now = new Map([['send', (0, network_js_1.readTransportStats)(entries)]]);
+            const q = (0, network_js_1.networkQualityOf)(now, previous, true);
+            previous = now;
+            if (q.rttMs !== null)
+                report.rttMs = Math.max(report.rttMs ?? 0, q.rttMs);
+            if (q.lossPct !== null)
+                report.lossPct = Math.max(report.lossPct ?? 0, q.lossPct);
+            if (q.availableKbps !== null)
+                report.uploadKbps = q.availableKbps;
+            report.level = q.level;
+        }
+        report.ok = true;
+        return report;
+    }
+    finally {
+        report.warnings = [...seen];
+        stopWarnings();
+        target.close();
+    }
+}
+/**
+ * A tone and a moving picture to publish when the app gives none (Twilio's preflight makes synthetic media too).
+ * Returns the stream and a function that stops everything it made. Browser only.
+ */
+function syntheticMedia() {
+    const tracks = [];
+    const stops = [];
+    const AudioCtx = globalThis.AudioContext;
+    if (AudioCtx) {
+        const ctx = new AudioCtx();
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        gain.gain.value = 0.05;
+        const dest = ctx.createMediaStreamDestination();
+        osc.connect(gain).connect(dest);
+        osc.start();
+        tracks.push(...dest.stream.getAudioTracks());
+        stops.push(() => { osc.stop(); void ctx.close(); });
+    }
+    if (typeof document !== 'undefined') {
+        const canvas = document.createElement('canvas');
+        canvas.width = 640;
+        canvas.height = 360;
+        const g = canvas.getContext('2d');
+        let frame = 0;
+        const draw = () => {
+            if (!g)
+                return;
+            frame += 1;
+            g.fillStyle = `hsl(${frame % 360}, 60%, 40%)`;
+            g.fillRect(0, 0, canvas.width, canvas.height);
+            g.fillStyle = '#fff';
+            g.fillRect((frame * 8) % canvas.width, 150, 60, 60);
+        };
+        draw();
+        const timer = setInterval(draw, 1000 / 30);
+        const captured = canvas.captureStream?.(30);
+        if (captured)
+            tracks.push(...captured.getVideoTracks());
+        stops.push(() => clearInterval(timer));
+    }
+    const stream = new MediaStream(tracks);
+    return { stream, stop: () => { for (const t of tracks)
+            t.stop(); for (const s of stops)
+            s(); } };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/cjs/preflight.js.map

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

package/dist/cjs/speakers.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Audio levels and active speakers (docs/implementation-progress/RTC_PERF_PROGRESS.md J1).
+ *
+ * - Agora `volume-indicator` and Tencent TRTC `AUDIO_VOLUME` report every participant's volume on an interval.
+ * - Amazon Chime's `DefaultActiveSpeakerPolicy` (read from its code) ranks speakers: a volume above a silence
+ *   threshold counts as speaking (1, else 0); each sample the speaker's score becomes `score × 0.9 + speaking × 0.1`,
+ *   and everyone else's drops by `0.2 × speaking` (the takeover); scores under 0.01 are 0. Its detector updates every
+ *   200 ms. Sampled together here, so two people speaking at once both stay; the takeover applies to the silent.
+ * - LiveKit's server counts a participant as speaking above -35 dBov.
+ *
+ * Levels are WebRTC's `audioLevel`: linear, 0 = silence, 1 = 0 dBov. -35 dBov is 10^(-35/20) ≈ 0.0178.
+ * Pure: the ranking takes levels and gives the order.
+ */
+/** Above this level a participant is speaking (LiveKit's -35 dBov). */
+export declare const SPEAKING_LEVEL = 0.0178;
+/** How often levels are read while someone listens (Chime's detector: 200 ms). */
+export declare const AUDIO_LEVEL_INTERVAL_MS = 250;
+export declare const SPEAKER_WEIGHT = 0.9;
+export declare const TAKEOVER_RATE = 0.2;
+export declare const SCORE_CUTOFF = 0.01;
+/** Chime's active speaker ranking: who has been speaking recently, the most recent and steady first. */
+export declare class ActiveSpeakers {
+    private readonly scores;
+    private last;
+    /**
+     * One sample: each identity's loudest level now (0..1). Identities missing from it count as silent. Returns the new
+     * order when it changed, else null.
+     */
+    update(levels: ReadonlyMap<string, number>): string[] | null;
+    /** Someone left: forget them. Returns the new order when it changed. */
+    remove(identity: string): string[] | null;
+    reset(): void;
+}
+//# sourceMappingURL=speakers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"speakers.d.ts","sourceRoot":"","sources":["../../src/speakers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,uEAAuE;AACvE,eAAO,MAAM,cAAc,SAAS,CAAC;AACrC,kFAAkF;AAClF,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,eAAO,MAAM,cAAc,MAAM,CAAC;AAClC,eAAO,MAAM,aAAa,MAAM,CAAC;AACjC,eAAO,MAAM,YAAY,OAAO,CAAC;AAEjC,wGAAwG;AACxG,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,IAAI,CAAgB;IAE5B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI;IAoB5D,wEAAwE;IACxE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAQzC,KAAK,IAAI,IAAI;CAId"}

package/dist/cjs/speakers.js

@@ -0,0 +1,71 @@
+"use strict";
+/**
+ * Audio levels and active speakers (docs/implementation-progress/RTC_PERF_PROGRESS.md J1).
+ *
+ * - Agora `volume-indicator` and Tencent TRTC `AUDIO_VOLUME` report every participant's volume on an interval.
+ * - Amazon Chime's `DefaultActiveSpeakerPolicy` (read from its code) ranks speakers: a volume above a silence
+ *   threshold counts as speaking (1, else 0); each sample the speaker's score becomes `score × 0.9 + speaking × 0.1`,
+ *   and everyone else's drops by `0.2 × speaking` (the takeover); scores under 0.01 are 0. Its detector updates every
+ *   200 ms. Sampled together here, so two people speaking at once both stay; the takeover applies to the silent.
+ * - LiveKit's server counts a participant as speaking above -35 dBov.
+ *
+ * Levels are WebRTC's `audioLevel`: linear, 0 = silence, 1 = 0 dBov. -35 dBov is 10^(-35/20) ≈ 0.0178.
+ * Pure: the ranking takes levels and gives the order.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ActiveSpeakers = exports.SCORE_CUTOFF = exports.TAKEOVER_RATE = exports.SPEAKER_WEIGHT = exports.AUDIO_LEVEL_INTERVAL_MS = exports.SPEAKING_LEVEL = void 0;
+/** Above this level a participant is speaking (LiveKit's -35 dBov). */
+exports.SPEAKING_LEVEL = 0.0178;
+/** How often levels are read while someone listens (Chime's detector: 200 ms). */
+exports.AUDIO_LEVEL_INTERVAL_MS = 250;
+exports.SPEAKER_WEIGHT = 0.9;
+exports.TAKEOVER_RATE = 0.2;
+exports.SCORE_CUTOFF = 0.01;
+/** Chime's active speaker ranking: who has been speaking recently, the most recent and steady first. */
+class ActiveSpeakers {
+    scores = new Map();
+    last = [];
+    /**
+     * One sample: each identity's loudest level now (0..1). Identities missing from it count as silent. Returns the new
+     * order when it changed, else null.
+     */
+    update(levels) {
+        for (const id of levels.keys())
+            if (!this.scores.has(id))
+                this.scores.set(id, 0);
+        // Chime updates one attendee at a time as volumes arrive; here everyone is sampled together, so people speaking
+        // at the same moment do not take over from each other -- only the silent ones lose ground.
+        const speakingNow = new Set([...levels].filter(([, level]) => level > exports.SPEAKING_LEVEL).map(([id]) => id));
+        for (const id of this.scores.keys()) {
+            const speaking = speakingNow.has(id) ? 1 : 0;
+            let score = (this.scores.get(id) ?? 0) * exports.SPEAKER_WEIGHT + speaking * (1 - exports.SPEAKER_WEIGHT);
+            if (!speaking && speakingNow.size > 0)
+                score = Math.max(score - exports.TAKEOVER_RATE, 0);
+            this.scores.set(id, score);
+        }
+        const order = [...this.scores.entries()]
+            .filter(([, score]) => score >= exports.SCORE_CUTOFF)
+            .sort((a, b) => b[1] - a[1] || (a[0] < b[0] ? -1 : 1))
+            .map(([id]) => id);
+        if (order.length === this.last.length && order.every((id, i) => id === this.last[i]))
+            return null;
+        this.last = order;
+        return order;
+    }
+    /** Someone left: forget them. Returns the new order when it changed. */
+    remove(identity) {
+        if (!this.scores.delete(identity))
+            return null;
+        const order = this.last.filter((id) => id !== identity);
+        if (order.length === this.last.length)
+            return null;
+        this.last = order;
+        return order;
+    }
+    reset() {
+        this.scores.clear();
+        this.last = [];
+    }
+}
+exports.ActiveSpeakers = ActiveSpeakers;
+//# sourceMappingURL=speakers.js.map

package/dist/cjs/speakers.js.map

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