@rapidmx/meet-plugin 0.14.1 → 0.16.0

package/apps/shared/media/filters/mlModels.ts

@@ -1,174 +1,174 @@
-///////////////////////////////////////////////////////////////////////////////
-// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
-// SPDX-License-Identifier: MPL-2.0
-///////////////////////////////////////////////////////////////////////////////
-/**
- * The two machine-learning models behind the filters, run in the browser with MediaPipe Tasks:
- *
- * - **Person segmentation** (`createPersonSegmenter`) - which pixels are the participant: what the background
- * blur and the custom background need.
- * - **Face landmarks** (`createFaceTracker`) - where the participant's face is: what the accessories need.
- *
- * Nothing here is loaded until a participant turns a filter on that needs it, and each model is loaded once and
- * shared. The MediaPipe library itself is `import()`ed on demand for the same reason - a participant who never uses a
- * filter never downloads it.
- *
- * **Where the assets come from**: by default the WebAssembly runtime is fetched from jsDelivr and the models from
- * Google's public MediaPipe model bucket. That is a request to a third party, so an administrator can host them
- * instead (the `mail:videoconf:effects:assets_url` setting, delivered by the join response): the runtime's `wasm/`
- * directory from the `@mediapipe/tasks-vision` package, plus `selfie_segmenter.tflite` and `face_landmarker.task`,
- * all under one base URL.
- *
- * Everything the rest of the pipeline needs from MediaPipe is behind the small `PersonSegmenter`/`FaceTracker`
- * interfaces, so `VideoFilterProcessor` never touches the library and its tests use fakes.
- */
-import type { FaceLandmark } from "./accessories.js";
-
-/** Must match the installed `@mediapipe/tasks-vision` (a test checks): the `.wasm` fetched at runtime has to be the
- * version the JavaScript was built against. */
-export const MEDIAPIPE_VERSION = "1.0.1";
-
-const CDN_WASM = `https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@${MEDIAPIPE_VERSION}/wasm`;
-const CDN_SEGMENTER_MODEL =
-    "https://storage.googleapis.com/mediapipe-models/image_segmenter/selfie_segmenter/float16/latest/selfie_segmenter.tflite";
-const CDN_FACE_MODEL =
-    "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
-
-export interface ModelUrls {
-    wasm: string;
-    segmenter: string;
-    face: string;
-}
-
-/** Where to fetch the runtime and models from - the CDN when `assetsUrl` is empty, else under `assetsUrl`. */
-export function modelUrls(assetsUrl?: string): ModelUrls {
-    if (!assetsUrl) {
-        return { wasm: CDN_WASM, segmenter: CDN_SEGMENTER_MODEL, face: CDN_FACE_MODEL };
-    }
-    const base = assetsUrl.replace(/\/+$/, "");
-    return { wasm: `${base}/wasm`, segmenter: `${base}/selfie_segmenter.tflite`, face: `${base}/face_landmarker.task` };
-}
-
-/** How likely each pixel of a frame is to be the participant, 0-1. */
-export interface PersonMask {
-    width: number;
-    height: number;
-    confidence: Float32Array;
-}
-
-export interface PersonSegmenter {
-    /** Segments `frame`, or `null` when the model produced nothing for it. */
-    segment(frame: HTMLVideoElement, timestampMs: number): PersonMask | null;
-}
-
-export interface FaceTracker {
-    /** The landmarks of the first face in `frame`, or `null` when there is none. */
-    detect(frame: HTMLVideoElement, timestampMs: number): FaceLandmark[] | null;
-}
-
-/** Which of a segmentation model's masks is the person: the one labelled as such (the selfie model's only label is
- * "selfie"), else the last (models list the background first). */
-export function personMaskIndex(labels: string[], maskCount: number): number {
-    const index = labels.findIndex((label) => /person|selfie|foreground/i.test(label));
-    return index >= 0 && index < maskCount ? index : maskCount - 1;
-}
-
-/** MediaPipe rejects a frame whose timestamp isn't later than the last one it saw. */
-function monotonic(): (timestampMs: number) => number {
-    let last = -1;
-    return (timestampMs) => {
-        last = Math.max(timestampMs, last + 1);
-        return last;
-    };
-}
-
-type Vision = typeof import("@mediapipe/tasks-vision");
-
-/** Creates a task on the GPU, or on the CPU when the GPU can't run it (no WebGL, or a driver that refuses). */
-async function withFallback<T>(create: (delegate: "GPU" | "CPU") => Promise<T>): Promise<T> {
-    try {
-        return await create("GPU");
-    } catch {
-        return create("CPU");
-    }
-}
-
-async function loadSegmenter(assetsUrl?: string): Promise<PersonSegmenter> {
-    const urls = modelUrls(assetsUrl);
-    const vision: Vision = await import("@mediapipe/tasks-vision");
-    const fileset = await vision.FilesetResolver.forVisionTasks(urls.wasm);
-    const segmenter = await withFallback((delegate) =>
-        vision.ImageSegmenter.createFromOptions(fileset, {
-            baseOptions: { modelAssetPath: urls.segmenter, delegate },
-            runningMode: "VIDEO",
-            outputConfidenceMasks: true,
-            outputCategoryMask: false,
-        }),
-    );
-    const labels = segmenter.getLabels();
-    const stamp = monotonic();
-    return {
-        segment(frame, timestampMs) {
-            let mask: PersonMask | null = null;
-            segmenter.segmentForVideo(frame, stamp(timestampMs), (result) => {
-                const masks = result.confidenceMasks;
-                if (!masks?.length) {
-                    return;
-                }
-                const person = masks[personMaskIndex(labels, masks.length)];
-                // The mask is only valid inside this callback, so it is copied out.
-                mask = { width: person.width, height: person.height, confidence: new Float32Array(person.getAsFloat32Array()) };
-            });
-            return mask;
-        },
-    };
-}
-
-async function loadFaceTracker(assetsUrl?: string): Promise<FaceTracker> {
-    const urls = modelUrls(assetsUrl);
-    const vision: Vision = await import("@mediapipe/tasks-vision");
-    const fileset = await vision.FilesetResolver.forVisionTasks(urls.wasm);
-    const landmarker = await withFallback((delegate) =>
-        vision.FaceLandmarker.createFromOptions(fileset, {
-            baseOptions: { modelAssetPath: urls.face, delegate },
-            runningMode: "VIDEO",
-            numFaces: 1,
-        }),
-    );
-    const stamp = monotonic();
-    return {
-        detect(frame, timestampMs) {
-            return landmarker.detectForVideo(frame, stamp(timestampMs)).faceLandmarks[0] ?? null;
-        },
-    };
-}
-
-const segmenters = new Map<string, Promise<PersonSegmenter>>();
-const faceTrackers = new Map<string, Promise<FaceTracker>>();
-
-/** Loads `load` once per key, and forgets a failure so the next attempt (a retry) tries again. */
-function shared<T>(cache: Map<string, Promise<T>>, key: string, load: () => Promise<T>): Promise<T> {
-    let pending = cache.get(key);
-    if (!pending) {
-        pending = load();
-        cache.set(key, pending);
-        pending.catch(() => cache.delete(key));
-    }
-    return pending;
-}
-
-/** The person-segmentation model, loaded on first use and shared from then on. Rejects if it can't be loaded. */
-export function createPersonSegmenter(assetsUrl?: string): Promise<PersonSegmenter> {
-    return shared(segmenters, assetsUrl ?? "", () => loadSegmenter(assetsUrl));
-}
-
-/** The face-landmark model, loaded on first use and shared from then on. Rejects if it can't be loaded. */
-export function createFaceTracker(assetsUrl?: string): Promise<FaceTracker> {
-    return shared(faceTrackers, assetsUrl ?? "", () => loadFaceTracker(assetsUrl));
-}
-
-/** Forgets every loaded model - for tests. */
-export function resetModelCache(): void {
-    segmenters.clear();
-    faceTrackers.clear();
-}
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The two machine-learning models behind the filters, run in the browser with MediaPipe Tasks:
+ *
+ * - **Person segmentation** (`createPersonSegmenter`) - which pixels are the participant: what the background
+ * blur and the custom background need.
+ * - **Face landmarks** (`createFaceTracker`) - where the participant's face is: what the accessories need.
+ *
+ * Nothing here is loaded until a participant turns a filter on that needs it, and each model is loaded once and
+ * shared. The MediaPipe library itself is `import()`ed on demand for the same reason - a participant who never uses a
+ * filter never downloads it.
+ *
+ * **Where the assets come from**: by default the WebAssembly runtime is fetched from jsDelivr and the models from
+ * Google's public MediaPipe model bucket. That is a request to a third party, so an administrator can host them
+ * instead (the `mail:videoconf:effects:assets_url` setting, delivered by the join response): the runtime's `wasm/`
+ * directory from the `@mediapipe/tasks-vision` package, plus `selfie_segmenter.tflite` and `face_landmarker.task`,
+ * all under one base URL.
+ *
+ * Everything the rest of the pipeline needs from MediaPipe is behind the small `PersonSegmenter`/`FaceTracker`
+ * interfaces, so `VideoFilterProcessor` never touches the library and its tests use fakes.
+ */
+import type { FaceLandmark } from "./accessories.js";
+
+/** Must match the installed `@mediapipe/tasks-vision` (a test checks): the `.wasm` fetched at runtime has to be the
+ * version the JavaScript was built against. */
+export const MEDIAPIPE_VERSION = "1.0.1";
+
+const CDN_WASM = `https://cdn.jsdelivr.net/npm/@mediapipe/tasks-vision@${MEDIAPIPE_VERSION}/wasm`;
+const CDN_SEGMENTER_MODEL =
+    "https://storage.googleapis.com/mediapipe-models/image_segmenter/selfie_segmenter/float16/latest/selfie_segmenter.tflite";
+const CDN_FACE_MODEL =
+    "https://storage.googleapis.com/mediapipe-models/face_landmarker/face_landmarker/float16/1/face_landmarker.task";
+
+export interface ModelUrls {
+    wasm: string;
+    segmenter: string;
+    face: string;
+}
+
+/** Where to fetch the runtime and models from - the CDN when `assetsUrl` is empty, else under `assetsUrl`. */
+export function modelUrls(assetsUrl?: string): ModelUrls {
+    if (!assetsUrl) {
+        return { wasm: CDN_WASM, segmenter: CDN_SEGMENTER_MODEL, face: CDN_FACE_MODEL };
+    }
+    const base = assetsUrl.replace(/\/+$/, "");
+    return { wasm: `${base}/wasm`, segmenter: `${base}/selfie_segmenter.tflite`, face: `${base}/face_landmarker.task` };
+}
+
+/** How likely each pixel of a frame is to be the participant, 0-1. */
+export interface PersonMask {
+    width: number;
+    height: number;
+    confidence: Float32Array;
+}
+
+export interface PersonSegmenter {
+    /** Segments `frame`, or `null` when the model produced nothing for it. */
+    segment(frame: HTMLVideoElement, timestampMs: number): PersonMask | null;
+}
+
+export interface FaceTracker {
+    /** The landmarks of the first face in `frame`, or `null` when there is none. */
+    detect(frame: HTMLVideoElement, timestampMs: number): FaceLandmark[] | null;
+}
+
+/** Which of a segmentation model's masks is the person: the one labelled as such (the selfie model's only label is
+ * "selfie"), else the last (models list the background first). */
+export function personMaskIndex(labels: string[], maskCount: number): number {
+    const index = labels.findIndex((label) => /person|selfie|foreground/i.test(label));
+    return index >= 0 && index < maskCount ? index : maskCount - 1;
+}
+
+/** MediaPipe rejects a frame whose timestamp isn't later than the last one it saw. */
+function monotonic(): (timestampMs: number) => number {
+    let last = -1;
+    return (timestampMs) => {
+        last = Math.max(timestampMs, last + 1);
+        return last;
+    };
+}
+
+type Vision = typeof import("@mediapipe/tasks-vision");
+
+/** Creates a task on the GPU, or on the CPU when the GPU can't run it (no WebGL, or a driver that refuses). */
+async function withFallback<T>(create: (delegate: "GPU" | "CPU") => Promise<T>): Promise<T> {
+    try {
+        return await create("GPU");
+    } catch {
+        return create("CPU");
+    }
+}
+
+async function loadSegmenter(assetsUrl?: string): Promise<PersonSegmenter> {
+    const urls = modelUrls(assetsUrl);
+    const vision: Vision = await import("@mediapipe/tasks-vision");
+    const fileset = await vision.FilesetResolver.forVisionTasks(urls.wasm);
+    const segmenter = await withFallback((delegate) =>
+        vision.ImageSegmenter.createFromOptions(fileset, {
+            baseOptions: { modelAssetPath: urls.segmenter, delegate },
+            runningMode: "VIDEO",
+            outputConfidenceMasks: true,
+            outputCategoryMask: false,
+        }),
+    );
+    const labels = segmenter.getLabels();
+    const stamp = monotonic();
+    return {
+        segment(frame, timestampMs) {
+            let mask: PersonMask | null = null;
+            segmenter.segmentForVideo(frame, stamp(timestampMs), (result) => {
+                const masks = result.confidenceMasks;
+                if (!masks?.length) {
+                    return;
+                }
+                const person = masks[personMaskIndex(labels, masks.length)];
+                // The mask is only valid inside this callback, so it is copied out.
+                mask = { width: person.width, height: person.height, confidence: new Float32Array(person.getAsFloat32Array()) };
+            });
+            return mask;
+        },
+    };
+}
+
+async function loadFaceTracker(assetsUrl?: string): Promise<FaceTracker> {
+    const urls = modelUrls(assetsUrl);
+    const vision: Vision = await import("@mediapipe/tasks-vision");
+    const fileset = await vision.FilesetResolver.forVisionTasks(urls.wasm);
+    const landmarker = await withFallback((delegate) =>
+        vision.FaceLandmarker.createFromOptions(fileset, {
+            baseOptions: { modelAssetPath: urls.face, delegate },
+            runningMode: "VIDEO",
+            numFaces: 1,
+        }),
+    );
+    const stamp = monotonic();
+    return {
+        detect(frame, timestampMs) {
+            return landmarker.detectForVideo(frame, stamp(timestampMs)).faceLandmarks[0] ?? null;
+        },
+    };
+}
+
+const segmenters = new Map<string, Promise<PersonSegmenter>>();
+const faceTrackers = new Map<string, Promise<FaceTracker>>();
+
+/** Loads `load` once per key, and forgets a failure so the next attempt (a retry) tries again. */
+function shared<T>(cache: Map<string, Promise<T>>, key: string, load: () => Promise<T>): Promise<T> {
+    let pending = cache.get(key);
+    if (!pending) {
+        pending = load();
+        cache.set(key, pending);
+        pending.catch(() => cache.delete(key));
+    }
+    return pending;
+}
+
+/** The person-segmentation model, loaded on first use and shared from then on. Rejects if it can't be loaded. */
+export function createPersonSegmenter(assetsUrl?: string): Promise<PersonSegmenter> {
+    return shared(segmenters, assetsUrl ?? "", () => loadSegmenter(assetsUrl));
+}
+
+/** The face-landmark model, loaded on first use and shared from then on. Rejects if it can't be loaded. */
+export function createFaceTracker(assetsUrl?: string): Promise<FaceTracker> {
+    return shared(faceTrackers, assetsUrl ?? "", () => loadFaceTracker(assetsUrl));
+}
+
+/** Forgets every loaded model - for tests. */
+export function resetModelCache(): void {
+    segmenters.clear();
+    faceTrackers.clear();
+}

package/apps/shared/relay/AudioPlayer.ts

@@ -2,9 +2,14 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
+import type { RelayReceiveDiagnostics } from "../webrtc/types.js";
 import { TimestampUnwrapper, type Frame } from "./frames.js";
 import type { AudioContextLike, AudioDataLike, DecoderLike, RelayEnv } from "./relayEnv.js";
 import { safeClose } from "./senderCommon.js";
+import { SilenceMeter } from "./SilenceMeter.js";
+
+/** The playback half of `RelayReceiveDiagnostics.audio`. */
+export type AudioPlaybackStats = Pick<RelayReceiveDiagnostics["audio"], "playedMs" | "silentMs" | "gaps" | "gapMs" | "droppedLate" | "bufferedMs">;
 
 export const PLAYBACK_SAMPLE_RATE = 48_000;
 /** How far ahead of the clock the first packet after a start or an underrun is scheduled. It is the jitter buffer:
@@ -42,6 +47,10 @@ export class AudioPlayer {
     private decoder: DecoderLike | undefined;
     private nextTime = 0;
     private readonly timestamps = new TimestampUnwrapper();
+    private readonly played = new SilenceMeter();
+    private gaps = 0;
+    private gapSeconds = 0;
+    private droppedLate = 0;
 
     /** `destination` is the node whose stream the peer's `MediaStream` carries. */
     constructor(
@@ -50,10 +59,23 @@ export class AudioPlayer {
         private readonly destination: unknown,
     ) {}
 
+    /** What playback has done so far - see `RelayReceiveDiagnostics`. */
+    stats(): AudioPlaybackStats {
+        return {
+            playedMs: this.played.totalMs,
+            silentMs: this.played.silentMs,
+            gaps: this.gaps,
+            gapMs: this.gapSeconds * 1000,
+            droppedLate: this.droppedLate,
+            bufferedMs: Math.max(0, this.nextTime - this.ctx.currentTime) * 1000,
+        };
+    }
+
     /** Feeds one reassembled audio frame (one Opus packet). */
     push(frame: Frame): void {
         const decoder = this.decoder ?? this.createDecoder();
         if (!decoder || decoder.decodeQueueSize > AUDIO_MAX_DECODE_QUEUE) {
+            this.droppedLate += 1;
             return;
         }
         try {
@@ -101,6 +123,7 @@ export class AudioPlayer {
         try {
             const now = this.ctx.currentTime;
             if (this.nextTime - now > MAX_AHEAD_SECONDS) {
+                this.droppedLate += 1;
                 return;
             }
             const buffer = this.ctx.createBuffer(1, data.numberOfFrames, data.sampleRate);
@@ -127,6 +150,12 @@ export class AudioPlayer {
                 source.onended = () => source.disconnect();
             }
             source.start(start);
+            this.played.feed(pcm, data.sampleRate);
+            if (start > this.nextTime && this.nextTime > 0) {
+                // Playback ran dry: everything between the end of the last block and this one is silence.
+                this.gaps += 1;
+                this.gapSeconds += start - this.nextTime;
+            }
             this.nextTime = start + buffer.duration;
         } catch {
             // A block the browser will not take (an odd sample rate, a closed context) is dropped like a lost packet.

package/apps/shared/relay/AudioSender.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz. All rights reserved.
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
+import type { RelaySendDiagnostics } from "../webrtc/types.js";
 import { resumeAudioContext } from "./audioResume.js";
 import { KIND_AUDIO } from "./frames.js";
 import type {
@@ -14,6 +15,7 @@ import type {
     ScriptProcessorLike,
 } from "./relayEnv.js";
 import { safeClose, type SenderDeps } from "./senderCommon.js";
+import { SilenceMeter } from "./SilenceMeter.js";
 
 export const AUDIO_SAMPLE_RATE = 48_000;
 /** Frames per `ScriptProcessorNode` callback: about 43 ms, a compromise between latency and how often the main
@@ -53,8 +55,24 @@ export class AudioSender {
     private baseMs = 0;
     private samples = 0;
 
+    /** Diagnostics, cumulative across capture sessions: what the capture path delivered (and how much of it was
+     * silent), the wall-clock time it was attached for, and what the encoder had to skip. */
+    private readonly captured = new SilenceMeter();
+    private wallMs = 0;
+    private encoderSkippedSamples = 0;
+
     constructor(private readonly deps: SenderDeps) {}
 
+    /** The capture half of `RelaySendDiagnostics`. */
+    captureStats(): Pick<RelaySendDiagnostics, "audioCapturedMs" | "audioCaptureWallMs" | "audioSilentMs" | "audioEncoderSkippedMs"> {
+        return {
+            audioCapturedMs: this.captured.totalMs,
+            audioCaptureWallMs: this.wallMs + (this.attachedTrack ? this.deps.env.now() - this.baseMs : 0),
+            audioSilentMs: this.captured.silentMs,
+            audioEncoderSkippedMs: (this.encoderSkippedSamples * 1000) / AUDIO_SAMPLE_RATE,
+        };
+    }
+
     setActive(active: boolean): void {
         this.active = active;
         this.sync();
@@ -105,6 +123,9 @@ export class AudioSender {
     }
 
     private detach(): void {
+        if (this.attachedTrack) {
+            this.wallMs += this.deps.env.now() - this.baseMs;
+        }
         this.attachedTrack = null;
         this.stopResume?.();
         this.stopResume = undefined;
@@ -132,11 +153,13 @@ export class AudioSender {
         const samples = input.length;
         const timestampUs = Math.round((this.samples * 1_000_000) / AUDIO_SAMPLE_RATE);
         this.samples += samples;
+        this.captured.feed(input, AUDIO_SAMPLE_RATE);
         if (!this.deps.canSend()) {
             return;
         }
         const encoder = this.encoder ?? this.createEncoder();
         if (!encoder || encoder.encodeQueueSize > AUDIO_MAX_ENCODE_QUEUE) {
+            this.encoderSkippedSamples += samples;
             return;
         }
         let audio: AudioDataLike | undefined;

package/apps/shared/relay/RelayClient.ts

@@ -13,13 +13,18 @@
  * older one, which accepts `MAX_MESSAGE_BYTES`). Nothing else may be sent before `ready`.
  * - `{"op":"want","peers":[...]}` REPLACES the set of senders this socket receives from (the server accepts at most
  * `MAX_WANTED_PEERS`). It has to be re-sent after every reconnect, because the server's set dies with the socket.
+ * - `{"op":"ping","t":<this client's clock>}`, every `RELAY_PING_INTERVAL_MS` once ready, is answered with
+ * `{"op":"pong","t":<the same>}`, which times the round trip to the server (`roundTripMs`) - over the same socket as
+ * the media, so it includes whatever the media has queued ahead of it. An older server ignores the ping and the
+ * round trip stays unknown.
  * - A binary message from the client is an opaque payload of at most `maxMessageBytes`. The server forwards it to
  * every socket that wants this sender as `[1 byte N][N bytes UTF-8 sender peer id][payload]`, stamping the sender
  * itself so a peer cannot speak as another.
  * - Binary messages may be dropped under backpressure and the socket may close at any moment, so this client
  * reconnects with exponential backoff and treats every media send as best effort.
  *
- * Authentication is the `jwt` cookie already in place (see `GuestSignalingClient`), so this client sets no cookie.
+ * Authentication is the `jwt` cookie already in place (see `../signaling/SignalingClient.ts`), so this client sets no
+ * cookie.
  */
 import { DEFAULT_MESSAGE_BYTES } from "./frames.js";
 import type { RelaySocket } from "./relayEnv.js";
@@ -48,6 +53,9 @@ export const RELAY_BACKOFF_MAX_MS = 15_000;
 /** How long a socket may take to become `ready` before it is abandoned and retried (a server that accepts the
  * upgrade but never answers the hello would otherwise hang the tier forever). */
 export const RELAY_HANDSHAKE_TIMEOUT_MS = 10_000;
+/** How often a ready socket pings the server to time the round trip - often enough that the diagnostics panel (which
+ * polls every few seconds) always has a recent sample, rarely enough to cost nothing next to the media. */
+export const RELAY_PING_INTERVAL_MS = 2_000;
 
 const SOCKET_OPEN = 1;
 
@@ -56,6 +64,8 @@ export interface RelayClientOptions {
     peerId: string;
     createSocket: (url: string) => RelaySocket;
     random: () => number;
+    /** A monotonic millisecond clock for timing pings. Defaults to `Date.now`. */
+    now?: () => number;
     /** Called with the sender's peer id (as stamped by the server) and the original payload. */
     onMedia: (peerId: string, payload: Uint8Array) => void;
 }
@@ -82,6 +92,8 @@ export class RelayClient {
     private wanted: string[] = [];
     private reconnectTimer: ReturnType<typeof setTimeout> | undefined;
     private handshakeTimer: ReturnType<typeof setTimeout> | undefined;
+    private pingTimer: ReturnType<typeof setInterval> | undefined;
+    private lastRoundTripMs: number | undefined;
     private readonly decoder = new TextDecoder();
 
     constructor(private readonly options: RelayClientOptions) {}
@@ -91,6 +103,12 @@ export class RelayClient {
         return this.isReady;
     }
 
+    /** The most recent ping's round trip to the server, in milliseconds - `undefined` until the first pong on the
+     * current socket (and for good on a server too old to answer pings). */
+    get roundTripMs(): number | undefined {
+        return this.lastRoundTripMs;
+    }
+
     /** The largest message `sendMedia()` will send: what the server announced in `ready` (validated and clamped), or
      * `MAX_MESSAGE_BYTES` before that, without one, and again after every disconnect until the next `ready`. The
      * frame fragmenter sizes its fragments from this. */
@@ -148,6 +166,7 @@ export class RelayClient {
         clearTimeout(this.reconnectTimer);
         clearTimeout(this.handshakeTimer);
         this.reconnectTimer = this.handshakeTimer = undefined;
+        this.stopPinging();
         this.detach();
     }
 
@@ -200,7 +219,15 @@ export class RelayClient {
         } catch {
             return;
         }
-        if (!message || typeof message !== "object" || (message as { op?: unknown }).op !== "ready" || this.isReady) {
+        if (!message || typeof message !== "object") {
+            return;
+        }
+        const op = (message as { op?: unknown }).op;
+        if (op === "pong") {
+            this.handlePong((message as { t?: unknown }).t);
+            return;
+        }
+        if (op !== "ready" || this.isReady) {
             return;
         }
         this.isReady = true;
@@ -213,6 +240,30 @@ export class RelayClient {
         this.handshakeTimer = undefined;
         // The server's wanted set is per socket, so it starts empty on every (re)connect.
         this.sendText({ op: "want", peers: this.wanted });
+        this.pingTimer = setInterval(() => this.sendText({ op: "ping", t: this.now() }), RELAY_PING_INTERVAL_MS);
+    }
+
+    /** Times the round trip of the ping that `t` came back from. Ignored before ready, for a `t` that isn't a number,
+     * or one from the future (nothing this client sent). */
+    private handlePong(t: unknown): void {
+        if (!this.isReady || typeof t !== "number") {
+            return;
+        }
+        const roundTrip = this.now() - t;
+        if (roundTrip >= 0) {
+            this.lastRoundTripMs = roundTrip;
+        }
+    }
+
+    private now(): number {
+        return (this.options.now ?? Date.now)();
+    }
+
+    /** Stops pinging and forgets the last round trip - it described a socket that is gone. */
+    private stopPinging(): void {
+        clearInterval(this.pingTimer);
+        this.pingTimer = undefined;
+        this.lastRoundTripMs = undefined;
     }
 
     private handleClose(socket: RelaySocket): void {
@@ -220,6 +271,7 @@ export class RelayClient {
             return;
         }
         this.isReady = false;
+        this.stopPinging();
         // The next server might be a different one (a rolling upgrade), so the limit is learned afresh.
         this.messageLimit = MAX_MESSAGE_BYTES;
         clearTimeout(this.handshakeTimer);