@relaymessenger/livekit 0.1.0-staging.1 → 0.1.0-staging.11

package/dist/transport.js

@@ -1,6 +1,36 @@
+/** Opus's native rate and Relay's wire channel count. */
+export const DEFAULT_INBOUND_AUDIO = Object.freeze({
+    sampleRate: 48_000,
+    channelCount: 2,
+});
+const INBOUND_SAMPLE_RATES = new Set([8_000, 12_000, 16_000, 24_000, 48_000]);
 const DEFAULT_ICE_GATHERING_TIMEOUT_MS = 10_000;
-const DEFAULT_CONNECTION_TIMEOUT_MS = 15_000;
 const AUDIO_SLICE_MS = 10;
+const STALL_CHECK_MS = 500;
+const STALL_AFTER_MS = 2_000;
+/**
+ * Restart rule, copied from PartyTracks and Cloudflare (PROTOCOL.md section 4):
+ * not `connected` 5 s after the SFU answer (Cloudflare's echo example waits
+ * 5000 ms; SFU operations block up to 5 s awaiting `connected`), `failed`, or
+ * `disconnected` for 7 s (PartyTracks.ts `timeoutSeconds = 7`). Backoff 250 ms
+ * x1.1 per attempt, capped at 10 s (PartyTracks `retryWithBackoff`
+ * `backoffFactor: 1.1`, rxjs-helpers.ts defaults). werift never reports
+ * `failed` on a session whose checks go unanswered (ice.js:983-986), so the
+ * 5 s timer is the trigger that fires in practice.
+ */
+export const RESTART_CONNECT_TIMEOUT_MS = 5_000;
+export const RESTART_DISCONNECTED_MS = 7_000;
+export const RESTART_INITIAL_DELAY_MS = 250;
+export const RESTART_BACKOFF_FACTOR = 1.1;
+export const RESTART_MAX_DELAY_MS = 10_000;
+/**
+ * Backoff before restart number `attempt` (1-based) counted since the last
+ * session that connected. PartyTracks passes `resetOnSuccess: true` to rxjs
+ * `retry` (rxjs-helpers.ts:18, :39); this transport reads "success" as a
+ * session reaching `connected`.
+ */
+export const restartDelayMs = (attempt) => Math.min(RESTART_INITIAL_DELAY_MS * RESTART_BACKOFF_FACTOR ** (attempt - 1), RESTART_MAX_DELAY_MS);
+const ACTIVE_CALL_STATUSES = new Set(["ringing", "in-progress"]);
 export class RelayCallTransportError extends Error {
     code;
     constructor(message, code) {
@@ -11,6 +41,11 @@ export class RelayCallTransportError extends Error {
     }
 }
 const DEFAULT_PEER_CONFIG = { iceServers: [], iceTransportPolicy: "all" };
+/**
+ * Cloudflare Realtime's echo example builds its peer with exactly this list
+ * (cloudflare/realtime-examples echo/index.html `createPeerConnection`).
+ */
+const DEFAULT_ICE_SERVERS = [{ urls: "stun:stun.cloudflare.com:3478" }];
 const loadWebRTCFactory = async (engine) => {
     if (engine === "werift") {
         const { createWeriftWebRTCFactory } = await import("./engine-werift.js");
@@ -23,7 +58,7 @@ const loadWebRTCFactory = async (engine) => {
             iceServers: config.iceServers,
             iceTransportPolicy: config.iceTransportPolicy,
         }),
-        createAudioSource: () => new wrtc.nonstandard.RTCAudioSource(),
+        createAudioSource: () => new WrtcAudioSource(new wrtc.nonstandard.RTCAudioSource()),
         createAudioSink: (track) => new wrtc.nonstandard.RTCAudioSink(track),
     };
 };
@@ -38,7 +73,8 @@ const seconds = (milliseconds) => `${(milliseconds / 1000).toFixed(1)}s`;
 const summarizeIce = (diagnostics) => {
     const { local, remote, transitions, connected } = diagnostics;
     const localPart = `local: host ${local.host}, srflx ${local.srflx}, relay ${local.relay}`
-        + (local.other ? `, other ${local.other}` : "");
+        + (local.other ? `, other ${local.other}` : "")
+        + (diagnostics.selectedPair ? `, pair ${diagnostics.selectedPair}` : "");
     const remotePart = remote.length
         ? `remote: ${remote.map((candidate) => `${candidate.transport} ${candidate.port}`).join(", ")}`
         : "remote: none";
@@ -60,11 +96,91 @@ const summarizeIce = (diagnostics) => {
         states.push("no connected");
     return `${localPart}; ${remotePart}; states: ${states.join(", ")}`;
 };
+const span = (first, last) => first === undefined || last === undefined ? "no packets" : `first ${seconds(first)} last ${seconds(last)}`;
+const summarizeInbound = (inbound) => `in: ${inbound.rtpPackets} rtp, ${inbound.decodeFailures} bad, ${inbound.frames} frames, `
+    + `${span(inbound.firstPacketAtMs, inbound.lastPacketAtMs)}, ${inbound.recentRtpPackets}/5s`;
+const summarizeOutbound = (outbound) => `out: ${outbound.frames} frames, ${outbound.opusPackets} opus, ${outbound.rtpPackets} rtp, `
+    + `silence ${outbound.silencePackets}, `
+    + `${span(outbound.firstPacketAtMs, outbound.lastPacketAtMs)}, ${outbound.recentRtpPackets}/5s, `
+    + `queue ${outbound.queued}, pacer ${outbound.pacerAlive === undefined ? "n/a" : outbound.pacerAlive ? "alive" : "idle"}`;
+const summarizeRoom = (room) => {
+    const parts = [`${room.roomStates} roomState`, `${room.offers} offer`];
+    if (room.endedReason !== undefined)
+        parts.push(`ended ${room.endedReason}`);
+    if (room.errors.length)
+        parts.push(`error ${room.errors.map((text) => JSON.stringify(text)).join(", ")}`);
+    return `room: ${parts.join(", ")}`;
+};
+const summarize = (diagnostics) => `${summarizeIce(diagnostics)}; ${summarizeInbound(diagnostics.inbound)}; `
+    + `${summarizeOutbound(diagnostics.outbound)}; ${summarizeRoom(diagnostics.room)}`
+    + (diagnostics.restarts ? `; restarts ${diagnostics.restarts}` : "");
+const copyIceServers = (servers) => servers.map((server) => ({
+    urls: Array.isArray(server.urls) ? [...server.urls] : server.urls,
+    ...(server.username === undefined ? {} : { username: server.username }),
+    ...(server.credential === undefined ? {} : { credential: server.credential }),
+}));
 const cloneSamples = (samples) => {
     const copy = new Int16Array(samples.length);
     copy.set(samples);
     return copy;
 };
+/**
+ * `@roamhq/wrtc`'s `RTCAudioSource` plays each 10 ms slice through libwebrtc's
+ * own clock and exposes no queue, so this wrapper estimates it from wall time:
+ * queued = accepted since the run started minus the time elapsed. Best effort;
+ * the werift engine (the default) reports its real queue.
+ *
+ * It sends no silence of its own. The source has no timer: `onData` hands the
+ * slice to the track's sinks and returns (`RTCAudioSource::OnData` ->
+ * `PushData`, node-webrtc src/interfaces/rtc_audio_source.cc and
+ * rtc_audio_source.hh, the repository @roamhq/wrtc 0.10.0 is published
+ * from), so libwebrtc receives audio only while the caller writes it, and
+ * this wrapper has no `start()`. What libwebrtc puts on the wire between
+ * writes was not measured; a caller of this
+ * engine that needs the track to carry data between utterances writes
+ * silence itself.
+ */
+class WrtcAudioSource {
+    #inner;
+    #runStartedAt = 0;
+    #runAcceptedMs = 0;
+    constructor(inner) {
+        this.#inner = inner;
+    }
+    createTrack() {
+        return this.#inner.createTrack();
+    }
+    onData(data) {
+        const now = Date.now();
+        if (this.queuedMs() === 0) {
+            this.#runStartedAt = now;
+            this.#runAcceptedMs = 0;
+        }
+        this.#runAcceptedMs += (data.numberOfFrames / data.sampleRate) * 1_000;
+        this.#inner.onData(data);
+    }
+    queuedMs() {
+        if (this.#runAcceptedMs === 0)
+            return 0;
+        return Math.max(0, this.#runAcceptedMs - (Date.now() - this.#runStartedAt));
+    }
+    async waitForDrain() {
+        const remaining = this.queuedMs();
+        if (remaining > 0)
+            await delay(remaining);
+    }
+    clear() {
+        // libwebrtc keeps slices already handed over; only the estimate can be reset.
+        this.#runAcceptedMs = 0;
+    }
+}
+/** werift's `close()` is async; a rejection there must not become an unhandled one. */
+const closePeer = (peer) => {
+    try {
+        void Promise.resolve(peer.close()).catch(() => undefined);
+    }
+    catch { /* already closed */ }
+};
 const delay = (milliseconds) => new Promise((resolve) => {
     const timer = setTimeout(resolve, milliseconds);
     timer.unref?.();
@@ -73,31 +189,75 @@ const delay = (milliseconds) => new Promise((resolve) => {
  * Provider-neutral Node WebRTC bridge for Relay Call rooms.
  *
  * The class owns Relay media negotiation internally. Higher-level adapters only
- * exchange PCM16 frames and call lifecycle events.
+ * exchange PCM16 frames and call lifecycle events. When an SFU session never
+ * connects or dies, the transport builds a new peer connection on a new
+ * session (PROTOCOL.md section 4); the audio source and the `audio` events
+ * carry on across the swap, so adapters only hear silence.
  */
 export class RelayCallTransport {
     #room;
     #providedFactory;
     #engine;
     #iceGatheringTimeoutMs;
-    #connectionTimeoutMs;
-    #peerConfig;
+    #sessionConnectTimeoutMs;
+    #iceServers;
+    #iceTransportPolicy;
+    #inboundAudio;
+    #onWarning;
     #connectStartedAt = 0;
+    #inboundFrames = 0;
+    #outboundFrames = 0;
+    #roomStates = 0;
+    #roomOffers = 0;
+    #endedReason;
+    #roomErrors = [];
+    /** Engine stats frozen when media shuts down, so diagnostics survive the call's end. */
+    #finalSinkStats;
+    #finalSourceStats;
+    /** Inbound counts from sinks of peers already replaced by a restart. */
+    #retiredSinkStats;
+    #stallTimer;
+    #stallSince;
+    #stallWarned = false;
     #iceLocal = { host: 0, srflx: 0, relay: 0, other: 0 };
     #iceRemote = [];
+    #selectedPair;
     #iceTransitions = [];
     #listeners = new Map();
     #factory;
     #peer;
+    /** Bumped for every peer built; work started for an older peer stops when it sees a newer one. */
+    #peerGeneration = 0;
+    /** The current peer has reached `connected` since it was built. */
+    #peerConnected = false;
     #audioSource;
     #localTrack;
+    /** Set while an offer waits for its first local candidate. */
+    #firstLocalCandidate;
     #remoteSink;
+    /** The track `#remoteSink` decodes; a repeated `ontrack` for it keeps the sink. */
+    #remoteSinkTrack;
     #publishTransceiver;
     #publishFrame;
     #initialAnswerSdp;
     #negotiationTail = Promise.resolve();
-    #outputTail = Promise.resolve();
+    #restarts = 0;
+    /** Restarts since the last `connected`; sets the backoff. */
+    #failedAttempts = 0;
+    #restartPending = false;
+    #wakeRestart;
+    #connectTimer;
+    #disconnectTimer;
+    #callStatus;
+    #remoteVideo = false;
+    #personConnected = false;
+    #peerAudioArrived = false;
+    #peerAudioReady = false;
+    #peerAudioWaiters = new Set();
+    #ended = false;
     #audioGeneration = 0;
+    /** `waitForPlayout()` callers released early by `clearAudio()` or `close()`. */
+    #playoutWaiters = new Set();
     #reportedConnected = false;
     #readySettled = false;
     #readyResolve;
@@ -111,30 +271,42 @@ export class RelayCallTransport {
         this.#room = options.roomClient ?? options.relay.calls.room(options.callId, options.room);
         this.#providedFactory = options.webRTC;
         this.#engine = options.engine ?? "werift";
+        this.#onWarning = options.onWarning ?? (() => undefined);
         if (this.#engine !== "werift" && this.#engine !== "wrtc") {
             throw new Error('engine must be "werift" or "wrtc".');
         }
+        const inbound = options.inboundAudio ?? DEFAULT_INBOUND_AUDIO;
+        if (!INBOUND_SAMPLE_RATES.has(inbound.sampleRate)) {
+            throw new Error("inboundAudio.sampleRate must be 8000, 12000, 16000, 24000 or 48000.");
+        }
+        if (inbound.channelCount !== 1 && inbound.channelCount !== 2) {
+            throw new Error("inboundAudio.channelCount must be 1 or 2.");
+        }
+        const isDefaultInbound = inbound.sampleRate === DEFAULT_INBOUND_AUDIO.sampleRate
+            && inbound.channelCount === DEFAULT_INBOUND_AUDIO.channelCount;
+        if (!options.webRTC && this.#engine === "wrtc" && !isDefaultInbound) {
+            // `@roamhq/wrtc`'s nonstandard RTCAudioSink hands over libwebrtc's own
+            // PCM and takes no format; honouring another one would mean resampling here.
+            throw new Error('The "wrtc" engine cannot decode to inboundAudio; use the "werift" engine.');
+        }
+        this.#inboundAudio = { sampleRate: inbound.sampleRate, channelCount: inbound.channelCount };
         this.#iceGatheringTimeoutMs = options.iceGatheringTimeoutMs ?? DEFAULT_ICE_GATHERING_TIMEOUT_MS;
-        this.#connectionTimeoutMs = options.mediaConnectTimeoutMs
+        this.#sessionConnectTimeoutMs = options.sessionConnectTimeoutMs
+            ?? options.mediaConnectTimeoutMs
             ?? options.connectionTimeoutMs
-            ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+            ?? RESTART_CONNECT_TIMEOUT_MS;
         const policy = options.iceTransportPolicy ?? "all";
         if (policy !== "all" && policy !== "relay") {
             throw new Error('iceTransportPolicy must be "all" or "relay".');
         }
-        this.#peerConfig = {
-            iceServers: (options.iceServers ?? []).map((server) => ({
-                urls: Array.isArray(server.urls) ? [...server.urls] : server.urls,
-                ...(server.username === undefined ? {} : { username: server.username }),
-                ...(server.credential === undefined ? {} : { credential: server.credential }),
-            })),
-            iceTransportPolicy: policy,
-        };
+        this.#iceTransportPolicy = policy;
+        const iceServers = options.iceServers ?? DEFAULT_ICE_SERVERS;
+        this.#iceServers = typeof iceServers === "function" ? iceServers : copyIceServers(iceServers);
         if (!Number.isFinite(this.#iceGatheringTimeoutMs) || this.#iceGatheringTimeoutMs <= 0) {
             throw new Error("iceGatheringTimeoutMs must be greater than zero.");
         }
-        if (!Number.isFinite(this.#connectionTimeoutMs) || this.#connectionTimeoutMs <= 0) {
-            throw new Error("mediaConnectTimeoutMs must be greater than zero.");
+        if (!Number.isFinite(this.#sessionConnectTimeoutMs) || this.#sessionConnectTimeoutMs <= 0) {
+            throw new Error("sessionConnectTimeoutMs must be greater than zero.");
         }
         this.#ready = new Promise((resolve, reject) => {
             this.#readyResolve = resolve;
@@ -155,13 +327,37 @@ export class RelayCallTransport {
         this.#listeners.get(event)?.delete(listener);
         return this;
     }
-    async connect() {
+    /**
+     * Join the room, publish, and resolve on the first `connected`. Dead SFU
+     * sessions are replaced as they are found (PROTOCOL.md section 4), with no
+     * overall deadline: this rejects only when the Call ends, the room or
+     * transport closes, the room reports an error, or `signal` aborts (which
+     * also closes the transport).
+     */
+    async connect(options = {}) {
         if (this.#closed)
             throw new Error("Relay Call transport is closed.");
+        const { signal } = options;
+        const aborted = () => new RelayCallTransportError("Relay Call connect was aborted.", "aborted");
+        if (signal?.aborted)
+            throw aborted();
+        const abort = () => {
+            this.#rejectReady(aborted());
+            this.close();
+        };
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            await this.#connect();
+        }
+        finally {
+            signal?.removeEventListener("abort", abort);
+        }
+    }
+    async #connect() {
         this.#attachRoomHandlers();
         await this.#room.connect();
-        if (this.#peer) {
-            await this.#waitForConnection();
+        if (this.#factory) {
+            await this.#ready;
             return;
         }
         this.#factory = this.#providedFactory ?? await loadWebRTCFactory(this.#engine);
@@ -171,18 +367,9 @@ export class RelayCallTransport {
             throw new RelayCallTransportError("The WebRTC binding created a non-audio Relay track.");
         }
         this.#connectStartedAt = Date.now();
-        const peer = this.#factory.createPeerConnection(this.#peerConfig);
-        this.#peer = peer;
-        this.#publishTransceiver = peer.addTransceiver(this.#localTrack, { direction: "sendonly" });
-        this.#observeIce(peer);
-        peer.onconnectionstatechange = () => {
-            this.#recordTransition("connection", peer.connectionState);
-            this.#connectionStateChanged();
-        };
-        peer.ontrack = (event) => this.#remoteTrack(event.track);
         try {
-            await this.#publishLocalAudio();
-            await this.#waitForConnection();
+            await this.#startPeer();
+            await this.#ready;
         }
         catch (error) {
             this.close();
@@ -198,19 +385,111 @@ export class RelayCallTransport {
         await this.#room.reconnect();
         this.#room.send(this.#publishFrame);
     }
-    /** ICE candidates and state transitions recorded for this call, with a one-line summary. */
+    /**
+     * ICE candidates, state transitions, packet counts in both directions,
+     * room frame counts and restarts recorded for this call, with a one-line summary.
+     */
     diagnostics() {
         const snapshot = {
             local: { ...this.#iceLocal },
             remote: this.#iceRemote.map((candidate) => ({ ...candidate })),
             transitions: this.#iceTransitions.map((transition) => ({ ...transition })),
-            connected: this.#reportedConnected,
+            selectedPair: this.#selectedPair,
+            connected: this.#peerConnected,
+            inbound: this.#inboundDiagnostics(),
+            outbound: this.#outboundDiagnostics(),
+            room: {
+                roomStates: this.#roomStates,
+                offers: this.#roomOffers,
+                endedReason: this.#endedReason,
+                errors: [...this.#roomErrors],
+            },
+            restarts: this.#restarts,
         };
-        return { ...snapshot, summary: summarizeIce(snapshot) };
+        return { ...snapshot, summary: summarize(snapshot) };
+    }
+    #sinceConnect(epochMs) {
+        return epochMs === undefined ? undefined : epochMs - this.#connectStartedAt;
+    }
+    /** The live sink's counts added to those of sinks retired by restarts. */
+    #sinkStats() {
+        const current = this.#remoteSink?.stats?.();
+        const retired = this.#retiredSinkStats;
+        if (!retired)
+            return current;
+        if (!current)
+            return { ...retired, recentRtpPackets: 0 };
+        return {
+            rtpPackets: retired.rtpPackets + current.rtpPackets,
+            decodeFailures: retired.decodeFailures + current.decodeFailures,
+            firstRtpAt: retired.firstRtpAt ?? current.firstRtpAt,
+            lastRtpAt: current.lastRtpAt ?? retired.lastRtpAt,
+            recentRtpPackets: current.recentRtpPackets,
+        };
+    }
+    #inboundDiagnostics() {
+        const stats = this.#finalSinkStats ?? this.#sinkStats();
+        return {
+            rtpPackets: stats?.rtpPackets ?? 0,
+            decodeFailures: stats?.decodeFailures ?? 0,
+            frames: this.#inboundFrames,
+            firstPacketAtMs: this.#sinceConnect(stats?.firstRtpAt),
+            lastPacketAtMs: this.#sinceConnect(stats?.lastRtpAt),
+            recentRtpPackets: stats?.recentRtpPackets ?? 0,
+        };
+    }
+    #outboundDiagnostics() {
+        const stats = this.#audioSource?.stats?.() ?? this.#finalSourceStats;
+        return {
+            frames: this.#outboundFrames,
+            opusPackets: stats?.opusPackets ?? 0,
+            rtpPackets: stats?.rtpPackets ?? 0,
+            silencePackets: stats?.silencePackets ?? 0,
+            firstPacketAtMs: this.#sinceConnect(stats?.firstRtpAt),
+            lastPacketAtMs: this.#sinceConnect(stats?.lastRtpAt),
+            recentRtpPackets: stats?.recentRtpPackets ?? 0,
+            queued: stats?.queued ?? 0,
+            pacerAlive: stats?.pacerAlive,
+        };
+    }
+    /**
+     * Outbound stall guard: audio is queued for the pacer but no RTP packet has
+     * left for 2 s while connected. Warns once with the summary; restarts nothing.
+     */
+    #checkStall() {
+        if (this.#stallWarned || !this.#reportedConnected)
+            return;
+        const stats = this.#audioSource?.stats?.();
+        if (!stats || stats.queued === 0) {
+            this.#stallSince = undefined;
+            return;
+        }
+        const now = Date.now();
+        const idleSince = stats.lastRtpAt ?? (this.#stallSince ??= now);
+        if (now - idleSince < STALL_AFTER_MS)
+            return;
+        this.#stallWarned = true;
+        this.#stopStallGuard();
+        this.#onWarning(`Relay outbound audio stalled (${this.diagnostics().summary})`);
+    }
+    #startStallGuard() {
+        if (this.#stallTimer)
+            return;
+        this.#stallTimer = setInterval(() => this.#checkStall(), STALL_CHECK_MS);
+        this.#stallTimer.unref?.();
+    }
+    #stopStallGuard() {
+        if (!this.#stallTimer)
+            return;
+        clearInterval(this.#stallTimer);
+        this.#stallTimer = undefined;
     }
     /**
      * Feed interleaved PCM16 audio into Relay. Frames are split into 10 ms WebRTC
-     * source slices and paced in real time, so adapters may push larger chunks.
+     * source slices and handed to the engine at once; the engine's 20 ms pump
+     * paces the wire, so adapters may push faster than real time (LiveKit's
+     * `AudioSource.captureFrame` shape). Resolves once the slices are queued;
+     * `waitForPlayout()` tells when they have left.
      */
     writeAudio(frame) {
         if (this.#closed)
@@ -231,14 +510,72 @@ export class RelayCallTransport {
             sampleRate: frame.sampleRate,
             channelCount: frame.channelCount,
         };
-        const generation = this.#audioGeneration;
-        const queued = this.#outputTail.then(() => this.#writeAudio(captured, generation));
-        this.#outputTail = queued.catch(() => undefined);
-        return queued;
+        this.#writeAudio(captured, this.#audioGeneration);
+        return Promise.resolve();
+    }
+    /** Milliseconds of audio accepted by `writeAudio` but not yet written to RTP. */
+    queuedAudioMs() {
+        return this.#audioSource?.queuedMs?.() ?? 0;
+    }
+    /**
+     * Resolves when every accepted slice has been written to RTP and the engine's
+     * pump is idle; immediately when nothing is queued; early on `clearAudio()`
+     * or `close()` (the caller reads `queuedAudioMs()` to learn what was dropped).
+     */
+    waitForPlayout() {
+        const source = this.#audioSource;
+        if (!source || this.#closed || this.queuedAudioMs() === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => {
+            const release = () => {
+                this.#playoutWaiters.delete(release);
+                resolve();
+            };
+            this.#playoutWaiters.add(release);
+            const drained = source.waitForDrain?.() ?? Promise.resolve();
+            drained.then(release, release);
+        });
     }
-    /** Drop queued outgoing PCM. At most one already-submitted 10 ms slice remains. */
+    /** Drop outgoing PCM that has not reached RTP and release `waitForPlayout()` callers. */
     clearAudio() {
         this.#audioGeneration += 1;
+        this.#audioSource?.clear?.();
+        this.#releasePlayoutWaiters();
+    }
+    /**
+     * Resolves once `peerAudio` has fired (at once if it already has). Rejects
+     * after `timeoutMs`, or when the Call ends or the transport closes first.
+     */
+    waitForPeerAudio(timeoutMs) {
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return Promise.reject(new Error("waitForPeerAudio timeoutMs must be greater than zero."));
+        }
+        if (this.#peerAudioReady)
+            return Promise.resolve();
+        if (this.#closed || this.#ended) {
+            return Promise.reject(new RelayCallTransportError("Relay Call ended before the person's audio arrived."));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: () => { clearTimeout(timer); this.#peerAudioWaiters.delete(waiter); resolve(); },
+                reject: (error) => { clearTimeout(timer); this.#peerAudioWaiters.delete(waiter); reject(error); },
+            };
+            const timer = setTimeout(() => waiter.reject(new RelayCallTransportError(`Timed out waiting for the person's audio (${this.diagnostics().summary})`)), timeoutMs);
+            timer.unref?.();
+            this.#peerAudioWaiters.add(waiter);
+        });
+    }
+    #checkPeerAudio() {
+        if (this.#peerAudioReady || !this.#peerAudioArrived || !this.#personConnected)
+            return;
+        this.#peerAudioReady = true;
+        for (const waiter of [...this.#peerAudioWaiters])
+            waiter.resolve();
+        this.#emit("peerAudio");
+    }
+    #rejectPeerAudio(error) {
+        for (const waiter of [...this.#peerAudioWaiters])
+            waiter.reject(error);
     }
     setMuted(muted) {
         this.#room.userUpdate({ muted });
@@ -251,16 +588,63 @@ export class RelayCallTransport {
             return;
         this.#closed = true;
         this.#rejectReady(new RelayCallTransportError("Relay Call transport closed before media connected."));
-        this.clearAudio();
+        this.#rejectPeerAudio(new RelayCallTransportError("Relay Call transport closed before the person's audio arrived."));
+        this.#audioGeneration += 1;
         this.#shutdownMedia();
+        this.#releasePlayoutWaiters();
         this.#room.close();
     }
-    async #publishLocalAudio() {
-        const peer = this.#requirePeer();
+    /**
+     * Build a peer connection around the one local track and publish it. The
+     * first peer sends a plain `offer`; every later one is a restart onto a new
+     * SFU session (`restart: true`) with ICE servers fetched again.
+     */
+    async #startPeer() {
+        const factory = this.#factory;
+        const track = this.#localTrack;
+        if (!factory || !track)
+            throw new Error("Relay Call transport is not connected.");
+        const restarts = this.#restarts;
+        const generation = ++this.#peerGeneration;
+        const iceServers = typeof this.#iceServers === "function"
+            ? copyIceServers(await this.#iceServers({ restarts }))
+            : copyIceServers(this.#iceServers);
+        if (this.#closed || this.#ended || generation !== this.#peerGeneration)
+            return;
+        const peer = factory.createPeerConnection({ iceServers, iceTransportPolicy: this.#iceTransportPolicy });
+        this.#peer = peer;
+        this.#peerConnected = false;
+        this.#initialAnswerSdp = undefined;
+        this.#publishTransceiver = peer.addTransceiver(track, { direction: "sendonly" });
+        this.#observeIce(peer);
+        peer.onconnectionstatechange = () => {
+            if (this.#peer !== peer)
+                return;
+            this.#recordTransition("connection", peer.connectionState);
+            this.#connectionStateChanged(peer);
+        };
+        peer.ontrack = (event) => {
+            if (this.#peer === peer)
+                this.#remoteTrack(event.track);
+        };
+        await this.#publishLocalAudio(peer, restarts > 0);
+    }
+    /**
+     * Sends the offer without waiting for ICE gathering, as Cloudflare's echo
+     * example does (`setLocalDescription(offer)`, then `tracks/new` at once): the
+     * SFU is ICE-lite and learns this peer's address from its connectivity
+     * checks. werift's `setLocalDescription` resolves only after every host,
+     * STUN and TURN candidate has settled (peerConnection.js `await
+     * this.gatherCandidates()`; ice.js `await Promise.allSettled(candidatePromises)`),
+     * which took 6.6 s on a staging call on 2026-09-22, so the offer leaves as
+     * soon as the description is applied and the first local candidate exists.
+     */
+    async #publishLocalAudio(peer, restart) {
         const offer = await peer.createOffer();
-        await peer.setLocalDescription(offer);
-        await this.#waitForIceGathering(peer);
-        const description = this.#localDescription("offer");
+        await this.#applyLocalOffer(peer, offer);
+        if (this.#peer !== peer)
+            return;
+        const description = this.#localDescription(peer, "offer");
         const mid = this.#publishTransceiver?.mid;
         if (!mid)
             throw new RelayCallTransportError("Relay audio publication has no WebRTC MID.");
@@ -268,6 +652,7 @@ export class RelayCallTransport {
             type: "offer",
             session_description: description,
             tracks: [{ mid, name: "audio" }],
+            ...(restart ? { restart: true } : {}),
         };
         this.#room.send(this.#publishFrame);
     }
@@ -279,10 +664,23 @@ export class RelayCallTransport {
             this.#queueNegotiation(() => this.#serverAnswer(frame));
         });
         this.#room.on("offer", (frame) => {
+            this.#roomOffers += 1;
             this.#queueNegotiation(() => this.#serverOffer(frame));
         });
         this.#room.on("roomState", (frame) => {
+            this.#roomStates += 1;
+            this.#callStatus = frame.call?.status;
+            // A Call has exactly one agent; the transport is that agent, so the
+            // person is the other participant.
+            const person = frame.participants?.find((participant) => participant.kind === "user");
+            const video = person?.video === true;
+            const videoChanged = video !== this.#remoteVideo;
+            this.#remoteVideo = video;
+            this.#personConnected = person?.connected === true;
             this.#emit("roomState", frame);
+            if (videoChanged)
+                this.#emit("remoteVideo", video);
+            this.#checkPeerAudio();
         });
         this.#room.on("error", (error) => {
             if (error instanceof Error) {
@@ -293,7 +691,10 @@ export class RelayCallTransport {
                 this.#serverError(error);
         });
         this.#room.on("ended", (frame) => {
+            this.#ended = true;
+            this.#endedReason = frame.reason;
             this.#rejectReady(new RelayCallTransportError(`Relay Call ended before media connected (${frame.reason}).`));
+            this.#rejectPeerAudio(new RelayCallTransportError(`Relay Call ended before the person's audio arrived (${frame.reason}).`));
             this.clearAudio();
             this.#shutdownMedia();
             this.#emit("ended", frame);
@@ -314,39 +715,71 @@ export class RelayCallTransport {
         });
     }
     async #serverAnswer(frame) {
-        const peer = this.#requirePeer();
+        // No peer: the answer is for a session a restart already replaced.
+        const peer = this.#peer;
+        if (!peer)
+            return;
         const sdp = frame.session_description.sdp;
         // Reconnecting the signaling socket replays the exact initial offer. Relay
         // returns its cached answer; applying that answer again in stable state is
         // invalid WebRTC signaling, so recognize and ignore the replay.
         if (peer.signalingState === "stable" && this.#initialAnswerSdp === sdp)
             return;
-        if (this.#initialAnswerSdp === undefined)
+        const initial = this.#initialAnswerSdp === undefined;
+        if (initial)
             this.#recordRemoteCandidates(sdp);
         await peer.setRemoteDescription(frame.session_description);
+        if (this.#peer !== peer)
+            return;
         this.#initialAnswerSdp ??= sdp;
+        if (initial && !this.#peerConnected)
+            this.#armConnectTimer(peer);
     }
     async #serverOffer(frame) {
-        const peer = this.#requirePeer();
+        const peer = this.#peer;
+        // A pull offer that arrives while this participant's restart offer is
+        // unanswered was sent for the replaced session: the room clears those
+        // pulls on restart and pulls again after the new session connects.
+        if (!peer || peer.signalingState === "have-local-offer")
+            return;
+        // `video` m-lines are answered receive-only by the engine and never decoded
+        // (`#remoteTrack` takes audio only).
         await peer.setRemoteDescription(frame.session_description);
         const answer = await peer.createAnswer();
         await peer.setLocalDescription(answer);
-        await this.#waitForIceGathering(peer);
-        this.#room.send({ type: "answer", session_description: this.#localDescription("answer") });
+        if (this.#peer !== peer)
+            return;
+        this.#room.send({ type: "answer", session_description: this.#localDescription(peer, "answer") });
     }
     #serverError(frame) {
+        this.#roomErrors.push(frame.message);
         const error = new RelayCallTransportError(frame.message, frame.code);
         this.#rejectReady(error);
         this.#emit("error", error);
     }
-    #connectionStateChanged() {
-        const state = this.#peer?.connectionState;
-        if (state === "connected" && !this.#reportedConnected) {
-            this.#reportedConnected = true;
+    #connectionStateChanged(peer) {
+        const state = peer.connectionState;
+        if (state === "connected") {
+            this.#clearTimer("connect");
+            this.#clearTimer("disconnect");
+            if (this.#peerConnected)
+                return;
+            this.#peerConnected = true;
+            this.#failedAttempts = 0;
+            void this.#readSelectedPair(peer);
+            // The SFU will not pull a track that has carried no RTP, so the source
+            // sends silence from here on until it is closed.
+            this.#audioSource?.start?.();
             try {
+                // Sent for every new session: the room re-pulls a restarted participant's
+                // tracks once it reports `connected` (PROTOCOL.md section 2).
                 this.#room.connected();
-                this.#resolveReady();
-                this.#emit("connected");
+                if (!this.#reportedConnected) {
+                    this.#reportedConnected = true;
+                    this.#resolveReady();
+                    this.#startStallGuard();
+                    this.#emit("connected");
+                }
             }
             catch (error) {
                 const parsed = error instanceof Error ? error : new Error(String(error));
@@ -355,17 +788,134 @@ export class RelayCallTransport {
             }
         }
         else if (state === "failed") {
-            const error = new RelayCallTransportError("Relay WebRTC connection failed.");
-            this.#rejectReady(error);
-            this.#emit("error", error);
+            this.#requestRestart("failed", peer);
+        }
+        else if (state === "disconnected") {
+            if (this.#disconnectTimer)
+                return;
+            this.#disconnectTimer = setTimeout(() => {
+                this.#disconnectTimer = undefined;
+                if (peer.connectionState !== "connected")
+                    this.#requestRestart("disconnected", peer);
+            }, RESTART_DISCONNECTED_MS);
+            this.#disconnectTimer.unref?.();
+        }
+    }
+    #armConnectTimer(peer) {
+        this.#clearTimer("connect");
+        this.#connectTimer = setTimeout(() => {
+            this.#connectTimer = undefined;
+            if (!this.#peerConnected)
+                this.#requestRestart("timeout", peer);
+        }, this.#sessionConnectTimeoutMs);
+        this.#connectTimer.unref?.();
+    }
+    #clearTimer(which) {
+        if (which === "connect") {
+            clearTimeout(this.#connectTimer);
+            this.#connectTimer = undefined;
         }
+        else {
+            clearTimeout(this.#disconnectTimer);
+            this.#disconnectTimer = undefined;
+        }
+    }
+    #callActive() {
+        if (this.#closed || this.#ended)
+            return false;
+        return this.#callStatus === undefined || ACTIVE_CALL_STATUSES.has(this.#callStatus);
+    }
+    /**
+     * Retire `peer` now, wait the backoff, then publish from a new peer on a new
+     * session. Unlimited while the Call is ringing or in progress; stops on
+     * `ended`, a terminal status, or `close()`.
+     */
+    #requestRestart(reason, peer) {
+        if (this.#restartPending || peer !== this.#peer || !this.#callActive())
+            return;
+        const summary = this.diagnostics().summary;
+        this.#restartPending = true;
+        this.#restarts += 1;
+        this.#failedAttempts += 1;
+        const restarts = this.#restarts;
+        const delayMs = restartDelayMs(this.#failedAttempts);
+        this.#retirePeer();
+        this.#queueNegotiation(async () => {
+            await this.#restartBackoff(delayMs);
+            this.#restartPending = false;
+            if (!this.#callActive())
+                return;
+            try {
+                await this.#startPeer();
+            }
+            catch (error) {
+                if (!this.#callActive())
+                    return;
+                const parsed = error instanceof Error ? error : new Error(String(error));
+                this.#emit("error", new RelayCallTransportError(`Relay WebRTC restart ${restarts} failed: ${parsed.message}`, "restart_failed"));
+                this.#requestRestart("error", this.#peer);
+                return;
+            }
+            if (this.#peer)
+                this.#emit("restarted", { reason, summary, restarts, delayMs });
+        });
+    }
+    #restartBackoff(milliseconds) {
+        return new Promise((resolve) => {
+            const wake = () => {
+                clearTimeout(timer);
+                if (this.#wakeRestart === wake)
+                    this.#wakeRestart = undefined;
+                resolve();
+            };
+            const timer = setTimeout(wake, milliseconds);
+            timer.unref?.();
+            this.#wakeRestart = wake;
+        });
     }
+    /** Close the current peer and its sink; the audio source and local track stay for the next peer. */
+    #retirePeer() {
+        this.#clearTimer("connect");
+        this.#clearTimer("disconnect");
+        const peer = this.#peer;
+        this.#peer = undefined;
+        this.#peerConnected = false;
+        this.#publishTransceiver = undefined;
+        this.#initialAnswerSdp = undefined;
+        if (this.#remoteSink) {
+            this.#retiredSinkStats = this.#sinkStats();
+            this.#remoteSink.stop();
+            this.#remoteSink = undefined;
+            this.#remoteSinkTrack = undefined;
+        }
+        if (!peer)
+            return;
+        peer.onconnectionstatechange = null;
+        peer.ontrack = null;
+        peer.onicecandidate = null;
+        peer.onicegatheringstatechange = null;
+        peer.oniceconnectionstatechange = null;
+        closePeer(peer);
+    }
+    /**
+     * werift fires `ontrack` again for every sending m-line on each
+     * `setRemoteDescription` (transceiverManager.js `setRemoteRTP`), so a pull
+     * offer that adds the person's video re-announces the audio track already
+     * decoded. That track keeps its sink, decoder and packet counts; a different
+     * audio track retires the old sink's counts into the call totals, as a restart does.
+     */
     #remoteTrack(track) {
         if (track.kind !== "audio" || !this.#factory)
             return;
-        this.#remoteSink?.stop();
-        const sink = this.#factory.createAudioSink(track);
+        if (this.#remoteSink && this.#remoteSinkTrack === track)
+            return;
+        if (this.#remoteSink) {
+            this.#retiredSinkStats = this.#sinkStats();
+            this.#remoteSink.stop();
+        }
+        const sink = this.#factory.createAudioSink(track, this.#inboundAudio);
         this.#remoteSink = sink;
+        this.#remoteSinkTrack = track;
         sink.ondata = (data) => {
             if (this.#closed || this.#remoteSink !== sink)
                 return;
@@ -374,18 +924,23 @@ export class RelayCallTransport {
                 this.#emit("error", new RelayCallTransportError(`Relay WebRTC delivered unsupported ${data.bitsPerSample}-bit audio.`));
                 return;
             }
+            this.#inboundFrames += 1;
             this.#emit("audio", {
                 samples: cloneSamples(data.samples),
                 sampleRate: data.sampleRate,
                 channelCount,
             });
+            if (!this.#peerAudioArrived) {
+                this.#peerAudioArrived = true;
+                this.#checkPeerAudio();
+            }
         };
     }
-    async #writeAudio(frame, generation) {
+    #writeAudio(frame, generation) {
         const source = this.#audioSource;
         if (!source || generation !== this.#audioGeneration)
             return;
-        const samplesPerChannel = frame.sampleRate / 100;
+        const samplesPerChannel = (frame.sampleRate * AUDIO_SLICE_MS) / 1000;
         const sliceSamples = samplesPerChannel * frame.channelCount;
         for (let offset = 0; offset < frame.samples.length; offset += sliceSamples) {
             if (this.#closed || generation !== this.#audioGeneration)
@@ -400,48 +955,54 @@ export class RelayCallTransport {
                 channelCount: frame.channelCount,
                 numberOfFrames: samplesPerChannel,
             });
-            await delay(AUDIO_SLICE_MS);
+            this.#outboundFrames += 1;
         }
     }
-    async #waitForIceGathering(peer) {
-        if (peer.iceGatheringState === "complete")
-            return;
-        await new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                cleanup();
-                reject(new RelayCallTransportError("Timed out gathering Relay WebRTC ICE candidates."));
-            }, this.#iceGatheringTimeoutMs);
-            timeout.unref?.();
-            const changed = () => {
-                if (peer.iceGatheringState !== "complete")
-                    return;
-                cleanup();
-                resolve();
-            };
-            const cleanup = () => {
-                clearTimeout(timeout);
-                peer.removeEventListener("icegatheringstatechange", changed);
-            };
-            peer.addEventListener("icegatheringstatechange", changed);
-            changed();
-        });
+    #releasePlayoutWaiters() {
+        for (const release of [...this.#playoutWaiters])
+            release();
     }
-    async #waitForConnection() {
-        if (this.#reportedConnected)
-            return;
-        await new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                reject(new RelayCallTransportError(`Timed out connecting Relay WebRTC media (${this.diagnostics().summary})`));
-            }, this.#connectionTimeoutMs);
-            timeout.unref?.();
-            this.#ready.then(() => {
-                clearTimeout(timeout);
-                resolve();
-            }, (error) => {
-                clearTimeout(timeout);
-                reject(error);
-            });
+    /**
+     * Resolves once the offer is applied and has a first local candidate, or
+     * once `setLocalDescription` resolves (W3C engines resolve before gathering),
+     * whichever comes first.
+     */
+    async #applyLocalOffer(peer, offer) {
+        const applied = peer.setLocalDescription(offer);
+        let settled = false;
+        applied.catch((error) => {
+            if (!settled || this.#peer !== peer)
+                return;
+            const parsed = error instanceof Error ? error : new Error(String(error));
+            this.#rejectReady(parsed);
+            this.#emit("error", parsed);
         });
+        try {
+            await new Promise((resolve, reject) => {
+                const timeout = setTimeout(() => {
+                    cleanup();
+                    reject(new RelayCallTransportError("Timed out gathering Relay WebRTC ICE candidates."));
+                }, this.#iceGatheringTimeoutMs);
+                timeout.unref?.();
+                const cleanup = () => {
+                    clearTimeout(timeout);
+                    if (this.#firstLocalCandidate === done)
+                        this.#firstLocalCandidate = undefined;
+                };
+                const done = () => {
+                    cleanup();
+                    resolve();
+                };
+                this.#firstLocalCandidate = done;
+                applied.then(done, (error) => {
+                    cleanup();
+                    reject(error);
+                });
+            });
+        }
+        finally {
+            settled = true;
+        }
     }
     /**
      * werift emits these as W3C-style handler calls (peerConnection.js:314-341:
@@ -458,6 +1019,8 @@ export class RelayCallTransport {
                 this.#iceLocal[type] += 1;
             else
                 this.#iceLocal.other += 1;
+            if (this.#peer === peer && peer.localDescription)
+                this.#firstLocalCandidate?.();
         };
         peer.onicegatheringstatechange = () => this.#recordTransition("gathering", peer.iceGatheringState);
         peer.oniceconnectionstatechange = () => {
@@ -465,6 +1028,35 @@ export class RelayCallTransport {
                 this.#recordTransition("ice", peer.iceConnectionState);
         };
     }
+    /**
+     * W3C stats path: `transport.selectedCandidatePairId` -> `candidate-pair`
+     * -> `local-candidate.candidateType` (werift transport/dtls.js and
+     * transport/ice.js `getStats`); a nominated, succeeded pair when the
+     * transport names none.
+     */
+    async #readSelectedPair(peer) {
+        let report;
+        try {
+            report = await peer.getStats?.();
+        }
+        catch {
+            return;
+        }
+        if (!report || this.#peer !== peer)
+            return;
+        const stats = new Map();
+        report.forEach((stat) => stats.set(String(stat.id), stat));
+        const all = [...stats.values()];
+        const selectedId = all.find((stat) => stat.type === "transport" && stat.selectedCandidatePairId)
+            ?.selectedCandidatePairId;
+        const pair = selectedId !== undefined
+            ? stats.get(String(selectedId))
+            : all.find((stat) => stat.type === "candidate-pair" && stat.nominated === true && stat.state === "succeeded");
+        const local = pair ? stats.get(String(pair.localCandidateId)) : undefined;
+        if (typeof local?.candidateType !== "string")
+            return;
+        this.#selectedPair = `${local.candidateType} ${typeof local.protocol === "string" ? local.protocol : "?"}`;
+    }
     #recordTransition(kind, state) {
         this.#iceTransitions.push({ kind, state, atMs: Date.now() - this.#connectStartedAt });
     }
@@ -489,24 +1081,27 @@ export class RelayCallTransport {
         this.#readySettled = true;
         this.#readyReject?.(error);
     }
-    #localDescription(type) {
-        const local = this.#requirePeer().localDescription;
+    #localDescription(peer, type) {
+        const local = peer.localDescription;
         if (!local || local.type !== type || !local.sdp) {
             throw new RelayCallTransportError(`Relay WebRTC did not produce a complete ${type} SDP.`);
         }
         return { type, sdp: local.sdp };
     }
-    #requirePeer() {
-        if (!this.#peer)
-            throw new Error("Relay Call transport is not connected.");
-        return this.#peer;
-    }
     #shutdownMedia() {
+        this.#stopStallGuard();
+        this.#clearTimer("connect");
+        this.#clearTimer("disconnect");
+        this.#wakeRestart?.();
+        this.#finalSinkStats ??= this.#sinkStats();
+        this.#finalSourceStats ??= this.#audioSource?.stats?.();
         this.#remoteSink?.stop();
         this.#remoteSink = undefined;
+        this.#remoteSinkTrack = undefined;
         this.#localTrack?.stop();
         this.#localTrack = undefined;
-        this.#peer?.close();
+        if (this.#peer)
+            closePeer(this.#peer);
         this.#peer = undefined;
         this.#audioSource = undefined;
     }