@relaymessenger/livekit 0.1.0-staging.0 → 0.1.0-staging.10

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) {
@@ -10,6 +40,7 @@ export class RelayCallTransportError extends Error {
             this.code = code;
     }
 }
+const DEFAULT_PEER_CONFIG = { iceServers: [], iceTransportPolicy: "all" };
 const loadWebRTCFactory = async (engine) => {
     if (engine === "werift") {
         const { createWeriftWebRTCFactory } = await import("./engine-werift.js");
@@ -17,19 +48,133 @@ const loadWebRTCFactory = async (engine) => {
     }
     const wrtc = await import("@roamhq/wrtc");
     return {
-        createPeerConnection: () => new wrtc.RTCPeerConnection({
+        createPeerConnection: (config = DEFAULT_PEER_CONFIG) => new wrtc.RTCPeerConnection({
             bundlePolicy: "max-bundle",
-            iceServers: [],
+            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),
     };
 };
+/** `candidate:<foundation> <component> <transport> <priority> <address> <port> typ <type> ...` (RFC 5245 §15.1). */
+const parseCandidate = (line) => {
+    const match = /candidate:\S+\s+\d+\s+(\S+)\s+\d+\s+\S+\s+(\d+)\s+typ\s+(\S+)/i.exec(line);
+    if (!match)
+        return undefined;
+    return { transport: match[1].toLowerCase(), port: Number(match[2]), type: match[3].toLowerCase() };
+};
+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}` : "");
+    const remotePart = remote.length
+        ? `remote: ${remote.map((candidate) => `${candidate.transport} ${candidate.port}`).join(", ")}`
+        : "remote: none";
+    const states = [];
+    let lastGathering = "new";
+    for (const transition of transitions) {
+        if (transition.kind === "gathering") {
+            states.push(`${lastGathering}\u2192${transition.state} ${seconds(transition.atMs)}`);
+            lastGathering = transition.state;
+        }
+        else if (transition.kind === "ice") {
+            states.push(`ice ${transition.state} ${seconds(transition.atMs)}`);
+        }
+        else {
+            states.push(`${transition.state} ${seconds(transition.atMs)}`);
+        }
+    }
+    if (!connected)
+        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?.();
@@ -38,17 +183,46 @@ 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;
+    #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 = [];
+    #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;
     #remoteSink;
@@ -56,8 +230,23 @@ export class RelayCallTransport {
     #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;
@@ -71,16 +260,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.connectionTimeoutMs ?? DEFAULT_CONNECTION_TIMEOUT_MS;
+        this.#sessionConnectTimeoutMs = options.sessionConnectTimeoutMs
+            ?? options.mediaConnectTimeoutMs
+            ?? options.connectionTimeoutMs
+            ?? RESTART_CONNECT_TIMEOUT_MS;
+        const policy = options.iceTransportPolicy ?? "all";
+        if (policy !== "all" && policy !== "relay") {
+            throw new Error('iceTransportPolicy must be "all" or "relay".');
+        }
+        this.#iceTransportPolicy = policy;
+        const iceServers = options.iceServers ?? [];
+        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("connectionTimeoutMs 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;
@@ -101,13 +316,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);
@@ -116,14 +355,10 @@ export class RelayCallTransport {
         if (this.#localTrack.kind !== "audio") {
             throw new RelayCallTransportError("The WebRTC binding created a non-audio Relay track.");
         }
-        const peer = this.#factory.createPeerConnection();
-        this.#peer = peer;
-        this.#publishTransceiver = peer.addTransceiver(this.#localTrack, { direction: "sendonly" });
-        peer.onconnectionstatechange = () => this.#connectionStateChanged();
-        peer.ontrack = (event) => this.#remoteTrack(event.track);
+        this.#connectStartedAt = Date.now();
         try {
-            await this.#publishLocalAudio();
-            await this.#waitForConnection();
+            await this.#startPeer();
+            await this.#ready;
         }
         catch (error) {
             this.close();
@@ -139,9 +374,110 @@ export class RelayCallTransport {
         await this.#room.reconnect();
         this.#room.send(this.#publishFrame);
     }
+    /**
+     * 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.#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: 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)
@@ -162,14 +498,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 });
@@ -182,16 +576,54 @@ 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);
+    }
+    async #publishLocalAudio(peer, restart) {
         const offer = await peer.createOffer();
         await peer.setLocalDescription(offer);
         await this.#waitForIceGathering(peer);
-        const description = this.#localDescription("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.");
@@ -199,6 +631,7 @@ export class RelayCallTransport {
             type: "offer",
             session_description: description,
             tracks: [{ mid, name: "audio" }],
+            ...(restart ? { restart: true } : {}),
         };
         this.#room.send(this.#publishFrame);
     }
@@ -210,10 +643,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) {
@@ -224,7 +670,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);
@@ -245,37 +694,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;
+        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;
+            // 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));
@@ -284,16 +767,119 @@ 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;
         }
+        if (!peer)
+            return;
+        peer.onconnectionstatechange = null;
+        peer.ontrack = null;
+        peer.onicecandidate = null;
+        peer.onicegatheringstatechange = null;
+        peer.oniceconnectionstatechange = null;
+        closePeer(peer);
     }
     #remoteTrack(track) {
         if (track.kind !== "audio" || !this.#factory)
             return;
         this.#remoteSink?.stop();
-        const sink = this.#factory.createAudioSink(track);
+        const sink = this.#factory.createAudioSink(track, this.#inboundAudio);
         this.#remoteSink = sink;
         sink.ondata = (data) => {
             if (this.#closed || this.#remoteSink !== sink)
@@ -303,18 +889,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)
@@ -329,9 +920,13 @@ export class RelayCallTransport {
                 channelCount: frame.channelCount,
                 numberOfFrames: samplesPerChannel,
             });
-            await delay(AUDIO_SLICE_MS);
+            this.#outboundFrames += 1;
         }
     }
+    #releasePlayoutWaiters() {
+        for (const release of [...this.#playoutWaiters])
+            release();
+    }
     async #waitForIceGathering(peer) {
         if (peer.iceGatheringState === "complete")
             return;
@@ -355,22 +950,39 @@ export class RelayCallTransport {
             changed();
         });
     }
-    async #waitForConnection() {
-        if (this.#reportedConnected)
-            return;
-        await new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                reject(new RelayCallTransportError("Timed out connecting Relay WebRTC media."));
-            }, this.#connectionTimeoutMs);
-            timeout.unref?.();
-            this.#ready.then(() => {
-                clearTimeout(timeout);
-                resolve();
-            }, (error) => {
-                clearTimeout(timeout);
-                reject(error);
-            });
-        });
+    /**
+     * werift emits these as W3C-style handler calls (peerConnection.js:314-341:
+     * `onicegatheringstatechange`, `oniceconnectionstatechange`,
+     * `onconnectionstatechange`, `onicecandidate` with `{ candidate }`).
+     */
+    #observeIce(peer) {
+        peer.onicecandidate = (event) => {
+            const line = event?.candidate?.candidate;
+            if (!line)
+                return;
+            const type = parseCandidate(line)?.type;
+            if (type === "host" || type === "srflx" || type === "relay")
+                this.#iceLocal[type] += 1;
+            else
+                this.#iceLocal.other += 1;
+        };
+        peer.onicegatheringstatechange = () => this.#recordTransition("gathering", peer.iceGatheringState);
+        peer.oniceconnectionstatechange = () => {
+            if (peer.iceConnectionState !== undefined)
+                this.#recordTransition("ice", peer.iceConnectionState);
+        };
+    }
+    #recordTransition(kind, state) {
+        this.#iceTransitions.push({ kind, state, atMs: Date.now() - this.#connectStartedAt });
+    }
+    #recordRemoteCandidates(sdp) {
+        for (const line of sdp.split(/\r?\n/)) {
+            if (!line.startsWith("a=candidate:"))
+                continue;
+            const parsed = parseCandidate(line);
+            if (parsed)
+                this.#iceRemote.push({ transport: parsed.transport, port: parsed.port });
+        }
     }
     #resolveReady() {
         if (this.#readySettled)
@@ -384,24 +996,26 @@ 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.#localTrack?.stop();
         this.#localTrack = undefined;
-        this.#peer?.close();
+        if (this.#peer)
+            closePeer(this.#peer);
         this.#peer = undefined;
         this.#audioSource = undefined;
     }