From a8217e56cb12a858e85fd1a2333506330d660abd Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 22:31:47 -0800
Subject: [PATCH 01/37] egocap: preview Orin cameras directly from LiveKit in
 the browser

Add an optional livekit_preview station section, GET /api/livekit-preview
(room, publisher, tracks and a subscribe-only viewer token), and browser
video tiles that subscribe to the configured publisher's tracks. The
backend never decodes or relays video, and these cameras are preview-only:
they are not requested from CaptureServer and are not recorded.

Not exercised against a real LiveKit server or the Orin publisher.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  86 +++++
 examples/egocap/backend/README.md             |   2 +
 examples/egocap/backend/egocap_web/app.py     |   5 +
 .../backend/egocap_web/livekit_preview.py     | 114 ++++++
 .../backend/egocap_web/station_config.py      |  56 +++
 examples/egocap/frontend/package-lock.json    | 120 +++++++
 examples/egocap/frontend/package.json         |   1 +
 .../src/App.liveRecordingWire.test.tsx        |   2 +
 .../frontend/src/App.operatorLayout.test.tsx  |   8 +-
 examples/egocap/frontend/src/App.test.tsx     |   8 +-
 .../frontend/src/CameraGrid.livekit.test.tsx  | 109 ++++++
 .../egocap/frontend/src/CameraGrid.test.tsx   |   8 +-
 examples/egocap/frontend/src/CameraGrid.tsx   |  24 +-
 .../frontend/src/LiveKitCameraTile.test.tsx   | 129 +++++++
 .../egocap/frontend/src/LiveKitCameraTile.tsx | 100 ++++++
 .../frontend/src/livekitPreview.test.ts       |  87 +++++
 .../egocap/frontend/src/livekitPreview.ts     |  77 ++++
 .../egocap/frontend/src/livekitTestDoubles.ts |  70 ++++
 examples/egocap/frontend/src/styles.css       |  27 ++
 .../frontend/src/useLiveKitPreview.test.ts    | 339 ++++++++++++++++++
 .../egocap/frontend/src/useLiveKitPreview.ts  | 166 +++++++++
 .../tests/backend/test_livekit_preview.py     | 180 ++++++++++
 .../backend/test_station_config_livekit.py    | 145 ++++++++
 23 files changed, 1858 insertions(+), 5 deletions(-)
 create mode 100644 examples/egocap/LIVEKIT_PREVIEW.md
 create mode 100644 examples/egocap/backend/egocap_web/livekit_preview.py
 create mode 100644 examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
 create mode 100644 examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
 create mode 100644 examples/egocap/frontend/src/LiveKitCameraTile.tsx
 create mode 100644 examples/egocap/frontend/src/livekitPreview.test.ts
 create mode 100644 examples/egocap/frontend/src/livekitPreview.ts
 create mode 100644 examples/egocap/frontend/src/livekitTestDoubles.ts
 create mode 100644 examples/egocap/frontend/src/useLiveKitPreview.test.ts
 create mode 100644 examples/egocap/frontend/src/useLiveKitPreview.ts
 create mode 100644 examples/egocap/tests/backend/test_livekit_preview.py
 create mode 100644 examples/egocap/tests/backend/test_station_config_livekit.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
new file mode 100644
index 0000000000..d287358b5c
--- /dev/null
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -0,0 +1,86 @@
+<!--
+SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# Live camera preview over LiveKit
+
+The camera host (an Orin running the SENSING publisher) publishes hardware-encoded H.264 into a LiveKit room. The
+browser subscribes to those tracks itself and decodes them, so the egocap backend only tells it where the room is and
+hands it a subscribe-only token. CaptureServer keeps doing tracking and control.
+
+```text
+Orin: SIPL -> hardware H.264 -> LiveKit publisher --> LiveKit server --> browser <video>
+PC:   egocap backend (station config + viewer token)     CaptureServer (tracking, control)
+```
+
+**These tiles are preview-only.** They are not requested from CaptureServer and are not recorded; pressing Record
+saves only the cameras the station already lists under `video_sources`. Every LiveKit tile says so.
+
+**Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
+latency have not been run or measured. Report those as untested until someone has run them.
+
+## 1. LiveKit server (on the PC or the LAN)
+
+Run a LiveKit server reachable from both the Orin and the browser, and note its API key and secret. For a quick local
+server, `livekit-server --dev --bind 0.0.0.0` uses the development key pair printed at start-up. Browsers need a
+secure context for WebRTC on anything but `localhost`, so use a `wss://` URL with a certificate the browser trusts
+when the browser is not on the server's own machine. Open the server's signalling and media ports between the machines.
+
+## 2. Backend credentials and station file
+
+The backend signs viewer tokens with the server's key pair, read from its environment only:
+
+```bash
+export LIVEKIT_API_KEY=...      # the LiveKit server's API key
+export LIVEKIT_API_SECRET=...   # its secret; never put this in the station file
+```
+
+Add a `livekit_preview` section to the station YAML that `EGOCAP_STATION_CONFIG` points at:
+
+```yaml
+livekit_preview:
+  url: wss://LIVEKIT_HOST          # what the browser connects to
+  room: sensing-preview
+  publisher: orin-sensing          # the publisher's participant identity
+  tracks:                          # up to four tiles
+    - name: Head left              # label shown on the tile
+      track: sensing-left          # the published track name
+    - name: Head right
+      track: sensing-right
+```
+
+Then start the backend as usual (`uv run uvicorn egocap_web.app:app --app-dir backend --port 8000`). The endpoint is
+`GET /api/livekit-preview`: 404 when the section is absent, 503 when the key pair is not set. The token lets a viewer
+join the room and subscribe, nothing more; like the camera preview routes it is open to anyone who can reach the
+backend, so keep the backend on a trusted network.
+
+## 3. Orin publisher
+
+Create a token file for the publisher: a LiveKit token for this room, with identity equal to the station's `publisher`,
+allowed to publish (for example with LiveKit's `lk token create`; see its `--help`). Then add the LiveKit options to
+the usual `camera_plugin_sensing` invocation, keeping the rig's own platform and configuration arguments:
+
+```bash
+camera_plugin_sensing ... \
+  --livekit-url=wss://LIVEKIT_HOST --livekit-token-file=join.token \
+  --add-stream=sensor=0,livekit=sensing-left \
+  --add-stream=sensor=1,livekit=sensing-right
+```
+
+The `livekit=` names must equal the station's `track` values. Start the publisher by hand; closing the browser
+disconnects only that viewer, and the Orin keeps capturing until you stop it.
+
+## 4. Expected result and troubleshooting
+
+Opening egocap shows the named tiles next to the tracking view, each marked preview-only. A tile reads "Waiting for
+camera" until its track is published, "No video frames" if a published track stops producing frames, and
+"Disconnected" while the room connection is down; the page reconnects on its own.
+
+| Symptom | Check |
+| --- | --- |
+| "LiveKit preview unavailable: ... must be set" | `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` in the backend's environment. |
+| Tiles never leave "Connecting" | The `url` is reachable from the browser; `wss://` certificate trusted; signalling and media ports open. |
+| Connected, tile stays "Waiting for camera" | The publisher's token room and identity match `room` and `publisher`; `livekit=` names match `track`. |
+| "Waiting for video" or black picture | The browser may not support the encoder's H.264 profile; check the browser console. |
diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md
index 74fa5010cd..ee06c335f6 100644
--- a/examples/egocap/backend/README.md
+++ b/examples/egocap/backend/README.md
@@ -33,6 +33,7 @@ or restarts it.
 | `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`) and the task it preselects (`preselected_task`). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. |
 | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. |
 | `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. |
+| `GET /api/livekit-preview` | Room, tracks and a subscribe-only token for the direct LiveKit camera preview; 404 unless the station file has a `livekit_preview` section. See [`../LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md). |
 | `GET /api/task-files`, `GET /api/task-files/{name}` | Read-only task-catalog API; see [`../data/taskfiles/README.md`](../data/taskfiles/README.md). |
 | `GET /recordings/...` | The optional recordings browser's API and file routes, off unless `EGOCAP_RECORDINGS_ENABLED=1`; see [`../recordings_frontend/README.md`](../recordings_frontend/README.md). |
 
@@ -54,6 +55,7 @@ Everything else is an environment variable:
 | --- | --- | --- |
 | `EGOCAP_STATION_CONFIG` | unset (development default) | Path to the deployment station YAML described above. |
 | `EGOCAP_CAPTURE_SERVER_URL` | `ws://127.0.0.1:8082` | Where to connect for tracking/camera data. |
+| `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | unset | The LiveKit server's key pair, used only to sign viewer tokens for `GET /api/livekit-preview`. |
 | `EGOCAP_TASK_FILES_DIR` | the shipped `data/taskfiles/` | Which task-catalog directory the task-file API serves. |
 | `EGOCAP_RECORDINGS_ENABLED` | off | Turns on the recordings browser's routes. |
 | `EGOCAP_ALLOWED_ORIGINS` | none (same-origin only) | Comma-separated extra origins allowed to open `WS /api/session` — needed when the frontend is hosted separately or behind a reverse proxy. |
diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index a6b1f79c0c..ad9e3873ed 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -37,6 +37,7 @@
 from .config import VisualizationConfig, config_from_env, visualization_from_env
 from .operator_settings import OperatorSettingsStore, operator_settings_path
 from .operator_settings import router as operator_settings_router
+from .livekit_preview import router as livekit_preview_router
 from .preview_routes import router as preview_router
 from .recording_adapter import (
     MANUS_GLOVE_SPEC,
@@ -304,6 +305,9 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     # the WHOLE Begin, not just that one camera, which also takes tracking preview down with it.
     if resolved_station is not None:
         config = replace(config, cameras=resolved_station.cameras)
+    # Direct LiveKit preview is independent of CaptureServer: it only tells the browser where the
+    # room is, so an invalid or absent station YAML simply leaves it unconfigured (404 from its route).
+    app.state.livekit_preview = resolved_station.livekit_preview if resolved_station is not None else None
     # task_text seeds the committed next-task instruction. operator seeds ONLY a prefill
     # default for the frontend's entry field (via recording_command.py's snapshot
     # "default_operator") -- start_episode's own operator parameter always replaces
@@ -403,6 +407,7 @@ def _optional_visualization(
 
 app = FastAPI(lifespan=lifespan)
 app.include_router(preview_router)
+app.include_router(livekit_preview_router)
 app.include_router(task_file_router)
 app.include_router(settings_router)
 app.include_router(operator_settings_router)
diff --git a/examples/egocap/backend/egocap_web/livekit_preview.py b/examples/egocap/backend/egocap_web/livekit_preview.py
new file mode 100644
index 0000000000..2c91f29b49
--- /dev/null
+++ b/examples/egocap/backend/egocap_web/livekit_preview.py
@@ -0,0 +1,114 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Direct LiveKit camera preview: the station's room/track mapping, a subscribe-only token, and one endpoint.
+
+The camera host publishes already-encoded H.264 into a LiveKit room. The browser subscribes to those tracks
+itself, so the backend never decodes, re-encodes or relays video and does not take part in recording. This module
+only tells the browser where the room is and hands it a short-lived token that can subscribe and nothing else.
+
+``LIVEKIT_API_KEY`` and ``LIVEKIT_API_SECRET`` belong to the LiveKit server and are read from the backend's
+environment only; they never appear in the station YAML, a response or a log line.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+from dataclasses import dataclass
+
+from fastapi import APIRouter, Request
+from fastapi.responses import JSONResponse
+
+API_KEY_ENV = "LIVEKIT_API_KEY"
+API_SECRET_ENV = "LIVEKIT_API_SECRET"
+#: A token only has to outlive the page's connect; LiveKit keeps an established connection going afterwards.
+TOKEN_TTL_S = 3600
+
+router = APIRouter()
+
+
+@dataclass(frozen=True)
+class LiveKitTrack:
+    """One camera tile: the operator-facing ``name`` and the published video track ``track`` it shows."""
+
+    name: str
+    track: str
+
+
+@dataclass(frozen=True)
+class LiveKitPreview:
+    """Where the camera host publishes: signalling ``url``, ``room``, ``publisher`` identity and its tracks.
+
+    A track name is only unique within one participant, so the browser selects by publisher plus track.
+    """
+
+    url: str
+    room: str
+    publisher: str
+    tracks: tuple[LiveKitTrack, ...]
+
+
+def _b64url(data: bytes) -> str:
+    """URL-safe base64 without padding, as JWT segments require."""
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_s: int = TOKEN_TTL_S) -> str:
+    """A signed LiveKit access token that may join ``room`` and subscribe, but not publish."""
+    header = {"alg": "HS256", "typ": "JWT"}
+    claims = {
+        "iss": api_key,
+        # Each browser gets its own identity: LiveKit disconnects an existing participant that reuses one.
+        "sub": f"egocap-viewer-{secrets.token_hex(4)}",
+        "nbf": now,
+        "exp": now + ttl_s,
+        "video": {
+            "room": room,
+            "roomJoin": True,
+            "canSubscribe": True,
+            "canPublish": False,
+            "canPublishData": False,
+        },
+    }
+    # Compact JSON: the signature covers exactly these bytes, so both sides must agree on them.
+    signing_input = ".".join(
+        _b64url(json.dumps(part, separators=(",", ":")).encode()) for part in (header, claims)
+    )
+    signature = hmac.new(api_secret.encode(), signing_input.encode("ascii"), hashlib.sha256).digest()
+    return f"{signing_input}.{_b64url(signature)}"
+
+
+@router.get("/api/livekit-preview")
+async def get_livekit_preview(request: Request) -> JSONResponse:
+    """The room, tracks and a fresh subscribe-only token for the browser, or why preview is unavailable.
+
+    Like the camera preview routes this is unauthenticated: anyone who can reach the backend can watch the
+    cameras, which is why the token cannot publish.
+    """
+    headers = {"Cache-Control": "no-store"}
+    preview: LiveKitPreview | None = request.app.state.livekit_preview
+    # Not configured is a normal state for a station that previews through CaptureServer instead.
+    if preview is None:
+        return JSONResponse({"detail": "LiveKit preview is not configured"}, status_code=404, headers=headers)
+    api_key = os.environ.get(API_KEY_ENV, "")
+    api_secret = os.environ.get(API_SECRET_ENV, "")
+    # Configured but unable to sign: say what to set, without echoing any value.
+    if not api_key or not api_secret:
+        detail = f"{API_KEY_ENV} and {API_SECRET_ENV} must be set for the backend"
+        return JSONResponse({"detail": detail}, status_code=503, headers=headers)
+    token = subscriber_token(api_key=api_key, api_secret=api_secret, room=preview.room, now=int(time.time()))
+    body = {
+        "url": preview.url,
+        "room": preview.room,
+        "publisher": preview.publisher,
+        "token": token,
+        "tracks": [{"name": t.name, "track": t.track} for t in preview.tracks],
+    }
+    return JSONResponse(body, headers=headers)
diff --git a/examples/egocap/backend/egocap_web/station_config.py b/examples/egocap/backend/egocap_web/station_config.py
index 53f873185b..8d27c98106 100644
--- a/examples/egocap/backend/egocap_web/station_config.py
+++ b/examples/egocap/backend/egocap_web/station_config.py
@@ -32,11 +32,15 @@
 
 from capture_server import protocol as p
 
+from .livekit_preview import LiveKitPreview, LiveKitTrack
+
 STATION_CONFIG_ENV = "EGOCAP_STATION_CONFIG"
 _DEFAULT_FLAT_STATION_ID = "station_01"
 #: Matches capture_server.protocol's own BeginRequest.cameras limit -- checked here too so an
 #: over-limit YAML is a configuration error, not a later capture-startup failure.
 _MAX_CAMERAS = 3
+#: Preview tiles share the camera grid, whose layout tops out at four.
+_MAX_LIVEKIT_TRACKS = 4
 
 
 class StationConfigError(ValueError):
@@ -57,6 +61,8 @@ class ResolvedStation:
     task_description: str | None
     data_dir: Path | None
     cameras: tuple[p.CameraSelection, ...]
+    #: Direct LiveKit camera preview; independent of ``cameras`` and never recorded.
+    livekit_preview: LiveKitPreview | None = None
 
 
 class _DuplicateKeyLoader(yaml.SafeLoader):
@@ -130,6 +136,55 @@ def _resolve_cameras(station_id: str, entry: dict) -> tuple[p.CameraSelection, .
     return tuple(cameras)
 
 
+def _nonempty_str(mapping: dict, key: str, where: str) -> str:
+    """A required nonempty string field of ``mapping``; ``where`` names it in the error."""
+    value = mapping.get(key)
+    if not isinstance(value, str) or not value:
+        raise StationConfigError(f"{where}.{key} must be a nonempty string")
+    return value
+
+
+def _resolve_livekit_preview(station_id: str, entry: dict) -> LiveKitPreview | None:
+    """The optional ``livekit_preview`` section: where the camera host publishes and which tracks to show.
+
+    Absent means the station has no direct LiveKit preview. These cameras are display-only: they are not
+    requested from CaptureServer and are never part of ``cameras``.
+    """
+    raw = entry.get("livekit_preview")
+    if raw is None:
+        return None
+    where = f"station {station_id!r}: livekit_preview"
+    if not isinstance(raw, dict):
+        raise StationConfigError(f"{where} must be a mapping")
+    # The browser connects with this URL, so only the WebSocket schemes LiveKit signalling uses are accepted.
+    url = _nonempty_str(raw, "url", where)
+    if not url.startswith(("ws://", "wss://")):
+        raise StationConfigError(f"{where}.url must start with ws:// or wss://")
+    room = _nonempty_str(raw, "room", where)
+    publisher = _nonempty_str(raw, "publisher", where)
+    raw_tracks = raw.get("tracks")
+    if not isinstance(raw_tracks, list) or not raw_tracks:
+        raise StationConfigError(f"{where}.tracks must be a nonempty list")
+    if len(raw_tracks) > _MAX_LIVEKIT_TRACKS:
+        raise StationConfigError(f"{where}.tracks supports at most {_MAX_LIVEKIT_TRACKS} entries")
+    tracks: list[LiveKitTrack] = []
+    for i, item in enumerate(raw_tracks):
+        if not isinstance(item, dict):
+            raise StationConfigError(f"{where}.tracks[{i}] must be a mapping")
+        tracks.append(
+            LiveKitTrack(
+                name=_nonempty_str(item, "name", f"{where}.tracks[{i}]"),
+                track=_nonempty_str(item, "track", f"{where}.tracks[{i}]"),
+            )
+        )
+    # Two tiles on one track, or two tiles with one label, would be indistinguishable to the operator.
+    if len({t.track for t in tracks}) != len(tracks):
+        raise StationConfigError(f"{where}.tracks has a duplicate track")
+    if len({t.name for t in tracks}) != len(tracks):
+        raise StationConfigError(f"{where}.tracks has a duplicate name")
+    return LiveKitPreview(url=url, room=room, publisher=publisher, tracks=tuple(tracks))
+
+
 def _resolve_one_station(station_id: str, entry: Any, config_dir: Path) -> ResolvedStation:
     """Build a :class:`ResolvedStation` from one station's parsed mapping."""
     if not isinstance(entry, dict):
@@ -162,6 +217,7 @@ def _resolve_one_station(station_id: str, entry: Any, config_dir: Path) -> Resol
         task_description=_str_field(meta, "task_description"),
         data_dir=data_dir,
         cameras=_resolve_cameras(station_id, entry),
+        livekit_preview=_resolve_livekit_preview(station_id, entry),
     )
 
 
diff --git a/examples/egocap/frontend/package-lock.json b/examples/egocap/frontend/package-lock.json
index 9b8a14900f..173182d2c6 100644
--- a/examples/egocap/frontend/package-lock.json
+++ b/examples/egocap/frontend/package-lock.json
@@ -8,6 +8,7 @@
       "name": "egocap-web-frontend",
       "version": "0.1.0",
       "dependencies": {
+        "livekit-client": "2.9.7",
         "react": "19.3.1",
         "react-dom": "19.3.1"
       },
@@ -105,6 +106,12 @@
         "specificity": "bin/cli.js"
       }
     },
+    "node_modules/@bufbuild/protobuf": {
+      "version": "1.10.1",
+      "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-1.10.1.tgz",
+      "integrity": "sha512-wJ8ReQbHxsAfXhrf9ixl0aYbZorRuOWpBNzm8pL8ftmSxQx/wnJD5Eg861NwJU/czy2VXFIebCeZnZrI9rktIQ==",
+      "license": "(Apache-2.0 AND BSD-3-Clause)"
+    },
     "node_modules/@csstools/color-helpers": {
       "version": "6.1.2",
       "resolved": "https://registry.npmjs.org/@csstools/color-helpers/-/color-helpers-6.1.2.tgz",
@@ -291,6 +298,21 @@
         "@jridgewell/sourcemap-codec": "^1.4.14"
       }
     },
+    "node_modules/@livekit/mutex": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@livekit/mutex/-/mutex-1.1.1.tgz",
+      "integrity": "sha512-EsshAucklmpuUAfkABPxJNhzj9v2sG7JuzFDL4ML1oJQSV14sqrpTYnsaOudMAw9yOaW53NU3QQTlUQoRs4czw==",
+      "license": "Apache-2.0"
+    },
+    "node_modules/@livekit/protocol": {
+      "version": "1.34.0",
+      "resolved": "https://registry.npmjs.org/@livekit/protocol/-/protocol-1.34.0.tgz",
+      "integrity": "sha512-bU7pCLAMRVTVZb1KSxA46q55bhOc4iATrY/gccy2/oX1D57tiZEI+8wGRWHeDwBb0UwnABu6JXzC4tTFkdsaOg==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@bufbuild/protobuf": "^1.10.0"
+      }
+    },
     "node_modules/@oxc-project/types": {
       "version": "0.154.0",
       "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.154.0.tgz",
@@ -1240,6 +1262,15 @@
         "@types/estree": "^1.0.0"
       }
     },
+    "node_modules/events": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/events/-/events-3.3.0.tgz",
+      "integrity": "sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.8.x"
+      }
+    },
     "node_modules/expect-type": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/expect-type/-/expect-type-1.4.0.tgz",
@@ -1612,6 +1643,36 @@
         "url": "https://opencollective.com/parcel"
       }
     },
+    "node_modules/livekit-client": {
+      "version": "2.9.7",
+      "resolved": "https://registry.npmjs.org/livekit-client/-/livekit-client-2.9.7.tgz",
+      "integrity": "sha512-a+Y76HE5k7IaFOpDnr14ON+VOAgh7cCjuBq8Loq5p5xHZzw+/cQyX/xPsMLU4lloKO5zGf45YZJYt/Egk1Xg+g==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "@livekit/mutex": "1.1.1",
+        "@livekit/protocol": "1.34.0",
+        "events": "^3.3.0",
+        "loglevel": "^1.9.2",
+        "sdp-transform": "^2.15.0",
+        "ts-debounce": "^4.0.0",
+        "tslib": "2.8.1",
+        "typed-emitter": "^2.1.0",
+        "webrtc-adapter": "^9.0.1"
+      }
+    },
+    "node_modules/loglevel": {
+      "version": "1.9.2",
+      "resolved": "https://registry.npmjs.org/loglevel/-/loglevel-1.9.2.tgz",
+      "integrity": "sha512-HgMmCqIJSAKqo68l0rS2AanEWfkxaZ5wNiEFb5ggm08lDs9Xl2KxBlX3PTcaD2chBM1gXAYf491/M2Rv8Jwayg==",
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6.0"
+      },
+      "funding": {
+        "type": "tidelift",
+        "url": "https://tidelift.com/funding/github/npm/loglevel"
+      }
+    },
     "node_modules/lru-cache": {
       "version": "11.5.3",
       "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.5.3.tgz",
@@ -1844,6 +1905,16 @@
         "@rolldown/binding-win32-x64-msvc": "1.2.14"
       }
     },
+    "node_modules/rxjs": {
+      "version": "7.8.2",
+      "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.2.tgz",
+      "integrity": "sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==",
+      "license": "Apache-2.0",
+      "optional": true,
+      "dependencies": {
+        "tslib": "^2.1.0"
+      }
+    },
     "node_modules/saxes": {
       "version": "6.0.0",
       "resolved": "https://registry.npmjs.org/saxes/-/saxes-6.0.0.tgz",
@@ -1863,6 +1934,21 @@
       "integrity": "sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==",
       "license": "MIT"
     },
+    "node_modules/sdp": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/sdp/-/sdp-3.2.2.tgz",
+      "integrity": "sha512-xZocWwfyp4hkbN4hLWxMjmv2Q8aNa9MhmOZ7L9aCZPT+dZsgRr6wZRrSYE3HTdyk/2pZKPSgqI7ns7Een1xMSA==",
+      "license": "MIT"
+    },
+    "node_modules/sdp-transform": {
+      "version": "2.15.0",
+      "resolved": "https://registry.npmjs.org/sdp-transform/-/sdp-transform-2.15.0.tgz",
+      "integrity": "sha512-KrOH82c/W+GYQ0LHqtr3caRpM3ITglq3ljGUIb8LTki7ByacJZ9z+piSGiwZDsRyhQbYBOBJgr2k6X4BZXi3Kw==",
+      "license": "MIT",
+      "bin": {
+        "sdp-verify": "checker.js"
+      }
+    },
     "node_modules/source-map-js": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.2.tgz",
@@ -1963,6 +2049,27 @@
         "node": "^22.14.0 || >=24.0.0"
       }
     },
+    "node_modules/ts-debounce": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/ts-debounce/-/ts-debounce-4.0.0.tgz",
+      "integrity": "sha512-+1iDGY6NmOGidq7i7xZGA4cm8DAa6fqdYcvO5Z6yBevH++Bdo9Qt/mN0TzHUgcCcKv1gmh9+W5dHqz8pMWbCbg==",
+      "license": "MIT"
+    },
+    "node_modules/tslib": {
+      "version": "2.8.1",
+      "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
+      "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
+      "license": "0BSD"
+    },
+    "node_modules/typed-emitter": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/typed-emitter/-/typed-emitter-2.1.0.tgz",
+      "integrity": "sha512-g/KzbYKbH5C2vPkaXGu8DJlHrGKHLsM25Zg9WuC9pMGfuvT+X25tZQWo5fK1BjBm8+UrVE9LDCvaY0CQk+fXDA==",
+      "license": "MIT",
+      "optionalDependencies": {
+        "rxjs": "*"
+      }
+    },
     "node_modules/typescript": {
       "version": "7.0.2",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz",
@@ -2192,6 +2299,19 @@
         "node": ">=20"
       }
     },
+    "node_modules/webrtc-adapter": {
+      "version": "9.0.6",
+      "resolved": "https://registry.npmjs.org/webrtc-adapter/-/webrtc-adapter-9.0.6.tgz",
+      "integrity": "sha512-CHbl2ZQbxx164IgWRgzJno4hWtM4tFbRam1QfI3Yxhs3w/DvqluVxVWeXs3oL5/fbGkSNLKo0Ty5MgUWceNhog==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "sdp": "^3.2.0"
+      },
+      "engines": {
+        "node": ">=6.0.0",
+        "npm": ">=3.10.0"
+      }
+    },
     "node_modules/whatwg-mimetype": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/whatwg-mimetype/-/whatwg-mimetype-5.0.0.tgz",
diff --git a/examples/egocap/frontend/package.json b/examples/egocap/frontend/package.json
index 967ecf6c65..cd5ce66436 100644
--- a/examples/egocap/frontend/package.json
+++ b/examples/egocap/frontend/package.json
@@ -11,6 +11,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "livekit-client": "2.9.7",
     "react": "19.3.1",
     "react-dom": "19.3.1"
   },
diff --git a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
index 7218e3b4e2..5653f4234d 100644
--- a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
+++ b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
@@ -129,6 +129,8 @@ describe("RecordingPanel -> real transport -> real backend wire shape", () => {
   beforeEach(() => {
     FakeWebSocket.instances = [];
     vi.stubGlobal("WebSocket", FakeWebSocket);
+    // CameraGrid asks for a LiveKit preview on mount; this station has none.
+    vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
   });
 
   afterEach(() => {
diff --git a/examples/egocap/frontend/src/App.operatorLayout.test.tsx b/examples/egocap/frontend/src/App.operatorLayout.test.tsx
index 0fa5e8347f..7e9f9f88cd 100644
--- a/examples/egocap/frontend/src/App.operatorLayout.test.tsx
+++ b/examples/egocap/frontend/src/App.operatorLayout.test.tsx
@@ -6,7 +6,7 @@
  * The cameras-first operator page: the status bar, the camera stage, the control dock and the side drawer that
  * holds the 3D view and raw data. useCaptureSession is mocked so each test controls the snapshot directly.
  */
-import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import App from "./App";
 import type { PreviewSnapshot } from "./captureProtocol";
@@ -18,9 +18,15 @@ vi.mock("./useCaptureSession", async (importOriginal) => {
   return { ...actual, useCaptureSession: vi.fn() };
 });
 
+// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
+beforeEach(() => {
+  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
+});
+
 afterEach(() => {
   cleanup();
   window.localStorage.clear();
+  vi.unstubAllGlobals();
 });
 
 function snapshot(overrides: Partial<PreviewSnapshot> = {}): PreviewSnapshot {
diff --git a/examples/egocap/frontend/src/App.test.tsx b/examples/egocap/frontend/src/App.test.tsx
index 8ae3e89c73..eabb56e8c8 100644
--- a/examples/egocap/frontend/src/App.test.tsx
+++ b/examples/egocap/frontend/src/App.test.tsx
@@ -11,7 +11,7 @@
  * directly rather than driving a real socket.
  */
 import type { ReactElement } from "react";
-import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
 import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react";
 import App from "./App";
 import { OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE } from "./settingsTestDoubles";
@@ -24,9 +24,15 @@ vi.mock("./useCaptureSession", async (importOriginal) => {
   return { ...actual, useCaptureSession: vi.fn() };
 });
 
+// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
+beforeEach(() => {
+  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
+});
+
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
+  vi.unstubAllGlobals();
 });
 
 function makeSnapshot(overrides: Partial<PreviewSnapshot> = {}): PreviewSnapshot {
diff --git a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
new file mode 100644
index 0000000000..fc7704ac5f
--- /dev/null
+++ b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
@@ -0,0 +1,109 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { CameraGrid } from "./CameraGrid";
+import type { PreviewSnapshot } from "./captureProtocol";
+import { CONFIG, FakeRoom } from "./livekitTestDoubles";
+
+vi.mock("livekit-client", async () => {
+  const doubles = await import("./livekitTestDoubles");
+  return {
+    Room: doubles.FakeRoom,
+    RoomEvent: {
+      TrackSubscribed: "TrackSubscribed",
+      TrackUnsubscribed: "TrackUnsubscribed",
+      ParticipantDisconnected: "ParticipantDisconnected",
+      Reconnecting: "Reconnecting",
+      Reconnected: "Reconnected",
+      Disconnected: "Disconnected",
+    },
+    Track: { Kind: { Video: "video", Audio: "audio" } },
+  };
+});
+
+function snapshot(names: string[]): PreviewSnapshot {
+  return {
+    version: 1,
+    type: 3,
+    backend_instance_id: "b1",
+    revision: 1,
+    station_label: "Station",
+    profile_label: "Profile",
+    connecting: false,
+    started: null,
+    status: null,
+    stopped: null,
+    error_message: null,
+    binary_generation: 1,
+    tracking: null,
+    cameras: names.map((name, i) => ({ stream_id: i + 1, name, url: `/stream${i + 1}?a=1`, sequence: null, age_ms: null, diagnostic: null })),
+    visualization: null,
+  } as PreviewSnapshot;
+}
+
+function stubFetch(status: number, body: unknown): void {
+  vi.stubGlobal("fetch", vi.fn(async () => ({ status, ok: status === 200, json: async () => body })));
+}
+
+async function settled(): Promise<void> {
+  // Let the hook's fetch and connect promises resolve.
+  await new Promise((r) => setTimeout(r, 0));
+  await new Promise((r) => setTimeout(r, 0));
+}
+
+beforeEach(() => FakeRoom.reset());
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+});
+
+describe("CameraGrid with LiveKit preview", () => {
+  it("renders LiveKit tiles beside MJPEG tiles, preview-only, with the MJPEG camera keeping the primary slot", async () => {
+    stubFetch(200, CONFIG);
+    const { container } = render(<CameraGrid snapshot={snapshot(["head_camera"])} live={true} receivedAtMonotonic={performance.now()} />);
+    await settled();
+    expect(screen.getByText("head_camera")).not.toBeNull();
+    expect(screen.getByText("Head left", { exact: false })).not.toBeNull();
+    expect(screen.getByText("Head right", { exact: false })).not.toBeNull();
+    expect(screen.getAllByText(/Preview only/)).toHaveLength(2);
+    expect(container.querySelector(".camera-grid-items")?.className).toContain("camera-grid-items--n3");
+    const primary = container.querySelectorAll(".camera-tile--primary");
+    expect(primary).toHaveLength(1);
+    expect(primary[0].textContent).toContain("head_camera");
+  });
+
+  it("shows only LiveKit tiles, the first as primary, when CaptureServer has no cameras", async () => {
+    stubFetch(200, CONFIG);
+    const { container } = render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    await settled();
+    expect(screen.queryByText("No cameras selected.")).toBeNull();
+    expect(container.querySelector(".camera-tile--primary")?.textContent).toContain("Head left");
+  });
+
+  it("keeps the empty note and MJPEG behavior unchanged when LiveKit is not configured", async () => {
+    stubFetch(404, { detail: "nf" });
+    const { container, rerender } = render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    await settled();
+    expect(screen.getByText("No cameras selected.")).not.toBeNull();
+    expect(screen.queryByText(/LiveKit preview unavailable/)).toBeNull();
+    rerender(<CameraGrid snapshot={snapshot(["a", "b"])} live={true} receivedAtMonotonic={performance.now()} />);
+    expect(container.querySelector(".camera-grid-items")?.className).toContain("camera-grid-items--n2");
+    expect(screen.queryByText(/Preview only/)).toBeNull();
+    expect(FakeRoom.instances).toHaveLength(0);
+  });
+
+  it("shows the unavailable note with the backend detail when the preview cannot start", async () => {
+    stubFetch(503, { detail: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set" });
+    render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    await settled();
+    expect(screen.getByText(/LiveKit preview unavailable: LIVEKIT_API_KEY/)).not.toBeNull();
+  });
+
+  it("shows the unavailable note when the backend cannot be reached", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => {
+      throw new TypeError("fetch failed");
+    }));
+    render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    await settled();
+    expect(screen.getByText("LiveKit preview unavailable: Cannot reach the backend")).not.toBeNull();
+  });
+});
diff --git a/examples/egocap/frontend/src/CameraGrid.test.tsx b/examples/egocap/frontend/src/CameraGrid.test.tsx
index 7f7d4617c0..6280c1606a 100644
--- a/examples/egocap/frontend/src/CameraGrid.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.test.tsx
@@ -6,14 +6,20 @@
  * CameraGrid's per-tile rate/latency readout: derived from successive snapshots' camera
  * sequence numbers, shown only for live fresh samples, and dashed until enough history exists.
  */
-import { afterEach, describe, expect, it, vi } from "vitest";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { act, cleanup, render, screen } from "@testing-library/react";
 import { CameraGrid } from "./CameraGrid";
 import type { PreviewSnapshot } from "./captureProtocol";
 
+// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
+beforeEach(() => {
+  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
+});
+
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
+  vi.unstubAllGlobals();
 });
 
 function makeSnapshot(sequence: string | null, ageMs: number | null, fps = 60): PreviewSnapshot {
diff --git a/examples/egocap/frontend/src/CameraGrid.tsx b/examples/egocap/frontend/src/CameraGrid.tsx
index 416a453fd3..f5b61bf168 100644
--- a/examples/egocap/frontend/src/CameraGrid.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.tsx
@@ -14,6 +14,8 @@ import { TRACKING_STALE_AFTER_MS } from "./CaptureTree";
 import { CameraRateTracker, formatCameraStats } from "./cameraRates";
 import { ROLE_LABELS } from "./settingsApi";
 import { roleOfCamera } from "./useOperatorSettings";
+import { LiveKitCameraTile } from "./LiveKitCameraTile";
+import { useLiveKitPreview } from "./useLiveKitPreview";
 
 const CAMERA_ERROR_RETRY_LIMIT = 3;
 
@@ -184,8 +186,11 @@ export function CameraGrid({
     rateTracker.current.retainOnly(keys);
   }
 
+  // Direct LiveKit tiles sit beside the CaptureServer ones; they have their own connection and readiness.
+  const livekit = useLiveKitPreview();
   const cameras = snapshot?.cameras ?? [];
-  if (cameras.length === 0) {
+  const livekitShown = livekit.tiles.length > 0 || livekit.phase === "error";
+  if (cameras.length === 0 && !livekitShown) {
     return (
       <section className="camera-grid">
         <h2 className="group-label">Cameras</h2>
@@ -201,7 +206,12 @@ export function CameraGrid({
   return (
     <section className="camera-grid">
       <h2 className="group-label">Cameras</h2>
-      <div className={`camera-grid-items camera-grid-items--n${Math.min(cameras.length, 4)}`}>
+      {livekit.phase === "error" && livekit.message !== null && (
+        <p className="empty-note">LiveKit preview unavailable: {livekit.message}</p>
+      )}
+      <div
+        className={`camera-grid-items camera-grid-items--n${Math.min(cameras.length + livekit.tiles.length, 4)}`}
+      >
         {cameras.map((cam, index) => {
           const effectiveAge = cam.age_ms === null ? null : cam.age_ms + elapsedSinceReceipt;
           // "Never had a sample" (sequence/age_ms both null) is a distinct,
@@ -236,6 +246,16 @@ export function CameraGrid({
             />
           );
         })}
+        {livekit.tiles.map((tile, index) => (
+          <LiveKitCameraTile
+            key={`livekit-${tile.name}`}
+            name={tile.name}
+            track={tile.track}
+            phase={livekit.phase}
+            // The first LiveKit tile is the main view only when no CaptureServer camera claims that place.
+            primary={cameras.length === 0 && index === 0}
+          />
+        ))}
       </div>
     </section>
   );
diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
new file mode 100644
index 0000000000..2ca0c2b881
--- /dev/null
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, render, screen } from "@testing-library/react";
+import { LiveKitCameraTile } from "./LiveKitCameraTile";
+import { fakeTrack } from "./livekitTestDoubles";
+
+let frameCallbacks: Array<() => void> = [];
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  frameCallbacks = [];
+  // jsdom has no requestVideoFrameCallback; this one lets a test present frames by hand.
+  (HTMLVideoElement.prototype as any).requestVideoFrameCallback = function (cb: () => void) {
+    frameCallbacks.push(cb);
+    return frameCallbacks.length;
+  };
+  (HTMLVideoElement.prototype as any).cancelVideoFrameCallback = vi.fn();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  delete (HTMLVideoElement.prototype as any).requestVideoFrameCallback;
+  delete (HTMLVideoElement.prototype as any).cancelVideoFrameCallback;
+});
+
+function presentFrame(): void {
+  const cbs = frameCallbacks;
+  frameCallbacks = [];
+  act(() => cbs.forEach((cb) => cb()));
+}
+
+describe("LiveKitCameraTile placeholders", () => {
+  it("shows Connecting while the room connects", () => {
+    render(<LiveKitCameraTile name="Head" track={null} phase="connecting" primary={false} />);
+    expect(screen.getByText("Connecting")).not.toBeNull();
+  });
+
+  it("shows Reconnecting while the SDK reconnects", () => {
+    render(<LiveKitCameraTile name="Head" track={null} phase="reconnecting" primary={false} />);
+    expect(screen.getByText("Reconnecting")).not.toBeNull();
+  });
+
+  it("shows Disconnected in the error phase", () => {
+    render(<LiveKitCameraTile name="Head" track={null} phase="error" primary={false} />);
+    expect(screen.getByText("Disconnected")).not.toBeNull();
+  });
+
+  it("shows Waiting for camera when connected but the track is not published", () => {
+    const { container } = render(<LiveKitCameraTile name="Head" track={null} phase="connected" primary={false} />);
+    expect(screen.getByText("Waiting for camera")).not.toBeNull();
+    expect(container.querySelector("video")).toBeNull();
+  });
+
+  it("shows Waiting for video until the first frame is presented, then no placeholder", () => {
+    const track = fakeTrack();
+    render(<LiveKitCameraTile name="Head" track={track} phase="connected" primary={false} />);
+    expect(screen.getByText("Waiting for video")).not.toBeNull();
+    presentFrame();
+    expect(screen.queryByText("Waiting for video")).toBeNull();
+    expect(document.querySelector(".camera-placeholder")).toBeNull();
+  });
+
+  it("shows No video frames and a warning tone when frames stop for more than three seconds", () => {
+    const track = fakeTrack();
+    const { container } = render(<LiveKitCameraTile name="Head" track={track} phase="connected" primary={false} />);
+    presentFrame();
+    act(() => {
+      vi.advanceTimersByTime(3000);
+    });
+    expect(screen.queryByText("No video frames")).toBeNull();
+    act(() => {
+      vi.advanceTimersByTime(2000);
+    });
+    expect(screen.getByText("No video frames")).not.toBeNull();
+    expect(container.querySelector("figure")?.className).toContain("tone-warning");
+    // Frames resuming clears the warning.
+    presentFrame();
+    expect(screen.queryByText("No video frames")).toBeNull();
+  });
+
+  it("falls back to timeupdate when requestVideoFrameCallback is unavailable", () => {
+    delete (HTMLVideoElement.prototype as any).requestVideoFrameCallback;
+    const track = fakeTrack();
+    const { container } = render(<LiveKitCameraTile name="Head" track={track} phase="connected" primary={false} />);
+    act(() => {
+      container.querySelector("video")!.dispatchEvent(new Event("timeupdate"));
+    });
+    expect(screen.queryByText("Waiting for video")).toBeNull();
+  });
+});
+
+describe("LiveKitCameraTile track wiring and labels", () => {
+  it("attaches the track to a muted inline video and detaches it on unmount", () => {
+    const track = fakeTrack();
+    const { container, unmount } = render(<LiveKitCameraTile name="Head" track={track} phase="connected" primary={false} />);
+    const video = container.querySelector("video")!;
+    expect(track.attach).toHaveBeenCalledWith(video);
+    expect(video.muted).toBe(true);
+    expect(video.autoplay).toBe(true);
+    expect(video.hasAttribute("playsinline")).toBe(true);
+    unmount();
+    expect(track.detach).toHaveBeenCalledWith(video);
+  });
+
+  it("detaches the old track and attaches the new one when the track changes", () => {
+    const a = fakeTrack();
+    const b = fakeTrack();
+    const { container, rerender } = render(<LiveKitCameraTile name="Head" track={a} phase="connected" primary={false} />);
+    const video = container.querySelector("video")!;
+    rerender(<LiveKitCameraTile name="Head" track={b} phase="connected" primary={false} />);
+    expect(a.detach).toHaveBeenCalledWith(video);
+    expect(b.attach).toHaveBeenCalledWith(video);
+  });
+
+  it("goes back to Waiting for video when a replacement track has not produced a frame", () => {
+    const a = fakeTrack();
+    const { rerender } = render(<LiveKitCameraTile name="Head" track={a} phase="connected" primary={false} />);
+    presentFrame();
+    rerender(<LiveKitCameraTile name="Head" track={fakeTrack()} phase="connected" primary={false} />);
+    expect(screen.getByText("Waiting for video")).not.toBeNull();
+  });
+
+  it("always labels the tile as preview only and shows its name", () => {
+    render(<LiveKitCameraTile name="Head left" track={null} phase="connected" primary={true} />);
+    expect(screen.getByText("Head left", { exact: false })).not.toBeNull();
+    expect(screen.getByText(/Preview only/)).not.toBeNull();
+    expect(document.querySelector(".camera-tile--primary")).not.toBeNull();
+  });
+});
diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
new file mode 100644
index 0000000000..4fd07b106a
--- /dev/null
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
@@ -0,0 +1,100 @@
+/**
+ * One live camera tile fed directly by a LiveKit video track.
+ *
+ * Readiness comes from the track and from decoded frames actually reaching the <video> element, never from a
+ * JPEG slot or a CaptureServer camera descriptor. A track that exists but stops producing frames is shown as
+ * stale rather than healthy.
+ */
+
+import { useEffect, useRef, useState } from "react";
+import type { RemoteTrack } from "livekit-client";
+import type { LiveKitPhase } from "./useLiveKitPreview";
+
+/** No decoded frame for this long means the picture is frozen. */
+const FRAME_STALE_AFTER_MS = 3000;
+
+/** Text shown instead of a picture, or null when a fresh picture is showing. */
+function placeholderFor(phase: LiveKitPhase, track: RemoteTrack | null, hasFrame: boolean, stale: boolean): string | null {
+  if (phase === "error") return "Disconnected";
+  if (phase !== "connected") return phase === "reconnecting" ? "Reconnecting" : "Connecting";
+  if (track === null) return "Waiting for camera";
+  if (!hasFrame) return "Waiting for video";
+  return stale ? "No video frames" : null;
+}
+
+/** A named preview tile; always labelled preview-only because these feeds are not recorded. */
+export function LiveKitCameraTile({
+  name,
+  track,
+  phase,
+  primary,
+}: {
+  name: string;
+  track: RemoteTrack | null;
+  phase: LiveKitPhase;
+  primary: boolean;
+}) {
+  const videoRef = useRef<HTMLVideoElement | null>(null);
+  const lastFrameAtRef = useRef<number | null>(null);
+  const [hasFrame, setHasFrame] = useState(false);
+  const [stale, setStale] = useState(false);
+
+  // Attach the subscribed track to the element, and detach it when the track changes or the tile goes away.
+  useEffect(() => {
+    const element = videoRef.current;
+    lastFrameAtRef.current = null;
+    setHasFrame(false);
+    setStale(false);
+    if (element === null || track === null) return;
+    track.attach(element);
+    return () => {
+      track.detach(element);
+    };
+  }, [track]);
+
+  // Frame liveness: note the time of every presented frame, and judge staleness once a second.
+  useEffect(() => {
+    const element = videoRef.current;
+    if (element === null || track === null) return;
+    let stopped = false;
+    let callbackId: number | null = null;
+    const markFrame = (): void => {
+      lastFrameAtRef.current = performance.now();
+      setHasFrame(true);
+      setStale(false);
+    };
+    const watchFrames = (): void => {
+      if (stopped) return;
+      callbackId = element.requestVideoFrameCallback(() => {
+        markFrame();
+        watchFrames();
+      });
+    };
+    // requestVideoFrameCallback reports presented frames exactly; without it, playback progress is the fallback.
+    if (typeof element.requestVideoFrameCallback === "function") watchFrames();
+    else element.addEventListener("timeupdate", markFrame);
+    const timer = setInterval(() => {
+      const last = lastFrameAtRef.current;
+      if (last !== null && performance.now() - last > FRAME_STALE_AFTER_MS) setStale(true);
+    }, 1000);
+    return () => {
+      stopped = true;
+      clearInterval(timer);
+      if (callbackId !== null) element.cancelVideoFrameCallback(callbackId);
+      element.removeEventListener("timeupdate", markFrame);
+    };
+  }, [track]);
+
+  const placeholder = placeholderFor(phase, track, hasFrame, stale);
+  return (
+    <figure className={`camera-tile${primary ? " camera-tile--primary" : ""}${stale ? " tone-warning" : ""}`}>
+      {/* The element stays mounted while a track exists so attach/detach never races a re-created node. */}
+      {track !== null && <video ref={videoRef} muted autoPlay playsInline aria-label={name} />}
+      {placeholder !== null && <div className="camera-placeholder">{placeholder}</div>}
+      <figcaption>
+        {name}
+        <span className="camera-preview-badge">Preview only, not recorded</span>
+      </figcaption>
+    </figure>
+  );
+}
diff --git a/examples/egocap/frontend/src/livekitPreview.test.ts b/examples/egocap/frontend/src/livekitPreview.test.ts
new file mode 100644
index 0000000000..a00eefd19a
--- /dev/null
+++ b/examples/egocap/frontend/src/livekitPreview.test.ts
@@ -0,0 +1,87 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  fetchLiveKitPreview,
+  LiveKitPreviewHttpError,
+  LiveKitPreviewParseError,
+  parseLiveKitPreview,
+} from "./livekitPreview";
+
+const GOOD = {
+  url: "wss://lk",
+  room: "r",
+  publisher: "orin",
+  token: "tok",
+  tracks: [{ name: "Head left", track: "left" }],
+};
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+function stubFetch(status: number, body: unknown, jsonThrows = false): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(async () => ({
+    status,
+    ok: status >= 200 && status < 300,
+    json: async () => {
+      if (jsonThrows) throw new Error("not json");
+      return body;
+    },
+  }));
+  vi.stubGlobal("fetch", fn);
+  return fn;
+}
+
+describe("parseLiveKitPreview", () => {
+  it("accepts a complete body", () => {
+    expect(parseLiveKitPreview(GOOD)).toEqual(GOOD);
+  });
+
+  it.each([
+    ["null body", null],
+    ["string body", "x"],
+    ["missing url", { ...GOOD, url: undefined }],
+    ["empty room", { ...GOOD, room: "" }],
+    ["non-string publisher", { ...GOOD, publisher: 3 }],
+    ["missing token", { ...GOOD, token: undefined }],
+    ["tracks not an array", { ...GOOD, tracks: "x" }],
+    ["empty tracks", { ...GOOD, tracks: [] }],
+    ["non-object track", { ...GOOD, tracks: ["x"] }],
+    ["track missing name", { ...GOOD, tracks: [{ track: "a" }] }],
+    ["track with empty track id", { ...GOOD, tracks: [{ name: "a", track: "" }] }],
+  ])("rejects %s", (_label, body) => {
+    expect(() => parseLiveKitPreview(body)).toThrow(LiveKitPreviewParseError);
+  });
+});
+
+describe("fetchLiveKitPreview", () => {
+  it("returns the parsed config on 200 and requests the preview route", async () => {
+    const fn = stubFetch(200, GOOD);
+    expect(await fetchLiveKitPreview()).toEqual(GOOD);
+    expect(fn.mock.calls[0][0]).toBe("/api/livekit-preview");
+  });
+
+  it("returns null on 404 because the station has no LiveKit preview", async () => {
+    stubFetch(404, { detail: "LiveKit preview is not configured" });
+    expect(await fetchLiveKitPreview()).toBeNull();
+  });
+
+  it("throws an HTTP error carrying the backend detail on 503", async () => {
+    stubFetch(503, { detail: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set for the backend" });
+    await expect(fetchLiveKitPreview()).rejects.toThrow(LiveKitPreviewHttpError);
+    await expect(fetchLiveKitPreview()).rejects.toThrow("LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set");
+  });
+
+  it("falls back to the status code when an error body is not JSON", async () => {
+    stubFetch(500, null, true);
+    await expect(fetchLiveKitPreview()).rejects.toThrow("HTTP 500");
+  });
+
+  it("throws a parse error when a 200 body is unusable", async () => {
+    stubFetch(200, { url: "wss://lk" });
+    await expect(fetchLiveKitPreview()).rejects.toThrow(LiveKitPreviewParseError);
+  });
+});
diff --git a/examples/egocap/frontend/src/livekitPreview.ts b/examples/egocap/frontend/src/livekitPreview.ts
new file mode 100644
index 0000000000..b21ce3b1c3
--- /dev/null
+++ b/examples/egocap/frontend/src/livekitPreview.ts
@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * Wire shape of GET /api/livekit-preview: where the camera host publishes and a viewer token.
+ *
+ * These cameras are display-only. They come straight from LiveKit to the browser and are neither
+ * requested from CaptureServer nor recorded.
+ */
+
+export interface LiveKitPreviewTrack {
+  /** Operator-facing tile label. */
+  name: string;
+  /** The published video track this tile shows. */
+  track: string;
+}
+
+export interface LiveKitPreviewConfig {
+  url: string;
+  room: string;
+  /** Participant identity of the camera host; a track name is only unique within one participant. */
+  publisher: string;
+  token: string;
+  tracks: LiveKitPreviewTrack[];
+}
+
+export class LiveKitPreviewParseError extends Error {}
+
+/** The backend answered, but not with a usable preview configuration (e.g. 503: signing credentials missing). */
+export class LiveKitPreviewHttpError extends Error {}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value === "") {
+    throw new LiveKitPreviewParseError(`${field} must be a nonempty string`);
+  }
+  return value;
+}
+
+/** Validates a parsed GET /api/livekit-preview body; anything else is a protocol error, never a partial config. */
+export function parseLiveKitPreview(body: unknown): LiveKitPreviewConfig {
+  if (typeof body !== "object" || body === null) throw new LiveKitPreviewParseError("body must be an object");
+  const raw = body as Record<string, unknown>;
+  if (!Array.isArray(raw.tracks) || raw.tracks.length === 0) {
+    throw new LiveKitPreviewParseError("tracks must be a nonempty array");
+  }
+  const tracks = raw.tracks.map((item, i) => {
+    if (typeof item !== "object" || item === null) throw new LiveKitPreviewParseError(`tracks[${i}] must be an object`);
+    const entry = item as Record<string, unknown>;
+    return { name: requireString(entry.name, `tracks[${i}].name`), track: requireString(entry.track, `tracks[${i}].track`) };
+  });
+  return {
+    url: requireString(raw.url, "url"),
+    room: requireString(raw.room, "room"),
+    publisher: requireString(raw.publisher, "publisher"),
+    token: requireString(raw.token, "token"),
+    tracks,
+  };
+}
+
+/** Fetches the preview config, or null when this station has no LiveKit preview configured (HTTP 404). */
+export async function fetchLiveKitPreview(signal?: AbortSignal): Promise<LiveKitPreviewConfig | null> {
+  const response = await fetch("/api/livekit-preview", { signal });
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    // The backend's own reason (e.g. missing signing credentials) is the useful part for the operator.
+    let detail = `HTTP ${response.status}`;
+    try {
+      const body = (await response.json()) as { detail?: unknown };
+      if (typeof body.detail === "string") detail = body.detail;
+    } catch {
+      // Keep the status-only message.
+    }
+    throw new LiveKitPreviewHttpError(detail);
+  }
+  return parseLiveKitPreview(await response.json());
+}
diff --git a/examples/egocap/frontend/src/livekitTestDoubles.ts b/examples/egocap/frontend/src/livekitTestDoubles.ts
new file mode 100644
index 0000000000..fcac66182b
--- /dev/null
+++ b/examples/egocap/frontend/src/livekitTestDoubles.ts
@@ -0,0 +1,70 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/** Fake livekit-client Room and tracks shared by the LiveKit hook and tile tests. */
+import { vi } from "vitest";
+
+type Handler = (...args: any[]) => void;
+
+export class FakeRoom {
+  static instances: FakeRoom[] = [];
+  handlers = new Map<string, Handler[]>();
+  remoteParticipants = new Map<string, any>();
+  connect = vi.fn(async (_url: string, _token: string) => {
+    if (FakeRoom.connectGate !== null) await FakeRoom.connectGate;
+    if (FakeRoom.connectError !== null) throw FakeRoom.connectError;
+  });
+  disconnect = vi.fn(async () => {});
+  /** Participants already in the room when a new Room is created, i.e. published before we joined. */
+  static seed: Array<[string, any]> = [];
+  static connectError: Error | null = null;
+  static connectGate: Promise<void> | null = null;
+
+  constructor() {
+    FakeRoom.instances.push(this);
+    for (const [identity, p] of FakeRoom.seed) this.remoteParticipants.set(identity, p);
+  }
+  on(event: string, handler: Handler): this {
+    this.handlers.set(event, [...(this.handlers.get(event) ?? []), handler]);
+    return this;
+  }
+  emit(event: string, ...args: any[]): void {
+    for (const h of this.handlers.get(event) ?? []) h(...args);
+  }
+  listenerCount(event: string): number {
+    return (this.handlers.get(event) ?? []).length;
+  }
+  static reset(): void {
+    FakeRoom.instances = [];
+    FakeRoom.connectError = null;
+    FakeRoom.connectGate = null;
+    FakeRoom.seed = [];
+  }
+}
+
+export function fakeTrack(): any {
+  return { kind: "video", attach: vi.fn(), detach: vi.fn() };
+}
+
+export function participant(identity: string, published: Array<{ name: string; track: any | null; kind?: string }> = []): any {
+  const trackPublications = new Map(
+    published.map((p, i) => [`s${i}`, { kind: p.kind ?? "video", trackName: p.name, track: p.track }]),
+  );
+  return { identity, trackPublications };
+}
+
+export function publication(name: string): any {
+  return { trackName: name };
+}
+
+export const CONFIG = {
+  url: "wss://lk",
+  room: "r",
+  publisher: "orin",
+  token: "tok",
+  tracks: [
+    { name: "Head left", track: "left" },
+    { name: "Head right", track: "right" },
+  ],
+};
diff --git a/examples/egocap/frontend/src/styles.css b/examples/egocap/frontend/src/styles.css
index 62fb6e2f10..b685836766 100644
--- a/examples/egocap/frontend/src/styles.css
+++ b/examples/egocap/frontend/src/styles.css
@@ -2318,3 +2318,30 @@ below for the narrow/stacked layout). */
     min-width: 0;
   }
 }
+
+/* Direct LiveKit preview tiles: a <video> sized like the MJPEG <img>, with any status text laid over it. */
+.camera-tile video {
+  width: 100%;
+  max-width: 100%;
+  height: auto;
+  display: block;
+}
+
+.op-stage .camera-tile video {
+  flex: 1 1 0;
+  height: 100%;
+  min-height: 0;
+  object-fit: contain;
+}
+
+.camera-tile video + .camera-placeholder {
+  position: absolute;
+  inset: 0;
+  height: auto;
+  background: rgba(0, 0, 0, 0.6);
+}
+
+.camera-preview-badge {
+  margin-left: var(--space-2);
+  opacity: 0.7;
+}
diff --git a/examples/egocap/frontend/src/useLiveKitPreview.test.ts b/examples/egocap/frontend/src/useLiveKitPreview.test.ts
new file mode 100644
index 0000000000..0b3d090648
--- /dev/null
+++ b/examples/egocap/frontend/src/useLiveKitPreview.test.ts
@@ -0,0 +1,339 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { act, cleanup, renderHook } from "@testing-library/react";
+import { CONFIG, FakeRoom, fakeTrack, participant, publication } from "./livekitTestDoubles";
+
+vi.mock("livekit-client", async () => {
+  const doubles = await import("./livekitTestDoubles");
+  return {
+    Room: doubles.FakeRoom,
+    RoomEvent: {
+      TrackSubscribed: "TrackSubscribed",
+      TrackUnsubscribed: "TrackUnsubscribed",
+      ParticipantDisconnected: "ParticipantDisconnected",
+      Reconnecting: "Reconnecting",
+      Reconnected: "Reconnected",
+      Disconnected: "Disconnected",
+    },
+    Track: { Kind: { Video: "video", Audio: "audio" } },
+  };
+});
+
+import { useLiveKitPreview } from "./useLiveKitPreview";
+
+const RETRY_MS = 3000;
+
+function stubFetch(handler: () => Promise<unknown>): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(handler);
+  vi.stubGlobal("fetch", fn);
+  return fn;
+}
+
+const ok = (body: unknown) => async () => ({ status: 200, ok: true, json: async () => body });
+const notFound = async () => ({ status: 404, ok: false, json: async () => ({ detail: "nf" }) });
+
+async function flush(): Promise<void> {
+  await act(async () => {
+    await vi.advanceTimersByTimeAsync(0);
+  });
+}
+
+async function mounted() {
+  const view = renderHook(() => useLiveKitPreview());
+  await flush();
+  return view;
+}
+
+beforeEach(() => {
+  FakeRoom.reset();
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+  vi.unstubAllGlobals();
+});
+
+describe("useLiveKitPreview", () => {
+  it("is unconfigured and creates no Room when the backend answers 404", async () => {
+    stubFetch(notFound);
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("unconfigured");
+    expect(result.current.tiles).toEqual([]);
+    expect(FakeRoom.instances).toHaveLength(0);
+  });
+
+  it("connects with the fetched url and token and lists configured tiles empty", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    expect(FakeRoom.instances[0].connect).toHaveBeenCalledWith("wss://lk", "tok");
+    expect(result.current.phase).toBe("connected");
+    expect(result.current.tiles).toEqual([
+      { name: "Head left", track: null },
+      { name: "Head right", track: null },
+    ]);
+  });
+
+  it("is connecting while the connect is still pending", async () => {
+    stubFetch(ok(CONFIG));
+    let release!: () => void;
+    FakeRoom.connectGate = new Promise<void>((r) => (release = r));
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("connecting");
+    release();
+    await flush();
+    expect(result.current.phase).toBe("connected");
+  });
+
+  it("adopts already-published video tracks of the publisher after connect", async () => {
+    stubFetch(ok(CONFIG));
+    const left = fakeTrack();
+    FakeRoom.seed = [
+      [
+        "orin",
+        participant("orin", [
+          { name: "left", track: left },
+          { name: "right", track: fakeTrack(), kind: "audio" },
+          { name: "right", track: null },
+          { name: "unconfigured", track: fakeTrack() },
+        ]),
+      ],
+    ];
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("connected");
+    expect(result.current.tiles[0].track).toBe(left);
+    expect(result.current.tiles[1].track).toBeNull();
+  });
+
+  it("does not adopt same-named tracks from another participant after connect", async () => {
+    stubFetch(ok(CONFIG));
+    FakeRoom.seed = [["intruder", participant("intruder", [{ name: "left", track: fakeTrack() }])]];
+    const { result } = await mounted();
+    expect(result.current.tiles[0].track).toBeNull();
+  });
+
+  it("picks up tracks published while the SDK was reconnecting", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const room = FakeRoom.instances[0];
+    const left = fakeTrack();
+    room.remoteParticipants.set("orin", participant("orin", [{ name: "left", track: left }]));
+    act(() => room.emit("Reconnected"));
+    expect(result.current.tiles[0].track).toBe(left);
+  });
+
+  it("shows a track on TrackSubscribed for the configured publisher and track name", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const track = fakeTrack();
+    act(() => FakeRoom.instances[0].emit("TrackSubscribed", track, publication("right"), { identity: "orin" }));
+    expect(result.current.tiles[1].track).toBe(track);
+    expect(result.current.tiles[0].track).toBeNull();
+  });
+
+  it("ignores a correctly named track from a different participant", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    act(() => FakeRoom.instances[0].emit("TrackSubscribed", fakeTrack(), publication("left"), { identity: "intruder" }));
+    expect(result.current.tiles[0].track).toBeNull();
+  });
+
+  it("ignores a subscribed audio track with a configured name", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const audio = { ...fakeTrack(), kind: "audio" };
+    act(() => FakeRoom.instances[0].emit("TrackSubscribed", audio, publication("left"), { identity: "orin" }));
+    expect(result.current.tiles[0].track).toBeNull();
+  });
+
+  it("clears a tile on TrackUnsubscribed", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const track = fakeTrack();
+    act(() => FakeRoom.instances[0].emit("TrackSubscribed", track, publication("left"), { identity: "orin" }));
+    act(() => FakeRoom.instances[0].emit("TrackUnsubscribed", track, publication("left"), { identity: "orin" }));
+    expect(result.current.tiles[0].track).toBeNull();
+  });
+
+  it("keeps a republished track when the old one is unsubscribed afterwards", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const oldTrack = fakeTrack();
+    const newTrack = fakeTrack();
+    const room = FakeRoom.instances[0];
+    act(() => room.emit("TrackSubscribed", oldTrack, publication("left"), { identity: "orin" }));
+    act(() => room.emit("TrackSubscribed", newTrack, publication("left"), { identity: "orin" }));
+    act(() => room.emit("TrackUnsubscribed", oldTrack, publication("left"), { identity: "orin" }));
+    expect(result.current.tiles[0].track).toBe(newTrack);
+  });
+
+  it("clears every tile when the publisher disconnects but not for another participant", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const room = FakeRoom.instances[0];
+    act(() => room.emit("TrackSubscribed", fakeTrack(), publication("left"), { identity: "orin" }));
+    act(() => room.emit("TrackSubscribed", fakeTrack(), publication("right"), { identity: "orin" }));
+    act(() => room.emit("ParticipantDisconnected", { identity: "someone-else" }));
+    expect(result.current.tiles[0].track).not.toBeNull();
+    act(() => room.emit("ParticipantDisconnected", { identity: "orin" }));
+    expect(result.current.tiles.map((t) => t.track)).toEqual([null, null]);
+    expect(result.current.phase).toBe("connected");
+  });
+
+  it("reports reconnecting then connected, keeping tracks across the SDK reconnect", async () => {
+    stubFetch(ok(CONFIG));
+    const { result } = await mounted();
+    const room = FakeRoom.instances[0];
+    const track = fakeTrack();
+    act(() => room.emit("TrackSubscribed", track, publication("left"), { identity: "orin" }));
+    act(() => room.emit("Reconnecting"));
+    expect(result.current.phase).toBe("reconnecting");
+    act(() => room.emit("Reconnected"));
+    expect(result.current.phase).toBe("connected");
+    expect(result.current.tiles[0].track).toBe(track);
+    expect(FakeRoom.instances).toHaveLength(1);
+  });
+
+  it("registers each listener once per Room", async () => {
+    stubFetch(ok(CONFIG));
+    await mounted();
+    const room = FakeRoom.instances[0];
+    for (const event of ["TrackSubscribed", "TrackUnsubscribed", "ParticipantDisconnected", "Reconnecting", "Reconnected", "Disconnected"]) {
+      expect(room.listenerCount(event)).toBe(1);
+    }
+  });
+
+  it("on full Disconnected shows an error, then refetches a fresh token and builds a new Room after the delay", async () => {
+    let n = 0;
+    const fetchFn = stubFetch(async () => ({ status: 200, ok: true, json: async () => ({ ...CONFIG, token: `tok${++n}` }) }));
+    const { result } = await mounted();
+    act(() => FakeRoom.instances[0].emit("Disconnected"));
+    expect(result.current.phase).toBe("error");
+    expect(result.current.message).toBe("Disconnected from the LiveKit room");
+    expect(result.current.tiles.map((t) => t.track)).toEqual([null, null]);
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS - 1);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(1);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+    expect(FakeRoom.instances).toHaveLength(2);
+    expect(FakeRoom.instances[1].connect).toHaveBeenCalledWith("wss://lk", "tok2");
+    expect(result.current.phase).toBe("connected");
+  });
+
+  it("retries after a failed connect with the SDK's message", async () => {
+    stubFetch(ok(CONFIG));
+    FakeRoom.connectError = new Error("ws refused");
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("error");
+    expect(result.current.message).toBe("ws refused");
+    FakeRoom.connectError = null;
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS);
+    });
+    expect(FakeRoom.instances).toHaveLength(2);
+    expect(result.current.phase).toBe("connected");
+  });
+
+  it("reports the backend's detail on HTTP 503 and keeps retrying", async () => {
+    const fetchFn = stubFetch(async () => ({ status: 503, ok: false, json: async () => ({ detail: "creds missing" }) }));
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("error");
+    expect(result.current.message).toBe("creds missing");
+    expect(FakeRoom.instances).toHaveLength(0);
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it("reports a parse error for an unusable body", async () => {
+    stubFetch(ok({ url: "wss://lk" }));
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("error");
+    expect(result.current.message).toContain("must be");
+  });
+
+  it("reports 'Cannot reach the backend' on a network failure and retries after the delay", async () => {
+    let fail = true;
+    const fetchFn = stubFetch(async () => {
+      if (fail) throw new TypeError("fetch failed");
+      return { status: 200, ok: true, json: async () => CONFIG };
+    });
+    const { result } = await mounted();
+    expect(result.current.phase).toBe("error");
+    expect(result.current.message).toBe("Cannot reach the backend");
+    expect(result.current.tiles).toEqual([]);
+    fail = false;
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+    expect(result.current.phase).toBe("connected");
+  });
+
+  it("disconnects on unmount and does not retry afterwards", async () => {
+    const fetchFn = stubFetch(ok(CONFIG));
+    const { unmount } = await mounted();
+    const room = FakeRoom.instances[0];
+    unmount();
+    expect(room.disconnect).toHaveBeenCalledTimes(1);
+    // The Disconnected the SDK emits on teardown must not schedule a retry.
+    room.emit("Disconnected");
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS * 3);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    expect(FakeRoom.instances).toHaveLength(1);
+  });
+
+  it("cancels a pending retry on unmount", async () => {
+    const fetchFn = stubFetch(async () => {
+      throw new TypeError("down");
+    });
+    const { unmount } = await mounted();
+    unmount();
+    await act(async () => {
+      await vi.advanceTimersByTimeAsync(RETRY_MS * 3);
+    });
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+  });
+
+  it("aborts the in-flight config fetch on unmount and creates no Room", async () => {
+    let signal: AbortSignal | undefined;
+    let resolve!: (v: unknown) => void;
+    vi.stubGlobal(
+      "fetch",
+      vi.fn((_url: string, init: { signal: AbortSignal }) => {
+        signal = init.signal;
+        return new Promise((r) => (resolve = r));
+      }),
+    );
+    const { unmount } = renderHook(() => useLiveKitPreview());
+    unmount();
+    expect(signal?.aborted).toBe(true);
+    resolve({ status: 200, ok: true, json: async () => CONFIG });
+    await flush();
+    expect(FakeRoom.instances).toHaveLength(0);
+  });
+
+  it("disconnects a Room whose connect finishes after unmount", async () => {
+    stubFetch(ok(CONFIG));
+    let release!: () => void;
+    FakeRoom.connectGate = new Promise<void>((r) => (release = r));
+    const { unmount } = await mounted();
+    const room = FakeRoom.instances[0];
+    unmount();
+    release();
+    await flush();
+    expect(room.disconnect).toHaveBeenCalled();
+  });
+});
diff --git a/examples/egocap/frontend/src/useLiveKitPreview.ts b/examples/egocap/frontend/src/useLiveKitPreview.ts
new file mode 100644
index 0000000000..e81eb6fc42
--- /dev/null
+++ b/examples/egocap/frontend/src/useLiveKitPreview.ts
@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * One LiveKit room connection for every preview tile.
+ *
+ * Connects once the backend says a preview is configured, picks each configured track out of the camera host's
+ * participant (whether it was published before we joined or after), and lets the SDK handle ordinary network
+ * reconnects. Only a full disconnect starts a new attempt, with a freshly fetched token.
+ */
+
+import { useEffect, useState } from "react";
+import { Room, RoomEvent, Track } from "livekit-client";
+import type { RemoteParticipant, RemoteTrack } from "livekit-client";
+import { fetchLiveKitPreview, LiveKitPreviewHttpError, LiveKitPreviewParseError } from "./livekitPreview";
+import type { LiveKitPreviewConfig } from "./livekitPreview";
+
+/** Delay before a new attempt after a failed connect or a full disconnect. */
+const RETRY_DELAY_MS = 3000;
+
+export type LiveKitPhase = "loading" | "unconfigured" | "connecting" | "connected" | "reconnecting" | "error";
+
+export interface LiveKitTile {
+  name: string;
+  /** The subscribed video track, or null while the camera host has not published it. */
+  track: RemoteTrack | null;
+}
+
+export interface LiveKitPreviewState {
+  phase: LiveKitPhase;
+  /** Why the preview is unavailable, when ``phase`` is "error". */
+  message: string | null;
+  /** One entry per configured track, in configuration order; empty until the configuration is known. */
+  tiles: LiveKitTile[];
+}
+
+const INITIAL: LiveKitPreviewState = { phase: "loading", message: null, tiles: [] };
+
+/** The configured tiles with the given subscribed tracks filled in by track name. */
+function tilesFor(config: LiveKitPreviewConfig, tracks: Map<string, RemoteTrack>): LiveKitTile[] {
+  return config.tracks.map((t) => ({ name: t.name, track: tracks.get(t.track) ?? null }));
+}
+
+/** Connects to the configured LiveKit room for the lifetime of the calling component. */
+export function useLiveKitPreview(): LiveKitPreviewState {
+  const [state, setState] = useState<LiveKitPreviewState>(INITIAL);
+
+  useEffect(() => {
+    // `cancelled` ends every in-flight attempt and pending retry when the component unmounts.
+    let cancelled = false;
+    let retryTimer: ReturnType<typeof setTimeout> | null = null;
+    let room: Room | null = null;
+    const controller = new AbortController();
+
+    function scheduleRetry(): void {
+      if (cancelled || retryTimer !== null) return;
+      retryTimer = setTimeout(() => {
+        retryTimer = null;
+        void attempt();
+      }, RETRY_DELAY_MS);
+    }
+
+    function fail(message: string, config: LiveKitPreviewConfig | null): void {
+      if (cancelled) return;
+      setState({ phase: "error", message, tiles: config === null ? [] : tilesFor(config, new Map()) });
+      scheduleRetry();
+    }
+
+    async function attempt(): Promise<void> {
+      let config: LiveKitPreviewConfig | null;
+      try {
+        // A fresh token for every attempt: the previous one may have expired while we were disconnected.
+        config = await fetchLiveKitPreview(controller.signal);
+      } catch (error) {
+        if (cancelled) return;
+        // Say why the preview is unavailable, including when the backend could not be reached at all: staying
+        // silent would make a configured station look like one with no cameras. The retry continues either way.
+        const reason =
+          error instanceof LiveKitPreviewHttpError || error instanceof LiveKitPreviewParseError
+            ? error.message
+            : "Cannot reach the backend";
+        fail(reason, null);
+        return;
+      }
+      if (cancelled) return;
+      if (config === null) {
+        setState({ phase: "unconfigured", message: null, tiles: [] });
+        return;
+      }
+      const active = config;
+      const tracks = new Map<string, RemoteTrack>();
+      const publish = (phase: LiveKitPhase): void => {
+        if (!cancelled) setState({ phase, message: null, tiles: tilesFor(active, tracks) });
+      };
+
+      /** Records the camera host's configured video tracks that are already subscribed. */
+      const adopt = (participant: RemoteParticipant): void => {
+        if (participant.identity !== active.publisher) return;
+        for (const publication of participant.trackPublications.values()) {
+          if (publication.kind === Track.Kind.Video && publication.track) {
+            tracks.set(publication.trackName, publication.track);
+          }
+        }
+      };
+
+      const next = new Room();
+      room = next;
+      next
+        .on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
+          if (participant.identity !== active.publisher || track.kind !== Track.Kind.Video) return;
+          tracks.set(publication.trackName, track);
+          publish("connected");
+        })
+        .on(RoomEvent.TrackUnsubscribed, (track, publication) => {
+          // Only drop the mapping if it is still this track: a republication may already have replaced it.
+          if (tracks.get(publication.trackName) === track) tracks.delete(publication.trackName);
+          publish("connected");
+        })
+        .on(RoomEvent.ParticipantDisconnected, (participant) => {
+          if (participant.identity !== active.publisher) return;
+          tracks.clear();
+          publish("connected");
+        })
+        .on(RoomEvent.Reconnecting, () => publish("reconnecting"))
+        .on(RoomEvent.Reconnected, () => {
+          // The SDK resumed the session; pick up anything published while it was away.
+          next.remoteParticipants.forEach(adopt);
+          publish("connected");
+        })
+        .on(RoomEvent.Disconnected, () => {
+          // Not a reconnect: the SDK gave up or the server closed the room. Start over with a new token.
+          tracks.clear();
+          fail("Disconnected from the LiveKit room", active);
+        });
+
+      publish("connecting");
+      try {
+        await next.connect(active.url, active.token);
+      } catch (error) {
+        if (!cancelled) fail(error instanceof Error ? error.message : String(error), active);
+        return;
+      }
+      if (cancelled) {
+        void next.disconnect();
+        return;
+      }
+      // Tracks published before we joined arrive here rather than through TrackSubscribed.
+      next.remoteParticipants.forEach(adopt);
+      publish("connected");
+    }
+
+    void attempt();
+
+    return () => {
+      cancelled = true;
+      controller.abort();
+      if (retryTimer !== null) clearTimeout(retryTimer);
+      // Detaches every track and closes the connection; the Disconnected handler above is a no-op once cancelled.
+      void room?.disconnect();
+      room = null;
+    };
+  }, []);
+
+  return state;
+}
diff --git a/examples/egocap/tests/backend/test_livekit_preview.py b/examples/egocap/tests/backend/test_livekit_preview.py
new file mode 100644
index 0000000000..4f14fb8fdd
--- /dev/null
+++ b/examples/egocap/tests/backend/test_livekit_preview.py
@@ -0,0 +1,180 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The LiveKit viewer token (decoded independently of the signer) and GET /api/livekit-preview."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+import json
+
+import pytest
+from fastapi.testclient import TestClient
+
+from egocap_web.app import app
+from egocap_web.livekit_preview import (
+    API_KEY_ENV,
+    API_SECRET_ENV,
+    LiveKitPreview,
+    LiveKitTrack,
+    subscriber_token,
+)
+
+KEY = "APIkeyForTests"
+SECRET = "super-secret-signing-value-0123456789"
+
+
+def _unb64(segment: str) -> bytes:
+    return base64.urlsafe_b64decode(segment + "=" * (-len(segment) % 4))
+
+
+def _decode(token: str) -> tuple[dict, dict, bytes, bytes]:
+    """header, claims, raw signature, signing input -- parsed with nothing but base64 and json."""
+    header_b64, claims_b64, sig_b64 = token.split(".")
+    assert "=" not in token
+    return (
+        json.loads(_unb64(header_b64)),
+        json.loads(_unb64(claims_b64)),
+        _unb64(sig_b64),
+        f"{header_b64}.{claims_b64}".encode("ascii"),
+    )
+
+
+def _hs256(secret: str, signing_input: bytes) -> bytes:
+    return hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
+
+
+def test_token_header_is_hs256_jwt():
+    header, _, _, _ = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1000))
+    assert header == {"alg": "HS256", "typ": "JWT"}
+
+
+def test_token_claims_name_issuer_validity_window_and_subscribe_only_grant():
+    _, claims, _, _ = _decode(
+        subscriber_token(api_key=KEY, api_secret=SECRET, room="sensing-preview", now=1000, ttl_s=60)
+    )
+    assert claims["iss"] == KEY
+    assert claims["nbf"] == 1000
+    assert claims["exp"] == 1060
+    assert claims["sub"].startswith("egocap-viewer-")
+    assert claims["video"] == {
+        "room": "sensing-preview",
+        "roomJoin": True,
+        "canSubscribe": True,
+        "canPublish": False,
+        "canPublishData": False,
+    }
+
+
+def test_token_default_ttl_is_one_hour():
+    _, claims, _, _ = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=5))
+    assert claims["exp"] - claims["nbf"] == 3600
+
+
+def test_every_token_gets_a_unique_viewer_identity():
+    subs = {
+        _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1))[1]["sub"] for _ in range(50)
+    }
+    assert len(subs) == 50
+
+
+def test_signature_verifies_with_the_secret_and_not_with_another():
+    _, _, signature, signing_input = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1))
+    assert hmac.compare_digest(signature, _hs256(SECRET, signing_input))
+    assert not hmac.compare_digest(signature, _hs256("another-secret", signing_input))
+
+
+def test_token_never_contains_the_secret():
+    token = subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1)
+    assert SECRET not in token
+    assert SECRET.encode() not in b"".join(_unb64(s) for s in token.split(".")[:2])
+
+
+@pytest.fixture
+def client_factory():
+    """A TestClient over the real app with app.state.livekit_preview set directly (no lifespan needed)."""
+    previous = getattr(app.state, "livekit_preview", None)
+
+    def make(preview: LiveKitPreview | None) -> TestClient:
+        app.state.livekit_preview = preview
+        return TestClient(app)
+
+    yield make
+    app.state.livekit_preview = previous
+
+
+PREVIEW = LiveKitPreview(
+    url="wss://lk.example:7881",
+    room="sensing-preview",
+    publisher="orin-sensing",
+    tracks=(LiveKitTrack("Head left", "sensing-left"), LiveKitTrack("Head right", "sensing-right")),
+)
+
+
+def test_unconfigured_station_gets_404_with_no_store(client_factory, monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV, KEY)
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    response = client_factory(None).get("/api/livekit-preview")
+    assert response.status_code == 404
+    assert response.headers["cache-control"] == "no-store"
+
+
+@pytest.mark.parametrize("missing", [(API_KEY_ENV,), (API_SECRET_ENV,), (API_KEY_ENV, API_SECRET_ENV)])
+def test_missing_credentials_give_503_naming_variables_but_no_values(client_factory, monkeypatch, missing):
+    monkeypatch.setenv(API_KEY_ENV, KEY)
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    for name in missing:
+        monkeypatch.delenv(name)
+    response = client_factory(PREVIEW).get("/api/livekit-preview")
+    assert response.status_code == 503
+    assert response.headers["cache-control"] == "no-store"
+    detail = response.json()["detail"]
+    assert API_KEY_ENV in detail and API_SECRET_ENV in detail
+    assert SECRET not in response.text
+    assert KEY not in response.text
+
+
+def test_empty_credentials_count_as_unset(client_factory, monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV, "")
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    assert client_factory(PREVIEW).get("/api/livekit-preview").status_code == 503
+
+
+def test_configured_station_gets_config_and_verifiable_token(client_factory, monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV, KEY)
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    response = client_factory(PREVIEW).get("/api/livekit-preview")
+    assert response.status_code == 200
+    assert response.headers["cache-control"] == "no-store"
+    body = response.json()
+    assert set(body) == {"url", "room", "publisher", "token", "tracks"}
+    assert body["url"] == "wss://lk.example:7881"
+    assert body["room"] == "sensing-preview"
+    assert body["publisher"] == "orin-sensing"
+    assert body["tracks"] == [
+        {"name": "Head left", "track": "sensing-left"},
+        {"name": "Head right", "track": "sensing-right"},
+    ]
+    _, claims, signature, signing_input = _decode(body["token"])
+    assert claims["video"]["room"] == "sensing-preview"
+    assert claims["iss"] == KEY
+    assert hmac.compare_digest(signature, _hs256(SECRET, signing_input))
+
+
+def test_secret_is_never_in_the_response_body_or_headers(client_factory, monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV, KEY)
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    response = client_factory(PREVIEW).get("/api/livekit-preview")
+    assert SECRET not in response.text
+    assert SECRET not in str(dict(response.headers))
+
+
+def test_each_request_gets_a_fresh_viewer_identity(client_factory, monkeypatch):
+    monkeypatch.setenv(API_KEY_ENV, KEY)
+    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    client = client_factory(PREVIEW)
+    subs = {_decode(client.get("/api/livekit-preview").json()["token"])[1]["sub"] for _ in range(5)}
+    assert len(subs) == 5
diff --git a/examples/egocap/tests/backend/test_station_config_livekit.py b/examples/egocap/tests/backend/test_station_config_livekit.py
new file mode 100644
index 0000000000..83f79a20e8
--- /dev/null
+++ b/examples/egocap/tests/backend/test_station_config_livekit.py
@@ -0,0 +1,145 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The optional ``livekit_preview`` section of the station YAML."""
+
+from pathlib import Path
+
+import pytest
+
+from egocap_web.livekit_preview import LiveKitPreview, LiveKitTrack
+from egocap_web.station_config import StationConfigError, load_station_config
+
+VALID = """
+meta: {}
+livekit_preview:
+  url: wss://lk.example:7881
+  room: sensing-preview
+  publisher: orin-sensing
+  tracks:
+    - name: Head left
+      track: sensing-left
+    - name: Head right
+      track: sensing-right
+"""
+
+
+def _load(tmp_path: Path, text: str):
+    path = tmp_path / "station.yaml"
+    path.write_text(text, encoding="utf-8")
+    return load_station_config(path)
+
+
+def _with_section(section: str) -> str:
+    return "meta: {}\nlivekit_preview:\n" + section
+
+
+def test_valid_section_parses_into_a_preview_with_ordered_tracks(tmp_path):
+    assert _load(tmp_path, VALID).livekit_preview == LiveKitPreview(
+        url="wss://lk.example:7881",
+        room="sensing-preview",
+        publisher="orin-sensing",
+        tracks=(LiveKitTrack("Head left", "sensing-left"), LiveKitTrack("Head right", "sensing-right")),
+    )
+
+
+def test_plain_ws_url_is_accepted(tmp_path):
+    text = VALID.replace("wss://", "ws://")
+    assert _load(tmp_path, text).livekit_preview.url == "ws://lk.example:7881"
+
+
+def test_absent_section_means_no_preview_and_otherwise_unchanged_station(tmp_path):
+    resolved = _load(tmp_path, "meta:\n  egocap_station_name: S\n")
+    assert resolved.livekit_preview is None
+    assert resolved.station_id == "S"
+    assert resolved.cameras == ()
+
+
+def test_livekit_preview_is_not_a_capture_server_camera(tmp_path):
+    assert _load(tmp_path, VALID).cameras == ()
+
+
+def test_four_tracks_are_allowed(tmp_path):
+    tracks = "".join(f"    - name: N{i}\n      track: t{i}\n" for i in range(4))
+    section = f"  url: ws://h\n  room: r\n  publisher: p\n  tracks:\n{tracks}"
+    assert len(_load(tmp_path, _with_section(section)).livekit_preview.tracks) == 4
+
+
+def _section(url="ws://h", room="r", publisher="p", tracks="    - {name: A, track: a}\n") -> str:
+    lines = []
+    for key, value in (("url", url), ("room", room), ("publisher", publisher)):
+        if value is not None:
+            lines.append(f"  {key}: {value!r}\n" if value == "" else f"  {key}: {value}\n")
+    if tracks is not None:
+        lines.append("  tracks:\n" + tracks)
+    return _with_section("".join(lines))
+
+
+@pytest.mark.parametrize(
+    ("text", "message"),
+    [
+        pytest.param("meta: {}\nlivekit_preview: nope\n", "must be a mapping", id="scalar-section"),
+        pytest.param("meta: {}\nlivekit_preview: [a]\n", "must be a mapping", id="list-section"),
+        pytest.param(_section(url=None), r"url must be a nonempty string", id="missing-url"),
+        pytest.param(_section(url=""), r"url must be a nonempty string", id="empty-url"),
+        pytest.param(_section(url="http://h"), "ws:// or wss://", id="http-url"),
+        pytest.param(_section(url="localhost:7880"), "ws:// or wss://", id="schemeless-url"),
+        pytest.param(_section(room=None), r"room must be a nonempty string", id="missing-room"),
+        pytest.param(_section(room=""), r"room must be a nonempty string", id="empty-room"),
+        pytest.param(_section(publisher=None), r"publisher must be a nonempty string", id="missing-publisher"),
+        pytest.param(_section(publisher=""), r"publisher must be a nonempty string", id="empty-publisher"),
+        pytest.param(_section(tracks=None), r"tracks must be a nonempty list", id="missing-tracks"),
+        pytest.param(_section(tracks="    []\n"), r"tracks must be a nonempty list", id="empty-tracks"),
+        pytest.param(
+            _with_section("  url: ws://h\n  room: r\n  publisher: p\n  tracks: x\n"),
+            r"tracks must be a nonempty list",
+            id="non-list-tracks",
+        ),
+        pytest.param(
+            _section(tracks="".join(f"    - {{name: N{i}, track: t{i}}}\n" for i in range(5))),
+            "at most 4",
+            id="too-many-tracks",
+        ),
+        pytest.param(
+            _section(tracks="    - just-a-string\n"), r"tracks\[0\] must be a mapping", id="non-mapping-track"
+        ),
+        pytest.param(
+            _section(tracks="    - {track: a}\n"),
+            r"tracks\[0\]\.name must be a nonempty string",
+            id="missing-name",
+        ),
+        pytest.param(
+            _section(tracks="    - {name: '', track: a}\n"), r"tracks\[0\]\.name must be", id="empty-name"
+        ),
+        pytest.param(
+            _section(tracks="    - {name: A}\n"),
+            r"tracks\[0\]\.track must be a nonempty string",
+            id="missing-track",
+        ),
+        pytest.param(
+            _section(tracks="    - {name: A, track: ''}\n"), r"tracks\[0\]\.track must be", id="empty-track"
+        ),
+        pytest.param(
+            _section(tracks="    - {name: A, track: 5}\n"), r"tracks\[0\]\.track must be", id="non-string-track"
+        ),
+        pytest.param(
+            _section(tracks="    - {name: A, track: a}\n    - {name: B, track: a}\n"),
+            "duplicate track",
+            id="duplicate-track",
+        ),
+        pytest.param(
+            _section(tracks="    - {name: A, track: a}\n    - {name: A, track: b}\n"),
+            "duplicate name",
+            id="duplicate-name",
+        ),
+    ],
+)
+def test_invalid_section_is_a_station_config_error(tmp_path, text, message):
+    with pytest.raises(StationConfigError, match=message):
+        _load(tmp_path, text)
+
+
+def test_error_names_the_station(tmp_path):
+    with pytest.raises(StationConfigError, match="livekit_preview"):
+        _load(tmp_path, "meta: {}\nlivekit_preview: 3\n")

From 2147c923354db77947b1ad84f64b0ee320121c1f Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 22:45:13 -0800
Subject: [PATCH 02/37] egocap: CaptureServer offers the LiveKit streams; the
 backend only issues tokens

Carry a livekit_streams list (URL, room, publisher, track, optional
geometry, timestamp basis) in the existing SessionInit, read from a new
--livekit-streams file. CaptureServer never joins the room and admission
is unchanged. The backend passes the list through the session snapshot and
issues subscribe-only viewer tokens for offered rooms; the browser takes
its tiles from the list and receives the video from LiveKit directly. The
station-file LiveKit section is removed.

Tests for this change follow in the next commit; the previous commit's
tests are stale until then. Not exercised against a real LiveKit server or
the Orin publisher.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  76 ++++++-----
 examples/egocap/backend/README.md             |   4 +-
 examples/egocap/backend/egocap_web/app.py     |   3 -
 .../backend/egocap_web/livekit_preview.py     |  64 +++------
 .../backend/egocap_web/preview_protocol.py    |   2 +
 .../backend/egocap_web/station_config.py      |  56 --------
 .../capture_server/capture_server/client.py   |   3 +
 .../capture_server/livekit_streams.py         |  77 +++++++++++
 .../capture_server/capture_server/protocol.py | 125 +++++++++++++++++-
 .../capture_server/capture_server/server.py   |  25 +++-
 examples/egocap/frontend/src/CameraGrid.tsx   |   2 +-
 .../egocap/frontend/src/captureProtocol.ts    |  33 +++++
 .../egocap/frontend/src/livekitPreview.ts     |  72 +++-------
 .../egocap/frontend/src/useLiveKitPreview.ts  |  94 ++++++-------
 14 files changed, 389 insertions(+), 247 deletions(-)
 create mode 100644 examples/egocap/capture_server/capture_server/livekit_streams.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index d287358b5c..06f4f0f3f7 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -4,19 +4,21 @@ SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserve
 SPDX-License-Identifier: Apache-2.0
 -->
 
-# Live camera preview over LiveKit
+# Live camera video over LiveKit
 
-The camera host (an Orin running the SENSING publisher) publishes hardware-encoded H.264 into a LiveKit room. The
-browser subscribes to those tracks itself and decodes them, so the egocap backend only tells it where the room is and
-hands it a subscribe-only token. CaptureServer keeps doing tracking and control.
+The camera host (an Orin running the SENSING publisher) publishes hardware-encoded H.264 into a LiveKit room.
+CaptureServer says where that video is: it offers the room's streams in the `livekit_streams` list of the existing
+session message, taken from a small file you give it. The egocap backend passes the list on and issues viewer
+tokens; the browser then connects to LiveKit itself to receive the video. No video passes through CaptureServer or
+the backend, and CaptureServer never joins the room.
 
 ```text
 Orin: SIPL -> hardware H.264 -> LiveKit publisher --> LiveKit server --> browser <video>
-PC:   egocap backend (station config + viewer token)     CaptureServer (tracking, control)
+PC:   CaptureServer (--livekit-streams: where the streams are) -> egocap backend (list + viewer token)
 ```
 
-**These tiles are preview-only.** They are not requested from CaptureServer and are not recorded; pressing Record
-saves only the cameras the station already lists under `video_sources`. Every LiveKit tile says so.
+**The tiles are display-only for now and say so.** Saving these streams in a recording is planned but not built, so
+pressing Record does not save them.
 
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.
@@ -28,37 +30,42 @@ server, `livekit-server --dev --bind 0.0.0.0` uses the development key pair prin
 secure context for WebRTC on anything but `localhost`, so use a `wss://` URL with a certificate the browser trusts
 when the browser is not on the server's own machine. Open the server's signalling and media ports between the machines.
 
-## 2. Backend credentials and station file
+## 2. Tell CaptureServer where the streams are
 
-The backend signs viewer tokens with the server's key pair, read from its environment only:
-
-```bash
-export LIVEKIT_API_KEY=...      # the LiveKit server's API key
-export LIVEKIT_API_SECRET=...   # its secret; never put this in the station file
-```
-
-Add a `livekit_preview` section to the station YAML that `EGOCAP_STATION_CONFIG` points at:
+Write a file naming the room and its tracks (this is all CaptureServer needs; it never connects to LiveKit):
 
 ```yaml
-livekit_preview:
-  url: wss://LIVEKIT_HOST          # what the browser connects to
+livekit:
+  url: wss://LIVEKIT_HOST          # what consumers connect to
   room: sensing-preview
   publisher: orin-sensing          # the publisher's participant identity
-  tracks:                          # up to four tiles
-    - name: Head left              # label shown on the tile
-      track: sensing-left          # the published track name
-    - name: Head right
-      track: sensing-right
+  streams:                         # up to eight
+    - {id: head_left, name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+    - {id: head_right, name: Head right, track: sensing-right}
+```
+
+`width`, `height` and `fps` are optional and only describe what to expect; leave them out when unknown. Start
+CaptureServer with `--livekit-streams FILE` in addition to its usual options. The list reaches the backend in the
+session start message, so it appears once the backend's capture session has started. Offering a stream does not mean
+frames are arriving.
+
+## 3. Backend credentials
+
+The backend signs viewer tokens with the server's key pair, read from its environment only:
+
+```bash
+export LIVEKIT_API_KEY=...      # the LiveKit server's API key
+export LIVEKIT_API_SECRET=...   # its secret
 ```
 
-Then start the backend as usual (`uv run uvicorn egocap_web.app:app --app-dir backend --port 8000`). The endpoint is
-`GET /api/livekit-preview`: 404 when the section is absent, 503 when the key pair is not set. The token lets a viewer
-join the room and subscribe, nothing more; like the camera preview routes it is open to anyone who can reach the
-backend, so keep the backend on a trusted network.
+`GET /api/livekit-token?room=ROOM` returns a token that can join that room and subscribe, nothing more. It answers 404
+for a room the session does not offer and 503 when the key pair is not set. Like the camera preview routes it is open
+to anyone who can reach the backend, so keep the backend on a trusted network. Missing credentials stop the video but
+the stream list is still shown.
 
-## 3. Orin publisher
+## 4. Orin publisher
 
-Create a token file for the publisher: a LiveKit token for this room, with identity equal to the station's `publisher`,
+Create a token file for the publisher: a LiveKit token for this room, with identity equal to `publisher` above,
 allowed to publish (for example with LiveKit's `lk token create`; see its `--help`). Then add the LiveKit options to
 the usual `camera_plugin_sensing` invocation, keeping the rig's own platform and configuration arguments:
 
@@ -69,17 +76,18 @@ camera_plugin_sensing ... \
   --add-stream=sensor=1,livekit=sensing-right
 ```
 
-The `livekit=` names must equal the station's `track` values. Start the publisher by hand; closing the browser
+The `livekit=` names must equal the file's `track` values. Start the publisher by hand; closing the browser
 disconnects only that viewer, and the Orin keeps capturing until you stop it.
 
-## 4. Expected result and troubleshooting
+## 5. Expected result and troubleshooting
 
-Opening egocap shows the named tiles next to the tracking view, each marked preview-only. A tile reads "Waiting for
-camera" until its track is published, "No video frames" if a published track stops producing frames, and
-"Disconnected" while the room connection is down; the page reconnects on its own.
+Opening egocap shows the named tiles next to the tracking view. A tile reads "Waiting for camera" until its track is
+published, "No video frames" if a published track stops producing frames, and "Disconnected" while the room
+connection is down; the page reconnects on its own.
 
 | Symptom | Check |
 | --- | --- |
+| No tiles at all | CaptureServer was started with `--livekit-streams`, and the backend's capture session has started. |
 | "LiveKit preview unavailable: ... must be set" | `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` in the backend's environment. |
 | Tiles never leave "Connecting" | The `url` is reachable from the browser; `wss://` certificate trusted; signalling and media ports open. |
 | Connected, tile stays "Waiting for camera" | The publisher's token room and identity match `room` and `publisher`; `livekit=` names match `track`. |
diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md
index ee06c335f6..ecd31b8cc8 100644
--- a/examples/egocap/backend/README.md
+++ b/examples/egocap/backend/README.md
@@ -33,7 +33,7 @@ or restarts it.
 | `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`) and the task it preselects (`preselected_task`). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. |
 | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. |
 | `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. |
-| `GET /api/livekit-preview` | Room, tracks and a subscribe-only token for the direct LiveKit camera preview; 404 unless the station file has a `livekit_preview` section. See [`../LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md). |
+| `GET /api/livekit-token?room=ROOM` | Subscribe-only viewer token for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. See [`../LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md). |
 | `GET /api/task-files`, `GET /api/task-files/{name}` | Read-only task-catalog API; see [`../data/taskfiles/README.md`](../data/taskfiles/README.md). |
 | `GET /recordings/...` | The optional recordings browser's API and file routes, off unless `EGOCAP_RECORDINGS_ENABLED=1`; see [`../recordings_frontend/README.md`](../recordings_frontend/README.md). |
 
@@ -55,7 +55,7 @@ Everything else is an environment variable:
 | --- | --- | --- |
 | `EGOCAP_STATION_CONFIG` | unset (development default) | Path to the deployment station YAML described above. |
 | `EGOCAP_CAPTURE_SERVER_URL` | `ws://127.0.0.1:8082` | Where to connect for tracking/camera data. |
-| `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | unset | The LiveKit server's key pair, used only to sign viewer tokens for `GET /api/livekit-preview`. |
+| `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | unset | The LiveKit server's key pair, used only to sign viewer tokens for `GET /api/livekit-token`. |
 | `EGOCAP_TASK_FILES_DIR` | the shipped `data/taskfiles/` | Which task-catalog directory the task-file API serves. |
 | `EGOCAP_RECORDINGS_ENABLED` | off | Turns on the recordings browser's routes. |
 | `EGOCAP_ALLOWED_ORIGINS` | none (same-origin only) | Comma-separated extra origins allowed to open `WS /api/session` — needed when the frontend is hosted separately or behind a reverse proxy. |
diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index ad9e3873ed..b284f23c2a 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -305,9 +305,6 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     # the WHOLE Begin, not just that one camera, which also takes tracking preview down with it.
     if resolved_station is not None:
         config = replace(config, cameras=resolved_station.cameras)
-    # Direct LiveKit preview is independent of CaptureServer: it only tells the browser where the
-    # room is, so an invalid or absent station YAML simply leaves it unconfigured (404 from its route).
-    app.state.livekit_preview = resolved_station.livekit_preview if resolved_station is not None else None
     # task_text seeds the committed next-task instruction. operator seeds ONLY a prefill
     # default for the frontend's entry field (via recording_command.py's snapshot
     # "default_operator") -- start_episode's own operator parameter always replaces
diff --git a/examples/egocap/backend/egocap_web/livekit_preview.py b/examples/egocap/backend/egocap_web/livekit_preview.py
index 2c91f29b49..e371a99e37 100644
--- a/examples/egocap/backend/egocap_web/livekit_preview.py
+++ b/examples/egocap/backend/egocap_web/livekit_preview.py
@@ -2,14 +2,14 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""Direct LiveKit camera preview: the station's room/track mapping, a subscribe-only token, and one endpoint.
+"""Viewer tokens for the LiveKit video CaptureServer offers.
 
-The camera host publishes already-encoded H.264 into a LiveKit room. The browser subscribes to those tracks
-itself, so the backend never decodes, re-encodes or relays video and does not take part in recording. This module
-only tells the browser where the room is and hands it a short-lived token that can subscribe and nothing else.
+CaptureServer says where the video is (URL, room, publisher, tracks) in the session's ``livekit_streams``. This
+module only issues the credential a consumer needs to join that room and subscribe, so a missing signing key can
+stop video but never hides the stream list. The backend does not decode or relay video.
 
 ``LIVEKIT_API_KEY`` and ``LIVEKIT_API_SECRET`` belong to the LiveKit server and are read from the backend's
-environment only; they never appear in the station YAML, a response or a log line.
+environment only; they never appear in a response or a log line.
 """
 
 from __future__ import annotations
@@ -21,7 +21,6 @@
 import os
 import secrets
 import time
-from dataclasses import dataclass
 
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
@@ -34,27 +33,6 @@
 router = APIRouter()
 
 
-@dataclass(frozen=True)
-class LiveKitTrack:
-    """One camera tile: the operator-facing ``name`` and the published video track ``track`` it shows."""
-
-    name: str
-    track: str
-
-
-@dataclass(frozen=True)
-class LiveKitPreview:
-    """Where the camera host publishes: signalling ``url``, ``room``, ``publisher`` identity and its tracks.
-
-    A track name is only unique within one participant, so the browser selects by publisher plus track.
-    """
-
-    url: str
-    room: str
-    publisher: str
-    tracks: tuple[LiveKitTrack, ...]
-
-
 def _b64url(data: bytes) -> str:
     """URL-safe base64 without padding, as JWT segments require."""
     return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
@@ -65,7 +43,7 @@ def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_
     header = {"alg": "HS256", "typ": "JWT"}
     claims = {
         "iss": api_key,
-        # Each browser gets its own identity: LiveKit disconnects an existing participant that reuses one.
+        # Each consumer gets its own identity: LiveKit disconnects an existing participant that reuses one.
         "sub": f"egocap-viewer-{secrets.token_hex(4)}",
         "nbf": now,
         "exp": now + ttl_s,
@@ -85,30 +63,24 @@ def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_
     return f"{signing_input}.{_b64url(signature)}"
 
 
-@router.get("/api/livekit-preview")
-async def get_livekit_preview(request: Request) -> JSONResponse:
-    """The room, tracks and a fresh subscribe-only token for the browser, or why preview is unavailable.
+@router.get("/api/livekit-token")
+async def get_livekit_token(request: Request, room: str = "") -> JSONResponse:
+    """A fresh subscribe-only token for ``room``, which must be one the current session offers.
 
     Like the camera preview routes this is unauthenticated: anyone who can reach the backend can watch the
-    cameras, which is why the token cannot publish.
+    cameras, which is why the token cannot publish and is only issued for rooms CaptureServer offers.
     """
     headers = {"Cache-Control": "no-store"}
-    preview: LiveKitPreview | None = request.app.state.livekit_preview
-    # Not configured is a normal state for a station that previews through CaptureServer instead.
-    if preview is None:
-        return JSONResponse({"detail": "LiveKit preview is not configured"}, status_code=404, headers=headers)
+    started = request.app.state.monitor.native.started
+    offered = {s.room for s in started.livekit_streams} if started is not None else set()
+    # A token for an arbitrary room would let a caller probe or join rooms this station never advertised.
+    if room not in offered:
+        return JSONResponse({"detail": "room is not offered by CaptureServer"}, status_code=404, headers=headers)
     api_key = os.environ.get(API_KEY_ENV, "")
     api_secret = os.environ.get(API_SECRET_ENV, "")
-    # Configured but unable to sign: say what to set, without echoing any value.
+    # Offered but unable to sign: say what to set, without echoing any value.
     if not api_key or not api_secret:
         detail = f"{API_KEY_ENV} and {API_SECRET_ENV} must be set for the backend"
         return JSONResponse({"detail": detail}, status_code=503, headers=headers)
-    token = subscriber_token(api_key=api_key, api_secret=api_secret, room=preview.room, now=int(time.time()))
-    body = {
-        "url": preview.url,
-        "room": preview.room,
-        "publisher": preview.publisher,
-        "token": token,
-        "tracks": [{"name": t.name, "track": t.track} for t in preview.tracks],
-    }
-    return JSONResponse(body, headers=headers)
+    token = subscriber_token(api_key=api_key, api_secret=api_secret, room=room, now=int(time.time()))
+    return JSONResponse({"token": token}, headers=headers)
diff --git a/examples/egocap/backend/egocap_web/preview_protocol.py b/examples/egocap/backend/egocap_web/preview_protocol.py
index 01461788e6..19eb12e9e9 100644
--- a/examples/egocap/backend/egocap_web/preview_protocol.py
+++ b/examples/egocap/backend/egocap_web/preview_protocol.py
@@ -115,6 +115,8 @@ def _capture_started_to_json(started: CaptureStarted) -> dict:
         "effective_config": started.effective_config.to_json(),
         "clock": started.clock.to_json(),
         "streams": [s.to_json() for s in started.streams],
+        # Where the offered LiveKit video is published; the video itself never passes through the backend.
+        "livekit_streams": [s.to_json() for s in started.livekit_streams],
     }
 
 
diff --git a/examples/egocap/backend/egocap_web/station_config.py b/examples/egocap/backend/egocap_web/station_config.py
index 8d27c98106..53f873185b 100644
--- a/examples/egocap/backend/egocap_web/station_config.py
+++ b/examples/egocap/backend/egocap_web/station_config.py
@@ -32,15 +32,11 @@
 
 from capture_server import protocol as p
 
-from .livekit_preview import LiveKitPreview, LiveKitTrack
-
 STATION_CONFIG_ENV = "EGOCAP_STATION_CONFIG"
 _DEFAULT_FLAT_STATION_ID = "station_01"
 #: Matches capture_server.protocol's own BeginRequest.cameras limit -- checked here too so an
 #: over-limit YAML is a configuration error, not a later capture-startup failure.
 _MAX_CAMERAS = 3
-#: Preview tiles share the camera grid, whose layout tops out at four.
-_MAX_LIVEKIT_TRACKS = 4
 
 
 class StationConfigError(ValueError):
@@ -61,8 +57,6 @@ class ResolvedStation:
     task_description: str | None
     data_dir: Path | None
     cameras: tuple[p.CameraSelection, ...]
-    #: Direct LiveKit camera preview; independent of ``cameras`` and never recorded.
-    livekit_preview: LiveKitPreview | None = None
 
 
 class _DuplicateKeyLoader(yaml.SafeLoader):
@@ -136,55 +130,6 @@ def _resolve_cameras(station_id: str, entry: dict) -> tuple[p.CameraSelection, .
     return tuple(cameras)
 
 
-def _nonempty_str(mapping: dict, key: str, where: str) -> str:
-    """A required nonempty string field of ``mapping``; ``where`` names it in the error."""
-    value = mapping.get(key)
-    if not isinstance(value, str) or not value:
-        raise StationConfigError(f"{where}.{key} must be a nonempty string")
-    return value
-
-
-def _resolve_livekit_preview(station_id: str, entry: dict) -> LiveKitPreview | None:
-    """The optional ``livekit_preview`` section: where the camera host publishes and which tracks to show.
-
-    Absent means the station has no direct LiveKit preview. These cameras are display-only: they are not
-    requested from CaptureServer and are never part of ``cameras``.
-    """
-    raw = entry.get("livekit_preview")
-    if raw is None:
-        return None
-    where = f"station {station_id!r}: livekit_preview"
-    if not isinstance(raw, dict):
-        raise StationConfigError(f"{where} must be a mapping")
-    # The browser connects with this URL, so only the WebSocket schemes LiveKit signalling uses are accepted.
-    url = _nonempty_str(raw, "url", where)
-    if not url.startswith(("ws://", "wss://")):
-        raise StationConfigError(f"{where}.url must start with ws:// or wss://")
-    room = _nonempty_str(raw, "room", where)
-    publisher = _nonempty_str(raw, "publisher", where)
-    raw_tracks = raw.get("tracks")
-    if not isinstance(raw_tracks, list) or not raw_tracks:
-        raise StationConfigError(f"{where}.tracks must be a nonempty list")
-    if len(raw_tracks) > _MAX_LIVEKIT_TRACKS:
-        raise StationConfigError(f"{where}.tracks supports at most {_MAX_LIVEKIT_TRACKS} entries")
-    tracks: list[LiveKitTrack] = []
-    for i, item in enumerate(raw_tracks):
-        if not isinstance(item, dict):
-            raise StationConfigError(f"{where}.tracks[{i}] must be a mapping")
-        tracks.append(
-            LiveKitTrack(
-                name=_nonempty_str(item, "name", f"{where}.tracks[{i}]"),
-                track=_nonempty_str(item, "track", f"{where}.tracks[{i}]"),
-            )
-        )
-    # Two tiles on one track, or two tiles with one label, would be indistinguishable to the operator.
-    if len({t.track for t in tracks}) != len(tracks):
-        raise StationConfigError(f"{where}.tracks has a duplicate track")
-    if len({t.name for t in tracks}) != len(tracks):
-        raise StationConfigError(f"{where}.tracks has a duplicate name")
-    return LiveKitPreview(url=url, room=room, publisher=publisher, tracks=tuple(tracks))
-
-
 def _resolve_one_station(station_id: str, entry: Any, config_dir: Path) -> ResolvedStation:
     """Build a :class:`ResolvedStation` from one station's parsed mapping."""
     if not isinstance(entry, dict):
@@ -217,7 +162,6 @@ def _resolve_one_station(station_id: str, entry: Any, config_dir: Path) -> Resol
         task_description=_str_field(meta, "task_description"),
         data_dir=data_dir,
         cameras=_resolve_cameras(station_id, entry),
-        livekit_preview=_resolve_livekit_preview(station_id, entry),
     )
 
 
diff --git a/examples/egocap/capture_server/capture_server/client.py b/examples/egocap/capture_server/capture_server/client.py
index 5e3eb228e9..cc689302fd 100644
--- a/examples/egocap/capture_server/capture_server/client.py
+++ b/examples/egocap/capture_server/capture_server/client.py
@@ -135,6 +135,8 @@ class CaptureStarted:
     effective_config: p.CaptureConfiguration
     clock: p.CaptureClock
     streams: tuple[FrameDescription | p.CameraStream, ...]
+    #: LiveKit video the server offers (where to find it, not frames it sends); empty from a server without any.
+    livekit_streams: tuple[p.LiveKitStream, ...] = ()
 
 
 def _to_client_started(wire: p.SessionInit) -> CaptureStarted:
@@ -145,6 +147,7 @@ def _to_client_started(wire: p.SessionInit) -> CaptureStarted:
         effective_config=wire.effective_config,
         clock=wire.clock,
         streams=wire.streams,
+        livekit_streams=wire.livekit_streams,
     )
 
 
diff --git a/examples/egocap/capture_server/capture_server/livekit_streams.py b/examples/egocap/capture_server/capture_server/livekit_streams.py
new file mode 100644
index 0000000000..87dfa6a4b5
--- /dev/null
+++ b/examples/egocap/capture_server/capture_server/livekit_streams.py
@@ -0,0 +1,77 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The LiveKit streams a station offers, read from the ``--livekit-streams`` YAML file.
+
+Only locates the video (server URL, room, publisher identity and track names). The server never joins the room:
+each consumer connects to LiveKit itself and learns the live details there.
+
+.. code-block:: yaml
+
+    livekit:
+      url: wss://LIVEKIT_HOST
+      room: sensing-preview
+      publisher: orin-sensing
+      streams:
+        - {id: head_left, name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from . import protocol as p
+
+_ROOM_KEYS = {"url", "room", "publisher", "streams"}
+_STREAM_KEYS = {"id", "name", "track", "width", "height", "fps"}
+
+
+def _mapping(value: object, where: str, allowed: set[str]) -> dict:
+    """A YAML mapping whose keys are all in ``allowed``; a typo is an error, not a silently ignored setting."""
+    if not isinstance(value, dict):
+        raise ValueError(f"{where} must be a mapping")
+    unknown = set(value) - allowed
+    if unknown:
+        raise ValueError(f"{where} has unknown key(s): {sorted(unknown)}")
+    return value
+
+
+def load_livekit_streams(path: Path) -> tuple[p.LiveKitStream, ...]:
+    """The streams named by the YAML file at ``path``; raises ``ValueError`` for anything unusable."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        raise ValueError(f"cannot read LiveKit streams file {path}: {exc}") from exc
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"LiveKit streams file {path} is not valid YAML: {exc}") from exc
+    room = _mapping(_mapping(data, "the file", {"livekit"}).get("livekit"), "livekit", _ROOM_KEYS)
+    raw_streams = room.get("streams")
+    if not isinstance(raw_streams, list):
+        raise ValueError("livekit.streams must be a list")
+    descriptors = []
+    for i, raw in enumerate(raw_streams):
+        entry = _mapping(raw, f"livekit.streams[{i}]", _STREAM_KEYS)
+        descriptors.append(
+            {
+                "stream_id": entry.get("id"),
+                "name": entry.get("name"),
+                "url": room.get("url"),
+                "room": room.get("room"),
+                "publisher": room.get("publisher"),
+                "track": entry.get("track"),
+                "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+                "width": entry.get("width"),
+                "height": entry.get("height"),
+                "fps": entry.get("fps"),
+            }
+        )
+    try:
+        # The wire parser is the one validator: a file that loads is a list every client will accept.
+        return p.parse_livekit_streams(descriptors)
+    except p.ProtocolError as exc:
+        raise ValueError(f"LiveKit streams file {path}: {exc}") from exc
diff --git a/examples/egocap/capture_server/capture_server/protocol.py b/examples/egocap/capture_server/capture_server/protocol.py
index 767d7844c2..1a2c798f83 100644
--- a/examples/egocap/capture_server/capture_server/protocol.py
+++ b/examples/egocap/capture_server/capture_server/protocol.py
@@ -28,6 +28,7 @@
 
 from __future__ import annotations
 
+import math
 import re
 import struct
 from dataclasses import dataclass
@@ -198,6 +199,13 @@ class TimeUnit(IntEnum):
     NANOSECONDS = 1
 
 
+class LiveKitTimestampBasis(IntEnum):
+    """What a LiveKit frame's ``user_timestamp_us`` means: the publisher host's monotonic clock in
+    microseconds, read when the frame is published. Not sensor exposure time and not this host's clock."""
+
+    PUBLISHER_MONOTONIC_US = 1
+
+
 class SampleTimeSemantics(IntEnum):
     HOST_POLL = 1
 
@@ -896,6 +904,116 @@ def camera_stream_descriptor(camera: CameraStreamConfig) -> CameraStream:
     )
 
 
+# ---------------------------------------------------------------------------
+# LiveKit stream descriptors. Separate from the tracking/camera ``streams``
+# above: these are not frames CaptureServer produces. Video goes straight from
+# the publisher to each consumer through a LiveKit room; the descriptor only says
+# where to find it and what it contains.
+# ---------------------------------------------------------------------------
+
+_MAX_LIVEKIT_STREAMS = 8
+_MAX_LIVEKIT_TEXT_LEN = 512
+
+
+def _require_text(value: Any, context: str) -> str:
+    """A nonempty bounded string field."""
+    if not isinstance(value, str) or not value or len(value) > _MAX_LIVEKIT_TEXT_LEN:
+        raise ProtocolError(f"{context} must be a nonempty string of at most {_MAX_LIVEKIT_TEXT_LEN} characters")
+    return value
+
+
+def _optional_positive_int(value: Any, context: str) -> int | None:
+    """A positive integer, or None when the value is not known."""
+    if value is None:
+        return None
+    if type(value) is not int or value <= 0:
+        raise ProtocolError(f"{context} must be a positive integer or null")
+    return value
+
+
+@dataclass(frozen=True)
+class LiveKitStream:
+    """One video stream offered through a LiveKit room.
+
+    ``width``/``height``/``fps`` are the configured values, or None when not known; a consumer learns the
+    actual values from the video itself. Offering a stream does not mean frames are arriving.
+    """
+
+    stream_id: str
+    name: str
+    url: str
+    room: str
+    publisher: str
+    track: str
+    timestamp_basis: LiveKitTimestampBasis = LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
+    width: int | None = None
+    height: int | None = None
+    fps: float | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "stream_id": self.stream_id,
+            "name": self.name,
+            "url": self.url,
+            "room": self.room,
+            "publisher": self.publisher,
+            "track": self.track,
+            "timestamp_basis": int(self.timestamp_basis),
+            "width": self.width,
+            "height": self.height,
+            "fps": self.fps,
+        }
+
+    @classmethod
+    def from_json(cls, data: Any) -> LiveKitStream:
+        keys = {
+            "stream_id", "name", "url", "room", "publisher", "track", "timestamp_basis", "width", "height", "fps",
+        }  # fmt: skip
+        _require_keys(data, keys, "a LiveKit stream descriptor")
+        url = _require_text(data.get("url"), "LiveKit stream.url")
+        if not url.startswith(("ws://", "wss://")):
+            raise ProtocolError("LiveKit stream.url must start with ws:// or wss://")
+        fps = data.get("fps")
+        # NaN and infinity pass an ordinary `<= 0` check but are not valid JSON numbers, so require a finite value.
+        if fps is not None and (
+            isinstance(fps, bool) or not isinstance(fps, (int, float)) or not math.isfinite(fps) or fps <= 0
+        ):
+            raise ProtocolError("LiveKit stream.fps must be a finite positive number or null")
+        return cls(
+            stream_id=_require_text(data.get("stream_id"), "LiveKit stream.stream_id"),
+            name=_require_text(data.get("name"), "LiveKit stream.name"),
+            url=url,
+            room=_require_text(data.get("room"), "LiveKit stream.room"),
+            publisher=_require_text(data.get("publisher"), "LiveKit stream.publisher"),
+            track=_require_text(data.get("track"), "LiveKit stream.track"),
+            timestamp_basis=_require_int_enum(
+                data.get("timestamp_basis"), LiveKitTimestampBasis, "LiveKit stream.timestamp_basis"
+            ),
+            width=_optional_positive_int(data.get("width"), "LiveKit stream.width"),
+            height=_optional_positive_int(data.get("height"), "LiveKit stream.height"),
+            fps=None if fps is None else float(fps),
+        )
+
+
+def parse_livekit_streams(raw: Any) -> tuple[LiveKitStream, ...]:
+    """A ``livekit_streams`` list. Absent means none are offered (a server without the field)."""
+    if raw is None:
+        return ()
+    if not isinstance(raw, list) or len(raw) > _MAX_LIVEKIT_STREAMS:
+        raise ProtocolError(
+            f"SessionInit.livekit_streams must be a list of at most {_MAX_LIVEKIT_STREAMS} entries"
+        )
+    streams = tuple(LiveKitStream.from_json(s) for s in raw)
+    for label, values in (
+        ("stream_id", [s.stream_id for s in streams]),
+        ("name", [s.name for s in streams]),
+        ("publisher/track", [(s.publisher, s.track) for s in streams]),
+    ):
+        if len(values) != len(set(values)):
+            raise ProtocolError(f"SessionInit.livekit_streams has a duplicate {label}")
+    return streams
+
+
 # ---------------------------------------------------------------------------
 # Shared JSON validation helpers, used only by the wire-parsing functions
 # below (parse_begin/parse_stop) -- the only two families CaptureServer
@@ -1676,6 +1794,7 @@ class SessionInit:
     effective_config: CaptureConfiguration
     clock: CaptureClock
     streams: tuple[TrackingStream | CameraStream, ...]
+    livekit_streams: tuple[LiveKitStream, ...] = ()
     type: MessageType = dataclass_field(default=MessageType.SESSION_INIT, init=False)
     version: int = dataclass_field(default=PROTOCOL_VERSION, init=False)
 
@@ -1688,13 +1807,14 @@ def to_json(self) -> dict[str, Any]:
             "effective_config": self.effective_config.to_json(),
             "clock": self.clock.to_json(),
             "streams": [s.to_json() for s in self.streams],
+            "livekit_streams": [s.to_json() for s in self.livekit_streams],
         }
 
     @classmethod
     def from_json(cls, data: Any) -> SessionInit:
         _require_keys(
             data,
-            {"type", "version", "session_id", "mode", "effective_config", "clock", "streams"},
+            {"type", "version", "session_id", "mode", "effective_config", "clock", "streams", "livekit_streams"},
             "SessionInit",
         )
         _require_message_type(data, MessageType.SESSION_INIT)
@@ -1724,6 +1844,7 @@ def from_json(cls, data: Any) -> SessionInit:
             effective_config=CaptureConfiguration.from_json(data.get("effective_config")),
             clock=CaptureClock.from_json(data.get("clock")),
             streams=streams,
+            livekit_streams=parse_livekit_streams(data.get("livekit_streams")),
         )
 
 
@@ -1733,6 +1854,7 @@ def session_init_event(
     mode: CaptureMode,
     begin: BeginRequest,
     streams: list[TrackingStream | CameraStream],
+    livekit_streams: tuple[LiveKitStream, ...] = (),
 ) -> SessionInit:
     return SessionInit(
         session_id=session_id,
@@ -1740,6 +1862,7 @@ def session_init_event(
         effective_config=effective_config(begin),
         clock=_capture_clock(),
         streams=tuple(streams),
+        livekit_streams=livekit_streams,
     )
 
 
diff --git a/examples/egocap/capture_server/capture_server/server.py b/examples/egocap/capture_server/capture_server/server.py
index a6a4091be5..b5f1071106 100644
--- a/examples/egocap/capture_server/capture_server/server.py
+++ b/examples/egocap/capture_server/capture_server/server.py
@@ -40,6 +40,7 @@
 import asyncio
 import collections
 import contextlib
+import dataclasses
 import json
 import logging
 import signal
@@ -180,6 +181,9 @@ class ServerConfig:
     # Manus glove calibration: the worker executable and the managed MCAL directory. None leaves calibration
     # unavailable (a StartCalibration is rejected) and capture unaffected.
     calibration: CalibrationConfig | None = None
+    # LiveKit video offered to clients in SessionInit. Video never passes through this server; the list only says
+    # where each stream is published.
+    livekit_streams: tuple[p.LiveKitStream, ...] = ()
 
     def __post_init__(self) -> None:
         """Resolve the MCAL folder once, then reject one physical camera assigned to more than one logical name."""
@@ -586,8 +590,10 @@ def __init__(
         mode: p.CaptureMode,
         outbox: _Outbox,
         owner_ws: ServerConnection,
+        livekit_streams: tuple[p.LiveKitStream, ...] = (),
     ) -> None:
         self.session_id = begin.session_id
+        self._livekit_streams = livekit_streams
         self.begin = begin
         # Which owner connection started this session -- a NEW owner
         # connecting later (because the old one disconnected while this
@@ -795,7 +801,13 @@ async def _run_unprotected_body(self) -> None:
         if tracking_stream is not None:
             streams.insert(0, tracking_stream)
 
-        init = p.session_init_event(session_id=self.session_id, mode=self._mode, begin=self.begin, streams=streams)
+        init = p.session_init_event(
+            session_id=self.session_id,
+            mode=self._mode,
+            begin=self.begin,
+            streams=streams,
+            livekit_streams=self._livekit_streams,
+        )
         self.init_event = init  # cached for CaptureServer._handle_begin's replay path
         # The shared connection Outbox/writer is already running (started
         # once in CaptureServer._handle_connection, for the whole
@@ -1610,6 +1622,7 @@ async def _handle_begin(self, ws: ServerConnection, data: dict[str, Any]) -> Non
             self._mode,
             self._outbox,
             ws,
+            livekit_streams=self.config.livekit_streams,
         )
         self._active_session = session
         asyncio.ensure_future(self._run_session(session))
@@ -1993,6 +2006,12 @@ def _build_arg_parser() -> argparse.ArgumentParser:
         help="live station: read GMSL camera frames from the camera receiver's local frame feed at this Unix "
         "socket (tracking still comes from IsaacCapture via ISAAC_ROOT); cameras are named with --gmsl-camera",
     )
+    parser.add_argument(
+        "--livekit-streams",
+        type=Path,
+        metavar="FILE",
+        help="YAML file naming the LiveKit video streams to offer clients in SessionInit (see livekit_streams.py)",
+    )
     parser.add_argument(
         "--gmsl-camera",
         action="append",
@@ -2223,6 +2242,10 @@ async def _run_cli(args: argparse.Namespace) -> int:
             source_factory = build_source_factory(
                 config, scenario=args.scenario, seed=args.seed, faults=frozenset(args.fault)
             )
+        if args.livekit_streams is not None:
+            from .livekit_streams import load_livekit_streams
+
+            config = dataclasses.replace(config, livekit_streams=load_livekit_streams(args.livekit_streams))
     except (ValueError, NotImplementedError, OSError, RuntimeError) as exc:
         # A malformed episode is a ValueError (EpisodeFormatError); a missing directory an OSError; an
         # unreachable or malformed frame feed a FeedError (RuntimeError).
diff --git a/examples/egocap/frontend/src/CameraGrid.tsx b/examples/egocap/frontend/src/CameraGrid.tsx
index f5b61bf168..a1571232e1 100644
--- a/examples/egocap/frontend/src/CameraGrid.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.tsx
@@ -187,7 +187,7 @@ export function CameraGrid({
   }
 
   // Direct LiveKit tiles sit beside the CaptureServer ones; they have their own connection and readiness.
-  const livekit = useLiveKitPreview();
+  const livekit = useLiveKitPreview(snapshot?.started?.livekit_streams ?? []);
   const cameras = snapshot?.cameras ?? [];
   const livekitShown = livekit.tiles.length > 0 || livekit.phase === "error";
   if (cameras.length === 0 && !livekitShown) {
diff --git a/examples/egocap/frontend/src/captureProtocol.ts b/examples/egocap/frontend/src/captureProtocol.ts
index 9519d2a36b..df1b706c73 100644
--- a/examples/egocap/frontend/src/captureProtocol.ts
+++ b/examples/egocap/frontend/src/captureProtocol.ts
@@ -339,11 +339,38 @@ function parseStreamDescriptor(value: unknown, field: string): StreamDescriptor
   };
 }
 
+/** One LiveKit video stream CaptureServer offers: where it is published, not frames CaptureServer sends. */
+export interface LiveKitStream {
+  stream_id: string;
+  /** Operator-facing tile label. */
+  name: string;
+  url: string;
+  room: string;
+  /** Participant identity of the camera host; a track name is only unique within one participant. */
+  publisher: string;
+  track: string;
+}
+
 export interface CaptureStarted {
   session_id: string;
   running: boolean;
   mode: CaptureModeValue;
   streams: StreamDescriptor[];
+  /** Empty when the server offers none, or predates the field. */
+  livekit_streams: LiveKitStream[];
+}
+
+/** Validates one `capture.started.livekit_streams` entry; only the fields a consumer needs to find the video. */
+function parseLiveKitStream(value: unknown, field: string): LiveKitStream {
+  if (!isObject(value)) throw new CapturePreviewParseError(`${field} must be an object`);
+  return {
+    stream_id: expectString(value.stream_id, `${field}.stream_id`),
+    name: expectString(value.name, `${field}.name`),
+    url: expectString(value.url, `${field}.url`),
+    room: expectString(value.room, `${field}.room`),
+    publisher: expectString(value.publisher, `${field}.publisher`),
+    track: expectString(value.track, `${field}.track`),
+  };
 }
 
 /** Validates the `capture.started` snapshot member. */
@@ -353,11 +380,17 @@ function parseCaptureStarted(value: unknown): CaptureStarted {
   if (!Array.isArray(streamsRaw)) {
     throw new CapturePreviewParseError("capture.started.streams must be an array");
   }
+  // A backend that predates the field omits it: nothing offered, not an error.
+  const livekitRaw = value.livekit_streams ?? [];
+  if (!Array.isArray(livekitRaw)) {
+    throw new CapturePreviewParseError("capture.started.livekit_streams must be an array");
+  }
   return {
     session_id: expectString(value.session_id, "capture.started.session_id"),
     running: expectBoolean(value.running, "capture.started.running"),
     mode: expectEnum(CaptureMode, value.mode, "capture.started.mode"),
     streams: streamsRaw.map((s, i) => parseStreamDescriptor(s, `capture.started.streams[${i}]`)),
+    livekit_streams: livekitRaw.map((s, i) => parseLiveKitStream(s, `capture.started.livekit_streams[${i}]`)),
   };
 }
 
diff --git a/examples/egocap/frontend/src/livekitPreview.ts b/examples/egocap/frontend/src/livekitPreview.ts
index b21ce3b1c3..cad54e38c5 100644
--- a/examples/egocap/frontend/src/livekitPreview.ts
+++ b/examples/egocap/frontend/src/livekitPreview.ts
@@ -3,65 +3,21 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * Wire shape of GET /api/livekit-preview: where the camera host publishes and a viewer token.
+ * The credential for the LiveKit video CaptureServer offers.
  *
- * These cameras are display-only. They come straight from LiveKit to the browser and are neither
- * requested from CaptureServer nor recorded.
+ * Which streams exist (URL, room, publisher, tracks) comes from CaptureServer in the session snapshot. This
+ * only fetches the viewer token, so a backend without signing keys can still list the streams.
  */
 
-export interface LiveKitPreviewTrack {
-  /** Operator-facing tile label. */
-  name: string;
-  /** The published video track this tile shows. */
-  track: string;
-}
-
-export interface LiveKitPreviewConfig {
-  url: string;
-  room: string;
-  /** Participant identity of the camera host; a track name is only unique within one participant. */
-  publisher: string;
-  token: string;
-  tracks: LiveKitPreviewTrack[];
-}
+/** The backend answered, but did not issue a token (e.g. 503: signing credentials missing). */
+export class LiveKitTokenHttpError extends Error {}
 
-export class LiveKitPreviewParseError extends Error {}
+/** The backend's answer was not the expected `{token}` body. */
+export class LiveKitTokenParseError extends Error {}
 
-/** The backend answered, but not with a usable preview configuration (e.g. 503: signing credentials missing). */
-export class LiveKitPreviewHttpError extends Error {}
-
-function requireString(value: unknown, field: string): string {
-  if (typeof value !== "string" || value === "") {
-    throw new LiveKitPreviewParseError(`${field} must be a nonempty string`);
-  }
-  return value;
-}
-
-/** Validates a parsed GET /api/livekit-preview body; anything else is a protocol error, never a partial config. */
-export function parseLiveKitPreview(body: unknown): LiveKitPreviewConfig {
-  if (typeof body !== "object" || body === null) throw new LiveKitPreviewParseError("body must be an object");
-  const raw = body as Record<string, unknown>;
-  if (!Array.isArray(raw.tracks) || raw.tracks.length === 0) {
-    throw new LiveKitPreviewParseError("tracks must be a nonempty array");
-  }
-  const tracks = raw.tracks.map((item, i) => {
-    if (typeof item !== "object" || item === null) throw new LiveKitPreviewParseError(`tracks[${i}] must be an object`);
-    const entry = item as Record<string, unknown>;
-    return { name: requireString(entry.name, `tracks[${i}].name`), track: requireString(entry.track, `tracks[${i}].track`) };
-  });
-  return {
-    url: requireString(raw.url, "url"),
-    room: requireString(raw.room, "room"),
-    publisher: requireString(raw.publisher, "publisher"),
-    token: requireString(raw.token, "token"),
-    tracks,
-  };
-}
-
-/** Fetches the preview config, or null when this station has no LiveKit preview configured (HTTP 404). */
-export async function fetchLiveKitPreview(signal?: AbortSignal): Promise<LiveKitPreviewConfig | null> {
-  const response = await fetch("/api/livekit-preview", { signal });
-  if (response.status === 404) return null;
+/** Fetches a fresh subscribe-only token for `room`; throws LiveKitTokenHttpError with the backend's reason. */
+export async function fetchLiveKitToken(room: string, signal?: AbortSignal): Promise<string> {
+  const response = await fetch(`/api/livekit-token?room=${encodeURIComponent(room)}`, { signal });
   if (!response.ok) {
     // The backend's own reason (e.g. missing signing credentials) is the useful part for the operator.
     let detail = `HTTP ${response.status}`;
@@ -71,7 +27,11 @@ export async function fetchLiveKitPreview(signal?: AbortSignal): Promise<LiveKit
     } catch {
       // Keep the status-only message.
     }
-    throw new LiveKitPreviewHttpError(detail);
+    throw new LiveKitTokenHttpError(detail);
+  }
+  const body = (await response.json()) as { token?: unknown };
+  if (typeof body.token !== "string" || body.token === "") {
+    throw new LiveKitTokenParseError("token must be a nonempty string");
   }
-  return parseLiveKitPreview(await response.json());
+  return body.token;
 }
diff --git a/examples/egocap/frontend/src/useLiveKitPreview.ts b/examples/egocap/frontend/src/useLiveKitPreview.ts
index e81eb6fc42..555e9d3177 100644
--- a/examples/egocap/frontend/src/useLiveKitPreview.ts
+++ b/examples/egocap/frontend/src/useLiveKitPreview.ts
@@ -3,23 +3,23 @@
 // SPDX-License-Identifier: Apache-2.0
 
 /**
- * One LiveKit room connection for every preview tile.
+ * One LiveKit room connection for every offered video stream.
  *
- * Connects once the backend says a preview is configured, picks each configured track out of the camera host's
- * participant (whether it was published before we joined or after), and lets the SDK handle ordinary network
- * reconnects. Only a full disconnect starts a new attempt, with a freshly fetched token.
+ * CaptureServer says which streams exist; this connects to their room only to receive the video. It picks each
+ * stream's track out of the camera host's participant (whether published before we joined or after), and lets the
+ * SDK handle ordinary network reconnects. Only a full disconnect starts a new attempt, with a fresh token.
  */
 
 import { useEffect, useState } from "react";
 import { Room, RoomEvent, Track } from "livekit-client";
 import type { RemoteParticipant, RemoteTrack } from "livekit-client";
-import { fetchLiveKitPreview, LiveKitPreviewHttpError, LiveKitPreviewParseError } from "./livekitPreview";
-import type { LiveKitPreviewConfig } from "./livekitPreview";
+import type { LiveKitStream } from "./captureProtocol";
+import { fetchLiveKitToken } from "./livekitPreview";
 
 /** Delay before a new attempt after a failed connect or a full disconnect. */
 const RETRY_DELAY_MS = 3000;
 
-export type LiveKitPhase = "loading" | "unconfigured" | "connecting" | "connected" | "reconnecting" | "error";
+export type LiveKitPhase = "idle" | "connecting" | "connected" | "reconnecting" | "error";
 
 export interface LiveKitTile {
   name: string;
@@ -29,25 +29,36 @@ export interface LiveKitTile {
 
 export interface LiveKitPreviewState {
   phase: LiveKitPhase;
-  /** Why the preview is unavailable, when ``phase`` is "error". */
+  /** Why video is unavailable, when ``phase`` is "error". */
   message: string | null;
-  /** One entry per configured track, in configuration order; empty until the configuration is known. */
+  /** One entry per offered stream, in the order offered; empty when nothing is offered. */
   tiles: LiveKitTile[];
 }
 
-const INITIAL: LiveKitPreviewState = { phase: "loading", message: null, tiles: [] };
+const IDLE: LiveKitPreviewState = { phase: "idle", message: null, tiles: [] };
 
-/** The configured tiles with the given subscribed tracks filled in by track name. */
-function tilesFor(config: LiveKitPreviewConfig, tracks: Map<string, RemoteTrack>): LiveKitTile[] {
-  return config.tracks.map((t) => ({ name: t.name, track: tracks.get(t.track) ?? null }));
+/** The offered streams with the given subscribed tracks filled in by track name. */
+function tilesFor(streams: LiveKitStream[], tracks: Map<string, RemoteTrack>): LiveKitTile[] {
+  return streams.map((s) => ({ name: s.name, track: tracks.get(s.track) ?? null }));
 }
 
-/** Connects to the configured LiveKit room for the lifetime of the calling component. */
-export function useLiveKitPreview(): LiveKitPreviewState {
-  const [state, setState] = useState<LiveKitPreviewState>(INITIAL);
+/**
+ * Receives the offered LiveKit streams for the lifetime of the calling component. All streams of one session
+ * share a room and publisher, so the first stream names the connection.
+ */
+export function useLiveKitPreview(streams: LiveKitStream[]): LiveKitPreviewState {
+  const [state, setState] = useState<LiveKitPreviewState>(IDLE);
+  // A new session offering the same streams must not reconnect, so the effect depends on content, not identity.
+  const key = JSON.stringify(streams);
 
   useEffect(() => {
-    // `cancelled` ends every in-flight attempt and pending retry when the component unmounts.
+    const offered: LiveKitStream[] = JSON.parse(key);
+    if (offered.length === 0) {
+      setState(IDLE);
+      return;
+    }
+    const { url, room: roomName, publisher } = offered[0];
+    // `cancelled` ends every in-flight attempt and pending retry when the streams change or the component unmounts.
     let cancelled = false;
     let retryTimer: ReturnType<typeof setTimeout> | null = null;
     let room: Room | null = null;
@@ -61,42 +72,32 @@ export function useLiveKitPreview(): LiveKitPreviewState {
       }, RETRY_DELAY_MS);
     }
 
-    function fail(message: string, config: LiveKitPreviewConfig | null): void {
+    function fail(message: string): void {
       if (cancelled) return;
-      setState({ phase: "error", message, tiles: config === null ? [] : tilesFor(config, new Map()) });
+      setState({ phase: "error", message, tiles: tilesFor(offered, new Map()) });
       scheduleRetry();
     }
 
     async function attempt(): Promise<void> {
-      let config: LiveKitPreviewConfig | null;
+      const tracks = new Map<string, RemoteTrack>();
+      const publish = (phase: LiveKitPhase): void => {
+        if (!cancelled) setState({ phase, message: null, tiles: tilesFor(offered, tracks) });
+      };
+      publish("connecting");
+      let token: string;
       try {
         // A fresh token for every attempt: the previous one may have expired while we were disconnected.
-        config = await fetchLiveKitPreview(controller.signal);
+        token = await fetchLiveKitToken(roomName, controller.signal);
       } catch (error) {
-        if (cancelled) return;
-        // Say why the preview is unavailable, including when the backend could not be reached at all: staying
-        // silent would make a configured station look like one with no cameras. The retry continues either way.
-        const reason =
-          error instanceof LiveKitPreviewHttpError || error instanceof LiveKitPreviewParseError
-            ? error.message
-            : "Cannot reach the backend";
-        fail(reason, null);
+        // Say why video is unavailable, including when the backend could not be reached at all.
+        if (!cancelled) fail(error instanceof Error && error.name !== "TypeError" ? error.message : "Cannot reach the backend");
         return;
       }
       if (cancelled) return;
-      if (config === null) {
-        setState({ phase: "unconfigured", message: null, tiles: [] });
-        return;
-      }
-      const active = config;
-      const tracks = new Map<string, RemoteTrack>();
-      const publish = (phase: LiveKitPhase): void => {
-        if (!cancelled) setState({ phase, message: null, tiles: tilesFor(active, tracks) });
-      };
 
-      /** Records the camera host's configured video tracks that are already subscribed. */
+      /** Records the camera host's offered video tracks that are already subscribed. */
       const adopt = (participant: RemoteParticipant): void => {
-        if (participant.identity !== active.publisher) return;
+        if (participant.identity !== publisher) return;
         for (const publication of participant.trackPublications.values()) {
           if (publication.kind === Track.Kind.Video && publication.track) {
             tracks.set(publication.trackName, publication.track);
@@ -108,7 +109,7 @@ export function useLiveKitPreview(): LiveKitPreviewState {
       room = next;
       next
         .on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
-          if (participant.identity !== active.publisher || track.kind !== Track.Kind.Video) return;
+          if (participant.identity !== publisher || track.kind !== Track.Kind.Video) return;
           tracks.set(publication.trackName, track);
           publish("connected");
         })
@@ -118,7 +119,7 @@ export function useLiveKitPreview(): LiveKitPreviewState {
           publish("connected");
         })
         .on(RoomEvent.ParticipantDisconnected, (participant) => {
-          if (participant.identity !== active.publisher) return;
+          if (participant.identity !== publisher) return;
           tracks.clear();
           publish("connected");
         })
@@ -131,14 +132,13 @@ export function useLiveKitPreview(): LiveKitPreviewState {
         .on(RoomEvent.Disconnected, () => {
           // Not a reconnect: the SDK gave up or the server closed the room. Start over with a new token.
           tracks.clear();
-          fail("Disconnected from the LiveKit room", active);
+          fail("Disconnected from the LiveKit room");
         });
 
-      publish("connecting");
       try {
-        await next.connect(active.url, active.token);
+        await next.connect(url, token);
       } catch (error) {
-        if (!cancelled) fail(error instanceof Error ? error.message : String(error), active);
+        if (!cancelled) fail(error instanceof Error ? error.message : String(error));
         return;
       }
       if (cancelled) {
@@ -160,7 +160,7 @@ export function useLiveKitPreview(): LiveKitPreviewState {
       void room?.disconnect();
       room = null;
     };
-  }, []);
+  }, [key]);
 
   return state;
 }

From 9893a2b03af5539719bd7f4499c3c4b94a368a9f Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 22:54:20 -0800
Subject: [PATCH 03/37] egocap: LiveKit cameras are entries of
 SessionInit.streams

Replace the separate livekit_streams list with a LIVEKIT_IMAGE stream kind
in the one stream registry (stream ids 16 and up; unique names, publishers
and tracks; finite positive fps). A station with no LiveKit streams sends
what it sent before, and the client layout checks and stream registry
ignore the new entries. The backend token route and the browser tiles read
the entries from streams. Rewrite the tests for the unified shape and drop
the station-file ones.

Not exercised against a real LiveKit server or the Orin publisher.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  12 +-
 .../backend/egocap_web/livekit_preview.py     |  11 +-
 .../backend/egocap_web/preview_protocol.py    |   2 -
 .../capture_server/capture_server/client.py   |   8 +-
 .../capture_server/livekit_streams.py         |  46 +-
 .../capture_server/capture_server/protocol.py | 123 +++--
 .../capture_server/capture_server/server.py   |  16 +-
 .../src/App.liveRecordingWire.test.tsx        |   2 -
 .../frontend/src/App.operatorLayout.test.tsx  |   7 +-
 examples/egocap/frontend/src/App.test.tsx     |   7 +-
 .../frontend/src/CameraGrid.livekit.test.tsx  |  48 +-
 .../egocap/frontend/src/CameraGrid.test.tsx   |   7 +-
 examples/egocap/frontend/src/CameraGrid.tsx   |   3 +-
 .../frontend/src/captureProtocol.test.ts      |  69 +++
 .../egocap/frontend/src/captureProtocol.ts    |  68 ++-
 .../frontend/src/livekitPreview.test.ts       |  76 +--
 .../egocap/frontend/src/livekitTestDoubles.ts |  15 +-
 .../frontend/src/useLiveKitPreview.test.ts    | 113 +++--
 .../egocap/frontend/src/useLiveKitPreview.ts  |   8 +-
 .../tests/backend/test_livekit_preview.py     | 112 +++--
 .../backend/test_preview_protocol_livekit.py  |  40 ++
 .../backend/test_station_config_livekit.py    | 145 ------
 .../capture_server/test_livekit_streams.py    | 452 ++++++++++++++++++
 23 files changed, 933 insertions(+), 457 deletions(-)
 create mode 100644 examples/egocap/tests/backend/test_preview_protocol_livekit.py
 delete mode 100644 examples/egocap/tests/backend/test_station_config_livekit.py
 create mode 100644 examples/egocap/tests/capture_server/test_livekit_streams.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index 06f4f0f3f7..e3e020c908 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -7,8 +7,8 @@ SPDX-License-Identifier: Apache-2.0
 # Live camera video over LiveKit
 
 The camera host (an Orin running the SENSING publisher) publishes hardware-encoded H.264 into a LiveKit room.
-CaptureServer says where that video is: it offers the room's streams in the `livekit_streams` list of the existing
-session message, taken from a small file you give it. The egocap backend passes the list on and issues viewer
+CaptureServer says where that video is: it lists the room's cameras in the session's existing `streams` list, next to
+its other cameras, from a small file you give it. The egocap backend passes the list on and issues viewer
 tokens; the browser then connects to LiveKit itself to receive the video. No video passes through CaptureServer or
 the backend, and CaptureServer never joins the room.
 
@@ -40,13 +40,13 @@ livekit:
   room: sensing-preview
   publisher: orin-sensing          # the publisher's participant identity
   streams:                         # up to eight
-    - {id: head_left, name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
-    - {id: head_right, name: Head right, track: sensing-right}
+    - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+    - {name: Head right, track: sensing-right}
 ```
 
 `width`, `height` and `fps` are optional and only describe what to expect; leave them out when unknown. Start
-CaptureServer with `--livekit-streams FILE` in addition to its usual options. The list reaches the backend in the
-session start message, so it appears once the backend's capture session has started. Offering a stream does not mean
+CaptureServer with `--livekit-streams FILE` in addition to its usual options. The entries reach the backend in the
+session start message, so they appear once the backend's capture session has started. Offering a stream does not mean
 frames are arriving.
 
 ## 3. Backend credentials
diff --git a/examples/egocap/backend/egocap_web/livekit_preview.py b/examples/egocap/backend/egocap_web/livekit_preview.py
index e371a99e37..13ef05dd0f 100644
--- a/examples/egocap/backend/egocap_web/livekit_preview.py
+++ b/examples/egocap/backend/egocap_web/livekit_preview.py
@@ -4,7 +4,8 @@
 
 """Viewer tokens for the LiveKit video CaptureServer offers.
 
-CaptureServer says where the video is (URL, room, publisher, tracks) in the session's ``livekit_streams``. This
+CaptureServer says where the video is (URL, room, publisher, track) in the LiveKit camera entries of the
+session's ``streams``. This
 module only issues the credential a consumer needs to join that room and subscribe, so a missing signing key can
 stop video but never hides the stream list. The backend does not decode or relay video.
 
@@ -25,6 +26,8 @@
 from fastapi import APIRouter, Request
 from fastapi.responses import JSONResponse
 
+from capture_server import protocol as p
+
 API_KEY_ENV = "LIVEKIT_API_KEY"
 API_SECRET_ENV = "LIVEKIT_API_SECRET"
 #: A token only has to outlive the page's connect; LiveKit keeps an established connection going afterwards.
@@ -65,14 +68,16 @@ def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_
 
 @router.get("/api/livekit-token")
 async def get_livekit_token(request: Request, room: str = "") -> JSONResponse:
-    """A fresh subscribe-only token for ``room``, which must be one the current session offers.
+    """A fresh subscribe-only token for ``room``, which must be one the current session's LiveKit cameras offer.
 
     Like the camera preview routes this is unauthenticated: anyone who can reach the backend can watch the
     cameras, which is why the token cannot publish and is only issued for rooms CaptureServer offers.
     """
     headers = {"Cache-Control": "no-store"}
     started = request.app.state.monitor.native.started
-    offered = {s.room for s in started.livekit_streams} if started is not None else set()
+    offered = (
+        {s.room for s in started.streams if isinstance(s, p.LiveKitCameraStream)} if started is not None else set()
+    )
     # A token for an arbitrary room would let a caller probe or join rooms this station never advertised.
     if room not in offered:
         return JSONResponse({"detail": "room is not offered by CaptureServer"}, status_code=404, headers=headers)
diff --git a/examples/egocap/backend/egocap_web/preview_protocol.py b/examples/egocap/backend/egocap_web/preview_protocol.py
index 19eb12e9e9..01461788e6 100644
--- a/examples/egocap/backend/egocap_web/preview_protocol.py
+++ b/examples/egocap/backend/egocap_web/preview_protocol.py
@@ -115,8 +115,6 @@ def _capture_started_to_json(started: CaptureStarted) -> dict:
         "effective_config": started.effective_config.to_json(),
         "clock": started.clock.to_json(),
         "streams": [s.to_json() for s in started.streams],
-        # Where the offered LiveKit video is published; the video itself never passes through the backend.
-        "livekit_streams": [s.to_json() for s in started.livekit_streams],
     }
 
 
diff --git a/examples/egocap/capture_server/capture_server/client.py b/examples/egocap/capture_server/capture_server/client.py
index cc689302fd..237de9589c 100644
--- a/examples/egocap/capture_server/capture_server/client.py
+++ b/examples/egocap/capture_server/capture_server/client.py
@@ -134,9 +134,7 @@ class CaptureStarted:
     mode: p.CaptureMode
     effective_config: p.CaptureConfiguration
     clock: p.CaptureClock
-    streams: tuple[FrameDescription | p.CameraStream, ...]
-    #: LiveKit video the server offers (where to find it, not frames it sends); empty from a server without any.
-    livekit_streams: tuple[p.LiveKitStream, ...] = ()
+    streams: tuple[FrameDescription | p.CameraStream | p.LiveKitCameraStream, ...]
 
 
 def _to_client_started(wire: p.SessionInit) -> CaptureStarted:
@@ -147,7 +145,6 @@ def _to_client_started(wire: p.SessionInit) -> CaptureStarted:
         effective_config=wire.effective_config,
         clock=wire.clock,
         streams=wire.streams,
-        livekit_streams=wire.livekit_streams,
     )
 
 
@@ -397,8 +394,9 @@ def from_session_init(cls, event: p.SessionInit) -> _StreamRegistry:
         for stream in event.streams:
             if isinstance(stream, p.TrackingStream):
                 registry.tracking = stream
-            else:
+            elif isinstance(stream, p.CameraStream):
                 registry.cameras[stream.stream_id] = stream
+            # A LiveKit camera is only located here, never decoded from a binary message: nothing to register.
         return registry
 
 
diff --git a/examples/egocap/capture_server/capture_server/livekit_streams.py b/examples/egocap/capture_server/capture_server/livekit_streams.py
index 87dfa6a4b5..dd49a54789 100644
--- a/examples/egocap/capture_server/capture_server/livekit_streams.py
+++ b/examples/egocap/capture_server/capture_server/livekit_streams.py
@@ -14,7 +14,7 @@
       room: sensing-preview
       publisher: orin-sensing
       streams:
-        - {id: head_left, name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+        - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
 """
 
 from __future__ import annotations
@@ -26,7 +26,7 @@
 from . import protocol as p
 
 _ROOM_KEYS = {"url", "room", "publisher", "streams"}
-_STREAM_KEYS = {"id", "name", "track", "width", "height", "fps"}
+_STREAM_KEYS = {"name", "track", "width", "height", "fps"}
 
 
 def _mapping(value: object, where: str, allowed: set[str]) -> dict:
@@ -39,7 +39,7 @@ def _mapping(value: object, where: str, allowed: set[str]) -> dict:
     return value
 
 
-def load_livekit_streams(path: Path) -> tuple[p.LiveKitStream, ...]:
+def load_livekit_streams(path: Path) -> tuple[p.LiveKitCameraStream, ...]:
     """The streams named by the YAML file at ``path``; raises ``ValueError`` for anything unusable."""
     try:
         text = path.read_text(encoding="utf-8")
@@ -53,25 +53,29 @@ def load_livekit_streams(path: Path) -> tuple[p.LiveKitStream, ...]:
     raw_streams = room.get("streams")
     if not isinstance(raw_streams, list):
         raise ValueError("livekit.streams must be a list")
-    descriptors = []
-    for i, raw in enumerate(raw_streams):
-        entry = _mapping(raw, f"livekit.streams[{i}]", _STREAM_KEYS)
-        descriptors.append(
-            {
-                "stream_id": entry.get("id"),
-                "name": entry.get("name"),
-                "url": room.get("url"),
-                "room": room.get("room"),
-                "publisher": room.get("publisher"),
-                "track": entry.get("track"),
-                "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
-                "width": entry.get("width"),
-                "height": entry.get("height"),
-                "fps": entry.get("fps"),
-            }
-        )
     try:
         # The wire parser is the one validator: a file that loads is a list every client will accept.
-        return p.parse_livekit_streams(descriptors)
+        streams = tuple(
+            p.LiveKitCameraStream.from_json(
+                {
+                    "stream_id": p.LIVEKIT_STREAM_ID_BASE + i,
+                    "kind": int(p.StreamKind.LIVEKIT_IMAGE),
+                    "name": entry.get("name"),
+                    "url": room.get("url"),
+                    "room": room.get("room"),
+                    "publisher": room.get("publisher"),
+                    "track": entry.get("track"),
+                    "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+                    "width": entry.get("width"),
+                    "height": entry.get("height"),
+                    "fps": entry.get("fps"),
+                }
+            )
+            for i, entry in enumerate(
+                _mapping(raw, f"livekit.streams[{i}]", _STREAM_KEYS) for i, raw in enumerate(raw_streams)
+            )
+        )
+        p.check_livekit_streams(streams)
     except p.ProtocolError as exc:
         raise ValueError(f"LiveKit streams file {path}: {exc}") from exc
+    return streams
diff --git a/examples/egocap/capture_server/capture_server/protocol.py b/examples/egocap/capture_server/capture_server/protocol.py
index 1a2c798f83..1794708d83 100644
--- a/examples/egocap/capture_server/capture_server/protocol.py
+++ b/examples/egocap/capture_server/capture_server/protocol.py
@@ -166,6 +166,8 @@ class CalibrationStopReason(IntEnum):
 class StreamKind(IntEnum):
     TRACKING = 1
     IMAGE = 2
+    # A camera offered through a LiveKit room: described here, never sent as frames by this server.
+    LIVEKIT_IMAGE = 3
 
 
 class BinaryKind(IntEnum):
@@ -913,6 +915,8 @@ def camera_stream_descriptor(camera: CameraStreamConfig) -> CameraStream:
 
 _MAX_LIVEKIT_STREAMS = 8
 _MAX_LIVEKIT_TEXT_LEN = 512
+#: LiveKit streams take stream_ids above the JPEG cameras' 1-3 so one registry has one id space.
+LIVEKIT_STREAM_ID_BASE = 16
 
 
 def _require_text(value: Any, context: str) -> str:
@@ -932,14 +936,14 @@ def _optional_positive_int(value: Any, context: str) -> int | None:
 
 
 @dataclass(frozen=True)
-class LiveKitStream:
-    """One video stream offered through a LiveKit room.
+class LiveKitCameraStream:
+    """One camera offered through a LiveKit room: a ``streams`` entry that locates video instead of carrying it.
 
     ``width``/``height``/``fps`` are the configured values, or None when not known; a consumer learns the
     actual values from the video itself. Offering a stream does not mean frames are arriving.
     """
 
-    stream_id: str
+    stream_id: int
     name: str
     url: str
     room: str
@@ -949,10 +953,12 @@ class LiveKitStream:
     width: int | None = None
     height: int | None = None
     fps: float | None = None
+    kind: StreamKind = dataclass_field(default=StreamKind.LIVEKIT_IMAGE, init=False)
 
     def to_json(self) -> dict[str, Any]:
         return {
             "stream_id": self.stream_id,
+            "kind": int(self.kind),
             "name": self.name,
             "url": self.url,
             "room": self.room,
@@ -965,53 +971,63 @@ def to_json(self) -> dict[str, Any]:
         }
 
     @classmethod
-    def from_json(cls, data: Any) -> LiveKitStream:
+    def from_json(cls, data: Any) -> LiveKitCameraStream:
         keys = {
-            "stream_id", "name", "url", "room", "publisher", "track", "timestamp_basis", "width", "height", "fps",
+            "stream_id", "kind", "name", "url", "room", "publisher", "track", "timestamp_basis", "width", "height",
+            "fps",
         }  # fmt: skip
-        _require_keys(data, keys, "a LiveKit stream descriptor")
-        url = _require_text(data.get("url"), "LiveKit stream.url")
+        _require_keys(data, keys, "a LiveKit camera stream descriptor")
+        if data.get("kind") != int(StreamKind.LIVEKIT_IMAGE):
+            raise ProtocolError("LiveKit camera stream.kind must be LIVEKIT_IMAGE")
+        stream_id = data.get("stream_id")
+        if type(stream_id) is not int or not (
+            LIVEKIT_STREAM_ID_BASE <= stream_id < LIVEKIT_STREAM_ID_BASE + _MAX_LIVEKIT_STREAMS
+        ):
+            raise ProtocolError(
+                f"LiveKit camera stream.stream_id must be an integer from {LIVEKIT_STREAM_ID_BASE} to "
+                f"{LIVEKIT_STREAM_ID_BASE + _MAX_LIVEKIT_STREAMS - 1}"
+            )
+        url = _require_text(data.get("url"), "LiveKit camera stream.url")
         if not url.startswith(("ws://", "wss://")):
-            raise ProtocolError("LiveKit stream.url must start with ws:// or wss://")
+            raise ProtocolError("LiveKit camera stream.url must start with ws:// or wss://")
         fps = data.get("fps")
         # NaN and infinity pass an ordinary `<= 0` check but are not valid JSON numbers, so require a finite value.
         if fps is not None and (
             isinstance(fps, bool) or not isinstance(fps, (int, float)) or not math.isfinite(fps) or fps <= 0
         ):
-            raise ProtocolError("LiveKit stream.fps must be a finite positive number or null")
+            raise ProtocolError("LiveKit camera stream.fps must be a finite positive number or null")
         return cls(
-            stream_id=_require_text(data.get("stream_id"), "LiveKit stream.stream_id"),
-            name=_require_text(data.get("name"), "LiveKit stream.name"),
+            stream_id=stream_id,
+            name=_require_text(data.get("name"), "LiveKit camera stream.name"),
             url=url,
-            room=_require_text(data.get("room"), "LiveKit stream.room"),
-            publisher=_require_text(data.get("publisher"), "LiveKit stream.publisher"),
-            track=_require_text(data.get("track"), "LiveKit stream.track"),
+            room=_require_text(data.get("room"), "LiveKit camera stream.room"),
+            publisher=_require_text(data.get("publisher"), "LiveKit camera stream.publisher"),
+            track=_require_text(data.get("track"), "LiveKit camera stream.track"),
             timestamp_basis=_require_int_enum(
-                data.get("timestamp_basis"), LiveKitTimestampBasis, "LiveKit stream.timestamp_basis"
+                data.get("timestamp_basis"), LiveKitTimestampBasis, "LiveKit camera stream.timestamp_basis"
             ),
-            width=_optional_positive_int(data.get("width"), "LiveKit stream.width"),
-            height=_optional_positive_int(data.get("height"), "LiveKit stream.height"),
+            width=_optional_positive_int(data.get("width"), "LiveKit camera stream.width"),
+            height=_optional_positive_int(data.get("height"), "LiveKit camera stream.height"),
             fps=None if fps is None else float(fps),
         )
 
 
-def parse_livekit_streams(raw: Any) -> tuple[LiveKitStream, ...]:
-    """A ``livekit_streams`` list. Absent means none are offered (a server without the field)."""
-    if raw is None:
-        return ()
-    if not isinstance(raw, list) or len(raw) > _MAX_LIVEKIT_STREAMS:
-        raise ProtocolError(
-            f"SessionInit.livekit_streams must be a list of at most {_MAX_LIVEKIT_STREAMS} entries"
-        )
-    streams = tuple(LiveKitStream.from_json(s) for s in raw)
-    for label, values in (
-        ("stream_id", [s.stream_id for s in streams]),
-        ("name", [s.name for s in streams]),
-        ("publisher/track", [(s.publisher, s.track) for s in streams]),
-    ):
-        if len(values) != len(set(values)):
-            raise ProtocolError(f"SessionInit.livekit_streams has a duplicate {label}")
-    return streams
+def check_livekit_streams(streams: Any) -> None:
+    """Reject a registry whose LiveKit entries are too many or ambiguous.
+
+    Names are checked against the JPEG cameras too: one camera name must mean one stream. Stream ids are unique
+    across the whole registry already (checked by the caller).
+    """
+    livekit = [s for s in streams if isinstance(s, LiveKitCameraStream)]
+    if len(livekit) > _MAX_LIVEKIT_STREAMS:
+        raise ProtocolError(f"at most {_MAX_LIVEKIT_STREAMS} LiveKit camera streams may be offered")
+    other_names = {s.name for s in streams if isinstance(s, CameraStream)}
+    names = [s.name for s in livekit]
+    if len(names) != len(set(names)) or other_names & set(names):
+        raise ProtocolError("LiveKit camera stream names must be unique among camera streams")
+    locations = [(s.publisher, s.track) for s in livekit]
+    if len(locations) != len(set(locations)):
+        raise ProtocolError("two LiveKit camera streams name the same publisher and track")
 
 
 # ---------------------------------------------------------------------------
@@ -1787,14 +1803,28 @@ def _parse_optional_status(data: Any) -> StatusSnapshot | None:
 # ---------------------------------------------------------------------------
 
 
+def _parse_stream(data: Any) -> TrackingStream | CameraStream | LiveKitCameraStream:
+    """One entry of SessionInit's ``streams``, dispatched on its ``kind``.
+
+    A non-dict entry (e.g. a string or list, however malformed) still reaches a ``from_json`` and its own
+    ``_require_keys`` check, which raises a clean ProtocolError, never AttributeError from calling ``.get`` on
+    something that is not a dict.
+    """
+    kind = data.get("kind") if isinstance(data, dict) else None
+    if kind == int(StreamKind.TRACKING):
+        return TrackingStream.from_json(data)
+    if kind == int(StreamKind.LIVEKIT_IMAGE):
+        return LiveKitCameraStream.from_json(data)
+    return CameraStream.from_json(data)
+
+
 @dataclass(frozen=True)
 class SessionInit:
     session_id: str
     mode: CaptureMode
     effective_config: CaptureConfiguration
     clock: CaptureClock
-    streams: tuple[TrackingStream | CameraStream, ...]
-    livekit_streams: tuple[LiveKitStream, ...] = ()
+    streams: tuple[TrackingStream | CameraStream | LiveKitCameraStream, ...]
     type: MessageType = dataclass_field(default=MessageType.SESSION_INIT, init=False)
     version: int = dataclass_field(default=PROTOCOL_VERSION, init=False)
 
@@ -1807,14 +1837,13 @@ def to_json(self) -> dict[str, Any]:
             "effective_config": self.effective_config.to_json(),
             "clock": self.clock.to_json(),
             "streams": [s.to_json() for s in self.streams],
-            "livekit_streams": [s.to_json() for s in self.livekit_streams],
         }
 
     @classmethod
     def from_json(cls, data: Any) -> SessionInit:
         _require_keys(
             data,
-            {"type", "version", "session_id", "mode", "effective_config", "clock", "streams", "livekit_streams"},
+            {"type", "version", "session_id", "mode", "effective_config", "clock", "streams"},
             "SessionInit",
         )
         _require_message_type(data, MessageType.SESSION_INIT)
@@ -1824,27 +1853,17 @@ def from_json(cls, data: Any) -> SessionInit:
         streams_raw = data.get("streams")
         if not isinstance(streams_raw, list):
             raise ProtocolError("SessionInit.streams must be a list")
-        streams = tuple(
-            TrackingStream.from_json(s)
-            # isinstance guard first: a non-dict entry (e.g. a string or
-            # list, however malformed) must still reach *_.from_json's own
-            # _require_keys check and raise a clean ProtocolError there,
-            # never AttributeError from calling .get on something that
-            # isn't a dict.
-            if isinstance(s, dict) and s.get("kind") == int(StreamKind.TRACKING)
-            else CameraStream.from_json(s)
-            for s in streams_raw
-        )
+        streams = tuple(_parse_stream(s) for s in streams_raw)
         stream_ids = [s.stream_id for s in streams]
         if len(stream_ids) != len(set(stream_ids)):
             raise ProtocolError(f"SessionInit.streams has duplicate stream_id(s): {stream_ids}")
+        check_livekit_streams(streams)
         return cls(
             session_id=session_id,
             mode=mode,
             effective_config=CaptureConfiguration.from_json(data.get("effective_config")),
             clock=CaptureClock.from_json(data.get("clock")),
             streams=streams,
-            livekit_streams=parse_livekit_streams(data.get("livekit_streams")),
         )
 
 
@@ -1853,8 +1872,7 @@ def session_init_event(
     session_id: str,
     mode: CaptureMode,
     begin: BeginRequest,
-    streams: list[TrackingStream | CameraStream],
-    livekit_streams: tuple[LiveKitStream, ...] = (),
+    streams: list[TrackingStream | CameraStream | LiveKitCameraStream],
 ) -> SessionInit:
     return SessionInit(
         session_id=session_id,
@@ -1862,7 +1880,6 @@ def session_init_event(
         effective_config=effective_config(begin),
         clock=_capture_clock(),
         streams=tuple(streams),
-        livekit_streams=livekit_streams,
     )
 
 
diff --git a/examples/egocap/capture_server/capture_server/server.py b/examples/egocap/capture_server/capture_server/server.py
index b5f1071106..5fd93d602c 100644
--- a/examples/egocap/capture_server/capture_server/server.py
+++ b/examples/egocap/capture_server/capture_server/server.py
@@ -183,7 +183,7 @@ class ServerConfig:
     calibration: CalibrationConfig | None = None
     # LiveKit video offered to clients in SessionInit. Video never passes through this server; the list only says
     # where each stream is published.
-    livekit_streams: tuple[p.LiveKitStream, ...] = ()
+    livekit_streams: tuple[p.LiveKitCameraStream, ...] = ()
 
     def __post_init__(self) -> None:
         """Resolve the MCAL folder once, then reject one physical camera assigned to more than one logical name."""
@@ -590,7 +590,7 @@ def __init__(
         mode: p.CaptureMode,
         outbox: _Outbox,
         owner_ws: ServerConnection,
-        livekit_streams: tuple[p.LiveKitStream, ...] = (),
+        livekit_streams: tuple[p.LiveKitCameraStream, ...] = (),
     ) -> None:
         self.session_id = begin.session_id
         self._livekit_streams = livekit_streams
@@ -797,17 +797,13 @@ async def _run_unprotected_body(self) -> None:
         exception here into a recorded diagnostic."""
         tracking_stream = self._tracking_stream()
         camera_streams = tuple(p.camera_stream_descriptor(c) for c in self._cameras)
-        streams: list[p.TrackingStream | p.CameraStream] = list(camera_streams)
+        streams: list[p.TrackingStream | p.CameraStream | p.LiveKitCameraStream] = list(camera_streams)
         if tracking_stream is not None:
             streams.insert(0, tracking_stream)
 
-        init = p.session_init_event(
-            session_id=self.session_id,
-            mode=self._mode,
-            begin=self.begin,
-            streams=streams,
-            livekit_streams=self._livekit_streams,
-        )
+        # Offered LiveKit cameras ride in the same registry; this server never produces frames for them.
+        streams.extend(self._livekit_streams)
+        init = p.session_init_event(session_id=self.session_id, mode=self._mode, begin=self.begin, streams=streams)
         self.init_event = init  # cached for CaptureServer._handle_begin's replay path
         # The shared connection Outbox/writer is already running (started
         # once in CaptureServer._handle_connection, for the whole
diff --git a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
index 5653f4234d..7218e3b4e2 100644
--- a/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
+++ b/examples/egocap/frontend/src/App.liveRecordingWire.test.tsx
@@ -129,8 +129,6 @@ describe("RecordingPanel -> real transport -> real backend wire shape", () => {
   beforeEach(() => {
     FakeWebSocket.instances = [];
     vi.stubGlobal("WebSocket", FakeWebSocket);
-    // CameraGrid asks for a LiveKit preview on mount; this station has none.
-    vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
   });
 
   afterEach(() => {
diff --git a/examples/egocap/frontend/src/App.operatorLayout.test.tsx b/examples/egocap/frontend/src/App.operatorLayout.test.tsx
index 7e9f9f88cd..37fe307ff7 100644
--- a/examples/egocap/frontend/src/App.operatorLayout.test.tsx
+++ b/examples/egocap/frontend/src/App.operatorLayout.test.tsx
@@ -6,7 +6,7 @@
  * The cameras-first operator page: the status bar, the camera stage, the control dock and the side drawer that
  * holds the 3D view and raw data. useCaptureSession is mocked so each test controls the snapshot directly.
  */
-import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import App from "./App";
 import type { PreviewSnapshot } from "./captureProtocol";
@@ -18,11 +18,6 @@ vi.mock("./useCaptureSession", async (importOriginal) => {
   return { ...actual, useCaptureSession: vi.fn() };
 });
 
-// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
-beforeEach(() => {
-  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
-});
-
 afterEach(() => {
   cleanup();
   window.localStorage.clear();
diff --git a/examples/egocap/frontend/src/App.test.tsx b/examples/egocap/frontend/src/App.test.tsx
index eabb56e8c8..8999d9fcf4 100644
--- a/examples/egocap/frontend/src/App.test.tsx
+++ b/examples/egocap/frontend/src/App.test.tsx
@@ -11,7 +11,7 @@
  * directly rather than driving a real socket.
  */
 import type { ReactElement } from "react";
-import { afterEach, beforeEach, describe, expect, it, vi, type Mock } from "vitest";
+import { afterEach, describe, expect, it, vi, type Mock } from "vitest";
 import { act, cleanup, fireEvent, render, screen, within } from "@testing-library/react";
 import App from "./App";
 import { OPERATOR_SETTINGS_FIXTURE, SETTINGS_FIXTURE } from "./settingsTestDoubles";
@@ -24,11 +24,6 @@ vi.mock("./useCaptureSession", async (importOriginal) => {
   return { ...actual, useCaptureSession: vi.fn() };
 });
 
-// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
-beforeEach(() => {
-  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
-});
-
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
diff --git a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
index fc7704ac5f..694c2e1462 100644
--- a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
@@ -1,8 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { cleanup, render, screen } from "@testing-library/react";
 import { CameraGrid } from "./CameraGrid";
-import type { PreviewSnapshot } from "./captureProtocol";
-import { CONFIG, FakeRoom } from "./livekitTestDoubles";
+import type { LiveKitStreamDescriptor, PreviewSnapshot } from "./captureProtocol";
+import { STREAMS, FakeRoom } from "./livekitTestDoubles";
 
 vi.mock("livekit-client", async () => {
   const doubles = await import("./livekitTestDoubles");
@@ -20,7 +20,7 @@ vi.mock("livekit-client", async () => {
   };
 });
 
-function snapshot(names: string[]): PreviewSnapshot {
+function snapshot(names: string[], offered: LiveKitStreamDescriptor[] = []): PreviewSnapshot {
   return {
     version: 1,
     type: 3,
@@ -29,7 +29,7 @@ function snapshot(names: string[]): PreviewSnapshot {
     station_label: "Station",
     profile_label: "Profile",
     connecting: false,
-    started: null,
+    started: { session_id: "s1", running: true, mode: 0, streams: offered },
     status: null,
     stopped: null,
     error_message: null,
@@ -40,8 +40,10 @@ function snapshot(names: string[]): PreviewSnapshot {
   } as PreviewSnapshot;
 }
 
-function stubFetch(status: number, body: unknown): void {
-  vi.stubGlobal("fetch", vi.fn(async () => ({ status, ok: status === 200, json: async () => body })));
+function stubFetch(status: number, body: unknown): ReturnType<typeof vi.fn> {
+  const fn = vi.fn(async () => ({ status, ok: status === 200, json: async () => body }));
+  vi.stubGlobal("fetch", fn);
+  return fn;
 }
 
 async function settled(): Promise<void> {
@@ -56,10 +58,12 @@ afterEach(() => {
   vi.unstubAllGlobals();
 });
 
-describe("CameraGrid with LiveKit preview", () => {
+describe("CameraGrid with offered LiveKit streams", () => {
   it("renders LiveKit tiles beside MJPEG tiles, preview-only, with the MJPEG camera keeping the primary slot", async () => {
-    stubFetch(200, CONFIG);
-    const { container } = render(<CameraGrid snapshot={snapshot(["head_camera"])} live={true} receivedAtMonotonic={performance.now()} />);
+    stubFetch(200, { token: "tok" });
+    const { container } = render(
+      <CameraGrid snapshot={snapshot(["head_camera"], STREAMS)} live={true} receivedAtMonotonic={performance.now()} />,
+    );
     await settled();
     expect(screen.getByText("head_camera")).not.toBeNull();
     expect(screen.getByText("Head left", { exact: false })).not.toBeNull();
@@ -72,15 +76,17 @@ describe("CameraGrid with LiveKit preview", () => {
   });
 
   it("shows only LiveKit tiles, the first as primary, when CaptureServer has no cameras", async () => {
-    stubFetch(200, CONFIG);
-    const { container } = render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    stubFetch(200, { token: "tok" });
+    const { container } = render(
+      <CameraGrid snapshot={snapshot([], STREAMS)} live={false} receivedAtMonotonic={null} />,
+    );
     await settled();
     expect(screen.queryByText("No cameras selected.")).toBeNull();
     expect(container.querySelector(".camera-tile--primary")?.textContent).toContain("Head left");
   });
 
-  it("keeps the empty note and MJPEG behavior unchanged when LiveKit is not configured", async () => {
-    stubFetch(404, { detail: "nf" });
+  it("does not contact the backend and keeps MJPEG behavior when no streams are offered", async () => {
+    const fetchFn = stubFetch(200, { token: "tok" });
     const { container, rerender } = render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
     await settled();
     expect(screen.getByText("No cameras selected.")).not.toBeNull();
@@ -89,20 +95,24 @@ describe("CameraGrid with LiveKit preview", () => {
     expect(container.querySelector(".camera-grid-items")?.className).toContain("camera-grid-items--n2");
     expect(screen.queryByText(/Preview only/)).toBeNull();
     expect(FakeRoom.instances).toHaveLength(0);
+    expect(fetchFn).not.toHaveBeenCalled();
   });
 
-  it("shows the unavailable note with the backend detail when the preview cannot start", async () => {
+  it("shows the unavailable note with the backend detail when the token cannot be issued", async () => {
     stubFetch(503, { detail: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set" });
-    render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    render(<CameraGrid snapshot={snapshot([], STREAMS)} live={false} receivedAtMonotonic={null} />);
     await settled();
     expect(screen.getByText(/LiveKit preview unavailable: LIVEKIT_API_KEY/)).not.toBeNull();
   });
 
   it("shows the unavailable note when the backend cannot be reached", async () => {
-    vi.stubGlobal("fetch", vi.fn(async () => {
-      throw new TypeError("fetch failed");
-    }));
-    render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new TypeError("fetch failed");
+      }),
+    );
+    render(<CameraGrid snapshot={snapshot([], STREAMS)} live={false} receivedAtMonotonic={null} />);
     await settled();
     expect(screen.getByText("LiveKit preview unavailable: Cannot reach the backend")).not.toBeNull();
   });
diff --git a/examples/egocap/frontend/src/CameraGrid.test.tsx b/examples/egocap/frontend/src/CameraGrid.test.tsx
index 6280c1606a..5a4f8feebd 100644
--- a/examples/egocap/frontend/src/CameraGrid.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.test.tsx
@@ -6,16 +6,11 @@
  * CameraGrid's per-tile rate/latency readout: derived from successive snapshots' camera
  * sequence numbers, shown only for live fresh samples, and dashed until enough history exists.
  */
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { act, cleanup, render, screen } from "@testing-library/react";
 import { CameraGrid } from "./CameraGrid";
 import type { PreviewSnapshot } from "./captureProtocol";
 
-// CameraGrid asks the backend for a LiveKit preview on mount; these tests are about other behavior.
-beforeEach(() => {
-  vi.stubGlobal("fetch", vi.fn(async () => ({ status: 404, ok: false, json: async () => ({}) })));
-});
-
 afterEach(() => {
   cleanup();
   vi.useRealTimers();
diff --git a/examples/egocap/frontend/src/CameraGrid.tsx b/examples/egocap/frontend/src/CameraGrid.tsx
index a1571232e1..aeadabd667 100644
--- a/examples/egocap/frontend/src/CameraGrid.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.tsx
@@ -9,6 +9,7 @@
  */
 
 import { useEffect, useRef, useState } from "react";
+import { liveKitStreams } from "./captureProtocol";
 import type { PreviewSnapshot } from "./captureProtocol";
 import { TRACKING_STALE_AFTER_MS } from "./CaptureTree";
 import { CameraRateTracker, formatCameraStats } from "./cameraRates";
@@ -187,7 +188,7 @@ export function CameraGrid({
   }
 
   // Direct LiveKit tiles sit beside the CaptureServer ones; they have their own connection and readiness.
-  const livekit = useLiveKitPreview(snapshot?.started?.livekit_streams ?? []);
+  const livekit = useLiveKitPreview(liveKitStreams(snapshot?.started));
   const cameras = snapshot?.cameras ?? [];
   const livekitShown = livekit.tiles.length > 0 || livekit.phase === "error";
   if (cameras.length === 0 && !livekitShown) {
diff --git a/examples/egocap/frontend/src/captureProtocol.test.ts b/examples/egocap/frontend/src/captureProtocol.test.ts
index 19fff01897..5e2cdb16c1 100644
--- a/examples/egocap/frontend/src/captureProtocol.test.ts
+++ b/examples/egocap/frontend/src/captureProtocol.test.ts
@@ -10,6 +10,7 @@ import {
   PREVIEW_VERSION,
   SNAPSHOT_TYPE,
   parseBinaryHeader,
+  liveKitStreams,
   parseSnapshot,
 } from "./captureProtocol";
 
@@ -63,6 +64,74 @@ function startedWith(streams: unknown[]): Record<string, unknown> {
   return { session_id: "s1", running: false, mode: 0, streams };
 }
 
+const LIVEKIT_STREAM = {
+  kind: 3,
+  stream_id: 16,
+  name: "Head left",
+  url: "wss://lk",
+  room: "r",
+  publisher: "orin",
+  track: "left",
+  timestamp_basis: 1,
+  width: 2560,
+  height: 1984,
+  fps: 30,
+};
+
+function snapshotWithStarted(started: Record<string, unknown>): Record<string, unknown> {
+  return validSnapshot({
+    capture: { connecting: false, started, status: null, stopped: null, error_message: null, binary_generation: null },
+  });
+}
+
+describe("parseSnapshot LiveKit camera streams", () => {
+  it("parses a kind-3 entry in streams into a livekit_camera descriptor", () => {
+    const parsed = parseSnapshot(snapshotWithStarted(startedWith([trackingStreamJson(), LIVEKIT_STREAM])));
+    expect(parsed.started?.streams[1]).toEqual({
+      kind: "livekit_camera",
+      stream_id: 16,
+      name: "Head left",
+      url: "wss://lk",
+      room: "r",
+      publisher: "orin",
+      track: "left",
+    });
+  });
+
+  it("liveKitStreams returns only the LiveKit entries, in order", () => {
+    const parsed = parseSnapshot(
+      snapshotWithStarted(
+        startedWith([trackingStreamJson(), cameraStreamJson(), LIVEKIT_STREAM, { ...LIVEKIT_STREAM, stream_id: 17, name: "Head right", track: "right" }]),
+      ),
+    );
+    expect(liveKitStreams(parsed.started).map((s) => s.name)).toEqual(["Head left", "Head right"]);
+  });
+
+  it("liveKitStreams is empty when there is no session or no LiveKit entry", () => {
+    expect(liveKitStreams(null)).toEqual([]);
+    expect(liveKitStreams(undefined)).toEqual([]);
+    const parsed = parseSnapshot(snapshotWithStarted(startedWith([cameraStreamJson()])));
+    expect(liveKitStreams(parsed.started)).toEqual([]);
+  });
+
+  it.each([
+    ["a missing url", { ...LIVEKIT_STREAM, url: undefined }],
+    ["a missing publisher", { ...LIVEKIT_STREAM, publisher: undefined }],
+    ["a numeric track", { ...LIVEKIT_STREAM, track: 3 }],
+    ["a numeric name", { ...LIVEKIT_STREAM, name: 3 }],
+    ["a non-numeric stream_id", { ...LIVEKIT_STREAM, stream_id: "16" }],
+    ["a zero stream_id", { ...LIVEKIT_STREAM, stream_id: 0 }],
+  ])("rejects %s", (_label, entry) => {
+    expect(() => parseSnapshot(snapshotWithStarted(startedWith([entry])))).toThrow(CapturePreviewParseError);
+  });
+
+  it("still rejects an unknown stream kind", () => {
+    expect(() => parseSnapshot(snapshotWithStarted(startedWith([{ ...LIVEKIT_STREAM, kind: 4 }])))).toThrow(
+      CapturePreviewParseError,
+    );
+  });
+});
+
 describe("parseSnapshot", () => {
   it("accepts a minimal well-formed snapshot", () => {
     const parsed = parseSnapshot(validSnapshot());
diff --git a/examples/egocap/frontend/src/captureProtocol.ts b/examples/egocap/frontend/src/captureProtocol.ts
index df1b706c73..cc9633b54a 100644
--- a/examples/egocap/frontend/src/captureProtocol.ts
+++ b/examples/egocap/frontend/src/captureProtocol.ts
@@ -41,7 +41,7 @@ export type WireDTypeValue = (typeof WireDType)[keyof typeof WireDType];
 // capture_server/protocol.py -- not guessed widths or representations.
 // A descriptor advertising anything else is an unsupported-protocol error,
 // not something to silently ignore and keep showing "connected" for.
-export const StreamKind = { TRACKING: 1, IMAGE: 2 } as const;
+export const StreamKind = { TRACKING: 1, IMAGE: 2, LIVEKIT_IMAGE: 3 } as const;
 export const TrackingSchema = { IC_TRACKING_V1: 1 } as const;
 export const PoseRepresentation = { POSITION_QUATERNION: 1 } as const;
 export const QuaternionOrder = { XYZW: 1 } as const;
@@ -254,7 +254,20 @@ export interface CameraStreamDescriptor {
   fps: number;
 }
 
-export type StreamDescriptor = TrackingStreamDescriptor | CameraStreamDescriptor;
+/** A camera CaptureServer offers through a LiveKit room: where the video is, not frames it sends. */
+export interface LiveKitStreamDescriptor {
+  kind: "livekit_camera";
+  stream_id: number;
+  /** Operator-facing tile label. */
+  name: string;
+  url: string;
+  room: string;
+  /** Participant identity of the camera host; a track name is only unique within one participant. */
+  publisher: string;
+  track: string;
+}
+
+export type StreamDescriptor = TrackingStreamDescriptor | CameraStreamDescriptor | LiveKitStreamDescriptor;
 
 /** Validates every field's extent is within payload_size and that no two
  * fields overlap. This is the one authoritative check for a descriptor's
@@ -327,7 +340,18 @@ function parseStreamDescriptor(value: unknown, field: string): StreamDescriptor
       handJointOrder: HandJointOrder.OPENXR_26,
     };
   }
-  // kind === StreamKind.IMAGE (the only other value expectEnum(StreamKind, ...) allows)
+  if (kind === StreamKind.LIVEKIT_IMAGE) {
+    return {
+      kind: "livekit_camera",
+      stream_id: expectBoundedPositiveInt(value.stream_id, `${field}.stream_id`, 255),
+      name: expectString(value.name, `${field}.name`),
+      url: expectString(value.url, `${field}.url`),
+      room: expectString(value.room, `${field}.room`),
+      publisher: expectString(value.publisher, `${field}.publisher`),
+      track: expectString(value.track, `${field}.track`),
+    };
+  }
+  // kind === StreamKind.IMAGE (the only remaining value expectEnum(StreamKind, ...) allows)
   const streamId = expectBoundedPositiveInt(value.stream_id, `${field}.stream_id`, 3);
   return {
     kind: "camera",
@@ -339,38 +363,11 @@ function parseStreamDescriptor(value: unknown, field: string): StreamDescriptor
   };
 }
 
-/** One LiveKit video stream CaptureServer offers: where it is published, not frames CaptureServer sends. */
-export interface LiveKitStream {
-  stream_id: string;
-  /** Operator-facing tile label. */
-  name: string;
-  url: string;
-  room: string;
-  /** Participant identity of the camera host; a track name is only unique within one participant. */
-  publisher: string;
-  track: string;
-}
-
 export interface CaptureStarted {
   session_id: string;
   running: boolean;
   mode: CaptureModeValue;
   streams: StreamDescriptor[];
-  /** Empty when the server offers none, or predates the field. */
-  livekit_streams: LiveKitStream[];
-}
-
-/** Validates one `capture.started.livekit_streams` entry; only the fields a consumer needs to find the video. */
-function parseLiveKitStream(value: unknown, field: string): LiveKitStream {
-  if (!isObject(value)) throw new CapturePreviewParseError(`${field} must be an object`);
-  return {
-    stream_id: expectString(value.stream_id, `${field}.stream_id`),
-    name: expectString(value.name, `${field}.name`),
-    url: expectString(value.url, `${field}.url`),
-    room: expectString(value.room, `${field}.room`),
-    publisher: expectString(value.publisher, `${field}.publisher`),
-    track: expectString(value.track, `${field}.track`),
-  };
 }
 
 /** Validates the `capture.started` snapshot member. */
@@ -380,20 +377,19 @@ function parseCaptureStarted(value: unknown): CaptureStarted {
   if (!Array.isArray(streamsRaw)) {
     throw new CapturePreviewParseError("capture.started.streams must be an array");
   }
-  // A backend that predates the field omits it: nothing offered, not an error.
-  const livekitRaw = value.livekit_streams ?? [];
-  if (!Array.isArray(livekitRaw)) {
-    throw new CapturePreviewParseError("capture.started.livekit_streams must be an array");
-  }
   return {
     session_id: expectString(value.session_id, "capture.started.session_id"),
     running: expectBoolean(value.running, "capture.started.running"),
     mode: expectEnum(CaptureMode, value.mode, "capture.started.mode"),
     streams: streamsRaw.map((s, i) => parseStreamDescriptor(s, `capture.started.streams[${i}]`)),
-    livekit_streams: livekitRaw.map((s, i) => parseLiveKitStream(s, `capture.started.livekit_streams[${i}]`)),
   };
 }
 
+/** The LiveKit cameras a started session offers; empty before the session starts or when it offers none. */
+export function liveKitStreams(started: CaptureStarted | null | undefined): LiveKitStreamDescriptor[] {
+  return (started?.streams ?? []).filter((s): s is LiveKitStreamDescriptor => s.kind === "livekit_camera");
+}
+
 export interface CaptureStatusFacts {
   session_id: string;
   type: CaptureStatusTypeValue;
diff --git a/examples/egocap/frontend/src/livekitPreview.test.ts b/examples/egocap/frontend/src/livekitPreview.test.ts
index a00eefd19a..3992726945 100644
--- a/examples/egocap/frontend/src/livekitPreview.test.ts
+++ b/examples/egocap/frontend/src/livekitPreview.test.ts
@@ -3,20 +3,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { afterEach, describe, expect, it, vi } from "vitest";
-import {
-  fetchLiveKitPreview,
-  LiveKitPreviewHttpError,
-  LiveKitPreviewParseError,
-  parseLiveKitPreview,
-} from "./livekitPreview";
-
-const GOOD = {
-  url: "wss://lk",
-  room: "r",
-  publisher: "orin",
-  token: "tok",
-  tracks: [{ name: "Head left", track: "left" }],
-};
+import { fetchLiveKitToken, LiveKitTokenHttpError, LiveKitTokenParseError } from "./livekitPreview";
 
 afterEach(() => {
   vi.unstubAllGlobals();
@@ -35,53 +22,42 @@ function stubFetch(status: number, body: unknown, jsonThrows = false): ReturnTyp
   return fn;
 }
 
-describe("parseLiveKitPreview", () => {
-  it("accepts a complete body", () => {
-    expect(parseLiveKitPreview(GOOD)).toEqual(GOOD);
-  });
-
-  it.each([
-    ["null body", null],
-    ["string body", "x"],
-    ["missing url", { ...GOOD, url: undefined }],
-    ["empty room", { ...GOOD, room: "" }],
-    ["non-string publisher", { ...GOOD, publisher: 3 }],
-    ["missing token", { ...GOOD, token: undefined }],
-    ["tracks not an array", { ...GOOD, tracks: "x" }],
-    ["empty tracks", { ...GOOD, tracks: [] }],
-    ["non-object track", { ...GOOD, tracks: ["x"] }],
-    ["track missing name", { ...GOOD, tracks: [{ track: "a" }] }],
-    ["track with empty track id", { ...GOOD, tracks: [{ name: "a", track: "" }] }],
-  ])("rejects %s", (_label, body) => {
-    expect(() => parseLiveKitPreview(body)).toThrow(LiveKitPreviewParseError);
-  });
-});
-
-describe("fetchLiveKitPreview", () => {
-  it("returns the parsed config on 200 and requests the preview route", async () => {
-    const fn = stubFetch(200, GOOD);
-    expect(await fetchLiveKitPreview()).toEqual(GOOD);
-    expect(fn.mock.calls[0][0]).toBe("/api/livekit-preview");
+describe("fetchLiveKitToken", () => {
+  it("returns the token and requests the token route with the room URL-encoded", async () => {
+    const fn = stubFetch(200, { token: "tok" });
+    expect(await fetchLiveKitToken("room a/b")).toBe("tok");
+    expect(fn.mock.calls[0][0]).toBe("/api/livekit-token?room=room%20a%2Fb");
   });
 
-  it("returns null on 404 because the station has no LiveKit preview", async () => {
-    stubFetch(404, { detail: "LiveKit preview is not configured" });
-    expect(await fetchLiveKitPreview()).toBeNull();
+  it("passes the abort signal to fetch", async () => {
+    const fn = stubFetch(200, { token: "tok" });
+    const controller = new AbortController();
+    await fetchLiveKitToken("r", controller.signal);
+    expect((fn.mock.calls[0] as unknown[])[1]).toEqual({ signal: controller.signal });
   });
 
   it("throws an HTTP error carrying the backend detail on 503", async () => {
     stubFetch(503, { detail: "LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set for the backend" });
-    await expect(fetchLiveKitPreview()).rejects.toThrow(LiveKitPreviewHttpError);
-    await expect(fetchLiveKitPreview()).rejects.toThrow("LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set");
+    await expect(fetchLiveKitToken("r")).rejects.toThrow(LiveKitTokenHttpError);
+    await expect(fetchLiveKitToken("r")).rejects.toThrow("LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set");
+  });
+
+  it("treats 404 as an error too, since the room was offered", async () => {
+    stubFetch(404, { detail: "room is not offered by CaptureServer" });
+    await expect(fetchLiveKitToken("r")).rejects.toThrow("room is not offered");
   });
 
   it("falls back to the status code when an error body is not JSON", async () => {
     stubFetch(500, null, true);
-    await expect(fetchLiveKitPreview()).rejects.toThrow("HTTP 500");
+    await expect(fetchLiveKitToken("r")).rejects.toThrow("HTTP 500");
   });
 
-  it("throws a parse error when a 200 body is unusable", async () => {
-    stubFetch(200, { url: "wss://lk" });
-    await expect(fetchLiveKitPreview()).rejects.toThrow(LiveKitPreviewParseError);
+  it.each([
+    ["missing token", {}],
+    ["empty token", { token: "" }],
+    ["non-string token", { token: 3 }],
+  ])("throws a parse error for %s", async (_label, body) => {
+    stubFetch(200, body);
+    await expect(fetchLiveKitToken("r")).rejects.toThrow(LiveKitTokenParseError);
   });
 });
diff --git a/examples/egocap/frontend/src/livekitTestDoubles.ts b/examples/egocap/frontend/src/livekitTestDoubles.ts
index fcac66182b..aea6afbef5 100644
--- a/examples/egocap/frontend/src/livekitTestDoubles.ts
+++ b/examples/egocap/frontend/src/livekitTestDoubles.ts
@@ -4,6 +4,7 @@
 
 /** Fake livekit-client Room and tracks shared by the LiveKit hook and tile tests. */
 import { vi } from "vitest";
+import type { LiveKitStreamDescriptor } from "./captureProtocol";
 
 type Handler = (...args: any[]) => void;
 
@@ -58,13 +59,7 @@ export function publication(name: string): any {
   return { trackName: name };
 }
 
-export const CONFIG = {
-  url: "wss://lk",
-  room: "r",
-  publisher: "orin",
-  token: "tok",
-  tracks: [
-    { name: "Head left", track: "left" },
-    { name: "Head right", track: "right" },
-  ],
-};
+export const STREAMS: LiveKitStreamDescriptor[] = [
+  { kind: "livekit_camera", stream_id: 16, name: "Head left", url: "wss://lk", room: "r", publisher: "orin", track: "left" },
+  { kind: "livekit_camera", stream_id: 17, name: "Head right", url: "wss://lk", room: "r", publisher: "orin", track: "right" },
+];
diff --git a/examples/egocap/frontend/src/useLiveKitPreview.test.ts b/examples/egocap/frontend/src/useLiveKitPreview.test.ts
index 0b3d090648..7a4510de51 100644
--- a/examples/egocap/frontend/src/useLiveKitPreview.test.ts
+++ b/examples/egocap/frontend/src/useLiveKitPreview.test.ts
@@ -4,7 +4,7 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { act, cleanup, renderHook } from "@testing-library/react";
-import { CONFIG, FakeRoom, fakeTrack, participant, publication } from "./livekitTestDoubles";
+import { STREAMS, FakeRoom, fakeTrack, participant, publication } from "./livekitTestDoubles";
 
 vi.mock("livekit-client", async () => {
   const doubles = await import("./livekitTestDoubles");
@@ -32,8 +32,7 @@ function stubFetch(handler: () => Promise<unknown>): ReturnType<typeof vi.fn> {
   return fn;
 }
 
-const ok = (body: unknown) => async () => ({ status: 200, ok: true, json: async () => body });
-const notFound = async () => ({ status: 404, ok: false, json: async () => ({ detail: "nf" }) });
+const ok = (token = "tok") => async () => ({ status: 200, ok: true, json: async () => ({ token }) });
 
 async function flush(): Promise<void> {
   await act(async () => {
@@ -42,7 +41,7 @@ async function flush(): Promise<void> {
 }
 
 async function mounted() {
-  const view = renderHook(() => useLiveKitPreview());
+  const view = renderHook(() => useLiveKitPreview(STREAMS));
   await flush();
   return view;
 }
@@ -59,16 +58,65 @@ afterEach(() => {
 });
 
 describe("useLiveKitPreview", () => {
-  it("is unconfigured and creates no Room when the backend answers 404", async () => {
-    stubFetch(notFound);
-    const { result } = await mounted();
-    expect(result.current.phase).toBe("unconfigured");
+  it("is idle, fetches nothing and creates no Room when no streams are offered", async () => {
+    const fetchFn = stubFetch(ok());
+    const { result } = renderHook(() => useLiveKitPreview([]));
+    await flush();
+    expect(result.current.phase).toBe("idle");
     expect(result.current.tiles).toEqual([]);
+    expect(fetchFn).not.toHaveBeenCalled();
     expect(FakeRoom.instances).toHaveLength(0);
   });
 
+  it("requests a token for the offered room", async () => {
+    const fetchFn = stubFetch(ok());
+    await mounted();
+    expect(fetchFn.mock.calls[0][0]).toBe("/api/livekit-token?room=r");
+  });
+
+  it("does not reconnect when re-rendered with the same stream content in a new array", async () => {
+    const fetchFn = stubFetch(ok());
+    const { rerender } = renderHook(({ streams }) => useLiveKitPreview(streams), {
+      initialProps: { streams: STREAMS },
+    });
+    await flush();
+    rerender({ streams: STREAMS.map((s) => ({ ...s })) });
+    await flush();
+    expect(fetchFn).toHaveBeenCalledTimes(1);
+    expect(FakeRoom.instances).toHaveLength(1);
+    expect(FakeRoom.instances[0].disconnect).not.toHaveBeenCalled();
+  });
+
+  it("disconnects and reconnects when the stream content changes", async () => {
+    const fetchFn = stubFetch(ok());
+    const { result, rerender } = renderHook(({ streams }) => useLiveKitPreview(streams), {
+      initialProps: { streams: STREAMS },
+    });
+    await flush();
+    rerender({ streams: [{ ...STREAMS[0], url: "wss://other", room: "r2" }] });
+    await flush();
+    expect(FakeRoom.instances[0].disconnect).toHaveBeenCalledTimes(1);
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+    expect(fetchFn.mock.calls[1][0]).toBe("/api/livekit-token?room=r2");
+    expect(FakeRoom.instances[1].connect).toHaveBeenCalledWith("wss://other", "tok");
+    expect(result.current.tiles).toEqual([{ name: "Head left", track: null }]);
+  });
+
+  it("goes back to idle and disconnects when the offer disappears", async () => {
+    stubFetch(ok());
+    const { result, rerender } = renderHook(({ streams }) => useLiveKitPreview(streams), {
+      initialProps: { streams: STREAMS },
+    });
+    await flush();
+    rerender({ streams: [] });
+    await flush();
+    expect(FakeRoom.instances[0].disconnect).toHaveBeenCalledTimes(1);
+    expect(result.current.phase).toBe("idle");
+    expect(result.current.tiles).toEqual([]);
+  });
+
   it("connects with the fetched url and token and lists configured tiles empty", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     expect(FakeRoom.instances[0].connect).toHaveBeenCalledWith("wss://lk", "tok");
     expect(result.current.phase).toBe("connected");
@@ -79,7 +127,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("is connecting while the connect is still pending", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     let release!: () => void;
     FakeRoom.connectGate = new Promise<void>((r) => (release = r));
     const { result } = await mounted();
@@ -90,7 +138,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("adopts already-published video tracks of the publisher after connect", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const left = fakeTrack();
     FakeRoom.seed = [
       [
@@ -110,14 +158,14 @@ describe("useLiveKitPreview", () => {
   });
 
   it("does not adopt same-named tracks from another participant after connect", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     FakeRoom.seed = [["intruder", participant("intruder", [{ name: "left", track: fakeTrack() }])]];
     const { result } = await mounted();
     expect(result.current.tiles[0].track).toBeNull();
   });
 
   it("picks up tracks published while the SDK was reconnecting", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const room = FakeRoom.instances[0];
     const left = fakeTrack();
@@ -127,7 +175,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("shows a track on TrackSubscribed for the configured publisher and track name", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const track = fakeTrack();
     act(() => FakeRoom.instances[0].emit("TrackSubscribed", track, publication("right"), { identity: "orin" }));
@@ -136,14 +184,14 @@ describe("useLiveKitPreview", () => {
   });
 
   it("ignores a correctly named track from a different participant", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     act(() => FakeRoom.instances[0].emit("TrackSubscribed", fakeTrack(), publication("left"), { identity: "intruder" }));
     expect(result.current.tiles[0].track).toBeNull();
   });
 
   it("ignores a subscribed audio track with a configured name", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const audio = { ...fakeTrack(), kind: "audio" };
     act(() => FakeRoom.instances[0].emit("TrackSubscribed", audio, publication("left"), { identity: "orin" }));
@@ -151,7 +199,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("clears a tile on TrackUnsubscribed", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const track = fakeTrack();
     act(() => FakeRoom.instances[0].emit("TrackSubscribed", track, publication("left"), { identity: "orin" }));
@@ -160,7 +208,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("keeps a republished track when the old one is unsubscribed afterwards", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const oldTrack = fakeTrack();
     const newTrack = fakeTrack();
@@ -172,7 +220,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("clears every tile when the publisher disconnects but not for another participant", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const room = FakeRoom.instances[0];
     act(() => room.emit("TrackSubscribed", fakeTrack(), publication("left"), { identity: "orin" }));
@@ -185,7 +233,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("reports reconnecting then connected, keeping tracks across the SDK reconnect", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     const { result } = await mounted();
     const room = FakeRoom.instances[0];
     const track = fakeTrack();
@@ -199,7 +247,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("registers each listener once per Room", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     await mounted();
     const room = FakeRoom.instances[0];
     for (const event of ["TrackSubscribed", "TrackUnsubscribed", "ParticipantDisconnected", "Reconnecting", "Reconnected", "Disconnected"]) {
@@ -209,7 +257,7 @@ describe("useLiveKitPreview", () => {
 
   it("on full Disconnected shows an error, then refetches a fresh token and builds a new Room after the delay", async () => {
     let n = 0;
-    const fetchFn = stubFetch(async () => ({ status: 200, ok: true, json: async () => ({ ...CONFIG, token: `tok${++n}` }) }));
+    const fetchFn = stubFetch(async () => ({ status: 200, ok: true, json: async () => ({ token: `tok${++n}` }) }));
     const { result } = await mounted();
     act(() => FakeRoom.instances[0].emit("Disconnected"));
     expect(result.current.phase).toBe("error");
@@ -230,7 +278,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("retries after a failed connect with the SDK's message", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     FakeRoom.connectError = new Error("ws refused");
     const { result } = await mounted();
     expect(result.current.phase).toBe("error");
@@ -256,7 +304,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("reports a parse error for an unusable body", async () => {
-    stubFetch(ok({ url: "wss://lk" }));
+    stubFetch(async () => ({ status: 200, ok: true, json: async () => ({}) }));
     const { result } = await mounted();
     expect(result.current.phase).toBe("error");
     expect(result.current.message).toContain("must be");
@@ -266,12 +314,15 @@ describe("useLiveKitPreview", () => {
     let fail = true;
     const fetchFn = stubFetch(async () => {
       if (fail) throw new TypeError("fetch failed");
-      return { status: 200, ok: true, json: async () => CONFIG };
+      return { status: 200, ok: true, json: async () => ({ token: "tok" }) };
     });
     const { result } = await mounted();
     expect(result.current.phase).toBe("error");
     expect(result.current.message).toBe("Cannot reach the backend");
-    expect(result.current.tiles).toEqual([]);
+    expect(result.current.tiles).toEqual([
+      { name: "Head left", track: null },
+      { name: "Head right", track: null },
+    ]);
     fail = false;
     await act(async () => {
       await vi.advanceTimersByTimeAsync(RETRY_MS);
@@ -281,7 +332,7 @@ describe("useLiveKitPreview", () => {
   });
 
   it("disconnects on unmount and does not retry afterwards", async () => {
-    const fetchFn = stubFetch(ok(CONFIG));
+    const fetchFn = stubFetch(ok());
     const { unmount } = await mounted();
     const room = FakeRoom.instances[0];
     unmount();
@@ -307,7 +358,7 @@ describe("useLiveKitPreview", () => {
     expect(fetchFn).toHaveBeenCalledTimes(1);
   });
 
-  it("aborts the in-flight config fetch on unmount and creates no Room", async () => {
+  it("aborts the in-flight token fetch on unmount and creates no Room", async () => {
     let signal: AbortSignal | undefined;
     let resolve!: (v: unknown) => void;
     vi.stubGlobal(
@@ -317,16 +368,16 @@ describe("useLiveKitPreview", () => {
         return new Promise((r) => (resolve = r));
       }),
     );
-    const { unmount } = renderHook(() => useLiveKitPreview());
+    const { unmount } = renderHook(() => useLiveKitPreview(STREAMS));
     unmount();
     expect(signal?.aborted).toBe(true);
-    resolve({ status: 200, ok: true, json: async () => CONFIG });
+    resolve({ status: 200, ok: true, json: async () => ({ token: "tok" }) });
     await flush();
     expect(FakeRoom.instances).toHaveLength(0);
   });
 
   it("disconnects a Room whose connect finishes after unmount", async () => {
-    stubFetch(ok(CONFIG));
+    stubFetch(ok());
     let release!: () => void;
     FakeRoom.connectGate = new Promise<void>((r) => (release = r));
     const { unmount } = await mounted();
diff --git a/examples/egocap/frontend/src/useLiveKitPreview.ts b/examples/egocap/frontend/src/useLiveKitPreview.ts
index 555e9d3177..f9974c531d 100644
--- a/examples/egocap/frontend/src/useLiveKitPreview.ts
+++ b/examples/egocap/frontend/src/useLiveKitPreview.ts
@@ -13,7 +13,7 @@
 import { useEffect, useState } from "react";
 import { Room, RoomEvent, Track } from "livekit-client";
 import type { RemoteParticipant, RemoteTrack } from "livekit-client";
-import type { LiveKitStream } from "./captureProtocol";
+import type { LiveKitStreamDescriptor } from "./captureProtocol";
 import { fetchLiveKitToken } from "./livekitPreview";
 
 /** Delay before a new attempt after a failed connect or a full disconnect. */
@@ -38,7 +38,7 @@ export interface LiveKitPreviewState {
 const IDLE: LiveKitPreviewState = { phase: "idle", message: null, tiles: [] };
 
 /** The offered streams with the given subscribed tracks filled in by track name. */
-function tilesFor(streams: LiveKitStream[], tracks: Map<string, RemoteTrack>): LiveKitTile[] {
+function tilesFor(streams: LiveKitStreamDescriptor[], tracks: Map<string, RemoteTrack>): LiveKitTile[] {
   return streams.map((s) => ({ name: s.name, track: tracks.get(s.track) ?? null }));
 }
 
@@ -46,13 +46,13 @@ function tilesFor(streams: LiveKitStream[], tracks: Map<string, RemoteTrack>): L
  * Receives the offered LiveKit streams for the lifetime of the calling component. All streams of one session
  * share a room and publisher, so the first stream names the connection.
  */
-export function useLiveKitPreview(streams: LiveKitStream[]): LiveKitPreviewState {
+export function useLiveKitPreview(streams: LiveKitStreamDescriptor[]): LiveKitPreviewState {
   const [state, setState] = useState<LiveKitPreviewState>(IDLE);
   // A new session offering the same streams must not reconnect, so the effect depends on content, not identity.
   const key = JSON.stringify(streams);
 
   useEffect(() => {
-    const offered: LiveKitStream[] = JSON.parse(key);
+    const offered: LiveKitStreamDescriptor[] = JSON.parse(key);
     if (offered.length === 0) {
       setState(IDLE);
       return;
diff --git a/examples/egocap/tests/backend/test_livekit_preview.py b/examples/egocap/tests/backend/test_livekit_preview.py
index 4f14fb8fdd..6de71d2292 100644
--- a/examples/egocap/tests/backend/test_livekit_preview.py
+++ b/examples/egocap/tests/backend/test_livekit_preview.py
@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""The LiveKit viewer token (decoded independently of the signer) and GET /api/livekit-preview."""
+"""The LiveKit viewer token (decoded independently of the signer) and GET /api/livekit-token."""
 
 from __future__ import annotations
 
@@ -10,16 +10,17 @@
 import hashlib
 import hmac
 import json
+from dataclasses import replace
+from types import SimpleNamespace
 
 import pytest
 from fastapi.testclient import TestClient
 
+from capture_server import protocol as p
 from egocap_web.app import app
 from egocap_web.livekit_preview import (
     API_KEY_ENV,
     API_SECRET_ENV,
-    LiveKitPreview,
-    LiveKitTrack,
     subscriber_token,
 )
 
@@ -93,42 +94,78 @@ def test_token_never_contains_the_secret():
     assert SECRET.encode() not in b"".join(_unb64(s) for s in token.split(".")[:2])
 
 
+def _offer(room: str = "sensing-preview") -> p.LiveKitCameraStream:
+    return p.LiveKitCameraStream(
+        stream_id=16,
+        name="Head left",
+        url="wss://lk.example:7881",
+        room=room,
+        publisher="orin-sensing",
+        track="sensing-left",
+    )
+
+
 @pytest.fixture
 def client_factory():
-    """A TestClient over the real app with app.state.livekit_preview set directly (no lifespan needed)."""
-    previous = getattr(app.state, "livekit_preview", None)
+    """A TestClient over the real app whose monitor reports a session offering the given streams."""
+    previous = getattr(app.state, "monitor", None)
 
-    def make(preview: LiveKitPreview | None) -> TestClient:
-        app.state.livekit_preview = preview
+    def make(streams: tuple | None) -> TestClient:
+        started = None if streams is None else SimpleNamespace(streams=streams)
+        app.state.monitor = SimpleNamespace(native=SimpleNamespace(started=started))
         return TestClient(app)
 
     yield make
-    app.state.livekit_preview = previous
-
-
-PREVIEW = LiveKitPreview(
-    url="wss://lk.example:7881",
-    room="sensing-preview",
-    publisher="orin-sensing",
-    tracks=(LiveKitTrack("Head left", "sensing-left"), LiveKitTrack("Head right", "sensing-right")),
-)
+    app.state.monitor = previous
 
 
-def test_unconfigured_station_gets_404_with_no_store(client_factory, monkeypatch):
+@pytest.fixture
+def credentials(monkeypatch):
     monkeypatch.setenv(API_KEY_ENV, KEY)
     monkeypatch.setenv(API_SECRET_ENV, SECRET)
-    response = client_factory(None).get("/api/livekit-preview")
+
+
+URL = "/api/livekit-token?room=sensing-preview"
+
+
+def test_no_session_yet_gets_404(client_factory, credentials):
+    response = client_factory(None).get(URL)
     assert response.status_code == 404
     assert response.headers["cache-control"] == "no-store"
 
 
+def test_session_offering_nothing_gets_404(client_factory, credentials):
+    assert client_factory(()).get(URL).status_code == 404
+
+
+def test_session_with_only_non_livekit_streams_gets_404(client_factory, credentials):
+    tracking = p.tracking_stream_descriptor((p.SourceType.HEAD,), 60)
+    assert client_factory((tracking,)).get(URL).status_code == 404
+
+
+def test_room_not_offered_gets_404_even_with_credentials(client_factory, credentials):
+    response = client_factory((_offer("other-room"),)).get(URL)
+    assert response.status_code == 404
+    assert response.headers["cache-control"] == "no-store"
+
+
+def test_missing_or_empty_room_query_gets_404(client_factory, credentials):
+    client = client_factory((_offer(),))
+    assert client.get("/api/livekit-token").status_code == 404
+    assert client.get("/api/livekit-token?room=").status_code == 404
+
+
+def test_old_route_is_gone(client_factory, credentials):
+    assert client_factory((_offer(),)).get("/api/livekit-preview").status_code == 404
+
+
 @pytest.mark.parametrize("missing", [(API_KEY_ENV,), (API_SECRET_ENV,), (API_KEY_ENV, API_SECRET_ENV)])
 def test_missing_credentials_give_503_naming_variables_but_no_values(client_factory, monkeypatch, missing):
     monkeypatch.setenv(API_KEY_ENV, KEY)
     monkeypatch.setenv(API_SECRET_ENV, SECRET)
     for name in missing:
         monkeypatch.delenv(name)
-    response = client_factory(PREVIEW).get("/api/livekit-preview")
+    response = client_factory((_offer(),)).get(URL)
     assert response.status_code == 503
     assert response.headers["cache-control"] == "no-store"
     detail = response.json()["detail"]
@@ -140,41 +177,34 @@ def test_missing_credentials_give_503_naming_variables_but_no_values(client_fact
 def test_empty_credentials_count_as_unset(client_factory, monkeypatch):
     monkeypatch.setenv(API_KEY_ENV, "")
     monkeypatch.setenv(API_SECRET_ENV, SECRET)
-    assert client_factory(PREVIEW).get("/api/livekit-preview").status_code == 503
+    assert client_factory((_offer(),)).get(URL).status_code == 503
 
 
-def test_configured_station_gets_config_and_verifiable_token(client_factory, monkeypatch):
-    monkeypatch.setenv(API_KEY_ENV, KEY)
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
-    response = client_factory(PREVIEW).get("/api/livekit-preview")
+def test_offered_room_gets_a_verifiable_subscribe_only_token(client_factory, credentials):
+    response = client_factory((_offer(),)).get(URL)
     assert response.status_code == 200
     assert response.headers["cache-control"] == "no-store"
     body = response.json()
-    assert set(body) == {"url", "room", "publisher", "token", "tracks"}
-    assert body["url"] == "wss://lk.example:7881"
-    assert body["room"] == "sensing-preview"
-    assert body["publisher"] == "orin-sensing"
-    assert body["tracks"] == [
-        {"name": "Head left", "track": "sensing-left"},
-        {"name": "Head right", "track": "sensing-right"},
-    ]
+    assert set(body) == {"token"}
     _, claims, signature, signing_input = _decode(body["token"])
     assert claims["video"]["room"] == "sensing-preview"
+    assert claims["video"]["canPublish"] is False
     assert claims["iss"] == KEY
     assert hmac.compare_digest(signature, _hs256(SECRET, signing_input))
 
 
-def test_secret_is_never_in_the_response_body_or_headers(client_factory, monkeypatch):
-    monkeypatch.setenv(API_KEY_ENV, KEY)
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
-    response = client_factory(PREVIEW).get("/api/livekit-preview")
+def test_room_is_matched_among_several_offered_streams(client_factory, credentials):
+    offers = (_offer("room-a"), replace(_offer("sensing-preview"), stream_id=17, name="b", track="u"))
+    assert client_factory(offers).get(URL).status_code == 200
+
+
+def test_secret_is_never_in_the_response_body_or_headers(client_factory, credentials):
+    response = client_factory((_offer(),)).get(URL)
     assert SECRET not in response.text
     assert SECRET not in str(dict(response.headers))
 
 
-def test_each_request_gets_a_fresh_viewer_identity(client_factory, monkeypatch):
-    monkeypatch.setenv(API_KEY_ENV, KEY)
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
-    client = client_factory(PREVIEW)
-    subs = {_decode(client.get("/api/livekit-preview").json()["token"])[1]["sub"] for _ in range(5)}
+def test_each_request_gets_a_fresh_viewer_identity(client_factory, credentials):
+    client = client_factory((_offer(),))
+    subs = {_decode(client.get(URL).json()["token"])[1]["sub"] for _ in range(5)}
     assert len(subs) == 5
diff --git a/examples/egocap/tests/backend/test_preview_protocol_livekit.py b/examples/egocap/tests/backend/test_preview_protocol_livekit.py
new file mode 100644
index 0000000000..8cb897452e
--- /dev/null
+++ b/examples/egocap/tests/backend/test_preview_protocol_livekit.py
@@ -0,0 +1,40 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The snapshot's capture.started member lists offered LiveKit cameras inside ``streams`` (kind 3)."""
+
+from __future__ import annotations
+
+from capture_server import protocol as p
+from capture_server.client import CaptureStarted, _to_client_started
+from egocap_web.preview_protocol import _capture_started_to_json
+
+_STREAM = p.LiveKitCameraStream(
+    stream_id=16,
+    name="Head left",
+    url="wss://lk.example:7881",
+    room="sensing-preview",
+    publisher="orin",
+    track="sensing-left",
+    width=2560,
+    height=1984,
+    fps=30.0,
+)
+
+
+def _started(streams: list[p.LiveKitCameraStream]) -> CaptureStarted:
+    begin = p.BeginRequest(tracking=p.TrackingConfig(sources=(p.SourceType.HEAD,)))
+    init = p.session_init_event(session_id="s1", mode=p.CaptureMode.MOCK, begin=begin, streams=streams)
+    return _to_client_started(init)
+
+
+def test_capture_started_json_lists_livekit_cameras_in_streams():
+    wire = _capture_started_to_json(_started([_STREAM]))
+    assert wire["streams"] == [_STREAM.to_json()]
+    assert wire["streams"][0]["kind"] == 3
+
+
+def test_capture_started_json_has_no_separate_livekit_list():
+    assert "livekit_streams" not in _capture_started_to_json(_started([_STREAM]))
+    assert "livekit_streams" not in _capture_started_to_json(_started([]))
diff --git a/examples/egocap/tests/backend/test_station_config_livekit.py b/examples/egocap/tests/backend/test_station_config_livekit.py
deleted file mode 100644
index 83f79a20e8..0000000000
--- a/examples/egocap/tests/backend/test_station_config_livekit.py
+++ /dev/null
@@ -1,145 +0,0 @@
-# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-#
-# SPDX-License-Identifier: Apache-2.0
-
-"""The optional ``livekit_preview`` section of the station YAML."""
-
-from pathlib import Path
-
-import pytest
-
-from egocap_web.livekit_preview import LiveKitPreview, LiveKitTrack
-from egocap_web.station_config import StationConfigError, load_station_config
-
-VALID = """
-meta: {}
-livekit_preview:
-  url: wss://lk.example:7881
-  room: sensing-preview
-  publisher: orin-sensing
-  tracks:
-    - name: Head left
-      track: sensing-left
-    - name: Head right
-      track: sensing-right
-"""
-
-
-def _load(tmp_path: Path, text: str):
-    path = tmp_path / "station.yaml"
-    path.write_text(text, encoding="utf-8")
-    return load_station_config(path)
-
-
-def _with_section(section: str) -> str:
-    return "meta: {}\nlivekit_preview:\n" + section
-
-
-def test_valid_section_parses_into_a_preview_with_ordered_tracks(tmp_path):
-    assert _load(tmp_path, VALID).livekit_preview == LiveKitPreview(
-        url="wss://lk.example:7881",
-        room="sensing-preview",
-        publisher="orin-sensing",
-        tracks=(LiveKitTrack("Head left", "sensing-left"), LiveKitTrack("Head right", "sensing-right")),
-    )
-
-
-def test_plain_ws_url_is_accepted(tmp_path):
-    text = VALID.replace("wss://", "ws://")
-    assert _load(tmp_path, text).livekit_preview.url == "ws://lk.example:7881"
-
-
-def test_absent_section_means_no_preview_and_otherwise_unchanged_station(tmp_path):
-    resolved = _load(tmp_path, "meta:\n  egocap_station_name: S\n")
-    assert resolved.livekit_preview is None
-    assert resolved.station_id == "S"
-    assert resolved.cameras == ()
-
-
-def test_livekit_preview_is_not_a_capture_server_camera(tmp_path):
-    assert _load(tmp_path, VALID).cameras == ()
-
-
-def test_four_tracks_are_allowed(tmp_path):
-    tracks = "".join(f"    - name: N{i}\n      track: t{i}\n" for i in range(4))
-    section = f"  url: ws://h\n  room: r\n  publisher: p\n  tracks:\n{tracks}"
-    assert len(_load(tmp_path, _with_section(section)).livekit_preview.tracks) == 4
-
-
-def _section(url="ws://h", room="r", publisher="p", tracks="    - {name: A, track: a}\n") -> str:
-    lines = []
-    for key, value in (("url", url), ("room", room), ("publisher", publisher)):
-        if value is not None:
-            lines.append(f"  {key}: {value!r}\n" if value == "" else f"  {key}: {value}\n")
-    if tracks is not None:
-        lines.append("  tracks:\n" + tracks)
-    return _with_section("".join(lines))
-
-
-@pytest.mark.parametrize(
-    ("text", "message"),
-    [
-        pytest.param("meta: {}\nlivekit_preview: nope\n", "must be a mapping", id="scalar-section"),
-        pytest.param("meta: {}\nlivekit_preview: [a]\n", "must be a mapping", id="list-section"),
-        pytest.param(_section(url=None), r"url must be a nonempty string", id="missing-url"),
-        pytest.param(_section(url=""), r"url must be a nonempty string", id="empty-url"),
-        pytest.param(_section(url="http://h"), "ws:// or wss://", id="http-url"),
-        pytest.param(_section(url="localhost:7880"), "ws:// or wss://", id="schemeless-url"),
-        pytest.param(_section(room=None), r"room must be a nonempty string", id="missing-room"),
-        pytest.param(_section(room=""), r"room must be a nonempty string", id="empty-room"),
-        pytest.param(_section(publisher=None), r"publisher must be a nonempty string", id="missing-publisher"),
-        pytest.param(_section(publisher=""), r"publisher must be a nonempty string", id="empty-publisher"),
-        pytest.param(_section(tracks=None), r"tracks must be a nonempty list", id="missing-tracks"),
-        pytest.param(_section(tracks="    []\n"), r"tracks must be a nonempty list", id="empty-tracks"),
-        pytest.param(
-            _with_section("  url: ws://h\n  room: r\n  publisher: p\n  tracks: x\n"),
-            r"tracks must be a nonempty list",
-            id="non-list-tracks",
-        ),
-        pytest.param(
-            _section(tracks="".join(f"    - {{name: N{i}, track: t{i}}}\n" for i in range(5))),
-            "at most 4",
-            id="too-many-tracks",
-        ),
-        pytest.param(
-            _section(tracks="    - just-a-string\n"), r"tracks\[0\] must be a mapping", id="non-mapping-track"
-        ),
-        pytest.param(
-            _section(tracks="    - {track: a}\n"),
-            r"tracks\[0\]\.name must be a nonempty string",
-            id="missing-name",
-        ),
-        pytest.param(
-            _section(tracks="    - {name: '', track: a}\n"), r"tracks\[0\]\.name must be", id="empty-name"
-        ),
-        pytest.param(
-            _section(tracks="    - {name: A}\n"),
-            r"tracks\[0\]\.track must be a nonempty string",
-            id="missing-track",
-        ),
-        pytest.param(
-            _section(tracks="    - {name: A, track: ''}\n"), r"tracks\[0\]\.track must be", id="empty-track"
-        ),
-        pytest.param(
-            _section(tracks="    - {name: A, track: 5}\n"), r"tracks\[0\]\.track must be", id="non-string-track"
-        ),
-        pytest.param(
-            _section(tracks="    - {name: A, track: a}\n    - {name: B, track: a}\n"),
-            "duplicate track",
-            id="duplicate-track",
-        ),
-        pytest.param(
-            _section(tracks="    - {name: A, track: a}\n    - {name: A, track: b}\n"),
-            "duplicate name",
-            id="duplicate-name",
-        ),
-    ],
-)
-def test_invalid_section_is_a_station_config_error(tmp_path, text, message):
-    with pytest.raises(StationConfigError, match=message):
-        _load(tmp_path, text)
-
-
-def test_error_names_the_station(tmp_path):
-    with pytest.raises(StationConfigError, match="livekit_preview"):
-        _load(tmp_path, "meta: {}\nlivekit_preview: 3\n")
diff --git a/examples/egocap/tests/capture_server/test_livekit_streams.py b/examples/egocap/tests/capture_server/test_livekit_streams.py
new file mode 100644
index 0000000000..28ed599f22
--- /dev/null
+++ b/examples/egocap/tests/capture_server/test_livekit_streams.py
@@ -0,0 +1,452 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""LiveKit stream offers: wire protocol, YAML loader, server SessionInit, client, and the CLI flag."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import select
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+import websockets
+
+from capture_server import protocol as p
+from capture_server.__main__ import main
+from capture_server.client import CaptureClient, _StreamRegistry
+from capture_server.livekit_streams import load_livekit_streams
+from capture_server.server import ServerConfig
+from tests.support.capture_server import poll_until, start_capture_server, stop_capture_server
+
+
+def _stream_json(**overrides) -> dict:
+    base = {
+        "stream_id": 16,
+        "kind": int(p.StreamKind.LIVEKIT_IMAGE),
+        "name": "Head left",
+        "url": "wss://lk.example:7881",
+        "room": "sensing-preview",
+        "publisher": "orin",
+        "track": "sensing-left",
+        "timestamp_basis": 1,
+        "width": 2560,
+        "height": 1984,
+        "fps": 30,
+    }
+    return {**base, **overrides}
+
+
+def _stream(**overrides) -> p.LiveKitCameraStream:
+    return p.LiveKitCameraStream.from_json(_stream_json(**overrides))
+
+
+def _two_streams() -> tuple[p.LiveKitCameraStream, ...]:
+    return (
+        _stream(),
+        _stream(stream_id=17, name="Head right", track="sensing-right", width=None, height=None, fps=None),
+    )
+
+
+def _begin() -> p.BeginRequest:
+    return p.BeginRequest(tracking=p.TrackingConfig(sources=(p.SourceType.HEAD,)))
+
+
+def _init(streams) -> p.SessionInit:
+    return p.session_init_event(session_id="s1", mode=p.CaptureMode.MOCK, begin=_begin(), streams=list(streams))
+
+
+# ---------------------------------------------------------------------------
+# Protocol.
+# ---------------------------------------------------------------------------
+
+
+def test_livekit_camera_stream_round_trips_through_json():
+    stream = _stream()
+    assert p.LiveKitCameraStream.from_json(stream.to_json()) == stream
+    assert stream.kind == p.StreamKind.LIVEKIT_IMAGE
+    assert stream.to_json()["kind"] == 3
+    assert stream.timestamp_basis == p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
+    assert stream.fps == 30.0
+
+
+def test_livekit_camera_stream_unknown_dimensions_are_null():
+    stream = _stream(width=None, height=None, fps=None)
+    assert (stream.width, stream.height, stream.fps) == (None, None, None)
+    assert stream.to_json()["fps"] is None
+
+
+def test_session_init_carries_livekit_streams_in_streams_and_round_trips():
+    streams = _two_streams()
+    wire = _init(streams).to_json()
+    assert "livekit_streams" not in wire
+    assert [s["kind"] for s in wire["streams"]] == [3, 3]
+    assert p.SessionInit.from_json(wire).streams == streams
+
+
+def test_session_init_mixes_livekit_with_tracking_and_jpeg_streams():
+    tracking = p.tracking_stream_descriptor((p.SourceType.HEAD,), 60)
+    init = _init([tracking, *_two_streams()])
+    assert p.SessionInit.from_json(init.to_json()) == init
+
+
+def test_session_init_without_livekit_streams_is_unchanged_on_the_wire():
+    wire = _init([]).to_json()
+    assert set(wire) == {"type", "version", "session_id", "mode", "effective_config", "clock", "streams"}
+    assert wire["streams"] == []
+
+
+def test_session_init_still_rejects_unknown_keys():
+    with pytest.raises(p.ProtocolError):
+        p.SessionInit.from_json({**_init([]).to_json(), "surprise": 1})
+
+
+@pytest.mark.parametrize(
+    "mutation",
+    [
+        {"surprise": 1},
+        {"kind": 2},
+        {"stream_id": 15},
+        {"stream_id": 24},
+        {"stream_id": "16"},
+        {"stream_id": True},
+        {"name": ""},
+        {"name": None},
+        {"room": ""},
+        {"publisher": 7},
+        {"track": ""},
+        {"url": "https://lk.example"},
+        {"url": "lk.example:7881"},
+        {"url": "x" * 600},
+        {"timestamp_basis": 2},
+        {"timestamp_basis": "1"},
+        {"timestamp_basis": True},
+        {"width": 0},
+        {"width": -1},
+        {"width": 1.5},
+        {"width": "100"},
+        {"height": True},
+        {"fps": 0},
+        {"fps": -5},
+        {"fps": "30"},
+        {"fps": True},
+        {"fps": float("nan")},
+        {"fps": float("inf")},
+        {"fps": float("-inf")},
+    ],
+)
+def test_livekit_camera_stream_rejects_bad_fields(mutation):
+    with pytest.raises(p.ProtocolError):
+        p.LiveKitCameraStream.from_json(_stream_json(**mutation))
+
+
+@pytest.mark.parametrize(
+    "missing", ["stream_id", "kind", "name", "url", "room", "publisher", "track", "timestamp_basis"]
+)
+def test_livekit_camera_stream_rejects_a_missing_required_key(missing):
+    data = _stream_json()
+    del data[missing]
+    with pytest.raises(p.ProtocolError):
+        p.LiveKitCameraStream.from_json(data)
+
+
+@pytest.mark.parametrize("fps", [float("nan"), float("inf"), float("-inf")])
+def test_livekit_fps_rejection_says_finite_positive(fps):
+    with pytest.raises(p.ProtocolError, match="finite positive number or null"):
+        p.LiveKitCameraStream.from_json(_stream_json(fps=fps))
+
+
+def test_livekit_camera_stream_treats_missing_optional_dimensions_as_unknown():
+    data = _stream_json()
+    for key in ("width", "height", "fps"):
+        del data[key]
+    stream = p.LiveKitCameraStream.from_json(data)
+    assert (stream.width, stream.height, stream.fps) == (None, None, None)
+
+
+def test_livekit_camera_stream_accepts_ws_and_wss():
+    assert _stream(url="ws://10.0.0.5:7880").url == "ws://10.0.0.5:7880"
+    assert _stream(url="wss://lk").url == "wss://lk"
+
+
+def _wire_with(entries: list[dict]) -> dict:
+    return {**_init([]).to_json(), "streams": entries}
+
+
+def test_session_init_livekit_limit_is_eight():
+    def many(n):
+        return [_stream_json(stream_id=16 + i, name=f"n{i}", track=f"t{i}") for i in range(n)]
+
+    assert len(p.SessionInit.from_json(_wire_with(many(8))).streams) == 8
+    with pytest.raises(p.ProtocolError):
+        p.SessionInit.from_json(_wire_with(many(9)))
+
+
+def test_check_livekit_streams_limit_is_eight():
+    streams = [_stream(stream_id=16 + i % 8, name=f"n{i}", track=f"t{i}") for i in range(9)]
+    with pytest.raises(p.ProtocolError, match="at most 8"):
+        p.check_livekit_streams(streams)
+
+
+@pytest.mark.parametrize(
+    ("second", "match"),
+    [
+        ({"stream_id": 16, "name": "other", "track": "other"}, "duplicate stream_id"),
+        ({"name": "Head left", "track": "other"}, "names must be unique"),
+        ({"name": "other", "track": "sensing-left"}, "same publisher and track"),
+    ],
+)
+def test_session_init_rejects_duplicate_livekit_entries(second, match):
+    first = _stream_json()
+    other = _stream_json(stream_id=17, name="b", track="u")
+    with pytest.raises(p.ProtocolError, match=match):
+        p.SessionInit.from_json(_wire_with([first, {**other, **second}]))
+
+
+def test_livekit_name_may_not_collide_with_a_jpeg_camera_name():
+    camera = p.camera_stream_descriptor(
+        p.CameraStreamConfig(
+            stream_id=1,
+            name="Head left",
+            type=p.CameraType.OAK_D_COLOR,
+            required=True,
+            width=4,
+            height=3,
+            fps=30.0,
+            jpeg_quality=90,
+        )
+    )
+    with pytest.raises(p.ProtocolError, match="names must be unique"):
+        p.check_livekit_streams([camera, _stream()])
+
+
+def test_same_track_name_from_different_publishers_is_allowed():
+    p.check_livekit_streams([_stream(), _stream(stream_id=17, name="b", publisher="other-host")])
+
+
+# ---------------------------------------------------------------------------
+# YAML loader.
+# ---------------------------------------------------------------------------
+
+_GOOD_YAML = """
+livekit:
+  url: wss://lk.example:7881
+  room: sensing-preview
+  publisher: orin
+  streams:
+    - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+    - {name: Head right, track: sensing-right}
+"""
+
+
+def _write(tmp_path: Path, text: str) -> Path:
+    path = tmp_path / "livekit.yaml"
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def test_loader_reads_a_valid_file(tmp_path):
+    streams = load_livekit_streams(_write(tmp_path, _GOOD_YAML))
+    assert [s.stream_id for s in streams] == [16, 17]
+    assert [s.name for s in streams] == ["Head left", "Head right"]
+    assert streams[0].url == "wss://lk.example:7881"
+    assert streams[0].room == "sensing-preview"
+    assert streams[0].publisher == "orin"
+    assert (streams[0].width, streams[0].height, streams[0].fps) == (2560, 1984, 30.0)
+    assert streams[1].width is None
+    assert streams[1].timestamp_basis == p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
+
+
+def test_loader_accepts_an_empty_streams_list(tmp_path):
+    text = "livekit: {url: wss://lk, room: r, publisher: o, streams: []}\n"
+    assert load_livekit_streams(_write(tmp_path, text)) == ()
+
+
+@pytest.mark.parametrize(
+    "text",
+    [
+        "",
+        "- a\n- b\n",
+        "other: 1\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [], extra: 1}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: x}\n",
+        "livekit: {room: r, publisher: o, streams: [{name: A, track: t}]}\n",
+        "livekit: {url: wss://lk, publisher: o, streams: [{name: A, track: t}]}\n",
+        "livekit: {url: wss://lk, room: r, streams: [{name: A, track: t}]}\n",
+        "livekit: {url: http://lk, room: r, publisher: o, streams: [{name: A, track: t}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{id: a, name: A, track: t}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t, bogus: 1}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [x]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t, fps: .nan}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t, fps: .inf}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t, fps: -.inf}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t, fps: 0}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t}, {name: A, track: u}]}\n",
+        "livekit: {url: wss://lk, room: r, publisher: o, streams: [{name: A, track: t}, {name: B, track: t}]}\n",
+        "livekit: [unterminated\n",
+    ],
+)
+def test_loader_rejects_unusable_files_with_value_error(tmp_path, text):
+    with pytest.raises(ValueError):
+        load_livekit_streams(_write(tmp_path, text))
+
+
+def test_loader_reports_an_unreadable_file_as_value_error(tmp_path):
+    with pytest.raises(ValueError, match="cannot read"):
+        load_livekit_streams(tmp_path / "missing.yaml")
+
+
+# ---------------------------------------------------------------------------
+# Server SessionInit and client.
+# ---------------------------------------------------------------------------
+
+
+async def _begin_and_read_init(url: str) -> p.SessionInit:
+    begin = _begin()
+    async with websockets.connect(url) as ws:
+        await ws.send(
+            json.dumps(
+                {
+                    "type": int(p.MessageType.BEGIN),
+                    "version": p.PROTOCOL_VERSION,
+                    "session_id": "livekit-session",
+                    **p.effective_config(begin).to_json(),
+                }
+            )
+        )
+        while True:
+            message = p.parse_server_message(json.loads(await asyncio.wait_for(ws.recv(), timeout=5)))
+            if isinstance(message, p.SessionInit):
+                return message
+
+
+def _livekit_in(init) -> tuple[p.LiveKitCameraStream, ...]:
+    return tuple(s for s in init.streams if isinstance(s, p.LiveKitCameraStream))
+
+
+@pytest.mark.asyncio
+async def test_server_session_init_streams_include_the_configured_livekit_cameras(unused_tcp_port):
+    streams = _two_streams()
+    running = await start_capture_server(unused_tcp_port, config=ServerConfig(livekit_streams=streams))
+    try:
+        init = await _begin_and_read_init(f"ws://127.0.0.1:{unused_tcp_port}")
+    finally:
+        await stop_capture_server(running)
+    assert _livekit_in(init) == streams
+    assert any(isinstance(s, p.TrackingStream) for s in init.streams)
+
+
+@pytest.mark.asyncio
+async def test_server_without_livekit_streams_offers_none(unused_tcp_port):
+    running = await start_capture_server(unused_tcp_port)
+    try:
+        init = await _begin_and_read_init(f"ws://127.0.0.1:{unused_tcp_port}")
+    finally:
+        await stop_capture_server(running)
+    assert _livekit_in(init) == ()
+
+
+@pytest.mark.asyncio
+async def test_client_started_streams_include_livekit_cameras_and_capture_still_runs(unused_tcp_port):
+    streams = _two_streams()
+    running = await start_capture_server(unused_tcp_port, config=ServerConfig(livekit_streams=streams))
+    started = []
+    frames = []
+    client = CaptureClient(f"ws://127.0.0.1:{unused_tcp_port}")
+    try:
+        await client.start(sources=(p.SourceType.HEAD,), on_started=started.append, on_capture_frame=frames.append)
+        await poll_until(lambda: len(frames) >= 1)
+        await client.stop()
+    finally:
+        await stop_capture_server(running)
+    assert _livekit_in(started[0]) == streams
+    assert not hasattr(started[0], "livekit_streams")
+
+
+def test_client_validate_layout_ignores_livekit_entries_when_checking_requested_cameras():
+    begin = p.BeginRequest(
+        tracking=p.TrackingConfig(sources=(p.SourceType.HEAD,)),
+        cameras=(p.CameraRequest(name="camera_left", type=p.CameraType.OAK_D_COLOR),),
+    )
+    tracking = p.tracking_stream_descriptor(begin.tracking.sources, begin.tracking.rate_hz)
+    camera = p.camera_stream_descriptor(
+        p.CameraStreamConfig(
+            stream_id=1,
+            name="camera_left",
+            type=p.CameraType.OAK_D_COLOR,
+            required=True,
+            width=4,
+            height=3,
+            fps=30.0,
+            jpeg_quality=90,
+        )
+    )
+    init = p.session_init_event(
+        session_id="s", mode=p.CaptureMode.MOCK, begin=begin, streams=[tracking, camera, *_two_streams()]
+    )
+    CaptureClient("ws://127.0.0.1:1")._validate_layout(begin, init)
+    registry = _StreamRegistry.from_session_init(init)
+    assert set(registry.cameras) == {1}
+
+
+# ---------------------------------------------------------------------------
+# CLI flag.
+# ---------------------------------------------------------------------------
+
+
+def test_cli_rejects_a_bad_streams_file_with_exit_code_2(tmp_path, capsys):
+    bad = _write(tmp_path, "livekit: {url: http://lk, room: r, publisher: o, streams: [{name: A, track: t}]}\n")
+    assert main(["--mock", "--livekit-streams", str(bad)]) == 2
+    assert "ws:// or wss://" in capsys.readouterr().err
+
+
+def test_cli_rejects_a_missing_streams_file_with_exit_code_2(tmp_path, capsys):
+    assert main(["--mock", "--livekit-streams", str(tmp_path / "nope.yaml")]) == 2
+    assert "cannot read" in capsys.readouterr().err
+
+
+@pytest.mark.asyncio
+async def test_cli_serves_the_streams_from_the_file(tmp_path, unused_tcp_port):
+    path = _write(tmp_path, _GOOD_YAML)
+    proc = subprocess.Popen(
+        [
+            sys.executable,
+            "-m",
+            "capture_server",
+            "--mock",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            str(unused_tcp_port),
+            "--livekit-streams",
+            str(path),
+        ],  # fmt: skip
+        stderr=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        text=True,
+    )
+    try:
+        # Wait for the startup banner so the connection below cannot race the listener.
+        deadline = time.monotonic() + 10
+        seen = ""
+        while "listening on" not in seen and time.monotonic() < deadline:
+            ready, _, _ = select.select([proc.stderr], [], [], 0.5)
+            if ready:
+                chunk = os.read(proc.stderr.fileno(), 4096).decode(errors="replace")
+                if not chunk:
+                    break
+                seen += chunk
+        assert "listening on" in seen
+        init = await _begin_and_read_init(f"ws://127.0.0.1:{unused_tcp_port}")
+        assert [s.stream_id for s in _livekit_in(init)] == [16, 17]
+    finally:
+        proc.terminate()
+        proc.wait(timeout=10)

From 7929851d1e81e59d19da032b273b6a0f514b0f89 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:01:02 -0800
Subject: [PATCH 04/37] egocap: read the LiveKit streams file with one explicit
 loop

Same fixed stream ids and shared wire-parser validation as before.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../capture_server/livekit_streams.py         | 42 +++++++++----------
 1 file changed, 21 insertions(+), 21 deletions(-)

diff --git a/examples/egocap/capture_server/capture_server/livekit_streams.py b/examples/egocap/capture_server/capture_server/livekit_streams.py
index dd49a54789..d8ecbdfd9f 100644
--- a/examples/egocap/capture_server/capture_server/livekit_streams.py
+++ b/examples/egocap/capture_server/capture_server/livekit_streams.py
@@ -53,29 +53,29 @@ def load_livekit_streams(path: Path) -> tuple[p.LiveKitCameraStream, ...]:
     raw_streams = room.get("streams")
     if not isinstance(raw_streams, list):
         raise ValueError("livekit.streams must be a list")
+    streams: list[p.LiveKitCameraStream] = []
     try:
-        # The wire parser is the one validator: a file that loads is a list every client will accept.
-        streams = tuple(
-            p.LiveKitCameraStream.from_json(
-                {
-                    "stream_id": p.LIVEKIT_STREAM_ID_BASE + i,
-                    "kind": int(p.StreamKind.LIVEKIT_IMAGE),
-                    "name": entry.get("name"),
-                    "url": room.get("url"),
-                    "room": room.get("room"),
-                    "publisher": room.get("publisher"),
-                    "track": entry.get("track"),
-                    "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
-                    "width": entry.get("width"),
-                    "height": entry.get("height"),
-                    "fps": entry.get("fps"),
-                }
+        for index, raw in enumerate(raw_streams):
+            entry = _mapping(raw, f"livekit.streams[{index}]", _STREAM_KEYS)
+            # The wire parser is the one validator: a file that loads is a list every client will accept.
+            streams.append(
+                p.LiveKitCameraStream.from_json(
+                    {
+                        "stream_id": p.LIVEKIT_STREAM_ID_BASE + index,
+                        "kind": int(p.StreamKind.LIVEKIT_IMAGE),
+                        "name": entry.get("name"),
+                        "url": room.get("url"),
+                        "room": room.get("room"),
+                        "publisher": room.get("publisher"),
+                        "track": entry.get("track"),
+                        "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+                        "width": entry.get("width"),
+                        "height": entry.get("height"),
+                        "fps": entry.get("fps"),
+                    }
+                )
             )
-            for i, entry in enumerate(
-                _mapping(raw, f"livekit.streams[{i}]", _STREAM_KEYS) for i, raw in enumerate(raw_streams)
-            )
-        )
         p.check_livekit_streams(streams)
     except p.ProtocolError as exc:
         raise ValueError(f"LiveKit streams file {path}: {exc}") from exc
-    return streams
+    return tuple(streams)

From 80d2bdc7b8af656fdb26ab74c5846129b7336eaa Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:05:56 -0800
Subject: [PATCH 05/37] egocap: receive the offered LiveKit camera video on the
 PC

Add a receiver that joins the offered room with the Python livekit SDK,
reads each offered video track as RGB, and queues frames per stream with
the publisher's own metadata and this process's receive time. A full queue
drops and counts, jumps in the publisher's frame id are counted as missing
frames, and a lost room sets a failed flag. It does not convert publisher
times or write recordings.

Adds the livekit==1.1.20 dependency. Not exercised against a real LiveKit
server or the Orin publisher.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../backend/egocap_web/livekit_receiver.py    | 228 +++++++++
 examples/egocap/pyproject.toml                |   2 +
 .../tests/backend/test_livekit_receiver.py    | 455 ++++++++++++++++++
 3 files changed, 685 insertions(+)
 create mode 100644 examples/egocap/backend/egocap_web/livekit_receiver.py
 create mode 100644 examples/egocap/tests/backend/test_livekit_receiver.py

diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
new file mode 100644
index 0000000000..ccc6e375f3
--- /dev/null
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -0,0 +1,228 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Receives the LiveKit camera video a session offers, for recording.
+
+One room connection serves every offered stream. Each frame arrives with the publisher's own metadata (the
+application timestamp, the frame id and the raw user data) and the time this process took it from the SDK, and is
+put on a bounded per-stream queue. Nothing here converts those publisher times to this machine's clock or writes
+anything: that belongs to the recorder. A full queue never blocks the receiver or hides a loss; the frame is
+dropped and counted, and a jump in the publisher's frame id is counted as missing frames.
+
+This is separate from the browser's own connection: closing the browser does not touch this one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import time
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+
+import numpy as np
+from livekit import rtc
+
+from capture_server import protocol as p
+
+logger = logging.getLogger("isaaccapture.egocap.livekit_receiver")
+
+#: Frames a stream may hold between the SDK and the consumer before further frames are dropped and counted.
+DEFAULT_QUEUE_FRAMES = 8
+#: The SDK keeps only this many undelivered frames per track and drops the oldest silently; its drops show up
+#: as a jump in the publisher's frame id, which is counted below.
+_SDK_QUEUE_FRAMES = 16
+
+
+@dataclass(frozen=True)
+class ReceivedFrame:
+    """One decoded frame and everything the publisher attached to it."""
+
+    stream_id: int
+    #: Height x width x 3, uint8, RGB. Views the SDK frame's own buffer, which the SDK builds per frame and never
+    #: reuses, so no further copy is made here.
+    image: np.ndarray
+    #: ``time.monotonic_ns()`` of this process when the frame was taken from the SDK, not a capture time.
+    receive_time_ns: int
+    #: The WebRTC event timestamp, which the SDK documents as different from the publisher's own metadata.
+    transport_timestamp_us: int
+    #: The publisher's application timestamp; its clock is named by the stream's ``timestamp_basis``.
+    user_timestamp_us: int | None
+    frame_id: int | None
+    user_data: bytes | None
+
+
+@dataclass
+class StreamCounters:
+    """What one stream received and what was lost on the way to the consumer."""
+
+    received: int = 0
+    #: Frames dropped because the consumer's queue was full.
+    queue_overflow: int = 0
+    #: Frames the publisher numbered but that never arrived (SDK drops, network loss).
+    missing_frames: int = 0
+    #: Times the publisher's frame id went backwards or repeated: a restarted publisher.
+    frame_id_resets: int = 0
+    #: Whether the stream's track is currently subscribed.
+    subscribed: bool = False
+    last_frame_id: int | None = field(default=None, repr=False)
+
+
+class LiveKitFrameReceiver:
+    """Joins the room of the offered streams and queues each stream's frames until the consumer takes them."""
+
+    def __init__(
+        self,
+        streams: Sequence[p.LiveKitCameraStream],
+        token: str,
+        *,
+        queue_frames: int = DEFAULT_QUEUE_FRAMES,
+    ) -> None:
+        if not streams:
+            raise ValueError("at least one LiveKit camera stream is required")
+        if len({(s.url, s.room, s.publisher) for s in streams}) != 1:
+            raise ValueError("all streams of one receiver must share a URL, room and publisher")
+        if queue_frames < 1:
+            raise ValueError("queue_frames must be at least 1")
+        self._streams = {s.stream_id: s for s in streams}
+        self._by_track = {s.track: s for s in streams}
+        self._url, self._publisher = streams[0].url, streams[0].publisher
+        self._token = token
+        self._room: rtc.Room | None = None
+        self._queues = {s.stream_id: asyncio.Queue[ReceivedFrame](maxsize=queue_frames) for s in streams}
+        self.counters = {s.stream_id: StreamCounters() for s in streams}
+        self._readers: dict[int, asyncio.Task[None]] = {}
+        # Set once the room connection is lost for good; the SDK's own reconnects do not set it.
+        self.failed = asyncio.Event()
+
+    async def start(self) -> None:
+        """Connect and begin receiving; frames of tracks published before or after joining are both picked up."""
+        room = rtc.Room()
+        self._room = room
+        room.on("track_subscribed", self._on_track_subscribed)
+        room.on("track_unsubscribed", self._on_track_unsubscribed)
+        room.on("participant_disconnected", self._on_participant_disconnected)
+        room.on("disconnected", self._on_disconnected)
+        await room.connect(self._url, self._token)
+        # Tracks published before we joined arrive here rather than through track_subscribed.
+        for participant in room.remote_participants.values():
+            for publication in participant.track_publications.values():
+                if publication.track is not None:
+                    self._attach(participant, publication.track, publication.name)
+
+    async def stop(self) -> None:
+        """Leave the room and stop every reader; frames still queued stay available to the consumer."""
+        room, self._room = self._room, None
+        for task in self._readers.values():
+            task.cancel()
+        for task in list(self._readers.values()):
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        self._readers.clear()
+        if room is not None:
+            await room.disconnect()
+        for counters in self.counters.values():
+            counters.subscribed = False
+
+    async def next_frame(self, stream_id: int) -> ReceivedFrame:
+        """The oldest queued frame of ``stream_id``, waiting for one if none is queued."""
+        return await self._queues[stream_id].get()
+
+    def pending(self, stream_id: int) -> int:
+        """How many frames of ``stream_id`` are queued for the consumer."""
+        return self._queues[stream_id].qsize()
+
+    def _attach(self, participant: rtc.RemoteParticipant, track: rtc.Track, name: str) -> None:
+        """Start reading ``track`` if it is one of the offered streams, from the offered publisher."""
+        stream = self._by_track.get(name)
+        if participant.identity != self._publisher or stream is None or track.kind != rtc.TrackKind.KIND_VIDEO:
+            return
+        # A republished track replaces the old reader; its frames must not interleave with the new ones.
+        previous = self._readers.pop(stream.stream_id, None)
+        if previous is not None:
+            previous.cancel()
+        self.counters[stream.stream_id].subscribed = True
+        # A new publication restarts the publisher's numbering, so a jump from the old track is not a loss.
+        self.counters[stream.stream_id].last_frame_id = None
+        self._readers[stream.stream_id] = asyncio.get_running_loop().create_task(
+            self._read(stream.stream_id, track)
+        )
+
+    def _detach(self, stream_id: int) -> None:
+        """Stop reading ``stream_id``: its track went away."""
+        task = self._readers.pop(stream_id, None)
+        if task is not None:
+            task.cancel()
+        self.counters[stream_id].subscribed = False
+
+    def _on_track_subscribed(
+        self, track: rtc.Track, publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant
+    ) -> None:
+        self._attach(participant, track, publication.name)
+
+    def _on_track_unsubscribed(
+        self, track: rtc.Track, publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant
+    ) -> None:
+        stream = self._by_track.get(publication.name)
+        if stream is not None and participant.identity == self._publisher:
+            self._detach(stream.stream_id)
+
+    def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
+        if participant.identity == self._publisher:
+            for stream_id in list(self._readers):
+                self._detach(stream_id)
+
+    def _on_disconnected(self, *_: object) -> None:
+        # Not a reconnect (the SDK reports those separately): the room is gone, and the recorder must find out.
+        for stream_id in list(self._readers):
+            self._detach(stream_id)
+        self.failed.set()
+
+    async def _read(self, stream_id: int, track: rtc.Track) -> None:
+        """Take frames of one track from the SDK, convert them, and queue them for the consumer."""
+        counters = self.counters[stream_id]
+        video = rtc.VideoStream(track, capacity=_SDK_QUEUE_FRAMES, format=rtc.VideoBufferType.RGB24)
+        try:
+            async for event in video:
+                received_at = time.monotonic_ns()
+                frame = event.frame
+                image = np.frombuffer(frame.data, dtype=np.uint8).reshape(frame.height, frame.width, 3)
+                metadata = event.metadata
+                has_meta = metadata is not None
+                frame_id = metadata.frame_id if has_meta and metadata.HasField("frame_id") else None
+                self._account(counters, frame_id)
+                item = ReceivedFrame(
+                    stream_id=stream_id,
+                    image=image,
+                    receive_time_ns=received_at,
+                    transport_timestamp_us=event.timestamp_us,
+                    user_timestamp_us=metadata.user_timestamp
+                    if has_meta and metadata.HasField("user_timestamp")
+                    else None,
+                    frame_id=frame_id,
+                    user_data=bytes(metadata.user_data) if has_meta and metadata.HasField("user_data") else None,
+                )
+                try:
+                    self._queues[stream_id].put_nowait(item)
+                except asyncio.QueueFull:
+                    # Never block the reader or skip silently: the consumer is behind, and the loss is counted.
+                    counters.queue_overflow += 1
+        finally:
+            await video.aclose()
+
+    @staticmethod
+    def _account(counters: StreamCounters, frame_id: int | None) -> None:
+        """Count a received frame, and any frames the publisher numbered that did not arrive before it."""
+        counters.received += 1
+        if frame_id is None:
+            return
+        last = counters.last_frame_id
+        if last is not None:
+            if frame_id <= last:
+                # The publisher restarted its numbering: a new run, not a loss.
+                counters.frame_id_resets += 1
+            elif frame_id > last + 1:
+                counters.missing_frames += frame_id - last - 1
+        counters.last_frame_id = frame_id
diff --git a/examples/egocap/pyproject.toml b/examples/egocap/pyproject.toml
index 64bb53cd95..1ad3560962 100644
--- a/examples/egocap/pyproject.toml
+++ b/examples/egocap/pyproject.toml
@@ -39,6 +39,8 @@ dependencies = [
     "uvicorn[standard]>=0.30",
     "viser==0.2.23",             # the 3D tracking view, on by default and embedded by iframe
                                  # (backend/egocap_web/viser_scene.py); EGOCAP_VISER_ENABLED=0 turns it off.
+    "livekit==1.1.20",           # receives the offered LiveKit camera video for recording
+                                 # (backend/egocap_web/livekit_receiver.py); the browser uses livekit-client.
 ]
 
 [project.optional-dependencies]
diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
new file mode 100644
index 0000000000..82a563bf87
--- /dev/null
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -0,0 +1,455 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""LiveKitFrameReceiver against a fake ``livekit.rtc``: subscription, frame accounting, queues, teardown."""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+from livekit import rtc as real_rtc
+
+from capture_server import protocol as p
+from egocap_web import livekit_receiver as lr
+
+URL = "ws://lk.test"
+ROOM = "room"
+PUBLISHER = "orin"
+TOKEN = "tok"
+
+
+class FakeTrack:
+    """A remote video track; the test feeds its events through ``push``."""
+
+    def __init__(self, kind: str = "video") -> None:
+        self.kind = kind
+        self.events: asyncio.Queue = asyncio.Queue()
+
+    def push(self, event: object) -> None:
+        self.events.put_nowait(event)
+
+
+class FakeVideoStream:
+    """Async iterator over a track's pushed events that blocks (cancellably) while there are none."""
+
+    instances: list[FakeVideoStream] = []
+
+    def __init__(self, track: FakeTrack, capacity: int = 0, format: object = None) -> None:
+        self.track, self.capacity, self.format = track, capacity, format
+        self.closed = 0
+        FakeVideoStream.instances.append(self)
+
+    def __aiter__(self) -> FakeVideoStream:
+        return self
+
+    async def __anext__(self) -> object:
+        return await self.track.events.get()
+
+    async def aclose(self) -> None:
+        self.closed += 1
+
+
+class FakeRoom:
+    """Records handlers and connect/disconnect calls; ``emit`` plays an SDK event."""
+
+    def __init__(self) -> None:
+        self.handlers: dict[str, object] = {}
+        self.connected_with: tuple[str, str] | None = None
+        self.disconnects = 0
+        self.remote_participants: dict[str, object] = {}
+
+    def on(self, name: str, handler: object) -> None:
+        self.handlers[name] = handler
+
+    async def connect(self, url: str, token: str) -> None:
+        self.connected_with = (url, token)
+
+    async def disconnect(self) -> None:
+        self.disconnects += 1
+
+    def emit(self, name: str, *args: object) -> None:
+        self.handlers[name](*args)
+
+
+FAKE_RTC = SimpleNamespace(
+    Room=FakeRoom,
+    VideoStream=FakeVideoStream,
+    TrackKind=SimpleNamespace(KIND_VIDEO="video"),
+    VideoBufferType=SimpleNamespace(RGB24="rgb24"),
+)
+
+
+def participant(identity: str = PUBLISHER, publications: dict | None = None) -> SimpleNamespace:
+    return SimpleNamespace(identity=identity, track_publications=publications or {})
+
+
+def publication(name: str, track: FakeTrack | None) -> SimpleNamespace:
+    return SimpleNamespace(name=name, track=track)
+
+
+def event(
+    value: int = 0,
+    *,
+    frame_id: int | None = None,
+    user_timestamp: int | None = None,
+    user_data: bytes | None = None,
+    no_metadata: bool = False,
+    timestamp_us: int = 111,
+    shape: tuple[int, int] = (2, 3),
+) -> SimpleNamespace:
+    height, width = shape
+    pixels = np.full((height, width, 3), value, dtype=np.uint8)
+    fields = {}
+    if frame_id is not None:
+        fields["frame_id"] = frame_id
+    if user_timestamp is not None:
+        fields["user_timestamp"] = user_timestamp
+    if user_data is not None:
+        fields["user_data"] = user_data
+    metadata = None if no_metadata else real_rtc.FrameMetadata(**fields)
+    frame = SimpleNamespace(data=memoryview(pixels), width=width, height=height)
+    return SimpleNamespace(frame=frame, timestamp_us=timestamp_us, metadata=metadata, pixels=pixels)
+
+
+def camera(stream_id: int, track: str, **overrides: str) -> p.LiveKitCameraStream:
+    fields = {"url": URL, "room": ROOM, "publisher": PUBLISHER, **overrides}
+    return p.LiveKitCameraStream(stream_id=stream_id, name=f"cam{stream_id}", track=track, **fields)
+
+
+async def settle() -> None:
+    for _ in range(5):
+        await asyncio.sleep(0)
+
+
+@pytest.fixture(autouse=True)
+def fake_sdk(monkeypatch: pytest.MonkeyPatch) -> None:
+    FakeVideoStream.instances = []
+    monkeypatch.setattr(lr, "rtc", FAKE_RTC)
+
+
+@pytest.fixture
+async def receiver():
+    rx = lr.LiveKitFrameReceiver([camera(1, "left"), camera(2, "right")], TOKEN)
+    await rx.start()
+    yield rx
+    await rx.stop()
+
+
+def room_of(rx: lr.LiveKitFrameReceiver) -> FakeRoom:
+    return rx._room
+
+
+def subscribe(rx: lr.LiveKitFrameReceiver, name: str = "left", who: str = PUBLISHER) -> FakeTrack:
+    track = FakeTrack()
+    room_of(rx).emit("track_subscribed", track, publication(name, track), participant(who))
+    return track
+
+
+# ---- constructor ----
+
+
+def test_constructor_requires_a_stream():
+    with pytest.raises(ValueError, match="at least one"):
+        lr.LiveKitFrameReceiver([], TOKEN)
+
+
+@pytest.mark.parametrize(
+    "other",
+    [camera(2, "b", room="other"), camera(2, "b", publisher="someone"), camera(2, "b", url="ws://other")],
+)
+def test_constructor_rejects_streams_from_different_room_publisher_or_url(other):
+    with pytest.raises(ValueError, match="share a URL, room and publisher"):
+        lr.LiveKitFrameReceiver([camera(1, "a"), other], TOKEN)
+
+
+@pytest.mark.parametrize("queue_frames", [0, -1])
+def test_constructor_rejects_queue_smaller_than_one(queue_frames):
+    with pytest.raises(ValueError, match="queue_frames"):
+        lr.LiveKitFrameReceiver([camera(1, "a")], TOKEN, queue_frames=queue_frames)
+
+
+# ---- start and subscription ----
+
+
+async def test_start_connects_with_url_and_token(receiver):
+    assert room_of(receiver).connected_with == (URL, TOKEN)
+    assert not receiver.failed.is_set()
+    assert not receiver.counters[1].subscribed
+
+
+async def test_start_adopts_tracks_published_before_joining(monkeypatch):
+    left, right = FakeTrack(), FakeTrack()
+
+    class Prejoined(FakeRoom):
+        def __init__(self) -> None:
+            super().__init__()
+            self.remote_participants = {
+                "x": participant(
+                    PUBLISHER,
+                    {
+                        "a": publication("left", left),
+                        "b": publication("right", right),
+                        "c": publication("left", None),
+                    },
+                )
+            }
+
+    monkeypatch.setattr(lr, "rtc", SimpleNamespace(**{**vars(FAKE_RTC), "Room": Prejoined}))
+    rx = lr.LiveKitFrameReceiver([camera(1, "left"), camera(2, "right")], TOKEN)
+    await rx.start()
+    try:
+        assert rx.counters[1].subscribed and rx.counters[2].subscribed
+        left.push(event(7, frame_id=1))
+        assert (await asyncio.wait_for(rx.next_frame(1), 1)).frame_id == 1
+        stream = FakeVideoStream.instances[0]
+        assert stream.capacity == lr._SDK_QUEUE_FRAMES and stream.format == "rgb24"
+    finally:
+        await rx.stop()
+
+
+async def test_track_subscribed_starts_reading(receiver):
+    track = subscribe(receiver, "left")
+    assert receiver.counters[1].subscribed and not receiver.counters[2].subscribed
+    track.push(event(3, frame_id=1))
+    assert (await asyncio.wait_for(receiver.next_frame(1), 1)).frame_id == 1
+
+
+async def test_other_participant_is_ignored(receiver):
+    track = subscribe(receiver, "left", who="intruder")
+    track.push(event())
+    await settle()
+    assert not receiver.counters[1].subscribed
+    assert receiver.pending(1) == 0 and not FakeVideoStream.instances
+
+
+async def test_unoffered_track_name_is_ignored(receiver):
+    track = subscribe(receiver, "depth")
+    track.push(event())
+    await settle()
+    assert not any(c.subscribed for c in receiver.counters.values())
+    assert not FakeVideoStream.instances
+
+
+async def test_non_video_track_is_ignored(receiver):
+    track = FakeTrack(kind="audio")
+    room_of(receiver).emit("track_subscribed", track, publication("left", track), participant())
+    assert not receiver.counters[1].subscribed
+
+
+# ---- frames ----
+
+
+async def test_frames_arrive_in_order_with_image_and_metadata(receiver):
+    track = subscribe(receiver)
+    before = time.monotonic_ns()
+    track.push(event(10, frame_id=1, user_timestamp=1000, user_data=b"\x01\x02", timestamp_us=5, shape=(4, 6)))
+    track.push(event(20, frame_id=2, user_timestamp=2000, user_data=b"", timestamp_us=6, shape=(4, 6)))
+    first = await asyncio.wait_for(receiver.next_frame(1), 1)
+    second = await asyncio.wait_for(receiver.next_frame(1), 1)
+    after = time.monotonic_ns()
+    assert first.stream_id == 1
+    assert first.image.shape == (4, 6, 3) and first.image.dtype == np.uint8
+    assert (first.image == 10).all() and (second.image == 20).all()
+    assert (first.frame_id, second.frame_id) == (1, 2)
+    assert (first.user_timestamp_us, second.user_timestamp_us) == (1000, 2000)
+    assert (first.transport_timestamp_us, second.transport_timestamp_us) == (5, 6)
+    assert first.user_data == b"\x01\x02" and second.user_data == b""
+    assert before <= first.receive_time_ns <= second.receive_time_ns <= after
+    assert receiver.counters[1].received == 2
+
+
+async def test_absent_metadata_fields_are_none(receiver):
+    track = subscribe(receiver)
+    track.push(event(1, frame_id=4))
+    frame = await asyncio.wait_for(receiver.next_frame(1), 1)
+    assert frame.frame_id == 4
+    assert frame.user_timestamp_us is None and frame.user_data is None
+
+
+async def test_missing_metadata_object_gives_none_fields_and_no_loss_accounting(receiver):
+    track = subscribe(receiver)
+    track.push(event(1, no_metadata=True))
+    track.push(event(2, no_metadata=True))
+    frames = [await asyncio.wait_for(receiver.next_frame(1), 1) for _ in range(2)]
+    assert all(f.frame_id is None and f.user_timestamp_us is None and f.user_data is None for f in frames)
+    counters = receiver.counters[1]
+    assert (counters.received, counters.missing_frames, counters.frame_id_resets) == (2, 0, 0)
+
+
+async def test_successive_frames_hold_their_own_distinct_images(receiver):
+    track = subscribe(receiver)
+    for value, fid in ((9, 1), (50, 2), (200, 3)):
+        track.push(event(value, frame_id=fid, shape=(2, 3)))
+    frames = [await asyncio.wait_for(receiver.next_frame(1), 1) for _ in range(3)]
+    for frame, value in zip(frames, (9, 50, 200)):
+        assert frame.image.shape == (2, 3, 3) and frame.image.dtype == np.uint8
+        assert (frame.image == value).all()
+    assert not np.shares_memory(frames[0].image, frames[1].image)
+    assert not np.shares_memory(frames[1].image, frames[2].image)
+
+
+async def test_streams_are_queued_independently(receiver):
+    subscribe(receiver, "left").push(event(1, frame_id=1))
+    subscribe(receiver, "right").push(event(2, frame_id=1))
+    assert (await asyncio.wait_for(receiver.next_frame(2), 1)).image[0, 0, 0] == 2
+    assert (await asyncio.wait_for(receiver.next_frame(1), 1)).image[0, 0, 0] == 1
+
+
+# ---- loss accounting ----
+
+
+async def _drain(rx: lr.LiveKitFrameReceiver, count: int) -> None:
+    for _ in range(count):
+        await asyncio.wait_for(rx.next_frame(1), 1)
+
+
+async def test_frame_id_jump_counts_missing_frames_but_first_frame_is_not_a_loss(receiver):
+    track = subscribe(receiver)
+    for fid in (100, 101, 104):
+        track.push(event(frame_id=fid))
+    await _drain(receiver, 3)
+    counters = receiver.counters[1]
+    assert counters.missing_frames == 2
+    assert counters.frame_id_resets == 0 and counters.last_frame_id == 104
+
+
+async def test_repeated_or_decreasing_frame_id_is_a_reset_not_a_loss(receiver):
+    track = subscribe(receiver)
+    for fid in (5, 6, 6, 2, 3):
+        track.push(event(frame_id=fid))
+    await _drain(receiver, 5)
+    counters = receiver.counters[1]
+    assert counters.frame_id_resets == 2
+    assert counters.missing_frames == 0 and counters.last_frame_id == 3
+
+
+# ---- bounded queue ----
+
+
+async def test_full_queue_counts_overflow_keeps_oldest_and_never_blocks():
+    rx = lr.LiveKitFrameReceiver([camera(1, "left")], TOKEN, queue_frames=2)
+    await rx.start()
+    try:
+        track = subscribe(rx)
+        for fid in range(1, 6):
+            track.push(event(fid, frame_id=fid))
+        await settle()
+        counters = rx.counters[1]
+        assert counters.received == 5 and counters.queue_overflow == 3
+        assert counters.missing_frames == 0
+        assert rx.pending(1) == 2
+        kept = [await asyncio.wait_for(rx.next_frame(1), 1) for _ in range(2)]
+        assert [f.frame_id for f in kept] == [1, 2]
+        # The reader is still alive after overflow.
+        track.push(event(9, frame_id=6))
+        assert (await asyncio.wait_for(rx.next_frame(1), 1)).frame_id == 6
+    finally:
+        await rx.stop()
+
+
+async def test_pending_reports_queued_counts(receiver):
+    track = subscribe(receiver)
+    assert receiver.pending(1) == 0 and receiver.pending(2) == 0
+    for fid in (1, 2, 3):
+        track.push(event(frame_id=fid))
+    await settle()
+    assert receiver.pending(1) == 3 and receiver.pending(2) == 0
+    await receiver.next_frame(1)
+    assert receiver.pending(1) == 2
+
+
+# ---- detach and republish ----
+
+
+async def test_track_unsubscribed_detaches_and_cancels_reader(receiver):
+    track = subscribe(receiver)
+    await settle()
+    reader = receiver._readers[1]
+    room_of(receiver).emit("track_unsubscribed", track, publication("left", track), participant())
+    await settle()
+    assert not receiver.counters[1].subscribed
+    assert reader.cancelled() and 1 not in receiver._readers
+    assert FakeVideoStream.instances[0].closed == 1
+
+
+async def test_unsubscribe_of_other_participant_or_track_is_ignored(receiver):
+    track = subscribe(receiver)
+    room_of(receiver).emit("track_unsubscribed", track, publication("left", track), participant("intruder"))
+    room_of(receiver).emit("track_unsubscribed", track, publication("depth", track), participant())
+    assert receiver.counters[1].subscribed and 1 in receiver._readers
+
+
+async def test_publisher_disconnect_detaches_every_stream(receiver):
+    subscribe(receiver, "left")
+    subscribe(receiver, "right")
+    await settle()
+    room_of(receiver).emit("participant_disconnected", participant("intruder"))
+    assert receiver.counters[1].subscribed and receiver.counters[2].subscribed
+    room_of(receiver).emit("participant_disconnected", participant())
+    await settle()
+    assert not receiver.counters[1].subscribed and not receiver.counters[2].subscribed
+    assert not receiver._readers
+    assert [s.closed for s in FakeVideoStream.instances] == [1, 1]
+    assert not receiver.failed.is_set()
+
+
+async def test_republication_replaces_reader_and_resets_frame_numbering(receiver):
+    old = subscribe(receiver)
+    old.push(event(1, frame_id=500))
+    await _drain(receiver, 1)
+    old_reader = receiver._readers[1]
+    new = subscribe(receiver)
+    await settle()
+    assert old_reader.cancelled() and receiver._readers[1] is not old_reader
+    assert receiver.counters[1].last_frame_id is None
+    new.push(event(2, frame_id=1))
+    frame = await asyncio.wait_for(receiver.next_frame(1), 1)
+    assert frame.frame_id == 1
+    counters = receiver.counters[1]
+    assert counters.missing_frames == 0 and counters.frame_id_resets == 0 and counters.subscribed
+    # The replaced track no longer feeds the queue.
+    old.push(event(3, frame_id=501))
+    await settle()
+    assert receiver.pending(1) == 0
+
+
+# ---- failure and stop ----
+
+
+async def test_room_disconnected_sets_failed_and_detaches(receiver):
+    subscribe(receiver, "left")
+    subscribe(receiver, "right")
+    room_of(receiver).emit("disconnected", "SOME_REASON")
+    await settle()
+    assert receiver.failed.is_set()
+    assert not any(c.subscribed for c in receiver.counters.values())
+    assert not receiver._readers
+
+
+async def test_stop_cancels_readers_disconnects_once_and_keeps_queued_frames():
+    rx = lr.LiveKitFrameReceiver([camera(1, "left")], TOKEN)
+    await rx.start()
+    room = room_of(rx)
+    track = subscribe(rx)
+    track.push(event(4, frame_id=1))
+    await settle()
+    reader = rx._readers[1]
+    await rx.stop()
+    await rx.stop()
+    assert reader.cancelled() and not rx._readers
+    assert room.disconnects == 1
+    assert FakeVideoStream.instances[0].closed == 1
+    assert not rx.counters[1].subscribed
+    assert rx.pending(1) == 1
+    assert (await asyncio.wait_for(rx.next_frame(1), 1)).frame_id == 1
+
+
+async def test_stop_before_start_is_harmless():
+    rx = lr.LiveKitFrameReceiver([camera(1, "left")], TOKEN)
+    await rx.stop()
+    assert not rx.failed.is_set()

From e556c052cbad95c8dc5d823d1120b9acd038a85a Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:12:17 -0800
Subject: [PATCH 06/37] egocap: feed received LiveKit frames to the recorder,
 and fail when a track is lost

Add a Unix-microseconds timestamp basis, a clock map from it to this
machine's monotonic clock (a bracketed pair refreshed about once a second),
and a feed that offers each mapped frame to a take's recording ingress.
A stream on the publisher's own monotonic clock is refused with a reason
instead of recording a guessed time; arrival time is never used as capture
time. The receiver wakes a waiting consumer when a track is unsubscribed,
the publisher leaves, or the room is lost, so a required source cannot go
missing silently. The ingress sizes a decoded frame by its pixels, and the
loader takes an optional timestamp_basis.

Not yet connected to a recording take, and the native sender does not yet
publish Unix time. Not exercised against a real LiveKit server.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../backend/egocap_web/livekit_receiver.py    |  30 +-
 .../backend/egocap_web/livekit_recording.py   | 186 ++++++++
 .../backend/egocap_web/recording_adapter.py   |   6 +-
 .../capture_server/livekit_streams.py         |  13 +-
 .../capture_server/capture_server/protocol.py |   7 +-
 .../tests/backend/test_livekit_receiver.py    | 170 ++++++++
 .../tests/backend/test_livekit_recording.py   | 400 ++++++++++++++++++
 .../tests/backend/test_recording_adapter.py   |  69 ++-
 .../capture_server/test_livekit_streams.py    |  54 ++-
 9 files changed, 926 insertions(+), 9 deletions(-)
 create mode 100644 examples/egocap/backend/egocap_web/livekit_recording.py
 create mode 100644 examples/egocap/tests/backend/test_livekit_recording.py

diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
index ccc6e375f3..98a039c81f 100644
--- a/examples/egocap/backend/egocap_web/livekit_receiver.py
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -93,6 +93,9 @@ def __init__(
         self._room: rtc.Room | None = None
         self._queues = {s.stream_id: asyncio.Queue[ReceivedFrame](maxsize=queue_frames) for s in streams}
         self.counters = {s.stream_id: StreamCounters() for s in streams}
+        # Set when a stream's track goes away or the room is lost, so a waiting consumer can fail instead of
+        # waiting forever; cleared when the track is subscribed again.
+        self._lost = {s.stream_id: asyncio.Event() for s in streams}
         self._readers: dict[int, asyncio.Task[None]] = {}
         # Set once the room connection is lost for good; the SDK's own reconnects do not set it.
         self.failed = asyncio.Event()
@@ -130,6 +133,26 @@ async def next_frame(self, stream_id: int) -> ReceivedFrame:
         """The oldest queued frame of ``stream_id``, waiting for one if none is queued."""
         return await self._queues[stream_id].get()
 
+    async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
+        """The oldest queued frame of ``stream_id``, or None once its track is lost and nothing is queued.
+
+        Frames already queued when the track goes away are still returned first, so a consumer drains what
+        arrived before it learns of the loss.
+        """
+        queue = self._queues[stream_id]
+        if not queue.empty():
+            return queue.get_nowait()
+        get = asyncio.ensure_future(queue.get())
+        lost = asyncio.ensure_future(self._lost[stream_id].wait())
+        try:
+            await asyncio.wait({get, lost}, return_when=asyncio.FIRST_COMPLETED)
+            # A frame that arrived together with the loss is still a frame the consumer is owed.
+            return get.result() if get.done() else None
+        finally:
+            for task in (get, lost):
+                if not task.done():
+                    task.cancel()
+
     def pending(self, stream_id: int) -> int:
         """How many frames of ``stream_id`` are queued for the consumer."""
         return self._queues[stream_id].qsize()
@@ -144,6 +167,7 @@ def _attach(self, participant: rtc.RemoteParticipant, track: rtc.Track, name: st
         if previous is not None:
             previous.cancel()
         self.counters[stream.stream_id].subscribed = True
+        self._lost[stream.stream_id].clear()
         # A new publication restarts the publisher's numbering, so a jump from the old track is not a loss.
         self.counters[stream.stream_id].last_frame_id = None
         self._readers[stream.stream_id] = asyncio.get_running_loop().create_task(
@@ -156,6 +180,7 @@ def _detach(self, stream_id: int) -> None:
         if task is not None:
             task.cancel()
         self.counters[stream_id].subscribed = False
+        self._lost[stream_id].set()
 
     def _on_track_subscribed(
         self, track: rtc.Track, publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant
@@ -171,12 +196,13 @@ def _on_track_unsubscribed(
 
     def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
         if participant.identity == self._publisher:
-            for stream_id in list(self._readers):
+            # Every offered stream, not only those already being read: one that never appeared is lost too.
+            for stream_id in self._streams:
                 self._detach(stream_id)
 
     def _on_disconnected(self, *_: object) -> None:
         # Not a reconnect (the SDK reports those separately): the room is gone, and the recorder must find out.
-        for stream_id in list(self._readers):
+        for stream_id in self._streams:
             self._detach(stream_id)
         self.failed.set()
 
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
new file mode 100644
index 0000000000..74af8eb03a
--- /dev/null
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -0,0 +1,186 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Feeds received LiveKit camera frames into a take's recording ingress.
+
+A frame is recorded only when its capture time can be put on this machine's monotonic clock, the same clock the
+tracking samples use. That is possible when the publisher's application timestamp is Unix time on a host kept in
+step with this one (``PUBLISHER_UNIX_US``). A stream whose timestamp is on the publisher's own monotonic clock has
+no honest mapping, so the feed stops with that reason instead of recording a guessed time. Arrival time is never
+used as capture time.
+
+This assumes the backend runs on the machine whose monotonic clock CaptureServer reports: tracking times come from
+CaptureServer, and the two agree only when both processes share a clock.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import time
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+
+import numpy as np
+
+from capture_server import protocol as p
+from recording_service import PixelFormat, VideoSample
+
+from .livekit_receiver import LiveKitFrameReceiver, ReceivedFrame
+from .recording_adapter import RecordingIngress
+
+logger = logging.getLogger("isaaccapture.egocap.livekit_recording")
+
+#: How long a measured pair of clock readings is reused. Unix and monotonic time only drift apart slowly, and a
+#: step of the Unix clock is caught within this interval.
+_PAIR_MAX_AGE_S = 1.0
+#: Readings per pair; the one read in the shortest span is the most trustworthy.
+_PAIR_ATTEMPTS = 3
+
+
+class UnixClockMap:
+    """Converts Unix-time microseconds to this process's monotonic seconds, from a recently measured pair.
+
+    The pair is two clock readings taken back to back and refreshed about once a second, from the consumer's
+    thread and never from an SDK callback. Between refreshes the two clocks run at the same rate, so the offset
+    holds; a step of the Unix clock shows up at the next refresh.
+    """
+
+    def __init__(
+        self,
+        *,
+        monotonic_ns: Callable[[], int] = time.monotonic_ns,
+        unix_ns: Callable[[], int] = time.time_ns,
+    ) -> None:
+        self._monotonic_ns = monotonic_ns
+        self._unix_ns = unix_ns
+        self._offset_s = 0.0
+        self._measured_at_ns: int | None = None
+
+    def monotonic_seconds(self, unix_us: int) -> float:
+        """The monotonic-clock time, in seconds, of the Unix time ``unix_us`` (microseconds)."""
+        now = self._monotonic_ns()
+        if self._measured_at_ns is None or now - self._measured_at_ns > _PAIR_MAX_AGE_S * 1e9:
+            self._measure()
+        return unix_us / 1e6 + self._offset_s
+
+    def _measure(self) -> None:
+        """Take the pair read in the shortest span: the Unix reading is taken between two monotonic ones."""
+        best: tuple[int, float] | None = None
+        for _ in range(_PAIR_ATTEMPTS):
+            before = self._monotonic_ns()
+            unix = self._unix_ns()
+            after = self._monotonic_ns()
+            span = after - before
+            if best is None or span < best[0]:
+                # The Unix reading happened somewhere in [before, after]; its midpoint is the best estimate.
+                best = (span, ((before + after) / 2 - unix) / 1e9)
+        assert best is not None
+        self._offset_s = best[1]
+        self._measured_at_ns = self._monotonic_ns()
+
+
+@dataclass(frozen=True)
+class MappedFrame:
+    """A received frame with the recording source it belongs to and its capture time on this machine's clock."""
+
+    frame: ReceivedFrame
+    source: str
+    capture_time: float
+
+    @property
+    def image(self) -> np.ndarray:
+        """The frame's pixels, so the ingress can size its queue by bytes."""
+        return self.frame.image
+
+
+def mapped_frame_to_samples(item: MappedFrame) -> list[VideoSample]:
+    """The recording sample for one mapped frame (the ingress's ``convert``)."""
+    return [
+        VideoSample(
+            source=item.source,
+            image=item.frame.image,
+            pixel_format=PixelFormat.RGB8,
+            capture_time=item.capture_time,
+            receive_time=item.frame.receive_time_ns / 1e9,
+        )
+    ]
+
+
+class LiveKitRecordingFeed:
+    """Moves every offered stream's frames from the receiver into the ingress of one take.
+
+    Stops, with the reason in ``failure``, at the first frame that cannot be recorded honestly or when the ingress
+    stops accepting; the recorder settles the take from that, so a source never goes missing silently.
+    """
+
+    def __init__(
+        self,
+        receiver: LiveKitFrameReceiver,
+        streams: Sequence[p.LiveKitCameraStream],
+        ingress: RecordingIngress,
+        source_names: Mapping[int, str],
+        *,
+        clock_map: UnixClockMap | None = None,
+        on_failure: Callable[[str], None] | None = None,
+    ) -> None:
+        missing = [s.name for s in streams if s.stream_id not in source_names]
+        if missing:
+            raise ValueError(f"no recording source for LiveKit stream(s): {missing}")
+        self._receiver = receiver
+        self._streams = {s.stream_id: s for s in streams}
+        self._ingress = ingress
+        self._source_names = dict(source_names)
+        self._clock_map = clock_map or UnixClockMap()
+        self._on_failure = on_failure
+        self._tasks: list[asyncio.Task[None]] = []
+        self.failure: str | None = None
+
+    def start(self) -> None:
+        """Begin feeding; one task per stream so a slow stream never delays another."""
+        loop = asyncio.get_running_loop()
+        self._tasks = [loop.create_task(self._run(stream_id)) for stream_id in self._streams]
+
+    async def stop(self) -> None:
+        """Stop feeding. Frames already offered to the ingress stay with it."""
+        for task in self._tasks:
+            task.cancel()
+        for task in self._tasks:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
+        self._tasks = []
+
+    def _fail(self, reason: str) -> None:
+        """Record the first reason feeding had to stop, once, and tell the recorder."""
+        if self.failure is None:
+            self.failure = reason
+            logger.error("LiveKit recording feed stopped: %s", reason)
+            if self._on_failure is not None:
+                self._on_failure(reason)
+
+    async def _run(self, stream_id: int) -> None:
+        """Feed one stream until the take fails or the feed is stopped."""
+        stream = self._streams[stream_id]
+        source = self._source_names[stream_id]
+        if stream.timestamp_basis is not p.LiveKitTimestampBasis.PUBLISHER_UNIX_US:
+            # Checked before any frame arrives: this stream cannot become recordable by waiting.
+            self._fail(
+                f"{stream.name}: timestamps are on the publisher's own clock and cannot be aligned with tracking"
+            )
+            return
+        while self.failure is None:
+            frame = await self._receiver.next_frame_or_lost(stream_id)
+            if frame is None:
+                # Whatever was queued has been taken; the camera is gone, and a recorded source must not vanish.
+                self._fail(f"{stream.name}: the LiveKit track was lost")
+                return
+            if frame.user_timestamp_us is None:
+                self._fail(f"{stream.name}: a frame arrived without the publisher's capture timestamp")
+                return
+            capture_time = self._clock_map.monotonic_seconds(frame.user_timestamp_us)
+            if not self._ingress.offer(MappedFrame(frame, source, capture_time)):
+                # The ingress refuses once it has failed or stopped; it reports its own reason.
+                self._fail(f"{stream.name}: the recording ingress is no longer accepting frames")
+                return
diff --git a/examples/egocap/backend/egocap_web/recording_adapter.py b/examples/egocap/backend/egocap_web/recording_adapter.py
index deb0ad6173..47b456f2e3 100644
--- a/examples/egocap/backend/egocap_web/recording_adapter.py
+++ b/examples/egocap/backend/egocap_web/recording_adapter.py
@@ -352,7 +352,11 @@ def convert_capture_frame(frame: CaptureFrame) -> list[NumericSample]:
 
 
 def _raw_item_bytes(raw_item: RawItem) -> int:
-    """The memory one queued raw item pins: the compressed JPEG or the raw tracking blob."""
+    """The memory one queued raw item pins: the compressed JPEG, the raw tracking blob or a decoded frame."""
+    image = getattr(raw_item, "image", None)
+    if image is not None:
+        # A decoded LiveKit frame (livekit_recording.MappedFrame) pins its pixels, not a compressed payload.
+        return image.nbytes
     return len(raw_item.jpeg) if isinstance(raw_item, CameraImage) else len(raw_item.payload)
 
 
diff --git a/examples/egocap/capture_server/capture_server/livekit_streams.py b/examples/egocap/capture_server/capture_server/livekit_streams.py
index d8ecbdfd9f..89562cee49 100644
--- a/examples/egocap/capture_server/capture_server/livekit_streams.py
+++ b/examples/egocap/capture_server/capture_server/livekit_streams.py
@@ -13,6 +13,7 @@
       url: wss://LIVEKIT_HOST
       room: sensing-preview
       publisher: orin-sensing
+      timestamp_basis: unix_us   # optional; default monotonic_us (not recordable against tracking)
       streams:
         - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
 """
@@ -25,7 +26,11 @@
 
 from . import protocol as p
 
-_ROOM_KEYS = {"url", "room", "publisher", "streams"}
+_ROOM_KEYS = {"url", "room", "publisher", "timestamp_basis", "streams"}
+_BASES = {
+    "monotonic_us": p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US,
+    "unix_us": p.LiveKitTimestampBasis.PUBLISHER_UNIX_US,
+}
 _STREAM_KEYS = {"name", "track", "width", "height", "fps"}
 
 
@@ -53,6 +58,10 @@ def load_livekit_streams(path: Path) -> tuple[p.LiveKitCameraStream, ...]:
     raw_streams = room.get("streams")
     if not isinstance(raw_streams, list):
         raise ValueError("livekit.streams must be a list")
+    basis_name = room.get("timestamp_basis", "monotonic_us")
+    # A YAML list or mapping is unhashable, so check the type before the lookup.
+    if not isinstance(basis_name, str) or basis_name not in _BASES:
+        raise ValueError(f"livekit.timestamp_basis must be one of {sorted(_BASES)}")
     streams: list[p.LiveKitCameraStream] = []
     try:
         for index, raw in enumerate(raw_streams):
@@ -68,7 +77,7 @@ def load_livekit_streams(path: Path) -> tuple[p.LiveKitCameraStream, ...]:
                         "room": room.get("room"),
                         "publisher": room.get("publisher"),
                         "track": entry.get("track"),
-                        "timestamp_basis": int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+                        "timestamp_basis": int(_BASES[basis_name]),
                         "width": entry.get("width"),
                         "height": entry.get("height"),
                         "fps": entry.get("fps"),
diff --git a/examples/egocap/capture_server/capture_server/protocol.py b/examples/egocap/capture_server/capture_server/protocol.py
index 1794708d83..b6013e5661 100644
--- a/examples/egocap/capture_server/capture_server/protocol.py
+++ b/examples/egocap/capture_server/capture_server/protocol.py
@@ -202,10 +202,13 @@ class TimeUnit(IntEnum):
 
 
 class LiveKitTimestampBasis(IntEnum):
-    """What a LiveKit frame's ``user_timestamp_us`` means: the publisher host's monotonic clock in
-    microseconds, read when the frame is published. Not sensor exposure time and not this host's clock."""
+    """What a LiveKit frame's ``user_timestamp_us`` means. Neither is sensor exposure time."""
 
+    # The publisher host's monotonic clock in microseconds, read when the frame is published. Not on any clock
+    # this host can convert, so such a stream cannot be recorded against tracking.
     PUBLISHER_MONOTONIC_US = 1
+    # Unix time in microseconds on the publisher host, which is kept in step with this host's clock.
+    PUBLISHER_UNIX_US = 2
 
 
 class SampleTimeSemantics(IntEnum):
diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
index 82a563bf87..eb342b71d1 100644
--- a/examples/egocap/tests/backend/test_livekit_receiver.py
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -453,3 +453,173 @@ async def test_stop_before_start_is_harmless():
     rx = lr.LiveKitFrameReceiver([camera(1, "left")], TOKEN)
     await rx.stop()
     assert not rx.failed.is_set()
+
+
+# ---- next_frame_or_lost ----
+
+
+def _only_test_tasks() -> set:
+    return asyncio.all_tasks() - {asyncio.current_task()}
+
+
+async def test_queued_frames_are_drained_before_none(receiver):
+    track = subscribe(receiver)
+    track.push(event(1, frame_id=1))
+    track.push(event(2, frame_id=2))
+    await settle()
+    room_of(receiver).emit("track_unsubscribed", track, publication("left", track), participant())
+    first = await asyncio.wait_for(receiver.next_frame_or_lost(1), 1)
+    second = await asyncio.wait_for(receiver.next_frame_or_lost(1), 1)
+    assert (first.frame_id, second.frame_id) == (1, 2)
+    assert await asyncio.wait_for(receiver.next_frame_or_lost(1), 1) is None
+
+
+async def test_frame_is_returned_while_the_track_is_live(receiver):
+    track = subscribe(receiver)
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    assert not waiter.done()
+    track.push(event(5, frame_id=9))
+    assert (await asyncio.wait_for(waiter, 1)).frame_id == 9
+
+
+async def test_loss_while_waiting_returns_none(receiver):
+    track = subscribe(receiver)
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    assert not waiter.done()
+    room_of(receiver).emit("track_unsubscribed", track, publication("left", track), participant())
+    assert await asyncio.wait_for(waiter, 1) is None
+
+
+def _unsubscribe(rx, track):
+    room_of(rx).emit("track_unsubscribed", track, publication("left", track), participant())
+
+
+def _publisher_leaves(rx, track):
+    room_of(rx).emit("participant_disconnected", participant())
+
+
+def _room_disconnected(rx, track):
+    room_of(rx).emit("disconnected", "SOME_REASON")
+
+
+@pytest.mark.parametrize("lose", [_unsubscribe, _publisher_leaves, _room_disconnected])
+async def test_each_kind_of_loss_wakes_a_waiter_on_an_attached_stream(receiver, lose):
+    track = subscribe(receiver)
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    lose(receiver, track)
+    assert await asyncio.wait_for(waiter, 1) is None
+
+
+async def test_room_disconnect_marks_a_never_attached_stream_lost(receiver):
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(2))
+    await settle()
+    _room_disconnected(receiver, None)
+    assert await asyncio.wait_for(waiter, 1) is None
+
+
+async def test_unsubscribe_of_a_never_attached_stream_marks_it_lost(receiver):
+    track = FakeTrack()
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    _unsubscribe(receiver, track)
+    assert await asyncio.wait_for(waiter, 1) is None
+
+
+async def test_publisher_leaving_marks_a_never_attached_stream_lost(receiver):
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    _publisher_leaves(receiver, None)
+    assert await asyncio.wait_for(waiter, 1) is None
+
+
+async def test_republication_clears_the_lost_state(receiver):
+    track = subscribe(receiver)
+    _unsubscribe(receiver, track)
+    assert await asyncio.wait_for(receiver.next_frame_or_lost(1), 1) is None
+    again = subscribe(receiver)
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    assert not waiter.done()
+    again.push(event(4, frame_id=1))
+    assert (await asyncio.wait_for(waiter, 1)).frame_id == 1
+
+
+async def test_no_helper_tasks_are_left_after_returning(receiver):
+    track = subscribe(receiver)
+    await settle()
+    baseline = _only_test_tasks()
+    # Returned because of a frame.
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    track.push(event(1, frame_id=1))
+    await asyncio.wait_for(waiter, 1)
+    await settle()
+    assert _only_test_tasks() == baseline
+    # Returned because of the loss.
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    _unsubscribe(receiver, track)
+    await asyncio.wait_for(waiter, 1)
+    await settle()
+    assert _only_test_tasks() - baseline == set()
+
+
+async def test_cancelling_a_waiter_leaves_no_helper_tasks(receiver):
+    subscribe(receiver)
+    await settle()
+    baseline = _only_test_tasks()
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    waiter.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await waiter
+    await settle()
+    assert _only_test_tasks() == baseline
+
+
+async def test_publisher_leaving_before_any_track_marks_every_stream_lost(receiver):
+    waiters = [asyncio.ensure_future(receiver.next_frame_or_lost(i)) for i in (1, 2)]
+    await settle()
+    assert not any(w.done() for w in waiters)
+    _publisher_leaves(receiver, None)
+    assert [await asyncio.wait_for(w, 1) for w in waiters] == [None, None]
+
+
+async def test_a_different_participant_disconnecting_changes_nothing(receiver):
+    track = subscribe(receiver)
+    waiters = [asyncio.ensure_future(receiver.next_frame_or_lost(i)) for i in (1, 2)]
+    await settle()
+    room_of(receiver).emit("participant_disconnected", participant("intruder"))
+    await settle()
+    assert not any(w.done() for w in waiters)
+    assert receiver.counters[1].subscribed
+    track.push(event(3, frame_id=1))
+    assert (await asyncio.wait_for(waiters[0], 1)).frame_id == 1
+    waiters[1].cancel()
+
+
+async def test_feed_on_a_never_attached_stream_fails_when_the_publisher_leaves(monkeypatch):
+    from egocap_web.livekit_recording import LiveKitRecordingFeed
+
+    unix = p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
+    stream = camera(1, "left", timestamp_basis=unix)
+    rx = lr.LiveKitFrameReceiver([stream], TOKEN)
+    await rx.start()
+    reasons: list[str] = []
+    feed = LiveKitRecordingFeed(
+        rx, [stream], SimpleNamespace(offer=lambda item: True), {1: "src"}, on_failure=reasons.append
+    )
+    try:
+        feed.start()
+        await settle()
+        assert feed.failure is None
+        _publisher_leaves(rx, None)
+        await settle()
+        assert feed.failure == "cam1: the LiveKit track was lost"
+        assert reasons == [feed.failure]
+    finally:
+        await feed.stop()
+        await rx.stop()
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
new file mode 100644
index 0000000000..f4518f460f
--- /dev/null
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -0,0 +1,400 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""livekit_recording: Unix-to-monotonic mapping, frame-to-sample conversion and the per-stream feed."""
+
+from __future__ import annotations
+
+import asyncio
+
+import numpy as np
+import pytest
+
+from capture_server import protocol as p
+from egocap_web.livekit_receiver import ReceivedFrame
+from egocap_web.livekit_recording import (
+    LiveKitRecordingFeed,
+    MappedFrame,
+    UnixClockMap,
+    mapped_frame_to_samples,
+)
+from recording_service import PixelFormat
+
+UNIX = p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
+MONO = p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
+
+
+class FakeClocks:
+    """Scripted monotonic and Unix clocks; each read pops the next value (the last one repeats)."""
+
+    def __init__(self, monotonic: list[int], unix: list[int]) -> None:
+        self._mono, self._unix = list(monotonic), list(unix)
+        self.mono_reads = 0
+        self.unix_reads = 0
+
+    def monotonic_ns(self) -> int:
+        self.mono_reads += 1
+        return self._mono.pop(0) if len(self._mono) > 1 else self._mono[0]
+
+    def unix_ns(self) -> int:
+        self.unix_reads += 1
+        return self._unix.pop(0) if len(self._unix) > 1 else self._unix[0]
+
+
+def _map(clocks: FakeClocks) -> UnixClockMap:
+    return UnixClockMap(monotonic_ns=clocks.monotonic_ns, unix_ns=clocks.unix_ns)
+
+
+# --- UnixClockMap --------------------------------------------------------------
+
+
+def test_offset_is_midpoint_of_the_bracket_minus_the_unix_reading():
+    # Every attempt brackets a Unix reading of 5000 s between monotonic 100 s and 102 s: midpoint 101 s.
+    clocks = FakeClocks(
+        monotonic=[0] + [100_000_000_000, 102_000_000_000] * 3 + [103_000_000_000],
+        unix=[5_000_000_000_000],
+    )
+    mapper = _map(clocks)
+    assert mapper.monotonic_seconds(5_000_000_000) == pytest.approx(101.0)
+    assert mapper.monotonic_seconds(5_001_000_000) == pytest.approx(102.0)  # offset is reused, 1 s later
+
+
+def test_best_of_three_picks_the_shortest_span():
+    # Spans 4 s, 1 s, 2 s; the 1 s bracket is [20 s, 21 s] around unix 1000 s -> offset 20.5 - 1000.
+    clocks = FakeClocks(
+        monotonic=[
+            0,  # age check
+            0,
+            4_000_000_000,
+            20_000_000_000,
+            21_000_000_000,
+            30_000_000_000,
+            32_000_000_000,
+            32_000_000_000,  # stamp
+        ],
+        unix=[1_000_000_000_000, 1_000_000_000_000, 1_000_000_000_000],
+    )
+    mapper = _map(clocks)
+    assert mapper.monotonic_seconds(1_000_000_000) == pytest.approx(20.5)
+
+
+def test_pair_is_reused_within_one_second_without_remeasuring():
+    state = {"mono": 0}
+    reads = {"unix": 0}
+
+    def unix() -> int:
+        reads["unix"] += 1
+        return 100_000_000_000
+
+    mapper = UnixClockMap(monotonic_ns=lambda: state["mono"], unix_ns=unix)
+    assert mapper.monotonic_seconds(100_000_000) == pytest.approx(0.0)  # offset -100 s
+    assert reads["unix"] == 3
+    state["mono"] = 500_000_000
+    assert mapper.monotonic_seconds(101_000_000) == pytest.approx(1.0)
+    state["mono"] = 1_000_000_000  # age exactly 1 s: still reused
+    assert mapper.monotonic_seconds(102_000_000) == pytest.approx(2.0)
+    assert reads["unix"] == 3
+
+
+def test_pair_is_remeasured_after_one_second():
+    state = {"mono": 0, "unix": 1_000_000_000_000}
+    reads = {"unix": 0}
+
+    def mono() -> int:
+        return state["mono"]
+
+    def unix() -> int:
+        reads["unix"] += 1
+        return state["unix"]
+
+    mapper = UnixClockMap(monotonic_ns=mono, unix_ns=unix)
+    assert mapper.monotonic_seconds(1_000_000_000) == pytest.approx(0.0)
+    assert reads["unix"] == 3
+    state["mono"] = 1_000_000_001  # just over one second
+    mapper.monotonic_seconds(1_000_000_000)
+    assert reads["unix"] == 6
+
+
+def test_stepped_unix_clock_is_picked_up_at_the_next_refresh():
+    state = {"mono": 0, "unix": 1_000_000_000_000}
+
+    def mono() -> int:
+        return state["mono"]
+
+    def unix() -> int:
+        return state["unix"]
+
+    mapper = UnixClockMap(monotonic_ns=mono, unix_ns=unix)
+    assert mapper.monotonic_seconds(1_000_000_000) == pytest.approx(0.0)
+    state["unix"] += 3_000_000_000  # the Unix clock steps forward 3 s
+    state["mono"] = 500_000_000
+    assert mapper.monotonic_seconds(1_000_000_000) == pytest.approx(0.0)  # not yet noticed
+    state["mono"] = 2_000_000_000
+    # Unix now reads 1003 s at monotonic 2 s: unix 1000 s is 3 s before that, i.e. -1 s.
+    assert mapper.monotonic_seconds(1_000_000_000) == pytest.approx(-1.0)
+
+
+def test_default_clocks_map_now_to_about_now():
+    import time
+
+    mapped = UnixClockMap().monotonic_seconds(time.time_ns() // 1000)
+    assert mapped == pytest.approx(time.monotonic(), abs=0.05)
+
+
+# --- mapped_frame_to_samples ---------------------------------------------------
+
+
+def _received(
+    stream_id: int = 16, user_ts: int | None = 1_000_000, receive_ns: int = 2_500_000_000
+) -> ReceivedFrame:
+    return ReceivedFrame(
+        stream_id=stream_id,
+        image=np.zeros((4, 6, 3), dtype=np.uint8),
+        receive_time_ns=receive_ns,
+        transport_timestamp_us=7,
+        user_timestamp_us=user_ts,
+        frame_id=None,
+        user_data=None,
+    )
+
+
+def test_mapped_frame_becomes_one_rgb8_sample_in_seconds():
+    frame = _received()
+    samples = mapped_frame_to_samples(MappedFrame(frame, "head_left", 1.25))
+    assert len(samples) == 1
+    sample = samples[0]
+    assert sample.source == "head_left"
+    assert sample.pixel_format == PixelFormat.RGB8
+    assert sample.capture_time == 1.25
+    assert sample.receive_time == pytest.approx(2.5)
+    assert sample.image is frame.image
+
+
+def test_mapped_frame_image_is_the_received_image():
+    frame = _received()
+    assert MappedFrame(frame, "s", 0.0).image is frame.image
+
+
+# --- LiveKitRecordingFeed ------------------------------------------------------
+
+
+def _stream(stream_id: int, name: str, basis=UNIX) -> p.LiveKitCameraStream:
+    return p.LiveKitCameraStream(
+        stream_id=stream_id,
+        name=name,
+        url="wss://lk",
+        room="r",
+        publisher="o",
+        track=f"t{stream_id}",
+        timestamp_basis=basis,
+    )
+
+
+class FakeReceiver:
+    """Per-stream scripted frames; an exhausted stream blocks like a quiet camera, or reports loss."""
+
+    def __init__(self, frames: dict[int, list[ReceivedFrame]]) -> None:
+        self.frames = {k: list(v) for k, v in frames.items()}
+        self.calls: list[int] = []
+        self.gates: dict[int, asyncio.Event] = {}
+        self.lost: set[int] = set()
+
+    async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
+        self.calls.append(stream_id)
+        gate = self.gates.get(stream_id)
+        if gate is not None:
+            await gate.wait()
+        if self.frames.get(stream_id):
+            return self.frames[stream_id].pop(0)
+        if stream_id in self.lost:
+            return None
+        await asyncio.Event().wait()
+        raise AssertionError("unreachable")
+
+
+class FakeIngress:
+    """Records offers; answers each with the next scripted value (True once the script runs out)."""
+
+    def __init__(self, answers: list[bool] | None = None) -> None:
+        self.offered: list[MappedFrame] = []
+        self._answers = list(answers or [])
+
+    def offer(self, item: MappedFrame) -> bool:
+        self.offered.append(item)
+        return self._answers.pop(0) if self._answers else True
+
+
+class FixedMap(UnixClockMap):
+    """Maps unix microseconds to ``us / 1e6 + 10`` seconds."""
+
+    def monotonic_seconds(self, unix_us: int) -> float:
+        return unix_us / 1e6 + 10.0
+
+
+async def _settle(times: int = 10) -> None:
+    for _ in range(times):
+        await asyncio.sleep(0)
+
+
+def _feed(receiver, streams, ingress, names=None, **kw) -> LiveKitRecordingFeed:
+    names = names if names is not None else {s.stream_id: f"src{s.stream_id}" for s in streams}
+    return LiveKitRecordingFeed(receiver, streams, ingress, names, clock_map=FixedMap(), **kw)
+
+
+async def test_unix_stream_frames_are_offered_with_source_and_mapped_capture_time():
+    streams = [_stream(16, "Head left")]
+    receiver = FakeReceiver({16: [_received(16, 1_000_000), _received(16, 2_000_000)]})
+    ingress = FakeIngress()
+    feed = _feed(receiver, streams, ingress, {16: "head_left"})
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert [m.source for m in ingress.offered] == ["head_left", "head_left"]
+    assert [m.capture_time for m in ingress.offered] == [11.0, 12.0]
+    assert feed.failure is None
+
+
+async def test_monotonic_stream_fails_at_once_and_never_offers():
+    reasons: list[str] = []
+    streams = [_stream(16, "Head left", MONO)]
+    receiver = FakeReceiver({16: [_received(16)]})
+    ingress = FakeIngress()
+    feed = _feed(receiver, streams, ingress, on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert ingress.offered == []
+    assert receiver.calls == []  # refused before any frame was taken
+    assert feed.failure is not None
+    assert "Head left" in feed.failure
+    assert "own clock" in feed.failure
+    assert reasons == [feed.failure]
+
+
+async def test_frame_without_publisher_timestamp_fails():
+    reasons: list[str] = []
+    streams = [_stream(16, "Head left")]
+    receiver = FakeReceiver({16: [_received(16, user_ts=None)]})
+    ingress = FakeIngress()
+    feed = _feed(receiver, streams, ingress, on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert ingress.offered == []
+    assert "without the publisher's capture timestamp" in feed.failure
+    assert reasons == [feed.failure]
+
+
+async def test_refusing_ingress_fails_and_stops_that_stream():
+    reasons: list[str] = []
+    streams = [_stream(16, "Head left")]
+    receiver = FakeReceiver({16: [_received(16, 1_000_000), _received(16, 2_000_000), _received(16, 3_000_000)]})
+    ingress = FakeIngress([True, False])
+    feed = _feed(receiver, streams, ingress, on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert len(ingress.offered) == 2  # the third frame is never taken
+    assert receiver.calls == [16, 16]
+    assert "no longer accepting" in feed.failure
+    assert reasons == [feed.failure]
+
+
+async def test_failure_is_reported_once_across_streams():
+    reasons: list[str] = []
+    streams = [_stream(16, "Head left", MONO), _stream(17, "Head right", MONO)]
+    feed = _feed(FakeReceiver({}), streams, FakeIngress(), on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert len(reasons) == 1
+    assert "Head left" in feed.failure  # the first reason is kept
+    assert "Head right" not in feed.failure
+
+
+async def test_failure_without_a_callback_is_still_stored():
+    feed = _feed(FakeReceiver({}), [_stream(16, "Head left", MONO)], FakeIngress())
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert feed.failure is not None
+
+
+def test_missing_source_names_raise_value_error():
+    streams = [_stream(16, "Head left"), _stream(17, "Head right")]
+    with pytest.raises(ValueError, match="Head right"):
+        LiveKitRecordingFeed(FakeReceiver({}), streams, FakeIngress(), {16: "a"})
+
+
+async def test_stop_leaves_no_running_tasks():
+    streams = [_stream(16, "Head left"), _stream(17, "Head right")]
+    feed = _feed(FakeReceiver({}), streams, FakeIngress())
+    before = asyncio.all_tasks()
+    feed.start()
+    await _settle()
+    assert len(asyncio.all_tasks() - before) == 2  # both blocked on a quiet camera
+    await feed.stop()
+    assert asyncio.all_tasks() == before
+    await feed.stop()  # idempotent
+
+
+async def test_stop_before_start_is_a_no_op():
+    feed = _feed(FakeReceiver({}), [_stream(16, "Head left")], FakeIngress())
+    await feed.stop()
+    assert feed.failure is None
+
+
+async def test_streams_are_independent():
+    streams = [_stream(16, "Head left"), _stream(17, "Head right")]
+    receiver = FakeReceiver({16: [_received(16, 1_000_000)], 17: [_received(17, 2_000_000)]})
+    receiver.gates[16] = asyncio.Event()  # stream 16 is stuck waiting
+    ingress = FakeIngress()
+    feed = _feed(receiver, streams, ingress)
+    feed.start()
+    await _settle()
+    assert [m.source for m in ingress.offered] == ["src17"]
+    receiver.gates[16].set()
+    await _settle()
+    await feed.stop()
+    assert sorted(m.source for m in ingress.offered) == ["src16", "src17"]
+
+
+async def test_lost_track_fails_the_take_with_the_stream_name():
+    reasons: list[str] = []
+    receiver = FakeReceiver({})
+    receiver.lost.add(16)
+    feed = _feed(receiver, [_stream(16, "Head left")], FakeIngress(), on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert feed.failure == "Head left: the LiveKit track was lost"
+    assert reasons == [feed.failure]
+
+
+async def test_frames_queued_before_the_loss_are_all_offered_first():
+    receiver = FakeReceiver({16: [_received(16, 1_000_000), _received(16, 2_000_000), _received(16, 3_000_000)]})
+    receiver.lost.add(16)
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left")], ingress)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert [m.capture_time for m in ingress.offered] == [11.0, 12.0, 13.0]
+    assert "track was lost" in feed.failure
+
+
+async def test_a_stream_still_waiting_on_its_track_does_not_delay_another_that_is_flowing():
+    receiver = FakeReceiver({17: [_received(17, 1_000_000)]})
+    receiver.gates[16] = asyncio.Event()  # 16 is quiet, and will later be lost
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left"), _stream(17, "Head right")], ingress)
+    feed.start()
+    await _settle()
+    assert [m.source for m in ingress.offered] == ["src17"]
+    assert feed.failure is None
+    receiver.lost.add(16)
+    receiver.gates[16].set()
+    await _settle()
+    await feed.stop()
+    assert feed.failure == "Head left: the LiveKit track was lost"
diff --git a/examples/egocap/tests/backend/test_recording_adapter.py b/examples/egocap/tests/backend/test_recording_adapter.py
index d10f3607c4..861e45ffdd 100644
--- a/examples/egocap/tests/backend/test_recording_adapter.py
+++ b/examples/egocap/tests/backend/test_recording_adapter.py
@@ -23,10 +23,11 @@
 import pytest
 
 from capture_server import protocol as capture_protocol
-from capture_server.client import CaptureFrame
+from capture_server.client import CameraImage, CaptureFrame
 from egocap_web.recording_adapter import (
     RecordingAdapterError,
     RecordingIngress,
+    _raw_item_bytes,
     build_manus_glove_fields,
     build_pico_controller_fields,
     button_pressed,
@@ -583,3 +584,69 @@ async def run():
 def test_queue_bytes_must_be_positive():
     with pytest.raises(ValueError):
         RecordingIngress(queue_capacity=1, queue_bytes=0, submit=lambda s: None)
+
+
+# --- raw item sizing -----------------------------------------------------------
+
+
+class _DecodedFrame:
+    """Anything with an ``image`` ndarray, as livekit_recording.MappedFrame has."""
+
+    def __init__(self, image: np.ndarray) -> None:
+        self.image = image
+
+
+def test_raw_item_bytes_sizes_a_decoded_frame_by_its_pixels():
+    assert _raw_item_bytes(_DecodedFrame(np.zeros((10, 20, 3), dtype=np.uint8))) == 600  # type: ignore[arg-type]
+    assert _raw_item_bytes(_DecodedFrame(np.zeros((2, 2), dtype=np.uint16))) == 8  # type: ignore[arg-type]
+
+
+def test_raw_item_bytes_keeps_sizing_the_existing_types():
+    jpeg = CameraImage(
+        session_id="s", stream_id=1, sequence=0, capture_time_ns=0, receive_time_ns=0, name="c", jpeg=b"j" * 123
+    )
+    frame = CaptureFrame(
+        session_id="s",
+        description=None,
+        stream_id=0,
+        sequence=0,
+        capture_time_ns=0,
+        receive_time_ns=0,
+        payload=b"x" * 77,
+    )
+    assert _raw_item_bytes(jpeg) == 123
+    assert _raw_item_bytes(frame) == 77
+
+
+def test_decoded_frame_larger_than_the_byte_budget_overflows_the_ingress():
+    async def run():
+        ingress = RecordingIngress(
+            queue_capacity=100,
+            queue_bytes=1000,
+            submit=lambda s: SubmissionResult(SubmissionStatus.ACCEPTED, s.source, None),
+            convert=lambda raw: [_numeric_sample(1)],
+        )
+        small = _DecodedFrame(np.zeros((10, 10, 3), dtype=np.uint8))  # 300 bytes
+        big = _DecodedFrame(np.zeros((20, 20, 3), dtype=np.uint8))  # 1200 bytes, over the budget on its own
+        assert ingress.offer(big) is False  # type: ignore[arg-type]
+        assert "byte budget" in ingress.failure
+        # A failed ingress admits nothing more, even a frame that would have fit.
+        assert ingress.offer(small) is False  # type: ignore[arg-type]
+
+    asyncio.run(run())
+
+
+def test_decoded_frames_within_the_budget_are_queued():
+    async def run():
+        ingress = RecordingIngress(
+            queue_capacity=100,
+            queue_bytes=1000,
+            submit=lambda s: SubmissionResult(SubmissionStatus.ACCEPTED, s.source, None),
+            convert=lambda raw: [_numeric_sample(1)],
+        )
+        frame = _DecodedFrame(np.zeros((10, 10, 3), dtype=np.uint8))
+        assert [ingress.offer(frame) for _ in range(3)] == [True, True, True]  # type: ignore[arg-type]
+        assert ingress.offer(frame) is False  # type: ignore[arg-type]  # 1200 > 1000
+        assert ingress.failure is not None
+
+    asyncio.run(run())
diff --git a/examples/egocap/tests/capture_server/test_livekit_streams.py b/examples/egocap/tests/capture_server/test_livekit_streams.py
index 28ed599f22..74eb5592e5 100644
--- a/examples/egocap/tests/capture_server/test_livekit_streams.py
+++ b/examples/egocap/tests/capture_server/test_livekit_streams.py
@@ -124,7 +124,8 @@ def test_session_init_still_rejects_unknown_keys():
         {"url": "https://lk.example"},
         {"url": "lk.example:7881"},
         {"url": "x" * 600},
-        {"timestamp_basis": 2},
+        {"timestamp_basis": 3},
+        {"timestamp_basis": 0},
         {"timestamp_basis": "1"},
         {"timestamp_basis": True},
         {"width": 0},
@@ -450,3 +451,54 @@ async def test_cli_serves_the_streams_from_the_file(tmp_path, unused_tcp_port):
     finally:
         proc.terminate()
         proc.wait(timeout=10)
+
+
+# ---------------------------------------------------------------------------
+# Timestamp basis.
+# ---------------------------------------------------------------------------
+
+
+def test_timestamp_basis_values_are_wire_stable():
+    assert int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US) == 1
+    assert int(p.LiveKitTimestampBasis.PUBLISHER_UNIX_US) == 2
+
+
+def test_unix_basis_round_trips_through_json():
+    stream = _stream(timestamp_basis=2)
+    assert stream.timestamp_basis == p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
+    assert p.LiveKitCameraStream.from_json(stream.to_json()) == stream
+
+
+@pytest.mark.parametrize(
+    ("basis_line", "expected"),
+    [
+        ("", p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+        ("timestamp_basis: monotonic_us,", p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
+        ("timestamp_basis: unix_us,", p.LiveKitTimestampBasis.PUBLISHER_UNIX_US),
+    ],
+)
+def test_loader_puts_the_room_basis_in_every_stream(tmp_path, basis_line, expected):
+    text = (
+        f"livekit: {{url: wss://lk, room: r, publisher: o, {basis_line} "
+        "streams: [{name: A, track: t}, {name: B, track: u}]}\n"
+    )
+    streams = load_livekit_streams(_write(tmp_path, text))
+    assert [s.timestamp_basis for s in streams] == [expected, expected]
+
+
+@pytest.mark.parametrize(
+    "value",
+    [
+        "wall_clock",
+        "UNIX_US",
+        "2",
+        "''",
+        "null",
+        "[unix_us]",
+        "{a: 1}",
+    ],
+)
+def test_loader_rejects_an_unknown_basis(tmp_path, value):
+    text = f"livekit: {{url: wss://lk, room: r, publisher: o, timestamp_basis: {value}, streams: []}}\n"
+    with pytest.raises(ValueError, match="timestamp_basis"):
+        load_livekit_streams(_write(tmp_path, text))

From 323e08510025f78a55143dc1f06d0ee800572a22 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:23:37 -0800
Subject: [PATCH 07/37] egocap: add a standalone process that emulates the
 Orin's LiveKit publishing

tools/livekit_orin_emulator.py joins a LiveKit room with a token file and
publishes synthetic camera tracks named like the native sender's, with the
same per-frame metadata (application timestamp, frame id, raw capture
counter in user data). It lets the PC side be developed and tested without
a Jetson. It uses the SDK's software encoder, so it does not exercise the
Jetson hardware encoder or the real sender's pacing, and it was not run
against a LiveKit server.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  16 +
 .../tests/tools/test_livekit_orin_emulator.py | 197 +++++++++++++
 .../egocap/tools/livekit_orin_emulator.py     | 279 ++++++++++++++++++
 3 files changed, 492 insertions(+)
 create mode 100644 examples/egocap/tests/tools/test_livekit_orin_emulator.py
 create mode 100644 examples/egocap/tools/livekit_orin_emulator.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index e3e020c908..178721fdae 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -92,3 +92,19 @@ connection is down; the page reconnects on its own.
 | Tiles never leave "Connecting" | The `url` is reachable from the browser; `wss://` certificate trusted; signalling and media ports open. |
 | Connected, tile stays "Waiting for camera" | The publisher's token room and identity match `room` and `publisher`; `livekit=` names match `track`. |
 | "Waiting for video" or black picture | The browser may not support the encoder's H.264 profile; check the browser console. |
+
+## 5. No Orin: the emulator
+
+`tools/livekit_orin_emulator.py` publishes test-pattern tracks with the same per-frame metadata (`user_timestamp`,
+`frame_id`, 8-byte little-endian capture counter) in place of the Orin. It uses the SDK's software encoder, so it
+exercises the PC side and the metadata contract but not the Jetson hardware encoder, its H.264 profile or the real
+sender's pacing.
+
+```bash
+uv run python tools/livekit_orin_emulator.py \
+  --livekit-url=wss://LIVEKIT_HOST --livekit-token-file=join.token \
+  --add-stream=sensor=0,livekit=sensing-left --add-stream=sensor=1,livekit=sensing-right \
+  --width=1280 --height=720 --fps=30 --timestamp-basis=unix_us
+```
+
+Use `--timestamp-basis=monotonic_us` to send what the current native sender sends (not recordable).
diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
new file mode 100644
index 0000000000..5cd0a8a5c6
--- /dev/null
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -0,0 +1,197 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import asyncio
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+# tools/ is a plain scripts directory, not a package.
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "tools"))
+import livekit_orin_emulator as emu  # noqa: E402
+
+
+@pytest.fixture
+def token_file(tmp_path: Path) -> Path:
+    path = tmp_path / "join.token"
+    path.write_text("secret-token\n")
+    return path
+
+
+def argv(token_file: Path, *extra: str) -> list[str]:
+    return ["--livekit-url=ws://x", f"--livekit-token-file={token_file}", *extra]
+
+
+def test_parse_valid_streams_and_defaults(token_file):
+    args = emu.parse_args(
+        argv(token_file, "--add-stream=sensor=0,livekit=left", "--add-stream=sensor=1,livekit=right")
+    )
+    assert args.streams == [emu.StreamSpec(0, "left"), emu.StreamSpec(1, "right")]
+    assert args.token == "secret-token"
+    assert (args.width, args.height, args.fps, args.timestamp_basis) == (1280, 720, 30.0, "unix_us")
+
+
+@pytest.mark.parametrize(
+    "bad",
+    ["sensor=0", "livekit=a", "sensor=x,livekit=a", "sensor=0,livekit=", "sensor=0,livekit=a,extra=1", "nonsense"],
+)
+def test_invalid_stream_is_rejected(token_file, bad):
+    with pytest.raises(SystemExit):
+        emu.parse_args(argv(token_file, f"--add-stream={bad}"))
+
+
+@pytest.mark.parametrize(
+    "streams",
+    [["sensor=0,livekit=a", "sensor=0,livekit=b"], ["sensor=0,livekit=a", "sensor=1,livekit=a"]],
+)
+def test_duplicate_sensor_or_track_is_rejected(token_file, streams):
+    with pytest.raises(SystemExit):
+        emu.parse_args(argv(token_file, *[f"--add-stream={s}" for s in streams]))
+
+
+def test_missing_or_empty_token_file_is_rejected(tmp_path, token_file):
+    stream = "--add-stream=sensor=0,livekit=a"
+    with pytest.raises(SystemExit):
+        emu.parse_args(argv(tmp_path / "absent", stream))
+    empty = tmp_path / "empty"
+    empty.write_text("\n")
+    with pytest.raises(SystemExit):
+        emu.parse_args(argv(empty, stream))
+
+
+@pytest.mark.parametrize("extra", ["--timestamp-basis=bogus", "--fps=0", "--width=1", "--height=0"])
+def test_bad_options_are_rejected(token_file, extra):
+    with pytest.raises(SystemExit):
+        emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", extra))
+
+
+def test_user_timestamp_basis(monkeypatch):
+    monkeypatch.setattr(emu.time, "time_ns", lambda: 5_000_000)
+    monkeypatch.setattr(emu.time, "monotonic_ns", lambda: 9_000_000)
+    assert emu.user_timestamp_us("unix_us") == 5_000
+    assert emu.user_timestamp_us("monotonic_us") == 9_000
+
+
+def test_metadata_fields_and_little_endian_user_data():
+    meta = emu.build_metadata(7, 0x0102030405060708, 123)
+    assert (meta.user_timestamp, meta.frame_id) == (123, 7)
+    assert bytes(meta.user_data) == bytes([8, 7, 6, 5, 4, 3, 2, 1])
+
+
+def test_pattern_shape_dtype_and_change_over_time():
+    first = emu.make_pattern(64, 48, 0, 1)
+    assert first.shape == (48, 64, 4) and first.dtype == np.uint8
+    assert not np.array_equal(first, emu.make_pattern(64, 48, 0, 2))
+    assert not np.array_equal(first, emu.make_pattern(64, 48, 1, 1))
+
+
+class FakeSource:
+    """Records captured frames and stops the run after a fixed number."""
+
+    def __init__(self, stop, limit=None):
+        self.stop, self.limit, self.calls, self.closed = stop, limit, [], False
+
+    def capture_frame(self, frame, *, timestamp_us, metadata):
+        self.calls.append((frame, timestamp_us, metadata))
+        if self.limit and len(self.calls) >= self.limit:
+            self.stop.set()
+
+    async def aclose(self):
+        self.closed = True
+
+
+@pytest.fixture
+def fake_rtc(monkeypatch):
+    """Replaces the SDK with recorders so no server is needed."""
+    log = SimpleNamespace(published=[], unpublished=[], disconnected=False, sources=[], stop=None)
+
+    class Participant:
+        async def publish_track(self, track, options):
+            log.published.append(track)
+            return SimpleNamespace(sid=f"sid-{track[0]}")
+
+        async def unpublish_track(self, sid):
+            log.unpublished.append(sid)
+
+    class Room:
+        local_participant = Participant()
+
+        async def connect(self, url, token):
+            log.connected = (url, token)
+
+        async def disconnect(self):
+            log.disconnected = True
+
+    def make_source(width, height):
+        src = FakeSource(log.stop, limit=3)
+        log.sources.append(src)
+        return src
+
+    fake = SimpleNamespace(
+        Room=Room,
+        VideoSource=make_source,
+        LocalVideoTrack=SimpleNamespace(create_video_track=lambda name, source: (name, source)),
+        VideoFrame=lambda w, h, t, data: SimpleNamespace(width=w, height=h, data=data),
+        VideoBufferType=SimpleNamespace(RGBA=1),
+        TrackPublishOptions=lambda **kw: kw,
+        TrackSource=SimpleNamespace(SOURCE_CAMERA=2),
+        FrameMetadata=emu.rtc.FrameMetadata,
+    )
+    monkeypatch.setattr(emu, "rtc", fake)
+    return log
+
+
+async def test_run_publishes_paces_and_shuts_down_cleanly(token_file, fake_rtc):
+    args = emu.parse_args(
+        argv(token_file, "--add-stream=sensor=0,livekit=a", "--add-stream=sensor=1,livekit=b", "--fps=200")
+    )
+    args.width, args.height = 48, 16
+    stop = asyncio.Event()
+    fake_rtc.stop = stop
+    await asyncio.wait_for(emu.run(args, stop), timeout=5)
+    # Every track is published by name and each source stops at its own limit or on shutdown.
+    assert [t[0] for t in fake_rtc.published] == ["a", "b"]
+    assert fake_rtc.connected == ("ws://x", "secret-token")
+    ids = [m.frame_id for _, _, m in fake_rtc.sources[0].calls]
+    assert ids == list(range(1, len(ids) + 1)) and len(ids) >= 1
+    # Cleanup happened: unpublished, closed, disconnected.
+    assert fake_rtc.unpublished == ["sid-a", "sid-b"]
+    assert all(s.closed for s in fake_rtc.sources) and fake_rtc.disconnected
+
+
+async def test_publish_stream_is_paced_by_fps(token_file, fake_rtc):
+    args = emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", "--fps=50"))
+    args.width, args.height = 48, 16
+    stop = asyncio.Event()
+    source = FakeSource(stop, limit=6)
+    counters = emu.Counters({"a": 0})
+    loop = asyncio.get_running_loop()
+    start = loop.time()
+    await emu.publish_stream(source, emu.StreamSpec(0, "a"), args, stop, counters)
+    elapsed = loop.time() - start
+    # Six frames at 50 fps leave five 20 ms gaps before the stop is noticed.
+    assert elapsed >= 0.09
+    assert counters.sent["a"] == 6
+
+
+async def test_stats_print_until_stopped(capsys, monkeypatch):
+    monkeypatch.setattr(emu, "STATS_INTERVAL_S", 0.01)
+    stop = asyncio.Event()
+    counters = emu.Counters({"a": 3})
+    task = asyncio.create_task(emu.report_stats(stop, counters))
+    await asyncio.sleep(0.05)
+    stop.set()
+    await task
+    assert "a=3" in capsys.readouterr().out
+
+
+def test_banner_never_shows_token(token_file, capsys):
+    emu.print_banner(emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a")))
+    out = capsys.readouterr().out
+    assert "secret-token" not in out and "a" in out
diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
new file mode 100644
index 0000000000..c34f4aa811
--- /dev/null
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -0,0 +1,279 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Stands in for the Orin's LiveKit publisher so the PC side can be developed without a Jetson.
+
+It joins a room with a token file and publishes one test-pattern video track per ``--add-stream``, with the
+per-frame metadata the real ``camera_plugin_sensing`` sender attaches: ``user_timestamp`` (microseconds),
+``frame_id`` (from 1 per track) and 8 bytes of little-endian ``user_data`` holding the sensor's raw capture
+counter. Video goes through the SDK's software encoder, so this exercises the PC side and the metadata contract,
+not the Jetson hardware encoder, its H.264 profile or the real sender's pacing.
+
+The top half of the file is pure (argument parsing, metadata, pattern); the bottom half publishes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import contextlib
+import signal
+import sys
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+from livekit import rtc
+
+#: Seconds between periodic stats lines.
+STATS_INTERVAL_S = 5.0
+#: Width of the frame-counter strip, in bits (one coloured block per bit).
+_COUNTER_BITS = 24
+
+
+@dataclass(frozen=True)
+class StreamSpec:
+    """One published track: which sensor it imitates and the track name consumers look for."""
+
+    sensor: int
+    name: str
+
+
+# --- Pure helpers -------------------------------------------------------------------------------------------
+
+
+def parse_stream(text: str) -> StreamSpec:
+    """Parses ``sensor=N,livekit=NAME`` (the native sender's ``--add-stream`` spelling)."""
+    # Split into key=value pairs; anything malformed is a usage error, not a crash.
+    try:
+        fields = dict(part.split("=", 1) for part in text.split(","))
+        sensor = int(fields.pop("sensor"))
+        name = fields.pop("livekit")
+    except (ValueError, KeyError):
+        raise argparse.ArgumentTypeError(f"expected sensor=N,livekit=NAME, got {text!r}") from None
+    # Unknown keys or empty names would silently publish the wrong thing.
+    if fields or not name or sensor < 0:
+        raise argparse.ArgumentTypeError(f"expected sensor=N,livekit=NAME, got {text!r}")
+    return StreamSpec(sensor, name)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Builds the command line, mirroring the native sender's option spelling."""
+    parser = argparse.ArgumentParser(description="Emulate the Orin's LiveKit camera publisher.")
+    parser.add_argument("--livekit-url", required=True, help="LiveKit server URL (ws:// or wss://)")
+    parser.add_argument("--livekit-token-file", required=True, type=Path, help="file holding the join token")
+    parser.add_argument(
+        "--add-stream",
+        action="append",
+        required=True,
+        type=parse_stream,
+        dest="streams",
+        metavar="sensor=N,livekit=NAME",
+        help="publish a track named NAME imitating sensor N; repeatable",
+    )
+    parser.add_argument("--width", type=int, default=1280)
+    parser.add_argument("--height", type=int, default=720)
+    parser.add_argument("--fps", type=float, default=30.0)
+    parser.add_argument(
+        "--timestamp-basis",
+        choices=("unix_us", "monotonic_us"),
+        default="unix_us",
+        help="clock user_timestamp carries: Unix time (recordable) or this host's monotonic time (not recordable)",
+    )
+    return parser
+
+
+def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
+    """Parses and validates the command line; exits with a usage error on any invalid combination."""
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    # A sensor or track name published twice would collide in the room.
+    sensors = [s.sensor for s in args.streams]
+    names = [s.name for s in args.streams]
+    if len(set(sensors)) != len(sensors):
+        parser.error("duplicate sensor in --add-stream")
+    if len(set(names)) != len(names):
+        parser.error("duplicate livekit track name in --add-stream")
+    # Sizes and rate must be positive or the pacing loop and the pattern are meaningless.
+    if args.width < _COUNTER_BITS or args.height < 1 or args.fps <= 0:
+        parser.error(f"--width must be at least {_COUNTER_BITS}, --height at least 1 and --fps positive")
+    # Fail now, not after connecting, on a token file that cannot be read; the token itself is never printed.
+    try:
+        args.token = args.livekit_token_file.read_text().strip()
+    except OSError as exc:
+        parser.error(f"cannot read --livekit-token-file: {exc.strerror}")
+    if not args.token:
+        parser.error("--livekit-token-file is empty")
+    return args
+
+
+def user_timestamp_us(basis: str) -> int:
+    """Returns now in microseconds on the chosen clock (``unix_us`` or ``monotonic_us``)."""
+    ns = time.time_ns() if basis == "unix_us" else time.monotonic_ns()
+    return ns // 1000
+
+
+def build_metadata(frame_id: int, capture_counter_ns: int, timestamp_us: int) -> rtc.FrameMetadata:
+    """Builds the per-frame metadata exactly as the native sender does.
+
+    ``user_data`` is the capture counter as 8 little-endian bytes (``frame_id`` and ``user_timestamp`` are plain
+    integers).
+    """
+    return rtc.FrameMetadata(
+        user_timestamp=timestamp_us,
+        frame_id=frame_id,
+        user_data=capture_counter_ns.to_bytes(8, "little"),
+    )
+
+
+def make_pattern(width: int, height: int, sensor: int, frame_id: int) -> np.ndarray:
+    """Returns an RGBA frame: a per-sensor colour ramp, a moving bar, and the frame id as bit blocks on top.
+
+    The bit strip lets a human or a script read the frame id off the video; the moving bar makes freezes visible.
+    """
+    frame = np.empty((height, width, 4), np.uint8)
+    # A horizontal ramp tinted by sensor so different cameras are told apart at a glance.
+    ramp = np.linspace(40, 200, width, dtype=np.uint8)
+    frame[..., 0] = ramp
+    frame[..., 1] = (sensor * 70) % 200 + 40
+    frame[..., 2] = ramp[::-1]
+    frame[..., 3] = 255
+    # The bar advances every frame, so consecutive frames always differ.
+    bar_x = (frame_id * 8) % width
+    frame[:, bar_x : bar_x + 8, :3] = 255
+    # Frame id bits, most significant first, as white/black blocks across the top.
+    block = width // _COUNTER_BITS
+    strip = max(1, min(height, height // 8))
+    for i in range(_COUNTER_BITS):
+        bit = (frame_id >> (_COUNTER_BITS - 1 - i)) & 1
+        frame[:strip, i * block : (i + 1) * block, :3] = 255 if bit else 0
+    return frame
+
+
+# --- Publishing ---------------------------------------------------------------------------------------------
+
+
+@dataclass
+class Counters:
+    """Frames sent per track name, for the stats line."""
+
+    sent: dict[str, int]
+
+
+async def publish_stream(
+    source: rtc.VideoSource,
+    spec: StreamSpec,
+    args: argparse.Namespace,
+    stop: asyncio.Event,
+    counters: Counters,
+    capture_clock: Callable[[], int] = time.monotonic_ns,
+) -> None:
+    """Sends frames for one track at ``--fps`` until ``stop`` is set.
+
+    Deadlines are start + n*period rather than sleep(period), so encode time and loop jitter do not accumulate
+    into drift. After a stall longer than a period the schedule restarts from now instead of bursting to catch up.
+    """
+    period = 1.0 / args.fps
+    loop = asyncio.get_running_loop()
+    deadline = loop.time()
+    frame_id = 0
+    while not stop.is_set():
+        frame_id += 1
+        # The raw capture counter is taken first, as the sensor would stamp it before encoding.
+        capture_ns = capture_clock()
+        pixels = make_pattern(args.width, args.height, spec.sensor, frame_id)
+        frame = rtc.VideoFrame(args.width, args.height, rtc.VideoBufferType.RGBA, pixels.tobytes())
+        timestamp_us = user_timestamp_us(args.timestamp_basis)
+        source.capture_frame(
+            frame,
+            timestamp_us=timestamp_us,
+            metadata=build_metadata(frame_id, capture_ns, timestamp_us),
+        )
+        counters.sent[spec.name] = frame_id
+        # Wait for the next slot, but wake at once on shutdown.
+        deadline += period
+        delay = deadline - loop.time()
+        if delay < -period:
+            deadline = loop.time()
+            delay = 0.0
+        with contextlib.suppress(asyncio.TimeoutError):
+            await asyncio.wait_for(stop.wait(), timeout=max(delay, 0.0))
+
+
+async def report_stats(stop: asyncio.Event, counters: Counters) -> None:
+    """Prints frames sent per track every ``STATS_INTERVAL_S`` until ``stop`` is set."""
+    while not stop.is_set():
+        with contextlib.suppress(asyncio.TimeoutError):
+            await asyncio.wait_for(stop.wait(), timeout=STATS_INTERVAL_S)
+        # Counters are cumulative, so a stalled track is visible as a number that stops moving.
+        print("sent: " + ", ".join(f"{n}={c}" for n, c in counters.sent.items()), flush=True)
+
+
+async def run(args: argparse.Namespace, stop: asyncio.Event) -> None:
+    """Joins the room, publishes every stream until ``stop`` is set, then unpublishes and disconnects."""
+    room = rtc.Room()
+    await room.connect(args.livekit_url, args.token)
+    counters = Counters({s.name: 0 for s in args.streams})
+    sources: list[rtc.VideoSource] = []
+    publications = []
+    tasks: list[asyncio.Task] = []
+    try:
+        # One source and one published track per stream, named as the PC side expects.
+        for spec in args.streams:
+            source = rtc.VideoSource(args.width, args.height)
+            sources.append(source)
+            track = rtc.LocalVideoTrack.create_video_track(spec.name, source)
+            options = rtc.TrackPublishOptions(source=rtc.TrackSource.SOURCE_CAMERA)
+            publications.append(await room.local_participant.publish_track(track, options))
+            tasks.append(asyncio.create_task(publish_stream(source, spec, args, stop, counters)))
+        tasks.append(asyncio.create_task(report_stats(stop, counters)))
+        # A failed task would otherwise be noticed only at shutdown; stop everything as soon as one ends.
+        for task in tasks:
+            task.add_done_callback(lambda _t: stop.set())
+        await stop.wait()
+    finally:
+        # Cleanup runs on normal stop and on error, and must not leave the room half-joined.
+        stop.set()
+        results = await asyncio.gather(*tasks, return_exceptions=True)
+        for publication in publications:
+            await room.local_participant.unpublish_track(publication.sid)
+        for source in sources:
+            await source.aclose()
+        await room.disconnect()
+        for result in results:
+            if isinstance(result, Exception):
+                raise result
+
+
+def print_banner(args: argparse.Namespace) -> None:
+    """Prints what is being emulated, without the token."""
+    streams = ", ".join(f"sensor {s.sensor} -> {s.name}" for s in args.streams)
+    print(
+        f"Orin emulator: {args.livekit_url}  {args.width}x{args.height}@{args.fps:g}  "
+        f"timestamp basis {args.timestamp_basis}\n  streams: {streams}\n  software encoder; Ctrl-C to stop",
+        flush=True,
+    )
+
+
+async def amain(args: argparse.Namespace) -> None:
+    """Runs the emulator with SIGINT/SIGTERM wired to a clean shutdown."""
+    stop = asyncio.Event()
+    # Signals set the event so run() can unpublish and disconnect instead of being killed mid-session.
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+    print_banner(args)
+    await run(args, stop)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Command-line entry point."""
+    asyncio.run(amain(parse_args(argv)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

From 5385ea27539707687c24b5c2d34d4909919cf107 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:30:11 -0800
Subject: [PATCH 08/37] egocap: record LiveKit cameras with a capture-time
 stamp, through the take lifecycle

A LiveKit stream is recorded only when its timestamp basis is a sensor
capture time and its width, height and fps are configured; a
publication-time or monotonic stamp is refused before any frame, never
recorded as capture time. The coordinator joins the room before storage
opens (a missing, wrong-sized or silent camera refuses the start), clears
frames queued during preparation, feeds the take's ingress, and stops
feeding before the ingress is retired. The recorder uses its own
subscribe-only token. The emulator's timestamp choices and the runbook
follow the new bases.

Tests for the new code are still being written and run, and some of the
committed ones may not pass yet. Not exercised against a LiveKit server or
the Orin; the SIPL counter-to-host mapping that would make real Orin
streams recordable is not implemented.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  16 +-
 examples/egocap/backend/egocap_web/app.py     |  18 ++
 .../backend/egocap_web/livekit_receiver.py    |   6 +
 .../backend/egocap_web/livekit_recording.py   | 110 ++++++-
 .../backend/egocap_web/recording_session.py   |  32 ++-
 .../capture_server/livekit_streams.py         |   5 +-
 .../capture_server/capture_server/protocol.py |  14 +-
 .../backend/test_app_livekit_recording.py     |  69 +++++
 .../tests/backend/test_livekit_receiver.py    |  14 +-
 .../tests/backend/test_livekit_recording.py   |  32 ++-
 .../backend/test_livekit_recording_source.py  | 268 ++++++++++++++++++
 .../backend/test_recording_session_livekit.py | 141 +++++++++
 .../capture_server/test_livekit_streams.py    |  25 +-
 .../tests/tools/test_livekit_orin_emulator.py |  15 +-
 .../egocap/tools/livekit_orin_emulator.py     |  11 +-
 15 files changed, 732 insertions(+), 44 deletions(-)
 create mode 100644 examples/egocap/tests/backend/test_app_livekit_recording.py
 create mode 100644 examples/egocap/tests/backend/test_livekit_recording_source.py
 create mode 100644 examples/egocap/tests/backend/test_recording_session_livekit.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index 178721fdae..bdc7bc5363 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -17,8 +17,13 @@ Orin: SIPL -> hardware H.264 -> LiveKit publisher --> LiveKit server --> browser
 PC:   CaptureServer (--livekit-streams: where the streams are) -> egocap backend (list + viewer token)
 ```
 
-**The tiles are display-only for now and say so.** Saving these streams in a recording is planned but not built, so
-pressing Record does not save them.
+**Recording.** A stream is saved with a take only when its station entry gives `width`, `height` and `fps` and
+declares `timestamp_basis: capture_unix_us`, meaning the publisher stamps each frame with the mapped capture time of
+the sensor event. The native Orin sender stamps `processing_unix_us` (host time after capture and conversion), which
+is not a capture time, so its streams are shown in the browser but never recorded. The recorder joins the room itself
+(it needs the same `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`) and checks each stream's first frame against the
+configured size before a take starts. Camera and tracking alignment also assumes the backend and CaptureServer share
+one machine's clock, and that the publisher's clock is synchronised with it; neither is checked.
 
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.
@@ -104,7 +109,10 @@ sender's pacing.
 uv run python tools/livekit_orin_emulator.py \
   --livekit-url=wss://LIVEKIT_HOST --livekit-token-file=join.token \
   --add-stream=sensor=0,livekit=sensing-left --add-stream=sensor=1,livekit=sensing-right \
-  --width=1280 --height=720 --fps=30 --timestamp-basis=unix_us
+  --width=1280 --height=720 --fps=30 --timestamp-basis=capture_unix_us
 ```
 
-Use `--timestamp-basis=monotonic_us` to send what the current native sender sends (not recordable).
+`--timestamp-basis=processing_unix_us` declares what the current native sender sends: processing time, which is not
+a capture time and is not recorded. `capture_unix_us` (the default) is honest here because the emulator is the
+camera: it stamps the frame when it generates it. `monotonic_us` sends the publisher's monotonic clock, also not
+recordable.
diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index b284f23c2a..931bdff49b 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -37,7 +37,9 @@
 from .config import VisualizationConfig, config_from_env, visualization_from_env
 from .operator_settings import OperatorSettingsStore, operator_settings_path
 from .operator_settings import router as operator_settings_router
+from .livekit_preview import API_KEY_ENV, API_SECRET_ENV, subscriber_token
 from .livekit_preview import router as livekit_preview_router
+from .livekit_recording import LiveKitRecordingSource, recordable_livekit_streams
 from .preview_routes import router as preview_router
 from .recording_adapter import (
     MANUS_GLOVE_SPEC,
@@ -123,6 +125,14 @@ def _station_calibration_assets() -> tuple[CalibrationAsset, ...]:
     )
 
 
+def _recorder_livekit_token(room: str) -> str:
+    """A subscribe-only token for the recorder's own LiveKit connection, signed with the backend's key pair."""
+    api_key, api_secret = os.environ.get(API_KEY_ENV, ""), os.environ.get(API_SECRET_ENV, "")
+    if not api_key or not api_secret:
+        raise RuntimeError(f"{API_KEY_ENV} and {API_SECRET_ENV} must be set to record LiveKit video")
+    return subscriber_token(api_key=api_key, api_secret=api_secret, room=room, now=int(time.time()))
+
+
 def _recording_config_factory(monitor: CaptureStatusMonitor, station_label: str | None, output_root: Path):
     """Builds the real ``ServiceConfig`` lazily, read fresh each time the
     coordinator actually opens/reopens a session (not once at import time)
@@ -140,6 +150,10 @@ def factory() -> ServiceConfig:
         video_sources = tuple(
             VideoSourceSpec(cam.name, cam.width, cam.height, cam.fps, intrinsics=False)
             for cam in monitor.camera_descriptors
+        ) + tuple(
+            # LiveKit cameras with a capture-time stamp and a configured size are recorded like any camera.
+            VideoSourceSpec(s.name, s.width, s.height, s.fps, intrinsics=False)
+            for s in recordable_livekit_streams(monitor.native.started)
         )
         # A supported profile must record actual tracking AND the
         # selected cameras -- pico_controller and every configured camera
@@ -330,12 +344,16 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     # Catalogs the operator imports from the page sit beside that file, apart from the shipped ones.
     app.state.imported_task_file_root = operator_settings_file.parent / "taskfiles"
     monitor = CaptureStatusMonitor(config, backend_instance_id=str(uuid.uuid4()))
+    livekit_source = LiveKitRecordingSource(
+        lambda: recordable_livekit_streams(monitor.native.started), _recorder_livekit_token
+    )
     coordinator = RecordingSessionCoordinator(
         _recording_config_factory(monitor, config.station_label, recording_output_root),
         queue_capacity=_INGRESS_QUEUE_CAPACITY,
         queue_bytes=_INGRESS_QUEUE_BYTES,
         readiness_check=_recording_readiness_check(monitor, station_config_error),
         initial_context=initial_context,
+        livekit_source=livekit_source,
     )
     monitor.set_recording(coordinator)
     await monitor.start()
diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
index 98a039c81f..9c3f7a2057 100644
--- a/examples/egocap/backend/egocap_web/livekit_receiver.py
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -153,6 +153,12 @@ async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
                 if not task.done():
                     task.cancel()
 
+    def clear_queued(self) -> None:
+        """Drop every queued frame, so a take starts with frames acquired after it began."""
+        for queue in self._queues.values():
+            while not queue.empty():
+                queue.get_nowait()
+
     def pending(self, stream_id: int) -> int:
         """How many frames of ``stream_id`` are queued for the consumer."""
         return self._queues[stream_id].qsize()
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index 74af8eb03a..04349e7af4 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -4,11 +4,10 @@
 
 """Feeds received LiveKit camera frames into a take's recording ingress.
 
-A frame is recorded only when its capture time can be put on this machine's monotonic clock, the same clock the
-tracking samples use. That is possible when the publisher's application timestamp is Unix time on a host kept in
-step with this one (``PUBLISHER_UNIX_US``). A stream whose timestamp is on the publisher's own monotonic clock has
-no honest mapping, so the feed stops with that reason instead of recording a guessed time. Arrival time is never
-used as capture time.
+A frame is recorded only when its timestamp is a capture time (``SENSOR_CAPTURE_UNIX_US``), which can then be put
+on this machine's monotonic clock, the same clock the tracking samples use. A stream stamped with the publisher's
+monotonic clock or with its processing time is not a capture time, so the feed stops with that reason instead of
+recording a guessed one. Arrival time is never used as capture time.
 
 This assumes the backend runs on the machine whose monotonic clock CaptureServer reports: tracking times come from
 CaptureServer, and the two agree only when both processes share a clock.
@@ -22,6 +21,7 @@
 import time
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
+from typing import Any
 
 import numpy as np
 
@@ -44,8 +44,8 @@ class UnixClockMap:
     """Converts Unix-time microseconds to this process's monotonic seconds, from a recently measured pair.
 
     The pair is two clock readings taken back to back and refreshed about once a second, from the consumer's
-    thread and never from an SDK callback. Between refreshes the two clocks run at the same rate, so the offset
-    holds; a step of the Unix clock shows up at the next refresh.
+    thread and never from an SDK callback. It converts on this machine only: it does not detect a step of the
+    Unix clock, and says nothing about whether the publisher's clock agrees with this one.
     """
 
     def __init__(
@@ -164,10 +164,10 @@ async def _run(self, stream_id: int) -> None:
         """Feed one stream until the take fails or the feed is stopped."""
         stream = self._streams[stream_id]
         source = self._source_names[stream_id]
-        if stream.timestamp_basis is not p.LiveKitTimestampBasis.PUBLISHER_UNIX_US:
+        if stream.timestamp_basis is not p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US:
             # Checked before any frame arrives: this stream cannot become recordable by waiting.
             self._fail(
-                f"{stream.name}: timestamps are on the publisher's own clock and cannot be aligned with tracking"
+                f"{stream.name}: its timestamps are not a capture time, so it cannot be aligned with tracking"
             )
             return
         while self.failure is None:
@@ -184,3 +184,95 @@ async def _run(self, stream_id: int) -> None:
                 # The ingress refuses once it has failed or stopped; it reports its own reason.
                 self._fail(f"{stream.name}: the recording ingress is no longer accepting frames")
                 return
+
+
+def recordable_livekit_streams(started: Any) -> tuple[p.LiveKitCameraStream, ...]:
+    """The LiveKit streams of a started session that a recording may include.
+
+    A stream is recordable when its timestamps are a capture time and its geometry is configured: the recording
+    schema fixes each source's size and rate when the session opens. The rest remain preview-only.
+    """
+    if started is None:
+        return ()
+    return tuple(
+        s
+        for s in started.streams
+        if isinstance(s, p.LiveKitCameraStream)
+        and s.timestamp_basis is p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+        and None not in (s.width, s.height, s.fps)
+    )
+
+
+class LiveKitRecordingSource:
+    """The recorder's LiveKit video for one take: joins before the take, feeds during it, leaves after it.
+
+    The recordable streams are read when the take is prepared, because the session offers them only once it has
+    started. The first frame of each stream is checked against its configured size. The browser's own connection
+    is separate and unaffected.
+    """
+
+    def __init__(
+        self,
+        recordable_streams: Callable[[], Sequence[p.LiveKitCameraStream]],
+        make_token: Callable[[str], str],
+        *,
+        first_frame_timeout_s: float = 10.0,
+    ) -> None:
+        self._recordable_streams = recordable_streams
+        self._make_token = make_token
+        self._first_frame_timeout_s = first_frame_timeout_s
+        self._streams: tuple[p.LiveKitCameraStream, ...] = ()
+        self._receiver: LiveKitFrameReceiver | None = None
+        self._feed: LiveKitRecordingFeed | None = None
+
+    async def prepare(self) -> None:
+        """Join the room and wait for a usable first frame from every stream; raises if one never arrives.
+
+        Runs before the take's storage opens, so a missing camera fails the start instead of a half-written take.
+        Does nothing when the session offers no recordable stream.
+        """
+        self._streams = tuple(self._recordable_streams())
+        if not self._streams:
+            return
+        receiver = LiveKitFrameReceiver(self._streams, self._make_token(self._streams[0].room))
+        self._receiver = receiver
+        try:
+            await receiver.start()
+            for stream in self._streams:
+                frame = await asyncio.wait_for(
+                    receiver.next_frame_or_lost(stream.stream_id), self._first_frame_timeout_s
+                )
+                if frame is None:
+                    raise RuntimeError(f"{stream.name}: the LiveKit track was lost before recording started")
+                if frame.image.shape[:2] != (stream.height, stream.width):
+                    raise RuntimeError(
+                        f"{stream.name}: frames are {frame.image.shape[1]}x{frame.image.shape[0]}, "
+                        f"expected {stream.width}x{stream.height}"
+                    )
+        except asyncio.TimeoutError as exc:
+            await self.stop()
+            raise RuntimeError("a LiveKit stream sent no frame before the recording could start") from exc
+        except BaseException:
+            await self.stop()
+            raise
+
+    def start(self, ingress: RecordingIngress, on_failure: Callable[[str], None]) -> None:
+        """Begin feeding the take's ingress with frames acquired from now on."""
+        if self._receiver is None:
+            return
+        # Frames queued while storage was opening were acquired before the take started.
+        self._receiver.clear_queued()
+        source_names = {s.stream_id: s.name for s in self._streams}
+        self._feed = LiveKitRecordingFeed(
+            self._receiver, self._streams, ingress, source_names, on_failure=on_failure
+        )
+        self._feed.start()
+
+    async def stop(self) -> None:
+        """Stop feeding and leave the room. Safe to call at any point, including after a failed prepare."""
+        feed, receiver = self._feed, self._receiver
+        self._feed = self._receiver = None
+        if feed is not None:
+            await feed.stop()
+        if receiver is not None:
+            await receiver.stop()
diff --git a/examples/egocap/backend/egocap_web/recording_session.py b/examples/egocap/backend/egocap_web/recording_session.py
index 91a6fa5cc2..47a346ccd9 100644
--- a/examples/egocap/backend/egocap_web/recording_session.py
+++ b/examples/egocap/backend/egocap_web/recording_session.py
@@ -56,7 +56,7 @@
 from dataclasses import dataclass, replace
 from enum import Enum
 from functools import partial
-from typing import Any, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 from capture_server.client import CameraImage, CaptureFrame
 from egocap_web.recording_adapter import RecordingIngress, validate_tracking_descriptor
@@ -68,6 +68,9 @@
     RecordingPhase,
     ServiceConfig,
 )
+
+if TYPE_CHECKING:
+    from egocap_web.livekit_recording import LiveKitRecordingSource
 from recording_service import RecordingService as _RecordingService
 from recording_service import RecordingSnapshot as ServiceSnapshot
 
@@ -183,8 +186,12 @@ def __init__(
         queue_bytes: int | None = None,
         readiness_check: ReadinessCheck,
         initial_context: TaskContext | None = None,
+        livekit_source: LiveKitRecordingSource | None = None,
     ) -> None:
         self._config_factory = config_factory
+        # Optional LiveKit video for each take: joined before storage opens, fed after the ingress starts, left
+        # before the ingress is retired.
+        self._livekit_source = livekit_source
         self._queue_capacity = queue_capacity
         self._queue_bytes = queue_bytes
         self._readiness_check = readiness_check
@@ -408,6 +415,21 @@ async def _start_episode_impl(self, frozen_context: TaskContext) -> EpisodeInfo:
             # construct a new ingress over it; the old consumer thread
             # would be left with nothing owning it.
             raise CoordinatorBusyError("a previous take's ingress has not yet settled")
+        if self._livekit_source is None:
+            return await self._start_episode_with_storage(frozen_context)
+        # LiveKit video must be flowing before any storage is opened, so a missing camera fails the start itself.
+        try:
+            await self._livekit_source.prepare()
+        except Exception as exc:  # noqa: BLE001 -- any prepare failure is a refused start, never a half-open take
+            raise CoordinatorBusyError(f"LiveKit video is not ready: {exc}") from exc
+        try:
+            return await self._start_episode_with_storage(frozen_context)
+        except BaseException:
+            # A start that fails or is cancelled after prepare must not leave the room joined.
+            await self._livekit_source.stop()
+            raise
+
+    async def _start_episode_with_storage(self, frozen_context: TaskContext) -> EpisodeInfo:
         service = await self._open_storage_if_needed()
         # Recheck readiness/closing intent right after storage finished
         # opening -- the same "don't trust state from before the last
@@ -446,6 +468,11 @@ async def _start_episode_impl(self, frozen_context: TaskContext) -> EpisodeInfo:
         )
         await ingress.start()
         self._current_ingress = ingress
+        if self._livekit_source is not None:
+            # A feed failure settles the take through the same path as an ingress failure.
+            self._livekit_source.start(
+                ingress, lambda message: self._schedule_failure_settlement(service, episode_id, message)
+            )
         if self.on_episode_started is not None:
             self.on_episode_started()
         return episode
@@ -609,6 +636,9 @@ async def _retire_current_ingress(self) -> _IngressRetirement:
         ingress = self._current_ingress
         if ingress is None:
             return _IngressRetirement(settled=True, failure=None)
+        if self._livekit_source is not None:
+            # The producer stops first, so nothing is offered to an ingress that is draining.
+            await self._livekit_source.stop()
         settled = await ingress.stop()
         if not settled:
             return _IngressRetirement(
diff --git a/examples/egocap/capture_server/capture_server/livekit_streams.py b/examples/egocap/capture_server/capture_server/livekit_streams.py
index 89562cee49..77e182b828 100644
--- a/examples/egocap/capture_server/capture_server/livekit_streams.py
+++ b/examples/egocap/capture_server/capture_server/livekit_streams.py
@@ -13,7 +13,7 @@
       url: wss://LIVEKIT_HOST
       room: sensing-preview
       publisher: orin-sensing
-      timestamp_basis: unix_us   # optional; default monotonic_us (not recordable against tracking)
+      timestamp_basis: processing_unix_us   # what the publisher puts in the frame timestamp (see protocol.py)
       streams:
         - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
 """
@@ -29,7 +29,8 @@
 _ROOM_KEYS = {"url", "room", "publisher", "timestamp_basis", "streams"}
 _BASES = {
     "monotonic_us": p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US,
-    "unix_us": p.LiveKitTimestampBasis.PUBLISHER_UNIX_US,
+    "processing_unix_us": p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US,
+    "capture_unix_us": p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US,
 }
 _STREAM_KEYS = {"name", "track", "width", "height", "fps"}
 
diff --git a/examples/egocap/capture_server/capture_server/protocol.py b/examples/egocap/capture_server/capture_server/protocol.py
index b6013e5661..6fc524f878 100644
--- a/examples/egocap/capture_server/capture_server/protocol.py
+++ b/examples/egocap/capture_server/capture_server/protocol.py
@@ -202,13 +202,17 @@ class TimeUnit(IntEnum):
 
 
 class LiveKitTimestampBasis(IntEnum):
-    """What a LiveKit frame's ``user_timestamp_us`` means. Neither is sensor exposure time."""
+    """What a LiveKit frame's ``user_timestamp_us`` means. Only the last is a capture time."""
 
-    # The publisher host's monotonic clock in microseconds, read when the frame is published. Not on any clock
-    # this host can convert, so such a stream cannot be recorded against tracking.
+    # The publisher host's monotonic clock in microseconds, read when the frame is processed. Not on any clock
+    # this host can convert.
     PUBLISHER_MONOTONIC_US = 1
-    # Unix time in microseconds on the publisher host, which is kept in step with this host's clock.
-    PUBLISHER_UNIX_US = 2
+    # Unix time in microseconds on the publisher host when the frame finished conversion: processing time,
+    # later than capture by the capture and conversion delay.
+    PUBLISHER_PROCESSING_UNIX_US = 2
+    # Unix time in microseconds of the sensor's capture event, mapped from the sensor's own counter by a sender
+    # that has verified the mapping. The only basis a recording may treat as the frame's capture time.
+    SENSOR_CAPTURE_UNIX_US = 3
 
 
 class SampleTimeSemantics(IntEnum):
diff --git a/examples/egocap/tests/backend/test_app_livekit_recording.py b/examples/egocap/tests/backend/test_app_livekit_recording.py
new file mode 100644
index 0000000000..eecdb1cdd4
--- /dev/null
+++ b/examples/egocap/tests/backend/test_app_livekit_recording.py
@@ -0,0 +1,69 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The app's wiring of recordable LiveKit streams: the recorder's token and the recording config."""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+
+import pytest
+
+from capture_server import protocol as p
+from egocap_web import app as app_module
+
+
+def _stream(stream_id: int, basis, width=6) -> p.LiveKitCameraStream:
+    return p.LiveKitCameraStream(
+        stream_id=stream_id,
+        name=f"cam{stream_id}",
+        url="wss://lk",
+        room="r",
+        publisher="o",
+        track=f"t{stream_id}",
+        timestamp_basis=basis,
+        width=width,
+        height=4,
+        fps=30.0,
+    )
+
+
+def _monitor(streams):
+    return SimpleNamespace(camera_descriptors=(), native=SimpleNamespace(started=SimpleNamespace(streams=streams)))
+
+
+def test_config_factory_declares_and_requires_each_recordable_livekit_stream(tmp_path):
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    monitor = _monitor(
+        [
+            _stream(16, capture),
+            _stream(17, p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US),
+            _stream(18, capture, width=None),
+        ]
+    )
+    config = app_module._recording_config_factory(monitor, None, tmp_path)()
+    assert [(v.name, v.width, v.height, v.fps, v.intrinsics) for v in config.video_sources] == [
+        ("cam16", 6, 4, 30.0, False)
+    ]
+    assert "cam16" in config.qc.required_sources
+
+
+def test_config_factory_without_a_started_session_has_no_livekit_sources(tmp_path):
+    monitor = SimpleNamespace(camera_descriptors=(), native=SimpleNamespace(started=None))
+    assert app_module._recording_config_factory(monitor, None, tmp_path)().video_sources == ()
+
+
+def test_recorder_token_is_signed_when_the_key_pair_is_set(monkeypatch):
+    monkeypatch.setenv("LIVEKIT_API_KEY", "key")
+    monkeypatch.setenv("LIVEKIT_API_SECRET", "secret")
+    assert app_module._recorder_livekit_token("room").count(".") == 2
+
+
+@pytest.mark.parametrize("missing", ["LIVEKIT_API_KEY", "LIVEKIT_API_SECRET"])
+def test_recorder_token_names_the_missing_variables(monkeypatch, missing):
+    monkeypatch.setenv("LIVEKIT_API_KEY", "key")
+    monkeypatch.setenv("LIVEKIT_API_SECRET", "secret")
+    monkeypatch.delenv(missing)
+    with pytest.raises(RuntimeError, match="LIVEKIT_API_KEY and LIVEKIT_API_SECRET"):
+        app_module._recorder_livekit_token("room")
diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
index eb342b71d1..dbbb19f424 100644
--- a/examples/egocap/tests/backend/test_livekit_receiver.py
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -604,8 +604,8 @@ async def test_a_different_participant_disconnecting_changes_nothing(receiver):
 async def test_feed_on_a_never_attached_stream_fails_when_the_publisher_leaves(monkeypatch):
     from egocap_web.livekit_recording import LiveKitRecordingFeed
 
-    unix = p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
-    stream = camera(1, "left", timestamp_basis=unix)
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    stream = camera(1, "left", timestamp_basis=capture)
     rx = lr.LiveKitFrameReceiver([stream], TOKEN)
     await rx.start()
     reasons: list[str] = []
@@ -623,3 +623,13 @@ async def test_feed_on_a_never_attached_stream_fails_when_the_publisher_leaves(m
     finally:
         await feed.stop()
         await rx.stop()
+
+
+async def test_clear_queued_drops_every_queued_frame(receiver):
+    track = subscribe(receiver)
+    track.push(event(3, frame_id=1))
+    track.push(event(3, frame_id=2))
+    await settle()
+    assert receiver.pending(1) > 0
+    receiver.clear_queued()
+    assert receiver.pending(1) == receiver.pending(2) == 0
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index f4518f460f..cecec73930 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -21,7 +21,8 @@
 )
 from recording_service import PixelFormat
 
-UNIX = p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
+CAPTURE = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+PROCESSING = p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US
 MONO = p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
 
 
@@ -179,7 +180,7 @@ def test_mapped_frame_image_is_the_received_image():
 # --- LiveKitRecordingFeed ------------------------------------------------------
 
 
-def _stream(stream_id: int, name: str, basis=UNIX) -> p.LiveKitCameraStream:
+def _stream(stream_id: int, name: str, basis=CAPTURE) -> p.LiveKitCameraStream:
     return p.LiveKitCameraStream(
         stream_id=stream_id,
         name=name,
@@ -242,7 +243,7 @@ def _feed(receiver, streams, ingress, names=None, **kw) -> LiveKitRecordingFeed:
     return LiveKitRecordingFeed(receiver, streams, ingress, names, clock_map=FixedMap(), **kw)
 
 
-async def test_unix_stream_frames_are_offered_with_source_and_mapped_capture_time():
+async def test_capture_stream_frames_are_offered_with_source_and_mapped_capture_time():
     streams = [_stream(16, "Head left")]
     receiver = FakeReceiver({16: [_received(16, 1_000_000), _received(16, 2_000_000)]})
     ingress = FakeIngress()
@@ -255,9 +256,10 @@ async def test_unix_stream_frames_are_offered_with_source_and_mapped_capture_tim
     assert feed.failure is None
 
 
-async def test_monotonic_stream_fails_at_once_and_never_offers():
+@pytest.mark.parametrize("basis", [MONO, PROCESSING])
+async def test_non_capture_stream_fails_at_once_and_never_offers(basis):
     reasons: list[str] = []
-    streams = [_stream(16, "Head left", MONO)]
+    streams = [_stream(16, "Head left", basis)]
     receiver = FakeReceiver({16: [_received(16)]})
     ingress = FakeIngress()
     feed = _feed(receiver, streams, ingress, on_failure=reasons.append)
@@ -268,7 +270,9 @@ async def test_monotonic_stream_fails_at_once_and_never_offers():
     assert receiver.calls == []  # refused before any frame was taken
     assert feed.failure is not None
     assert "Head left" in feed.failure
-    assert "own clock" in feed.failure
+    assert (
+        feed.failure == "Head left: its timestamps are not a capture time, so it cannot be aligned with tracking"
+    )
     assert reasons == [feed.failure]
 
 
@@ -360,6 +364,22 @@ async def test_streams_are_independent():
     assert sorted(m.source for m in ingress.offered) == ["src16", "src17"]
 
 
+async def test_a_stream_still_flowing_when_another_fails_stops_after_its_next_frame():
+    streams = [_stream(16, "Head left"), _stream(17, "Head right")]
+    receiver = FakeReceiver({16: [], 17: [_received(17, 2_000_000)]})
+    receiver.lost.add(16)
+    receiver.gates[17] = asyncio.Event()
+    ingress = FakeIngress()
+    feed = _feed(receiver, streams, ingress)
+    feed.start()
+    await _settle()
+    assert feed.failure == "Head left: the LiveKit track was lost"
+    receiver.gates[17].set()
+    await _settle()
+    assert receiver.calls.count(17) == 1  # the loop ended instead of waiting for another frame
+    await feed.stop()
+
+
 async def test_lost_track_fails_the_take_with_the_stream_name():
     reasons: list[str] = []
     receiver = FakeReceiver({})
diff --git a/examples/egocap/tests/backend/test_livekit_recording_source.py b/examples/egocap/tests/backend/test_livekit_recording_source.py
new file mode 100644
index 0000000000..1eef03566f
--- /dev/null
+++ b/examples/egocap/tests/backend/test_livekit_recording_source.py
@@ -0,0 +1,268 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""recordable_livekit_streams and LiveKitRecordingSource, against a fake frame receiver."""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from capture_server import protocol as p
+from egocap_web import livekit_recording as lrec
+from egocap_web.livekit_receiver import ReceivedFrame
+from egocap_web.livekit_recording import LiveKitRecordingSource, recordable_livekit_streams
+
+CAPTURE = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+PROCESSING = p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US
+MONO = p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US
+
+
+def livekit_stream(stream_id: int, *, basis=CAPTURE, width=6, height=4, fps=30.0, room="room-a"):
+    return p.LiveKitCameraStream(
+        stream_id=stream_id,
+        name=f"cam{stream_id}",
+        url="wss://lk",
+        room=room,
+        publisher="o",
+        track=f"t{stream_id}",
+        timestamp_basis=basis,
+        width=width,
+        height=height,
+        fps=fps,
+    )
+
+
+def jpeg_camera(stream_id: int = 1) -> p.CameraStream:
+    return p.CameraStream(
+        stream_id=stream_id,
+        kind=p.StreamKind.IMAGE,
+        name="jpeg",
+        type=next(iter(p.CameraType)),
+        required=False,
+        width=6,
+        height=4,
+        fps=30.0,
+        codec=next(iter(p.ImageCodec)),
+        jpeg_quality=80,
+        orientation=next(iter(p.ImageOrientation)),
+    )
+
+
+def frame(stream_id: int, *, width=6, height=4) -> ReceivedFrame:
+    return ReceivedFrame(
+        stream_id=stream_id,
+        image=np.zeros((height, width, 3), dtype=np.uint8),
+        receive_time_ns=1,
+        transport_timestamp_us=1,
+        user_timestamp_us=1_000_000,
+        frame_id=None,
+        user_data=None,
+    )
+
+
+# --- recordable_livekit_streams --------------------------------------------------
+
+
+def test_no_started_session_has_no_recordable_streams():
+    assert recordable_livekit_streams(None) == ()
+
+
+def test_only_capture_time_streams_with_full_geometry_are_recordable():
+    keep = livekit_stream(16)
+    streams = [
+        keep,
+        livekit_stream(17, basis=PROCESSING),
+        livekit_stream(18, basis=MONO),
+        livekit_stream(19, width=None),
+        livekit_stream(20, height=None),
+        livekit_stream(21, fps=None),
+        jpeg_camera(),
+    ]
+    assert recordable_livekit_streams(SimpleNamespace(streams=streams)) == (keep,)
+
+
+# --- LiveKitRecordingSource ------------------------------------------------------
+
+
+class FakeReceiver:
+    """Per-stream queues; a ``None`` item is a lost track, an empty queue is a quiet camera."""
+
+    instances: list[FakeReceiver] = []
+    start_error: Exception | None = None
+
+    def __init__(self, streams, token):
+        self.streams, self.token = list(streams), token
+        self.queues = {s.stream_id: asyncio.Queue() for s in streams}
+        self.events: list[str] = []
+        self.stops = 0
+        FakeReceiver.instances.append(self)
+
+    async def start(self):
+        self.events.append("start")
+        if FakeReceiver.start_error is not None:
+            raise FakeReceiver.start_error
+
+    async def stop(self):
+        self.stops += 1
+        self.events.append("stop")
+
+    async def next_frame_or_lost(self, stream_id):
+        return await self.queues[stream_id].get()
+
+    def clear_queued(self):
+        self.events.append("clear")
+        for queue in self.queues.values():
+            while not queue.empty():
+                queue.get_nowait()
+
+
+class FakeIngress:
+    def __init__(self):
+        self.offered = []
+
+    def offer(self, item):
+        self.offered.append(item)
+        return True
+
+
+@pytest.fixture(autouse=True)
+def fake_receiver(monkeypatch):
+    FakeReceiver.instances = []
+    FakeReceiver.start_error = None
+    monkeypatch.setattr(lrec, "LiveKitFrameReceiver", FakeReceiver)
+
+
+def make_source(streams, *, timeout=1.0, tokens=None):
+    tokens = tokens if tokens is not None else []
+    return LiveKitRecordingSource(
+        lambda: streams, lambda room: tokens.append(room) or f"token-{room}", first_frame_timeout_s=timeout
+    )
+
+
+def preload(streams, **frame_kw):
+    for stream in streams:
+        FakeReceiver.instances[-1].queues[stream.stream_id].put_nowait(frame(stream.stream_id, **frame_kw))
+
+
+async def prepare_with_frames(source, streams, **frame_kw):
+    """Runs prepare() while feeding every stream one first frame as the receiver appears."""
+    task = asyncio.ensure_future(source.prepare())
+    while not FakeReceiver.instances:
+        await asyncio.sleep(0)
+    preload(streams, **frame_kw)
+    await task
+
+
+async def test_prepare_with_no_recordable_stream_does_nothing():
+    source = make_source([])
+    await source.prepare()
+    source.start(FakeIngress(), lambda message: None)
+    await source.stop()
+    assert FakeReceiver.instances == []
+
+
+async def test_prepare_joins_with_a_token_for_the_first_streams_room_and_takes_every_first_frame():
+    streams = [livekit_stream(16, room="room-a"), livekit_stream(17, room="room-b")]
+    tokens: list[str] = []
+    source = make_source(streams, tokens=tokens)
+    await prepare_with_frames(source, streams)
+    receiver = FakeReceiver.instances[0]
+    assert tokens == ["room-a"]
+    assert receiver.token == "token-room-a"
+    assert receiver.events == ["start"]
+    assert all(q.empty() for q in receiver.queues.values())
+    await source.stop()
+
+
+async def test_a_wrong_sized_first_frame_fails_naming_the_stream_and_leaves_the_room():
+    streams = [livekit_stream(16)]
+    source = make_source(streams)
+    with pytest.raises(RuntimeError, match=r"cam16: frames are 8x2, expected 6x4"):
+        await prepare_with_frames(source, streams, width=8, height=2)
+    assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_a_lost_track_fails_naming_the_stream_and_leaves_the_room():
+    streams = [livekit_stream(16)]
+    source = make_source(streams)
+    task = asyncio.ensure_future(source.prepare())
+    while not FakeReceiver.instances:
+        await asyncio.sleep(0)
+    FakeReceiver.instances[0].queues[16].put_nowait(None)
+    with pytest.raises(RuntimeError, match="cam16: the LiveKit track was lost"):
+        await task
+    assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_a_quiet_stream_times_out_and_leaves_the_room():
+    source = make_source([livekit_stream(16)], timeout=0.01)
+    with pytest.raises(RuntimeError, match="sent no frame"):
+        await source.prepare()
+    assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_a_failing_join_leaves_the_room_and_propagates():
+    FakeReceiver.start_error = ConnectionError("no route")
+    source = make_source([livekit_stream(16)])
+    with pytest.raises(ConnectionError, match="no route"):
+        await source.prepare()
+    assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_cancelling_prepare_leaves_the_room():
+    source = make_source([livekit_stream(16)], timeout=30.0)
+    task = asyncio.ensure_future(source.prepare())
+    while not FakeReceiver.instances:
+        await asyncio.sleep(0)
+    await asyncio.sleep(0)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+    assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_start_drops_the_backlog_before_feeding_and_names_sources_after_the_streams():
+    streams = [livekit_stream(16)]
+    source = make_source(streams)
+    await prepare_with_frames(source, streams)
+    receiver = FakeReceiver.instances[0]
+    receiver.queues[16].put_nowait(frame(16))  # acquired while storage was opening
+    ingress = FakeIngress()
+    source.start(ingress, lambda message: None)
+    await asyncio.sleep(0)
+    assert "clear" in receiver.events
+    assert ingress.offered == []
+    receiver.queues[16].put_nowait(frame(16))
+    for _ in range(5):
+        await asyncio.sleep(0)
+    assert [m.source for m in ingress.offered] == ["cam16"]
+    await source.stop()
+
+
+async def test_a_feed_failure_reaches_the_failure_callback():
+    streams = [livekit_stream(16)]
+    source = make_source(streams)
+    await prepare_with_frames(source, streams)
+    reasons: list[str] = []
+    source.start(FakeIngress(), reasons.append)
+    FakeReceiver.instances[0].queues[16].put_nowait(None)
+    for _ in range(5):
+        await asyncio.sleep(0)
+    assert reasons == ["cam16: the LiveKit track was lost"]
+    await source.stop()
+
+
+async def test_stop_is_idempotent_and_safe_before_prepare():
+    source = make_source([livekit_stream(16)])
+    await source.stop()
+    streams = [livekit_stream(16)]
+    await prepare_with_frames(source, streams)
+    source.start(FakeIngress(), lambda message: None)
+    await source.stop()
+    await source.stop()
+    assert FakeReceiver.instances[0].stops == 1
diff --git a/examples/egocap/tests/backend/test_recording_session_livekit.py b/examples/egocap/tests/backend/test_recording_session_livekit.py
new file mode 100644
index 0000000000..52eb6536ad
--- /dev/null
+++ b/examples/egocap/tests/backend/test_recording_session_livekit.py
@@ -0,0 +1,141 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The coordinator's optional LiveKit source: prepared before storage opens, fed after the ingress starts,
+stopped before the ingress is retired."""
+
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from egocap_web.recording_session import CoordinatorBusyError, RecordingSessionCoordinator
+from recording_service import FieldSpec, NumericSourceSpec, RecordingPhase, ServiceConfig
+
+NUMERIC = NumericSourceSpec("s", (FieldSpec("v", "float64"),))
+
+
+class FakeSource:
+    """Records the order of prepare/start/stop calls; can be told to fail prepare."""
+
+    def __init__(self, events: list[str], prepare_error: Exception | None = None) -> None:
+        self.events = events
+        self.prepare_error = prepare_error
+        self.ingress = None
+        self.on_failure = None
+
+    async def prepare(self) -> None:
+        self.events.append("prepare")
+        if self.prepare_error is not None:
+            raise self.prepare_error
+
+    def start(self, ingress, on_failure) -> None:
+        self.events.append("start")
+        self.ingress, self.on_failure = ingress, on_failure
+
+    async def stop(self) -> None:
+        self.events.append("stop")
+
+
+def make_coordinator(tmp_path: Path, source) -> RecordingSessionCoordinator:
+    def factory() -> ServiceConfig:
+        return ServiceConfig(output_root=tmp_path / "out", numeric_sources=(NUMERIC,), video_sources=())
+
+    return RecordingSessionCoordinator(
+        factory, queue_capacity=8, readiness_check=lambda: (True, None), livekit_source=source
+    )
+
+
+async def test_a_prepare_failure_refuses_the_start_before_storage_opens(tmp_path, monkeypatch):
+    events: list[str] = []
+    coordinator = make_coordinator(tmp_path, FakeSource(events, RuntimeError("cam16 sent no frame")))
+    await coordinator.open()
+    coordinator.set_task("t")
+    opened: list[bool] = []
+    original = coordinator._open_storage_if_needed
+
+    async def counting_open():
+        opened.append(True)
+        return await original()
+
+    monkeypatch.setattr(coordinator, "_open_storage_if_needed", counting_open)
+    with pytest.raises(CoordinatorBusyError, match="LiveKit video is not ready: cam16 sent no frame"):
+        await coordinator.start_episode()
+    assert opened == []
+    assert events == ["prepare"]
+    assert coordinator.snapshot().service.phase is RecordingPhase.IDLE
+    await coordinator.close()
+
+
+async def test_a_start_that_fails_after_prepare_stops_the_source(tmp_path, monkeypatch):
+    events: list[str] = []
+    coordinator = make_coordinator(tmp_path, FakeSource(events))
+    await coordinator.open()
+    coordinator.set_task("t")
+
+    async def failing(_context):
+        raise RuntimeError("storage exploded")
+
+    monkeypatch.setattr(coordinator, "_start_episode_with_storage", failing)
+    with pytest.raises(RuntimeError, match="storage exploded"):
+        await coordinator.start_episode()
+    assert events == ["prepare", "stop"]
+    await coordinator.close()
+
+
+async def test_a_start_cancelled_after_prepare_stops_the_source(tmp_path, monkeypatch):
+    events: list[str] = []
+    coordinator = make_coordinator(tmp_path, FakeSource(events))
+    await coordinator.open()
+    coordinator.set_task("t")
+
+    async def cancelled(_context):
+        raise asyncio.CancelledError
+
+    monkeypatch.setattr(coordinator, "_start_episode_with_storage", cancelled)
+    with pytest.raises(asyncio.CancelledError):
+        await coordinator.start_episode()
+    assert events == ["prepare", "stop"]
+    await coordinator.close()
+
+
+async def test_the_source_is_started_with_the_ingress_and_its_failure_settles_the_take(tmp_path):
+    events: list[str] = []
+    source = FakeSource(events)
+    coordinator = make_coordinator(tmp_path, source)
+    await coordinator.open()
+    coordinator.set_task("t")
+    await coordinator.start_episode()
+    assert events == ["prepare", "start"]
+    assert source.ingress is coordinator._current_ingress
+
+    source.on_failure("cam16: the LiveKit track was lost")
+    for _ in range(300):
+        snap = coordinator.snapshot()
+        if snap.service.phase is RecordingPhase.RECOVERY_REQUIRED and snap.active_operation is None:
+            break
+        await asyncio.sleep(0.01)
+    assert coordinator.snapshot().service.phase is RecordingPhase.RECOVERY_REQUIRED
+    await coordinator.close()
+
+
+async def test_retiring_the_take_stops_the_source_before_the_ingress(tmp_path):
+    events: list[str] = []
+    coordinator = make_coordinator(tmp_path, FakeSource(events))
+    await coordinator.open()
+    coordinator.set_task("t")
+    episode = await coordinator.start_episode()
+    ingress = coordinator._current_ingress
+    original_stop = ingress.stop
+
+    async def recording_stop():
+        events.append("ingress.stop")
+        return await original_stop()
+
+    ingress.stop = recording_stop
+    await coordinator.stop_episode(episode.episode_id)
+    assert events[-2:] == ["stop", "ingress.stop"]
+    await coordinator.close()
diff --git a/examples/egocap/tests/capture_server/test_livekit_streams.py b/examples/egocap/tests/capture_server/test_livekit_streams.py
index 74eb5592e5..13deaa2b13 100644
--- a/examples/egocap/tests/capture_server/test_livekit_streams.py
+++ b/examples/egocap/tests/capture_server/test_livekit_streams.py
@@ -124,7 +124,7 @@ def test_session_init_still_rejects_unknown_keys():
         {"url": "https://lk.example"},
         {"url": "lk.example:7881"},
         {"url": "x" * 600},
-        {"timestamp_basis": 3},
+        {"timestamp_basis": 4},
         {"timestamp_basis": 0},
         {"timestamp_basis": "1"},
         {"timestamp_basis": True},
@@ -460,12 +460,20 @@ async def test_cli_serves_the_streams_from_the_file(tmp_path, unused_tcp_port):
 
 def test_timestamp_basis_values_are_wire_stable():
     assert int(p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US) == 1
-    assert int(p.LiveKitTimestampBasis.PUBLISHER_UNIX_US) == 2
+    assert int(p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US) == 2
+    assert int(p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US) == 3
 
 
-def test_unix_basis_round_trips_through_json():
-    stream = _stream(timestamp_basis=2)
-    assert stream.timestamp_basis == p.LiveKitTimestampBasis.PUBLISHER_UNIX_US
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [
+        (2, p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US),
+        (3, p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US),
+    ],
+)
+def test_unix_bases_round_trip_through_json(value, expected):
+    stream = _stream(timestamp_basis=value)
+    assert stream.timestamp_basis == expected
     assert p.LiveKitCameraStream.from_json(stream.to_json()) == stream
 
 
@@ -474,7 +482,8 @@ def test_unix_basis_round_trips_through_json():
     [
         ("", p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
         ("timestamp_basis: monotonic_us,", p.LiveKitTimestampBasis.PUBLISHER_MONOTONIC_US),
-        ("timestamp_basis: unix_us,", p.LiveKitTimestampBasis.PUBLISHER_UNIX_US),
+        ("timestamp_basis: processing_unix_us,", p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US),
+        ("timestamp_basis: capture_unix_us,", p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US),
     ],
 )
 def test_loader_puts_the_room_basis_in_every_stream(tmp_path, basis_line, expected):
@@ -490,11 +499,13 @@ def test_loader_puts_the_room_basis_in_every_stream(tmp_path, basis_line, expect
     "value",
     [
         "wall_clock",
+        "unix_us",
         "UNIX_US",
+        "CAPTURE_UNIX_US",
         "2",
         "''",
         "null",
-        "[unix_us]",
+        "[capture_unix_us]",
         "{a: 1}",
     ],
 )
diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
index 5cd0a8a5c6..915602ea51 100644
--- a/examples/egocap/tests/tools/test_livekit_orin_emulator.py
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -34,7 +34,7 @@ def test_parse_valid_streams_and_defaults(token_file):
     )
     assert args.streams == [emu.StreamSpec(0, "left"), emu.StreamSpec(1, "right")]
     assert args.token == "secret-token"
-    assert (args.width, args.height, args.fps, args.timestamp_basis) == (1280, 720, 30.0, "unix_us")
+    assert (args.width, args.height, args.fps, args.timestamp_basis) == (1280, 720, 30.0, "capture_unix_us")
 
 
 @pytest.mark.parametrize(
@@ -65,7 +65,15 @@ def test_missing_or_empty_token_file_is_rejected(tmp_path, token_file):
         emu.parse_args(argv(empty, stream))
 
 
-@pytest.mark.parametrize("extra", ["--timestamp-basis=bogus", "--fps=0", "--width=1", "--height=0"])
+@pytest.mark.parametrize("basis", ["capture_unix_us", "processing_unix_us", "monotonic_us"])
+def test_each_timestamp_basis_choice_is_accepted(token_file, basis):
+    args = emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", f"--timestamp-basis={basis}"))
+    assert args.timestamp_basis == basis
+
+
+@pytest.mark.parametrize(
+    "extra", ["--timestamp-basis=unix_us", "--timestamp-basis=bogus", "--fps=0", "--width=1", "--height=0"]
+)
 def test_bad_options_are_rejected(token_file, extra):
     with pytest.raises(SystemExit):
         emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", extra))
@@ -74,7 +82,8 @@ def test_bad_options_are_rejected(token_file, extra):
 def test_user_timestamp_basis(monkeypatch):
     monkeypatch.setattr(emu.time, "time_ns", lambda: 5_000_000)
     monkeypatch.setattr(emu.time, "monotonic_ns", lambda: 9_000_000)
-    assert emu.user_timestamp_us("unix_us") == 5_000
+    assert emu.user_timestamp_us("capture_unix_us") == 5_000
+    assert emu.user_timestamp_us("processing_unix_us") == 5_000
     assert emu.user_timestamp_us("monotonic_us") == 9_000
 
 
diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index c34f4aa811..fb25695462 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -79,9 +79,10 @@ def build_parser() -> argparse.ArgumentParser:
     parser.add_argument("--fps", type=float, default=30.0)
     parser.add_argument(
         "--timestamp-basis",
-        choices=("unix_us", "monotonic_us"),
-        default="unix_us",
-        help="clock user_timestamp carries: Unix time (recordable) or this host's monotonic time (not recordable)",
+        choices=("capture_unix_us", "processing_unix_us", "monotonic_us"),
+        default="capture_unix_us",
+        help="what user_timestamp carries: this host's Unix time at frame generation, which for synthetic frames "
+        "is their capture time (recordable); the same reading declared as processing time; or monotonic time",
     )
     return parser
 
@@ -111,8 +112,8 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
 
 
 def user_timestamp_us(basis: str) -> int:
-    """Returns now in microseconds on the chosen clock (``unix_us`` or ``monotonic_us``)."""
-    ns = time.time_ns() if basis == "unix_us" else time.monotonic_ns()
+    """Returns now in microseconds on the chosen clock (a Unix basis, or ``monotonic_us``)."""
+    ns = time.monotonic_ns() if basis == "monotonic_us" else time.time_ns()
     return ns // 1000
 
 

From 7c3d26097d510e199189b29321bcc6a944333a23 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:30:26 -0800
Subject: [PATCH 09/37] egocap: stop labelling every LiveKit tile as not
 recorded

Whether a stream is saved is the recorder's state, not something the tile
can know from its descriptor, so the tile makes no recording claim. The
tests that asserted the label are being updated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/frontend/src/LiveKitCameraTile.tsx | 7 ++-----
 examples/egocap/frontend/src/styles.css            | 4 ----
 2 files changed, 2 insertions(+), 9 deletions(-)

diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
index 4fd07b106a..5503fda09a 100644
--- a/examples/egocap/frontend/src/LiveKitCameraTile.tsx
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
@@ -22,7 +22,7 @@ function placeholderFor(phase: LiveKitPhase, track: RemoteTrack | null, hasFrame
   return stale ? "No video frames" : null;
 }
 
-/** A named preview tile; always labelled preview-only because these feeds are not recorded. */
+/** A named live tile. It makes no claim about recording: whether a stream is saved is the recorder's state. */
 export function LiveKitCameraTile({
   name,
   track,
@@ -91,10 +91,7 @@ export function LiveKitCameraTile({
       {/* The element stays mounted while a track exists so attach/detach never races a re-created node. */}
       {track !== null && <video ref={videoRef} muted autoPlay playsInline aria-label={name} />}
       {placeholder !== null && <div className="camera-placeholder">{placeholder}</div>}
-      <figcaption>
-        {name}
-        <span className="camera-preview-badge">Preview only, not recorded</span>
-      </figcaption>
+      <figcaption>{name}</figcaption>
     </figure>
   );
 }
diff --git a/examples/egocap/frontend/src/styles.css b/examples/egocap/frontend/src/styles.css
index b685836766..8114d90f41 100644
--- a/examples/egocap/frontend/src/styles.css
+++ b/examples/egocap/frontend/src/styles.css
@@ -2341,7 +2341,3 @@ below for the narrow/stacked layout). */
   background: rgba(0, 0, 0, 0.6);
 }
 
-.camera-preview-badge {
-  margin-left: var(--space-2);
-  opacity: 0.7;
-}

From 19ca439d44b4654a4c4a6d55e7346539ed247b80 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:32:57 -0800
Subject: [PATCH 10/37] egocap: tests for the recording lifecycle, timestamp
 bases and tile label

Cover the LiveKit recording source and its cleanup paths, the coordinator
hooks (prepare before storage, stop before the ingress, failure
settlement), the recording config for LiveKit streams, the three timestamp
bases in the loader, feed and emulator, and the removed tile label.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/frontend/src/CameraGrid.livekit.test.tsx  | 5 +++--
 examples/egocap/frontend/src/LiveKitCameraTile.test.tsx   | 5 +++--
 examples/egocap/frontend/src/styles.css                   | 1 -
 examples/egocap/tests/backend/test_livekit_recording.py   | 8 +++-----
 .../egocap/tests/backend/test_livekit_recording_source.py | 6 +++---
 5 files changed, 12 insertions(+), 13 deletions(-)

diff --git a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
index 694c2e1462..383935104c 100644
--- a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
@@ -59,7 +59,7 @@ afterEach(() => {
 });
 
 describe("CameraGrid with offered LiveKit streams", () => {
-  it("renders LiveKit tiles beside MJPEG tiles, preview-only, with the MJPEG camera keeping the primary slot", async () => {
+  it("renders LiveKit tiles beside MJPEG tiles, with the MJPEG camera keeping the primary slot", async () => {
     stubFetch(200, { token: "tok" });
     const { container } = render(
       <CameraGrid snapshot={snapshot(["head_camera"], STREAMS)} live={true} receivedAtMonotonic={performance.now()} />,
@@ -68,7 +68,8 @@ describe("CameraGrid with offered LiveKit streams", () => {
     expect(screen.getByText("head_camera")).not.toBeNull();
     expect(screen.getByText("Head left", { exact: false })).not.toBeNull();
     expect(screen.getByText("Head right", { exact: false })).not.toBeNull();
-    expect(screen.getAllByText(/Preview only/)).toHaveLength(2);
+    expect(screen.queryByText(/Preview only/)).toBeNull();
+    expect(container.querySelector(".camera-preview-badge")).toBeNull();
     expect(container.querySelector(".camera-grid-items")?.className).toContain("camera-grid-items--n3");
     const primary = container.querySelectorAll(".camera-tile--primary");
     expect(primary).toHaveLength(1);
diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
index 2ca0c2b881..f94d6de5f9 100644
--- a/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
@@ -120,10 +120,11 @@ describe("LiveKitCameraTile track wiring and labels", () => {
     expect(screen.getByText("Waiting for video")).not.toBeNull();
   });
 
-  it("always labels the tile as preview only and shows its name", () => {
+  it("shows its name and makes no claim about recording", () => {
     render(<LiveKitCameraTile name="Head left" track={null} phase="connected" primary={true} />);
     expect(screen.getByText("Head left", { exact: false })).not.toBeNull();
-    expect(screen.getByText(/Preview only/)).not.toBeNull();
+    expect(screen.queryByText(/Preview only/)).toBeNull();
+    expect(document.querySelector(".camera-preview-badge")).toBeNull();
     expect(document.querySelector(".camera-tile--primary")).not.toBeNull();
   });
 });
diff --git a/examples/egocap/frontend/src/styles.css b/examples/egocap/frontend/src/styles.css
index 8114d90f41..0a23939697 100644
--- a/examples/egocap/frontend/src/styles.css
+++ b/examples/egocap/frontend/src/styles.css
@@ -2340,4 +2340,3 @@ below for the narrow/stacked layout). */
   height: auto;
   background: rgba(0, 0, 0, 0.6);
 }
-
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index cecec73930..c0298980e3 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -364,19 +364,17 @@ async def test_streams_are_independent():
     assert sorted(m.source for m in ingress.offered) == ["src16", "src17"]
 
 
-async def test_a_stream_still_flowing_when_another_fails_stops_after_its_next_frame():
+async def test_a_stream_starting_after_another_has_failed_never_takes_a_frame():
     streams = [_stream(16, "Head left"), _stream(17, "Head right")]
     receiver = FakeReceiver({16: [], 17: [_received(17, 2_000_000)]})
     receiver.lost.add(16)
-    receiver.gates[17] = asyncio.Event()
     ingress = FakeIngress()
     feed = _feed(receiver, streams, ingress)
     feed.start()
     await _settle()
     assert feed.failure == "Head left: the LiveKit track was lost"
-    receiver.gates[17].set()
-    await _settle()
-    assert receiver.calls.count(17) == 1  # the loop ended instead of waiting for another frame
+    assert receiver.calls == [16]
+    assert ingress.offered == []
     await feed.stop()
 
 
diff --git a/examples/egocap/tests/backend/test_livekit_recording_source.py b/examples/egocap/tests/backend/test_livekit_recording_source.py
index 1eef03566f..79623d5b41 100644
--- a/examples/egocap/tests/backend/test_livekit_recording_source.py
+++ b/examples/egocap/tests/backend/test_livekit_recording_source.py
@@ -42,14 +42,14 @@ def jpeg_camera(stream_id: int = 1) -> p.CameraStream:
         stream_id=stream_id,
         kind=p.StreamKind.IMAGE,
         name="jpeg",
-        type=next(iter(p.CameraType)),
+        type=p.CameraType.OAK_D_COLOR,
         required=False,
         width=6,
         height=4,
         fps=30.0,
-        codec=next(iter(p.ImageCodec)),
+        codec=p.ImageCodec.JPEG,
         jpeg_quality=80,
-        orientation=next(iter(p.ImageOrientation)),
+        orientation=p.ImageOrientation(),
     )
 
 

From 22ef6bc7927217984b3cf74786ab0f7107a06a34 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:36:48 -0800
Subject: [PATCH 11/37] egocap: the emulator requests the per-frame metadata
 fields

Without frame_metadata_features in the track options, LiveKit delivers no
user timestamp, frame id or user data to the receiver, which an end-to-end
run against a local LiveKit server showed. The native sender sets all
three; the emulator now does too.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../tests/tools/test_livekit_orin_emulator.py | 19 ++++++++++++++++++-
 .../egocap/tools/livekit_orin_emulator.py     | 10 +++++++++-
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
index 915602ea51..abdc0c14ea 100644
--- a/examples/egocap/tests/tools/test_livekit_orin_emulator.py
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -118,11 +118,12 @@ async def aclose(self):
 @pytest.fixture
 def fake_rtc(monkeypatch):
     """Replaces the SDK with recorders so no server is needed."""
-    log = SimpleNamespace(published=[], unpublished=[], disconnected=False, sources=[], stop=None)
+    log = SimpleNamespace(published=[], options=[], unpublished=[], disconnected=False, sources=[], stop=None)
 
     class Participant:
         async def publish_track(self, track, options):
             log.published.append(track)
+            log.options.append(options)
             return SimpleNamespace(sid=f"sid-{track[0]}")
 
         async def unpublish_track(self, sid):
@@ -150,6 +151,7 @@ def make_source(width, height):
         VideoBufferType=SimpleNamespace(RGBA=1),
         TrackPublishOptions=lambda **kw: kw,
         TrackSource=SimpleNamespace(SOURCE_CAMERA=2),
+        FrameMetadataFeature=SimpleNamespace(FMF_USER_TIMESTAMP=1, FMF_FRAME_ID=2, FMF_USER_DATA=3),
         FrameMetadata=emu.rtc.FrameMetadata,
     )
     monkeypatch.setattr(emu, "rtc", fake)
@@ -174,6 +176,21 @@ async def test_run_publishes_paces_and_shuts_down_cleanly(token_file, fake_rtc):
     assert all(s.closed for s in fake_rtc.sources) and fake_rtc.disconnected
 
 
+async def test_every_track_requests_all_frame_metadata_features(token_file, fake_rtc):
+    args = emu.parse_args(
+        argv(token_file, "--add-stream=sensor=0,livekit=a", "--add-stream=sensor=1,livekit=b", "--fps=200")
+    )
+    args.width, args.height = 48, 16
+    stop = asyncio.Event()
+    fake_rtc.stop = stop
+    await asyncio.wait_for(emu.run(args, stop), timeout=5)
+    features = emu.rtc.FrameMetadataFeature
+    wanted = [features.FMF_USER_TIMESTAMP, features.FMF_FRAME_ID, features.FMF_USER_DATA]
+    assert len(fake_rtc.options) == 2
+    assert all(o["frame_metadata_features"] == wanted for o in fake_rtc.options)
+    assert all(o["source"] == emu.rtc.TrackSource.SOURCE_CAMERA for o in fake_rtc.options)
+
+
 async def test_publish_stream_is_paced_by_fps(token_file, fake_rtc):
     args = emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", "--fps=50"))
     args.width, args.height = 48, 16
diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index fb25695462..fef911017f 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -227,7 +227,15 @@ async def run(args: argparse.Namespace, stop: asyncio.Event) -> None:
             source = rtc.VideoSource(args.width, args.height)
             sources.append(source)
             track = rtc.LocalVideoTrack.create_video_track(spec.name, source)
-            options = rtc.TrackPublishOptions(source=rtc.TrackSource.SOURCE_CAMERA)
+            # As the native sender does, request all three per-frame metadata fields; otherwise none reach the receiver.
+            options = rtc.TrackPublishOptions(
+                source=rtc.TrackSource.SOURCE_CAMERA,
+                frame_metadata_features=[
+                    rtc.FrameMetadataFeature.FMF_USER_TIMESTAMP,
+                    rtc.FrameMetadataFeature.FMF_FRAME_ID,
+                    rtc.FrameMetadataFeature.FMF_USER_DATA,
+                ],
+            )
             publications.append(await room.local_participant.publish_track(track, options))
             tasks.append(asyncio.create_task(publish_stream(source, spec, args, stop, counters)))
         tasks.append(asyncio.create_task(report_stats(stop, counters)))

From e767951b1eef53f7f84dbdaed3f09085dbc9195c Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:36:57 -0800
Subject: [PATCH 12/37] egocap: shorten a comment in the emulator to the line
 limit

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/tools/livekit_orin_emulator.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index fef911017f..b6047478ef 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -227,7 +227,7 @@ async def run(args: argparse.Namespace, stop: asyncio.Event) -> None:
             source = rtc.VideoSource(args.width, args.height)
             sources.append(source)
             track = rtc.LocalVideoTrack.create_video_track(spec.name, source)
-            # As the native sender does, request all three per-frame metadata fields; otherwise none reach the receiver.
+            # As the native sender does, request all three per-frame metadata fields, or none reach the receiver.
             options = rtc.TrackPublishOptions(
                 source=rtc.TrackSource.SOURCE_CAMERA,
                 frame_metadata_features=[

From fe5a5abe0bfb03cbb815dc23f50b4111b54894de Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:40:22 -0800
Subject: [PATCH 13/37] egocap: fix recording LiveKit cameras end to end

Found by recording a take against a local LiveKit server with the
emulator: the ingress had no conversion for the feed's item type and failed
the take, and the readiness check refused a start when the only cameras
were LiveKit streams. The feed now offers a ready VideoSample, which the
ingress passes through, and a recordable LiveKit stream counts as a camera.

The recorded take is KEPT with both cameras at the configured size and
rate and monotonic capture times. Some tests of the old item type still
need updating.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/backend/egocap_web/app.py     |  4 +-
 .../backend/egocap_web/livekit_recording.py   | 41 ++++---------------
 .../backend/egocap_web/recording_adapter.py   |  7 +++-
 3 files changed, 17 insertions(+), 35 deletions(-)

diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index 931bdff49b..f7800cefac 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -244,7 +244,9 @@ def check() -> tuple[bool, str | None]:
         if tracking is None or (now - tracking.received_monotonic) > _READINESS_STALE_SECONDS:
             return False, "tracking source is stale or has no sample yet"
         cameras = monitor.camera_descriptors
-        if not cameras:
+        # A recordable LiveKit stream is a camera too; its liveness is checked when the take prepares and
+        # while it records, not by a preview sample here.
+        if not cameras and not recordable_livekit_streams(monitor.native.started):
             return False, "no camera selected"
         for cam in cameras:
             slot = monitor.preview.camera(cam.name)
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index 04349e7af4..04ff0a17fc 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -20,15 +20,12 @@
 import logging
 import time
 from collections.abc import Callable, Mapping, Sequence
-from dataclasses import dataclass
 from typing import Any
 
-import numpy as np
-
 from capture_server import protocol as p
 from recording_service import PixelFormat, VideoSample
 
-from .livekit_receiver import LiveKitFrameReceiver, ReceivedFrame
+from .livekit_receiver import LiveKitFrameReceiver
 from .recording_adapter import RecordingIngress
 
 logger = logging.getLogger("isaaccapture.egocap.livekit_recording")
@@ -82,33 +79,6 @@ def _measure(self) -> None:
         self._measured_at_ns = self._monotonic_ns()
 
 
-@dataclass(frozen=True)
-class MappedFrame:
-    """A received frame with the recording source it belongs to and its capture time on this machine's clock."""
-
-    frame: ReceivedFrame
-    source: str
-    capture_time: float
-
-    @property
-    def image(self) -> np.ndarray:
-        """The frame's pixels, so the ingress can size its queue by bytes."""
-        return self.frame.image
-
-
-def mapped_frame_to_samples(item: MappedFrame) -> list[VideoSample]:
-    """The recording sample for one mapped frame (the ingress's ``convert``)."""
-    return [
-        VideoSample(
-            source=item.source,
-            image=item.frame.image,
-            pixel_format=PixelFormat.RGB8,
-            capture_time=item.capture_time,
-            receive_time=item.frame.receive_time_ns / 1e9,
-        )
-    ]
-
-
 class LiveKitRecordingFeed:
     """Moves every offered stream's frames from the receiver into the ingress of one take.
 
@@ -180,7 +150,14 @@ async def _run(self, stream_id: int) -> None:
                 self._fail(f"{stream.name}: a frame arrived without the publisher's capture timestamp")
                 return
             capture_time = self._clock_map.monotonic_seconds(frame.user_timestamp_us)
-            if not self._ingress.offer(MappedFrame(frame, source, capture_time)):
+            sample = VideoSample(
+                source=source,
+                image=frame.image,
+                pixel_format=PixelFormat.RGB8,
+                capture_time=capture_time,
+                receive_time=frame.receive_time_ns / 1e9,
+            )
+            if not self._ingress.offer(sample):
                 # The ingress refuses once it has failed or stopped; it reports its own reason.
                 self._fail(f"{stream.name}: the recording ingress is no longer accepting frames")
                 return
diff --git a/examples/egocap/backend/egocap_web/recording_adapter.py b/examples/egocap/backend/egocap_web/recording_adapter.py
index 47b456f2e3..8e19c9b769 100644
--- a/examples/egocap/backend/egocap_web/recording_adapter.py
+++ b/examples/egocap/backend/egocap_web/recording_adapter.py
@@ -348,14 +348,14 @@ def convert_capture_frame(frame: CaptureFrame) -> list[NumericSample]:
 
 # --- bounded ingress queue/consumer -------------------------------------------
 
-RawItem = CaptureFrame | CameraImage
+RawItem = CaptureFrame | CameraImage | VideoSample
 
 
 def _raw_item_bytes(raw_item: RawItem) -> int:
     """The memory one queued raw item pins: the compressed JPEG, the raw tracking blob or a decoded frame."""
     image = getattr(raw_item, "image", None)
     if image is not None:
-        # A decoded LiveKit frame (livekit_recording.MappedFrame) pins its pixels, not a compressed payload.
+        # A decoded frame (a VideoSample from LiveKit) pins its pixels, not a compressed payload.
         return image.nbytes
     return len(raw_item.jpeg) if isinstance(raw_item, CameraImage) else len(raw_item.payload)
 
@@ -369,6 +369,9 @@ def _convert_raw_item(raw_item: RawItem) -> list[NumericSample | VideoSample]:
         return list(convert_capture_frame(raw_item))
     if isinstance(raw_item, CameraImage):
         return [convert_camera_image(raw_item, raw_item.name)]
+    if isinstance(raw_item, VideoSample):
+        # Already a decoded frame with its capture time (LiveKit video): nothing to convert.
+        return [raw_item]
     raise TypeError(f"unsupported raw item type: {type(raw_item).__name__}")
 
 

From d39ce4b937a8d18f466edfca15d868fb580e538a Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:40:32 -0800
Subject: [PATCH 14/37] egocap: document running the whole stack with the
 emulator

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index bdc7bc5363..fc1651ffdc 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -116,3 +116,29 @@ uv run python tools/livekit_orin_emulator.py \
 a capture time and is not recorded. `capture_unix_us` (the default) is honest here because the emulator is the
 camera: it stamps the frame when it generates it. `monotonic_us` sends the publisher's monotonic clock, also not
 recordable.
+
+## 6. The whole stack on one machine, with the emulator
+
+This runs everything except the Orin on one machine, against a local LiveKit server in development mode (key
+`devkey`, secret `secret`). Each command runs in its own terminal, from `examples/egocap/`.
+
+```bash
+livekit-server --dev --bind 127.0.0.1                    # signalling on ws://127.0.0.1:7880
+
+# pub.token: a token for room sensing-preview, identity orin-sensing, allowed to publish (lk token create, or any
+# LiveKit token tool, signed with devkey/secret)
+uv run python tools/livekit_orin_emulator.py --livekit-url=ws://127.0.0.1:7880 --livekit-token-file=pub.token \
+  --add-stream=sensor=0,livekit=sensing-left --add-stream=sensor=1,livekit=sensing-right \
+  --width=640 --height=480 --fps=15 --timestamp-basis=capture_unix_us
+
+uv run capture-server --mock --livekit-streams streams.yaml
+LIVEKIT_API_KEY=devkey LIVEKIT_API_SECRET=secret uv run uvicorn egocap_web.app:app --app-dir backend --port 8000
+```
+
+`streams.yaml` names the room, the publisher and both tracks, with `width: 640`, `height: 480`, `fps: 15` and
+`timestamp_basis: capture_unix_us` (section 2). Open `http://127.0.0.1:8000/`: both tiles show live video, and
+Record saves a take with the two cameras next to the mock tracking. A take recorded this way came out KEPT, with 91
+frames per camera over 6 s at the configured size and rate and increasing capture times.
+
+This exercises the PC side only. It does not test the Jetson encoder, the sender's pacing, or clock agreement
+between two machines.

From c0cd7e7c5eb70501fcb0c17896110132f856de2c Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:41:54 -0800
Subject: [PATCH 15/37] egocap: refuse recording by name when an offered
 LiveKit stream cannot be recorded

An offered stream whose timestamps are not a capture time, or whose size
and rate are not configured, used to be left out of the take silently.
Recording is now refused with that stream's name until it is removed or
made recordable; preview is unaffected. The feed also applies one coarse
clock check per frame (more than 2 s old or in the future ends the take),
and the runbook says plainly that this catches gross disagreement only and
that a passing take is not proven aligned. Corrects a stale comment that
claimed a clock step is caught.

Tests for the new checks are being written.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            | 17 ++++++---
 examples/egocap/backend/egocap_web/app.py     |  6 ++-
 .../backend/egocap_web/livekit_recording.py   | 38 +++++++++++++++++--
 3 files changed, 51 insertions(+), 10 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index fc1651ffdc..40029b1b9c 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -17,13 +17,18 @@ Orin: SIPL -> hardware H.264 -> LiveKit publisher --> LiveKit server --> browser
 PC:   CaptureServer (--livekit-streams: where the streams are) -> egocap backend (list + viewer token)
 ```
 
-**Recording.** A stream is saved with a take only when its station entry gives `width`, `height` and `fps` and
+**Recording.** A LiveKit stream is saved with a take only when its entry gives `width`, `height` and `fps` and
 declares `timestamp_basis: capture_unix_us`, meaning the publisher stamps each frame with the mapped capture time of
-the sensor event. The native Orin sender stamps `processing_unix_us` (host time after capture and conversion), which
-is not a capture time, so its streams are shown in the browser but never recorded. The recorder joins the room itself
-(it needs the same `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET`) and checks each stream's first frame against the
-configured size before a take starts. Camera and tracking alignment also assumes the backend and CaptureServer share
-one machine's clock, and that the publisher's clock is synchronised with it; neither is checked.
+the sensor event. If any offered stream does not qualify, recording is refused with that stream's name (remove it
+from the streams file, or make it recordable); preview is unaffected. The native Orin sender stamps
+`processing_unix_us` (host time after capture and conversion), so with it recording is refused until the sensor's
+capture time is mapped. The recorder joins the room itself (it needs the same `LIVEKIT_API_KEY` and
+`LIVEKIT_API_SECRET`) and checks each stream's first frame against the configured size before a take starts. The
+recorder converts the publisher's Unix time to this machine's monotonic clock and applies one coarse check: a frame
+that is more than 2 s old on arrival, or stamped in the future, ends the take. That catches gross clock disagreement
+only; it does not prove the two machines' clocks agree to milliseconds, and nothing detects a clock step. Alignment
+with tracking also assumes the backend and CaptureServer share one machine's clock. A take that passes is not
+thereby proven aligned.
 
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.
diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index f7800cefac..20226e16d6 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -39,7 +39,7 @@
 from .operator_settings import router as operator_settings_router
 from .livekit_preview import API_KEY_ENV, API_SECRET_ENV, subscriber_token
 from .livekit_preview import router as livekit_preview_router
-from .livekit_recording import LiveKitRecordingSource, recordable_livekit_streams
+from .livekit_recording import LiveKitRecordingSource, recordable_livekit_streams, unrecordable_reason
 from .preview_routes import router as preview_router
 from .recording_adapter import (
     MANUS_GLOVE_SPEC,
@@ -243,6 +243,10 @@ def check() -> tuple[bool, str | None]:
         tracking = monitor.preview.tracking()
         if tracking is None or (now - tracking.received_monotonic) > _READINESS_STALE_SECONDS:
             return False, "tracking source is stale or has no sample yet"
+        # An offered LiveKit stream that cannot be recorded blocks recording by name, never silently dropped.
+        blocked = unrecordable_reason(monitor.native.started)
+        if blocked is not None:
+            return False, blocked
         cameras = monitor.camera_descriptors
         # A recordable LiveKit stream is a camera too; its liveness is checked when the take prepares and
         # while it records, not by a preview sample here.
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index 04ff0a17fc..cf1eb5c472 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -30,9 +30,13 @@
 
 logger = logging.getLogger("isaaccapture.egocap.livekit_recording")
 
-#: How long a measured pair of clock readings is reused. Unix and monotonic time only drift apart slowly, and a
-#: step of the Unix clock is caught within this interval.
+#: How long a measured pair of clock readings is reused. Unix and monotonic time only drift apart slowly; a step of
+#: the Unix clock is simply reflected in the offset at the next measurement, not detected.
 _PAIR_MAX_AGE_S = 1.0
+#: A frame older than this when it arrives, or stamped further than the lead below in the future, means the
+#: publisher's clock and this host's disagree grossly. This catches gross disagreement only, not millisecond error.
+_MAX_FRAME_AGE_S = 2.0
+_MAX_FRAME_LEAD_S = 0.05
 #: Readings per pair; the one read in the shortest span is the most trustworthy.
 _PAIR_ATTEMPTS = 3
 
@@ -79,6 +83,26 @@ def _measure(self) -> None:
         self._measured_at_ns = self._monotonic_ns()
 
 
+def unrecordable_reason(started: Any) -> str | None:
+    """Why a started session's LiveKit streams cannot all be recorded, naming the first that cannot; else None.
+
+    A stream that cannot be recorded is never left out of a take silently: recording is refused until it is
+    removed from the streams file or made recordable.
+    """
+    if started is None:
+        return None
+    for stream in started.streams:
+        if not isinstance(stream, p.LiveKitCameraStream):
+            continue
+        if stream.timestamp_basis is not p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US:
+            return (
+                f"LiveKit stream {stream.name!r}: its timestamps are not a capture time, so it cannot be recorded"
+            )
+        if None in (stream.width, stream.height, stream.fps):
+            return f"LiveKit stream {stream.name!r}: width, height and fps must be configured to record it"
+    return None
+
+
 class LiveKitRecordingFeed:
     """Moves every offered stream's frames from the receiver into the ingress of one take.
 
@@ -150,12 +174,20 @@ async def _run(self, stream_id: int) -> None:
                 self._fail(f"{stream.name}: a frame arrived without the publisher's capture timestamp")
                 return
             capture_time = self._clock_map.monotonic_seconds(frame.user_timestamp_us)
+            receive_time = frame.receive_time_ns / 1e9
+            age = receive_time - capture_time
+            if not -_MAX_FRAME_LEAD_S <= age <= _MAX_FRAME_AGE_S:
+                # A coarse validity check: a capture time far from this host's clock is not a capture time here.
+                self._fail(
+                    f"{stream.name}: the publisher's clock disagrees with this host's (frame age {age:+.3f} s)"
+                )
+                return
             sample = VideoSample(
                 source=source,
                 image=frame.image,
                 pixel_format=PixelFormat.RGB8,
                 capture_time=capture_time,
-                receive_time=frame.receive_time_ns / 1e9,
+                receive_time=receive_time,
             )
             if not self._ingress.offer(sample):
                 # The ingress refuses once it has failed or stopped; it reports its own reason.

From a95205860c2e6a198af47ef3de1ead2ef8b48d0a Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:44:57 -0800
Subject: [PATCH 16/37] egocap: tests for the VideoSample feed, by-name refusal
 and clock check (in progress)

Regression test with the real ingress for the item type that failed the
first recorded take, readiness refusal by stream name, and the coarse
clock check. The subagent writing them had not finished its full run when
this was committed.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../backend/test_app_livekit_recording.py     |  50 ++++++
 .../tests/backend/test_livekit_recording.py   | 159 +++++++++++++++---
 .../backend/test_livekit_recording_source.py  |   6 +-
 .../tests/backend/test_recording_adapter.py   |  63 ++++++-
 4 files changed, 249 insertions(+), 29 deletions(-)

diff --git a/examples/egocap/tests/backend/test_app_livekit_recording.py b/examples/egocap/tests/backend/test_app_livekit_recording.py
index eecdb1cdd4..76e32702c4 100644
--- a/examples/egocap/tests/backend/test_app_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_app_livekit_recording.py
@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import time
 from types import SimpleNamespace
 
 import pytest
@@ -67,3 +68,52 @@ def test_recorder_token_names_the_missing_variables(monkeypatch, missing):
     monkeypatch.delenv(missing)
     with pytest.raises(RuntimeError, match="LIVEKIT_API_KEY and LIVEKIT_API_SECRET"):
         app_module._recorder_livekit_token("room")
+
+
+# --- recording readiness -------------------------------------------------------
+
+
+def _ready_monitor(streams, cameras=()):
+    now = time.monotonic()
+    return SimpleNamespace(
+        tracking_descriptor=object(),
+        camera_descriptors=tuple(cameras),
+        native=SimpleNamespace(status=SimpleNamespace(running=True), started=SimpleNamespace(streams=streams)),
+        preview=SimpleNamespace(
+            tracking=lambda: SimpleNamespace(received_monotonic=now),
+            camera=lambda name: SimpleNamespace(received_monotonic=now),
+        ),
+    )
+
+
+@pytest.fixture
+def accepted_tracking(monkeypatch):
+    monkeypatch.setattr(app_module, "validate_tracking_descriptor", lambda descriptor: None)
+
+
+def test_readiness_accepts_recordable_livekit_streams_without_a_jpeg_camera(accepted_tracking):
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    check = app_module._recording_readiness_check(_ready_monitor([_stream(16, capture)]), None)
+    assert check() == (True, None)
+
+
+def test_readiness_without_any_stream_says_no_camera(accepted_tracking):
+    assert app_module._recording_readiness_check(_ready_monitor([]), None)() == (False, "no camera selected")
+
+
+def test_readiness_names_a_stream_whose_timestamps_are_not_a_capture_time(accepted_tracking):
+    streams = [
+        _stream(16, p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US),
+        _stream(17, p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US),
+    ]
+    check = app_module._recording_readiness_check(_ready_monitor(streams), None)
+    assert check() == (
+        False,
+        "LiveKit stream 'cam17': its timestamps are not a capture time, so it cannot be recorded",
+    )
+
+
+def test_readiness_names_a_stream_without_geometry(accepted_tracking):
+    stream = _stream(16, p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US, width=None)
+    check = app_module._recording_readiness_check(_ready_monitor([stream]), None)
+    assert check() == (False, "LiveKit stream 'cam16': width, height and fps must be configured to record it")
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index c0298980e3..98ac723dad 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-"""livekit_recording: Unix-to-monotonic mapping, frame-to-sample conversion and the per-stream feed."""
+"""livekit_recording: Unix-to-monotonic mapping, the per-stream feed."""
 
 from __future__ import annotations
 
@@ -15,11 +15,11 @@
 from egocap_web.livekit_receiver import ReceivedFrame
 from egocap_web.livekit_recording import (
     LiveKitRecordingFeed,
-    MappedFrame,
     UnixClockMap,
-    mapped_frame_to_samples,
+    unrecordable_reason,
 )
-from recording_service import PixelFormat
+from egocap_web.recording_adapter import RecordingIngress
+from recording_service import PixelFormat, SubmissionResult, SubmissionStatus, VideoSample
 
 CAPTURE = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
 PROCESSING = p.LiveKitTimestampBasis.PUBLISHER_PROCESSING_UNIX_US
@@ -143,12 +143,15 @@ def test_default_clocks_map_now_to_about_now():
     assert mapped == pytest.approx(time.monotonic(), abs=0.05)
 
 
-# --- mapped_frame_to_samples ---------------------------------------------------
+# --- received frames -----------------------------------------------------------
 
 
 def _received(
-    stream_id: int = 16, user_ts: int | None = 1_000_000, receive_ns: int = 2_500_000_000
+    stream_id: int = 16, user_ts: int | None = 1_000_000, receive_ns: int | None = None
 ) -> ReceivedFrame:
+    if receive_ns is None:
+        # Arrives 0.1 s after capture on FixedMap's clock (capture = user_ts / 1e6 + 10).
+        receive_ns = int(((user_ts or 0) / 1e6 + 10.1) * 1e9)
     return ReceivedFrame(
         stream_id=stream_id,
         image=np.zeros((4, 6, 3), dtype=np.uint8),
@@ -160,23 +163,6 @@ def _received(
     )
 
 
-def test_mapped_frame_becomes_one_rgb8_sample_in_seconds():
-    frame = _received()
-    samples = mapped_frame_to_samples(MappedFrame(frame, "head_left", 1.25))
-    assert len(samples) == 1
-    sample = samples[0]
-    assert sample.source == "head_left"
-    assert sample.pixel_format == PixelFormat.RGB8
-    assert sample.capture_time == 1.25
-    assert sample.receive_time == pytest.approx(2.5)
-    assert sample.image is frame.image
-
-
-def test_mapped_frame_image_is_the_received_image():
-    frame = _received()
-    assert MappedFrame(frame, "s", 0.0).image is frame.image
-
-
 # --- LiveKitRecordingFeed ------------------------------------------------------
 
 
@@ -218,10 +204,10 @@ class FakeIngress:
     """Records offers; answers each with the next scripted value (True once the script runs out)."""
 
     def __init__(self, answers: list[bool] | None = None) -> None:
-        self.offered: list[MappedFrame] = []
+        self.offered: list[VideoSample] = []
         self._answers = list(answers or [])
 
-    def offer(self, item: MappedFrame) -> bool:
+    def offer(self, item: VideoSample) -> bool:
         self.offered.append(item)
         return self._answers.pop(0) if self._answers else True
 
@@ -253,9 +239,50 @@ async def test_capture_stream_frames_are_offered_with_source_and_mapped_capture_
     await feed.stop()
     assert [m.source for m in ingress.offered] == ["head_left", "head_left"]
     assert [m.capture_time for m in ingress.offered] == [11.0, 12.0]
+    assert all(isinstance(m, VideoSample) for m in ingress.offered)
     assert feed.failure is None
 
 
+async def test_offered_sample_is_rgb8_with_the_frame_image_and_receive_time_in_seconds():
+    frame = _received(16, 1_000_000, receive_ns=11_100_000_000)
+    ingress = FakeIngress()
+    feed = _feed(FakeReceiver({16: [frame]}), [_stream(16, "Head left")], ingress, {16: "head_left"})
+    feed.start()
+    await _settle()
+    await feed.stop()
+    (sample,) = ingress.offered
+    assert isinstance(sample, VideoSample)
+    assert sample.source == "head_left"
+    assert sample.pixel_format == PixelFormat.RGB8
+    assert sample.image is frame.image
+    assert sample.capture_time == 11.0
+    assert sample.receive_time == pytest.approx(11.1)
+
+
+async def test_feed_into_the_real_ingress_converts_and_submits_the_sample():
+    submitted: list[VideoSample] = []
+
+    def submit(sample):
+        submitted.append(sample)
+        return SubmissionResult(SubmissionStatus.ACCEPTED, sample.source, None)
+
+    ingress = RecordingIngress(queue_capacity=4, submit=submit)
+    await ingress.start()
+    frame = _received(16, 1_000_000)
+    feed = _feed(FakeReceiver({16: [frame]}), [_stream(16, "Head left")], ingress, {16: "head_left"})
+    feed.start()
+    for _ in range(50):
+        if submitted:
+            break
+        await asyncio.sleep(0.01)
+    await feed.stop()
+    await ingress.stop()
+    assert feed.failure is None
+    assert ingress.failure is None
+    assert [x.source for x in submitted] == ["head_left"]
+    assert submitted[0].image is frame.image
+
+
 @pytest.mark.parametrize("basis", [MONO, PROCESSING])
 async def test_non_capture_stream_fails_at_once_and_never_offers(basis):
     reasons: list[str] = []
@@ -416,3 +443,85 @@ async def test_a_stream_still_waiting_on_its_track_does_not_delay_another_that_i
     await _settle()
     await feed.stop()
     assert feed.failure == "Head left: the LiveKit track was lost"
+
+
+# --- frame age window ----------------------------------------------------------
+
+
+@pytest.mark.parametrize("age_s", [-0.04, 0.0, 0.5, 1.99])
+async def test_frames_inside_the_age_window_are_offered(age_s):
+    frame = _received(16, 1_000_000, receive_ns=int((11.0 + age_s) * 1e9))
+    ingress = FakeIngress()
+    feed = _feed(FakeReceiver({16: [frame]}), [_stream(16, "Head left")], ingress)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert len(ingress.offered) == 1
+    assert feed.failure is None
+
+
+@pytest.mark.parametrize(
+    ("age_s", "text"), [(3.0, "frame age +3.000 s"), (-0.5, "frame age -0.500 s"), (2.01, "frame age +2.010 s")]
+)
+async def test_frames_outside_the_age_window_fail_the_feed_and_are_not_offered(age_s, text):
+    reasons: list[str] = []
+    frame = _received(16, 1_000_000, receive_ns=int((11.0 + age_s) * 1e9))
+    ingress = FakeIngress()
+    feed = _feed(FakeReceiver({16: [frame]}), [_stream(16, "Head left")], ingress, on_failure=reasons.append)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert ingress.offered == []
+    assert feed.failure == f"Head left: the publisher's clock disagrees with this host's ({text})"
+    assert reasons == [feed.failure]
+
+
+# --- unrecordable_reason -------------------------------------------------------
+
+
+def _started(*streams):
+    return type("Started", (), {"streams": list(streams)})()
+
+
+def _geometry(stream_id, basis=CAPTURE, **missing):
+    values = {"width": 6, "height": 4, "fps": 30.0} | missing
+    return p.LiveKitCameraStream(
+        stream_id=stream_id,
+        name=f"cam{stream_id}",
+        url="wss://lk",
+        room="r",
+        publisher="o",
+        track=f"t{stream_id}",
+        timestamp_basis=basis,
+        **values,
+    )
+
+
+def test_unrecordable_reason_is_none_without_a_session_or_streams():
+    assert unrecordable_reason(None) is None
+    assert unrecordable_reason(_started()) is None
+
+
+def test_unrecordable_reason_is_none_when_every_stream_is_recordable():
+    assert unrecordable_reason(_started(_geometry(16), _geometry(17))) is None
+
+
+def test_unrecordable_reason_names_a_stream_that_is_not_a_capture_time():
+    started = _started(_geometry(16), _geometry(17, PROCESSING), _geometry(18, MONO))
+    assert (
+        unrecordable_reason(started)
+        == "LiveKit stream 'cam17': its timestamps are not a capture time, so it cannot be recorded"
+    )
+
+
+@pytest.mark.parametrize("field", ["width", "height", "fps"])
+def test_unrecordable_reason_names_a_stream_missing_geometry(field):
+    started = _started(_geometry(16, **{field: None}))
+    assert (
+        unrecordable_reason(started)
+        == "LiveKit stream 'cam16': width, height and fps must be configured to record it"
+    )
+
+
+def test_unrecordable_reason_ignores_streams_that_are_not_livekit():
+    assert unrecordable_reason(_started(object(), _geometry(16))) is None
diff --git a/examples/egocap/tests/backend/test_livekit_recording_source.py b/examples/egocap/tests/backend/test_livekit_recording_source.py
index 79623d5b41..dfa0c7985d 100644
--- a/examples/egocap/tests/backend/test_livekit_recording_source.py
+++ b/examples/egocap/tests/backend/test_livekit_recording_source.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import asyncio
+import time
 from types import SimpleNamespace
 
 import numpy as np
@@ -57,9 +58,10 @@ def frame(stream_id: int, *, width=6, height=4) -> ReceivedFrame:
     return ReceivedFrame(
         stream_id=stream_id,
         image=np.zeros((height, width, 3), dtype=np.uint8),
-        receive_time_ns=1,
+        # Captured just now on this host's clocks, so it passes the feed's frame-age check.
+        receive_time_ns=time.monotonic_ns(),
         transport_timestamp_us=1,
-        user_timestamp_us=1_000_000,
+        user_timestamp_us=time.time_ns() // 1000,
         frame_id=None,
         user_data=None,
     )
diff --git a/examples/egocap/tests/backend/test_recording_adapter.py b/examples/egocap/tests/backend/test_recording_adapter.py
index 861e45ffdd..25a5229d0e 100644
--- a/examples/egocap/tests/backend/test_recording_adapter.py
+++ b/examples/egocap/tests/backend/test_recording_adapter.py
@@ -27,6 +27,7 @@
 from egocap_web.recording_adapter import (
     RecordingAdapterError,
     RecordingIngress,
+    _convert_raw_item,
     _raw_item_bytes,
     build_manus_glove_fields,
     build_pico_controller_fields,
@@ -39,7 +40,7 @@
     pose7d_to_matrix,
     validate_tracking_descriptor,
 )
-from recording_service import NumericSample, SubmissionResult, SubmissionStatus, VideoSample
+from recording_service import NumericSample, PixelFormat, SubmissionResult, SubmissionStatus, VideoSample
 
 IDENTITY_QUAT = (0.0, 0.0, 0.0, 1.0)
 
@@ -590,7 +591,7 @@ def test_queue_bytes_must_be_positive():
 
 
 class _DecodedFrame:
-    """Anything with an ``image`` ndarray, as livekit_recording.MappedFrame has."""
+    """Anything with an ``image`` ndarray, to size by pixels without being a VideoSample."""
 
     def __init__(self, image: np.ndarray) -> None:
         self.image = image
@@ -650,3 +651,61 @@ async def run():
         assert ingress.failure is not None
 
     asyncio.run(run())
+
+
+def _video_sample(shape=(10, 10, 3), source="head_left") -> VideoSample:
+    return VideoSample(
+        source=source,
+        image=np.zeros(shape, dtype=np.uint8),
+        pixel_format=PixelFormat.RGB8,
+        capture_time=1.0,
+        receive_time=2.0,
+    )
+
+
+def test_convert_raw_item_passes_a_video_sample_through_unchanged():
+    sample = _video_sample()
+    converted = _convert_raw_item(sample)
+    assert len(converted) == 1
+    assert converted[0] is sample
+
+
+def test_raw_item_bytes_sizes_a_video_sample_by_its_pixels():
+    assert _raw_item_bytes(_video_sample((10, 20, 3))) == 600
+
+
+def test_real_ingress_with_the_default_converter_submits_a_video_sample():
+    async def run():
+        submitted: list[VideoSample] = []
+
+        def submit(sample):
+            submitted.append(sample)
+            return SubmissionResult(SubmissionStatus.ACCEPTED, sample.source, None)
+
+        ingress = RecordingIngress(queue_capacity=4, submit=submit)  # no convert: the default converter
+        await ingress.start()
+        sample = _video_sample()
+        assert ingress.offer(sample) is True
+        for _ in range(50):
+            if submitted:
+                break
+            await asyncio.sleep(0.01)
+        await ingress.stop()
+        assert ingress.failure is None
+        assert len(submitted) == 1
+        assert submitted[0] is sample
+
+    asyncio.run(run())
+
+
+def test_real_ingress_enforces_the_byte_budget_on_video_samples():
+    async def run():
+        ingress = RecordingIngress(
+            queue_capacity=100,
+            queue_bytes=1000,
+            submit=lambda s: SubmissionResult(SubmissionStatus.ACCEPTED, s.source, None),
+        )
+        assert ingress.offer(_video_sample((20, 20, 3))) is False  # 1200 bytes, over the budget on its own
+        assert "byte budget" in ingress.failure
+
+    asyncio.run(run())

From 82c854f66b8a4e48c03cfefba27aa70846c17660 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:51:58 -0800
Subject: [PATCH 17/37] sensing: add a probe to measure the capture counter
 against the host clocks

SENSING_TSC_PROBE=1 prints the SIPL capture counter beside
CLOCK_MONOTONIC_RAW, CLOCK_MONOTONIC and CLOCK_REALTIME twice a second, so a
person on the Orin can see whether the counter shares a timebase with a host
clock. It builds no mapping and the sender still publishes processing time.
The runbook lists what real Orin recording still needs. The probe is
clang-format checked and its clock-reading lines were syntax-checked in
isolation; the Jetson sources are not compiled here.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index 40029b1b9c..88a1e38bd5 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -30,6 +30,22 @@ only; it does not prove the two machines' clocks agree to milliseconds, and noth
 with tracking also assumes the backend and CaptureServer share one machine's clock. A take that passes is not
 thereby proven aligned.
 
+**What recording from the real Orin still needs.** The native sender must publish `capture_unix_us`, the Unix time
+of the sensor's capture event. Its only capture-event clock is the SIPL frame capture counter (`frameCaptureTSC`),
+which Slack reports as the end-of-frame time in nanoseconds on the Tegra TSC timebase, not exposure; none of that is
+checked here. The SIPL headers and an Orin are needed to settle three things, in order:
+
+1. Run the sender with `SENSING_TSC_PROBE=1`. It prints the capture counter next to `CLOCK_MONOTONIC_RAW`,
+   `CLOCK_MONOTONIC` and `CLOCK_REALTIME` twice a second. A `raw_minus_tsc_ns` that stays constant over minutes, apart
+   from a small jitter, shows the counter shares a timebase with a host clock. If it drifts or steps, there is no
+   mapping to build on.
+2. With the relation confirmed, convert the counter to Unix time in the sender (one offset, re-measured at a low
+   rate and never per frame) and publish that as the application timestamp with the `capture_unix_us` basis, keeping
+   the raw counter in the frame's user data. Check against the SIPL documentation what instant the counter marks.
+3. Keep the Orin's and the PC's clocks in step with an ordinary time service, and measure the residual offset;
+   the recorder's frame-age check only catches gross disagreement, and a physical event seen by both the camera and a
+   tracking device is the test of real alignment.
+
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.
 

From f577eb3d419b7729e60a12361e1c9a694443a950 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:54:36 -0800
Subject: [PATCH 18/37] sensing: make the counter probe cheap when off, logged,
 and honest about what it shows

Read the environment once, log through the repository logger, and say in
the comment and the runbook that the counter-to-host difference includes
sensor, ISP and dequeue delay, so it is not a mapping and must not be
subtracted as one. The runbook now lists the evidence real Orin recording
needs. Jetson source, not compiled here.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index 88a1e38bd5..a151367429 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -33,18 +33,22 @@ thereby proven aligned.
 **What recording from the real Orin still needs.** The native sender must publish `capture_unix_us`, the Unix time
 of the sensor's capture event. Its only capture-event clock is the SIPL frame capture counter (`frameCaptureTSC`),
 which Slack reports as the end-of-frame time in nanoseconds on the Tegra TSC timebase, not exposure; none of that is
-checked here. The SIPL headers and an Orin are needed to settle three things, in order:
-
-1. Run the sender with `SENSING_TSC_PROBE=1`. It prints the capture counter next to `CLOCK_MONOTONIC_RAW`,
-   `CLOCK_MONOTONIC` and `CLOCK_REALTIME` twice a second. A `raw_minus_tsc_ns` that stays constant over minutes, apart
-   from a small jitter, shows the counter shares a timebase with a host clock. If it drifts or steps, there is no
-   mapping to build on.
-2. With the relation confirmed, convert the counter to Unix time in the sender (one offset, re-measured at a low
-   rate and never per frame) and publish that as the application timestamp with the `capture_unix_us` basis, keeping
-   the raw counter in the frame's user data. Check against the SIPL documentation what instant the counter marks.
-3. Keep the Orin's and the PC's clocks in step with an ordinary time service, and measure the residual offset;
-   the recorder's frame-age check only catches gross disagreement, and a physical event seen by both the camera and a
-   tracking device is the test of real alignment.
+checked here, and the SIPL headers and an Orin are needed. The evidence required, from a supported platform API and
+not from fitting measurements:
+
+1. The counter's definition, units and event (which instant of the frame it marks) from the SIPL image-metadata
+   documentation of the deployed release, and the TSC's definition and rate in the L4T documentation of the
+   deployed JetPack. Record the exact header, SDK and L4T versions.
+2. A contemporaneous counter and host-clock reading from a supported API, so that a counter value can be placed on
+   `CLOCK_REALTIME` through one offset that is re-measured at a low rate, never per frame. Convert in the sender and
+   publish that time with the `capture_unix_us` basis, keeping the raw counter in the frame's user data.
+3. A time service between the Orin and the PC with the residual offset measured, and a physical event seen by both
+   the camera and a tracking device as the test of real alignment. The recorder's frame-age check only catches gross
+   disagreement.
+
+`SENSING_TSC_PROBE=1` prints the capture counter beside the host clocks twice a second, off by default. Its
+difference includes sensor readout, ISP and dequeue delay as well as any clock offset, so it only shows the order of
+magnitude and the drift of the relation. It is not a mapping and must not be fitted or subtracted as one.
 
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.

From 7178557485e18e509f5247c17c655b409a759fc7 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 4 Nov 2026 23:56:17 -0800
Subject: [PATCH 19/37] egocap: runbook says the SIPL capture counter is raw
 ticks until the Orin headers confirm units

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index a151367429..efe1691be6 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -32,8 +32,9 @@ thereby proven aligned.
 
 **What recording from the real Orin still needs.** The native sender must publish `capture_unix_us`, the Unix time
 of the sensor's capture event. Its only capture-event clock is the SIPL frame capture counter (`frameCaptureTSC`),
-which Slack reports as the end-of-frame time in nanoseconds on the Tegra TSC timebase, not exposure; none of that is
-checked here, and the SIPL headers and an Orin are needed. The evidence required, from a supported platform API and
+which NVIDIA's public SIPL documentation describes as raw ARM generic-timer ticks, not nanoseconds (the `capture_tsc_ns`
+names in the sender code are misleading until units are confirmed). The deployed Orin's SIPL headers are not available
+here, so nothing about its units or event is verified. The evidence required, from a supported platform API and
 not from fitting measurements:
 
 1. The counter's definition, units and event (which instant of the frame it marks) from the SIPL image-metadata

From 34c1dd73a5950e439ca203503702cd2ecc791177 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 00:07:54 -0800
Subject: [PATCH 20/37] egocap emulator: take the Unix and counter stamps
 together before synthesizing the frame

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/tools/livekit_orin_emulator.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index b6047478ef..bcc9e788ca 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -183,11 +183,11 @@ async def publish_stream(
     frame_id = 0
     while not stop.is_set():
         frame_id += 1
-        # The raw capture counter is taken first, as the sensor would stamp it before encoding.
+        # Both stamps are taken together, before the frame is synthesized, as a camera stamps at capture.
         capture_ns = capture_clock()
+        timestamp_us = user_timestamp_us(args.timestamp_basis)
         pixels = make_pattern(args.width, args.height, spec.sensor, frame_id)
         frame = rtc.VideoFrame(args.width, args.height, rtc.VideoBufferType.RGBA, pixels.tobytes())
-        timestamp_us = user_timestamp_us(args.timestamp_basis)
         source.capture_frame(
             frame,
             timestamp_us=timestamp_us,

From 72454cc46874c04c8821824c53cdbbafd9867baa Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:30:27 -0800
Subject: [PATCH 21/37] egocap emulator test: stamps are taken together before
 the frame is synthesized

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../tests/tools/test_livekit_orin_emulator.py | 22 +++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
index abdc0c14ea..aea6e70316 100644
--- a/examples/egocap/tests/tools/test_livekit_orin_emulator.py
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -221,3 +221,25 @@ def test_banner_never_shows_token(token_file, capsys):
     emu.print_banner(emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a")))
     out = capsys.readouterr().out
     assert "secret-token" not in out and "a" in out
+
+
+async def test_stamps_are_taken_together_before_the_frame_is_synthesized(token_file, fake_rtc, monkeypatch):
+    args = emu.parse_args(argv(token_file, "--add-stream=sensor=0,livekit=a", "--fps=200"))
+    args.width, args.height = 4, 4
+    now_us = [1_000]
+
+    def slow_pattern(width, height, sensor, frame_id):
+        now_us[0] += 500  # synthesizing a frame takes time
+        return np.zeros((height, width, 4), np.uint8)
+
+    monkeypatch.setattr(emu, "make_pattern", slow_pattern)
+    monkeypatch.setattr(emu, "user_timestamp_us", lambda basis: now_us[0])
+    stop = asyncio.Event()
+    source = FakeSource(stop, limit=1)
+    await emu.publish_stream(
+        source, emu.StreamSpec(0, "a"), args, stop, emu.Counters({"a": 0}), capture_clock=lambda: now_us[0] * 1000
+    )
+    _, timestamp_us, metadata = source.calls[0]
+    # The same stamp goes to the frame and the metadata, and excludes the synthesis time.
+    assert timestamp_us == metadata.user_timestamp == 1_000
+    assert int.from_bytes(bytes(metadata.user_data), "little") == 1_000_000

From be534dbb61eee1963c1b0d9c132148e24a7035a1 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:37:12 -0800
Subject: [PATCH 22/37] egocap emulator: stamp processing time after the frame
 is synthesized

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/tools/livekit_orin_emulator.py | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index bcc9e788ca..8d1fa0b431 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -183,11 +183,15 @@ async def publish_stream(
     frame_id = 0
     while not stop.is_set():
         frame_id += 1
-        # Both stamps are taken together, before the frame is synthesized, as a camera stamps at capture.
+        # The counter and a capture-time stamp are taken before the frame is synthesized, as a camera stamps at
+        # capture; a processing-time stamp is taken once the frame is ready, as the real sender's is.
         capture_ns = capture_clock()
-        timestamp_us = user_timestamp_us(args.timestamp_basis)
+        at_capture = args.timestamp_basis != "processing_unix_us"
+        timestamp_us = user_timestamp_us(args.timestamp_basis) if at_capture else 0
         pixels = make_pattern(args.width, args.height, spec.sensor, frame_id)
         frame = rtc.VideoFrame(args.width, args.height, rtc.VideoBufferType.RGBA, pixels.tobytes())
+        if not at_capture:
+            timestamp_us = user_timestamp_us(args.timestamp_basis)
         source.capture_frame(
             frame,
             timestamp_us=timestamp_us,

From e179a4b77c673cd5995b2c190a83e358df3355ba Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:37:28 -0800
Subject: [PATCH 23/37] egocap emulator test: only the processing basis is
 stamped after synthesis

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../tests/tools/test_livekit_orin_emulator.py | 30 +++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
index aea6e70316..68c86a0d9d 100644
--- a/examples/egocap/tests/tools/test_livekit_orin_emulator.py
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -243,3 +243,33 @@ def slow_pattern(width, height, sensor, frame_id):
     # The same stamp goes to the frame and the metadata, and excludes the synthesis time.
     assert timestamp_us == metadata.user_timestamp == 1_000
     assert int.from_bytes(bytes(metadata.user_data), "little") == 1_000_000
+
+
+@pytest.mark.parametrize(
+    ("basis", "expected_us"),
+    [("capture_unix_us", 1_000), ("monotonic_us", 1_000), ("processing_unix_us", 1_500)],
+)
+async def test_only_the_processing_basis_is_stamped_after_synthesis(
+    token_file, fake_rtc, monkeypatch, basis, expected_us
+):
+    args = emu.parse_args(
+        argv(token_file, "--add-stream=sensor=0,livekit=a", "--fps=200", f"--timestamp-basis={basis}")
+    )
+    args.width, args.height = 4, 4
+    now_us = [1_000]
+
+    def slow_pattern(width, height, sensor, frame_id):
+        now_us[0] += 500
+        return np.zeros((height, width, 4), np.uint8)
+
+    monkeypatch.setattr(emu, "make_pattern", slow_pattern)
+    monkeypatch.setattr(emu, "user_timestamp_us", lambda _basis: now_us[0])
+    stop = asyncio.Event()
+    source = FakeSource(stop, limit=1)
+    await emu.publish_stream(
+        source, emu.StreamSpec(0, "a"), args, stop, emu.Counters({"a": 0}), capture_clock=lambda: now_us[0] * 1000
+    )
+    _, timestamp_us, metadata = source.calls[0]
+    assert timestamp_us == metadata.user_timestamp == expected_us
+    # The raw capture counter is always read before synthesis.
+    assert int.from_bytes(bytes(metadata.user_data), "little") == 1_000_000

From d6db3c8cd9b08c3c69805259184cb2f84e8d6e99 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:38:17 -0800
Subject: [PATCH 24/37] sensing: stop calling the SIPL capture counter
 nanoseconds

Rename capture_tsc_ns to capture_tsc and the probe's labels to match; the
counter is unscaled ticks until the SIPL headers confirm units. Jetson
source, not compiled here.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index efe1691be6..a0fbe43e01 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -32,8 +32,8 @@ thereby proven aligned.
 
 **What recording from the real Orin still needs.** The native sender must publish `capture_unix_us`, the Unix time
 of the sensor's capture event. Its only capture-event clock is the SIPL frame capture counter (`frameCaptureTSC`),
-which NVIDIA's public SIPL documentation describes as raw ARM generic-timer ticks, not nanoseconds (the `capture_tsc_ns`
-names in the sender code are misleading until units are confirmed). The deployed Orin's SIPL headers are not available
+which NVIDIA's public SIPL documentation describes as raw ARM generic-timer ticks, not nanoseconds (the sender carries it
+as `capture_tsc`, an unscaled value). The deployed Orin's SIPL headers are not available
 here, so nothing about its units or event is verified. The evidence required, from a supported platform API and
 not from fitting measurements:
 

From 2156099d916355bdc93871ee1201fd05aaafb023 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:56:45 -0800
Subject: [PATCH 25/37] egocap: show several head cameras at equal size

With only LiveKit video, every camera named head is a main view of equal
size; other cameras (wrist) stack smaller beside them.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .../frontend/src/CameraGrid.livekit.test.tsx  | 46 +++++++++++++++++++
 examples/egocap/frontend/src/CameraGrid.tsx   | 23 ++++++++--
 examples/egocap/frontend/src/styles.css       | 15 ++++++
 3 files changed, 79 insertions(+), 5 deletions(-)

diff --git a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
index 383935104c..a6135ca604 100644
--- a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
@@ -86,6 +86,52 @@ describe("CameraGrid with offered LiveKit streams", () => {
     expect(container.querySelector(".camera-tile--primary")?.textContent).toContain("Head left");
   });
 
+  it("gives two head tiles equal primary weight with the heads-only layout", async () => {
+    stubFetch(200, { token: "tok" });
+    const { container } = render(
+      <CameraGrid snapshot={snapshot([], STREAMS)} live={false} receivedAtMonotonic={null} />,
+    );
+    await settled();
+    const grid = container.querySelector<HTMLElement>(".camera-grid-items");
+    expect(grid?.className).toContain("camera-grid-items--heads");
+    expect(grid?.className).toContain("camera-grid-items--heads-only");
+    expect(grid?.style.getPropertyValue("--head-count")).toBe("2");
+    expect(container.querySelectorAll(".camera-tile--primary")).toHaveLength(2);
+  });
+
+  it("keeps a wrist tile secondary beside two primary head tiles", async () => {
+    stubFetch(200, { token: "tok" });
+    const offered = [
+      ...STREAMS,
+      { ...STREAMS[0], stream_id: 18, name: "Wrist left", track: "wrist" },
+    ];
+    const { container } = render(
+      <CameraGrid snapshot={snapshot([], offered)} live={false} receivedAtMonotonic={null} />,
+    );
+    await settled();
+    const grid = container.querySelector<HTMLElement>(".camera-grid-items");
+    expect(grid?.className).toContain("camera-grid-items--heads");
+    expect(grid?.className).not.toContain("camera-grid-items--heads-only");
+    expect(grid?.style.getPropertyValue("--head-count")).toBe("2");
+    expect(grid?.style.getPropertyValue("--side-count")).toBe("1");
+    const primary = container.querySelectorAll(".camera-tile--primary");
+    expect(primary).toHaveLength(2);
+    primary.forEach((tile) => expect(tile.textContent).toContain("Head"));
+    expect(screen.getByText("Wrist left", { exact: false }).closest(".camera-tile--primary")).toBeNull();
+  });
+
+  it("keeps the single-tile layout when only one LiveKit tile is offered", async () => {
+    stubFetch(200, { token: "tok" });
+    const { container } = render(
+      <CameraGrid snapshot={snapshot([], [STREAMS[0]])} live={false} receivedAtMonotonic={null} />,
+    );
+    await settled();
+    expect(container.querySelector(".camera-grid-items")?.className).toContain("camera-grid-items--n1");
+    const primary = container.querySelectorAll(".camera-tile--primary");
+    expect(primary).toHaveLength(1);
+    expect(primary[0].textContent).toContain("Head left");
+  });
+
   it("does not contact the backend and keeps MJPEG behavior when no streams are offered", async () => {
     const fetchFn = stubFetch(200, { token: "tok" });
     const { container, rerender } = render(<CameraGrid snapshot={null} live={false} receivedAtMonotonic={null} />);
diff --git a/examples/egocap/frontend/src/CameraGrid.tsx b/examples/egocap/frontend/src/CameraGrid.tsx
index aeadabd667..e79a257e5e 100644
--- a/examples/egocap/frontend/src/CameraGrid.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.tsx
@@ -9,6 +9,7 @@
  */
 
 import { useEffect, useRef, useState } from "react";
+import type { CSSProperties } from "react";
 import { liveKitStreams } from "./captureProtocol";
 import type { PreviewSnapshot } from "./captureProtocol";
 import { TRACKING_STALE_AFTER_MS } from "./CaptureTree";
@@ -204,15 +205,26 @@ export function CameraGrid({
   const egoIndex = cameras.findIndex((cam) => cam.name === cameraRoles?.ego);
   const headIndex = cameras.findIndex((cam) => /head/i.test(cam.name));
   const primaryIndex = egoIndex !== -1 ? egoIndex : headIndex === -1 ? 0 : headIndex;
+  // With only LiveKit video, every head camera is a main view of equal size; any other camera (a wrist camera)
+  // stacks smaller beside them. With no more than one named head, the first tile is the main view.
+  const liveKitOnly = cameras.length === 0;
+  const isHeadTile = (name: string): boolean => /head/i.test(name);
+  const headTiles = liveKitOnly ? livekit.tiles.filter((tile) => isHeadTile(tile.name)).length : 0;
+  const equalHeads = headTiles >= 2;
+  const sideTiles = livekit.tiles.length - headTiles;
+  const gridClass = equalHeads
+    ? `camera-grid-items--heads${sideTiles === 0 ? " camera-grid-items--heads-only" : ""}`
+    : `camera-grid-items--n${Math.min(cameras.length + livekit.tiles.length, 4)}`;
+  const gridStyle = equalHeads
+    ? ({ "--head-count": headTiles, "--side-count": Math.max(sideTiles, 1) } as CSSProperties)
+    : undefined;
   return (
     <section className="camera-grid">
       <h2 className="group-label">Cameras</h2>
       {livekit.phase === "error" && livekit.message !== null && (
         <p className="empty-note">LiveKit preview unavailable: {livekit.message}</p>
       )}
-      <div
-        className={`camera-grid-items camera-grid-items--n${Math.min(cameras.length + livekit.tiles.length, 4)}`}
-      >
+      <div className={`camera-grid-items ${gridClass}`} style={gridStyle}>
         {cameras.map((cam, index) => {
           const effectiveAge = cam.age_ms === null ? null : cam.age_ms + elapsedSinceReceipt;
           // "Never had a sample" (sequence/age_ms both null) is a distinct,
@@ -253,8 +265,9 @@ export function CameraGrid({
             name={tile.name}
             track={tile.track}
             phase={livekit.phase}
-            // The first LiveKit tile is the main view only when no CaptureServer camera claims that place.
-            primary={cameras.length === 0 && index === 0}
+            // A LiveKit tile is a main view only when no CaptureServer camera claims that place: every head
+            // camera when there are several, otherwise the first tile.
+            primary={liveKitOnly && (equalHeads ? isHeadTile(tile.name) : index === 0)}
           />
         ))}
       </div>
diff --git a/examples/egocap/frontend/src/styles.css b/examples/egocap/frontend/src/styles.css
index 0a23939697..adc36003c2 100644
--- a/examples/egocap/frontend/src/styles.css
+++ b/examples/egocap/frontend/src/styles.css
@@ -1929,6 +1929,21 @@ below for the narrow/stacked layout). */
   grid-row: 1 / -1;
 }
 
+/* Several head cameras share the main area in equal columns; other cameras stack smaller in the last column. */
+.op-stage .camera-grid-items--heads {
+  grid-template-columns: repeat(var(--head-count), minmax(0, 2fr)) minmax(0, 1fr);
+  grid-template-rows: repeat(var(--side-count), minmax(0, 1fr));
+}
+
+.op-stage .camera-grid-items--heads-only {
+  grid-template-columns: repeat(var(--head-count), minmax(0, 1fr));
+}
+
+.op-stage .camera-grid-items--heads .camera-tile--primary {
+  grid-column: auto;
+  grid-row: 1 / -1;
+}
+
 .op-stage .camera-tile {
   display: flex;
   flex-direction: column;

From d52c4f6e529c1d5a83d6f806e8ca3eb0c42aba75 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 08:59:19 -0800
Subject: [PATCH 26/37] sensing: log the SIPL counter uncalibrated, and state
 the encoder timestamp contract as observed

The probe no longer subtracts an unscaled counter from nanoseconds. The
encoder comments now match the Orin behaviour (returned stamp is not the
submitted one; pair by order), and the in-flight cap is described as
bounding staleness, not repairing a shifted pairing.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index a0fbe43e01..f0cf249b80 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -47,9 +47,8 @@ not from fitting measurements:
    the camera and a tracking device as the test of real alignment. The recorder's frame-age check only catches gross
    disagreement.
 
-`SENSING_TSC_PROBE=1` prints the capture counter beside the host clocks twice a second, off by default. Its
-difference includes sensor readout, ISP and dequeue delay as well as any clock offset, so it only shows the order of
-magnitude and the drift of the relation. It is not a mapping and must not be fitted or subtracted as one.
+`SENSING_TSC_PROBE=1` prints the capture counter beside the host clocks twice a second, off by default, as separate
+uncalibrated samples. The counter's units are unconfirmed, so they must not be subtracted, fitted or used as a mapping.
 
 **Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
 latency have not been run or measured. Report those as untested until someone has run them.

From 00505854cfcd28e7872e775fd76a1164726e6779 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 09:13:05 -0800
Subject: [PATCH 27/37] egocap: say what the single Orin run did and did not
 show

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index f0cf249b80..418391bd39 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -50,8 +50,11 @@ not from fitting measurements:
 `SENSING_TSC_PROBE=1` prints the capture counter beside the host clocks twice a second, off by default, as separate
 uncalibrated samples. The counter's units are unconfirmed, so they must not be subtracted, fitted or used as a mapping.
 
-**Not yet exercised on the Orin.** The publisher, the browser's acceptance of its H.264 profile and the end-to-end
-latency have not been run or measured. Report those as untested until someone has run them.
+**Exercised once on an Orin.** The author ran the publisher on an AGX Orin with two SHW5G cameras (2560x1984, 30 fps,
+H.264) into a LiveKit server on the Orin, and a PC browser showed the video. Over the run each track published about
+2,100 frames with none replaced and one capture missed on one sensor. This was a single short run on dev keys and plain
+`ws://`, not a qualification. Still unmeasured or unverified: end-to-end latency, behaviour when the encoder drops a
+frame, and real sensor-to-tracking alignment. Recording from the real Orin stays refused.
 
 ## 1. LiveKit server (on the PC or the LAN)
 

From cb0ebaef3673569ddfe11d131e3398dcc5abd033 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 14:11:12 -0800
Subject: [PATCH 28/37] egocap: stop checking in the agent-only LiveKit preview
 plan

The plan lives in the git-ignored agentPlans/ folder instead; the READMEs no
longer link to it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .gitignore                         |   3 +
 examples/egocap/LIVEKIT_PREVIEW.md | 172 -----------------------------
 examples/egocap/backend/README.md  |   2 +-
 3 files changed, 4 insertions(+), 173 deletions(-)
 delete mode 100644 examples/egocap/LIVEKIT_PREVIEW.md

diff --git a/.gitignore b/.gitignore
index 39b59ea057..dd837b9efd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -95,3 +95,6 @@ tmp/
 !/examples/mujoco_xr/python/isaacteleop_examples/mujoco_xr/assets/follower/follower_arm.xml
 # Wheel SBOM and license evidence written by the collector in scripts/sbom/
 /sbom/
+
+# Agent-only plans and status notes; never checked in.
+/agentPlans/
diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
deleted file mode 100644
index 418391bd39..0000000000
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ /dev/null
@@ -1,172 +0,0 @@
-<!--
-SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-
-SPDX-License-Identifier: Apache-2.0
--->
-
-# Live camera video over LiveKit
-
-The camera host (an Orin running the SENSING publisher) publishes hardware-encoded H.264 into a LiveKit room.
-CaptureServer says where that video is: it lists the room's cameras in the session's existing `streams` list, next to
-its other cameras, from a small file you give it. The egocap backend passes the list on and issues viewer
-tokens; the browser then connects to LiveKit itself to receive the video. No video passes through CaptureServer or
-the backend, and CaptureServer never joins the room.
-
-```text
-Orin: SIPL -> hardware H.264 -> LiveKit publisher --> LiveKit server --> browser <video>
-PC:   CaptureServer (--livekit-streams: where the streams are) -> egocap backend (list + viewer token)
-```
-
-**Recording.** A LiveKit stream is saved with a take only when its entry gives `width`, `height` and `fps` and
-declares `timestamp_basis: capture_unix_us`, meaning the publisher stamps each frame with the mapped capture time of
-the sensor event. If any offered stream does not qualify, recording is refused with that stream's name (remove it
-from the streams file, or make it recordable); preview is unaffected. The native Orin sender stamps
-`processing_unix_us` (host time after capture and conversion), so with it recording is refused until the sensor's
-capture time is mapped. The recorder joins the room itself (it needs the same `LIVEKIT_API_KEY` and
-`LIVEKIT_API_SECRET`) and checks each stream's first frame against the configured size before a take starts. The
-recorder converts the publisher's Unix time to this machine's monotonic clock and applies one coarse check: a frame
-that is more than 2 s old on arrival, or stamped in the future, ends the take. That catches gross clock disagreement
-only; it does not prove the two machines' clocks agree to milliseconds, and nothing detects a clock step. Alignment
-with tracking also assumes the backend and CaptureServer share one machine's clock. A take that passes is not
-thereby proven aligned.
-
-**What recording from the real Orin still needs.** The native sender must publish `capture_unix_us`, the Unix time
-of the sensor's capture event. Its only capture-event clock is the SIPL frame capture counter (`frameCaptureTSC`),
-which NVIDIA's public SIPL documentation describes as raw ARM generic-timer ticks, not nanoseconds (the sender carries it
-as `capture_tsc`, an unscaled value). The deployed Orin's SIPL headers are not available
-here, so nothing about its units or event is verified. The evidence required, from a supported platform API and
-not from fitting measurements:
-
-1. The counter's definition, units and event (which instant of the frame it marks) from the SIPL image-metadata
-   documentation of the deployed release, and the TSC's definition and rate in the L4T documentation of the
-   deployed JetPack. Record the exact header, SDK and L4T versions.
-2. A contemporaneous counter and host-clock reading from a supported API, so that a counter value can be placed on
-   `CLOCK_REALTIME` through one offset that is re-measured at a low rate, never per frame. Convert in the sender and
-   publish that time with the `capture_unix_us` basis, keeping the raw counter in the frame's user data.
-3. A time service between the Orin and the PC with the residual offset measured, and a physical event seen by both
-   the camera and a tracking device as the test of real alignment. The recorder's frame-age check only catches gross
-   disagreement.
-
-`SENSING_TSC_PROBE=1` prints the capture counter beside the host clocks twice a second, off by default, as separate
-uncalibrated samples. The counter's units are unconfirmed, so they must not be subtracted, fitted or used as a mapping.
-
-**Exercised once on an Orin.** The author ran the publisher on an AGX Orin with two SHW5G cameras (2560x1984, 30 fps,
-H.264) into a LiveKit server on the Orin, and a PC browser showed the video. Over the run each track published about
-2,100 frames with none replaced and one capture missed on one sensor. This was a single short run on dev keys and plain
-`ws://`, not a qualification. Still unmeasured or unverified: end-to-end latency, behaviour when the encoder drops a
-frame, and real sensor-to-tracking alignment. Recording from the real Orin stays refused.
-
-## 1. LiveKit server (on the PC or the LAN)
-
-Run a LiveKit server reachable from both the Orin and the browser, and note its API key and secret. For a quick local
-server, `livekit-server --dev --bind 0.0.0.0` uses the development key pair printed at start-up. Browsers need a
-secure context for WebRTC on anything but `localhost`, so use a `wss://` URL with a certificate the browser trusts
-when the browser is not on the server's own machine. Open the server's signalling and media ports between the machines.
-
-## 2. Tell CaptureServer where the streams are
-
-Write a file naming the room and its tracks (this is all CaptureServer needs; it never connects to LiveKit):
-
-```yaml
-livekit:
-  url: wss://LIVEKIT_HOST          # what consumers connect to
-  room: sensing-preview
-  publisher: orin-sensing          # the publisher's participant identity
-  streams:                         # up to eight
-    - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
-    - {name: Head right, track: sensing-right}
-```
-
-`width`, `height` and `fps` are optional and only describe what to expect; leave them out when unknown. Start
-CaptureServer with `--livekit-streams FILE` in addition to its usual options. The entries reach the backend in the
-session start message, so they appear once the backend's capture session has started. Offering a stream does not mean
-frames are arriving.
-
-## 3. Backend credentials
-
-The backend signs viewer tokens with the server's key pair, read from its environment only:
-
-```bash
-export LIVEKIT_API_KEY=...      # the LiveKit server's API key
-export LIVEKIT_API_SECRET=...   # its secret
-```
-
-`GET /api/livekit-token?room=ROOM` returns a token that can join that room and subscribe, nothing more. It answers 404
-for a room the session does not offer and 503 when the key pair is not set. Like the camera preview routes it is open
-to anyone who can reach the backend, so keep the backend on a trusted network. Missing credentials stop the video but
-the stream list is still shown.
-
-## 4. Orin publisher
-
-Create a token file for the publisher: a LiveKit token for this room, with identity equal to `publisher` above,
-allowed to publish (for example with LiveKit's `lk token create`; see its `--help`). Then add the LiveKit options to
-the usual `camera_plugin_sensing` invocation, keeping the rig's own platform and configuration arguments:
-
-```bash
-camera_plugin_sensing ... \
-  --livekit-url=wss://LIVEKIT_HOST --livekit-token-file=join.token \
-  --add-stream=sensor=0,livekit=sensing-left \
-  --add-stream=sensor=1,livekit=sensing-right
-```
-
-The `livekit=` names must equal the file's `track` values. Start the publisher by hand; closing the browser
-disconnects only that viewer, and the Orin keeps capturing until you stop it.
-
-## 5. Expected result and troubleshooting
-
-Opening egocap shows the named tiles next to the tracking view. A tile reads "Waiting for camera" until its track is
-published, "No video frames" if a published track stops producing frames, and "Disconnected" while the room
-connection is down; the page reconnects on its own.
-
-| Symptom | Check |
-| --- | --- |
-| No tiles at all | CaptureServer was started with `--livekit-streams`, and the backend's capture session has started. |
-| "LiveKit preview unavailable: ... must be set" | `LIVEKIT_API_KEY` and `LIVEKIT_API_SECRET` in the backend's environment. |
-| Tiles never leave "Connecting" | The `url` is reachable from the browser; `wss://` certificate trusted; signalling and media ports open. |
-| Connected, tile stays "Waiting for camera" | The publisher's token room and identity match `room` and `publisher`; `livekit=` names match `track`. |
-| "Waiting for video" or black picture | The browser may not support the encoder's H.264 profile; check the browser console. |
-
-## 5. No Orin: the emulator
-
-`tools/livekit_orin_emulator.py` publishes test-pattern tracks with the same per-frame metadata (`user_timestamp`,
-`frame_id`, 8-byte little-endian capture counter) in place of the Orin. It uses the SDK's software encoder, so it
-exercises the PC side and the metadata contract but not the Jetson hardware encoder, its H.264 profile or the real
-sender's pacing.
-
-```bash
-uv run python tools/livekit_orin_emulator.py \
-  --livekit-url=wss://LIVEKIT_HOST --livekit-token-file=join.token \
-  --add-stream=sensor=0,livekit=sensing-left --add-stream=sensor=1,livekit=sensing-right \
-  --width=1280 --height=720 --fps=30 --timestamp-basis=capture_unix_us
-```
-
-`--timestamp-basis=processing_unix_us` declares what the current native sender sends: processing time, which is not
-a capture time and is not recorded. `capture_unix_us` (the default) is honest here because the emulator is the
-camera: it stamps the frame when it generates it. `monotonic_us` sends the publisher's monotonic clock, also not
-recordable.
-
-## 6. The whole stack on one machine, with the emulator
-
-This runs everything except the Orin on one machine, against a local LiveKit server in development mode (key
-`devkey`, secret `secret`). Each command runs in its own terminal, from `examples/egocap/`.
-
-```bash
-livekit-server --dev --bind 127.0.0.1                    # signalling on ws://127.0.0.1:7880
-
-# pub.token: a token for room sensing-preview, identity orin-sensing, allowed to publish (lk token create, or any
-# LiveKit token tool, signed with devkey/secret)
-uv run python tools/livekit_orin_emulator.py --livekit-url=ws://127.0.0.1:7880 --livekit-token-file=pub.token \
-  --add-stream=sensor=0,livekit=sensing-left --add-stream=sensor=1,livekit=sensing-right \
-  --width=640 --height=480 --fps=15 --timestamp-basis=capture_unix_us
-
-uv run capture-server --mock --livekit-streams streams.yaml
-LIVEKIT_API_KEY=devkey LIVEKIT_API_SECRET=secret uv run uvicorn egocap_web.app:app --app-dir backend --port 8000
-```
-
-`streams.yaml` names the room, the publisher and both tracks, with `width: 640`, `height: 480`, `fps: 15` and
-`timestamp_basis: capture_unix_us` (section 2). Open `http://127.0.0.1:8000/`: both tiles show live video, and
-Record saves a take with the two cameras next to the mock tracking. A take recorded this way came out KEPT, with 91
-frames per camera over 6 s at the configured size and rate and increasing capture times.
-
-This exercises the PC side only. It does not test the Jetson encoder, the sender's pacing, or clock agreement
-between two machines.
diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md
index ecd31b8cc8..479e41e576 100644
--- a/examples/egocap/backend/README.md
+++ b/examples/egocap/backend/README.md
@@ -33,7 +33,7 @@ or restarts it.
 | `GET`/`PUT /api/operator-settings` | The operator's station setup: the camera type (`sensing_gmsl` or `oak_d`), camera roles (`ego`, `wrist_left`, `wrist_right`), the task catalog the recording panel's picker offers (`task_file`) and the task it preselects (`preselected_task`). Kept in `.egocap/operator_settings.json` under the recording output (hidden from the recordings browser) (`EGOCAP_OPERATOR_SETTINGS_FILE` overrides the path) so every browser sees the same values. `PUT` names only the fields it changes and uses `X-Control-Token`; legacy JSON `control_token` remains accepted. A wrong token is 403 and bodies above 16 KiB are rejected with 413 before parsing. |
 | `POST /api/task-files/import`, `DELETE /api/task-files/{name}` | Import a task catalog the operator supplies — by `name` + `content` (text uploaded from the browser) — into the imported-catalog directory beside the operator settings, once it parses; and remove an imported one. `POST` and `DELETE` use the `X-Control-Token` header (legacy JSON tokens remain accepted for `POST`); `DELETE` refuses removal of the selected catalog (409); imports also refuse replacement of that catalog until it is deselected. Imports appear in `GET /api/task-files` (as `imported`) and shadow a shipped catalog of the same name. |
 | `GET /api/tools` | The operator tools the Settings drawer offers (headset calibration, glove calibration, fisheye rectification for the SENSING cameras), each with whether this build can launch it. None can yet. |
-| `GET /api/livekit-token?room=ROOM` | Subscribe-only viewer token for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. See [`../LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md). |
+| `GET /api/livekit-token?room=ROOM` | Subscribe-only viewer token for a LiveKit room the session offers (404 otherwise, 503 without signing credentials). Which streams exist comes from CaptureServer's session message. |
 | `GET /api/task-files`, `GET /api/task-files/{name}` | Read-only task-catalog API; see [`../data/taskfiles/README.md`](../data/taskfiles/README.md). |
 | `GET /recordings/...` | The optional recordings browser's API and file routes, off unless `EGOCAP_RECORDINGS_ENABLED=1`; see [`../recordings_frontend/README.md`](../recordings_frontend/README.md). |
 

From 542a8f5ffce17ba14bfc5f038f6117e2f445ef26 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 17:08:10 -0800
Subject: [PATCH 29/37] egocap: address review findings in the LiveKit
 recording backend

Size the recording ingress and the receiver queues from the recordable LiveKit
frame geometry, so a stalled writer no longer fails a take at full-size
frames. A reader task that fails now marks its stream lost instead of
stopping silently. Bound the room leave during teardown and the wait for the
join without cancelling either call, refuse LiveKit recording when
CaptureServer is not on this machine, and make discarded awaits explicit.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/backend/README.md             |  2 +-
 examples/egocap/backend/egocap_web/app.py     | 67 ++++++++++---
 .../backend/egocap_web/livekit_receiver.py    | 23 ++++-
 .../backend/egocap_web/livekit_recording.py   | 95 ++++++++++++++++--
 .../backend/egocap_web/recording_session.py   |  5 +-
 .../backend/test_app_livekit_recording.py     | 96 +++++++++++++++++++
 .../tests/backend/test_livekit_receiver.py    | 32 ++++++-
 .../tests/backend/test_livekit_recording.py   | 17 ++++
 .../backend/test_livekit_recording_source.py  | 71 ++++++++++++--
 .../tests/tools/test_livekit_orin_emulator.py |  2 +-
 10 files changed, 372 insertions(+), 38 deletions(-)

diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md
index 479e41e576..f11ac231ec 100644
--- a/examples/egocap/backend/README.md
+++ b/examples/egocap/backend/README.md
@@ -55,7 +55,7 @@ Everything else is an environment variable:
 | --- | --- | --- |
 | `EGOCAP_STATION_CONFIG` | unset (development default) | Path to the deployment station YAML described above. |
 | `EGOCAP_CAPTURE_SERVER_URL` | `ws://127.0.0.1:8082` | Where to connect for tracking/camera data. |
-| `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | unset | The LiveKit server's key pair, used only to sign viewer tokens for `GET /api/livekit-token`. |
+| `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET` | unset | The LiveKit server's key pair. The backend signs two subscribe-only tokens with it: viewer tokens for `GET /api/livekit-token`, and the recorder's own token. LiveKit recording will not start without both variables; see [`LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md). |
 | `EGOCAP_TASK_FILES_DIR` | the shipped `data/taskfiles/` | Which task-catalog directory the task-file API serves. |
 | `EGOCAP_RECORDINGS_ENABLED` | off | Turns on the recordings browser's routes. |
 | `EGOCAP_ALLOWED_ORIGINS` | none (same-origin only) | Comma-separated extra origins allowed to open `WS /api/session` — needed when the frontend is hosted separately or behind a reverse proxy. |
diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index 20226e16d6..41e8672770 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -17,7 +17,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import replace
 from pathlib import Path
-from typing import AsyncIterator
+from typing import Any, AsyncIterator
 
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
@@ -39,6 +39,7 @@
 from .operator_settings import router as operator_settings_router
 from .livekit_preview import API_KEY_ENV, API_SECRET_ENV, subscriber_token
 from .livekit_preview import router as livekit_preview_router
+from .livekit_receiver import RECEIVER_FRAMES_PER_STREAM
 from .livekit_recording import LiveKitRecordingSource, recordable_livekit_streams, unrecordable_reason
 from .preview_routes import router as preview_router
 from .recording_adapter import (
@@ -74,7 +75,9 @@
 # independently, each of these would look individually reasonable while
 # still summing to far more memory than intended -- see
 # _recording_config_factory below for how the decoded-queue capacity is
-# derived from what's left after the raw side's own reservation.
+# derived from what's left after the raw side's own reservation. The
+# LiveKit streams' own ingress share and receiver queues are added on top
+# per take (they scale with the stream geometry), not carved out of this.
 _RECORDING_QUEUE_MEMORY_BUDGET_BYTES = 256 * 1024 * 1024
 
 # RecordingIngress's own raw-item queue, per take -- items queued here are
@@ -83,14 +86,37 @@
 # blob (a typical camera frame is a few hundred KB, so this holds seconds
 # of 60 Hz tracking plus two or three 30 fps cameras, where an 8-slot count
 # held ~50 ms). _INGRESS_QUEUE_CAPACITY is only a safety cap on item count.
-# The reservation adds one MAX_CAMERA_JPEG_BYTES for the raw item held live
-# in the executor during conversion (capture_preview.py's own cap, not a
-# locally-assumed "typical" size). Fixed at coordinator-construction time,
-# before any camera is necessarily known, so unlike the decoded queue below
-# it cannot be sized from real resolution.
+# The reservation adds one raw item held live in the executor during
+# conversion: MAX_CAMERA_JPEG_BYTES (capture_preview.py's own cap), or a
+# LiveKit stream's decoded frame when that is larger.
 _INGRESS_QUEUE_BYTES = 64 * 1024 * 1024
 _INGRESS_QUEUE_CAPACITY = 4096
-_INGRESS_RESERVED_BYTES = _INGRESS_QUEUE_BYTES + MAX_CAMERA_JPEG_BYTES
+# LiveKit frames are decoded RGB (megabytes each, ~15 MB at 2560x1984), so
+# the JPEG allowance above holds only a few and a short consumer stall would
+# fail the take. Each recordable stream therefore adds this many of its own
+# frames to the ingress queue, and the receiver's queues (see
+# livekit_receiver.RECEIVER_FRAMES_PER_STREAM) are added to the total budget.
+_LIVEKIT_INGRESS_FRAMES_PER_STREAM = 6
+
+
+def _livekit_frame_bytes(started: Any) -> list[int]:
+    """Decoded RGB size of one frame of each LiveKit stream a take would record."""
+    return [s.width * s.height * 3 for s in recordable_livekit_streams(started)]
+
+
+def _livekit_ingress_bytes(started: Any) -> int:
+    """Extra raw-ingress bytes the recordable LiveKit streams need."""
+    return sum(_livekit_frame_bytes(started)) * _LIVEKIT_INGRESS_FRAMES_PER_STREAM
+
+
+def _livekit_receiver_bytes(started: Any) -> int:
+    """Worst-case bytes the LiveKit receiver's own queues pin for the recordable streams."""
+    return sum(_livekit_frame_bytes(started)) * RECEIVER_FRAMES_PER_STREAM
+
+
+def _ingress_queue_bytes(started: Any) -> int:
+    """The raw-ingress byte bound of a take: the JPEG/tracking allowance plus the LiveKit frames' share."""
+    return _INGRESS_QUEUE_BYTES + _livekit_ingress_bytes(started)
 
 
 def _recording_output_root(station_data_dir: Path | None = None) -> Path:
@@ -178,9 +204,16 @@ def factory() -> ServiceConfig:
             # one in the real service's own writer (the sample it has
             # already dequeued and is actively encoding). Genuinely bounds
             # the combined worst case at _RECORDING_QUEUE_MEMORY_BUDGET_BYTES.
-            decoded_queue_budget = (
-                _RECORDING_QUEUE_MEMORY_BUDGET_BYTES - _INGRESS_RESERVED_BYTES - 2 * largest_decoded_frame_bytes
+            started = monitor.native.started
+            # The live raw item is a JPEG, or a LiveKit stream's decoded frame when that is larger.
+            live_item_bytes = max([MAX_CAMERA_JPEG_BYTES, *_livekit_frame_bytes(started)])
+            reserved = _ingress_queue_bytes(started) + live_item_bytes
+            total = (
+                _RECORDING_QUEUE_MEMORY_BUDGET_BYTES
+                + _livekit_ingress_bytes(started)
+                + _livekit_receiver_bytes(started)
             )
+            decoded_queue_budget = total - reserved - 2 * largest_decoded_frame_bytes
             capacity = decoded_queue_budget // largest_decoded_frame_bytes
             if capacity < 1:
                 # A silent floor here would claim a cap that doesn't
@@ -207,7 +240,11 @@ def factory() -> ServiceConfig:
 _READINESS_STALE_SECONDS = 2.0
 
 
-def _recording_readiness_check(monitor: CaptureStatusMonitor, station_config_error: str | None = None):
+def _recording_readiness_check(
+    monitor: CaptureStatusMonitor,
+    station_config_error: str | None = None,
+    capture_server_url: str | None = None,
+):
     """Real backend-local capture facts, injected into the coordinator --
     it never imports CaptureStatusMonitor/CaptureClient itself (see
     recording_session.py's own module docstring). Checked at start_episode
@@ -223,6 +260,8 @@ def _recording_readiness_check(monitor: CaptureStatusMonitor, station_config_err
     received within the staleness window -- not merely "ever arrived
     once."
 
+    ``capture_server_url`` lets LiveKit recording be refused when CaptureServer is not on this machine.
+
     ``station_config_error``, when set, unconditionally blocks new recording
     admission with that reason -- a configured-but-invalid station YAML
     must never silently fall back to a development default, but it must
@@ -244,7 +283,7 @@ def check() -> tuple[bool, str | None]:
         if tracking is None or (now - tracking.received_monotonic) > _READINESS_STALE_SECONDS:
             return False, "tracking source is stale or has no sample yet"
         # An offered LiveKit stream that cannot be recorded blocks recording by name, never silently dropped.
-        blocked = unrecordable_reason(monitor.native.started)
+        blocked = unrecordable_reason(monitor.native.started, capture_server_url)
         if blocked is not None:
             return False, blocked
         cameras = monitor.camera_descriptors
@@ -356,8 +395,8 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
     coordinator = RecordingSessionCoordinator(
         _recording_config_factory(monitor, config.station_label, recording_output_root),
         queue_capacity=_INGRESS_QUEUE_CAPACITY,
-        queue_bytes=_INGRESS_QUEUE_BYTES,
-        readiness_check=_recording_readiness_check(monitor, station_config_error),
+        queue_bytes=lambda: _ingress_queue_bytes(monitor.native.started),
+        readiness_check=_recording_readiness_check(monitor, station_config_error, config.capture_server_url),
         initial_context=initial_context,
         livekit_source=livekit_source,
     )
diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
index 9c3f7a2057..6e259ce7a2 100644
--- a/examples/egocap/backend/egocap_web/livekit_receiver.py
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -30,10 +30,13 @@
 logger = logging.getLogger("isaaccapture.egocap.livekit_receiver")
 
 #: Frames a stream may hold between the SDK and the consumer before further frames are dropped and counted.
-DEFAULT_QUEUE_FRAMES = 8
+#: Decoded frames are megabytes each, so the queues are short and sized into the recorder's memory budget.
+DEFAULT_QUEUE_FRAMES = 2
 #: The SDK keeps only this many undelivered frames per track and drops the oldest silently; its drops show up
 #: as a jump in the publisher's frame id, which is counted below.
-_SDK_QUEUE_FRAMES = 16
+SDK_QUEUE_FRAMES = 2
+#: Frames one stream can pin at once with default queues: both queues plus the one the reader is converting.
+RECEIVER_FRAMES_PER_STREAM = DEFAULT_QUEUE_FRAMES + SDK_QUEUE_FRAMES + 1
 
 
 @dataclass(frozen=True)
@@ -108,7 +111,7 @@ async def start(self) -> None:
         room.on("track_unsubscribed", self._on_track_unsubscribed)
         room.on("participant_disconnected", self._on_participant_disconnected)
         room.on("disconnected", self._on_disconnected)
-        await room.connect(self._url, self._token)
+        _ = await room.connect(self._url, self._token)
         # Tracks published before we joined arrive here rather than through track_subscribed.
         for participant in room.remote_participants.values():
             for publication in participant.track_publications.values():
@@ -185,6 +188,10 @@ def _detach(self, stream_id: int) -> None:
         task = self._readers.pop(stream_id, None)
         if task is not None:
             task.cancel()
+        self._mark_lost(stream_id)
+
+    def _mark_lost(self, stream_id: int) -> None:
+        """Record that ``stream_id`` can deliver no more frames, without cancelling the calling reader task."""
         self.counters[stream_id].subscribed = False
         self._lost[stream_id].set()
 
@@ -215,7 +222,8 @@ def _on_disconnected(self, *_: object) -> None:
     async def _read(self, stream_id: int, track: rtc.Track) -> None:
         """Take frames of one track from the SDK, convert them, and queue them for the consumer."""
         counters = self.counters[stream_id]
-        video = rtc.VideoStream(track, capacity=_SDK_QUEUE_FRAMES, format=rtc.VideoBufferType.RGB24)
+        this_task = asyncio.current_task()
+        video = rtc.VideoStream(track, capacity=SDK_QUEUE_FRAMES, format=rtc.VideoBufferType.RGB24)
         try:
             async for event in video:
                 received_at = time.monotonic_ns()
@@ -241,6 +249,13 @@ async def _read(self, stream_id: int, track: rtc.Track) -> None:
                 except asyncio.QueueFull:
                     # Never block the reader or skip silently: the consumer is behind, and the loss is counted.
                     counters.queue_overflow += 1
+        except Exception:
+            # A dead reader would leave the consumer waiting forever; marking the stream lost lets the take settle.
+            # Only the reader still registered for the stream may do so: a replaced one is already superseded.
+            logger.exception("LiveKit reader for stream %d failed", stream_id)
+            if self._readers.get(stream_id) is this_task:
+                self._readers.pop(stream_id)
+                self._mark_lost(stream_id)
         finally:
             await video.aclose()
 
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index cf1eb5c472..23b3ab34f2 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -9,18 +9,20 @@
 monotonic clock or with its processing time is not a capture time, so the feed stops with that reason instead of
 recording a guessed one. Arrival time is never used as capture time.
 
-This assumes the backend runs on the machine whose monotonic clock CaptureServer reports: tracking times come from
-CaptureServer, and the two agree only when both processes share a clock.
+Tracking times come from CaptureServer's monotonic clock, which agrees with this process's only when both run on
+one machine, so recording LiveKit video is refused unless CaptureServer's URL is a loopback address.
 """
 
 from __future__ import annotations
 
 import asyncio
 import contextlib
+import ipaddress
 import logging
 import time
 from collections.abc import Callable, Mapping, Sequence
 from typing import Any
+from urllib.parse import urlparse
 
 from capture_server import protocol as p
 from recording_service import PixelFormat, VideoSample
@@ -39,6 +41,10 @@
 _MAX_FRAME_LEAD_S = 0.05
 #: Readings per pair; the one read in the shortest span is the most trustworthy.
 _PAIR_ATTEMPTS = 3
+#: How long the room join may take before the take's start is refused.
+_JOIN_TIMEOUT_S = 15.0
+#: How long leaving the room may take before teardown moves on and lets the leave finish in the background.
+_LEAVE_TIMEOUT_S = 10.0
 
 
 class UnixClockMap:
@@ -83,17 +89,34 @@ def _measure(self) -> None:
         self._measured_at_ns = self._monotonic_ns()
 
 
-def unrecordable_reason(started: Any) -> str | None:
+def is_loopback_url(url: str) -> bool:
+    """Whether ``url`` names this machine: ``localhost`` or a loopback IP literal."""
+    host = urlparse(url).hostname or ""
+    if host.lower() == "localhost":
+        return True
+    try:
+        return ipaddress.ip_address(host).is_loopback
+    except ValueError:
+        return False
+
+
+def unrecordable_reason(started: Any, capture_server_url: str | None = None) -> str | None:
     """Why a started session's LiveKit streams cannot all be recorded, naming the first that cannot; else None.
 
     A stream that cannot be recorded is never left out of a take silently: recording is refused until it is
-    removed from the streams file or made recordable.
+    removed from the streams file or made recordable. When ``capture_server_url`` is given and is not a
+    loopback address, every LiveKit stream is refused because the clocks cannot be assumed to be shared.
     """
     if started is None:
         return None
     for stream in started.streams:
         if not isinstance(stream, p.LiveKitCameraStream):
             continue
+        if capture_server_url is not None and not is_loopback_url(capture_server_url):
+            return (
+                f"LiveKit stream {stream.name!r}: recording needs CaptureServer on this machine "
+                f"(its clock must match tracking's), but it is at {capture_server_url!r}"
+            )
         if stream.timestamp_basis is not p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US:
             return (
                 f"LiveKit stream {stream.name!r}: its timestamps are not a capture time, so it cannot be recorded"
@@ -143,7 +166,7 @@ async def stop(self) -> None:
             task.cancel()
         for task in self._tasks:
             with contextlib.suppress(asyncio.CancelledError):
-                await task
+                _ = await task
         self._tasks = []
 
     def _fail(self, reason: str) -> None:
@@ -226,10 +249,16 @@ def __init__(
         make_token: Callable[[str], str],
         *,
         first_frame_timeout_s: float = 10.0,
+        join_timeout_s: float = _JOIN_TIMEOUT_S,
+        leave_timeout_s: float = _LEAVE_TIMEOUT_S,
     ) -> None:
         self._recordable_streams = recordable_streams
         self._make_token = make_token
         self._first_frame_timeout_s = first_frame_timeout_s
+        self._join_timeout_s = join_timeout_s
+        self._leave_timeout_s = leave_timeout_s
+        # Room joins and leaves that outlived their deadline; held so they are not garbage-collected mid-flight.
+        self._background: set[asyncio.Future[None]] = set()
         self._streams: tuple[p.LiveKitCameraStream, ...] = ()
         self._receiver: LiveKitFrameReceiver | None = None
         self._feed: LiveKitRecordingFeed | None = None
@@ -246,7 +275,7 @@ async def prepare(self) -> None:
         receiver = LiveKitFrameReceiver(self._streams, self._make_token(self._streams[0].room))
         self._receiver = receiver
         try:
-            await receiver.start()
+            await self._join(receiver)
             for stream in self._streams:
                 frame = await asyncio.wait_for(
                     receiver.next_frame_or_lost(stream.stream_id), self._first_frame_timeout_s
@@ -265,6 +294,51 @@ async def prepare(self) -> None:
             await self.stop()
             raise
 
+    async def _join(self, receiver: LiveKitFrameReceiver) -> None:
+        """Run ``receiver.start()`` with a deadline on the wait, never on the join itself.
+
+        Cancelling ``Room.connect`` can strand the SDK's room-event handshake, so a join that is late (or whose
+        caller is cancelled) keeps running and the receiver is retired once it finishes.
+        """
+        join = asyncio.ensure_future(receiver.start())
+        try:
+            _ = await asyncio.wait({join}, timeout=self._join_timeout_s)
+        except BaseException:
+            self._retire_after_join(join, receiver)
+            raise
+        if not join.done():
+            self._retire_after_join(join, receiver)
+            raise RuntimeError(f"joining the LiveKit room took longer than {self._join_timeout_s:g} s")
+        # A join that failed raises here, with the receiver still ours to stop.
+        join.result()
+
+    def _retire_after_join(self, join: asyncio.Future[None], receiver: LiveKitFrameReceiver) -> None:
+        """Hand an unfinished join to a background task that leaves the room as soon as the join ends."""
+        if join.done():
+            return
+        # This source no longer owns the receiver: stop() must not leave a room that is still being joined.
+        self._receiver = None
+        self._background.add(join)
+
+        def _leave(done: asyncio.Future[None]) -> None:
+            self._background.discard(done)
+            if not done.cancelled() and done.exception() is not None:
+                logger.warning("late LiveKit room join failed: %s", done.exception())
+            self._track(asyncio.ensure_future(receiver.stop()), "leaving the room after a late join")
+
+        join.add_done_callback(_leave)
+
+    def _track(self, task: asyncio.Future[None], what: str) -> None:
+        """Keep a background task referenced until it ends, logging a failure instead of losing it."""
+        self._background.add(task)
+
+        def _done(finished: asyncio.Future[None]) -> None:
+            self._background.discard(finished)
+            if not finished.cancelled() and finished.exception() is not None:
+                logger.warning("%s failed: %s", what, finished.exception())
+
+        task.add_done_callback(_done)
+
     def start(self, ingress: RecordingIngress, on_failure: Callable[[str], None]) -> None:
         """Begin feeding the take's ingress with frames acquired from now on."""
         if self._receiver is None:
@@ -284,4 +358,11 @@ async def stop(self) -> None:
         if feed is not None:
             await feed.stop()
         if receiver is not None:
-            await receiver.stop()
+            # A stalled room leave must not block retiring the take's ingress; it is left to finish on its own.
+            leave = asyncio.ensure_future(receiver.stop())
+            self._track(leave, "leaving the LiveKit room")
+            _ = await asyncio.wait({leave}, timeout=self._leave_timeout_s)
+            if not leave.done():
+                logger.warning(
+                    "leaving the LiveKit room took longer than %g s; continuing teardown", self._leave_timeout_s
+                )
diff --git a/examples/egocap/backend/egocap_web/recording_session.py b/examples/egocap/backend/egocap_web/recording_session.py
index 47a346ccd9..6737097556 100644
--- a/examples/egocap/backend/egocap_web/recording_session.py
+++ b/examples/egocap/backend/egocap_web/recording_session.py
@@ -183,7 +183,7 @@ def __init__(
         config_factory: Callable[[], ServiceConfig],
         *,
         queue_capacity: int,
-        queue_bytes: int | None = None,
+        queue_bytes: int | Callable[[], int] | None = None,
         readiness_check: ReadinessCheck,
         initial_context: TaskContext | None = None,
         livekit_source: LiveKitRecordingSource | None = None,
@@ -460,9 +460,10 @@ async def _start_episode_with_storage(self, frozen_context: TaskContext) -> Epis
                 await service.discard_episode(episode.episode_id)
             raise CoordinatorBusyError("start was superseded before activation")
         episode_id = episode.episode_id
+        # A callable is resolved per take: LiveKit frame sizes are known only once the session has started.
         ingress = RecordingIngress(
             queue_capacity=self._queue_capacity,
-            queue_bytes=self._queue_bytes,
+            queue_bytes=self._queue_bytes() if callable(self._queue_bytes) else self._queue_bytes,
             submit=partial(service.submit_sample, episode_id),
             on_failure=lambda message: self._schedule_failure_settlement(service, episode_id, message),
         )
diff --git a/examples/egocap/tests/backend/test_app_livekit_recording.py b/examples/egocap/tests/backend/test_app_livekit_recording.py
index 76e32702c4..aaa720f35a 100644
--- a/examples/egocap/tests/backend/test_app_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_app_livekit_recording.py
@@ -9,10 +9,14 @@
 import time
 from types import SimpleNamespace
 
+import numpy as np
 import pytest
 
 from capture_server import protocol as p
 from egocap_web import app as app_module
+from egocap_web.livekit_receiver import RECEIVER_FRAMES_PER_STREAM
+from egocap_web.recording_adapter import RecordingIngress
+from recording_service import PixelFormat, VideoSample
 
 
 def _stream(stream_id: int, basis, width=6) -> p.LiveKitCameraStream:
@@ -117,3 +121,95 @@ def test_readiness_names_a_stream_without_geometry(accepted_tracking):
     stream = _stream(16, p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US, width=None)
     check = app_module._recording_readiness_check(_ready_monitor([stream]), None)
     assert check() == (False, "LiveKit stream 'cam16': width, height and fps must be configured to record it")
+
+
+# --- memory budget with full-size decoded frames -------------------------------
+
+FULL_WIDTH, FULL_HEIGHT = 2560, 1984
+
+
+def _full_size_streams(count):
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    return [_full(16 + i, capture) for i in range(count)]
+
+
+def _full(stream_id, basis):
+    return p.LiveKitCameraStream(
+        stream_id=stream_id,
+        name=f"cam{stream_id}",
+        url="wss://lk",
+        room="r",
+        publisher="o",
+        track=f"t{stream_id}",
+        timestamp_basis=basis,
+        width=FULL_WIDTH,
+        height=FULL_HEIGHT,
+        fps=30.0,
+    )
+
+
+def test_full_size_livekit_frames_fit_ordinary_back_pressure_in_the_ingress():
+    started = SimpleNamespace(streams=_full_size_streams(2))
+    frame_bytes = FULL_WIDTH * FULL_HEIGHT * 3
+    ingress = RecordingIngress(
+        queue_capacity=4096,
+        queue_bytes=app_module._ingress_queue_bytes(started),
+        submit=lambda sample: None,
+    )
+    image = np.zeros((FULL_HEIGHT, FULL_WIDTH, 3), dtype=np.uint8)
+    sample = VideoSample(
+        source="cam16", image=image, pixel_format=PixelFormat.RGB8, capture_time=1.0, receive_time=1.0
+    )
+    # About 200 ms of a stalled consumer at 30 fps on two streams.
+    assert all(ingress.offer(sample) for _ in range(12))
+    assert ingress.failure is None
+    assert app_module._ingress_queue_bytes(started) >= 12 * frame_bytes
+
+
+def test_config_factory_with_two_full_size_streams_fits_its_total_budget(tmp_path):
+    started = SimpleNamespace(streams=_full_size_streams(2))
+    monitor = SimpleNamespace(camera_descriptors=(), native=SimpleNamespace(started=started))
+    config = app_module._recording_config_factory(monitor, None, tmp_path)()
+    frame_bytes = FULL_WIDTH * FULL_HEIGHT * 3
+    total = (
+        app_module._RECORDING_QUEUE_MEMORY_BUDGET_BYTES
+        + app_module._livekit_ingress_bytes(started)
+        + app_module._livekit_receiver_bytes(started)
+    )
+    held = (
+        app_module._ingress_queue_bytes(started)
+        + max(app_module.MAX_CAMERA_JPEG_BYTES, frame_bytes)
+        + (config.queue_capacity + 2) * frame_bytes
+    )
+    assert config.queue_capacity >= 1
+    assert held <= total
+
+
+def test_receiver_queues_are_part_of_the_livekit_budget():
+    started = SimpleNamespace(streams=_full_size_streams(2))
+    frame_bytes = FULL_WIDTH * FULL_HEIGHT * 3
+    assert app_module._livekit_receiver_bytes(started) == 2 * frame_bytes * RECEIVER_FRAMES_PER_STREAM
+
+
+def test_without_livekit_streams_the_ingress_budget_is_the_jpeg_allowance():
+    assert app_module._ingress_queue_bytes(None) == app_module._INGRESS_QUEUE_BYTES
+
+
+# --- recording needs CaptureServer on this machine -----------------------------
+
+
+def test_readiness_refuses_livekit_recording_when_capture_server_is_remote(accepted_tracking):
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    check = app_module._recording_readiness_check(
+        _ready_monitor([_stream(16, capture)]), None, "ws://10.0.0.5:8082"
+    )
+    ready, reason = check()
+    assert not ready and "CaptureServer on this machine" in reason
+
+
+def test_readiness_accepts_livekit_recording_with_a_loopback_capture_server(accepted_tracking):
+    capture = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
+    check = app_module._recording_readiness_check(
+        _ready_monitor([_stream(16, capture)]), None, "ws://127.0.0.1:8082"
+    )
+    assert check() == (True, None)
diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
index dbbb19f424..686a6d03fa 100644
--- a/examples/egocap/tests/backend/test_livekit_receiver.py
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -134,7 +134,8 @@ def fake_sdk(monkeypatch: pytest.MonkeyPatch) -> None:
 
 @pytest.fixture
 async def receiver():
-    rx = lr.LiveKitFrameReceiver([camera(1, "left"), camera(2, "right")], TOKEN)
+    # Deeper than the default queues so these tests exercise accounting, not the memory-budget-sized back-pressure.
+    rx = lr.LiveKitFrameReceiver([camera(1, "left"), camera(2, "right")], TOKEN, queue_frames=8)
     await rx.start()
     yield rx
     await rx.stop()
@@ -207,7 +208,7 @@ def __init__(self) -> None:
         left.push(event(7, frame_id=1))
         assert (await asyncio.wait_for(rx.next_frame(1), 1)).frame_id == 1
         stream = FakeVideoStream.instances[0]
-        assert stream.capacity == lr._SDK_QUEUE_FRAMES and stream.format == "rgb24"
+        assert stream.capacity == lr.SDK_QUEUE_FRAMES and stream.format == "rgb24"
     finally:
         await rx.stop()
 
@@ -575,7 +576,7 @@ async def test_cancelling_a_waiter_leaves_no_helper_tasks(receiver):
     await settle()
     waiter.cancel()
     with pytest.raises(asyncio.CancelledError):
-        await waiter
+        _ = await waiter
     await settle()
     assert _only_test_tasks() == baseline
 
@@ -633,3 +634,28 @@ async def test_clear_queued_drops_every_queued_frame(receiver):
     assert receiver.pending(1) > 0
     receiver.clear_queued()
     assert receiver.pending(1) == receiver.pending(2) == 0
+
+
+# ---- reader failure ----
+
+
+async def test_a_failing_reader_marks_its_stream_lost_and_logs(receiver, caplog):
+    track = subscribe(receiver, "left")
+    bad = event(1, frame_id=1)
+    bad.frame.height = 99  # the buffer no longer matches the stated size
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    track.push(bad)
+    assert await asyncio.wait_for(waiter, 1) is None
+    assert not receiver.counters[1].subscribed
+    assert "reader for stream 1 failed" in caplog.text
+    assert FakeVideoStream.instances[0].closed == 1
+
+
+async def test_a_failing_reader_leaves_the_other_stream_running(receiver):
+    left, right = subscribe(receiver, "left"), subscribe(receiver, "right")
+    bad = event(1)
+    bad.frame.width = 99
+    left.push(bad)
+    right.push(event(5, frame_id=1))
+    assert (await asyncio.wait_for(receiver.next_frame(2), 1)).image[0, 0, 0] == 5
+    assert receiver.counters[2].subscribed and not receiver.counters[1].subscribed
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index 98ac723dad..1448713c96 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -525,3 +525,20 @@ def test_unrecordable_reason_names_a_stream_missing_geometry(field):
 
 def test_unrecordable_reason_ignores_streams_that_are_not_livekit():
     assert unrecordable_reason(_started(object(), _geometry(16))) is None
+
+
+@pytest.mark.parametrize(
+    "url", ["ws://127.0.0.1:8082", "ws://localhost:8082", "ws://[::1]:8082", "ws://127.0.0.2"]
+)
+def test_unrecordable_reason_accepts_a_loopback_capture_server(url):
+    assert unrecordable_reason(_started(_geometry(16)), url) is None
+
+
+@pytest.mark.parametrize("url", ["ws://192.168.1.20:8082", "ws://capture.lan:8082", "ws://[2001:db8::1]:8082"])
+def test_unrecordable_reason_refuses_a_capture_server_on_another_host(url):
+    reason = unrecordable_reason(_started(_geometry(16)), url)
+    assert reason is not None and "CaptureServer on this machine" in reason and url in reason
+
+
+def test_a_remote_capture_server_does_not_affect_a_session_without_livekit_streams():
+    assert unrecordable_reason(_started(object()), "ws://192.168.1.20:8082") is None
diff --git a/examples/egocap/tests/backend/test_livekit_recording_source.py b/examples/egocap/tests/backend/test_livekit_recording_source.py
index dfa0c7985d..d8e821f61e 100644
--- a/examples/egocap/tests/backend/test_livekit_recording_source.py
+++ b/examples/egocap/tests/backend/test_livekit_recording_source.py
@@ -96,6 +96,9 @@ class FakeReceiver:
 
     instances: list[FakeReceiver] = []
     start_error: Exception | None = None
+    #: When set, ``start``/``stop`` wait on it, so a test can stall the join or the leave.
+    start_gate: asyncio.Event | None = None
+    stop_gate: asyncio.Event | None = None
 
     def __init__(self, streams, token):
         self.streams, self.token = list(streams), token
@@ -106,12 +109,16 @@ def __init__(self, streams, token):
 
     async def start(self):
         self.events.append("start")
+        if FakeReceiver.start_gate is not None:
+            await FakeReceiver.start_gate.wait()
         if FakeReceiver.start_error is not None:
             raise FakeReceiver.start_error
 
     async def stop(self):
-        self.stops += 1
         self.events.append("stop")
+        if FakeReceiver.stop_gate is not None:
+            await FakeReceiver.stop_gate.wait()
+        self.stops += 1
 
     async def next_frame_or_lost(self, stream_id):
         return await self.queues[stream_id].get()
@@ -136,13 +143,17 @@ def offer(self, item):
 def fake_receiver(monkeypatch):
     FakeReceiver.instances = []
     FakeReceiver.start_error = None
+    FakeReceiver.start_gate = FakeReceiver.stop_gate = None
     monkeypatch.setattr(lrec, "LiveKitFrameReceiver", FakeReceiver)
 
 
-def make_source(streams, *, timeout=1.0, tokens=None):
+def make_source(streams, *, timeout=1.0, tokens=None, **kwargs):
     tokens = tokens if tokens is not None else []
     return LiveKitRecordingSource(
-        lambda: streams, lambda room: tokens.append(room) or f"token-{room}", first_frame_timeout_s=timeout
+        lambda: streams,
+        lambda room: tokens.append(room) or f"token-{room}",
+        first_frame_timeout_s=timeout,
+        **kwargs,
     )
 
 
@@ -157,7 +168,7 @@ async def prepare_with_frames(source, streams, **frame_kw):
     while not FakeReceiver.instances:
         await asyncio.sleep(0)
     preload(streams, **frame_kw)
-    await task
+    _ = await task
 
 
 async def test_prepare_with_no_recordable_stream_does_nothing():
@@ -197,7 +208,7 @@ async def test_a_lost_track_fails_naming_the_stream_and_leaves_the_room():
         await asyncio.sleep(0)
     FakeReceiver.instances[0].queues[16].put_nowait(None)
     with pytest.raises(RuntimeError, match="cam16: the LiveKit track was lost"):
-        await task
+        _ = await task
     assert FakeReceiver.instances[0].stops == 1
 
 
@@ -224,7 +235,7 @@ async def test_cancelling_prepare_leaves_the_room():
     await asyncio.sleep(0)
     task.cancel()
     with pytest.raises(asyncio.CancelledError):
-        await task
+        _ = await task
     assert FakeReceiver.instances[0].stops == 1
 
 
@@ -268,3 +279,51 @@ async def test_stop_is_idempotent_and_safe_before_prepare():
     await source.stop()
     await source.stop()
     assert FakeReceiver.instances[0].stops == 1
+
+
+async def test_a_stalled_leave_does_not_block_teardown_and_finishes_in_the_background():
+    streams = [livekit_stream(16)]
+    source = make_source(streams, leave_timeout_s=0.01)
+    await prepare_with_frames(source, streams)
+    FakeReceiver.stop_gate = asyncio.Event()
+    await asyncio.wait_for(source.stop(), 1)
+    receiver = FakeReceiver.instances[0]
+    assert receiver.stops == 0
+    FakeReceiver.stop_gate.set()
+    for _ in range(5):
+        await asyncio.sleep(0)
+    assert receiver.stops == 1
+
+
+async def test_a_late_join_fails_the_start_without_cancelling_it_and_leaves_once_it_ends():
+    FakeReceiver.start_gate = asyncio.Event()
+    source = make_source([livekit_stream(16)], join_timeout_s=0.01)
+    with pytest.raises(RuntimeError, match="joining the LiveKit room took longer"):
+        await source.prepare()
+    receiver = FakeReceiver.instances[0]
+    # The join is still running and has not been cancelled or disconnected underneath.
+    assert receiver.events == ["start"]
+    FakeReceiver.start_gate.set()
+    for _ in range(5):
+        await asyncio.sleep(0)
+    assert receiver.events == ["start", "stop"]
+    await source.stop()
+    assert receiver.stops == 1
+
+
+async def test_cancelling_prepare_during_the_join_does_not_cancel_the_join():
+    FakeReceiver.start_gate = asyncio.Event()
+    source = make_source([livekit_stream(16)])
+    task = asyncio.ensure_future(source.prepare())
+    while not FakeReceiver.instances:
+        await asyncio.sleep(0)
+    await asyncio.sleep(0)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        _ = await task
+    receiver = FakeReceiver.instances[0]
+    assert receiver.events == ["start"]
+    FakeReceiver.start_gate.set()
+    for _ in range(5):
+        await asyncio.sleep(0)
+    assert receiver.events == ["start", "stop"]
diff --git a/examples/egocap/tests/tools/test_livekit_orin_emulator.py b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
index 68c86a0d9d..7bdcaf093a 100644
--- a/examples/egocap/tests/tools/test_livekit_orin_emulator.py
+++ b/examples/egocap/tests/tools/test_livekit_orin_emulator.py
@@ -213,7 +213,7 @@ async def test_stats_print_until_stopped(capsys, monkeypatch):
     task = asyncio.create_task(emu.report_stats(stop, counters))
     await asyncio.sleep(0.05)
     stop.set()
-    await task
+    _ = await task
     assert "a=3" in capsys.readouterr().out
 
 

From 2d24d56a77f944e328377e78c433ff979596c22f Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 17:08:10 -0800
Subject: [PATCH 30/37] egocap: document the LiveKit streams and validate them
 at load

Document StreamKind 3, LiveKitTimestampBasis and --livekit-streams in the
protocol reference, add the PC runbook, and correct the backend key-pair
note. Reject a LiveKit stream whose name matches a camera, or that names more
than one room, when the server config is built instead of when a client parses
SessionInit. Drop the personal-tooling ignore entries.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 .gitignore                                    |  3 -
 examples/egocap/LIVEKIT_PREVIEW.md            | 84 +++++++++++++++++++
 examples/egocap/capture_server/README.md      | 43 +++++++++-
 .../capture_server/capture_server/protocol.py |  5 +-
 .../capture_server/capture_server/server.py   | 11 ++-
 .../capture_server/test_livekit_streams.py    | 26 +++++-
 6 files changed, 160 insertions(+), 12 deletions(-)
 create mode 100644 examples/egocap/LIVEKIT_PREVIEW.md

diff --git a/.gitignore b/.gitignore
index dd837b9efd..39b59ea057 100644
--- a/.gitignore
+++ b/.gitignore
@@ -95,6 +95,3 @@ tmp/
 !/examples/mujoco_xr/python/isaacteleop_examples/mujoco_xr/assets/follower/follower_arm.xml
 # Wheel SBOM and license evidence written by the collector in scripts/sbom/
 /sbom/
-
-# Agent-only plans and status notes; never checked in.
-/agentPlans/
diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
new file mode 100644
index 0000000000..3a4db1fe15
--- /dev/null
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -0,0 +1,84 @@
+<!--
+SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# LiveKit camera preview and recording
+
+Camera video can reach the PC through a LiveKit room instead of through CaptureServer. CaptureServer only
+says where the video is; the browser (preview) and the backend (recording) each join the room themselves.
+The publisher is the Orin's sender, or `tools/livekit_orin_emulator.py` when no Orin is available.
+
+Run every command from `examples/egocap`.
+
+## 1. Describe the streams
+
+Write a YAML file naming the room, the publisher's identity and one entry per published track. The field
+reference is in [`capture_server/README.md`](capture_server/README.md#the---livekit-streams-file).
+
+```yaml
+livekit:
+  url: wss://LIVEKIT_HOST
+  room: sensing-preview
+  publisher: orin-sensing
+  timestamp_basis: capture_unix_us
+  streams:
+    - {name: Head left, track: sensing-left, width: 1280, height: 720, fps: 30}
+```
+
+- `track` must equal the name the publisher gives the track (the emulator's `livekit=NAME`).
+- `publisher` must equal the identity in the publisher's join token.
+- Preview works with any `timestamp_basis`. Recording needs `capture_unix_us` and `width`, `height` and
+  `fps`; recording is refused while any offered stream lacks them.
+
+Start CaptureServer with the file (add `--mock` for synthetic tracking):
+
+```bash
+uv run capture-server --mock --livekit-streams livekit.yaml
+```
+
+## 2. Create the publisher's join token
+
+The publisher joins with a token for the room and identity from the file, with publish permission. With the
+LiveKit CLI (`lk`), using the key pair of the LiveKit server:
+
+```bash
+lk token create --api-key "$LIVEKIT_API_KEY" --api-secret "$LIVEKIT_API_SECRET" \
+  --join --room sensing-preview --identity orin-sensing --valid-for 24h > orin-token.txt
+```
+
+The CLI flags are not exercised by this repository's tests; check `lk token create --help` for your version.
+The token file holds only the token. Keep it private.
+
+## 3. Run the emulator (no Orin)
+
+`tools/livekit_orin_emulator.py` joins the room and publishes one test-pattern track per `--add-stream`.
+
+```bash
+uv run python tools/livekit_orin_emulator.py \
+  --livekit-url wss://LIVEKIT_HOST \
+  --livekit-token-file orin-token.txt \
+  --add-stream sensor=0,livekit=sensing-left \
+  --width 1280 --height 720 --fps 30
+```
+
+`--add-stream sensor=N,livekit=NAME` is repeatable. `--timestamp-basis` takes `capture_unix_us` (default),
+`processing_unix_us` or `monotonic_us`; set the same value in the streams file. Frames go through a software
+encoder, so this checks the PC side and the metadata, not the Jetson encoder.
+
+## 4. Preview and record on the PC
+
+Give the backend the LiveKit server's key pair, then start it as in the root [`README.md`](README.md):
+
+```bash
+export LIVEKIT_API_KEY=... LIVEKIT_API_SECRET=...
+uv run uvicorn egocap_web.app:app --app-dir backend --port 8000
+```
+
+- The browser asks `GET /api/livekit-token` for a subscribe-only token, only for a room the current session
+  offers, and shows the stream in the camera grid. Without the key pair the backend answers 503 and the page
+  reports the preview as unavailable.
+- Recording joins the room with its own subscribe-only token signed with the same key pair. It starts only
+  when every offered stream is recordable (see step 1) and stops with a reason if a frame cannot be recorded
+  honestly. The backend must run on the machine whose clock CaptureServer reports.
diff --git a/examples/egocap/capture_server/README.md b/examples/egocap/capture_server/README.md
index 577bfc3c39..11e4b6b318 100644
--- a/examples/egocap/capture_server/README.md
+++ b/examples/egocap/capture_server/README.md
@@ -586,7 +586,7 @@ All enums are IntEnum classes. Supply enum members to the Python API; incoming n
 | `StartupStage` | `INITIALIZING=1`, `WAITING_FOR_HEADSET=2`, `CONNECTING=3`, `STARTING_SOURCES=4` |
 | `StopReason` | `REQUESTED=1`, `OWNER_DISCONNECTED=4`, `SERVER_SHUTDOWN=6`, `IC_ERROR=7`, `IC_EXITED=8`, `CAMERA_ERROR=9` |
 | `RejectionReason` | `INVALID_CONFIG=1`, `BUSY=2`, `UNKNOWN_SESSION=3` |
-| `StreamKind` | `TRACKING=1`, `IMAGE=2` |
+| `StreamKind` | `TRACKING=1`, `IMAGE=2`, `LIVEKIT_IMAGE=3` |
 | `BinaryKind` | `CAPTURE_FRAME=1`, `CAPTURE_IMAGE=2` |
 | `TrackingSchema` | `IC_TRACKING_V1=1` |
 | `WireDType` | `UINT8=1`, `FLOAT32_LE=2`, `FLOAT64_LE=3` |
@@ -594,6 +594,7 @@ All enums are IntEnum classes. Supply enum members to the Python API; incoming n
 | `ImageCodec` | `JPEG=1` |
 | `ClockDomain` | `CAPTURE_HOST_MONOTONIC=1` |
 | `TimeUnit` | `NANOSECONDS=1` |
+| `LiveKitTimestampBasis` | `PUBLISHER_MONOTONIC_US=1`, `PUBLISHER_PROCESSING_UNIX_US=2`, `SENSOR_CAPTURE_UNIX_US=3` |
 | `SampleTimeSemantics` | `HOST_POLL=1` |
 | `PoseRepresentation` | `POSITION_QUATERNION=1` |
 | `QuaternionOrder` | `XYZW=1` |
@@ -928,7 +929,7 @@ This is a complete SessionInit for head, controllers and hands:
 | `clock.domain` | `ClockDomain`: `CAPTURE_HOST_MONOTONIC=1`. | Times use the capture computer's elapsed-time clock; they do not use Unix/calendar time or the client's elapsed-time clock. |
 | `clock.unit` | `TimeUnit`: `NANOSECONDS=1`. | An interval of 1,000,000,000 timestamp units means one second. |
 | `clock.sample_time_semantics` | `SampleTimeSemantics`: `HOST_POLL=1`. | The tracking timestamp describes the host's source-sampling step. It does not claim to be a sensor exposure time or an SDK callback timestamp. |
-| `streams` | Array of tracking and camera descriptor objects. | Defines the stream IDs, formats and tracking byte layout the client must register from SessionInit before any binary messages. An empty array is valid only when no streams were requested. |
+| `streams` | Array of tracking, camera and LiveKit camera descriptor objects. | Defines the stream IDs, formats and tracking byte layout the client must register from SessionInit before any binary messages. An empty array is valid only when no streams were requested. |
 
 The client validates and caches this decoding contract. A layout/format change requires a new session. Unknown camera intrinsics can initially be null; later measured intrinsics are metadata, not a byte-layout change.
 
@@ -1081,7 +1082,7 @@ Dotted field names preserve the public IC group/field identity. Dtype codes are
 | Tracking descriptor field | Python enum and accepted values, or ordinary type | Meaning |
 |---|---|---|
 | `stream_id` | Not an enum: integer 0 for tracking. | Associates a binary message's header with this descriptor. |
-| `kind` | `StreamKind`: `TRACKING=1` for this descriptor; `IMAGE=2` for camera descriptors. | Selects the kind of decoder to use for the stream. |
+| `kind` | `StreamKind`: `TRACKING=1` for this descriptor; `IMAGE=2` for camera descriptors; `LIVEKIT_IMAGE=3` for LiveKit camera descriptors. | Selects the kind of decoder to use for the stream. |
 | `name` | String, `tracking` for this stream; no enum. | Provides a readable stream label. Routing uses stream\_id, not this label. |
 | `schema` | `TrackingSchema`: `IC_TRACKING_V1=1`. | Identifies the complete field contract, including presence/validity meanings and the 1995-byte layout. A client rejects an unsupported schema rather than interpreting a similar-looking blob. |
 | `sources` | `SourceType`: unique array drawn from `HEAD=1`, `CONTROLLERS=2`, `HANDS=3`. | Records the source channels selected for this tracking stream. Unselected channels retain inert slots in the fixed binary layout. |
@@ -1215,6 +1216,42 @@ The camera descriptor repeats name and type from the accepted request and adds t
 | `orientation.mirrored` | Boolean false. | Advertises no server-applied mirror operation. |
 | `intrinsics` | Null or a finite numeric array of shape \[3,3\]; not an enum. | A camera projection matrix for these image dimensions. Its focal-length terms express how rays project into pixels, and its principal-point terms locate the image's optical center in pixel coordinates. Null means the server supplies no such calibration; it must not be interpreted as an identity camera matrix. |
 
+#### LiveKit camera descriptors
+
+A `streams` entry with `kind` `LIVEKIT_IMAGE=3` says where a camera's video is published in a LiveKit room. The server never sends these frames; each consumer joins the room itself and learns the actual dimensions and frame rate from the video. A descriptor does not mean frames are arriving. A client that does not know kind 3 rejects the whole SessionInit, so a server started with `--livekit-streams` cannot be used by older clients.
+
+| LiveKit descriptor field | Python enum and accepted values, or ordinary type | Meaning |
+|---|---|---|
+| `stream_id` | Not an enum: integer 16–23. | Identifies the entry in the one stream-id space shared with the tracking and JPEG camera streams. |
+| `kind` | `StreamKind`: `LIVEKIT_IMAGE=3`. | Selects this descriptor. |
+| `name` | Nonempty string of at most 512 characters. | Operator-facing camera name. It must differ from every other LiveKit entry's name and from every JPEG camera name. |
+| `url` | Nonempty string of at most 512 characters starting with `ws://` or `wss://`. | The LiveKit server to join. |
+| `room` | Nonempty string of at most 512 characters. | The room to join. |
+| `publisher` | Nonempty string of at most 512 characters. | The publishing participant's identity. |
+| `track` | Nonempty string of at most 512 characters. | The published track's name; unique per `publisher`. |
+| `timestamp_basis` | `LiveKitTimestampBasis`: `PUBLISHER_MONOTONIC_US=1`, `PUBLISHER_PROCESSING_UNIX_US=2`, `SENSOR_CAPTURE_UNIX_US=3`. | What the frame's `user_timestamp_us` means. Only `SENSOR_CAPTURE_UNIX_US` is a capture time; the other two are not recordable as one. |
+| `width`, `height` | Positive integer, or null (the key may be omitted). | The configured frame size, or null when not known. |
+| `fps` | Finite positive number, or null (the key may be omitted). | The configured frame rate, or null when not known. |
+
+At most 8 LiveKit entries are allowed, and all of them must share one `url`, `room` and `publisher`: consumers join a single room as a single publisher. Both the server (at startup) and the client (when parsing SessionInit) enforce these rules.
+
+##### The `--livekit-streams` file
+
+`--livekit-streams FILE` loads the entries from a YAML file. The server exits with code 2 and a message on stderr if the file cannot be read or is invalid. Stream ids are assigned 16, 17, ... in file order. Unknown keys are errors.
+
+```yaml
+livekit:
+  url: wss://LIVEKIT_HOST            # ws:// or wss://
+  room: sensing-preview
+  publisher: orin-sensing
+  timestamp_basis: capture_unix_us   # monotonic_us (default), processing_unix_us or capture_unix_us
+  streams:                           # may be empty
+    - {name: Head left, track: sensing-left, width: 2560, height: 1984, fps: 30}
+    - {name: Head right, track: sensing-right}   # width, height and fps are optional
+```
+
+`timestamp_basis` applies to every stream and maps to the `LiveKitTimestampBasis` values above (`monotonic_us`=1, `processing_unix_us`=2, `capture_unix_us`=3). `url`, `room` and `publisher` are set once under `livekit`; each stream supplies `name`, `track` and optionally `width`, `height` and `fps`. A LiveKit stream name that equals a camera name configured with `--gmsl-camera` is rejected.
+
 Each WebSocket binary message consists of a 32-byte header followed immediately by a payload. For CaptureFrame, that payload is the packed tracking blob defined by SessionInit. For CaptureImage, it is the JPEG bytes. The header itself contains no JSON and no field-name strings.
 
 Both binary families use `struct.Struct("<4sBBHQQQ")`:
diff --git a/examples/egocap/capture_server/capture_server/protocol.py b/examples/egocap/capture_server/capture_server/protocol.py
index 6fc524f878..3b5c9fe7a0 100644
--- a/examples/egocap/capture_server/capture_server/protocol.py
+++ b/examples/egocap/capture_server/capture_server/protocol.py
@@ -1020,14 +1020,17 @@ def from_json(cls, data: Any) -> LiveKitCameraStream:
 
 
 def check_livekit_streams(streams: Any) -> None:
-    """Reject a registry whose LiveKit entries are too many or ambiguous.
+    """Reject a registry whose LiveKit entries are too many, ambiguous, or spread over several rooms.
 
+    Consumers join one room as one publisher, so every entry must share the same url, room and publisher.
     Names are checked against the JPEG cameras too: one camera name must mean one stream. Stream ids are unique
     across the whole registry already (checked by the caller).
     """
     livekit = [s for s in streams if isinstance(s, LiveKitCameraStream)]
     if len(livekit) > _MAX_LIVEKIT_STREAMS:
         raise ProtocolError(f"at most {_MAX_LIVEKIT_STREAMS} LiveKit camera streams may be offered")
+    if len({(s.url, s.room, s.publisher) for s in livekit}) > 1:
+        raise ProtocolError("LiveKit camera streams must all use the same url, room and publisher")
     other_names = {s.name for s in streams if isinstance(s, CameraStream)}
     names = [s.name for s in livekit]
     if len(names) != len(set(names)) or other_names & set(names):
diff --git a/examples/egocap/capture_server/capture_server/server.py b/examples/egocap/capture_server/capture_server/server.py
index 5fd93d602c..2c1ede6191 100644
--- a/examples/egocap/capture_server/capture_server/server.py
+++ b/examples/egocap/capture_server/capture_server/server.py
@@ -186,7 +186,7 @@ class ServerConfig:
     livekit_streams: tuple[p.LiveKitCameraStream, ...] = ()
 
     def __post_init__(self) -> None:
-        """Resolve the MCAL folder once, then reject one physical camera assigned to more than one logical name."""
+        """Resolve the MCAL folder once, then reject duplicate physical cameras and unusable LiveKit streams."""
         # Resolved here, at construction, so no later request re-resolves it on the event loop.
         if self.manus_calibration_dir is not None:
             self.manus_calibration_dir = self.manus_calibration_dir.resolve()
@@ -201,6 +201,15 @@ def __post_init__(self) -> None:
             duplicates = sorted({i for i in ids if ids.count(i) > 1})
             if duplicates:
                 raise ValueError(f"physical camera(s) assigned to more than one logical name: {duplicates}")
+        # Fail at construction, not when a client first parses SessionInit.
+        try:
+            p.check_livekit_streams(self.livekit_streams)
+        except p.ProtocolError as exc:
+            raise ValueError(f"ServerConfig.livekit_streams: {exc}") from exc
+        jpeg_names = set(self.cameras or ()) | set(self.known_cameras or ())
+        clashes = sorted(jpeg_names & {s.name for s in self.livekit_streams})
+        if clashes:
+            raise ValueError(f"LiveKit stream name(s) equal to a camera name: {clashes}")
 
 
 @dataclass
diff --git a/examples/egocap/tests/capture_server/test_livekit_streams.py b/examples/egocap/tests/capture_server/test_livekit_streams.py
index 13deaa2b13..212956652a 100644
--- a/examples/egocap/tests/capture_server/test_livekit_streams.py
+++ b/examples/egocap/tests/capture_server/test_livekit_streams.py
@@ -22,7 +22,7 @@
 from capture_server.__main__ import main
 from capture_server.client import CaptureClient, _StreamRegistry
 from capture_server.livekit_streams import load_livekit_streams
-from capture_server.server import ServerConfig
+from capture_server.server import ServerConfig, StationCamera
 from tests.support.capture_server import poll_until, start_capture_server, stop_capture_server
 
 
@@ -172,7 +172,7 @@ def test_livekit_camera_stream_treats_missing_optional_dimensions_as_unknown():
 
 
 def test_livekit_camera_stream_accepts_ws_and_wss():
-    assert _stream(url="ws://10.0.0.5:7880").url == "ws://10.0.0.5:7880"
+    assert _stream(url="ws://192.0.2.5:7880").url == "ws://192.0.2.5:7880"
     assert _stream(url="wss://lk").url == "wss://lk"
 
 
@@ -227,8 +227,26 @@ def test_livekit_name_may_not_collide_with_a_jpeg_camera_name():
         p.check_livekit_streams([camera, _stream()])
 
 
-def test_same_track_name_from_different_publishers_is_allowed():
-    p.check_livekit_streams([_stream(), _stream(stream_id=17, name="b", publisher="other-host")])
+@pytest.mark.parametrize(
+    "different",
+    [{"publisher": "other-host"}, {"room": "other-room"}, {"url": "wss://other.example"}],
+)
+def test_livekit_streams_must_share_one_url_room_and_publisher(different):
+    with pytest.raises(p.ProtocolError, match="same url, room and publisher"):
+        p.check_livekit_streams([_stream(), _stream(stream_id=17, name="b", track="u", **different)])
+
+
+def test_server_config_rejects_livekit_streams_in_several_rooms():
+    other = _stream(stream_id=17, name="b", track="u", room="other-room")
+    with pytest.raises(ValueError, match="same url, room and publisher"):
+        ServerConfig(livekit_streams=(_stream(), other))
+
+
+@pytest.mark.parametrize("field", ["cameras", "known_cameras"])
+def test_server_config_rejects_a_livekit_name_equal_to_a_camera_name(field):
+    value = {"Head left": StationCamera(device_id="dev")} if field == "cameras" else ("Head left",)
+    with pytest.raises(ValueError, match="equal to a camera name"):
+        ServerConfig(livekit_streams=(_stream(),), **{field: value})
 
 
 # ---------------------------------------------------------------------------

From 3dd0465790eb7c5fac317b84b1fbb30d824985cb Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 17:15:07 -0800
Subject: [PATCH 31/37] egocap: make the livekit package an optional extra

The backend and CaptureServer no longer require the livekit package: it moves
to a livekit extra that the dev extra includes. The receiver module imports
without it, a LiveKit stream is reported unrecordable with a message naming
the extra, and the emulator exits with the same instruction. uv.lock is
regenerated with the same resolved packages.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/LIVEKIT_PREVIEW.md            |  4 ++
 examples/egocap/backend/README.md             |  6 ++
 .../backend/egocap_web/livekit_receiver.py    | 17 ++++-
 .../backend/egocap_web/livekit_recording.py   |  5 +-
 examples/egocap/pyproject.toml                |  9 ++-
 .../tests/backend/test_livekit_optional.py    | 54 ++++++++++++++++
 .../egocap/tools/livekit_orin_emulator.py     |  6 +-
 examples/egocap/uv.lock                       | 62 ++++++++++++++++++-
 8 files changed, 156 insertions(+), 7 deletions(-)
 create mode 100644 examples/egocap/tests/backend/test_livekit_optional.py

diff --git a/examples/egocap/LIVEKIT_PREVIEW.md b/examples/egocap/LIVEKIT_PREVIEW.md
index 3a4db1fe15..30952ee889 100644
--- a/examples/egocap/LIVEKIT_PREVIEW.md
+++ b/examples/egocap/LIVEKIT_PREVIEW.md
@@ -10,6 +10,10 @@ Camera video can reach the PC through a LiveKit room instead of through CaptureS
 says where the video is; the browser (preview) and the backend (recording) each join the room themselves.
 The publisher is the Orin's sender, or `tools/livekit_orin_emulator.py` when no Orin is available.
 
+Recording LiveKit video and running the emulator need the optional `livekit` package: `uv sync --extra livekit`
+(included in `--extra dev`). Without it the backend still starts and the browser preview works, but the Record
+button is blocked for LiveKit streams with a message naming the extra.
+
 Run every command from `examples/egocap`.
 
 ## 1. Describe the streams
diff --git a/examples/egocap/backend/README.md b/examples/egocap/backend/README.md
index f11ac231ec..ec58128719 100644
--- a/examples/egocap/backend/README.md
+++ b/examples/egocap/backend/README.md
@@ -62,6 +62,12 @@ Everything else is an environment variable:
 | `EGOCAP_TRUSTED_HOSTNAMES` | unset (dev default) | Comma-separated hostnames trusted for the same-origin fallback on `WS /api/session`. Leaving this unset derives the expected origin from the request's own `Host` header, which is fine for local development but not a safe default for a deployment reachable from an untrusted network. |
 | `EGOCAP_VISER_ENABLED` and related `EGOCAP_VISER_*` | on | The embedded 3D tracking view; see [`frontend/README.md`](../frontend/README.md). |
 
+## Optional LiveKit support
+
+Recording LiveKit camera video needs the `livekit` extra (`uv sync --extra livekit`). Without it the backend
+starts normally and the browser preview works; only recording a LiveKit stream is refused, with a message that
+names the extra. See [`LIVEKIT_PREVIEW.md`](../LIVEKIT_PREVIEW.md).
+
 ## Development
 
 ```bash
diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
index 6e259ce7a2..8c3af07b3d 100644
--- a/examples/egocap/backend/egocap_web/livekit_receiver.py
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -23,12 +23,24 @@
 from dataclasses import dataclass, field
 
 import numpy as np
-from livekit import rtc
 
 from capture_server import protocol as p
 
+try:
+    from livekit import rtc
+except ImportError:  # the optional "livekit" extra is not installed
+    rtc = None
+
 logger = logging.getLogger("isaaccapture.egocap.livekit_receiver")
 
+LIVEKIT_MISSING = "receiving LiveKit video needs the livekit package: install the egocap 'livekit' extra"
+
+
+def livekit_available() -> bool:
+    """Whether the optional ``livekit`` package is installed, so LiveKit video can be received."""
+    return rtc is not None
+
+
 #: Frames a stream may hold between the SDK and the consumer before further frames are dropped and counted.
 #: Decoded frames are megabytes each, so the queues are short and sized into the recorder's memory budget.
 DEFAULT_QUEUE_FRAMES = 2
@@ -83,6 +95,9 @@ def __init__(
         *,
         queue_frames: int = DEFAULT_QUEUE_FRAMES,
     ) -> None:
+        # The package is optional; fail here with the fix rather than later with an AttributeError.
+        if rtc is None:
+            raise RuntimeError(LIVEKIT_MISSING)
         if not streams:
             raise ValueError("at least one LiveKit camera stream is required")
         if len({(s.url, s.room, s.publisher) for s in streams}) != 1:
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index 23b3ab34f2..6213cc13c1 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -27,7 +27,7 @@
 from capture_server import protocol as p
 from recording_service import PixelFormat, VideoSample
 
-from .livekit_receiver import LiveKitFrameReceiver
+from .livekit_receiver import LIVEKIT_MISSING, LiveKitFrameReceiver, livekit_available
 from .recording_adapter import RecordingIngress
 
 logger = logging.getLogger("isaaccapture.egocap.livekit_recording")
@@ -112,6 +112,9 @@ def unrecordable_reason(started: Any, capture_server_url: str | None = None) ->
     for stream in started.streams:
         if not isinstance(stream, p.LiveKitCameraStream):
             continue
+        # Without the optional package no LiveKit stream can be received, so say so before anything else.
+        if not livekit_available():
+            return f"LiveKit stream {stream.name!r}: {LIVEKIT_MISSING}"
         if capture_server_url is not None and not is_loopback_url(capture_server_url):
             return (
                 f"LiveKit stream {stream.name!r}: recording needs CaptureServer on this machine "
diff --git a/examples/egocap/pyproject.toml b/examples/egocap/pyproject.toml
index 1ad3560962..39f4709789 100644
--- a/examples/egocap/pyproject.toml
+++ b/examples/egocap/pyproject.toml
@@ -39,18 +39,23 @@ dependencies = [
     "uvicorn[standard]>=0.30",
     "viser==0.2.23",             # the 3D tracking view, on by default and embedded by iframe
                                  # (backend/egocap_web/viser_scene.py); EGOCAP_VISER_ENABLED=0 turns it off.
-    "livekit==1.1.20",           # receives the offered LiveKit camera video for recording
-                                 # (backend/egocap_web/livekit_receiver.py); the browser uses livekit-client.
 ]
 
 [project.optional-dependencies]
 dev = [
+    "egocap[livekit]",           # the LiveKit tests and emulator need it
     "pytest>=7.4.0",
     "pytest-asyncio",
     "pytest-cov",
     "ruff",
     "httpx",
 ]
+livekit = [
+    # Receives the offered LiveKit camera video for recording (backend/egocap_web/livekit_receiver.py) and
+    # runs the Orin emulator. Without it the backend still starts; LiveKit streams just cannot be recorded.
+    # The browser preview uses livekit-client and does not need this.
+    "livekit==1.1.20",
+]
 oak = [
     "depthai==3.6.1",
 ]
diff --git a/examples/egocap/tests/backend/test_livekit_optional.py b/examples/egocap/tests/backend/test_livekit_optional.py
new file mode 100644
index 0000000000..256bd30961
--- /dev/null
+++ b/examples/egocap/tests/backend/test_livekit_optional.py
@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""The backend works without the optional ``livekit`` package; only receiving LiveKit video needs it."""
+
+from __future__ import annotations
+
+import importlib
+import sys
+from types import SimpleNamespace
+
+import pytest
+
+import egocap_web
+from capture_server import protocol as p
+from egocap_web import livekit_receiver as original_receiver
+from egocap_web import livekit_recording as lrec
+
+
+def _stream() -> p.LiveKitCameraStream:
+    return p.LiveKitCameraStream(
+        stream_id=16, name="cam", track="t", url="ws://livekit.invalid:7880", room="r", publisher="orin"
+    )
+
+
+@pytest.fixture
+def without_livekit(monkeypatch: pytest.MonkeyPatch):
+    """A fresh import of the receiver module as if the package were not installed; undone afterwards."""
+    monkeypatch.setitem(sys.modules, "livekit", None)  # makes ``from livekit import rtc`` raise ImportError
+    monkeypatch.delitem(sys.modules, "egocap_web.livekit_receiver")
+    # The import below rebinds this package attribute; restore it so later tests see the original module.
+    monkeypatch.setattr(egocap_web, "livekit_receiver", original_receiver)
+    return importlib.import_module("egocap_web.livekit_receiver")
+
+
+def test_the_receiver_module_imports_without_livekit(without_livekit):
+    assert without_livekit.livekit_available() is False
+
+
+def test_receiving_without_livekit_names_the_fix(without_livekit):
+    with pytest.raises(RuntimeError, match="'livekit' extra"):
+        without_livekit.LiveKitFrameReceiver([_stream()], "token")
+
+
+def test_a_livekit_stream_is_reported_unrecordable_without_livekit(monkeypatch):
+    monkeypatch.setattr(lrec, "livekit_available", lambda: False)
+    reason = lrec.unrecordable_reason(SimpleNamespace(streams=[_stream()]))
+    assert reason is not None and "'livekit' extra" in reason
+
+
+def test_a_session_without_livekit_streams_is_unaffected_when_it_is_missing(monkeypatch):
+    monkeypatch.setattr(lrec, "livekit_available", lambda: False)
+    assert lrec.unrecordable_reason(SimpleNamespace(streams=[])) is None
diff --git a/examples/egocap/tools/livekit_orin_emulator.py b/examples/egocap/tools/livekit_orin_emulator.py
index 8d1fa0b431..3381d90c8b 100644
--- a/examples/egocap/tools/livekit_orin_emulator.py
+++ b/examples/egocap/tools/livekit_orin_emulator.py
@@ -26,7 +26,11 @@
 from pathlib import Path
 
 import numpy as np
-from livekit import rtc
+
+try:
+    from livekit import rtc
+except ImportError as exc:  # the optional "livekit" extra is not installed
+    raise SystemExit("the emulator needs the livekit package: install the egocap 'livekit' extra") from exc
 
 #: Seconds between periodic stats lines.
 STATS_INTERVAL_S = 5.0
diff --git a/examples/egocap/uv.lock b/examples/egocap/uv.lock
index 0b42d81899..1381df504c 100644
--- a/examples/egocap/uv.lock
+++ b/examples/egocap/uv.lock
@@ -1,7 +1,16 @@
 version = 1
-revision = 3
+revision = 5
 requires-python = "==3.12.*"
 
+[[package]]
+name = "aiofiles"
+version = "25.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/41/c3/534eac40372d8ee36ef40df62ec129bee4fdb5ad9706e58a29be53b2c970/aiofiles-25.1.0.tar.gz", hash = "sha256:a8d728f0a29de45dc521f18f07297428d56992a742f0cd2701ba86e44d23d5b2", size = 46354, upload-time = "2025-10-09T20:51:04.358Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/bc/8a/340a1555ae33d7354dbca4faa54948d76d89a27ceef032c8c3bc661d003e/aiofiles-25.1.0-py3-none-any.whl", hash = "sha256:abe311e527c862958650f9438e859c1fa7568a141b22abcd015e120e86a85695", size = 14668, upload-time = "2025-10-09T20:51:03.174Z" },
+]
+
 [[package]]
 name = "annotated-doc"
 version = "0.0.5"
@@ -219,6 +228,7 @@ dependencies = [
 [package.optional-dependencies]
 dev = [
     { name = "httpx" },
+    { name = "livekit" },
     { name = "pytest" },
     { name = "pytest-asyncio" },
     { name = "pytest-cov" },
@@ -227,6 +237,9 @@ dev = [
 gmsl = [
     { name = "cupy-cuda12x" },
 ]
+livekit = [
+    { name = "livekit" },
+]
 oak = [
     { name = "depthai" },
 ]
@@ -235,9 +248,11 @@ oak = [
 requires-dist = [
     { name = "cupy-cuda12x", marker = "extra == 'gmsl'", specifier = ">=13,<14" },
     { name = "depthai", marker = "extra == 'oak'", specifier = "==3.6.1" },
+    { name = "egocap", extras = ["livekit"], marker = "extra == 'dev'" },
     { name = "fastapi", specifier = ">=0.115" },
     { name = "httpx", marker = "extra == 'dev'" },
     { name = "isaaccapture-manus-calibration", directory = "../../src/plugins/manus_calibration/python" },
+    { name = "livekit", marker = "extra == 'livekit'", specifier = "==1.1.20" },
     { name = "loguru", specifier = ">=0.7.3" },
     { name = "numpy", specifier = ">=1.26.4" },
     { name = "opencv-python", specifier = "==4.12.0.88" },
@@ -254,7 +269,7 @@ requires-dist = [
     { name = "websockets", specifier = ">=17.2" },
     { name = "zarr", specifier = "==3.1.6" },
 ]
-provides-extras = ["dev", "oak", "gmsl"]
+provides-extras = ["dev", "livekit", "oak", "gmsl"]
 
 [[package]]
 name = "embreex"
@@ -455,6 +470,25 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/23/93/4e45e37f26c820216704b36b8e67cc55c490a7abd287a78a26a2c0e21386/lazy_loader-0.6-py3-none-any.whl", hash = "sha256:77253be3391b06124a0e16105bd663b6c54470af1a9ca8e1cf026f38d58ed056", size = 8791, upload-time = "2026-09-21T21:31:31.632Z" },
 ]
 
+[[package]]
+name = "livekit"
+version = "1.1.20"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiofiles" },
+    { name = "numpy" },
+    { name = "protobuf" },
+    { name = "types-protobuf" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e4/dd/651c7ad31d8f80b43511b2cb9ee1a8f5bf50a31ed4399182d09e70777e90/livekit-1.1.20.tar.gz", hash = "sha256:93f0ed9e8ee9ef356da6cbf71f98edcc891678da6872946a87e34e1458528c9c", size = 394319, upload-time = "2026-09-23T20:33:57.147Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/d8/96/2c0ab8b78779f9241017a6e1980dd24c95e7509870d9d3de9bd4acf4f739/livekit-1.1.20-py3-none-macosx_10_15_x86_64.whl", hash = "sha256:253e4d15a78bbb408e926d0b317c7a47c2ca3f6bb9f9d2c7d10528a49f9b4fd9", size = 10485365, upload-time = "2026-09-23T20:33:43.35Z" },
+    { url = "https://files.pythonhosted.org/packages/08/73/9d35e3ffec6e428b040d3b599d4e1ddf554d2046dacfffeae1c20c972f8f/livekit-1.1.20-py3-none-macosx_11_0_arm64.whl", hash = "sha256:a29120a0278a20ede380ac719cd084e39241546cfd3b415aa503c7b8a21afb4e", size = 9307974, upload-time = "2026-09-23T20:33:47.143Z" },
+    { url = "https://files.pythonhosted.org/packages/75/55/dd84369c741eb04a8ca92f7c586f6d24aa0491d4bcb81fa275d91568681c/livekit-1.1.20-py3-none-manylinux_2_28_aarch64.whl", hash = "sha256:c29a5f966806db961a0607ca8e2e4957e6900bbd44710f5f618b284043be584c", size = 10602682, upload-time = "2026-09-23T20:33:49.514Z" },
+    { url = "https://files.pythonhosted.org/packages/cc/15/a53a370dc5b1f2a7c3806f24f1543fbad98bcadb0588f28f938fc338a627/livekit-1.1.20-py3-none-manylinux_2_28_x86_64.whl", hash = "sha256:83c0ea54d7ff505e92c3e88943e050e54825b0bf0f7e90652fb126eb447b3d76", size = 11832028, upload-time = "2026-09-23T20:33:51.835Z" },
+    { url = "https://files.pythonhosted.org/packages/5e/bf/dccec2015a5594eedf26c605fe4a2682d152fabcae0cce4b71d1412efbd2/livekit-1.1.20-py3-none-win_amd64.whl", hash = "sha256:64ea60b3293e3ce92c60592ff32c518bb7c278548b97de8026c1d0617510af4d", size = 10991380, upload-time = "2026-09-23T20:33:54.775Z" },
+]
+
 [[package]]
 name = "loguru"
 version = "0.7.3"
@@ -700,6 +734,21 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/99/69/3452dd12683d722bc33758c8875fb8a812df21f3ee339293aebf97bc2340/plyfile-1.1.5-py3-none-any.whl", hash = "sha256:675c0fc22b949c49398f5ed6725a1d781f6a9f7625b42232c02198f6509c4ae3", size = 36463, upload-time = "2026-07-28T08:23:12.14Z" },
 ]
 
+[[package]]
+name = "protobuf"
+version = "7.36.2"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d9/89/5b8517baa72f84a67b8a307ba953c91057af618bf40bf676f3c03551f8f0/protobuf-7.36.2.tar.gz", hash = "sha256:497d0463ff3316681da6c0b9e8d06cb465d61abce00b613ab42226175644d1bb", size = 512737, upload-time = "2026-09-17T20:07:59.326Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/32/72/98342feb672507c8f3a69e34b4fa8961f608edba5c1a48a6f47156d92cb5/protobuf-7.36.2-cp310-abi3-macosx_10_9_universal2.whl", hash = "sha256:cbc70b17ee27e28894c7fee8bb04be1abead49e936bc70eb60052531eee2079e", size = 456039, upload-time = "2026-09-17T20:07:51.542Z" },
+    { url = "https://files.pythonhosted.org/packages/b6/ea/91fdf7c2b8bbd49cde056f00a9df6773532987e1c00fe2830b895af95c7e/protobuf-7.36.2-cp310-abi3-manylinux2014_aarch64.whl", hash = "sha256:e11e1f0180583a2af89db6a2ecd9e8dc40aa6d2988ca175bfd0e6d12ea72d74e", size = 344219, upload-time = "2026-09-17T20:07:52.914Z" },
+    { url = "https://files.pythonhosted.org/packages/17/ab/5fd5f8ece73fad885c5a09aa849b32d70472f954ba3a92d3bb5974ea953b/protobuf-7.36.2-cp310-abi3-manylinux2014_s390x.whl", hash = "sha256:f4fee11ec330d238b34a05c9b675f693c20415d1c5bd7d5320cc2f8a798eb9cf", size = 357223, upload-time = "2026-09-17T20:07:53.985Z" },
+    { url = "https://files.pythonhosted.org/packages/db/f3/3996583dd2906297a637af12114deddf7658af6e683fedb83be061983fb5/protobuf-7.36.2-cp310-abi3-manylinux2014_x86_64.whl", hash = "sha256:89f23aa53c24553a2416fd4fd1ec06f74fa42b14b546d8883128813f775bbfd2", size = 343223, upload-time = "2026-09-17T20:07:54.931Z" },
+    { url = "https://files.pythonhosted.org/packages/fc/1b/dcc64f358fcb51811b58ae40b3d28f820725f116d86487cc20bd4b130701/protobuf-7.36.2-cp310-abi3-win32.whl", hash = "sha256:912c1221170e16c08d1f086762f563dd61ff83c18b5fa6652952dfaded66f728", size = 442998, upload-time = "2026-09-17T20:07:55.826Z" },
+    { url = "https://files.pythonhosted.org/packages/8a/55/b77bda4e5e5f5971fb51b07663694690e9afdb9402136c16a522bd621cad/protobuf-7.36.2-cp310-abi3-win_amd64.whl", hash = "sha256:a300819d441e078a5608c0d3c709796bb548136058fda017ae51d425b44fd353", size = 456514, upload-time = "2026-09-17T20:07:57.188Z" },
+    { url = "https://files.pythonhosted.org/packages/e4/04/d52c7016b04b6c5108f26691f9d33ec82a9b65d041f1a9c771137693d618/protobuf-7.36.2-py3-none-any.whl", hash = "sha256:bdb3a345d48db958e6ce1f18e508beb0cc981d64f24088427549c866cd039f1e", size = 179806, upload-time = "2026-09-17T20:07:58.211Z" },
+]
+
 [[package]]
 name = "psutil"
 version = "7.2.2"
@@ -1144,6 +1193,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8f/eb/461d5f167b6f5c7d97696f397c82f82e3480e003fce3f0a1cd1dd26e2eb2/typeguard-4.6.0-py3-none-any.whl", hash = "sha256:79878165bb86f2cf5d41d159a0ff1792a796cf496882d2fe1b1c6c7049b9cdd7", size = 36884, upload-time = "2026-07-26T08:40:21.868Z" },
 ]
 
+[[package]]
+name = "types-protobuf"
+version = "7.35.1.20260906"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/e1/6c/e3e5b3e10bc328126a39637c138f9ebfd734bf14342b9f3540039b4ab995/types_protobuf-7.35.1.20260906.tar.gz", hash = "sha256:efd1a3862d4c967dad5512ef8d56b1530ac84f182c41735b94004756518c4998", size = 69895, upload-time = "2026-09-06T06:35:28.308Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/44/4e/f63e826c68f77ef875506d72f225918800346545ee99847bc28f3394f18d/types_protobuf-7.35.1.20260906-py3-none-any.whl", hash = "sha256:5155e48569e0dabff303fdf578db96cd31ea9a4a63b18018a4ceac6b0ae17462", size = 86419, upload-time = "2026-09-06T06:35:27.247Z" },
+]
+
 [[package]]
 name = "typing-extensions"
 version = "4.16.0"

From bff0725e4573603d8282e038643043853fdd704c Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Thu, 5 Nov 2026 21:41:31 -0800
Subject: [PATCH 32/37] egocap: restore the receiver module attribute by name
 in the optional-livekit test

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/tests/backend/test_livekit_optional.py | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/examples/egocap/tests/backend/test_livekit_optional.py b/examples/egocap/tests/backend/test_livekit_optional.py
index 256bd30961..e45d3fe465 100644
--- a/examples/egocap/tests/backend/test_livekit_optional.py
+++ b/examples/egocap/tests/backend/test_livekit_optional.py
@@ -12,7 +12,6 @@
 
 import pytest
 
-import egocap_web
 from capture_server import protocol as p
 from egocap_web import livekit_receiver as original_receiver
 from egocap_web import livekit_recording as lrec
@@ -30,7 +29,7 @@ def without_livekit(monkeypatch: pytest.MonkeyPatch):
     monkeypatch.setitem(sys.modules, "livekit", None)  # makes ``from livekit import rtc`` raise ImportError
     monkeypatch.delitem(sys.modules, "egocap_web.livekit_receiver")
     # The import below rebinds this package attribute; restore it so later tests see the original module.
-    monkeypatch.setattr(egocap_web, "livekit_receiver", original_receiver)
+    monkeypatch.setattr("egocap_web.livekit_receiver", original_receiver)
     return importlib.import_module("egocap_web.livekit_receiver")
 
 

From f3d8066debad7d5b9139135a989fac5205fb4a80 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Fri, 6 Nov 2026 13:04:23 -0800
Subject: [PATCH 33/37] egocap: recorder subscribes to its tracks only, and a
 take records what was lost

The receiver connects without automatic subscription and subscribes to the
offered tracks of the offered publisher. A replaced publication drops the old
queued frames and counts as a discontinuity, a stale unsubscribe is ignored, a
stream that ends normally is lost, and frame-number strides are learned so
paced streams are not counted as loss. The recording feed ends a take on
dropped frames, a replaced publication or five seconds of silence, and reports
what was lost. Receiver queue storage is counted once in the memory budget.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/backend/egocap_web/app.py     |   5 +-
 .../backend/egocap_web/livekit_receiver.py    |  69 +++++-
 .../backend/egocap_web/livekit_recording.py   |  43 +++-
 .../backend/test_app_livekit_recording.py     |  23 ++
 .../tests/backend/test_livekit_receiver.py    | 204 +++++++++++++++++-
 .../tests/backend/test_livekit_recording.py   | 128 ++++++++++-
 .../backend/test_livekit_recording_source.py  |   6 +-
 7 files changed, 456 insertions(+), 22 deletions(-)

diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index 41e8672770..5c43b4111a 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -207,7 +207,10 @@ def factory() -> ServiceConfig:
             started = monitor.native.started
             # The live raw item is a JPEG, or a LiveKit stream's decoded frame when that is larger.
             live_item_bytes = max([MAX_CAMERA_JPEG_BYTES, *_livekit_frame_bytes(started)])
-            reserved = _ingress_queue_bytes(started) + live_item_bytes
+            # Owned storage, each counted once: the raw ingress queue, the LiveKit receivers' own frame queues, and
+            # the one live item. The budget is the base plus the LiveKit ingress allowance plus the receiver
+            # allowance, so the receiver queues are taken out of it here and what remains is the decoded queue.
+            reserved = _ingress_queue_bytes(started) + _livekit_receiver_bytes(started) + live_item_bytes
             total = (
                 _RECORDING_QUEUE_MEMORY_BUDGET_BYTES
                 + _livekit_ingress_bytes(started)
diff --git a/examples/egocap/backend/egocap_web/livekit_receiver.py b/examples/egocap/backend/egocap_web/livekit_receiver.py
index 8c3af07b3d..a6375cb6fd 100644
--- a/examples/egocap/backend/egocap_web/livekit_receiver.py
+++ b/examples/egocap/backend/egocap_web/livekit_receiver.py
@@ -80,6 +80,11 @@ class StreamCounters:
     missing_frames: int = 0
     #: Times the publisher's frame id went backwards or repeated: a restarted publisher.
     frame_id_resets: int = 0
+    #: Times the stream's publication was replaced: a discontinuity, since the new one is a different source epoch.
+    publication_changes: int = 0
+    #: The smallest step between consecutive frame ids seen. A publisher that paces its stream below the capture
+    #: rate numbers frames in steps (2, 4, 6...), which is not loss; only a deviation from this step is.
+    id_step: int | None = field(default=None, repr=False)
     #: Whether the stream's track is currently subscribed.
     subscribed: bool = False
     last_frame_id: int | None = field(default=None, repr=False)
@@ -115,6 +120,8 @@ def __init__(
         # waiting forever; cleared when the track is subscribed again.
         self._lost = {s.stream_id: asyncio.Event() for s in streams}
         self._readers: dict[int, asyncio.Task[None]] = {}
+        # The id of the track each stream is currently read from, so an event about a replaced track is recognised.
+        self._active: dict[int, str] = {}
         # Set once the room connection is lost for good; the SDK's own reconnects do not set it.
         self.failed = asyncio.Event()
 
@@ -122,14 +129,18 @@ async def start(self) -> None:
         """Connect and begin receiving; frames of tracks published before or after joining are both picked up."""
         room = rtc.Room()
         self._room = room
+        room.on("track_published", self._on_track_published)
         room.on("track_subscribed", self._on_track_subscribed)
         room.on("track_unsubscribed", self._on_track_unsubscribed)
         room.on("participant_disconnected", self._on_participant_disconnected)
         room.on("disconnected", self._on_disconnected)
-        _ = await room.connect(self._url, self._token)
-        # Tracks published before we joined arrive here rather than through track_subscribed.
+        # Nothing is subscribed automatically: only the offered tracks are, so unrelated tracks in the room cost no
+        # media work here.
+        _ = await room.connect(self._url, self._token, rtc.RoomOptions(auto_subscribe=False))
+        # Tracks published before we joined arrive here rather than through track_published.
         for participant in room.remote_participants.values():
             for publication in participant.track_publications.values():
+                self._subscribe_if_offered(participant, publication)
                 if publication.track is not None:
                     self._attach(participant, publication.track, publication.name)
 
@@ -151,11 +162,12 @@ async def next_frame(self, stream_id: int) -> ReceivedFrame:
         """The oldest queued frame of ``stream_id``, waiting for one if none is queued."""
         return await self._queues[stream_id].get()
 
-    async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
+    async def next_frame_or_lost(self, stream_id: int, timeout: float | None = None) -> ReceivedFrame | None:
         """The oldest queued frame of ``stream_id``, or None once its track is lost and nothing is queued.
 
         Frames already queued when the track goes away are still returned first, so a consumer drains what
-        arrived before it learns of the loss.
+        arrived before it learns of the loss. With ``timeout`` set, raises ``asyncio.TimeoutError`` when neither a
+        frame nor a loss arrives in that many seconds: a track that stays published but sends nothing is not lost.
         """
         queue = self._queues[stream_id]
         if not queue.empty():
@@ -163,7 +175,9 @@ async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
         get = asyncio.ensure_future(queue.get())
         lost = asyncio.ensure_future(self._lost[stream_id].wait())
         try:
-            await asyncio.wait({get, lost}, return_when=asyncio.FIRST_COMPLETED)
+            done, _pending = await asyncio.wait({get, lost}, timeout=timeout, return_when=asyncio.FIRST_COMPLETED)
+            if not done:
+                raise asyncio.TimeoutError
             # A frame that arrived together with the loss is still a frame the consumer is owed.
             return get.result() if get.done() else None
         finally:
@@ -181,15 +195,38 @@ def pending(self, stream_id: int) -> int:
         """How many frames of ``stream_id`` are queued for the consumer."""
         return self._queues[stream_id].qsize()
 
+    def _subscribe_if_offered(
+        self, participant: rtc.RemoteParticipant, publication: rtc.RemoteTrackPublication
+    ) -> None:
+        """Subscribe to ``publication`` if it is an offered stream's track from the offered publisher."""
+        if (
+            participant.identity == self._publisher
+            and publication.name in self._by_track
+            and publication.kind == rtc.TrackKind.KIND_VIDEO
+        ):
+            publication.set_subscribed(True)
+
+    def _on_track_published(
+        self, publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant
+    ) -> None:
+        self._subscribe_if_offered(participant, publication)
+
     def _attach(self, participant: rtc.RemoteParticipant, track: rtc.Track, name: str) -> None:
         """Start reading ``track`` if it is one of the offered streams, from the offered publisher."""
         stream = self._by_track.get(name)
         if participant.identity != self._publisher or stream is None or track.kind != rtc.TrackKind.KIND_VIDEO:
             return
-        # A republished track replaces the old reader; its frames must not interleave with the new ones.
+        # A republished track replaces the old reader; its frames must not interleave with the new ones, so what
+        # the old one queued is dropped, and the replacement is counted as a discontinuity the consumer can see.
         previous = self._readers.pop(stream.stream_id, None)
         if previous is not None:
             previous.cancel()
+        if previous is not None or self._active.get(stream.stream_id, track.sid) != track.sid:
+            self.counters[stream.stream_id].publication_changes += 1
+            queue = self._queues[stream.stream_id]
+            while not queue.empty():
+                queue.get_nowait()
+        self._active[stream.stream_id] = track.sid
         self.counters[stream.stream_id].subscribed = True
         self._lost[stream.stream_id].clear()
         # A new publication restarts the publisher's numbering, so a jump from the old track is not a loss.
@@ -203,6 +240,7 @@ def _detach(self, stream_id: int) -> None:
         task = self._readers.pop(stream_id, None)
         if task is not None:
             task.cancel()
+        self._active.pop(stream_id, None)
         self._mark_lost(stream_id)
 
     def _mark_lost(self, stream_id: int) -> None:
@@ -219,8 +257,12 @@ def _on_track_unsubscribed(
         self, track: rtc.Track, publication: rtc.RemoteTrackPublication, participant: rtc.RemoteParticipant
     ) -> None:
         stream = self._by_track.get(publication.name)
-        if stream is not None and participant.identity == self._publisher:
-            self._detach(stream.stream_id)
+        if stream is None or participant.identity != self._publisher:
+            return
+        # An unsubscribe of a track that has since been replaced says nothing about the current one.
+        if self._active.get(stream.stream_id) != track.sid:
+            return
+        self._detach(stream.stream_id)
 
     def _on_participant_disconnected(self, participant: rtc.RemoteParticipant) -> None:
         if participant.identity == self._publisher:
@@ -264,6 +306,10 @@ async def _read(self, stream_id: int, track: rtc.Track) -> None:
                 except asyncio.QueueFull:
                     # Never block the reader or skip silently: the consumer is behind, and the loss is counted.
                     counters.queue_overflow += 1
+            # The SDK ended the stream normally: nothing more will arrive, and a consumer must not wait for it.
+            if self._readers.get(stream_id) is this_task:
+                self._readers.pop(stream_id)
+                self._mark_lost(stream_id)
         except Exception:
             # A dead reader would leave the consumer waiting forever; marking the stream lost lets the take settle.
             # Only the reader still registered for the stream may do so: a replaced one is already superseded.
@@ -285,6 +331,9 @@ def _account(counters: StreamCounters, frame_id: int | None) -> None:
             if frame_id <= last:
                 # The publisher restarted its numbering: a new run, not a loss.
                 counters.frame_id_resets += 1
-            elif frame_id > last + 1:
-                counters.missing_frames += frame_id - last - 1
+            else:
+                step = frame_id - last
+                counters.id_step = step if counters.id_step is None else min(counters.id_step, step)
+                # A publisher that paces its stream steps its ids by a constant; only a bigger jump is loss.
+                counters.missing_frames += max(0, round(step / counters.id_step) - 1)
         counters.last_frame_id = frame_id
diff --git a/examples/egocap/backend/egocap_web/livekit_recording.py b/examples/egocap/backend/egocap_web/livekit_recording.py
index 6213cc13c1..7aae0a79b5 100644
--- a/examples/egocap/backend/egocap_web/livekit_recording.py
+++ b/examples/egocap/backend/egocap_web/livekit_recording.py
@@ -39,6 +39,8 @@
 #: publisher's clock and this host's disagree grossly. This catches gross disagreement only, not millisecond error.
 _MAX_FRAME_AGE_S = 2.0
 _MAX_FRAME_LEAD_S = 0.05
+#: How long a published stream may send nothing before the take ends. Normal frame gaps are tens of milliseconds.
+_MAX_SILENCE_S = 5.0
 #: Readings per pair; the one read in the shortest span is the most trustworthy.
 _PAIR_ATTEMPTS = 3
 #: How long the room join may take before the take's start is refused.
@@ -157,9 +159,28 @@ def __init__(
         self._on_failure = on_failure
         self._tasks: list[asyncio.Task[None]] = []
         self.failure: str | None = None
+        self._baseline: dict[int, tuple[int, int]] = {}
+
+    def loss(self) -> dict[str, dict[str, int]]:
+        """What the receiver lost on the way to this take, per stream name (counted since the take began)."""
+        out: dict[str, dict[str, int]] = {}
+        for stream_id, stream in self._streams.items():
+            counters = self._receiver.counters[stream_id]
+            overflow, changes = self._baseline.get(stream_id, (0, 0))
+            out[stream.name] = {
+                "received": counters.received,
+                "queue_overflow": counters.queue_overflow - overflow,
+                "publication_changes": counters.publication_changes - changes,
+                "missing_frames": counters.missing_frames,
+                "frame_id_resets": counters.frame_id_resets,
+            }
+        return out
 
     def start(self) -> None:
         """Begin feeding; one task per stream so a slow stream never delays another."""
+        for stream_id in self._streams:
+            counters = self._receiver.counters[stream_id]
+            self._baseline[stream_id] = (counters.queue_overflow, counters.publication_changes)
         loop = asyncio.get_running_loop()
         self._tasks = [loop.create_task(self._run(stream_id)) for stream_id in self._streams]
 
@@ -191,11 +212,31 @@ async def _run(self, stream_id: int) -> None:
             )
             return
         while self.failure is None:
-            frame = await self._receiver.next_frame_or_lost(stream_id)
+            try:
+                frame = await self._receiver.next_frame_or_lost(stream_id, timeout=_MAX_SILENCE_S)
+            except asyncio.TimeoutError:
+                # A track can stay published and send nothing; a take must not wait on it forever.
+                self._fail(
+                    f"{stream.name}: no frame for {_MAX_SILENCE_S:.0f} s although the track is still published"
+                )
+                return
             if frame is None:
                 # Whatever was queued has been taken; the camera is gone, and a recorded source must not vanish.
                 self._fail(f"{stream.name}: the LiveKit track was lost")
                 return
+            # What the receiver lost since this take began: video that was not recorded must not look like video
+            # that was, so a gap or a replaced publication ends the take with its reason.
+            counters = self._receiver.counters[stream_id]
+            overflow, changes = self._baseline[stream_id]
+            if counters.queue_overflow > overflow:
+                self._fail(
+                    f"{stream.name}: the recorder fell behind and dropped "
+                    f"{counters.queue_overflow - overflow} frame(s)"
+                )
+                return
+            if counters.publication_changes > changes:
+                self._fail(f"{stream.name}: the camera's publication was replaced during the take")
+                return
             if frame.user_timestamp_us is None:
                 self._fail(f"{stream.name}: a frame arrived without the publisher's capture timestamp")
                 return
diff --git a/examples/egocap/tests/backend/test_app_livekit_recording.py b/examples/egocap/tests/backend/test_app_livekit_recording.py
index aaa720f35a..dbe67599f9 100644
--- a/examples/egocap/tests/backend/test_app_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_app_livekit_recording.py
@@ -178,6 +178,7 @@ def test_config_factory_with_two_full_size_streams_fits_its_total_budget(tmp_pat
     )
     held = (
         app_module._ingress_queue_bytes(started)
+        + app_module._livekit_receiver_bytes(started)
         + max(app_module.MAX_CAMERA_JPEG_BYTES, frame_bytes)
         + (config.queue_capacity + 2) * frame_bytes
     )
@@ -185,6 +186,28 @@ def test_config_factory_with_two_full_size_streams_fits_its_total_budget(tmp_pat
     assert held <= total
 
 
+def test_owned_bytes_of_two_full_size_streams_never_exceed_the_allowances(tmp_path):
+    started = SimpleNamespace(streams=_full_size_streams(2))
+    monitor = SimpleNamespace(camera_descriptors=(), native=SimpleNamespace(started=started))
+    config = app_module._recording_config_factory(monitor, None, tmp_path)()
+    frame_bytes = FULL_WIDTH * FULL_HEIGHT * 3
+    owned = (
+        app_module._ingress_queue_bytes(started)
+        + app_module._livekit_receiver_bytes(started)
+        + max(app_module.MAX_CAMERA_JPEG_BYTES, frame_bytes)
+        + 2 * frame_bytes
+        + config.queue_capacity * frame_bytes
+    )
+    allowed = (
+        app_module._RECORDING_QUEUE_MEMORY_BUDGET_BYTES
+        + app_module._livekit_ingress_bytes(started)
+        + app_module._livekit_receiver_bytes(started)
+    )
+    assert owned <= allowed
+    # The capacity is the largest that fits: one more decoded frame would exceed the allowance.
+    assert owned + frame_bytes > allowed
+
+
 def test_receiver_queues_are_part_of_the_livekit_budget():
     started = SimpleNamespace(streams=_full_size_streams(2))
     frame_bytes = FULL_WIDTH * FULL_HEIGHT * 3
diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
index 686a6d03fa..b4dc73938b 100644
--- a/examples/egocap/tests/backend/test_livekit_receiver.py
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import asyncio
+import itertools
 import time
 from types import SimpleNamespace
 
@@ -26,8 +27,11 @@
 class FakeTrack:
     """A remote video track; the test feeds its events through ``push``."""
 
+    _sids = itertools.count(1)
+
     def __init__(self, kind: str = "video") -> None:
         self.kind = kind
+        self.sid = f"TR_{next(FakeTrack._sids)}"
         self.events: asyncio.Queue = asyncio.Queue()
 
     def push(self, event: object) -> None:
@@ -48,7 +52,10 @@ def __aiter__(self) -> FakeVideoStream:
         return self
 
     async def __anext__(self) -> object:
-        return await self.track.events.get()
+        item = await self.track.events.get()
+        if item is StopAsyncIteration:
+            raise StopAsyncIteration
+        return item
 
     async def aclose(self) -> None:
         self.closed += 1
@@ -60,14 +67,16 @@ class FakeRoom:
     def __init__(self) -> None:
         self.handlers: dict[str, object] = {}
         self.connected_with: tuple[str, str] | None = None
+        self.connect_options: object = None
         self.disconnects = 0
         self.remote_participants: dict[str, object] = {}
 
     def on(self, name: str, handler: object) -> None:
         self.handlers[name] = handler
 
-    async def connect(self, url: str, token: str) -> None:
+    async def connect(self, url: str, token: str, options: object = None) -> None:
         self.connected_with = (url, token)
+        self.connect_options = options
 
     async def disconnect(self) -> None:
         self.disconnects += 1
@@ -79,6 +88,7 @@ def emit(self, name: str, *args: object) -> None:
 FAKE_RTC = SimpleNamespace(
     Room=FakeRoom,
     VideoStream=FakeVideoStream,
+    RoomOptions=lambda **fields: SimpleNamespace(**fields),
     TrackKind=SimpleNamespace(KIND_VIDEO="video"),
     VideoBufferType=SimpleNamespace(RGB24="rgb24"),
 )
@@ -88,8 +98,10 @@ def participant(identity: str = PUBLISHER, publications: dict | None = None) ->
     return SimpleNamespace(identity=identity, track_publications=publications or {})
 
 
-def publication(name: str, track: FakeTrack | None) -> SimpleNamespace:
-    return SimpleNamespace(name=name, track=track)
+def publication(name: str, track: FakeTrack | None, kind: str = "video") -> SimpleNamespace:
+    """A remote publication; ``subscribed_calls`` records each ``set_subscribed`` the receiver makes."""
+    calls: list[bool] = []
+    return SimpleNamespace(name=name, track=track, kind=kind, subscribed_calls=calls, set_subscribed=calls.append)
 
 
 def event(
@@ -521,12 +533,15 @@ async def test_room_disconnect_marks_a_never_attached_stream_lost(receiver):
     assert await asyncio.wait_for(waiter, 1) is None
 
 
-async def test_unsubscribe_of_a_never_attached_stream_marks_it_lost(receiver):
+async def test_unsubscribe_of_a_never_attached_track_is_ignored(receiver):
+    # Only the active track's unsubscribe is a loss; one for a track that was never read says nothing.
     track = FakeTrack()
     waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
     await settle()
     _unsubscribe(receiver, track)
-    assert await asyncio.wait_for(waiter, 1) is None
+    await settle()
+    assert not waiter.done()
+    waiter.cancel()
 
 
 async def test_publisher_leaving_marks_a_never_attached_stream_lost(receiver):
@@ -659,3 +674,180 @@ async def test_a_failing_reader_leaves_the_other_stream_running(receiver):
     right.push(event(5, frame_id=1))
     assert (await asyncio.wait_for(receiver.next_frame(2), 1)).image[0, 0, 0] == 5
     assert receiver.counters[2].subscribed and not receiver.counters[1].subscribed
+
+
+# ---- selective subscription ----
+
+
+def _prejoined_rtc(monkeypatch, participants: dict):
+    class Prejoined(FakeRoom):
+        def __init__(self) -> None:
+            super().__init__()
+            self.remote_participants = participants
+
+    monkeypatch.setattr(lr, "rtc", SimpleNamespace(**{**vars(FAKE_RTC), "Room": Prejoined}))
+
+
+async def test_connect_disables_auto_subscribe(receiver):
+    assert room_of(receiver).connect_options.auto_subscribe is False
+
+
+async def test_only_the_offered_publication_is_subscribed_among_existing_ones(monkeypatch):
+    offered = publication("left", None)
+    unrelated = publication("depth", None)
+    audio = publication("left", None, kind="audio")
+    foreign = publication("left", None)
+    _prejoined_rtc(
+        monkeypatch,
+        {
+            "a": participant(PUBLISHER, {"1": offered, "2": unrelated, "3": audio}),
+            "b": participant("intruder", {"4": foreign}),
+        },
+    )
+    rx = lr.LiveKitFrameReceiver([camera(1, "left")], TOKEN)
+    await rx.start()
+    try:
+        assert offered.subscribed_calls == [True]
+        assert unrelated.subscribed_calls == [] and audio.subscribed_calls == [] and foreign.subscribed_calls == []
+    finally:
+        await rx.stop()
+
+
+async def test_a_later_publication_is_subscribed_only_when_offered(receiver):
+    room = room_of(receiver)
+    offered = publication("right", None)
+    unrelated = publication("depth", None)
+    foreign = publication("right", None)
+    audio = publication("right", None, kind="audio")
+    room.emit("track_published", offered, participant())
+    room.emit("track_published", unrelated, participant())
+    room.emit("track_published", foreign, participant("intruder"))
+    room.emit("track_published", audio, participant())
+    assert offered.subscribed_calls == [True]
+    assert unrelated.subscribed_calls == foreign.subscribed_calls == audio.subscribed_calls == []
+
+
+# ---- replacement and stale events ----
+
+
+async def test_stale_unsubscribe_after_replacement_does_not_detach_the_replacement(receiver):
+    old = subscribe(receiver)
+    new = subscribe(receiver)
+    await settle()
+    reader = receiver._readers[1]
+    _unsubscribe(receiver, old)
+    await settle()
+    assert receiver.counters[1].subscribed and receiver._readers[1] is reader and not reader.done()
+    new.push(event(1, frame_id=1))
+    assert (await asyncio.wait_for(receiver.next_frame_or_lost(1), 1)).frame_id == 1
+
+
+async def test_unsubscribe_of_the_active_track_still_detaches(receiver):
+    subscribe(receiver)
+    new = subscribe(receiver)
+    await settle()
+    _unsubscribe(receiver, new)
+    await settle()
+    assert not receiver.counters[1].subscribed and 1 not in receiver._readers and 1 not in receiver._active
+
+
+async def test_replacement_counts_a_publication_change_and_drops_the_old_queue(receiver):
+    old = subscribe(receiver)
+    assert receiver.counters[1].publication_changes == 0  # the first attach is not a change
+    for fid in (1, 2, 3):
+        old.push(event(frame_id=fid))
+    await settle()
+    assert receiver.pending(1) == 3
+    subscribe(receiver)
+    assert receiver.counters[1].publication_changes == 1
+    assert receiver.pending(1) == 0
+    assert receiver.counters[1].received == 3
+
+
+async def test_a_different_sid_without_a_reader_is_a_change_too(receiver):
+    track = subscribe(receiver)
+    reader = receiver._readers.pop(1)
+    reader.cancel()
+    other = FakeTrack()
+    room_of(receiver).emit("track_subscribed", other, publication("left", other), participant())
+    assert receiver.counters[1].publication_changes == 1
+    assert receiver._active[1] == other.sid != track.sid
+
+
+async def test_reattaching_after_a_detach_is_not_a_publication_change(receiver):
+    track = subscribe(receiver)
+    _unsubscribe(receiver, track)
+    subscribe(receiver)
+    assert receiver.counters[1].publication_changes == 0
+
+
+# ---- the SDK stream ending ----
+
+
+async def test_a_normally_ended_reader_marks_the_stream_lost_and_wakes_a_waiter(receiver):
+    track = subscribe(receiver)
+    track.push(event(1, frame_id=1))
+    await settle()
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    assert (await asyncio.wait_for(waiter, 1)).frame_id == 1
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1))
+    await settle()
+    assert not waiter.done()
+    track.push(StopAsyncIteration)  # the fake stream raises it from __anext__
+    assert await asyncio.wait_for(waiter, 1) is None
+    assert 1 not in receiver._readers
+
+
+async def test_next_frame_or_lost_times_out_when_nothing_arrives(receiver):
+    subscribe(receiver)
+    await settle()
+    baseline = _only_test_tasks()
+    with pytest.raises(asyncio.TimeoutError):
+        await receiver.next_frame_or_lost(1, timeout=0.01)
+    await settle()
+    assert _only_test_tasks() == baseline
+
+
+async def test_timeout_does_not_fire_when_a_frame_arrives_in_time(receiver):
+    track = subscribe(receiver)
+    waiter = asyncio.ensure_future(receiver.next_frame_or_lost(1, timeout=1))
+    await settle()
+    track.push(event(1, frame_id=1))
+    assert (await asyncio.wait_for(waiter, 1)).frame_id == 1
+
+
+# ---- frame-id stride ----
+
+
+async def _ids(rx, ids):
+    track = subscribe(rx)
+    for fid in ids:
+        track.push(event(frame_id=fid))
+    await _drain(rx, len(ids))
+    return rx.counters[1]
+
+
+async def test_a_constant_stride_of_two_is_not_loss(receiver):
+    counters = await _ids(receiver, (2, 4, 6, 8))
+    assert counters.missing_frames == 0 and counters.id_step == 2
+
+
+async def test_one_dropped_frame_at_stride_two_is_one_missing(receiver):
+    counters = await _ids(receiver, (2, 4, 6, 10, 12))
+    assert counters.missing_frames == 1
+
+
+async def test_a_gap_of_three_at_stride_one_is_two_missing(receiver):
+    counters = await _ids(receiver, (1, 2, 5))
+    assert counters.missing_frames == 2 and counters.id_step == 1
+
+
+async def test_a_reset_is_counted_and_not_loss_with_a_stride(receiver):
+    counters = await _ids(receiver, (10, 12, 14, 2, 4))
+    assert counters.frame_id_resets == 1 and counters.missing_frames == 0
+
+
+async def test_the_step_is_learned_from_the_smallest_delta(receiver):
+    # A first gap of two steps looks like stride 4 until a smaller step is seen; later gaps use the smaller one.
+    counters = await _ids(receiver, (4, 8, 10, 12))
+    assert counters.id_step == 2 and counters.missing_frames == 0
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index 1448713c96..a910110c93 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -7,12 +7,14 @@
 from __future__ import annotations
 
 import asyncio
+from collections import defaultdict
 
 import numpy as np
 import pytest
 
 from capture_server import protocol as p
-from egocap_web.livekit_receiver import ReceivedFrame
+from egocap_web import livekit_recording as lrec
+from egocap_web.livekit_receiver import ReceivedFrame, StreamCounters
 from egocap_web.livekit_recording import (
     LiveKitRecordingFeed,
     UnixClockMap,
@@ -186,9 +188,12 @@ def __init__(self, frames: dict[int, list[ReceivedFrame]]) -> None:
         self.calls: list[int] = []
         self.gates: dict[int, asyncio.Event] = {}
         self.lost: set[int] = set()
+        self.counters: defaultdict[int, StreamCounters] = defaultdict(StreamCounters)
+        self.timeouts: list[float | None] = []
 
-    async def next_frame_or_lost(self, stream_id: int) -> ReceivedFrame | None:
+    async def next_frame_or_lost(self, stream_id: int, timeout: float | None = None) -> ReceivedFrame | None:
         self.calls.append(stream_id)
+        self.timeouts.append(timeout)
         gate = self.gates.get(stream_id)
         if gate is not None:
             await gate.wait()
@@ -445,6 +450,125 @@ async def test_a_stream_still_waiting_on_its_track_does_not_delay_another_that_i
     assert feed.failure == "Head left: the LiveKit track was lost"
 
 
+# --- what the receiver lost during the take -----------------------------------
+
+
+async def test_overflow_since_the_take_began_fails_the_take_with_the_count():
+    reasons: list[str] = []
+    receiver = FakeReceiver({16: [_received(16, 1_000_000)]})
+    receiver.counters[16].queue_overflow = 4  # before the take: not this take's loss
+    receiver.gates[16] = asyncio.Event()
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left")], ingress, on_failure=reasons.append)
+    feed.start()
+    receiver.counters[16].queue_overflow += 3
+    receiver.gates[16].set()
+    await _settle()
+    await feed.stop()
+    assert ingress.offered == []
+    assert feed.failure == "Head left: the recorder fell behind and dropped 3 frame(s)"
+    assert reasons == [feed.failure]
+
+
+async def test_overflow_before_the_take_is_not_held_against_it():
+    receiver = FakeReceiver({16: [_received(16, 1_000_000)]})
+    receiver.counters[16].queue_overflow = 4
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left")], ingress)
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert len(ingress.offered) == 1 and feed.failure is None
+
+
+async def test_a_publication_change_during_the_take_fails_it():
+    receiver = FakeReceiver({16: [_received(16, 1_000_000)]})
+    receiver.gates[16] = asyncio.Event()
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left")], ingress)
+    feed.start()
+    receiver.counters[16].publication_changes += 1
+    receiver.gates[16].set()
+    await _settle()
+    await feed.stop()
+    assert ingress.offered == []
+    assert feed.failure == "Head left: the camera's publication was replaced during the take"
+
+
+async def test_silence_fails_the_take_after_the_limit(monkeypatch):
+    monkeypatch.setattr(lrec, "_MAX_SILENCE_S", 0.02)
+
+    class Silent(FakeReceiver):
+        async def next_frame_or_lost(self, stream_id, timeout=None):
+            self.timeouts.append(timeout)
+            await asyncio.sleep(timeout)
+            raise asyncio.TimeoutError
+
+    reasons: list[str] = []
+    receiver = Silent({})
+    feed = _feed(receiver, [_stream(16, "Head left")], FakeIngress(), on_failure=reasons.append)
+    feed.start()
+    await asyncio.sleep(0.1)
+    await feed.stop()
+    assert receiver.timeouts == [0.02]
+    assert feed.failure == "Head left: no frame for 0 s although the track is still published"
+    assert reasons == [feed.failure]
+
+
+async def test_the_feed_asks_the_receiver_to_time_out_at_the_silence_limit():
+    receiver = FakeReceiver({})
+    feed = _feed(receiver, [_stream(16, "Head left")], FakeIngress())
+    feed.start()
+    await _settle()
+    await feed.stop()
+    assert receiver.timeouts == [lrec._MAX_SILENCE_S]
+
+
+async def test_loss_reports_counters_since_the_take_began():
+    receiver = FakeReceiver({})
+    counters = receiver.counters[16]
+    counters.queue_overflow, counters.publication_changes = 2, 1
+    feed = _feed(receiver, [_stream(16, "Head left")], FakeIngress())
+    feed.start()
+    counters.received, counters.missing_frames, counters.frame_id_resets = 9, 3, 1
+    counters.queue_overflow += 5
+    counters.publication_changes += 2
+    assert feed.loss() == {
+        "Head left": {
+            "received": 9,
+            "queue_overflow": 5,
+            "publication_changes": 2,
+            "missing_frames": 3,
+            "frame_id_resets": 1,
+        }
+    }
+    await feed.stop()
+
+
+def test_loss_before_start_reports_raw_counters():
+    receiver = FakeReceiver({})
+    receiver.counters[16].queue_overflow = 2
+    feed = _feed(receiver, [_stream(16, "Head left")], FakeIngress())
+    assert feed.loss()["Head left"]["queue_overflow"] == 2
+
+
+async def test_a_healthy_take_with_stride_two_ids_records_every_frame_with_no_missing():
+    import egocap_web.livekit_receiver as lr
+
+    frames = [_received(16, 1_000_000 * i) for i in (1, 2, 3, 4)]
+    receiver = FakeReceiver({16: frames})
+    counters = receiver.counters[16]
+    ingress = FakeIngress()
+    feed = _feed(receiver, [_stream(16, "Head left")], ingress)
+    feed.start()
+    for fid in (2, 4, 6, 8):  # the receiver's own accounting, fed the ids a half-rate publisher numbers
+        lr.LiveKitFrameReceiver._account(counters, fid)
+    await _settle()
+    await feed.stop()
+    assert len(ingress.offered) == 4 and feed.failure is None
+    assert feed.loss()["Head left"]["missing_frames"] == 0
+
+
 # --- frame age window ----------------------------------------------------------
 
 
diff --git a/examples/egocap/tests/backend/test_livekit_recording_source.py b/examples/egocap/tests/backend/test_livekit_recording_source.py
index d8e821f61e..b1cb501cae 100644
--- a/examples/egocap/tests/backend/test_livekit_recording_source.py
+++ b/examples/egocap/tests/backend/test_livekit_recording_source.py
@@ -8,6 +8,7 @@
 
 import asyncio
 import time
+from collections import defaultdict
 from types import SimpleNamespace
 
 import numpy as np
@@ -15,7 +16,7 @@
 
 from capture_server import protocol as p
 from egocap_web import livekit_recording as lrec
-from egocap_web.livekit_receiver import ReceivedFrame
+from egocap_web.livekit_receiver import ReceivedFrame, StreamCounters
 from egocap_web.livekit_recording import LiveKitRecordingSource, recordable_livekit_streams
 
 CAPTURE = p.LiveKitTimestampBasis.SENSOR_CAPTURE_UNIX_US
@@ -105,6 +106,7 @@ def __init__(self, streams, token):
         self.queues = {s.stream_id: asyncio.Queue() for s in streams}
         self.events: list[str] = []
         self.stops = 0
+        self.counters = defaultdict(StreamCounters)
         FakeReceiver.instances.append(self)
 
     async def start(self):
@@ -120,7 +122,7 @@ async def stop(self):
             await FakeReceiver.stop_gate.wait()
         self.stops += 1
 
-    async def next_frame_or_lost(self, stream_id):
+    async def next_frame_or_lost(self, stream_id, timeout=None):
         return await self.queues[stream_id].get()
 
     def clear_queued(self):

From 1f5f68629a86c54bba312a5d1f7e61345e36ba48 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Mon, 9 Nov 2026 18:23:27 -0500
Subject: [PATCH 34/37] egocap: tidy two test helpers flagged by the
 code-quality bot

Use the module's existing from-import instead of a second import style, and pass
SimpleNamespace directly instead of wrapping it in a lambda.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/tests/backend/test_livekit_receiver.py  | 2 +-
 examples/egocap/tests/backend/test_livekit_recording.py | 6 ++----
 2 files changed, 3 insertions(+), 5 deletions(-)

diff --git a/examples/egocap/tests/backend/test_livekit_receiver.py b/examples/egocap/tests/backend/test_livekit_receiver.py
index b4dc73938b..5584cc272c 100644
--- a/examples/egocap/tests/backend/test_livekit_receiver.py
+++ b/examples/egocap/tests/backend/test_livekit_receiver.py
@@ -88,7 +88,7 @@ def emit(self, name: str, *args: object) -> None:
 FAKE_RTC = SimpleNamespace(
     Room=FakeRoom,
     VideoStream=FakeVideoStream,
-    RoomOptions=lambda **fields: SimpleNamespace(**fields),
+    RoomOptions=SimpleNamespace,
     TrackKind=SimpleNamespace(KIND_VIDEO="video"),
     VideoBufferType=SimpleNamespace(RGB24="rgb24"),
 )
diff --git a/examples/egocap/tests/backend/test_livekit_recording.py b/examples/egocap/tests/backend/test_livekit_recording.py
index a910110c93..0de00fed38 100644
--- a/examples/egocap/tests/backend/test_livekit_recording.py
+++ b/examples/egocap/tests/backend/test_livekit_recording.py
@@ -14,7 +14,7 @@
 
 from capture_server import protocol as p
 from egocap_web import livekit_recording as lrec
-from egocap_web.livekit_receiver import ReceivedFrame, StreamCounters
+from egocap_web.livekit_receiver import LiveKitFrameReceiver, ReceivedFrame, StreamCounters
 from egocap_web.livekit_recording import (
     LiveKitRecordingFeed,
     UnixClockMap,
@@ -553,8 +553,6 @@ def test_loss_before_start_reports_raw_counters():
 
 
 async def test_a_healthy_take_with_stride_two_ids_records_every_frame_with_no_missing():
-    import egocap_web.livekit_receiver as lr
-
     frames = [_received(16, 1_000_000 * i) for i in (1, 2, 3, 4)]
     receiver = FakeReceiver({16: frames})
     counters = receiver.counters[16]
@@ -562,7 +560,7 @@ async def test_a_healthy_take_with_stride_two_ids_records_every_frame_with_no_mi
     feed = _feed(receiver, [_stream(16, "Head left")], ingress)
     feed.start()
     for fid in (2, 4, 6, 8):  # the receiver's own accounting, fed the ids a half-rate publisher numbers
-        lr.LiveKitFrameReceiver._account(counters, fid)
+        LiveKitFrameReceiver._account(counters, fid)
     await _settle()
     await feed.stop()
     assert len(ingress.offered) == 4 and feed.failure is None

From bd15655ebd56cf544939c1e0ebe58a3ed1368c77 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Tue, 10 Nov 2026 12:01:24 -0500
Subject: [PATCH 35/37] egocap: add SPDX headers to the LiveKit tile sources

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/frontend/src/CameraGrid.livekit.test.tsx | 4 ++++
 examples/egocap/frontend/src/LiveKitCameraTile.test.tsx  | 4 ++++
 examples/egocap/frontend/src/LiveKitCameraTile.tsx       | 4 ++++
 3 files changed, 12 insertions(+)

diff --git a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
index a6135ca604..244aaf774e 100644
--- a/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
+++ b/examples/egocap/frontend/src/CameraGrid.livekit.test.tsx
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { cleanup, render, screen } from "@testing-library/react";
 import { CameraGrid } from "./CameraGrid";
diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
index f94d6de5f9..7eb88dcd62 100644
--- a/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.test.tsx
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { act, cleanup, render, screen } from "@testing-library/react";
 import { LiveKitCameraTile } from "./LiveKitCameraTile";
diff --git a/examples/egocap/frontend/src/LiveKitCameraTile.tsx b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
index 5503fda09a..e6acb096a3 100644
--- a/examples/egocap/frontend/src/LiveKitCameraTile.tsx
+++ b/examples/egocap/frontend/src/LiveKitCameraTile.tsx
@@ -1,3 +1,7 @@
+// SPDX-FileCopyrightText: 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+//
+// SPDX-License-Identifier: Apache-2.0
+
 /**
  * One live camera tile fed directly by a LiveKit video track.
  *

From 014900ba14612bed8b47361ccc86ed21eb237a75 Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 11 Nov 2026 00:04:41 -0500
Subject: [PATCH 36/37] egocap: sort the backend app's imports

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/backend/egocap_web/app.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index 5c43b4111a..672b97cea0 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -35,12 +35,12 @@
 from .capture_preview import MAX_CAMERA_JPEG_BYTES
 from .capture_status import CaptureStatusMonitor
 from .config import VisualizationConfig, config_from_env, visualization_from_env
-from .operator_settings import OperatorSettingsStore, operator_settings_path
-from .operator_settings import router as operator_settings_router
 from .livekit_preview import API_KEY_ENV, API_SECRET_ENV, subscriber_token
 from .livekit_preview import router as livekit_preview_router
 from .livekit_receiver import RECEIVER_FRAMES_PER_STREAM
 from .livekit_recording import LiveKitRecordingSource, recordable_livekit_streams, unrecordable_reason
+from .operator_settings import OperatorSettingsStore, operator_settings_path
+from .operator_settings import router as operator_settings_router
 from .preview_routes import router as preview_router
 from .recording_adapter import (
     MANUS_GLOVE_SPEC,

From e7c2e284764c91fc6c132f14fbdfebddde558a7b Mon Sep 17 00:00:00 2001
From: Gareth Morgan <gmorgan@nvidia.com>
Date: Wed, 11 Nov 2026 00:18:01 -0500
Subject: [PATCH 37/37] egocap: name the JWT signing key as a key, not a secret

The LiveKit token is an HS256 JWT: the server's key signs it with HMAC-SHA256. A parameter called api_secret made the code scanner read that as password hashing. Only local names change; the LIVEKIT_API_SECRET environment variable is the server's own setting and stays.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Signed-off-by: Gareth Morgan <gmorgan@nvidia.com>
---
 examples/egocap/backend/egocap_web/app.py     |  6 +--
 .../backend/egocap_web/livekit_preview.py     | 10 ++---
 .../tests/backend/test_livekit_preview.py     | 43 ++++++++++---------
 3 files changed, 31 insertions(+), 28 deletions(-)

diff --git a/examples/egocap/backend/egocap_web/app.py b/examples/egocap/backend/egocap_web/app.py
index 672b97cea0..8d0478220f 100644
--- a/examples/egocap/backend/egocap_web/app.py
+++ b/examples/egocap/backend/egocap_web/app.py
@@ -153,10 +153,10 @@ def _station_calibration_assets() -> tuple[CalibrationAsset, ...]:
 
 def _recorder_livekit_token(room: str) -> str:
     """A subscribe-only token for the recorder's own LiveKit connection, signed with the backend's key pair."""
-    api_key, api_secret = os.environ.get(API_KEY_ENV, ""), os.environ.get(API_SECRET_ENV, "")
-    if not api_key or not api_secret:
+    api_key, signing_key = os.environ.get(API_KEY_ENV, ""), os.environ.get(API_SECRET_ENV, "")
+    if not api_key or not signing_key:
         raise RuntimeError(f"{API_KEY_ENV} and {API_SECRET_ENV} must be set to record LiveKit video")
-    return subscriber_token(api_key=api_key, api_secret=api_secret, room=room, now=int(time.time()))
+    return subscriber_token(api_key=api_key, signing_key=signing_key, room=room, now=int(time.time()))
 
 
 def _recording_config_factory(monitor: CaptureStatusMonitor, station_label: str | None, output_root: Path):
diff --git a/examples/egocap/backend/egocap_web/livekit_preview.py b/examples/egocap/backend/egocap_web/livekit_preview.py
index 13ef05dd0f..99566e3b50 100644
--- a/examples/egocap/backend/egocap_web/livekit_preview.py
+++ b/examples/egocap/backend/egocap_web/livekit_preview.py
@@ -41,7 +41,7 @@ def _b64url(data: bytes) -> str:
     return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
 
 
-def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_s: int = TOKEN_TTL_S) -> str:
+def subscriber_token(*, api_key: str, signing_key: str, room: str, now: int, ttl_s: int = TOKEN_TTL_S) -> str:
     """A signed LiveKit access token that may join ``room`` and subscribe, but not publish."""
     header = {"alg": "HS256", "typ": "JWT"}
     claims = {
@@ -62,7 +62,7 @@ def subscriber_token(*, api_key: str, api_secret: str, room: str, now: int, ttl_
     signing_input = ".".join(
         _b64url(json.dumps(part, separators=(",", ":")).encode()) for part in (header, claims)
     )
-    signature = hmac.new(api_secret.encode(), signing_input.encode("ascii"), hashlib.sha256).digest()
+    signature = hmac.new(signing_key.encode(), signing_input.encode("ascii"), hashlib.sha256).digest()
     return f"{signing_input}.{_b64url(signature)}"
 
 
@@ -82,10 +82,10 @@ async def get_livekit_token(request: Request, room: str = "") -> JSONResponse:
     if room not in offered:
         return JSONResponse({"detail": "room is not offered by CaptureServer"}, status_code=404, headers=headers)
     api_key = os.environ.get(API_KEY_ENV, "")
-    api_secret = os.environ.get(API_SECRET_ENV, "")
+    signing_key = os.environ.get(API_SECRET_ENV, "")
     # Offered but unable to sign: say what to set, without echoing any value.
-    if not api_key or not api_secret:
+    if not api_key or not signing_key:
         detail = f"{API_KEY_ENV} and {API_SECRET_ENV} must be set for the backend"
         return JSONResponse({"detail": detail}, status_code=503, headers=headers)
-    token = subscriber_token(api_key=api_key, api_secret=api_secret, room=room, now=int(time.time()))
+    token = subscriber_token(api_key=api_key, signing_key=signing_key, room=room, now=int(time.time()))
     return JSONResponse({"token": token}, headers=headers)
diff --git a/examples/egocap/tests/backend/test_livekit_preview.py b/examples/egocap/tests/backend/test_livekit_preview.py
index 6de71d2292..bb9dc06c87 100644
--- a/examples/egocap/tests/backend/test_livekit_preview.py
+++ b/examples/egocap/tests/backend/test_livekit_preview.py
@@ -25,7 +25,7 @@
 )
 
 KEY = "APIkeyForTests"
-SECRET = "super-secret-signing-value-0123456789"
+SIGNING_KEY = "test-signing-value-0123456789"
 
 
 def _unb64(segment: str) -> bytes:
@@ -44,18 +44,18 @@ def _decode(token: str) -> tuple[dict, dict, bytes, bytes]:
     )
 
 
-def _hs256(secret: str, signing_input: bytes) -> bytes:
-    return hmac.new(secret.encode(), signing_input, hashlib.sha256).digest()
+def _hs256(key: str, signing_input: bytes) -> bytes:
+    return hmac.new(key.encode(), signing_input, hashlib.sha256).digest()
 
 
 def test_token_header_is_hs256_jwt():
-    header, _, _, _ = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1000))
+    header, _, _, _ = _decode(subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="r", now=1000))
     assert header == {"alg": "HS256", "typ": "JWT"}
 
 
 def test_token_claims_name_issuer_validity_window_and_subscribe_only_grant():
     _, claims, _, _ = _decode(
-        subscriber_token(api_key=KEY, api_secret=SECRET, room="sensing-preview", now=1000, ttl_s=60)
+        subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="sensing-preview", now=1000, ttl_s=60)
     )
     assert claims["iss"] == KEY
     assert claims["nbf"] == 1000
@@ -71,27 +71,30 @@ def test_token_claims_name_issuer_validity_window_and_subscribe_only_grant():
 
 
 def test_token_default_ttl_is_one_hour():
-    _, claims, _, _ = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=5))
+    _, claims, _, _ = _decode(subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="r", now=5))
     assert claims["exp"] - claims["nbf"] == 3600
 
 
 def test_every_token_gets_a_unique_viewer_identity():
     subs = {
-        _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1))[1]["sub"] for _ in range(50)
+        _decode(subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="r", now=1))[1]["sub"]
+        for _ in range(50)
     }
     assert len(subs) == 50
 
 
 def test_signature_verifies_with_the_secret_and_not_with_another():
-    _, _, signature, signing_input = _decode(subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1))
-    assert hmac.compare_digest(signature, _hs256(SECRET, signing_input))
-    assert not hmac.compare_digest(signature, _hs256("another-secret", signing_input))
+    _, _, signature, signing_input = _decode(
+        subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="r", now=1)
+    )
+    assert hmac.compare_digest(signature, _hs256(SIGNING_KEY, signing_input))
+    assert not hmac.compare_digest(signature, _hs256("another-key", signing_input))
 
 
 def test_token_never_contains_the_secret():
-    token = subscriber_token(api_key=KEY, api_secret=SECRET, room="r", now=1)
-    assert SECRET not in token
-    assert SECRET.encode() not in b"".join(_unb64(s) for s in token.split(".")[:2])
+    token = subscriber_token(api_key=KEY, signing_key=SIGNING_KEY, room="r", now=1)
+    assert SIGNING_KEY not in token
+    assert SIGNING_KEY.encode() not in b"".join(_unb64(s) for s in token.split(".")[:2])
 
 
 def _offer(room: str = "sensing-preview") -> p.LiveKitCameraStream:
@@ -122,7 +125,7 @@ def make(streams: tuple | None) -> TestClient:
 @pytest.fixture
 def credentials(monkeypatch):
     monkeypatch.setenv(API_KEY_ENV, KEY)
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    monkeypatch.setenv(API_SECRET_ENV, SIGNING_KEY)
 
 
 URL = "/api/livekit-token?room=sensing-preview"
@@ -162,7 +165,7 @@ def test_old_route_is_gone(client_factory, credentials):
 @pytest.mark.parametrize("missing", [(API_KEY_ENV,), (API_SECRET_ENV,), (API_KEY_ENV, API_SECRET_ENV)])
 def test_missing_credentials_give_503_naming_variables_but_no_values(client_factory, monkeypatch, missing):
     monkeypatch.setenv(API_KEY_ENV, KEY)
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    monkeypatch.setenv(API_SECRET_ENV, SIGNING_KEY)
     for name in missing:
         monkeypatch.delenv(name)
     response = client_factory((_offer(),)).get(URL)
@@ -170,13 +173,13 @@ def test_missing_credentials_give_503_naming_variables_but_no_values(client_fact
     assert response.headers["cache-control"] == "no-store"
     detail = response.json()["detail"]
     assert API_KEY_ENV in detail and API_SECRET_ENV in detail
-    assert SECRET not in response.text
+    assert SIGNING_KEY not in response.text
     assert KEY not in response.text
 
 
 def test_empty_credentials_count_as_unset(client_factory, monkeypatch):
     monkeypatch.setenv(API_KEY_ENV, "")
-    monkeypatch.setenv(API_SECRET_ENV, SECRET)
+    monkeypatch.setenv(API_SECRET_ENV, SIGNING_KEY)
     assert client_factory((_offer(),)).get(URL).status_code == 503
 
 
@@ -190,7 +193,7 @@ def test_offered_room_gets_a_verifiable_subscribe_only_token(client_factory, cre
     assert claims["video"]["room"] == "sensing-preview"
     assert claims["video"]["canPublish"] is False
     assert claims["iss"] == KEY
-    assert hmac.compare_digest(signature, _hs256(SECRET, signing_input))
+    assert hmac.compare_digest(signature, _hs256(SIGNING_KEY, signing_input))
 
 
 def test_room_is_matched_among_several_offered_streams(client_factory, credentials):
@@ -200,8 +203,8 @@ def test_room_is_matched_among_several_offered_streams(client_factory, credentia
 
 def test_secret_is_never_in_the_response_body_or_headers(client_factory, credentials):
     response = client_factory((_offer(),)).get(URL)
-    assert SECRET not in response.text
-    assert SECRET not in str(dict(response.headers))
+    assert SIGNING_KEY not in response.text
+    assert SIGNING_KEY not in str(dict(response.headers))
 
 
 def test_each_request_gets_a_fresh_viewer_identity(client_factory, credentials):