@voltkit-rtc/client 0.7.3 → 0.9.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,8GAA8G;AAC9G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAC1C,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,QAAS,CAAC;AACzC,6DAA6D;AAC7D,eAAO,MAAM,OAAO,QAAS,CAAC;AAC9B,sFAAsF;AACtF,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,qHAAqH;AACrH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvG,mCAAmC;AACnC,MAAM,MAAM,cAAc;AACxB,qDAAqD;AACnD,WAAW;AACb,4EAA4E;GAC1E,aAAa;AACf,iHAAiH;GAC/G,SAAS,CAAC;AAEd,MAAM,WAAW,aAAa;IAC5B,mHAAmH;IACnH,MAAM,IAAI,OAAO,CAAC;IAClB,gFAAgF;IAChF,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACzD,6CAA6C;IAC7C,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,yGAAyG;IACzG,YAAY,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IACxD,QAAQ,CAAC,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC/C,UAAU,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC;AAWD,gFAAgF;AAChF,qBAAa,cAAc;IAKb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA4B;gBAE1B,IAAI,EAAE,aAAa;IAKhD,yFAAyF;IACzF,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI;IAoCxD,qFAAqF;IACrF,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAQjC,mDAAmD;IACnD,KAAK,IAAI,IAAI;IAIb,qFAAqF;IACrF,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;YAI7B,OAAO;IAoCrB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,MAAM;CAIf;AAED,MAAM,WAAW,YAAY;IAC3B,mFAAmF;IACnF,MAAM,IAAI,OAAO,CAAC;IAClB,sGAAsG;IACtG,IAAI,IAAI,IAAI,CAAC;IACb,wEAAwE;IACxE,IAAI,IAAI,IAAI,CAAC;IACb,GAAG,CAAC,IAAI,MAAM,CAAC;IACf,WAAW,CAAC,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAClD,aAAa,CAAC,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAAC;CACvC;AAED,kDAAkD;AAClD,qBAAa,cAAc;IAMb,OAAO,CAAC,QAAQ,CAAC,IAAI;IALjC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEN,IAAI,EAAE,YAAY;IAI/C,4CAA4C;IAC5C,KAAK,IAAI,IAAI;IAWb,IAAI,IAAI,IAAI;IAMZ,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,uCAAuC;IACvC,QAAQ,IAAI,IAAI;IAKhB,oFAAoF;IACpF,QAAQ,IAAI,IAAI;IAQhB,KAAK,IAAI,IAAI;CAed"}

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/noise-suppression.d.ts

@@ -0,0 +1,44 @@
+/**
+ * AI noise suppression for the microphone (docs/implementation-progress/RTC_PERF_PROGRESS.md P3-4): what Agora's AI
+ * Denoiser, LiveKit's Krisp filter and ZEGOCLOUD's AI noise suppression do, with RNNoise -- the open neural-network
+ * denoiser Jitsi uses -- through `@sapphi-red/web-noise-suppressor` (MIT): a Web Audio worklet in the browser's
+ * audio thread. Fans, traffic and room rumble fall away (measured in Chromium: rumble-like noise down by more than
+ * 60 dB, steady white hiss by 7-12 dB); voices stay.
+ *
+ * Imported on its own (`@voltkit-rtc/client/noise-suppression`), so an app that does not use it never ships it:
+ *
+ *   import { createNoiseSuppressor } from '@voltkit-rtc/client/noise-suppression';
+ *   await client.setAudioProcessor(createNoiseSuppressor());
+ *
+ * The worklet (64 kB) and the model (150 kB) are fetched when it starts: from jsDelivr, at the exact version this
+ * SDK was tested with, unless you serve them yourself (`workletUrl`, `wasmUrl`, `simdWasmUrl`) -- copy them from
+ * `node_modules/@sapphi-red/web-noise-suppressor/dist` to your own site for a strict Content-Security-Policy.
+ */
+import type { AudioTrackProcessor } from './processors.js';
+/** The package version the default URLs point at; equal to this SDK's pinned dependency (a test checks it). */
+export declare const NOISE_SUPPRESSOR_VERSION = "0.4.1";
+export interface NoiseSuppressorOptions {
+    /** Where `rnnoise/workletProcessor.js` is served. Default: jsDelivr, pinned. */
+    workletUrl?: string;
+    /** Where `rnnoise.wasm` is served. Default: jsDelivr, pinned. */
+    wasmUrl?: string;
+    /** Where `rnnoise_simd.wasm` is served (used where the browser supports SIMD). Default: jsDelivr, pinned. */
+    simdWasmUrl?: string;
+}
+/** What the processor needs from the browser; stood in for by tests. */
+export interface NoiseSuppressorDeps {
+    createContext(): AudioContext;
+    loadModel(urls: {
+        url: string;
+        simdUrl: string;
+    }): Promise<ArrayBuffer>;
+    createNode(context: AudioContext, wasmBinary: ArrayBuffer): Promise<DenoiseNode> | DenoiseNode;
+    createStream(tracks: MediaStreamTrack[]): MediaStream;
+}
+type DenoiseNode = AudioNode & {
+    destroy?(): void;
+};
+/** An `AudioTrackProcessor` for `client.setAudioProcessor()` that removes background noise with RNNoise. */
+export declare function createNoiseSuppressor(options?: NoiseSuppressorOptions, deps?: NoiseSuppressorDeps): AudioTrackProcessor;
+export {};
+//# sourceMappingURL=noise-suppression.d.ts.map

package/dist/cjs/noise-suppression.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise-suppression.d.ts","sourceRoot":"","sources":["../../src/noise-suppression.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAE3D,+GAA+G;AAC/G,eAAO,MAAM,wBAAwB,UAAU,CAAC;AAGhD,MAAM,WAAW,sBAAsB;IACrC,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6GAA6G;IAC7G,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wEAAwE;AACxE,MAAM,WAAW,mBAAmB;IAClC,aAAa,IAAI,YAAY,CAAC;IAC9B,SAAS,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACxE,UAAU,CAAC,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,WAAW,CAAC;IAC/F,YAAY,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,WAAW,CAAC;CACvD;AAED,KAAK,WAAW,GAAG,SAAS,GAAG;IAAE,OAAO,CAAC,IAAI,IAAI,CAAA;CAAE,CAAC;AAsBpD,4GAA4G;AAC5G,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,sBAA2B,EAAE,IAAI,GAAE,mBAAiC,GAAG,mBAAmB,CAwExI"}

package/dist/cjs/noise-suppression.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NOISE_SUPPRESSOR_VERSION = void 0;
+exports.createNoiseSuppressor = createNoiseSuppressor;
+/** The package version the default URLs point at; equal to this SDK's pinned dependency (a test checks it). */
+exports.NOISE_SUPPRESSOR_VERSION = '0.4.1';
+const CDN = `https://cdn.jsdelivr.net/npm/@sapphi-red/web-noise-suppressor@${exports.NOISE_SUPPRESSOR_VERSION}/dist`;
+let library = null;
+/**
+ * The library is loaded on first use, not with this module: it extends `AudioWorkletNode` as it loads, which exists
+ * only in browsers, so a static import would break a server render (Next.js) or Node.
+ */
+const load = () => (library ??= Promise.resolve().then(() => require('@sapphi-red/web-noise-suppressor')).catch((err) => {
+    library = null;
+    throw err;
+}));
+const browserDeps = {
+    // RNNoise works on 48 kHz audio.
+    createContext: () => new AudioContext({ sampleRate: 48000 }),
+    loadModel: async (urls) => (await load()).loadRnnoise(urls),
+    createNode: async (context, wasmBinary) => new (await load()).RnnoiseWorkletNode(context, { wasmBinary, maxChannels: 1 }),
+    createStream: (tracks) => new MediaStream(tracks),
+};
+/** An `AudioTrackProcessor` for `client.setAudioProcessor()` that removes background noise with RNNoise. */
+function createNoiseSuppressor(options = {}, deps = browserDeps) {
+    let context = null;
+    let ready = null;
+    let graph = null;
+    let resumeOnGesture = null;
+    const release = () => {
+        if (!graph)
+            return;
+        try {
+            graph.source.disconnect();
+            graph.node.disconnect();
+            graph.node.destroy?.();
+        }
+        catch {
+            // Already gone.
+        }
+        graph.output.stop();
+        graph = null;
+    };
+    /** A context made without a tap starts suspended: no sound would go out until the page is touched. */
+    const keepRunning = (ctx) => {
+        void ctx.resume?.().catch(() => undefined);
+        if (ctx.state === 'running' || typeof document === 'undefined' || resumeOnGesture)
+            return;
+        resumeOnGesture = () => {
+            void ctx.resume().catch(() => undefined);
+            if (ctx.state === 'running' && resumeOnGesture) {
+                for (const type of ['pointerdown', 'keydown'])
+                    document.removeEventListener(type, resumeOnGesture, { capture: true });
+                resumeOnGesture = null;
+            }
+        };
+        for (const type of ['pointerdown', 'keydown'])
+            document.addEventListener(type, resumeOnGesture, { capture: true });
+    };
+    return {
+        name: 'noise-suppression',
+        async process(track) {
+            const ctx = (context ??= deps.createContext());
+            ready ??= Promise.all([
+                deps.loadModel({ url: options.wasmUrl ?? `${CDN}/rnnoise.wasm`, simdUrl: options.simdWasmUrl ?? `${CDN}/rnnoise_simd.wasm` }),
+                ctx.audioWorklet.addModule(options.workletUrl ?? `${CDN}/rnnoise/workletProcessor.js`),
+            ]).then(([model]) => model);
+            let model;
+            try {
+                model = await ready;
+            }
+            catch (err) {
+                ready = null; // try again next time (a network blip)
+                throw err;
+            }
+            const node = await deps.createNode(ctx, model);
+            release();
+            const source = ctx.createMediaStreamSource(deps.createStream([track]));
+            const destination = ctx.createMediaStreamDestination();
+            source.connect(node);
+            node.connect(destination);
+            const output = destination.stream.getAudioTracks()[0];
+            if (!output)
+                throw new Error('the audio graph gave no track');
+            graph = { source, node, output };
+            keepRunning(ctx);
+            return output;
+        },
+        async destroy() {
+            release();
+            if (resumeOnGesture && typeof document !== 'undefined') {
+                for (const type of ['pointerdown', 'keydown'])
+                    document.removeEventListener(type, resumeOnGesture, { capture: true });
+            }
+            resumeOnGesture = null;
+            const ctx = context;
+            context = null;
+            ready = null;
+            await ctx?.close().catch(() => undefined);
+        },
+    };
+}
+//# sourceMappingURL=noise-suppression.js.map

package/dist/cjs/noise-suppression.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noise-suppression.js","sourceRoot":"","sources":["../../src/noise-suppression.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