@rapidmx/meet-plugin 0.14.1 → 0.15.0

package/apps/meet/_CallControls.tsx

@@ -21,8 +21,11 @@
  * their own: "Diagnostics" (`onOpenDiagnostics`) and "Settings" (`onOpenSettings`, host-only) each open their own
  * persistent window/modal in `_CallView.tsx` and close this menu; "Connection method" is a four-way
  * `menuitemradio` group (`TransportMode` - see `MeshConnectionManager.setTransportMode()`'s own doc comment)
- * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen. Otherwise an
- * ordinary menu of this bar's own shape (`openMenu`, closes on Escape/outside click like every other one here).
+ * forcing how *this tab's* media reaches everyone else, independent of what anyone else has chosen; "Hide self"/
+ * "Show self" (`selfHidden`/`onToggleSelfHidden`) is the only way to bring the local tile back once hidden from
+ * grid view, where there's no tile left to offer its own "show" control - see `_CallView.tsx`'s doc comment on
+ * where the local tile appears. Otherwise an ordinary menu of this bar's own shape (`openMenu`, closes on
+ * Escape/outside click like every other one here).
  */
 import React, { useEffect, useRef, useState } from "react";
 import { filtersActive } from "../shared/media/filters/filterTypes.js";
@@ -86,6 +89,10 @@ export interface CallControlsProps {
     onSetTransportMode: (mode: TransportMode) => void;
     onOpenDiagnostics: () => void;
     onOpenSettings: () => void;
+    /** Whether the local tile is currently hidden - the "…" menu's "Hide self"/"Show self" item reflects and
+     * toggles this; see `_CallView.tsx`'s doc comment on where the local tile appears. */
+    selfHidden: boolean;
+    onToggleSelfHidden: () => void;
     onLeave: () => void;
 }
 
@@ -131,6 +138,8 @@ export default function CallControls({
     onSetTransportMode,
     onOpenDiagnostics,
     onOpenSettings,
+    selfHidden,
+    onToggleSelfHidden,
     onLeave,
 }: CallControlsProps) {
     const [openMenu, setOpenMenu] = useState<OpenMenu>(null);
@@ -364,6 +373,17 @@ export default function CallControls({
                         >
                             Diagnostics
                         </button>
+                        <button
+                            type="button"
+                            role="menuitem"
+                            className="w-full px-3 py-2 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                            onClick={() => {
+                                onToggleSelfHidden();
+                                setOpenMenu(null);
+                            }}
+                        >
+                            {selfHidden ? "Show self" : "Hide self"}
+                        </button>
                         <div className="my-1 border-t border-white/10" />
                         <p className="px-3 pt-1 pb-0.5 text-xs font-semibold uppercase tracking-wide text-white/60">Connection method</p>
                         {TRANSPORT_MODE_OPTIONS.map(({ mode, label }) => (

package/apps/meet/_CallView.tsx

@@ -15,10 +15,24 @@
  *
  * The call fills the viewport (`fixed inset-0`) as three rows - a slim header, the tiles (which take whatever room
  * is left and never scroll the page), and the control bar pinned to the bottom - instead of being laid out inside
- * the branded page shell, whose header, footer and padding pushed it off the screen. The local participant's own
- * tile is a small tile in the bottom-right corner while anyone else is in the call (above the control bar on a narrower
- * window, and at the top on a phone, where the bar wraps onto a second row), and fills the tile area while they are
- * alone.
+ * the branded page shell, whose header, footer and padding pushed it off the screen.
+ *
+ * ## Where the local tile appears
+ *
+ * In plain grid view (not focus, not presenting), the local tile is an ordinary member of the grid, same size as
+ * everyone else's, rather than a floating corner overlay - so with exactly two participants, the local tile is
+ * genuinely one of the two grid cells, not a small picture-in-picture over the other person's. The floating corner
+ * tile (above the control bar on a narrower window, at the top on a phone, where the bar wraps onto a second row)
+ * is reserved for focus/presentation layouts, where there's already a single large tile the local one would
+ * otherwise compete with for space. Either way, alone in the call, the local tile simply fills the whole stage
+ * (see the `alone` branch of the `stage` computation).
+ *
+ * `selfHidden` (`handleHideSelf()`/`handleToggleSelfHidden()`) removes the local tile from view entirely, wherever
+ * it would otherwise appear - set from the tile's own corner "…" menu (`_ParticipantTile.tsx`'s `onHideSelf`, one
+ * directional: there's no tile left to click "show" on once it's gone) or toggled back on from the navbar's own
+ * "…" menu (`_CallControls.tsx`), which is the only way to re-show it from grid view, where there'd otherwise be
+ * nothing left bearing a "show self" control. Never honored while `alone`: hiding the only tile on screen would
+ * just blank it, so the local tile ignores `selfHidden` there and always shows.
  *
  * ## Who is heard
  *
@@ -223,6 +237,7 @@ export default function CallView({
     const [diagnosticsOpen, setDiagnosticsOpen] = useState(false);
     const [settingsOpen, setSettingsOpen] = useState(false);
     const [transportMode, setTransportModeState] = useState<TransportMode>("auto");
+    const [selfHidden, setSelfHidden] = useState(false);
 
     const managerRef = useRef<MeshConnectionManager | null>(null);
     /** The raw capture from `getDisplayMedia()` - only ever used to stop it (releasing the OS's own share
@@ -469,6 +484,17 @@ export default function CallView({
         setHandRaised((prev) => !prev);
     }
 
+    /** Hides the local tile - the tile's own "…" menu calls this directly (one-directional: there is no "show
+     * self" from in-grid, since a hidden tile isn't there to click on). Re-showing it is the navbar "…" menu's
+     * `handleToggleSelfHidden()` instead. */
+    function handleHideSelf() {
+        setSelfHidden(true);
+    }
+
+    function handleToggleSelfHidden() {
+        setSelfHidden((prev) => !prev);
+    }
+
     function handleReaction(emoji: string) {
         if (managerRef.current?.sendReaction(emoji)) {
             showReaction(emoji, "You");
@@ -636,7 +662,7 @@ export default function CallView({
         />
     );
 
-    const selfTile = (className?: string) => (
+    const selfTile = (className?: string, canHide?: boolean) => (
         <ParticipantTile
             name={selfName}
             stream={media.videoStream}
@@ -648,6 +674,7 @@ export default function CallView({
             // A custom background is a fixed picture, not a live reflection - mirroring it would show it backwards
             // to no one but the participant themselves (see `_ParticipantTile.tsx`'s doc comment).
             mirrored={media.filters.background !== "image"}
+            onHideSelf={canHide ? handleHideSelf : undefined}
             className={className}
         />
     );
@@ -657,7 +684,8 @@ export default function CallView({
 
     let stage: React.ReactNode;
     if (alone) {
-        // Nobody else yet: the local participant fills the tile area, presenting or not.
+        // Nobody else yet: the local participant fills the tile area, presenting or not - and is never hideable,
+        // since there'd be nothing left to look at (see this module's doc comment on hiding the local tile).
         stage = isPresenting ? (
             <ParticipantTile name={selfName} stream={screenStream} isLocal contain isFocused className="h-full" />
         ) : (
@@ -685,8 +713,11 @@ export default function CallView({
             </div>
         );
     } else {
+        // Plain grid, nobody presenting: the local tile joins the grid as an ordinary tile (unless hidden) instead
+        // of floating in a corner - see this module's doc comment.
         stage = (
             <div className="h-full grid gap-2 auto-rows-fr [grid-template-columns:repeat(auto-fit,minmax(min(100%,320px),1fr))]">
+                {!selfHidden && selfTile("h-full", true)}
                 {participants.map((p) => remoteTile(p, "h-full"))}
             </div>
         );
@@ -769,6 +800,8 @@ export default function CallView({
                         viewMode={viewMode}
                         onToggleViewMode={() => setViewMode((prev) => (prev === "grid" ? "focus" : "grid"))}
                         micLocked={micLocked}
+                        selfHidden={selfHidden}
+                        onToggleSelfHidden={handleToggleSelfHidden}
                         isHost={isHost}
                         transportMode={transportMode}
                         onSetTransportMode={handleSetTransportMode}
@@ -778,12 +811,12 @@ export default function CallView({
                     />
                 </footer>
 
-                {!alone && (
+                {!alone && !selfHidden && showFocusLayout && (
                     <div
                         className="absolute z-10 right-3 top-14 w-28 sm:top-auto sm:bottom-24 sm:w-52 aspect-video shadow-xl xl:right-4 xl:bottom-4"
                         data-testid="self-view"
                     >
-                        {selfTile("h-full")}
+                        {selfTile("h-full", true)}
                     </div>
                 )}
 

package/apps/meet/_DiagnosticsPanel.tsx

@@ -10,12 +10,14 @@
  * (`MeshParticipant.diagnostics`, refreshed every few seconds by `MeshConnectionManager`'s own poller - see its doc
  * comment). Purely informational and entirely local: nothing here is sent anywhere.
  *
- * `diagnostics` is `undefined` until the first poll completes (shortly after a connection comes up) and always
- * absent for a `"websocket"`-relayed participant (there is no `RTCPeerConnection` to poll there) - both cases show
- * "Not available" rather than a blank space, so it never looks like the panel forgot to load.
+ * `diagnostics` is `undefined` until the first poll completes (shortly after a connection comes up, or the pair moves
+ * to the server relay), shown as "Not available yet" rather than a blank space, so it never looks like the panel
+ * forgot to load. For a `"websocket"`-relayed participant the round trip is this browser's own leg to the relay
+ * server (the relay has no direct path to the peer), and the relay's own counters follow (`RelayRows`): how much of this browser's microphone audio the capture path
+ * delivered and how much of it was digital silence, and how this peer's audio is playing back here.
  */
 import React from "react";
-import type { MeshParticipant } from "../shared/webrtc/types.js";
+import type { MeshParticipant, RelayDiagnostics } from "../shared/webrtc/types.js";
 import { TRANSPORT_BADGES } from "./_ParticipantTile.js";
 
 export interface DiagnosticsPanelProps {
@@ -64,6 +66,59 @@ function StreamRow({ kind, packetsLost, jitter, bytesSent, bytesReceived }: { ki
     );
 }
 
+/** `part` as a whole-number percentage of `whole`, or "—" when there is no whole yet. */
+function percent(part: number, whole: number): string {
+    return whole > 0 ? `${Math.round((part / whole) * 100)}%` : "—";
+}
+
+function plural(count: number, noun: string): string {
+    return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+/** The server relay's own counters (see `RelayDiagnostics`). The capture row is this browser's own microphone, the
+ * playback row this peer's audio as heard here - so a mostly silent capture points at the sender, silence arriving in
+ * playback with no capture problem points at the other end's capture, and gaps point at the network. */
+function RelayRows({ relay }: { relay: RelayDiagnostics }) {
+    const { send, receive } = relay;
+    const notSent = send.audio.framesDropped + send.video.framesDropped;
+    return (
+        <>
+            {send.audioCaptureWallMs > 0 && (
+                <div className={ROW}>
+                    <span className={LABEL}>Your mic capture</span>
+                    <span>
+                        {percent(send.audioCapturedMs, send.audioCaptureWallMs)} of real time · {percent(send.audioSilentMs, send.audioCapturedMs)} silent
+                        {send.audioEncoderSkippedMs > 0 && ` · ${formatMs(send.audioEncoderSkippedMs / 1000)} skipped`}
+                    </span>
+                </div>
+            )}
+            {notSent > 0 && (
+                <div className={ROW}>
+                    <span className={LABEL}>Not sent</span>
+                    <span>
+                        {send.audio.framesDropped} audio · {send.video.framesDropped} video frames
+                    </span>
+                </div>
+            )}
+            {receive && (
+                <div className={ROW}>
+                    <span className={LABEL}>Playback</span>
+                    <span>
+                        {`${percent(receive.audio.silentMs, receive.audio.playedMs)} silent · ${plural(receive.audio.gaps, "gap")} ` +
+                            `(${formatMs(receive.audio.gapMs / 1000)}) · ${formatMs(receive.audio.bufferedMs / 1000)} buffered`}
+                    </span>
+                </div>
+            )}
+            {receive && receive.audio.droppedLate > 0 && (
+                <div className={ROW}>
+                    <span className={LABEL}>Dropped late</span>
+                    <span>{plural(receive.audio.droppedLate, "packet")}</span>
+                </div>
+            )}
+        </>
+    );
+}
+
 export default function DiagnosticsPanel({ selfName, micOn, cameraOn, participants }: DiagnosticsPanelProps) {
     return (
         <div className="text-sm">
@@ -93,16 +148,19 @@ export default function DiagnosticsPanel({ selfName, micOn, cameraOn, participan
                             <span className={LABEL}>Connection</span>
                             <span title={badge?.title}>{badge?.label ?? (p.transport === "connecting" ? "Connecting…" : "Direct")}</span>
                         </div>
-                        {p.transport === "websocket" || !p.diagnostics ? (
-                            <p className={`${LABEL} py-0.5`}>Not available{p.transport !== "websocket" && " yet"}.</p>
+                        {!p.diagnostics ? (
+                            <p className={`${LABEL} py-0.5`}>Not available yet.</p>
                         ) : (
                             <>
                                 <div className={ROW}>
-                                    <span className={LABEL}>Round-trip time</span>
+                                    <span className={LABEL} title={p.diagnostics.relay ? "From this browser to the relay server and back" : undefined}>
+                                        {p.diagnostics.relay ? "Round-trip to server" : "Round-trip time"}
+                                    </span>
                                     <span>{formatMs(p.diagnostics.roundTripTimeSeconds)}</span>
                                 </div>
                                 <StreamRow kind="Audio" {...p.diagnostics.audio} />
                                 <StreamRow kind="Video" {...p.diagnostics.video} />
+                                {p.diagnostics.relay && <RelayRows relay={p.diagnostics.relay} />}
                             </>
                         )}
                     </div>

package/apps/meet/_ParticipantTile.tsx

@@ -14,10 +14,13 @@
  * natural - this is a local display transform only, never applied to the video actually sent to anyone, so
  * everyone else always sees the participant the right way round. `mirrored={false}` (`_CallView.tsx`, when a custom
  * background image is on) turns that off: the picture the participant chose is a fixed reference, not a live
- * reflection, and mirroring it would show it backwards to no one but themselves. */
-import React, { useEffect, useRef } from "react";
+ * reflection, and mirroring it would show it backwards to no one but themselves.
+ *
+ * `onHideSelf` adds a small "…" menu to the tile's corner, local-tile-only - see `_CallView.tsx`'s doc comment on
+ * hiding the local tile from grid view. */
+import React, { useEffect, useRef, useState } from "react";
 import type { MediaTransport } from "../shared/webrtc/types.js";
-import { MicOffIcon } from "./_icons.js";
+import { MicOffIcon, OverflowIcon } from "./_icons.js";
 
 /** What a tile says about how its participant's media is arriving, for the paths that are not the ordinary direct one
  * (which needs no comment). Text rather than only an icon, so the reason a picture is degraded is never a guess.
@@ -74,6 +77,10 @@ export interface ParticipantTileProps {
     /** Whether the local tile is shown mirrored, like a real mirror - ignored for a remote tile, which is never
      * mirrored. Default `true`; see this module's doc comment. */
     mirrored?: boolean;
+    /** Offers a small "…" menu in the tile's top-right corner with one item, "Hide self" - see `_CallView.tsx`'s
+     * doc comment on hiding the local tile. Omitted everywhere that shouldn't offer it: every remote tile, and the
+     * local tile while alone in the call, where hiding it would just blank the only thing on screen. */
+    onHideSelf?: () => void;
     onClick?: () => void;
     className?: string;
 }
@@ -94,12 +101,15 @@ export default function ParticipantTile({
     isFocused,
     contain,
     mirrored = true,
+    onHideSelf,
     onClick,
     className,
 }: ParticipantTileProps) {
     const badge = transport ? TRANSPORT_BADGES[transport] : undefined;
     const videoRef = useRef<HTMLVideoElement>(null);
     const showVideo = !!stream && !cameraOff;
+    const [hideMenuOpen, setHideMenuOpen] = useState(false);
+    const hideMenuRef = useRef<HTMLDivElement>(null);
 
     // The `<video>` element only exists while `showVideo`, so its stream is bound whenever it (re)appears too.
     useEffect(() => {
@@ -108,6 +118,30 @@ export default function ParticipantTile({
         }
     }, [stream, showVideo]);
 
+    // The tile's own "…" menu closes on Escape or a press anywhere outside it, same shape as every other menu in
+    // this app.
+    useEffect(() => {
+        if (!hideMenuOpen) {
+            return;
+        }
+        const onPointerDown = (event: PointerEvent) => {
+            if (!hideMenuRef.current?.contains(event.target as Node)) {
+                setHideMenuOpen(false);
+            }
+        };
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.key === "Escape") {
+                setHideMenuOpen(false);
+            }
+        };
+        document.addEventListener("pointerdown", onPointerDown);
+        document.addEventListener("keydown", onKeyDown);
+        return () => {
+            document.removeEventListener("pointerdown", onPointerDown);
+            document.removeEventListener("keydown", onKeyDown);
+        };
+    }, [hideMenuOpen]);
+
     return (
         <div
             className={`relative overflow-hidden rounded-xl bg-[#3c4043] flex items-center justify-center min-h-[90px] ${
@@ -142,12 +176,51 @@ export default function ParticipantTile({
                     ✋
                 </span>
             )}
-            {micMuted && (
-                <span className="absolute top-2 right-2 flex items-center justify-center w-7 h-7 rounded-full bg-black/60 text-white" role="img" aria-label="Muted">
-                    <span className="w-4 h-4 [&>svg]:w-4 [&>svg]:h-4">
-                        <MicOffIcon />
-                    </span>
-                </span>
+            {(micMuted || onHideSelf) && (
+                <div className="absolute top-2 right-2 flex items-center gap-1">
+                    {micMuted && (
+                        <span className="flex items-center justify-center w-7 h-7 rounded-full bg-black/60 text-white" role="img" aria-label="Muted">
+                            <span className="w-4 h-4 [&>svg]:w-4 [&>svg]:h-4">
+                                <MicOffIcon />
+                            </span>
+                        </span>
+                    )}
+                    {onHideSelf && (
+                        <div className="relative" ref={hideMenuRef}>
+                            <button
+                                type="button"
+                                className="flex items-center justify-center w-7 h-7 rounded-full bg-black/60 hover:bg-black/80 text-white focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                                aria-label="Local video options"
+                                aria-haspopup="menu"
+                                aria-expanded={hideMenuOpen}
+                                onClick={() => setHideMenuOpen((prev) => !prev)}
+                            >
+                                <span className="w-4 h-4 [&>svg]:w-4 [&>svg]:h-4">
+                                    <OverflowIcon />
+                                </span>
+                            </button>
+                            {hideMenuOpen && (
+                                <div
+                                    role="menu"
+                                    aria-label="Local video options"
+                                    className="absolute top-full right-0 mt-1 w-32 rounded-xl bg-[#2b2d30] text-white shadow-xl py-1 text-sm"
+                                >
+                                    <button
+                                        type="button"
+                                        role="menuitem"
+                                        className="w-full px-3 py-1.5 text-left hover:bg-white/10 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                                        onClick={() => {
+                                            setHideMenuOpen(false);
+                                            onHideSelf();
+                                        }}
+                                    >
+                                        Hide self
+                                    </button>
+                                </div>
+                            )}
+                        </div>
+                    )}
+                </div>
             )}
             {badge && (
                 <span

package/apps/meet/_ParticipantsDrawer.tsx

@@ -35,7 +35,7 @@ import React, { useEffect } from "react";
 import type { MeshParticipant } from "../shared/webrtc/types.js";
 import type { WaitingParticipant } from "./_meetApi.js";
 import { TRANSPORT_BADGES } from "./_ParticipantTile.js";
-import { MicOffIcon } from "./_icons.js";
+import { BatonIcon, MicOffIcon, RemoveIcon } from "./_icons.js";
 
 export interface ParticipantsDrawerProps {
     selfName: string;
@@ -184,35 +184,38 @@ function Row({
             {canGiveStick && !hasStick && (
                 <button
                     type="button"
-                    className="px-2 py-0.5 rounded text-xs whitespace-nowrap bg-white/10 hover:bg-white/20 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                    className="w-7 h-7 flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80 [&>svg]:w-4 [&>svg]:h-4"
                     aria-label={`Give the talking stick to ${name}`}
+                    title={`Give the talking stick to ${name}`}
                     onClick={onGiveStick}
                 >
-                    Give stick
+                    <BatonIcon />
                 </button>
             )}
             {canModerate && !micMuted && (
                 <button
                     type="button"
-                    className="px-2 py-0.5 rounded text-xs whitespace-nowrap bg-white/10 hover:bg-white/20 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                    className="w-7 h-7 flex items-center justify-center rounded-full bg-white/10 hover:bg-white/20 focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80 [&>svg]:w-4 [&>svg]:h-4"
                     aria-label={`Mute ${name}`}
+                    title={`Mute ${name}`}
                     onClick={onMute}
                 >
-                    Mute
+                    <MicOffIcon />
                 </button>
             )}
             {canModerate && (
                 <button
                     type="button"
-                    className="px-2 py-0.5 rounded text-xs whitespace-nowrap bg-[#601410] text-[#f9dedc] hover:bg-[#7a1b16] focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80"
+                    className="w-7 h-7 flex items-center justify-center rounded-full bg-[#601410] text-[#f9dedc] hover:bg-[#7a1b16] focus:outline-none focus-visible:ring-2 focus-visible:ring-white/80 [&>svg]:w-4 [&>svg]:h-4"
                     aria-label={`Remove ${name}`}
+                    title={`Remove ${name}`}
                     onClick={() => {
                         if (window.confirm(`Remove ${name} from the call?`)) {
                             onKick?.();
                         }
                     }}
                 >
-                    Remove
+                    <RemoveIcon />
                 </button>
             )}
         </li>

package/apps/meet/_icons.tsx

@@ -78,3 +78,13 @@ export const BatonIcon = () => (
 );
 
 export const OverflowIcon = () => <Icon path="M6 10c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm12 0c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2zm-6 0c-1.1 0-2 .9-2 2s.9 2 2 2 2-.9 2-2-.9-2-2-2z" />;
+
+/** A plain "X" - removing a participant from the call (the participants drawer's "Remove" row button). Drawn with
+ * strokes rather than a filled Material path, same "simple primitives, not a recalled path" reasoning as
+ * `BatonIcon`. */
+export const RemoveIcon = () => (
+    <svg viewBox="0 0 24 24" className="w-6 h-6" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true" focusable="false">
+        <line x1="6" y1="6" x2="18" y2="18" />
+        <line x1="18" y1="6" x2="6" y2="18" />
+    </svg>
+);

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;