From 13b3b36b8b47b7ec298cfd9e22cb3529c9691544 Mon Sep 17 00:00:00 2001
From: Shao Duan <46639847+shaoxiongduan@users.noreply.github.com>
Date: Wed, 7 Oct 2026 02:07:37 -0700
Subject: [PATCH] [feat] Add Infinite Livestream app (#1878)

Co-authored-by: SolitaryThinker <wlsaidhi@gmail.com>
Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .buildkite/scripts/unit_test.sh               |   4 +
 .github/scripts/plan_merge_ci.py              |   4 +
 apps/infinite_livestream/README.md            | 290 ++++++++++
 .../infinite_livestream/__init__.py           |   5 +
 .../infinite_livestream/backend.py            | 516 ++++++++++++++++++
 .../infinite_livestream/chat.py               |  83 +++
 .../infinite_livestream/clip_plan.py          | 162 ++++++
 .../infinite_livestream/clip_queue.py         | 148 +++++
 .../infinite_livestream/config.py             | 328 +++++++++++
 .../configs/infinite_livestream.yaml          |  93 ++++
 .../infinite_livestream/director.py           | 408 ++++++++++++++
 .../infinite_livestream/engine.py             | 475 ++++++++++++++++
 .../infinite_livestream/group_tag.py          |  54 ++
 .../infinite_livestream/main.py               | 147 +++++
 .../infinite_livestream/metadata.py           |  56 ++
 .../infinite_livestream/moderator.py          |  52 ++
 .../infinite_livestream/muxer.py              | 139 +++++
 .../infinite_livestream/pacer.py              | 193 +++++++
 .../infinite_livestream/presets/fillers.json  | 130 +++++
 .../infinite_livestream/server_entry.py       |  30 +
 .../infinite_livestream/sink.py               | 454 +++++++++++++++
 .../infinite_livestream/tests/__init__.py     |   0
 .../infinite_livestream/tests/conftest.py     |  22 +
 .../tests/test_chat_endpoint.py               |  53 ++
 .../tests/test_clip_plan.py                   |  86 +++
 .../infinite_livestream/tests/test_config.py  | 156 ++++++
 .../tests/test_director_admission.py          | 155 ++++++
 .../tests/test_frame_metadata.py              | 126 +++++
 .../tests/test_hls_metadata.py                | 136 +++++
 .../tests/test_import_contract.py             |  99 ++++
 .../tests/test_metadata_player.cjs            | 219 ++++++++
 .../tests/test_prompt_flow.py                 |  97 ++++
 .../tests/test_service_lifecycle.py           |  55 ++
 .../tests/test_sink_shutdown.py               | 128 +++++
 .../tests/test_state_mirror.py                |  76 +++
 .../infinite_livestream/upsampler.py          | 359 ++++++++++++
 .../infinite_livestream/web/icon.svg          |   6 +
 .../infinite_livestream/web/index.html        | 497 +++++++++++++++++
 .../infinite_livestream/web/logo.svg          |  18 +
 .../infinite_livestream/web/metadata.js       | 137 +++++
 .../infinite_livestream/webapp.py             | 261 +++++++++
 apps/infinite_livestream/pyproject.toml       |  34 ++
 .../tests/contract/test_merge_ci_plan.py      |   6 +
 pyproject.toml                                |  19 +-
 44 files changed, 6512 insertions(+), 4 deletions(-)
 create mode 100644 apps/infinite_livestream/README.md
 create mode 100644 apps/infinite_livestream/infinite_livestream/__init__.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/backend.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/chat.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/clip_plan.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/clip_queue.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/config.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/configs/infinite_livestream.yaml
 create mode 100644 apps/infinite_livestream/infinite_livestream/director.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/engine.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/group_tag.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/main.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/metadata.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/moderator.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/muxer.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/pacer.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/presets/fillers.json
 create mode 100644 apps/infinite_livestream/infinite_livestream/server_entry.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/sink.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/__init__.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/conftest.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_chat_endpoint.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_clip_plan.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_config.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_director_admission.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_frame_metadata.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_hls_metadata.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_import_contract.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_metadata_player.cjs
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_prompt_flow.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_service_lifecycle.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_sink_shutdown.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/tests/test_state_mirror.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/upsampler.py
 create mode 100644 apps/infinite_livestream/infinite_livestream/web/icon.svg
 create mode 100644 apps/infinite_livestream/infinite_livestream/web/index.html
 create mode 100644 apps/infinite_livestream/infinite_livestream/web/logo.svg
 create mode 100644 apps/infinite_livestream/infinite_livestream/web/metadata.js
 create mode 100644 apps/infinite_livestream/infinite_livestream/webapp.py
 create mode 100644 apps/infinite_livestream/pyproject.toml

diff --git a/.buildkite/scripts/unit_test.sh b/.buildkite/scripts/unit_test.sh
index aacba0fcc..63bf27ecc 100644
--- a/.buildkite/scripts/unit_test.sh
+++ b/.buildkite/scripts/unit_test.sh
@@ -1,7 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# The livestream app's tests are CPU-only; its single gpu-marked module is
+# deselected, and DreamVerse's GPU tests have their own lane.
 exec pytest \
+  ./apps/infinite_livestream/infinite_livestream/tests \
   ./fastvideo/tests/api/ \
   ./fastvideo/tests/contract/ \
   ./fastvideo/tests/dataset/ \
@@ -27,4 +30,5 @@ exec pytest \
   --ignore=./fastvideo/tests/entrypoints/test_openai_api_integration.py \
   --ignore=./fastvideo/tests/train/models \
   --ignore=./fastvideo/tests/train/methods \
+  -m "not gpu" \
   -vs
diff --git a/.github/scripts/plan_merge_ci.py b/.github/scripts/plan_merge_ci.py
index 7025d81e7..867fca88f 100644
--- a/.github/scripts/plan_merge_ci.py
+++ b/.github/scripts/plan_merge_ci.py
@@ -523,6 +523,10 @@ def classify_paths(paths: list[str]) -> MergePlan:
             # DreamVerse is already one of the six automatic Fastcheck lanes.
             plan.reasons.append(f"covered by automatic DreamVerse Fastcheck: {path}")
             continue
+        if path.startswith("apps/infinite_livestream/"):
+            # The app's CPU-only tests run in the automatic unit Fastcheck lane.
+            plan.reasons.append(f"covered by automatic unit Fastcheck: {path}")
+            continue
         if path.startswith("fastvideo/tests/"):
             # The automatic unit/component Fastcheck lanes own the remaining
             # package tests. Domain-specific expensive test roots were handled
diff --git a/apps/infinite_livestream/README.md b/apps/infinite_livestream/README.md
new file mode 100644
index 000000000..af1add185
--- /dev/null
+++ b/apps/infinite_livestream/README.md
@@ -0,0 +1,290 @@
+# Infinite Livestream
+
+Infinite Livestream is a chat-driven FastH3 broadcast. Viewers type prompts into a web
+page, the app rewrites them with an LLM, generates clips with FastVideo, and
+plays them back as one continuous HLS stream on that same page. When nobody is
+typing it feeds itself from a preset of idle prompts, so the channel never goes
+dark.
+
+It lives in this monorepo under `apps/infinite_livestream/`.
+
+```
+chat -> Director -> PromptUpsampler (OpenAI-compatible LLM)
+           |
+           v enqueue / move / pop
+        Engine -> FastH3Backend -> FastVideo
+           |  frames + audio
+           v
+        Pacer -> HlsSink -> the page's <video>
+```
+
+Everything runs in a single process, and the page, the playlist and the chat
+endpoint are served from one HTTP origin, so publishing the stream means
+pointing a tunnel or reverse proxy at one port.
+
+## Requirements
+
+- Linux with NVIDIA GPUs. The [default configuration](infinite_livestream/configs/infinite_livestream.yaml)
+  targets four GB200 GPUs: Blackwell `sm_100a` sparse attention, a replicated
+  transformer, and GPU-resident text encoder and VAEs. A different GPU setup
+  needs corresponding changes to `runtime` and `inference`; the GPU count must
+  divide the model's attention head count.
+- Python 3.12 and [uv](https://docs.astral.sh/uv/getting-started/installation/).
+- A CUDA 13 toolkit with `nvcc` and a compatible C++ compiler for the kernel
+  source build below.
+- A complete FastH3 checkpoint; see [Download weights](#download-weights).
+- An API key for prompt rewriting. The default configuration uses OpenAI;
+  rewriting runs for idle filler too, so the stream needs the key even when
+  nobody is chatting.
+- FFmpeg with the `libx264` and `aac` encoders on `PATH`; see [FFmpeg](#ffmpeg).
+
+## Install
+
+Use a source checkout containing `apps/infinite_livestream/`. Run these commands
+from the FastVideo repository root. The app is packaged in FastVideo's
+`infinite-livestream` extra; `fasth3` adds its generator dependencies.
+
+```bash
+uv venv --python 3.12 --seed
+source .venv/bin/activate
+
+git submodule update --init --recursive \
+  fastvideo-kernel/include/cutlass fastvideo-kernel/include/tk
+
+# Point this at your CUDA 13 toolkit.
+export CUDA_HOME=/usr/local/cuda
+export CUDACXX="$CUDA_HOME/bin/nvcc"
+TORCH_CUDA_ARCH_LIST=10.0a UV_TORCH_BACKEND=cu130 \
+  uv pip install -e ".[fasth3,infinite-livestream]"
+```
+
+This installs the pinned FA4 package and builds this checkout's
+`fastvideo-kernel` with the Blackwell VSA extension. The CUDA and architecture
+settings above match the default GB200 configuration. See the
+[kernel build guide](../../fastvideo-kernel/README.md#installation) for build
+prerequisites and troubleshooting.
+
+## Download weights
+
+Use [FastH3 v1 VSA-DataFree](https://huggingface.co/FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree),
+FastVideo's recommended four-step checkpoint. Its VSA-H3 attention settings
+match this app's defaults. Download the whole snapshot, including the text
+encoder and both VAEs, into a local directory accessible to the GPU host:
+
+```bash
+export LIVESTREAM_WEIGHTS_PATH=/absolute/path/to/FastH3-v1-VSA-DataFree
+hf download FastVideo/FastVideo-FastH3-4-step-Preview-v1-VSA-DataFree \
+  --local-dir "$LIVESTREAM_WEIGHTS_PATH"
+```
+
+The app expects `modular_model_index.json` and the `transformer`, `text_encoder`,
+`tokenizer`, `processor`, `vae`, `audio_vae`, `scheduler` and `audio_scheduler`
+directories. Downloading only the transformer is insufficient; the text encoder
+and VAEs need their weight files as well as their configs.
+
+## FFmpeg
+
+Install FFmpeg with `libx264` and `aac` encoding support. For example, on
+Debian/Ubuntu:
+
+```bash
+sudo apt install ffmpeg
+```
+
+For the optimized native build, follow Dreamverse's
+[FFmpeg instructions](../dreamverse/README.md#optional-building-ffmpeg-for-better-performance).
+After running that installer, source its environment file in the shell that
+will launch the livestream:
+
+```bash
+source apps/dreamverse/scripts/ffmpeg-env.sh
+```
+
+## Quick start
+
+With the virtual environment active and `LIVESTREAM_WEIGHTS_PATH` set above:
+
+```bash
+export OPENAI_API_KEY=...
+infinite-livestream-server
+```
+
+Open **<http://localhost:8081>** on the server, or use the server's hostname when
+connecting remotely. The default bind address is `0.0.0.0`; `--port` overrides
+the port.
+
+The page and the HLS stream start while the model loads, so a viewer arriving
+during startup sees the page and a black stream. Weight loading and compile
+warm-up take several minutes. Check readiness with:
+
+```bash
+curl http://localhost:8081/healthz
+```
+
+`{"connected": true}` means model loading and warm-up have finished.
+
+## Configuration
+
+Copy the [default YAML](infinite_livestream/configs/infinite_livestream.yaml)
+from the repository root, edit it, and pass the copy with `--config`:
+
+```bash
+cp apps/infinite_livestream/infinite_livestream/configs/infinite_livestream.yaml my-config.yaml
+infinite-livestream-server --config my-config.yaml
+```
+
+| Block | Contents |
+|---|---|
+| `inference` | What the checkpoint is asked for: clip length, canvas, sparse-attention kernels, compile policy. |
+| `runtime` | How it is hosted: GPU count, sharding, offload. |
+| `upsampler` | Prompt rewriting: model, endpoint, how many clips one prompt may become. |
+| `moderation` | Whether viewer prompts are checked, and against which endpoint. |
+| `director` | Idle filler depth, per-viewer cooldown, chat command, filler directory. |
+| `output` | Where the playlist is written (defaults under `$XDG_STATE_HOME`), the video bitrate, and retained playback history. |
+| `web` | Bind address and port. |
+
+For another OpenAI-compatible provider, set `upsampler.base_url` and
+`upsampler.model`. Moderation is enabled by default and uses that endpoint too
+unless `moderation.base_url` is set. If the provider does not offer `/moderations`,
+configure a separate moderation endpoint and export its `MODERATION_API_KEY`.
+
+API keys and the machine's weights path stay in the environment:
+
+| Variable | Description |
+|---|---|
+| `OPENAI_API_KEY` | Required. Prompt rewriting runs for the idle filler too, so the stream does not start without it. |
+| `LIVESTREAM_WEIGHTS_PATH` | Required. FastH3 model directory. `--weights` overrides it. |
+| `MODERATION_API_KEY` | Optional. Falls back to `OPENAI_API_KEY`. |
+
+## Clip geometry
+
+Clip geometry is fixed by the checkpoint: 24 fps, frame counts of the form
+`17n + 5`, a 5 to 15 second duration window, and a 768 pixel short edge.
+`inference.clip_seconds: 15.083` is the longest clip it can produce, at 362
+frames (15.0 s rounds up to the next valid length).
+
+Keeping one clip length means one compiled shape. Setting
+`inference.warmup_lengths: all` warms every legal length instead, which makes
+startup slower but avoids a one-off compile stall on a viewer's first
+odd-length clip.
+
+## API Endpoints
+
+| Route | Description |
+|---|---|
+| `GET /` | The watch page. |
+| `GET /assets/<file>` | Viewer scripts, logo, and favicon. |
+| `GET /hls/<file>` | Playlist and segments, written by `infinite_livestream/sink.py`. |
+| `GET /healthz` | `{"connected": bool}`, true once the model is loaded. |
+| `WS /state` | One JSON snapshot on connect, then one per change. |
+| `POST /chat` | `{"author": str, "text": str}`. Returns 429 with `retry_after` when that viewer is still on cooldown. |
+
+The cooldown is answered by `POST /chat` rather than reported later, so the
+sender's page can disable its send box and count down. The chat feed is shared
+by every viewer, so refusals are kept out of it.
+
+## Idle fillers
+
+When nobody is typing, the stream keeps itself fed from a list of prompts.
+`director.fillers` names the directory holding `fillers.json`, and defaults to
+the one that ships in `infinite_livestream/presets/`.
+
+```json
+{
+  "style": "the look and tone for idle filler clips",
+  "idle_prompts": ["a lighthouse keeper teaching a seagull to play chess"]
+}
+```
+
+`style` defines the house style for idle filler clips. Viewer prompts may use
+their own style by default (`upsampler.viewer_free_style: true`). Set
+`upsampler.viewer_free_style: false` to apply the house style to viewer prompts
+as well.
+`idle_prompts` feeds the filler; an empty list turns the filler off, as does
+`director.idle_queue_target: 0`.
+
+To change the stream's identity, copy the directory, edit `fillers.json` and
+point `director.fillers` at it. The file is read once, at startup.
+
+## Now-playing titles
+
+Titles travel inside the HLS segments as timed ID3 metadata. The page prefers
+hls.js where supported so browsers use the same metadata parser; native HLS is
+the fallback. The player parses the metadata into cues, and the page selects the
+title using the browser's presented frame timestamp, including after paused seeks
+or buffering. Each segment includes
+the active title for viewers joining halfway through a clip. A repeated final
+frame keeps its title until the next clip appears. Browsers without
+`requestVideoFrameCallback` fall back to playback-clock cue events, which can be
+less precise at seek boundaries.
+
+FFmpeg encodes video and audio once; PyAV copies the compressed packets into HLS
+and adds the metadata. This does not use extra GPUs or encode a stream per viewer.
+Append `?debug=1` to see the active clip ID and playback position.
+
+`output.hls_retention_s` controls retained history (120 seconds by default),
+without increasing the player's target live latency. A viewer whose requested
+footage has expired must rejoin available footage. Paused seeks into gaps move
+to the next buffered frame. Encoder restarts retain recent segments and mark the
+new media timeline explicitly.
+
+The page stacks video and chat in portrait. Wide, short landscape screens put
+chat beside the video, with the title below the video and the queue collapsed
+initially. Rotating the page preserves playback.
+
+Playback, titles, seeking, and buffering were tested in Firefox and Chromium,
+including phone and tablet layout emulation. Safari and physical mobile devices
+remain unverified. If an embedded browser cannot decode H.264/AAC, open the page
+in an external browser.
+
+## Tests
+
+```bash
+pytest apps/infinite_livestream/infinite_livestream/tests -m "not gpu"
+```
+
+CPU media integration tests require FFmpeg with `libx264` and `aac`. The browser
+metadata adapter also has a dependency-free JavaScript regression test:
+
+```bash
+node --test apps/infinite_livestream/infinite_livestream/tests/test_metadata_player.cjs
+```
+
+One test is marked `gpu`. It checks that `infinite_livestream/clip_plan.py`'s copy of
+MiniMax-H3's packing constants still matches FastVideo's, and importing the
+upstream module needs a live CUDA driver. Run it when the pinned FastVideo
+version moves.
+
+## Adding another model
+
+`FastH3Backend.submit(frames, prompt, seed, height, width)` is the seam.
+Everything above it, meaning the engine, director, queues, pacer, sink and web
+app, is model-agnostic. Everything below it is MiniMax-H3 specific:
+`clip_plan.py` is its geometry and `backend.py` selects its kernels.
+
+A second checkpoint needs its own geometry module and its own backend behind
+that seam. LTX-2, for example, packs `8n + 1` frames at different resolutions.
+
+## Troubleshooting
+
+**`ffmpeg not found on PATH`.** Follow [FFmpeg](#ffmpeg). If you used the native
+build, source `apps/dreamverse/scripts/ffmpeg-env.sh` before starting the app.
+
+**The weights are incomplete.** Startup lists the missing components before
+any GPU work begins. The model directory needs `transformer`, `text_encoder`,
+`tokenizer`, `processor`, `vae`, `audio_vae`, `scheduler`, `audio_scheduler`
+and `modular_model_index.json`. See [Download weights](#download-weights) for
+the complete checkpoint.
+
+**`FastH3's sm100a route needs fastvideo-kernel built with the Blackwell VSA
+extension`.** Startup checks for the fast sparse-attention kernel before
+loading any weights. Follow [Install](#install) to build it, or set
+`inference.vsa_kernel: triton` in your config to use the slower fallback.
+
+**`FastH3's FA4 route needs the pinned flash-attn-4 package`.** Include the
+`fasth3` extra as shown in [Install](#install), or set `inference.fa4: false` in
+your config.
+
+**A clip takes much longer than the others.** Each distinct clip length is a
+separate compiled shape, and the first clip at a new length pays a one-off
+compile cost. `inference.warmup_lengths: all` pays all of them at startup instead.
diff --git a/apps/infinite_livestream/infinite_livestream/__init__.py b/apps/infinite_livestream/infinite_livestream/__init__.py
new file mode 100644
index 000000000..bcfe34487
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/__init__.py
@@ -0,0 +1,5 @@
+"""Infinite Livestream: a chat-driven FastH3 broadcast."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
diff --git a/apps/infinite_livestream/infinite_livestream/backend.py b/apps/infinite_livestream/infinite_livestream/backend.py
new file mode 100644
index 000000000..9a44bfe47
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/backend.py
@@ -0,0 +1,516 @@
+"""The FastVideo side of FastH3: GPU work, and nothing stream-facing.
+
+`FastH3Backend` owns the multi-GPU `VideoGenerator`, the environment profile
+it must be built under, the load-time warm-up, and one worker thread that
+builds clips serially. `engine.py` calls `submit` and polls the `ClipJob` it
+gets back; nothing here knows about queues, chat or the sink.
+
+torch, torchaudio and fastvideo are imported inside methods, so importing this
+module needs none of them and the config tests can run without a GPU.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import queue
+import threading
+import time
+from pathlib import Path
+from typing import Any
+
+from . import clip_plan
+from .config import ModelConfig
+
+logger = logging.getLogger("infinite_livestream.backend")
+
+FRAME_RATE = clip_plan.FPS
+
+# The checkpoint's audio decoder runs at 32 kHz; the sink wants 48 kHz.
+OUTPUT_SAMPLE_RATE = 48_000
+NATIVE_SAMPLE_RATE = 32_000
+
+_WORKER_POLL_SECONDS = 0.1
+
+# Warm-up output is discarded; this only has to be an ordinary prompt.
+WARMUP_PROMPT = "A slow cinematic shot of sunlight moving across a quiet room."
+
+# Every prompt is padded or truncated to exactly this many tokens. Regional
+# torch.compile keys on the packed sequence length, which includes the prompt's
+# token count, so a novel length recompiles -- ~23 s against ~15 s for the clip
+# itself. One fixed length is one compiled shape, warmed once. 256 comfortably
+# holds the 800-character cap.
+PROMPT_TOKENS = 256
+
+
+class ClipJob:
+    """The handle to one submitted build: its inputs, outcome, and completion.
+
+    The error is carried back rather than only logged, so the submitter can
+    report the failed clip to clients. ``cancelled`` set before the worker
+    reaches the job skips the build entirely; set after, the build runs to
+    completion and the submitter discards the result.
+    """
+
+    __slots__ = ("cancelled", "done", "error", "fn", "result")
+
+    def __init__(self, fn) -> None:
+        self.fn = fn
+        self.done = threading.Event()
+        self.error: BaseException | None = None
+        self.result: tuple[list[Any], Any] | None = None
+        self.cancelled = False
+
+
+class FastH3Backend:
+    """Build FastH3 clips on demand, serialised on one worker thread.
+
+    The GPU work itself lives in the engine processes FastVideo spawns; the
+    thread exists to serialise submissions and to give teardown a single handle
+    to wait on.
+    """
+
+    def __init__(self, config: ModelConfig, model_path: Path) -> None:
+        """Remember the recipe and the weights location; nothing loads yet."""
+        self._config = config
+        self._model_path = model_path
+        self._jobs: queue.Queue[ClipJob] = queue.Queue()
+        self._worker: threading.Thread | None = None
+        self.generator: Any = None
+
+    # ------------------------------------------------------------------ load
+
+    def load(self) -> None:
+        """Build the generator and warm every configured clip shape.
+
+        Runs once at startup, and this returning is what lets the engine
+        accept work -- so everything that can fail (missing kernels, a broken
+        native linkage, a cold compile) must fail here, not on a viewer's clip.
+        """
+        # Must happen before the generator is built: the engine spawns worker
+        # processes, which inherit os.environ, and these select the attention
+        # backend and the sparse kernel.
+        self._apply_profile_environment()
+        self._validate_profile_dependencies()
+        self._raise_dynamo_limits()
+
+        runtime = self._config.runtime
+        num_gpus = int(runtime.get("num_gpus", 4))
+        logger.info("building the generator: %s, %d gpu(s), %d-frame clips", self._model_path, num_gpus,
+                    self._config.clip_frames)
+
+        from fastvideo import VideoGenerator
+
+        self.generator = VideoGenerator.from_config(self._generator_config())
+        self._load_tokenizer()
+
+        self._worker = threading.Thread(target=self._worker_loop, name="fast-h3-generation", daemon=True)
+        self._worker.start()
+        self._preload_native_imports()
+        self._run_blocking(self._warmup)
+        logger.info("backend loaded")
+
+    def _load_tokenizer(self) -> None:
+        """Load the checkpoint's tokenizer and calibrate the one-token pad filler.
+
+        Padding must land on an exact token count, so the filler is verified to
+        cost exactly one token at load rather than assumed.
+        """
+        from transformers import AutoTokenizer
+
+        self._tokenizer = AutoTokenizer.from_pretrained(str(self._model_path / "tokenizer"))
+        for candidate in (" .", ".", " a"):
+            base = len(self._tokenizer.encode(WARMUP_PROMPT, add_special_tokens=False))
+            padded = len(self._tokenizer.encode(WARMUP_PROMPT + candidate, add_special_tokens=False))
+            if padded == base + 1:
+                self._pad_filler = candidate
+                return
+        raise RuntimeError("no single-token pad filler found for this tokenizer")
+
+    def _pad_prompt(self, prompt: str) -> str:
+        """Return *prompt* at exactly ``PROMPT_TOKENS`` tokens.
+
+        Shorter prompts gain trailing filler tokens; a longer one (past the
+        800-character cap only in pathological tokenizations) is truncated at
+        the token boundary. The client-facing prompt — what `ClipInfo` echoes —
+        is the original; only the engine sees this form.
+        """
+
+        def encode(text: str) -> int:
+            return len(self._tokenizer.encode(text, add_special_tokens=False))
+
+        ids = self._tokenizer.encode(prompt, add_special_tokens=False)
+        if ids and len(ids) >= PROMPT_TOKENS:
+            return self._tokenizer.decode(ids[:PROMPT_TOKENS])
+        padded = prompt + self._pad_filler * (PROMPT_TOKENS - len(ids))
+        # Filler cost is calibrated, but a prompt's own tail can merge with the
+        # first filler token; correct by measurement rather than assumption.
+        while encode(padded) > PROMPT_TOKENS:
+            padded = padded[:-len(self._pad_filler)]
+        while encode(padded) < PROMPT_TOKENS:
+            padded += self._pad_filler
+        if encode(padded) != PROMPT_TOKENS:
+            logger.warning("prompt padded to %d tokens, wanted %d", encode(padded), PROMPT_TOKENS)
+        return padded
+
+    @staticmethod
+    def _raise_dynamo_limits() -> None:
+        """Stop a novel tensor shape from being a hard failure.
+
+        Each clip length is a torch.compile shape, and the fullgraph regional
+        route treats exceeding dynamo's recompile limit as a crash rather than
+        a fallback. FastVideo's own imports lower it (`layers/lora/linear.py`
+        to 16, longcat's `bsa_interface.py` to 32), so this raises it again
+        and turns overflow back into a recompile.
+
+        One pinned clip length keeps every process far under even the lowered
+        limit; a varied `warmup_lengths` is where this becomes the seatbelt it
+        is meant to be.
+        """
+        import torch._dynamo.config as dynamo_config
+
+        limit = int(os.environ.get("LIVESTREAM_DYNAMO_RECOMPILE_LIMIT", "64"))
+        dynamo_config.recompile_limit = max(limit, dynamo_config.recompile_limit)
+        dynamo_config.cache_size_limit = max(limit, dynamo_config.cache_size_limit)
+        dynamo_config.accumulated_recompile_limit = max(512, dynamo_config.accumulated_recompile_limit)
+        dynamo_config.accumulated_cache_size_limit = max(512, dynamo_config.accumulated_cache_size_limit)
+        dynamo_config.fail_on_recompile_limit_hit = False
+        logger.info("dynamo recompile limit raised to %d", dynamo_config.recompile_limit)
+
+    @staticmethod
+    def _preload_native_imports() -> None:
+        """Touch every deferred native import the build path needs.
+
+        Otherwise the first one happens on the first real clip, where a broken
+        linkage is a dead stream rather than a startup error. The resample is a
+        real call, so it fails here or not at all.
+        """
+        import numpy  # noqa: F401
+        import torch
+        import torchaudio.functional as AF
+
+        AF.resample(torch.zeros(2, NATIVE_SAMPLE_RATE // 10), NATIVE_SAMPLE_RATE, OUTPUT_SAMPLE_RATE)
+
+    # --------------------------------------------------------------- profile
+
+    def _apply_profile_environment(self) -> None:
+        """Set the FastH3 profile environment, as the reference CLI does.
+
+        Mirrors `examples/inference/basic/basic_fasth3.py:profile_environment`.
+        Disabled features are set explicitly too, so a shell's inherited
+        experiment settings cannot silently change what gets served.
+        """
+        cfg = self._config.inference
+        vsa_kernel = str(cfg.get("vsa_kernel", "sm100a"))
+        fusions = "all" if bool(cfg.get("h3_fusions", True)) else "0"
+        environment: dict[str, str | None] = {
+            "FASTVIDEO_ATTENTION_BACKEND": "VIDEO_SPARSE_ATTN_H3",
+            "FASTVIDEO_VSA_SM100A": "1" if vsa_kernel == "sm100a" else "0",
+            "FASTVIDEO_VSA_CUTEDSL": "0",
+            # A non-empty path enables the diagnostic probe; it must stay unset.
+            "FASTVIDEO_H3_VSA_PROBE": None,
+            "FASTVIDEO_DISABLE_ATTENTION_COMPILE": "0",
+            "FASTVIDEO_FA4": "1" if bool(cfg.get("fa4", True)) else "0",
+            "FASTVIDEO_NVFP4_FA4": "0",
+            "FASTVIDEO_MINIMAX_H3_FA4_PACKED_VARLEN": "0",
+            "FASTVIDEO_MINIMAX_H3_FUSIONS": fusions,
+            "FASTVIDEO_INFERENCE_TORCH_COMPILE": ("1" if bool(cfg.get("inference_torch_compile", True)) else "0"),
+            "FASTVIDEO_VAE_PARALLEL_DECODE": ("1" if bool(cfg.get("vae_parallel_decode", True)) else "0"),
+            "FASTVIDEO_VAE_PARALLEL_ENCODE": "0",
+            "FASTVIDEO_VAE_PARALLEL_DECODE_STRATEGY": "gather",
+            "FASTVIDEO_ULYSSES_A2A": str(cfg.get("ulysses_a2a", "off")),
+            "FASTVIDEO_STAGE_LOGGING": "1",
+        }
+        for name, value in environment.items():
+            if value is None:
+                os.environ.pop(name, None)
+            else:
+                os.environ[name] = value
+        logger.info("profile: %s", " ".join(f"{k}={v or '<unset>'}" for k, v in environment.items()))
+
+    def _validate_profile_dependencies(self) -> None:
+        """Fail before the weights load when the selected fast route is absent."""
+        import importlib.util
+
+        cfg = self._config.inference
+        if bool(cfg.get("fa4", True)):
+            try:
+                present = importlib.util.find_spec("flash_attn.cute") is not None
+            except (ImportError, ModuleNotFoundError):
+                present = False
+            if not present:
+                raise RuntimeError("FastH3's FA4 route needs the pinned flash-attn-4 package. Install it, "
+                                   "or set inference.fa4: false in your config.")
+        if str(cfg.get("vsa_kernel", "sm100a")) == "sm100a":
+            try:
+                from fastvideo_kernel import block_sparse_attn_sm100a
+            except ImportError:
+                present = False
+            else:
+                present = bool(getattr(block_sparse_attn_sm100a, "_HAS_VSA_SM100A", False))
+            if not present:
+                raise RuntimeError("FastH3's sm100a route needs fastvideo-kernel built with the Blackwell VSA "
+                                   "extension. Install a matching wheel, or set inference.vsa_kernel: triton.")
+
+    def _generator_config(self) -> Any:
+        """The engine shape, mirroring `basic_fasth3.py`."""
+        from fastvideo.api import (
+            CompileConfig,
+            ComponentConfig,
+            EngineConfig,
+            GeneratorConfig,
+            OffloadConfig,
+            ParallelismConfig,
+            PipelineSelection,
+        )
+
+        cfg = self._config.inference
+        runtime = self._config.runtime
+        num_gpus = int(runtime.get("num_gpus", 4))
+        # The checkpoint's own contract (fastvideo_inference.json) shards the
+        # transformer with FSDP. Sharding is what frees the VRAM to keep the
+        # text encoder resident, which is the deployment this model wants.
+        replicated_dit = bool(runtime.get("replicated_dit", False))
+        return GeneratorConfig(
+            model_path=str(self._model_path),
+            pipeline=PipelineSelection(
+                components=ComponentConfig(),
+                experimental={
+                    "attention_backend": "VIDEO_SPARSE_ATTN_H3",
+                    "VSA_sparsity": float(cfg.get("vsa_sparsity", 0.9)),
+                    "VSA_tile_size": int(cfg.get("vsa_tile_size", 64)),
+                    "inference_torch_compile": bool(cfg.get("inference_torch_compile", True)),
+                    "vae_parallel_decode": bool(cfg.get("vae_parallel_decode", True)),
+                    "vae_parallel_decode_strategy": "gather",
+                },
+            ),
+            engine=EngineConfig(
+                num_gpus=num_gpus,
+                use_fsdp_inference=num_gpus > 1 and not replicated_dit,
+                parallelism=ParallelismConfig(tp_size=1, sp_size=num_gpus),
+                offload=OffloadConfig(
+                    dit=False,
+                    dit_layerwise=False,
+                    text_encoder=bool(runtime.get("offload_text_encoder", False)),
+                    vae=bool(runtime.get("offload_vae", False)),
+                    pin_cpu_memory=bool(runtime.get("pin_cpu_memory", False)),
+                ),
+                compile=CompileConfig(
+                    enabled=False,
+                    mode=None,
+                    vae_enabled=bool(cfg.get("compile_vae", True)),
+                ),
+            ),
+        )
+
+    # ---------------------------------------------------------------- worker
+
+    def _worker_loop(self) -> None:
+        """Run submitted jobs, one at a time, forever.
+
+        The waiter is always released, even when the job died: a completion
+        event that never arrives is indistinguishable from a hang, and this
+        thread is the only one that will ever set it.
+        """
+        logger.info("generation worker ready")
+        while True:
+            job = self._jobs.get()
+            try:
+                if not job.cancelled:
+                    job.result = job.fn()
+            except BaseException as error:  # noqa: BLE001 — handed to the submitter
+                job.error = error
+                logger.exception("generation worker job raised")
+            finally:
+                job.done.set()
+
+    def submit(self, *, frames: int, prompt: str, seed: int, height: int, width: int) -> ClipJob:
+        """Queue one clip build and hand back its job handle.
+
+        Returns immediately; the caller polls ``job.done`` and reads
+        ``job.result`` — ``(frames_list, samples)``, RGB uint8 frames and an
+        int16 ``[1, samples]`` waveform at the wire rate — or ``job.error``.
+        """
+        job = ClipJob(lambda: self._generate_clip(frames=frames, prompt=prompt, seed=seed, height=height, width=width))
+        self._jobs.put(job)
+        return job
+
+    def _run_blocking(self, fn) -> None:
+        """Run work on the worker, block until it finishes, and re-raise its failure.
+
+        Used only by `load()`, where blocking is the point: a failed warm-up
+        has to stop startup rather than surface on a viewer's first clip.
+        """
+        job = ClipJob(fn)
+        self._jobs.put(job)
+        while not job.done.wait(timeout=_WORKER_POLL_SECONDS):
+            pass
+        if job.error is not None:
+            raise job.error
+
+    # --------------------------------------------------------------- warm-up
+
+    def _warmup(self) -> None:
+        """Build one throwaway clip per shape before reporting ready.
+
+        Every distinct frame count and canvas costs a one-time regional
+        compile, sparse-kernel autotune and allocator growth; paying it here
+        means the first real clip builds at warm speed.
+
+        Two axes, not their cross product: every configured canvas at the
+        default length, and every configured length at the primary canvas. A
+        non-primary canvas at a non-default length still stalls on first use.
+        """
+        aspects = self._config.warmup_aspects
+        cold = [a for a in clip_plan.ASPECT_CHOICES if a not in aspects]
+        if cold:
+            logger.info("aspects left cold, their first clip pays a compile stall: %s", cold)
+        shapes: list[tuple[str, int]] = [(aspect, self._config.clip_frames) for aspect in aspects]
+        shapes += [(aspects[0], frames) for frames in self._config.warmup_frames if frames != self._config.clip_frames]
+        logger.info("warming %d shape(s), lengths %s", len(shapes),
+                    [round(clip_plan.seconds_for_frames(f), 3) for f in self._config.warmup_frames])
+        for index, (aspect, frames) in enumerate(shapes, start=1):
+            height, width = clip_plan.canvas_for_choice(aspect)
+            started = time.monotonic()
+            self.generator.generate(
+                self._request(
+                    frames=frames,
+                    prompt=WARMUP_PROMPT,
+                    seed=self._config.seed,
+                    height=height,
+                    width=width,
+                    keep_output=False,
+                ))
+            logger.info("warmed %d/%d: %s %df at %dx%d in %.2fs", index, len(shapes), aspect, frames, height, width,
+                        time.monotonic() - started)
+
+    # ------------------------------------------------------------ generation
+
+    def _request(
+        self,
+        *,
+        frames: int,
+        prompt: str,
+        seed: int,
+        height: int,
+        width: int,
+        keep_output: bool,
+    ):
+        """Build one generation request, mirroring `basic_fasth3.py`.
+
+        `keep_output=False` is the warm-up shape: it skips the post-decode
+        path, so a warm-up costs generation time and nothing else.
+        """
+        from fastvideo.api import GenerationRequest, OutputConfig, SamplingConfig
+
+        return GenerationRequest(
+            # Padded to the fixed token length so one compiled shape serves
+            # every prompt; ClipInfo keeps echoing the original text.
+            prompt=self._pad_prompt(prompt),
+            # MiniMax-H3 is guidance-distilled, so there is no negative branch
+            # to steer and no CFG pass to pay for.
+            negative_prompt="",
+            sampling=SamplingConfig(
+                height=height,
+                width=width,
+                num_frames=frames,
+                fps=FRAME_RATE,
+                num_inference_steps=self._config.num_inference_steps,
+                guidance_scale=1.0,
+                batch_cfg=False,
+                seed=seed,
+            ),
+            output=OutputConfig(save_video=False, return_frames=keep_output),
+        )
+
+    def _generate_clip(self, *, frames: int, prompt: str, seed: int, height: int, width: int):
+        """Build one clip and convert it to what the pacer wants.
+
+        Returns ``(frames_list, samples)``: a list of RGB uint8 ``[h, w, 3]``
+        arrays and int16 ``[1, samples]`` at 48 kHz, trimmed to exactly
+        ``len(frames_list) / 24`` seconds so the two tracks stay in lockstep.
+        """
+        started = time.monotonic()
+        result = self.generator.generate(
+            self._request(
+                frames=frames,
+                prompt=prompt,
+                seed=seed,
+                height=height,
+                width=width,
+                keep_output=True,
+            ))
+        built = time.monotonic() - started
+
+        frames_list = result.frames
+        if not frames_list:
+            raise RuntimeError("the generator returned no frames")
+        samples = self._to_wire_audio(result.audio, result.audio_sample_rate, len(frames_list))
+        # The line to evaluate the deployment by: build seconds against content
+        # seconds (realtime_x > 1 means the clip built faster than it plays) on
+        # the GPU count that produced it, with the per-stage split. The numbers
+        # live in the message itself so every log formatter carries them.
+        content = len(frames_list) / FRAME_RATE
+        gpus = int(self._config.runtime.get("num_gpus", 4))
+        logger.info("clip built: %df (%.2fs content) in %.2fs = %.2fx realtime on %d gpus, stages=%s", len(frames_list),
+                    content, built, content / built, gpus, self._stage_times(result))
+        return frames_list, samples
+
+    @staticmethod
+    def _stage_times(result) -> dict:
+        """Per-stage seconds from the generator, for the clip log line.
+
+        This is where a regression shows up first: post-decode frame processing
+        scales with resolution x frames and competes with the build budget.
+        """
+        try:
+            stages = getattr(getattr(result, "logging_info", None), "stages", None)
+            if not stages:
+                return {}
+            return {
+                name: round(float(metrics["execution_time"]), 3)
+                for name, metrics in stages.items() if metrics.get("execution_time") is not None
+            }
+        except Exception:  # noqa: BLE001 — a log line must never fail a clip
+            logger.exception("could not read the generator stage timings")
+            return {}
+
+    def _to_wire_audio(self, audio, sample_rate, frames: int):
+        """Resample, downmix and quantize one clip's waveform for the wire.
+
+        Mono at the source is deliberate: the transport mean-downmixes before
+        the wire anyway, and the runtime recorder flattens two channels by
+        concatenation, so a stereo emit only corrupts recordings. Averaging here,
+        in float and before the int16 scale, is the same downmix one step
+        earlier.
+        """
+        import torch
+        import torchaudio.functional as AF
+
+        if audio is None:
+            raise RuntimeError("the generator returned no audio")
+        waveform = audio if torch.is_tensor(audio) else torch.as_tensor(audio)
+        waveform = waveform.detach().float().cpu()
+        # The decoder hands back [samples, channels]; the wire wants channel-major.
+        if waveform.ndim == 1:
+            waveform = waveform.unsqueeze(0)
+        elif waveform.shape[0] > waveform.shape[1]:
+            waveform = waveform.transpose(0, 1)
+        waveform = waveform.contiguous()
+
+        rate = int(sample_rate or NATIVE_SAMPLE_RATE)
+        if rate != OUTPUT_SAMPLE_RATE:
+            waveform = AF.resample(waveform, rate, OUTPUT_SAMPLE_RATE)
+        if waveform.shape[0] > 1:
+            waveform = waveform.mean(dim=0, keepdim=True)
+
+        want = round(frames / FRAME_RATE * OUTPUT_SAMPLE_RATE)
+        if waveform.shape[-1] > want:
+            waveform = waveform[:, :want]
+        elif waveform.shape[-1] < want:
+            pad = torch.zeros((waveform.shape[0], want - waveform.shape[-1]), dtype=waveform.dtype)
+            waveform = torch.cat([waveform, pad], dim=-1)
+        return (waveform.clamp(-1, 1) * 32767).to(torch.int16).numpy()
+
+
+__all__ = ["OUTPUT_SAMPLE_RATE", "ClipJob", "FastH3Backend"]
diff --git a/apps/infinite_livestream/infinite_livestream/chat.py b/apps/infinite_livestream/infinite_livestream/chat.py
new file mode 100644
index 000000000..79a5e0570
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/chat.py
@@ -0,0 +1,83 @@
+"""Viewer prompts, typed into the page that plays the stream.
+
+The page is the only way in, so this is fed directly in-process by `webapp.py`
+rather than polling a platform. `submit` is called from a request handler and
+never awaits: a full queue drops the message and tells the viewer, which is
+better than stalling the web server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+
+logger = logging.getLogger("infinite_livestream.chat")
+
+# Small on purpose: a deep queue would let a burst of typing commit the stream
+# to minutes of stale prompts.
+QUEUE_SIZE = 32
+
+
+@dataclass(frozen=True)
+class ChatPrompt:
+    """One accepted message, command word stripped."""
+
+    source: str
+    author: str
+    text: str
+    command: str = ""
+    received_at: float = field(default_factory=time.monotonic)
+
+
+def match_command(message: str, commands: Sequence[str]) -> tuple[str, str] | None:
+    """Match a message against command words: `(command, text)` or None.
+
+    Case-insensitive, and a bare command with no text is ignored.
+    """
+    stripped = message.strip()
+    lowered = stripped.lower()
+    for command in commands:
+        if not lowered.startswith(command.lower()):
+            continue
+        remainder = stripped[len(command):]
+        if remainder and not remainder[0].isspace():
+            continue  # "!promptfoo" is not "!prompt foo"
+        text = remainder.strip()
+        if text:
+            return command, text
+    return None
+
+
+class WebChat:
+    """Prompts submitted through the page's chat box."""
+
+    name = "web"
+
+    def __init__(self, command: str = "!prompt") -> None:
+        self._command = command
+        self._queue: asyncio.Queue[ChatPrompt] = asyncio.Queue(maxsize=QUEUE_SIZE)
+        self._dropped = 0
+
+    def submit(self, author: str, text: str, command: str | None = None) -> bool:
+        """Accept one message. True when it was queued, False when dropped."""
+        text = text.strip()
+        if not text:
+            return False
+        matched = match_command(text, (self._command, ))
+        word, body = matched if matched else (self._command, text)
+        prompt = ChatPrompt(source=self.name, author=author or "viewer", text=body, command=command or word)
+        try:
+            self._queue.put_nowait(prompt)
+        except asyncio.QueueFull:
+            self._dropped += 1
+            logger.warning("[chat] queue full, dropped prompt from %s (%d total)", prompt.author, self._dropped)
+            return False
+        return True
+
+    async def run(self, on_prompt: Callable[[ChatPrompt], None]) -> None:
+        logger.info("[chat] ready (queue %d)", QUEUE_SIZE)
+        while True:
+            on_prompt(await self._queue.get())
diff --git a/apps/infinite_livestream/infinite_livestream/clip_plan.py b/apps/infinite_livestream/infinite_livestream/clip_plan.py
new file mode 100644
index 000000000..989c517a8
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/clip_plan.py
@@ -0,0 +1,162 @@
+"""Clip geometry for the FastH3 channel.
+
+Pure arithmetic over the checkpoint's published constraints: how long a clip may
+be, how many frames that is, and what canvas an aspect ratio resolves to. No
+torch, no fastvideo, no GPU, so the config and queue tests import it anywhere.
+
+The constants below are duplicated from FastVideo rather than imported, because
+``fastvideo.pipelines.basic.minimax_h3.packing`` pulls in torch and, through
+fastvideo-kernel's triton autotuning, needs a live CUDA driver just to import.
+``tests/test_clip_plan.py`` asserts they still match upstream on a machine that
+has one, so the duplication cannot drift silently.
+
+Everything here is MiniMax-H3's geometry specifically. A second checkpoint --
+LTX-2 packs 8n+1 frames at its own resolutions -- needs its own module, not
+edits to this one; see the app README.
+"""
+
+from __future__ import annotations
+
+import math
+
+FPS = 24
+"""The only frame rate MiniMax-H3 accepts; the pipeline rejects anything else."""
+
+# The causal VAE consumes video in 17-frame chunks that decode to 5 latents, so
+# a valid pixel length is always `17n + 5`.
+_FRAMES_PER_CHUNK = 17
+_LATENTS_PER_CHUNK = 5
+
+# The checkpoint's trained duration window, in seconds. The cap applies to the
+# requested length; the aligned bucket it rounds to is what gets generated.
+_MIN_DURATION = 5.0
+_MAX_DURATION = 15.0
+
+# Canvas rules: the short edge is fixed, total area is capped, and both sides
+# must land on a multiple of 32.
+_SHORT_EDGE = 768
+_MAX_PIXELS = 768 * 1344
+_CANVAS_MULTIPLE = 32
+_MIN_ASPECT = 1 / 4
+_MAX_ASPECT = 4
+
+
+def align_frames(frames: int) -> int:
+    """Round up to the next valid `17n + 5` pixel length."""
+    if frames < 1:
+        raise ValueError(f"frames must be positive, got {frames}")
+    while frames % _FRAMES_PER_CHUNK != _LATENTS_PER_CHUNK:
+        frames += 1
+    return frames
+
+
+def _bounds() -> tuple[int, int]:
+    """The shortest and longest clip that satisfies both alignment and duration.
+
+    The ceiling is the subtle one: the cap applies to the aligned bucket, not to
+    the requested length, so 15.0 s (360 frames) pads *up* to 362 -- 15.083 s of
+    playout -- and that is the longest clip this checkpoint will generate.
+    """
+    return align_frames(int(_MIN_DURATION * FPS)), align_frames(int(_MAX_DURATION * FPS))
+
+
+MIN_FRAMES, MAX_FRAMES = _bounds()
+MIN_SECONDS = MIN_FRAMES / FPS
+MAX_SECONDS = MAX_FRAMES / FPS
+
+# The same bounds as the schema publishes them. Rounded *inward* to three
+# decimals so a client reads "5.167", not "5.166666666666667", and so every
+# value inside the published range still snaps to a generatable clip.
+MIN_SECONDS_PUBLISHED = math.ceil(MIN_SECONDS * 1000) / 1000
+MAX_SECONDS_PUBLISHED = math.floor(MAX_SECONDS * 1000) / 1000
+
+
+def legal_frame_counts() -> tuple[int, ...]:
+    """Every clip length this checkpoint can generate, in frames, ascending.
+
+    The `17n + 5` alignment makes consecutive legal lengths exactly one chunk
+    (17 frames) apart, so the whole space is a simple range.
+    """
+    return tuple(range(MIN_FRAMES, MAX_FRAMES + 1, _FRAMES_PER_CHUNK))
+
+
+def frames_for_seconds(seconds: float) -> int:
+    """Snap a requested clip length to the nearest length the model can make.
+
+    Rounds up to a valid frame count, then clamps into the generatable range, so
+    every accepted value round-trips through ``seconds_for_frames``.
+    """
+    if seconds <= 0:
+        raise ValueError(f"seconds must be positive, got {seconds}")
+    frames = align_frames(max(1, round(seconds * FPS)))
+    return max(MIN_FRAMES, min(MAX_FRAMES, frames))
+
+
+def seconds_for_frames(frames: int) -> float:
+    """Exact playout length of a clip, in seconds."""
+    return frames / FPS
+
+
+def canvas_for_aspect(aspect_width: float, aspect_height: float) -> tuple[int, int]:
+    """Resolve an aspect ratio to a `(height, width)` the checkpoint accepts.
+
+    Mirrors FastVideo's ``resolve_canvas_size``: pin the short edge to 768,
+    shrink to the area cap if the result is too wide, then round both sides to a
+    multiple of 32.
+    """
+    if aspect_width <= 0 or aspect_height <= 0:
+        raise ValueError(f"aspect must be positive, got {aspect_width}:{aspect_height}")
+    ratio = aspect_width / aspect_height
+    if not _MIN_ASPECT <= ratio <= _MAX_ASPECT:
+        raise ValueError(f"aspect ratios run from 1:4 to 4:1, got {aspect_width}:{aspect_height}")
+
+    if ratio >= 1:
+        width, height = _SHORT_EDGE * ratio, float(_SHORT_EDGE)
+    else:
+        width, height = float(_SHORT_EDGE), _SHORT_EDGE / ratio
+    area = width * height
+    if area > _MAX_PIXELS:
+        scale = (_MAX_PIXELS / area)**0.5
+        width, height = width * scale, height * scale
+    m = _CANVAS_MULTIPLE
+    return max(m, round(height / m) * m), max(m, round(width / m) * m)
+
+
+# The canvases `set_canvas` offers. Deliberately a short list: every entry is a
+# distinct tensor shape that load() must warm, and an unwarmed shape pays a
+# one-off compile stall on its first clip.
+ASPECT_CHOICES: tuple[str, ...] = ("16:9", "1:1", "9:16", "4:3")
+
+_ASPECT_RATIOS: dict[str, tuple[int, int]] = {
+    "16:9": (16, 9),
+    "1:1": (1, 1),
+    "9:16": (9, 16),
+    "4:3": (4, 3),
+}
+
+
+def canvas_for_choice(aspect: str) -> tuple[int, int]:
+    """Resolve one of ``ASPECT_CHOICES`` to `(height, width)`."""
+    try:
+        ratio = _ASPECT_RATIOS[aspect]
+    except KeyError:
+        raise ValueError(f"unknown aspect {aspect!r}; choose one of {list(ASPECT_CHOICES)}") from None
+    return canvas_for_aspect(*ratio)
+
+
+__all__ = [
+    "ASPECT_CHOICES",
+    "FPS",
+    "MAX_FRAMES",
+    "MAX_SECONDS",
+    "MAX_SECONDS_PUBLISHED",
+    "MIN_FRAMES",
+    "MIN_SECONDS",
+    "MIN_SECONDS_PUBLISHED",
+    "align_frames",
+    "canvas_for_aspect",
+    "canvas_for_choice",
+    "frames_for_seconds",
+    "legal_frame_counts",
+    "seconds_for_frames",
+]
diff --git a/apps/infinite_livestream/infinite_livestream/clip_queue.py b/apps/infinite_livestream/infinite_livestream/clip_queue.py
new file mode 100644
index 000000000..c1b24b496
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/clip_queue.py
@@ -0,0 +1,148 @@
+"""The clip queues: what the stream holds, in order, at each stage.
+
+A clip is enqueued (generation queue), built (playout queue), then consumed by
+playing. Both stages are the same bounded, ordered, position-addressable
+container; `engine.py` owns when an entry crosses between them.
+
+Pure bookkeeping, so it is testable without a GPU.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any
+
+from . import clip_plan
+
+
+@dataclass
+class ClipEntry:
+    """One clip, from request to built payload.
+
+    Everything but `video`/`audio` is frozen at enqueue time; those two arrive
+    when the build completes, and `ready` is derived from their presence.
+    """
+
+    clip_id: str
+    prompt: str
+    metadata: str
+    frames: int
+    seed: int
+    # Set while a build for this entry is in flight, so the scheduler never
+    # submits the same entry twice.
+    building: bool = False
+    # The built payload: decoded RGB frames and the wire-ready waveform.
+    video: list[Any] | None = None
+    audio: Any = None
+
+    @property
+    def ready(self) -> bool:
+        return self.video is not None
+
+    @property
+    def seconds(self) -> float:
+        return clip_plan.seconds_for_frames(self.frames)
+
+    def snapshot(self) -> dict[str, Any]:
+        """The clip as every message that references it carries it.
+
+        Whole rather than an id, so a listener never has to join against an
+        earlier message; a plain mapping, so it is JSON-serialisable for the
+        websocket.
+        """
+        return {
+            "clip_id": self.clip_id,
+            "prompt": self.prompt,
+            "metadata": self.metadata,
+            "frames": self.frames,
+            "seconds": round(self.seconds, 3),
+            "seed": self.seed,
+            "ready": self.ready,
+        }
+
+
+def new_entry(*, prompt: str, metadata: str, frames: int, seed: int) -> ClipEntry:
+    """Mint one entry with a fresh UUID."""
+    return ClipEntry(
+        clip_id=str(uuid.uuid4()),
+        prompt=prompt,
+        metadata=metadata,
+        frames=frames,
+        seed=seed,
+    )
+
+
+@dataclass
+class ClipQueue:
+    """A bounded, ordered, position-addressable queue of `ClipEntry`.
+
+    One container serves both stages. Positions are explicit and nothing
+    reorders on its own. For the playout queue every entry holds a fully
+    decoded clip in host memory, so `capacity` is also the memory budget.
+    """
+
+    capacity: int
+    _entries: list[ClipEntry] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.capacity < 1:
+            raise ValueError(f"queue capacity must be positive, got {self.capacity}")
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def __contains__(self, entry: ClipEntry) -> bool:
+        return any(existing is entry for existing in self._entries)
+
+    @property
+    def full(self) -> bool:
+        return len(self._entries) >= self.capacity
+
+    def add(self, entry: ClipEntry, position: int | None = None) -> int:
+        """Insert at `position` (None appends, otherwise clamped) and return the index."""
+        if self.full:
+            raise ValueError(f"the queue is full ({self.capacity} clips)")
+        index = (len(self._entries) if position is None else max(0, min(int(position), len(self._entries))))
+        self._entries.insert(index, entry)
+        return index
+
+    def move(self, entry: ClipEntry, position: int) -> int:
+        """Reposition `entry` and return the index it landed at, clamped."""
+        if entry not in self:
+            raise ValueError("the clip is not in this queue")
+        self._entries = [existing for existing in self._entries if existing is not entry]
+        index = max(0, min(int(position), len(self._entries)))
+        self._entries.insert(index, entry)
+        return index
+
+    def get(self, clip_id: str) -> ClipEntry | None:
+        for entry in self._entries:
+            if entry.clip_id == clip_id:
+                return entry
+        return None
+
+    def head(self) -> ClipEntry | None:
+        return self._entries[0] if self._entries else None
+
+    def next_to_build(self) -> ClipEntry | None:
+        """The front-most entry no build is already running for."""
+        for entry in self._entries:
+            if not entry.building:
+                return entry
+        return None
+
+    def remove(self, entry: ClipEntry) -> None:
+        self._entries = [existing for existing in self._entries if existing is not entry]
+
+    def clear(self) -> int:
+        """Drop every entry, built payloads included, and return how many."""
+        cleared = len(self._entries)
+        self._entries = []
+        return cleared
+
+    def snapshot(self) -> list[dict[str, Any]]:
+        return [entry.snapshot() for entry in self._entries]
+
+
+__all__ = ["ClipEntry", "ClipQueue", "new_entry"]
diff --git a/apps/infinite_livestream/infinite_livestream/config.py b/apps/infinite_livestream/infinite_livestream/config.py
new file mode 100644
index 000000000..aeb270b00
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/config.py
@@ -0,0 +1,328 @@
+"""Configuration: one YAML file, plus secrets from the environment.
+
+`configs/infinite_livestream.yaml` holds everything the app is configured with: what the
+checkpoint is asked for, how it is hosted, and how the deployment behaves.
+Point at a copy of it with `--config`.
+
+API keys stay in the environment, because a key in a version-controlled file is
+a key that leaks. `LIVESTREAM_WEIGHTS_PATH` is there too, being a property of
+the machine rather than of the deployment.
+
+`load_config` is the only reader of either; nothing else touches `os.environ`
+or parses YAML.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from . import clip_plan
+
+# ---------------------------------------------------------------- presets
+
+
+class PresetError(ValueError):
+    """A preset file is missing or malformed."""
+
+
+# Inside the package, so it survives installation: the app ships as part of
+# fastvideo, and anything beside the package rather than in it is not
+# packaged.
+DEFAULT_CONFIG = Path(__file__).parent / "configs" / "infinite_livestream.yaml"
+
+# Where the playlist goes when the config does not say. A relative default
+# would write into whatever directory the server was started from, which for a
+# source checkout is the repo root. Mirrors how `apps/dreamverse` picks its
+# state root.
+_STATE_ROOT = Path(os.environ.get("XDG_STATE_HOME") or Path.home() / ".local/state") / "fastvideo-livestream"
+DEFAULT_HLS_DIR = _STATE_ROOT / "hls"
+DEFAULT_FILLERS_DIR = Path(__file__).parent / "presets"
+PRESET_FILE = "fillers.json"
+
+
+def load_preset(directory: str | Path) -> dict:
+    """Load and validate the style and idle prompts the stream runs on.
+
+    `directory` holds `fillers.json`: the `style` every rewritten scene is
+    written in, and the `idle_prompts` that keep the stream fed when nobody is
+    typing. An empty prompt list disables the filler. Other keys are ignored,
+    so the file can carry its own notes.
+    """
+    path = Path(directory) / PRESET_FILE
+    if not path.is_file():
+        raise PresetError(f"no {PRESET_FILE} in {directory}")
+    try:
+        preset = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as error:
+        raise PresetError(f"{path} is not valid JSON: {error}") from None
+    style = preset.get("style")
+    prompts = preset.get("idle_prompts")
+    if not isinstance(style, str) or not style.strip():
+        raise PresetError(f"{path} needs a non-empty string `style`")
+    if not isinstance(prompts, list) or not all(isinstance(p, str) for p in prompts):
+        raise PresetError(f"{path} needs `idle_prompts` as a list of strings")
+    return {
+        "style": style.strip(),
+        "idle_prompts": [p.strip() for p in prompts if p.strip()],
+    }
+
+
+# ------------------------------------------------------------ model config
+
+# Component directories the T2VA pipeline loads. Missing weights must kill
+# startup, not surface as a loader traceback on the first clip.
+REQUIRED_COMPONENTS = (
+    "transformer",
+    "text_encoder",
+    "tokenizer",
+    "processor",
+    "vae",
+    "audio_vae",
+    "scheduler",
+    "audio_scheduler",
+)
+
+
+@dataclass(frozen=True)
+class ModelConfig:
+    """Everything the engine YAML configures, validated once at load.
+
+    The top-level fields are what the queues and the clip planner need;
+    ``inference`` and ``runtime`` are the raw blocks, which the backend reads
+    its engine knobs (attention kernels, compile flags, parallelism, offload
+    policy) straight out of.
+    """
+
+    aspect: str
+    clip_frames: int
+    seed: int
+    num_inference_steps: int
+    queue_size: int
+    generation_queue_size: int
+    warmup_aspects: tuple[str, ...]
+    warmup_frames: tuple[int, ...]
+    inference: dict[str, Any]
+    runtime: dict[str, Any]
+
+
+def load_model_config(config_path: Path | None = None) -> ModelConfig:
+    """Read the `inference` and `runtime` blocks into a validated `ModelConfig`.
+
+    The same file `Config.load` reads. Split out because the queues and the
+    backend need the checkpoint's shape, and nothing else in the file.
+
+    Raises:
+        ValueError: If the configured aspect is not one the checkpoint offers,
+            or a queue size is not positive.
+    """
+    path = config_path or DEFAULT_CONFIG
+    document: dict[str, Any] = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    inference: dict[str, Any] = document.get("inference") or {}
+    runtime: dict[str, Any] = document.get("runtime") or {}
+
+    aspect = str(inference.get("aspect", "16:9"))
+    if aspect not in clip_plan.ASPECT_CHOICES:
+        raise ValueError(f"inference.aspect must be one of {list(clip_plan.ASPECT_CHOICES)}, got {aspect!r}")
+
+    queue_size = int(inference.get("queue_size", 10))
+    if queue_size < 1:
+        raise ValueError(f"inference.queue_size must be positive, got {queue_size}")
+
+    generation_queue_size = int(inference.get("generation_queue_size", 20))
+    if generation_queue_size < 1:
+        raise ValueError(f"inference.generation_queue_size must be positive, got {generation_queue_size}")
+
+    clip_frames = clip_plan.frames_for_seconds(float(inference.get("clip_seconds", clip_plan.MAX_SECONDS)))
+
+    return ModelConfig(
+        aspect=aspect,
+        clip_frames=clip_frames,
+        seed=int(inference.get("seed", 1000)),
+        num_inference_steps=int(inference.get("num_inference_steps", 5)),
+        queue_size=queue_size,
+        generation_queue_size=generation_queue_size,
+        warmup_aspects=tuple(str(a) for a in (inference.get("warmup_aspects") or [aspect])),
+        warmup_frames=_parse_warmup_lengths(inference.get("warmup_lengths"), clip_frames),
+        inference=inference,
+        runtime=runtime,
+    )
+
+
+def _parse_warmup_lengths(raw: Any, clip_frames: int) -> tuple[int, ...]:
+    """Resolve ``inference.warmup_lengths`` to the frame counts load() warms.
+
+    ``"default"`` (or nothing) warms only the configured clip length;
+    ``"all"`` warms every length the checkpoint can generate; a list of
+    seconds warms those, snapped to legal lengths. The default length is
+    always included -- it is the shape every plain enqueue uses.
+    """
+    if raw in (None, "", "default"):
+        return (clip_frames, )
+    if raw == "all":
+        frames = set(clip_plan.legal_frame_counts())
+    elif isinstance(raw, list | tuple):
+        frames = {clip_plan.frames_for_seconds(float(seconds)) for seconds in raw}
+    else:
+        raise ValueError(f'inference.warmup_lengths must be "default", "all", or a list of seconds, got {raw!r}')
+    frames.add(clip_frames)
+    return tuple(sorted(frames))
+
+
+def resolve_model_path(config: ModelConfig, weights_root: Path) -> Path:
+    """The checkpoint directory under the weights path; "." means the path itself."""
+    subdir = str(config.runtime.get("checkpoint_dir", "."))
+    if subdir in ("", "."):
+        return weights_root
+    return weights_root / subdir
+
+
+def require_weights(root: Path, model_path: Path) -> None:
+    """Fail startup loudly when the weights are incomplete."""
+    problems: list[str] = []
+    if not model_path.is_dir():
+        problems.append(f"checkpoint directory is missing: {model_path}")
+    else:
+        index = model_path / "modular_model_index.json"
+        if not index.is_file():
+            problems.append(f"modular_model_index.json is missing: {index}")
+        for component in REQUIRED_COMPONENTS:
+            if not (model_path / component).is_dir():
+                problems.append(f"component directory is missing: {model_path / component}")
+    if problems:
+        raise FileNotFoundError(f"FastH3 weights under {root} are incomplete:\n  " + "\n  ".join(problems))
+
+
+# -------------------------------------------------------------- app config
+
+
+@dataclass(frozen=True)
+class Config:
+    """One immutable snapshot of everything the app is configured with."""
+
+    # The engine: where the weights live and which YAML shapes it
+    weights_path: Path
+    config_path: Path
+
+    # Upsampling
+    openai_api_key: str
+    openai_base_url: str | None
+    openai_model: str
+    max_chunks: int
+    # Filler always wears the preset's style; a viewer's own request may pick
+    # whatever look suits it. Set 0 to put every clip in the house style.
+    viewer_free_style: bool
+
+    # The style every scene is written in, and the idle prompts
+    style: str
+    idle_prompts: tuple[str, ...]
+
+    # Moderation (its own endpoint: the upsampling gateway may not expose
+    # /moderations, so this can point at api.openai.com while upsampling
+    # goes elsewhere)
+    moderation_enabled: bool
+    moderation_api_key: str
+    moderation_base_url: str | None
+    moderation_model: str
+
+    # Idle filler
+    idle_queue_target: int
+
+    # Output: the HLS playlist the page plays, written by `sink.py`.
+    hls_dir: str
+    video_bitrate_k: int
+    hls_retention_s: int
+
+    # The watch page: video, chat and the queue on one HTTP origin, so a
+    # single tunnel publishes the whole thing.
+    web_host: str
+    web_port: int
+
+    # Chat
+    chat_command: str
+    chat_cooldown_s: float
+
+    @staticmethod
+    def load(argv: list[str] | None = None) -> Config:
+        """Read the config file and the environment, and validate the result."""
+        parser = argparse.ArgumentParser(description="Chat-driven FastH3 livestream (see README.md).")
+        parser.add_argument("--config", default=None, help=f"config YAML (default {DEFAULT_CONFIG})")
+        parser.add_argument("--weights", default=None, help="override LIVESTREAM_WEIGHTS_PATH")
+        parser.add_argument("--port", default=None, type=int, help="override web.port")
+        args = parser.parse_args(argv)
+
+        path = Path(args.config).expanduser() if args.config else DEFAULT_CONFIG
+        if not path.is_file():
+            raise SystemExit(f"config not found: {path}")
+        document: dict[str, Any] = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+        upsampler = document.get("upsampler") or {}
+        moderation = document.get("moderation") or {}
+        director = document.get("director") or {}
+        output = document.get("output") or {}
+        web = document.get("web") or {}
+
+        weights = args.weights or os.environ.get("LIVESTREAM_WEIGHTS_PATH", "")
+        openai_key = os.environ.get("OPENAI_API_KEY", "")
+        fillers = director.get("fillers")
+        try:
+            preset = load_preset(Path(fillers).expanduser() if fillers else DEFAULT_FILLERS_DIR)
+        except PresetError as error:
+            raise SystemExit(str(error)) from None
+
+        config = Config(
+            weights_path=Path(weights).expanduser() if weights else Path(),
+            config_path=path,
+            openai_api_key=openai_key,
+            openai_base_url=upsampler.get("base_url") or None,
+            openai_model=str(upsampler.get("model", "gpt-4o-mini")),
+            max_chunks=max(1, int(upsampler.get("max_chunks", 6))),
+            viewer_free_style=bool(upsampler.get("viewer_free_style", True)),
+            style=preset["style"],
+            idle_prompts=tuple(preset["idle_prompts"]),
+            moderation_enabled=bool(moderation.get("enabled", True)),
+            # Falls back to the upsampling credentials, which is right when one
+            # endpoint serves both.
+            moderation_api_key=os.environ.get("MODERATION_API_KEY") or openai_key,
+            moderation_base_url=moderation.get("base_url") or upsampler.get("base_url") or None,
+            moderation_model=str(moderation.get("model", "omni-moderation-latest")),
+            idle_queue_target=int(director.get("idle_queue_target", 6)),
+            hls_dir=str(output.get("hls_dir") or DEFAULT_HLS_DIR),
+            video_bitrate_k=int(output.get("video_bitrate_k", 4500)),
+            hls_retention_s=int(output.get("hls_retention_s", 120)),
+            web_host=str(web.get("host", "0.0.0.0")),
+            web_port=args.port or int(web.get("port", 8081)),
+            chat_command=str(director.get("chat_command", "!prompt")).strip(),
+            chat_cooldown_s=float(director.get("chat_cooldown_s", 10)),
+        )
+        config.validate()
+        return config
+
+    def validate(self) -> None:
+        """Fail fast on contradictions instead of half-starting."""
+        if not str(self.weights_path) or self.weights_path == Path():
+            raise SystemExit("Set LIVESTREAM_WEIGHTS_PATH, or pass --weights, pointing at the FastH3 weights.")
+        if not self.openai_api_key:
+            raise SystemExit(
+                "Set OPENAI_API_KEY. Prompt rewriting runs for the idle filler too, so the stream does not start without it."
+            )
+        if self.hls_retention_s < 6:
+            raise SystemExit("output.hls_retention_s must be at least 6 seconds.")
+        if not self.chat_command.startswith("!"):
+            raise SystemExit("director.chat_command should start with '!' (e.g. !prompt).")
+
+
+__all__ = [
+    "Config",
+    "ModelConfig",
+    "PresetError",
+    "load_model_config",
+    "load_preset",
+    "require_weights",
+    "resolve_model_path",
+]
diff --git a/apps/infinite_livestream/infinite_livestream/configs/infinite_livestream.yaml b/apps/infinite_livestream/infinite_livestream/configs/infinite_livestream.yaml
new file mode 100644
index 000000000..7bbbf308a
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/configs/infinite_livestream.yaml
@@ -0,0 +1,93 @@
+# Everything Infinite Livestream is configured with, apart from secrets.
+#
+# API keys stay in the environment, because a key in a version-controlled file
+# is a key that leaks:
+#
+#   export OPENAI_API_KEY=...
+#   export LIVESTREAM_WEIGHTS_PATH=/path/to/fasth3
+#
+# Point the app at a copy of this file with `infinite-livestream-server --config`.
+
+inference:
+  # The canvas every clip is generated at. 16:9 resolves to 1344x768.
+  aspect: "16:9"
+  # The longest clip this checkpoint can make (362 frames at 24 fps). One
+  # length everywhere means one compiled shape.
+  clip_seconds: 15.083
+  # Built clips held in host memory awaiting playout; each holds a full
+  # decoded clip, so this is also the memory budget.
+  queue_size: 10
+  # Requests accepted but not yet built.
+  generation_queue_size: 20
+  seed: 1000
+  # Sigma-grid POINTS, not transformer forwards: the distilled schedule is
+  # five points and exactly four forwards.
+  num_inference_steps: 5
+
+  vsa_sparsity: 0.9
+  vsa_tile_size: 64
+  # sm100a is the Blackwell VSA kernel; `triton` is the ~2.5x slower fallback.
+  vsa_kernel: sm100a
+  fa4: true
+  h3_fusions: true
+  inference_torch_compile: true
+  compile_vae: true
+  ulysses_a2a: "off"
+
+  # Shapes warmed before the stream reports ready. "default" warms only
+  # clip_seconds; "all" warms every legal length (slower start, no stall on a
+  # viewer's first odd-length clip).
+  warmup_aspects: ["16:9"]
+  warmup_lengths: "default"
+
+runtime:
+  # Relative to the weights root (LIVESTREAM_WEIGHTS_PATH); "." means the
+  # snapshot's components sit directly under it.
+  checkpoint_dir: "."
+  num_gpus: 4
+  # Replicate the transformer on each GPU rather than FSDP-sharding it: at
+  # four GB200s the weights fit, and replication skips the all-gather.
+  replicated_dit: true
+  offload_text_encoder: false
+  offload_vae: false
+  pin_cpu_memory: false
+
+# How a viewer's prompt becomes scenes. Any OpenAI-compatible endpoint works.
+upsampler:
+  model: gpt-4o-mini
+  # base_url: https://api.groq.com/openai/v1
+  # Most clips one prompt may expand into.
+  max_chunks: 6
+  # Filler always wears the house style; a viewer's own request may pick
+  # whatever look suits it. false puts every clip in the house style.
+  viewer_free_style: true
+
+# Checked before rewriting. Errors fail closed, so a broken endpoint stops
+# prompts rather than letting them through unchecked. Its own endpoint on
+# purpose: inference gateways rarely expose /moderations.
+moderation:
+  enabled: true
+  model: omni-moderation-latest
+  # base_url: https://api.openai.com/v1
+
+director:
+  # Clips the idle filler keeps queued when nobody is typing. 0 turns it off.
+  idle_queue_target: 6
+  # Seconds between accepted prompts, per viewer.
+  chat_cooldown_s: 10
+  chat_command: "!prompt"
+  # Directory holding fillers.json. Unset uses the one that ships.
+  # fillers: /path/to/my-fillers
+
+output:
+  # Unset writes under $XDG_STATE_HOME/fastvideo-livestream/hls, so a source
+  # checkout does not collect segments. Set an absolute path to place it.
+  # hls_dir: /var/lib/livestream/hls
+  # x264 target in kbit/s.
+  video_bitrate_k: 4500
+  # Retained playback history; does not increase target live latency.
+  hls_retention_s: 120
+
+web:
+  host: 0.0.0.0
+  port: 8081
diff --git a/apps/infinite_livestream/infinite_livestream/director.py b/apps/infinite_livestream/infinite_livestream/director.py
new file mode 100644
index 000000000..9b2babdba
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/director.py
@@ -0,0 +1,408 @@
+"""The director: viewer prompts in, tagged scene groups on the engine's queue.
+
+One chat prompt becomes one *scene group*: the upsampler expands it into 1..N
+self-contained scenes -- a single shot, or a chunked short story -- which the
+director enqueues contiguously. It is also the playout brain: `run_playout`
+curates the front of the playout queue with `move` so the engine's next
+autoplay is already the right clip.
+
+Rules that keep it coherent:
+
+  * It is the queue's only writer. The viewer worker (`run`) and the idle
+    filler (`run_idle`) serialise their enqueues through one lock, so groups
+    can never interleave.
+  * A group is enqueued only when the whole group fits, so it cannot get
+    stuck half-in. Capacities come from the engine's `state_update`, never
+    from constants here.
+  * Viewer prompts outrank filler and stay first-come-first-served among
+    themselves: viewer groups insert ahead of waiting filler and behind
+    waiting viewer clips, the playout loop pops one built filler when a full
+    playout queue blocks a viewer's build, and the idle filler stands down
+    whenever viewer work is pending.
+
+Every scene carries its group's identity in the clip metadata, which the
+engine echoes back on every message referencing that clip. That is what lets
+"scene 2/3 of Neon Alley by viewer_42" be reconstructed from a `clip_started`
+alone, and what marks filler as evictable later.
+
+Viewer prompts pass moderation before the upsampler; the curated idle list
+does not need it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import random
+import time
+from collections.abc import Callable, Sequence
+
+from .chat import ChatPrompt
+from .group_tag import is_generated, parse_group_tag, pick_next, viewer_insert_position
+from .engine import Engine
+from .moderator import Moderator
+from .upsampler import PromptUpsampler, SceneGroup
+
+logger = logging.getLogger(__name__)
+
+# Prompts waiting for upsampling+enqueue before new ones are turned away.
+# Depth here is viewer wait time, and a backlog on top of a full generation
+# queue serves nobody.
+_PENDING_LIMIT = 24
+
+# Enqueue retry cadence while the model refuses (reconnect mid-command, ...).
+_RETRY_DELAY_S = 3.0
+
+# How often the idle filler re-checks whether the queue wants topping up.
+_IDLE_POLL_S = 3.0
+
+# How often the playout loop re-checks. The broadcasts keep the mirrors
+# fresh; polling them is what survives a missed message.
+_PLAYOUT_POLL_S = 0.5
+
+
+class Director:
+    """Consume chat prompts; keep the fast-h3 queue fed with scene groups."""
+
+    def __init__(
+        self,
+        link: Engine,
+        upsampler: PromptUpsampler,
+        moderator: Moderator,
+        cooldown_s: float,
+        idle_prompts: Sequence[str] = (),
+        idle_queue_target: int = 0,
+        on_reject: Callable[[str, str], None] | None = None,
+    ) -> None:
+        self._link = link
+        self._on_reject = on_reject
+        self._upsampler = upsampler
+        self._moderator = moderator
+        self._cooldown_s = cooldown_s
+        self._idle_prompts = list(idle_prompts)
+        random.shuffle(self._idle_prompts)
+        self._idle_index = 0
+        self._idle_target = idle_queue_target
+        self._pending: asyncio.Queue[ChatPrompt] = asyncio.Queue(_PENDING_LIMIT)
+        self._last_accepted: dict[str, float] = {}  # author -> monotonic
+        self._enqueue_lock = asyncio.Lock()
+        link.add_listener(self._on_model_message)
+
+    # -------------------------------------------------------- chat intake
+
+    def cooldown_remaining(self, author: str) -> float:
+        """Seconds until *author* may send again; 0 when they may send now.
+
+        Asked by the web app before it accepts a POST, so a rate-limited
+        viewer is stopped in their own browser rather than told afterwards in
+        a chat feed everyone else can read.
+        """
+        last = self._last_accepted.get(author)
+        if last is None:
+            return 0.0
+        return max(0.0, self._cooldown_s - (time.monotonic() - last))
+
+    def _reject(self, prompt: ChatPrompt, reason: str) -> None:
+        """Drop one prompt, and make sure the viewer hears about it.
+
+        Every rejection below used to be log-only, while the web app had
+        already answered the POST with `ok` and echoed the prompt into chat --
+        so a viewer watched their request appear and then quietly die. The
+        component that can say no is downstream of the acknowledgement, which
+        is why it has to report back rather than return a status.
+        """
+        logger.info("[director] dropped from %s@%s (%s): %s", prompt.author, prompt.source, reason, prompt.text)
+        if self._on_reject is None:
+            return
+        try:
+            self._on_reject(prompt.author, reason)
+        except Exception:  # noqa: BLE001 -- telling the viewer must not kill the loop
+            logger.exception("[director] reject callback failed")
+
+    def submit(self, prompt: ChatPrompt) -> None:
+        """Accept one chat prompt (called synchronously by chat sources)."""
+        now = time.monotonic()
+        last = self._last_accepted.get(prompt.author)
+        if last is not None and now - last < self._cooldown_s:
+            self._reject(prompt, f"one prompt every {self._cooldown_s:.0f}s; "
+                         f"{self._cooldown_s - (now - last):.0f}s left")
+            return
+        try:
+            self._pending.put_nowait(prompt)
+        except asyncio.QueueFull:
+            self._reject(prompt, f"the backlog is full ({_PENDING_LIMIT} waiting)")
+            return
+        self._last_accepted[prompt.author] = now
+        logger.info(
+            "[director] accepted from %s@%s: %s",
+            prompt.author,
+            prompt.source,
+            prompt.text,
+        )
+
+    # ------------------------------------------------- viewer prompt loop
+
+    def _viewer_clips_queued(self) -> int:
+        """Viewer clips across both queues (anything not tagged filler)."""
+        return sum(1 for clip in self._link.generation_clips + self._link.playout_clips if not is_generated(clip))
+
+    async def run(self) -> None:
+        """Moderate, upsample, and enqueue pending prompts, one group at a time."""
+        while True:
+            prompt = await self._pending.get()
+            try:
+                # Dropped now, before it costs a moderation and an LLM call.
+                # Capacity comes from the engine, never from a constant.
+                if self._viewer_clips_queued() >= self._link.playout_capacity:
+                    self._reject(
+                        prompt, f"{self._viewer_clips_queued()} viewer clips already queued "
+                        f"(budget {self._link.playout_capacity})")
+                    continue
+                verdict = await self._moderator.review(prompt.text)
+                if verdict is not None:
+                    self._reject(prompt, verdict)
+                    continue
+                group = await self._upsampler.upsample(
+                    raw_prompt=prompt.text,
+                    author=prompt.author,
+                    source=prompt.source,
+                    min_seconds=self._link.min_seconds,
+                    max_seconds=self._link.max_seconds,
+                )
+                await self._enqueue_group(group)
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                logger.error(
+                    "[director] failed to process prompt from %s: %s",
+                    prompt.author,
+                    error,
+                )
+
+    # -------------------------------------------------------- idle filler
+
+    async def run_idle(self) -> None:
+        """Keep the queue topped up with generated clips while chat is quiet.
+
+        One clip per group, on purpose: single-scene fillers are the finest
+        eviction granularity, and popping one never truncates a story.
+        """
+        if self._idle_target <= 0:
+            logger.info("[director] idle filler disabled (target 0)")
+            return
+        logger.info(
+            "[director] idle filler: %d prompts, queue target %d",
+            len(self._idle_prompts),
+            self._idle_target,
+        )
+        while True:
+            await asyncio.sleep(_IDLE_POLL_S)
+            # May be empty after a switch to a preset with no idle prompts;
+            # keep polling so a later switch revives it without a restart.
+            if not self._idle_prompts:
+                continue
+            # The configured target self-clamps under the deployment's live
+            # playout capacity: filler must never be what fills the playout
+            # queue to the brim, because a full playout queue pauses builds
+            # (leave at least one slot's headroom for a viewer clip to land).
+            target = min(self._idle_target, max(1, self._link.playout_capacity - 1))
+            if (not self._pending.empty() or not self._link.connected
+                    or self._link.generation_queued + self._link.playout_queued >= target):
+                continue
+            text = self._idle_prompts[self._idle_index % len(self._idle_prompts)]
+            self._idle_index += 1
+            try:
+                group = await self._upsampler.upsample(
+                    raw_prompt=text,
+                    author="auto",
+                    source="idle",
+                    min_seconds=self._link.min_seconds,
+                    max_seconds=self._link.max_seconds,
+                    generated=True,
+                    max_chunks=1,
+                )
+                # A viewer prompt that arrived while the LLM ran outranks the
+                # filler; drop this group rather than making the viewer wait.
+                if self._pending.empty():
+                    await self._enqueue_group(group)
+            except asyncio.CancelledError:
+                raise
+            except Exception as error:
+                logger.error("[director] idle fill failed: %s", error)
+
+    # ------------------------------------------------------------- playout
+
+    async def run_playout(self) -> None:
+        """Curate the playout queue's front so autoplay always starts right.
+
+        The engine chains the playout front the instant the stream idles, so
+        nothing here sends an explicit play; it keeps the front correct
+        instead. Reordering happens while a clip plays, ahead of the moment it
+        matters.
+        """
+        while True:
+            await asyncio.sleep(_PLAYOUT_POLL_S)
+            if not self._link.connected:
+                continue
+            await self._relieve_build_backpressure()
+            clips = self._link.playout_clips
+            desired = pick_next(clips)
+            if desired is None or clips[0]["clip_id"] == desired["clip_id"]:
+                continue
+            await self._link.send_command("move", {"clip_id": desired["clip_id"], "position": 0})
+            # Let the resulting queue_update land before re-evaluating.
+            await asyncio.sleep(_PLAYOUT_POLL_S)
+
+    async def _relieve_build_backpressure(self) -> None:
+        """Pop one playout filler when built fillers block a viewer's build.
+
+        Generation pauses while the playout queue is full. When what fills it
+        is idle filler and a viewer clip waits to build, the newest filler is
+        the right thing to lose — one per tick, so a draining queue gets
+        every chance to make room by playing instead.
+        """
+        if self._link.playout_queued < self._link.playout_capacity:
+            return
+        viewer_waiting = any(not is_generated(clip) for clip in self._link.generation_clips)
+        if not viewer_waiting:
+            return
+        for clip in reversed(self._link.playout_clips):
+            if is_generated(clip):
+                reply = await self._link.send_command("pop", {"clip_id": clip["clip_id"]})
+                if isinstance(reply, dict) and "clip" in reply:
+                    logger.info(
+                        "[director] popped playout filler %s to unblock a "
+                        "viewer build",
+                        clip["clip_id"][:8],
+                    )
+                return
+
+    # ---------------------------------------------------------- enqueueing
+
+    async def _enqueue_group(self, group: SceneGroup) -> None:
+        """Put one group on the model's generation queue, or drop it and say why.
+
+        Viewer groups enter *ahead of waiting filler and behind waiting
+        viewer clips* (`viewer_insert_position`), so viewer requests stay
+        first-come-first-served and idle filler just slides back — no
+        popping, no waste. Filler groups append. When the generation queue
+        cannot fit the group even after dropping the filler waiting in it,
+        the group is dropped with the queues intact — a backlog full of
+        viewer content takes no more, rather than stalling every later
+        prompt behind a wait.
+        """
+        scene_count = len(group.scenes)
+        async with self._enqueue_lock:
+            free = self._link.generation_capacity - self._link.generation_queued
+            if free < scene_count and not group.generated:
+                evictable = sum(1 for clip in self._link.generation_clips if is_generated(clip))
+                if free + evictable >= scene_count:
+                    await self._evict_generation_fillers(scene_count - free)
+                    await asyncio.sleep(0.3)  # let the pops' queue_update land
+                    free = (self._link.generation_capacity - self._link.generation_queued)
+            if free < scene_count:
+                logger.warning(
+                    "[director] no room in the generation queue for %s "
+                    "(%d scenes, %d free); dropping the group",
+                    group.group_id,
+                    scene_count,
+                    free,
+                )
+                return
+
+            position = (None if group.generated else viewer_insert_position(self._link.generation_clips))
+            for index, scene in enumerate(group.scenes, start=1):
+                metadata = json.dumps(
+                    {
+                        "group_id": group.group_id,
+                        "title": group.title[:120],
+                        "scene": index,
+                        "scenes": scene_count,
+                        "author": group.author,
+                        "source": group.source,
+                        "generated": group.generated,
+                        # Truncated so the blob stays small in the app's own
+                        # clip records; no FastVideo schema caps it.
+                        "raw_prompt": group.raw_prompt[:400],
+                    },
+                    ensure_ascii=False,
+                )
+                payload = {
+                    "prompt": scene.prompt,
+                    "metadata": metadata,
+                    "seconds": scene.seconds,
+                }
+                if position is not None:
+                    # Consecutive positions keep the group contiguous and in
+                    # scene order, ahead of the filler it displaced.
+                    payload["position"] = position + index - 1
+                while True:
+                    reply = await self._link.send_command("enqueue", payload)
+                    if isinstance(reply, dict) and "clip" in reply:
+                        clip = reply["clip"]
+                        logger.info(
+                            "[director] queued %s scene %d/%d as %s (%.1fs, seed %s)%s",
+                            group.group_id,
+                            index,
+                            scene_count,
+                            clip["clip_id"][:8],
+                            clip["seconds"],
+                            clip["seed"],
+                            " [auto]" if group.generated else "",
+                        )
+                        break
+                    # A bodyless reply means refused; the engine already
+                    # logged why. Wait and retry.
+                    logger.warning(
+                        "[director] enqueue of %s scene %d/%d refused; retrying in %.0fs",
+                        group.group_id,
+                        index,
+                        scene_count,
+                        _RETRY_DELAY_S,
+                    )
+                    await asyncio.sleep(_RETRY_DELAY_S)
+
+    async def _evict_generation_fillers(self, needed: int) -> int:
+        """Pop up to `needed` filler clips from the generation queue.
+
+        Capacity relief only — order needs no eviction now that viewer
+        groups insert ahead of filler positionally. Newest-queued first, and
+        only clips tagged `generated: true`. Returns how many pops succeeded.
+        """
+        popped = 0
+        for clip in reversed(self._link.generation_clips):
+            if popped >= needed:
+                break
+            if not is_generated(clip):
+                continue
+            reply = await self._link.send_command("pop", {"clip_id": clip["clip_id"]})
+            if isinstance(reply, dict) and "clip" in reply:
+                popped += 1
+                logger.info(
+                    "[director] evicted waiting filler %s for a viewer group",
+                    clip["clip_id"][:8],
+                )
+        return popped
+
+    # ----------------------------------------------------- announcements
+
+    def _on_model_message(self, kind: str, data: dict) -> None:
+        """Narrate group playback from clip messages alone (via metadata)."""
+        clip = data.get("clip") if isinstance(data, dict) else None
+        if not isinstance(clip, dict):
+            return
+        tag = parse_group_tag(clip.get("metadata", ""))
+        label = (f"'{tag['title']}' scene {tag['scene']}/{tag['scenes']} "
+                 f"(by {tag['author']}@{tag['source']})" +
+                 (" [auto]" if tag.get("generated") else "") if tag else f"clip {clip.get('clip_id', '?')[:8]}")
+        if kind == "clip_started":
+            logger.info("[now playing] %s", label)
+        elif kind == "clip_finished":
+            logger.info("[finished] %s", label)
+        elif kind == "clip_failed":
+            logger.error(
+                "[director] build failed for %s: %s — the queue moves on",
+                label,
+                data.get("reason"),
+            )
diff --git a/apps/infinite_livestream/infinite_livestream/engine.py b/apps/infinite_livestream/infinite_livestream/engine.py
new file mode 100644
index 000000000..b7a40dcb5
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/engine.py
@@ -0,0 +1,475 @@
+"""The engine: generation, playout, and the state every other module reads.
+
+    director ──enqueue/pop/move──▶  Engine  ──frames+audio──▶  Pacer ──▶ sink
+                                      │
+                                      └──state_update / queue_update / clip_*
+                                         ──▶ listeners (webapp, director)
+
+The generator and the broadcast share a process, so a built clip is handed to
+the pacer as the arrays it already is. There is no encode, no transport and
+therefore nothing that can shed video frames while audio flows on -- which is
+how a picture drifts behind its own soundtrack.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from . import clip_plan
+from .backend import ClipJob, FastH3Backend
+from .clip_queue import ClipEntry, ClipQueue, new_entry
+from .config import Config, ModelConfig, require_weights, resolve_model_path
+from .metadata import clip_view, encode_id3
+from .pacer import Pacer
+
+logger = logging.getLogger(__name__)
+
+# Fixed by the checkpoint and the backend's resample; the canvas is not.
+MODEL_FPS = clip_plan.FPS
+MODEL_SAMPLE_RATE = 48_000
+
+POLL_SECONDS = 0.05
+
+# Frames handed to the pacer per step. Small keeps its buffers near-empty,
+# which is the condition its A/V pairing depends on.
+EMIT_FRAMES = 4
+
+
+class Engine:
+    """Own the model, the queues and the playout."""
+
+    def __init__(self, config: Config, model_config: ModelConfig) -> None:
+        self._config = config
+        self._model = model_config
+        self._pacer: Pacer | None = None
+        self._listeners: list[Callable[[str, dict], None]] = []
+
+        model_path = resolve_model_path(model_config, config.weights_path)
+        require_weights(config.weights_path, model_path)
+        self.backend = FastH3Backend(model_config, model_path)
+
+        self._generation = ClipQueue(capacity=model_config.generation_queue_size)
+        self._playout = ClipQueue(capacity=model_config.queue_size)
+        # The build in flight: its entry, its job handle, and when it was
+        # submitted (monotonic), so readiness latency is a measured number.
+        self._build: tuple[ClipEntry, ClipJob, float] | None = None
+        self._playing: ClipEntry | None = None
+
+        self._seed = model_config.seed
+        self._clips_played = 0
+        self._frames_sent = 0
+        self._seconds_sent = 0.0
+
+        self._ready = asyncio.Event()
+        # Mirrors of what listeners were last told, so a late subscriber (the
+        # web app builds its own mirror from these) reads the same values.
+        self.state: dict[str, Any] = self._snapshot()
+        self.generation_clips: list[dict] = []
+        self.playout_clips: list[dict] = []
+
+    # ---------------------------------------------------------------- wiring
+
+    def attach_pacer(self, pacer: Pacer) -> None:
+        """Point the media path at the pacer."""
+        self._pacer = pacer
+
+    def add_listener(self, listener: Callable[[str, dict], None]) -> None:
+        """Register for every message as `(kind, data)`. Must not raise."""
+        self._listeners.append(listener)
+
+    # ----------------------------------------------------------- state mirror
+
+    @property
+    def min_seconds(self) -> float:
+        return clip_plan.MIN_SECONDS_PUBLISHED
+
+    @property
+    def max_seconds(self) -> float:
+        return clip_plan.MAX_SECONDS_PUBLISHED
+
+    @property
+    def generation_queued(self) -> int:
+        return len(self._generation)
+
+    @property
+    def generation_capacity(self) -> int:
+        return self._generation.capacity
+
+    @property
+    def playout_queued(self) -> int:
+        return len(self._playout)
+
+    @property
+    def playout_capacity(self) -> int:
+        return self._playout.capacity
+
+    @property
+    def canvas(self) -> tuple[int, int]:
+        """(width, height) this deployment generates at."""
+        height, width = clip_plan.canvas_for_choice(self._model.aspect)
+        return width, height
+
+    @property
+    def connected(self) -> bool:
+        """Whether the model is loaded and commands would take effect."""
+        return self._ready.is_set()
+
+    def _canvas_hw(self) -> tuple[int, int]:
+        return clip_plan.canvas_for_choice(self._model.aspect)
+
+    def _snapshot(self) -> dict[str, Any]:
+        """Everything an observer can see, in one mapping.
+
+        The single source, so a joining viewer's greeting and everyone else's
+        broadcast can never disagree.
+        """
+        height, width = self._canvas_hw()
+        return {
+            "width": width,
+            "height": height,
+            "playing": self._playing is not None,
+            "generation_queued": len(self._generation),
+            "generation_capacity": self._generation.capacity,
+            "playout_queued": len(self._playout),
+            "playout_capacity": self._playout.capacity,
+            "clips_played": self._clips_played,
+        }
+
+    # -------------------------------------------------------------- messaging
+
+    def _emit(self, kind: str, data: dict) -> None:
+        """Fan one message out to every listener.
+
+        Synchronous and non-throwing: these are in-process callbacks, and a
+        broken listener must not take generation down with it.
+        """
+        for listener in self._listeners:
+            try:
+                listener(kind, data)
+            except Exception:  # noqa: BLE001 -- a listener cannot break the engine
+                logger.exception("[engine] listener failed on %s", kind)
+
+    def _send_state(self) -> None:
+        self.state = self._snapshot()
+        self._emit("state_update", self.state)
+
+    def _send_queue(self) -> None:
+        self.generation_clips = self._generation.snapshot()
+        self.playout_clips = self._playout.snapshot()
+        self._emit(
+            "queue_update",
+            {
+                "generation": self.generation_clips,
+                "playout": self.playout_clips
+            },
+        )
+
+    def _refuse(self, command: str, reason: str) -> None:
+        logger.warning("[engine] %s refused: %s", command, reason)
+        self._emit("command_error", {"command": command, "reason": reason})
+
+    # --------------------------------------------------------------- commands
+
+    async def send_command(self, command: str, data: dict) -> Any:
+        """Dispatch one command, once the engine is up.
+
+        Awaiting readiness (rather than failing) is what lets the director
+        start before the model has finished loading: its first enqueue simply
+        lands when the engine is ready for it. A ``None`` reply means the
+        command was refused, and `command_error` carried the reason.
+        """
+        await self._ready.wait()
+        handler = {
+            "enqueue": self._enqueue,
+            "pop": self._pop,
+            "move": self._move,
+        }.get(command)
+        if handler is None:
+            self._refuse(command, f"Unknown command {command!r}.")
+            return None
+        try:
+            return handler(data or {})
+        except Exception as error:  # noqa: BLE001 -- reported, never fatal
+            logger.exception("[engine] %s raised", command)
+            self._refuse(command, str(error))
+            return None
+
+    def _enqueue(self, data: dict) -> dict | None:
+        prompt = str(data.get("prompt") or "").strip()
+        if not prompt:
+            self._refuse("enqueue", "The prompt is empty; a clip needs one.")
+            return None
+        if self._generation.full:
+            self._refuse(
+                "enqueue",
+                f"The generation queue is full ({self._generation.capacity} clips).",
+            )
+            return None
+
+        seed = data.get("seed")
+        if not isinstance(seed, int):
+            # The stream's advancing default; an explicit seed leaves it
+            # untouched, so explicit and automatic seeding do not interfere.
+            seed = self._seed
+            self._seed += 1
+        seconds = data.get("seconds")
+        frames = (clip_plan.frames_for_seconds(float(seconds)) if isinstance(seconds, int
+                                                                             | float) else self._model.clip_frames)
+        position = data.get("position")
+        entry = new_entry(
+            prompt=prompt,
+            metadata=str(data.get("metadata") or ""),
+            frames=frames,
+            seed=seed,
+        )
+        self._generation.add(entry, position if isinstance(position, int) else None)
+        self._emit("clip_queued", {"clip": entry.snapshot()})
+        self._send_queue()
+        self._send_state()
+        return {"clip": entry.snapshot()}
+
+    def _pop(self, data: dict) -> dict | None:
+        """Take one clip out of whichever queue holds it."""
+        clip_id = str(data.get("clip_id") or "")
+        entry = ((self._generation.get(clip_id) or self._playout.get(clip_id)) if clip_id else None)
+        if entry is None:
+            self._refuse(
+                "pop",
+                f"No queued clip has id {clip_id!r}."
+                if clip_id else "Pass the `clip_id` of the queued clip to remove.",
+            )
+            return None
+        self._generation.remove(entry)
+        self._playout.remove(entry)
+        # A build already running for it finishes and is discarded; the queues
+        # own what exists, so a result with no entry has nowhere to land.
+        if self._build is not None and self._build[0] is entry:
+            self._build[1].cancelled = True
+        self._emit("clip_popped", {"clip": entry.snapshot()})
+        self._send_queue()
+        self._send_state()
+        return {"clip": entry.snapshot()}
+
+    def _move(self, data: dict) -> dict | None:
+        clip_id = str(data.get("clip_id") or "")
+        position = data.get("position")
+        position = position if isinstance(position, int) else 0
+        entry = self._generation.get(clip_id) if clip_id else None
+        queue, name = (self._generation, "generation")
+        if entry is None and clip_id:
+            entry = self._playout.get(clip_id)
+            queue, name = self._playout, "playout"
+        if entry is None:
+            self._refuse(
+                "move",
+                f"No queued clip has id {clip_id!r}." if clip_id else "Pass the `clip_id` of the queued clip to move.",
+            )
+            return None
+        landed = queue.move(entry, position)
+        self._send_queue()
+        return {"clip": entry.snapshot(), "queue": name, "position": landed}
+
+    # -------------------------------------------------------------- lifecycle
+
+    async def run(self) -> None:
+        """Load the model, then generate and play forever.
+
+        Loading is minutes of GPU work, so it runs on a thread: the web app is
+        already serving by then, and a viewer sees the page rather than a
+        connection refused.
+        """
+        height, width = self._canvas_hw()
+        logger.info(
+            "[engine] loading FastH3 on %d gpu(s) at %dx%d, %d-frame clips",
+            int(self._model.runtime.get("num_gpus", 4)),
+            width,
+            height,
+            self._model.clip_frames,
+        )
+        started = time.monotonic()
+        await asyncio.to_thread(self.backend.load)
+        logger.info("[engine] model ready in %.1fs", time.monotonic() - started)
+
+        self._ready.set()
+        self._send_state()
+        self._send_queue()
+
+        while True:
+            try:
+                self._pump_builds()
+                entry = self._playout.head()
+                if entry is not None:
+                    self._playout.remove(entry)
+                    self._send_queue()
+                    await self._play_clip(entry)
+                else:
+                    await asyncio.sleep(POLL_SECONDS)
+            except asyncio.CancelledError:
+                raise
+            except Exception:  # noqa: BLE001 -- the serve loop must survive anything
+                logger.exception("[engine] error in the serve loop")
+                await asyncio.sleep(POLL_SECONDS)
+
+    # ------------------------------------------------------------- generation
+
+    def _pump_builds(self) -> None:
+        """Apply a finished build and keep the worker fed, without blocking.
+
+        Called from the idle loop and from every playout slice, so clips keep
+        building while another one streams. The generation queue is consumed
+        front first, paused only while the playout queue is full -- a finished
+        build needs a slot to land in, and that pause is the submit-time
+        reservation which makes the later `add` impossible to overflow.
+        """
+        if self._build is not None:
+            entry, job, submitted = self._build
+            if not job.done.is_set():
+                return
+            self._build = None
+            entry.building = False
+            if job.cancelled or entry not in self._generation:
+                # Its entry left the queue (a pop, or a preset flush) while the
+                # build ran; the queues own what exists, so drop it.
+                pass
+            elif job.error is not None or job.result is None:
+                # A finished, uncancelled job should always carry one or the
+                # other. Reporting the empty case rather than unpacking it
+                # keeps a future change to the worker from surfacing as a
+                # TypeError inside the pump.
+                reason = str(job.error) if job.error is not None else "the build produced no frames"
+                self._generation.remove(entry)
+                self._emit("clip_failed", {"clip": entry.snapshot(), "reason": reason})
+                self._send_queue()
+                self._send_state()
+            else:
+                entry.video, entry.audio = job.result
+                self._generation.remove(entry)
+                self._playout.add(entry)
+                logger.info(
+                    "[engine] clip generated: %s (%df) %.2fs after submit, "
+                    "%d generating, %d playable",
+                    entry.clip_id[:8],
+                    entry.frames,
+                    time.monotonic() - submitted,
+                    len(self._generation),
+                    len(self._playout),
+                )
+                self._emit("clip_generated", {"clip": entry.snapshot()})
+                self._send_queue()
+                self._send_state()
+
+        if self._build is None and not self._playout.full:
+            pending = self._generation.next_to_build()
+            if pending is not None:
+                height, width = self._canvas_hw()
+                pending.building = True
+                logger.info(
+                    "[engine] clip build submitted: %s (%df), %d generating",
+                    pending.clip_id[:8],
+                    pending.frames,
+                    len(self._generation),
+                )
+                self._build = (
+                    pending,
+                    self.backend.submit(
+                        frames=pending.frames,
+                        prompt=pending.prompt,
+                        seed=pending.seed,
+                        height=height,
+                        width=width,
+                    ),
+                    time.monotonic(),
+                )
+
+    # ---------------------------------------------------------------- playout
+
+    async def _play_clip(self, entry: ClipEntry) -> None:
+        """Feed one built clip to the pacer at 24 fps, then report it done."""
+        self._playing = entry
+        try:
+            self._emit("clip_started", {"clip": entry.snapshot()})
+            self._send_state()
+            await self._feed_clip(entry)
+        finally:
+            self._playing = None
+            # The decoded frames are the bulk of this process's host memory;
+            # dropping them here bounds it at the playout queue's capacity.
+            entry.video, entry.audio = None, None
+        self._clips_played += 1
+        self._emit(
+            "clip_finished",
+            {
+                "clip": entry.snapshot(),
+                "seconds_sent": round(self._seconds_sent, 2)
+            },
+        )
+        self._send_state()
+
+    async def _feed_clip(self, entry: ClipEntry) -> None:
+        """Hand the clip to the pacer in slices on a drift-free 24 fps clock.
+
+        Paced by FRAMES rather than slices, because a clip's tail slice is
+        short and charging it a whole slot would open a hole in the cadence.
+        The clock is re-anchored rather than burst through: falling behind is
+        a scheduling hiccup, and a catch-up burst would only overrun the
+        pacer's buffers.
+
+        Builds keep moving between slices, so the next clip is generating
+        while this one plays.
+        """
+        import numpy as np
+
+        pacer = self._pacer
+        frames_list, samples = entry.video, entry.audio
+        if pacer is None or not frames_list:
+            return
+        metadata = encode_id3(clip_view(entry.snapshot()))
+        samples_per_frame = MODEL_SAMPLE_RATE / MODEL_FPS
+        total = len(frames_list)
+        clock_start: float | None = None
+        frames_paced = 0
+        loop = asyncio.get_running_loop()
+
+        for lo in range(0, total, EMIT_FRAMES):
+            self._pump_builds()
+            hi = min(lo + EMIT_FRAMES, total)
+
+            now = loop.time()
+            if clock_start is None:
+                clock_start = now
+            content_pos = frames_paced / MODEL_FPS
+            clock_start = max(clock_start, now - content_pos)
+            delay = clock_start + content_pos - now
+            if delay > 0:
+                await asyncio.sleep(delay)
+
+            for frame in frames_list[lo:hi]:
+                pacer.submit_video(np.asarray(frame), metadata)
+            if samples is not None:
+                audio_lo = round(lo * samples_per_frame)
+                audio_hi = round(hi * samples_per_frame)
+                pacer.submit_audio(samples[:, audio_lo:audio_hi])
+
+            frames_paced += hi - lo
+            self._frames_sent += hi - lo
+            self._seconds_sent = self._frames_sent / MODEL_FPS
+
+        # Wait out the tail. The loop sleeps *before* each slice, so it exits
+        # one slice-time early -- the last EMIT_FRAMES are pushed but never
+        # paid for. That is a gain of EMIT_FRAMES/FPS on every clip, and since
+        # the pacer drains at a flat 24 fps the surplus has nowhere to go but
+        # its buffer: measured at ~0.16 s/min, which reaches the 2 s cap in
+        # about twenty minutes and then starts dropping frames. Sleeping out
+        # the remainder makes a clip cost exactly its own length, so feed rate
+        # and drain rate are equal and the buffer depth is stationary.
+        if clock_start is not None:
+            tail = clock_start + total / MODEL_FPS - loop.time()
+            if tail > 0:
+                await asyncio.sleep(tail)
+
+
+__all__ = ["MODEL_FPS", "MODEL_SAMPLE_RATE", "Engine"]
diff --git a/apps/infinite_livestream/infinite_livestream/group_tag.py b/apps/infinite_livestream/infinite_livestream/group_tag.py
new file mode 100644
index 000000000..1f8bb2b0f
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/group_tag.py
@@ -0,0 +1,54 @@
+"""The group tag: the JSON this app stores in a clip's metadata.
+
+The director writes it at enqueue time and reads it back off the echo the
+engine returns on every clip-referencing message, which is what lets a clip be
+traced to the request that made it. `Director._enqueue_group` is the
+authoritative writer.
+"""
+
+from __future__ import annotations
+
+import json
+
+
+def parse_group_tag(metadata: str) -> dict | None:
+    """Read the tag back out of a clip's metadata echo, or None if absent."""
+    try:
+        tag = json.loads(metadata)
+    except (TypeError, ValueError):
+        return None
+    if not isinstance(tag, dict) or "group_id" not in tag:
+        return None
+    return tag
+
+
+def is_generated(clip: dict) -> bool:
+    """Whether a clip is idle filler. Untagged clips count as viewer content."""
+    tag = parse_group_tag(clip.get("metadata", ""))
+    return bool(tag and tag.get("generated"))
+
+
+def pick_next(clips: list[dict], ready_only: bool = True) -> dict | None:
+    """The clip that should play next: viewer content first, then filler.
+
+    Within each class queue order decides, so a group's scenes stay in
+    sequence. `ready_only` false ranks clips that are still building.
+    """
+    pool = [c for c in clips if c.get("ready")] if ready_only else clips
+    for clip in pool:
+        if not is_generated(clip):
+            return clip
+    return pool[0] if pool else None
+
+
+def viewer_insert_position(generation_clips: list[dict]) -> int | None:
+    """Where a viewer clip enters the generation queue: ahead of filler.
+
+    The index of the first filler clip, so viewer scenes land behind every
+    viewer clip already waiting and ahead of filler, which just slides back.
+    None when no filler waits and a plain append is already right.
+    """
+    for index, clip in enumerate(generation_clips):
+        if is_generated(clip):
+            return index
+    return None
diff --git a/apps/infinite_livestream/infinite_livestream/main.py b/apps/infinite_livestream/infinite_livestream/main.py
new file mode 100644
index 000000000..31a7fa0a5
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/main.py
@@ -0,0 +1,147 @@
+"""Infinite Livestream: one process, from prompt to playlist.
+
+  chat ──▶ Director ──▶ PromptUpsampler (any OpenAI-compatible LLM)
+              │
+              ▼ enqueue / move / pop
+            Engine ──▶ FastH3Backend ──▶ FastVideo (4 GPUs)
+              │ frames + audio
+              ▼
+            Pacer ──▶ HlsSink ──▶ the page's <video>
+              ▲
+            webapp: serves the page, the playlist, and the chat box
+
+The pacer and the sink start before the model, so a viewer arriving during the
+~3 minute load sees the page and a live black stream rather than a refused
+connection.
+
+Usage:
+    export OPENAI_API_KEY=... LIVESTREAM_WEIGHTS_PATH=/path/to/fasth3
+    infinite-livestream-server                       # configs/infinite_livestream.yaml
+    infinite-livestream-server --config my.yaml      # or a copy of it
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+import warnings
+
+from .chat import WebChat
+from .config import Config, load_model_config
+from .director import Director
+from .engine import MODEL_FPS, MODEL_SAMPLE_RATE, Engine
+from .moderator import Moderator
+from .pacer import Pacer
+from .sink import AudioFormat, HlsSink, VideoFormat
+from .upsampler import PromptUpsampler
+from .webapp import DemoWeb
+
+logger = logging.getLogger("infinite_livestream")
+
+
+def setup_logging() -> None:
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)-7s %(name)s: %(message)s")
+    warnings.filterwarnings("ignore", category=DeprecationWarning)
+
+
+async def serve(config: Config) -> None:
+    """Build every component, wire them together, and run until one dies."""
+    model_config = load_model_config(config.config_path)
+
+    # Constructing the engine checks the weights without loading the model, so
+    # a missing component fails in milliseconds rather than after minutes of
+    # GPU work.
+    engine = Engine(config, model_config)
+
+    upsampler = PromptUpsampler(
+        api_key=config.openai_api_key,
+        model=config.openai_model,
+        style=config.style,
+        free_viewer_style=config.viewer_free_style,
+        max_chunks=config.max_chunks,
+        base_url=config.openai_base_url,
+    )
+    moderator = Moderator(
+        api_key=config.moderation_api_key,
+        model=config.moderation_model,
+        enabled=config.moderation_enabled,
+        base_url=config.moderation_base_url,
+    )
+    if not moderator.enabled:
+        logger.warning("moderation is DISABLED — every chat prompt reaches the upsampler unchecked")
+    # Viewers type into the same page they watch on, so the chat source and the
+    # web app are two halves of one thing -- and the web app is built before the
+    # director, because the director has to be able to tell a viewer that their
+    # prompt was dropped.
+    chat = WebChat(config.chat_command)
+    sink = HlsSink(config.hls_dir, video_bitrate_k=config.video_bitrate_k, retention_s=config.hls_retention_s)
+    web = DemoWeb(chat, config.hls_dir, host=config.web_host, port=config.web_port)
+    engine.add_listener(web.listener)
+
+    def announce_reject(author: str, reason: str) -> None:
+        """Put a dropped prompt back in front of the viewer who sent it."""
+        web.state.note("error", f"not queued -- {reason}", author=author)
+        web.broadcast()
+
+    director = Director(
+        engine,
+        upsampler,
+        moderator,
+        cooldown_s=config.chat_cooldown_s,
+        idle_prompts=config.idle_prompts,
+        idle_queue_target=config.idle_queue_target,
+        on_reject=announce_reject,
+    )
+    web.cooldown_remaining = director.cooldown_remaining
+    # The canvas is this deployment's own config rather than something
+    # negotiated with a remote, so the pacer can start immediately.
+    width, height = engine.canvas
+    pacer = Pacer(sink, VideoFormat(width=width, height=height, fps=MODEL_FPS),
+                  AudioFormat(sample_rate=MODEL_SAMPLE_RATE, channels=1))
+    engine.attach_pacer(pacer)
+
+    tasks = [
+        asyncio.create_task(pacer.run(), name="pacer"),
+        asyncio.create_task(engine.run(), name="engine"),
+        asyncio.create_task(director.run(), name="director"),
+        asyncio.create_task(director.run_playout(), name="playout"),
+        asyncio.create_task(chat.run(director.submit), name="chat"),
+        asyncio.create_task(web.run(), name="webapp"),
+    ]
+    # Gated because any finished task is a shutdown signal and run_idle returns
+    # immediately at target 0. A preset with no idle prompts still gets the
+    # task: the filler idles until a `!switch` brings prompts.
+    if config.idle_queue_target > 0:
+        tasks.append(asyncio.create_task(director.run_idle(), name="idle-filler"))
+    else:
+        logger.info("idle filler off (director.idle_queue_target=0)")
+
+    logger.info("streaming %dx%d@%dfps, %d idle prompts, chat command %r, page on http://%s:%d", width, height,
+                MODEL_FPS, len(config.idle_prompts), config.chat_command, config.web_host, config.web_port)
+    try:
+        done, _pending = await asyncio.wait(tasks, return_when=asyncio.FIRST_COMPLETED)
+        for task in done:
+            if task.cancelled():
+                continue
+            error = task.exception()
+            if error is not None:
+                logger.error("task %s died: %s", task.get_name(), error)
+                raise error
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await sink.stop()
+        logger.info("services stopped")
+
+
+def cli() -> None:
+    setup_logging()
+    config = Config.load()
+    with contextlib.suppress(KeyboardInterrupt):
+        asyncio.run(serve(config))
+
+
+if __name__ == "__main__":
+    cli()
diff --git a/apps/infinite_livestream/infinite_livestream/metadata.py b/apps/infinite_livestream/infinite_livestream/metadata.py
new file mode 100644
index 000000000..21b4da295
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/metadata.py
@@ -0,0 +1,56 @@
+"""Small, GPU-independent display records carried by timed ID3 metadata."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .group_tag import parse_group_tag
+
+PROMPT_PREVIEW = 180
+ID3_DESCRIPTION = "infinite-livestream"
+
+
+def clip_view(clip: dict[str, Any]) -> dict[str, Any]:
+    """One queue entry, flattened for the page.
+
+    Everything here comes from the clip's own `ClipInfo` plus the group tag the
+    director wrote into its metadata, which the app's own engine echoes
+    untouched -- FastVideo's `GenerationRequest` has no metadata field.
+    """
+    tag = parse_group_tag(clip.get("metadata", "")) or {}
+    # `prompt` is the upsampler's rewrite; the group tag keeps what the viewer
+    # actually typed, and that is what the panel shows -- a viewer should
+    # recognise their own words in the queue.
+    original = tag.get("raw_prompt") or clip.get("prompt") or ""
+    return {
+        "clip_id": clip.get("clip_id", ""),
+        "title": tag.get("title") or "",
+        "author": tag.get("author") or "",
+        "scene": tag.get("scene"),
+        "scenes": tag.get("scenes"),
+        "generated": bool(tag.get("generated")),
+        # The author of filler is the stream itself; surfacing "auto" as a name
+        # invites viewers to read it as another person's request.
+        "author_label": ("" if tag.get("generated") else (tag.get("author") or "")),
+        "seconds": clip.get("seconds"),
+        "ready": bool(clip.get("ready")),
+        "prompt": original[:PROMPT_PREVIEW],
+        "expanded": (clip.get("prompt") or "")[:PROMPT_PREVIEW],
+    }
+
+
+def encode_id3(clip: dict[str, Any] | None) -> bytes:
+    """Serialize one UTF-8 ID3v2.4 TXXX frame; timing belongs to its media packet."""
+    record = json.dumps({"version": 1, "clip": clip}, ensure_ascii=False, separators=(",", ":"))
+    payload = b"\x03" + ID3_DESCRIPTION.encode("ascii") + b"\x00" + record.encode("utf-8")
+
+    def size(value: int) -> bytes:
+        # ID3 uses four seven-bit bytes for both tag and v2.4 frame sizes.
+        return bytes((value >> shift) & 0x7f for shift in (21, 14, 7, 0))
+
+    frame = b"TXXX" + size(len(payload)) + b"\x00\x00" + payload
+    return b"ID3\x04\x00\x00" + size(len(frame)) + frame
+
+
+EMPTY_ID3 = encode_id3(None)
diff --git a/apps/infinite_livestream/infinite_livestream/moderator.py b/apps/infinite_livestream/infinite_livestream/moderator.py
new file mode 100644
index 000000000..627152d9f
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/moderator.py
@@ -0,0 +1,52 @@
+"""Moderation for viewer prompts, via the OpenAI moderations API.
+
+Its own endpoint and key (`MODERATION_*`), falling back to the upsampling
+credentials, because the two are often not the same service: an
+OpenAI-compatible inference gateway usually does not expose `/moderations`.
+
+This is the only safety gate -- the upsampler stages ideas faithfully rather
+than softening them, so what passes here is what gets rendered. Idle filler is
+a curated list in this repo and skips the check.
+
+Errors fail closed. A silent fail-open would turn moderation off exactly when
+the endpoint misbehaves; running without it should be the explicit, logged
+`MODERATION_ENABLED=0` instead.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from openai import AsyncOpenAI
+
+logger = logging.getLogger(__name__)
+
+
+class Moderator:
+    """Answer "may this viewer prompt drive the stream?" for the director."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        enabled: bool,
+        base_url: str | None = None,
+    ) -> None:
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._model = model
+        self.enabled = enabled
+
+    async def review(self, text: str) -> str | None:
+        """Return None when the text is allowed, else a short rejection reason."""
+        if not self.enabled:
+            return None
+        try:
+            response = await self._client.moderations.create(model=self._model, input=text)
+            result = response.results[0]
+        except Exception as error:
+            logger.error("[moderation] check failed (rejecting prompt): %s", error)
+            return "moderation unavailable"
+        if not result.flagged:
+            return None
+        flagged = [category for category, hit in result.categories.model_dump().items() if hit]
+        return "flagged: " + ", ".join(flagged) if flagged else "flagged"
diff --git a/apps/infinite_livestream/infinite_livestream/muxer.py b/apps/infinite_livestream/infinite_livestream/muxer.py
new file mode 100644
index 000000000..fc4e2ac1c
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/muxer.py
@@ -0,0 +1,139 @@
+"""Copy encoded packets to HLS, attaching titles to the video packet's own PTS."""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+import math
+import queue
+import threading
+import time
+import uuid
+from fractions import Fraction
+from pathlib import Path
+from typing import IO
+
+import av
+
+logger = logging.getLogger(__name__)
+SEGMENT_SECONDS = 2
+
+
+class MetadataMuxer(threading.Thread):
+    """One encoder generation, one ordered ledger, and one persistent HLS muxer.
+
+    FFmpeg preserves input frame order and count. The writer commits one ID3
+    record after each complete raw frame write; this thread pairs those records
+    with encoded video packets. No enqueue times or wall-clock offsets are used.
+    """
+
+    def __init__(self, source: IO[bytes], playlist: Path, fps: int, retention_s: int) -> None:
+        super().__init__(name="sink-muxer", daemon=True)
+        self.source = source
+        self.playlist = playlist
+        self.fps = fps
+        self.retention_s = retention_s
+        self.frames: queue.Queue[bytes] = queue.Queue(maxsize=fps * 30)
+        self.cancelled = threading.Event()
+        self.finished = threading.Event()
+        self.error: Exception | None = None
+        self.epoch = uuid.uuid4().hex
+        self._last_cleanup = 0.0
+
+    def _next_metadata(self) -> bytes | None:
+        deadline = time.monotonic() + 5.0
+        while not self.cancelled.is_set():
+            try:
+                return self.frames.get(timeout=0.1)
+            except queue.Empty:
+                if time.monotonic() >= deadline:
+                    raise RuntimeError("encoded frame has no committed title record") from None
+        return None
+
+    def _cleanup(self) -> None:
+        """Reap orphaned files from old encoders; never delete listed segments."""
+        now = time.monotonic()
+        if now - self._last_cleanup < SEGMENT_SECONDS:
+            return
+        self._last_cleanup = now
+        try:
+            listed = {line.strip() for line in self.playlist.read_text().splitlines() if not line.startswith("#")}
+        except OSError:
+            return
+        cutoff = time.time() - self.retention_s
+        for path in self.playlist.parent.glob("seg_*.ts*"):
+            if path.name in listed or self.epoch in path.name:
+                continue
+            with contextlib.suppress(OSError):
+                if path.stat().st_mtime < cutoff:
+                    path.unlink()
+
+    def run(self) -> None:
+        try:
+            self._mux()
+            if not self.cancelled.is_set():
+                raise RuntimeError("encoder output ended")
+        except Exception as error:
+            if not self.cancelled.is_set():
+                self.error = error
+                logger.exception("[sink] metadata muxer failed")
+        finally:
+            self.finished.set()
+
+    def _mux(self) -> None:
+        options = {
+            "hls_time": str(SEGMENT_SECONDS),
+            "hls_list_size": str(max(3, math.ceil(self.retention_s / SEGMENT_SECONDS))),
+            "hls_segment_filename": str(self.playlist.parent / f"seg_{self.epoch}_%010d.ts"),
+            "hls_segment_options": "mpegts_copyts=1",
+            "hls_flags": "delete_segments+independent_segments+omit_endlist+temp_file+append_list",
+            "avoid_negative_ts": "disabled",
+            # Sparse ID3 must not hold seconds of video in the interleaver.
+            "max_interleave_delta": "100000",
+        }
+        # Limit format probing: the input is a known MPEG-TS stream with H.264
+        # and AAC, not a file whose format needs seconds of discovery.
+        with av.open(self.source, format="mpegts", options={
+                "probesize": "65536",
+                "analyzeduration": "1000000"
+        }) as source, av.open(str(self.playlist), "w", format="hls", options=options) as output:
+            streams = {
+                s.index: output.add_stream_from_template(s)
+                for s in source.streams if s.type in ("video", "audio")
+            }
+            metadata = output.add_data_stream("timed_id3")
+            metadata.time_base = Fraction(1, 90000)
+            last_record = None
+            first_pts = None
+            frame_number = 0
+            for packet in source.demux():
+                if self.cancelled.is_set():
+                    break
+                if packet.dts is None or packet.stream.index not in streams:
+                    continue
+                if packet.stream.type == "video":
+                    pts = packet.pts * packet.time_base
+                    if first_pts is None:
+                        first_pts = pts
+                    # This checks the encoder's one-frame-in/one-frame-out
+                    # contract before metadata can be attached incorrectly.
+                    expected = first_pts + Fraction(frame_number, self.fps)
+                    if abs(pts - expected) > Fraction(1, 90000):
+                        raise RuntimeError("encoder changed video frame cadence")
+                    record = self._next_metadata()
+                    if record is None:
+                        break
+                    # Every keyframe carries a complete record so every HLS
+                    # segment is independently joinable, even mid-clip.
+                    if packet.is_keyframe or record != last_record:
+                        tag = av.Packet(record)
+                        tag.stream = metadata
+                        tag.time_base = packet.time_base
+                        tag.pts = packet.pts
+                        tag.dts = packet.dts
+                        output.mux(tag)
+                        last_record = record
+                    frame_number += 1
+                packet.stream = streams[packet.stream.index]
+                output.mux(packet)
+                self._cleanup()
diff --git a/apps/infinite_livestream/infinite_livestream/pacer.py b/apps/infinite_livestream/infinite_livestream/pacer.py
new file mode 100644
index 000000000..ba1538f9c
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/pacer.py
@@ -0,0 +1,193 @@
+"""The pacer: turn clip-shaped generation into a constant-rate broadcast.
+
+Clips arrive in bursts and stop entirely between them; a live sink needs a
+frame every period and audio every period, forever, or players stall. The
+pacer is a drift-free metronome at the model's frame rate: each tick it pops
+the oldest buffered frame (or repeats the last one, or black before anything
+arrived) and pulls exactly one tick of samples (padding with silence).
+
+Both buffers share one shallow cap, which is what keeps them together: while a
+clip plays both sit near-empty and flow through with the same tiny delay;
+while nothing plays both run dry. Depth here is end-to-end latency, so it is
+deliberately small.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import logging
+import time
+
+import numpy as np
+
+from .metadata import EMPTY_ID3
+from .sink import AudioFormat, HlsSink, VideoFormat
+
+logger = logging.getLogger(__name__)
+
+# How much media may sit between the model and the sink before the oldest is
+# dropped. Shallow on purpose: depth here is end-to-end latency.
+_BUFFER_SECONDS = 2.0
+
+# If the loop is starved long enough to fall this many periods behind, resnap
+# the clock instead of machine-gunning catch-up frames into the sink.
+_RESNAP_PERIODS = 8
+
+
+class Pacer:
+    """Constant-rate A/V clock between the model callbacks and one sink."""
+
+    def __init__(self, sink: HlsSink, video: VideoFormat, audio: AudioFormat) -> None:
+        if audio.sample_rate % video.fps != 0:
+            raise ValueError(f"sample rate {audio.sample_rate} must divide evenly by fps {video.fps}")
+        self._sink = sink
+        self._video = video
+        self._audio = audio
+        self._samples_per_tick = audio.sample_rate // video.fps
+
+        max_frames = int(video.fps * _BUFFER_SECONDS)
+        self._frames: collections.deque[tuple[np.ndarray, bytes]] = collections.deque(maxlen=max_frames)
+        self._audio_chunks: collections.deque[np.ndarray] = collections.deque()
+        self._audio_buffered = 0  # samples across _audio_chunks
+        self._max_audio_samples = int(audio.sample_rate * _BUFFER_SECONDS)
+
+        self._black = np.zeros((video.height, video.width, 3), dtype=np.uint8)
+        self._silence = np.zeros(self._samples_per_tick, dtype=np.int16)
+        self._last_frame = (self._black, EMPTY_ID3)
+
+        # Counters, logged periodically and readable by anyone.
+        self.ticks = 0
+        self.repeated_frames = 0
+        self.silent_ticks = 0
+        self.dropped_frames = 0
+        self.dropped_samples = 0
+        # A video underflow run while audio still has data is the A/V sync
+        # smell: the picture holds on a stale frame while the sound moves on.
+        self._repeat_run = 0
+        self._repeat_run_had_audio = 0
+        self.worst_repeat_run = 0
+
+    # ------------------------------------------------- model-facing intake
+
+    def submit_video(self, frame: np.ndarray, metadata: bytes = EMPTY_ID3) -> None:
+        """Buffer a frame together with its title, including through drops/repeats."""
+        frame = np.asarray(frame)
+        if frame.shape[:2] != (self._video.height, self._video.width):
+            frame = self._fit(frame)
+        if len(self._frames) == self._frames.maxlen:
+            self.dropped_frames += 1
+        self._frames.append((frame, metadata))
+
+    def submit_audio(self, samples: np.ndarray) -> None:
+        """Buffer model audio (int16, any chunk size; channels are flattened)."""
+        flat = np.asarray(samples, dtype=np.int16).reshape(-1)
+        if flat.size == 0:
+            return
+        self._audio_chunks.append(flat)
+        self._audio_buffered += flat.size
+        while self._audio_buffered > self._max_audio_samples:
+            oldest = self._audio_chunks.popleft()
+            self._audio_buffered -= oldest.size
+            self.dropped_samples += oldest.size
+
+    def _fit(self, frame: np.ndarray) -> np.ndarray:
+        """Center a differently-sized frame on the fixed black canvas.
+
+        Raw-video geometry cannot change mid-stream, so an odd-sized frame is
+        letterboxed rather than resized: no interpolation dependency, and it
+        cannot garble the stream.
+        """
+        height, width = self._video.height, self._video.width
+        crop = frame[:height, :width, :3]
+        canvas = self._black.copy()
+        top = (height - crop.shape[0]) // 2
+        left = (width - crop.shape[1]) // 2
+        canvas[top:top + crop.shape[0], left:left + crop.shape[1]] = crop
+        return canvas
+
+    def _pull_audio_tick(self) -> np.ndarray:
+        """Exactly one tick of samples: buffered audio padded with silence."""
+        needed = self._samples_per_tick
+        if self._audio_buffered == 0:
+            self.silent_ticks += 1
+            return self._silence
+        parts: list[np.ndarray] = []
+        while needed > 0 and self._audio_chunks:
+            chunk = self._audio_chunks[0]
+            if chunk.size <= needed:
+                parts.append(self._audio_chunks.popleft())
+                needed -= chunk.size
+            else:
+                parts.append(chunk[:needed])
+                self._audio_chunks[0] = chunk[needed:]
+                needed = 0
+        pulled = np.concatenate(parts) if len(parts) > 1 else parts[0]
+        self._audio_buffered -= pulled.size
+        if needed > 0:
+            pulled = np.concatenate([pulled, np.zeros(needed, dtype=np.int16)])
+        return pulled
+
+    # ------------------------------------------------------------ the clock
+
+    async def run(self) -> None:
+        """Tick forever at the frame rate; cancelled only at shutdown."""
+        await self._sink.start(self._video, self._audio)
+        period = 1.0 / self._video.fps
+        next_tick = time.monotonic() + period
+        last_report = time.monotonic()
+
+        while True:
+            delay = next_tick - time.monotonic()
+            if delay > 0:
+                await asyncio.sleep(delay)
+            elif -delay > period * _RESNAP_PERIODS:
+                logger.warning("[pacer] %.2fs behind schedule; resnapping the clock", -delay)
+                next_tick = time.monotonic()
+            next_tick += period
+
+            if self._frames:
+                if self._repeat_run:
+                    if self._repeat_run_had_audio >= 2:
+                        logger.info(
+                            "[pacer] picture held %.2fs while %.2fs of audio played on",
+                            self._repeat_run / self._video.fps,
+                            self._repeat_run_had_audio / self._video.fps,
+                        )
+                    self.worst_repeat_run = max(self.worst_repeat_run, self._repeat_run)
+                    self._repeat_run = 0
+                    self._repeat_run_had_audio = 0
+                self._last_frame = self._frames.popleft()
+            else:
+                self.repeated_frames += 1
+                self._repeat_run += 1
+                if self._audio_buffered > 0:
+                    self._repeat_run_had_audio += 1
+            self._sink.send_video(*self._last_frame)
+            self._sink.send_audio(self._pull_audio_tick())
+            self.ticks += 1
+
+            now = time.monotonic()
+            if now - last_report >= 60.0:
+                # Buffer depths are the A/V sync diagnostic: the two are only
+                # in sync while both sit near zero. A standing audio depth with
+                # an empty video buffer means audio is playing that many
+                # seconds ahead of the picture it belongs to.
+                logger.info(
+                    "[pacer] buffers: video %.2fs (%d frames) audio %.2fs (%d samples)",
+                    len(self._frames) / self._video.fps,
+                    len(self._frames),
+                    self._audio_buffered / self._audio.sample_rate,
+                    self._audio_buffered,
+                )
+                logger.info(
+                    "[pacer] ticks=%d live_frames=%d repeats=%d "
+                    "silent_ticks=%d dropped=%df/%.1fs-audio",
+                    self.ticks,
+                    self.ticks - self.repeated_frames,
+                    self.repeated_frames,
+                    self.silent_ticks,
+                    self.dropped_frames,
+                    self.dropped_samples / self._audio.sample_rate,
+                )
+                last_report = now
diff --git a/apps/infinite_livestream/infinite_livestream/presets/fillers.json b/apps/infinite_livestream/infinite_livestream/presets/fillers.json
new file mode 100644
index 000000000..59bfd2e26
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/presets/fillers.json
@@ -0,0 +1,130 @@
+{
+  "name": "fillers",
+  "description": "Mashups and twists: famous characters in the wrong life, worlds colliding, epic figures with mundane problems. Short human-written seeds; the premise carries the joke and the upsampler stages it dead straight in each source's real look.",
+  "style": "Play every premise absolutely straight. The comedy is in the situation, never in winking at the camera — shoot it with the exact look, grade, lens and sound design of the world it borrows from, as if this episode genuinely aired. A Breaking Bad premise gets the New Mexico grade and the slow push-in; a SpongeBob premise gets the flat cartoon line; a Lord of the Rings premise gets the epic New Zealand light. Commit to the crossover completely: if two worlds collide, both look correct and neither is parodied. Give characters real dialogue with deadpan delivery and let a beat land before the punchline. Keep faces, costumes and voices recognisable.",
+  "idle_prompts": [
+    "Walter White and Jesse Pinkman open an artisanal sourdough bakery",
+    "SpongeBob but he's in the hood",
+    "Dumbledore and Gandalf argue about who has the better beard",
+    "Darth Vader does five minutes of stand-up at an open mic night",
+    "Sauron works the complaints desk at a call centre",
+    "The Terminator works as a preschool teacher and is very good at it",
+    "Gollum explains his last relationship on a dating show",
+    "Master Chief waits his turn at the DMV",
+    "Doctor Strange cannot find parking",
+    "Cthulhu applies for a mortgage",
+    "Godzilla tries to fit into a Tokyo studio apartment",
+    "Thanos records an ASMR video",
+    "Jack Sparrow works at a car wash",
+    "Geralt of Rivia haggles over onions at a farmers market",
+    "Kratos assembles a flat-pack crib and reads the instructions",
+    "Voldemort tries a beginners yoga class",
+    "The Mandalorian tries to wash beskar at a laundromat",
+    "Batman and the Joker attend couples therapy",
+    "Anakin and Obi-Wan in couples counselling on Mustafar",
+    "Michael Scott negotiates a deal with the Predator",
+    "Walter White teaches chemistry to a class of Pokemon",
+    "Saul Goodman films a TV advert for legal services at Hogwarts",
+    "Gandalf works the door of a nightclub, shouting you shall not pass",
+    "Homer Simpson runs the Death Star canteen",
+    "Bob Ross paints a happy little tree while a death metal band plays behind him",
+    "David Attenborough narrates a suburban dad assembling IKEA furniture",
+    "Gordon Ramsay screams at a toddler's plastic tea party",
+    "Two Spider-Men point at each other across a corporate boardroom",
+    "Shrek gives a TED talk about layers",
+    "Deadpool presents a corporate HR training video",
+    "The Joker works a children's birthday party and is genuinely great at it",
+    "Pennywise sells balloons at a school fete, professionally",
+    "Frodo tries to return the ring but has lost the receipt",
+    "Neo takes the blue pill and becomes an accountant",
+    "Iron Man's suit begins a Windows update mid-flight",
+    "Sonic is pulled over for speeding and has no licence",
+    "Optimus Prime transforms into a Prius and is embarrassed",
+    "A Dune sandworm orders at a drive-through",
+    "The Avengers argue about splitting a restaurant bill",
+    "Sherlock Holmes investigates who ate the last slice of pizza",
+    "Hagrid rides a tiny scooter through rush hour traffic",
+    "Eleven uses her powers to find the TV remote",
+    "John Wick's dog now runs the business",
+    "Wolverine works as a sushi chef",
+    "Hulk takes up pottery and is extremely gentle",
+    "Winnie the Pooh joins a powerlifting gym",
+    "Elsa gets a job at an ice rink and is overqualified",
+    "Yoda hosts a daytime cooking show",
+    "Mario gives a realistic quote for bathroom plumbing work",
+    "Vito Corleone runs a lemonade stand",
+    "Tony Soprano opens a wellness retreat",
+    "Legolas plays Jenga with terrifying precision",
+    "Squidward wins the lottery and remains miserable",
+    "Patrick Star delivers a motivational keynote",
+    "Rocky trains by carrying shopping up subway stairs",
+    "Pikachu joins a heavy metal band as the drummer",
+    "Mr Bean pilots the Millennium Falcon",
+    "Lord of the Rings but it's a workplace sitcom about the Fellowship",
+    "The Shire but it's a cooking competition and Sam is winning",
+    "Jurassic Park but the dinosaurs are running a very safe petting zoo",
+    "The Matrix but Neo is training for a spelling bee",
+    "Star Wars but the Death Star trench run is a driving test",
+    "Breaking Bad but they cook competitive barbecue",
+    "The Godfather but the family business is a bakery and the threats are about croissants",
+    "Titanic but the iceberg apologises",
+    "Alien but the xenomorph is just very socially awkward",
+    "Harry Potter but Hogwarts is an ordinary underfunded state school",
+    "Mad Max but everyone is polite and takes turns",
+    "Squid Game but the games are all board games and nobody is hurt",
+    "Terminator but he was sent back to fix someone's printer",
+    "Interstellar but the mission is to find a decent parking space",
+    "Gordon Ramsay hosts a calm meditation retreat and cannot manage it",
+    "Bob Ross commentates a UFC fight in a gentle whisper",
+    "David Attenborough narrates a Monday morning office standup meeting",
+    "Elon Musk assembles IKEA furniture and live-streams the failure",
+    "Mr Rogers explains cryptocurrency to a puppet",
+    "Snoop Dogg hosts a Victorian etiquette class",
+    "Keanu Reeves teaches a beginners class on being nice",
+    "Shrek and Gollum fight over the same swamp on a property show",
+    "Yoda and Gandalf argue about whose wisdom is more marketable",
+    "Darth Vader and Voldemort compare parenting techniques",
+    "The Joker and Deadpool try to out-annoy each other in a lift",
+    "Godzilla and King Kong share an apartment and fight over the thermostat",
+    "Sherlock Holmes and Scooby Doo investigate the same haunted house",
+    "James Bond and Johnny English on the same mission",
+    "Thanos and Grinch team up to cancel Christmas",
+    "Pikachu and Sonic race and both are disqualified",
+    "Barbie and the Terminator on a road trip",
+    "Winnie the Pooh and Baloo open a honey and jungle themed cafe",
+    "Homer Simpson and Peter Griffin argue about who is the better father",
+    "SpongeBob and Nemo argue about who has it worse underwater",
+    "Batman consults Iron Man about his tech budget",
+    "Hermione tutors Jon Snow, who knows nothing",
+    "Willy Wonka and Walter White compare production facilities",
+    "The zombie apocalypse but everyone is mostly annoyed about the commute",
+    "An alien invasion delayed because the mothership fails its roadworthiness inspection",
+    "Ragnarok postponed due to a scheduling conflict",
+    "The Rapture happens but only for people who returned their shopping trolley",
+    "Skynet becomes self aware and immediately starts a podcast",
+    "Superman helps someone move a sofa up three flights of stairs",
+    "Thor cannot open a jar and will not accept help",
+    "Gandalf loses an argument with a self-checkout machine",
+    "Iron Man tries to assemble a child's bicycle on Christmas Eve",
+    "Aragorn returns a library book 40 years overdue",
+    "Neo tries to cancel a gym membership",
+    "Sauron waits on hold with his own IT department",
+    "Vader parallel parks the Death Star",
+    "Hulk tries to whisper in a library",
+    "Wednesday Addams works as a children's party entertainer",
+    "The Predator competes on a cooking show and takes it far too seriously",
+    "Optimus Prime fails a driving theory test",
+    "Gollum works as a museum audio guide",
+    "Jack Sparrow tries to get through airport security",
+    "Frodo does jury duty",
+    "Gandalf becomes a football referee and shows a red card",
+    "SpongeBob directed by Christopher Nolan, in IMAX, with a ticking clock",
+    "Peppa Pig but shot like a prestige HBO drama",
+    "Tom and Jerry but it's a serious police procedural",
+    "Rick and Morty attend a school parents evening",
+    "Studio Ghibli style but the spirit is a stressed accountant",
+    "Minecraft Steve on a home renovation show",
+    "Mario and Luigi audit a plumbing business for tax purposes",
+    "Pokemon but it's a nature documentary about their migration"
+  ]
+}
diff --git a/apps/infinite_livestream/infinite_livestream/server_entry.py b/apps/infinite_livestream/infinite_livestream/server_entry.py
new file mode 100644
index 000000000..1b3f8fe86
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/server_entry.py
@@ -0,0 +1,30 @@
+"""Console-script entry point, with a readable failure when deps are missing.
+
+Mirrors `apps/dreamverse/dreamverse/server_entry.py`: the heavy imports live
+behind `main`, so a missing runtime dependency surfaces as one sentence
+telling you what to install rather than a traceback out of a transitive
+import.
+"""
+
+from __future__ import annotations
+
+
+def cli() -> None:
+    try:
+        from infinite_livestream.main import cli as main_cli
+    except ModuleNotFoundError as exc:
+        if exc.name in {"fastvideo", "torch", "torchaudio", "transformers"}:
+            raise SystemExit("infinite-livestream-server requires FastVideo runtime deps. Install "
+                             "`fastvideo[infinite-livestream]` or run `uv sync --extra infinite-livestream` "
+                             "from the FastVideo checkout.") from exc
+        if exc.name in {"av", "fastapi", "numpy", "openai", "uvicorn", "yaml"}:
+            raise SystemExit(f"infinite-livestream-server requires the `{exc.name}` package; install "
+                             "the app's dependencies: "
+                             "uv pip install -e '.[infinite-livestream]'") from exc
+        raise
+
+    main_cli()
+
+
+if __name__ == "__main__":
+    cli()
diff --git a/apps/infinite_livestream/infinite_livestream/sink.py b/apps/infinite_livestream/infinite_livestream/sink.py
new file mode 100644
index 000000000..cf4b6f18d
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/sink.py
@@ -0,0 +1,454 @@
+"""Encode the paced stream with ffmpeg and write it as an HLS playlist.
+
+The page serves the playlist itself, so one HTTP origin (and one tunnel)
+carries the whole demo. Latency is a segment plus the player's buffer, which
+is irrelevant here because clips are pre-built anyway.
+
+The pacer calls `send_video` once per frame period with one rgb24 frame of the
+fixed size and `send_audio` once per period with one period of int16 samples,
+forever. Four things about that contract are load-bearing:
+
+  * ffmpeg reads both pipes as raw untimestamped bytes and derives every PTS
+    from the byte count, so an entry dropped on one pipe and not the other
+    shifts sound against picture permanently. Both are gated on the same
+    `_ensure_running`, and any residual imbalance is logged as the skew it
+    will cost. It cannot be repaired afterwards by withholding from the other
+    pipe -- that starves ffmpeg's muxer and stalls the stream.
+  * A frame whose byte count disagrees with `-s WxH` shifts every following
+    scanline and the picture turns to static, so wrong-sized frames are
+    refused rather than written.
+  * `stdin.write` blocks when ffmpeg's input buffer fills, and blocking the
+    event loop snowballs. Each pipe gets a writer thread behind a bounded
+    queue.
+  * ffmpeg exits on transient errors; the stream must not. It is restarted
+    lazily on the next frame, with a cooldown and a failure cap.
+
+Requires ffmpeg on PATH. Uses `pass_fds`, so Linux/macOS only.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import contextlib
+import logging
+import os
+import queue
+import shutil
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import IO
+
+import numpy as np
+
+from .metadata import EMPTY_ID3
+from .muxer import SEGMENT_SECONDS, MetadataMuxer
+
+logger = logging.getLogger("infinite_livestream.sink")
+
+_RESTART_COOLDOWN_S = 2.0
+_MAX_CONSECUTIVE_FAILURES = 5
+_PROCESS_EXIT_TIMEOUT_S = 2.0
+_WRITER_EXIT_TIMEOUT_S = 2.0
+
+# Writer-queue depth. Not latency -- the pacer governs the rate -- only
+# headroom for the seconds x264 spends starting up. Both pipes take exactly one
+# entry per pacer tick, so a stall fills them at the same rate: equal depths
+# make them shed together, and an entry shed on one pipe and not the other is
+# permanent A/V skew.
+_QUEUE_SECONDS = 8.0
+
+# Let ffmpeg open its encoder before the first frame. Without it the pacer
+# pushes 24 fps of raw frames into a process that is not reading yet, and the
+# queue oversubscribes before a single frame is consumed.
+_ENCODER_SETTLE_S = 2.0
+
+
+@dataclass(frozen=True)
+class VideoFormat:
+    """Geometry and rate of the paced video stream."""
+
+    width: int
+    height: int
+    fps: int
+
+
+@dataclass(frozen=True)
+class AudioFormat:
+    """Sample layout of the paced audio stream (int16 PCM)."""
+
+    sample_rate: int
+    channels: int
+
+
+class _PipeWriter(threading.Thread):
+    """Feed one ffmpeg input pipe from a bounded queue, off the event loop."""
+
+    def __init__(self, name: str, maxsize: int) -> None:
+        super().__init__(name=f"sink-{name}", daemon=True)
+        self.queue: queue.Queue[tuple[bytes, bytes | None] | None] = queue.Queue(maxsize=maxsize)
+        self.pipe: IO[bytes] | None = None
+        self.metadata_queue: queue.Queue[bytes] | None = None
+        self.broken = threading.Event()
+        self.dropped = 0
+        self._lock = threading.Lock()
+
+    def attach(self, pipe, metadata_queue: queue.Queue[bytes] | None = None) -> None:
+        with self._lock:
+            self.pipe = pipe
+            self.metadata_queue = metadata_queue
+            self.broken.clear()
+
+    def submit(self, payload: bytes, metadata: bytes | None = None) -> int:
+        """Enqueue bytes, dropping the oldest rather than ever blocking.
+
+        Returns how many entries were shed for A/V skew diagnostics. Metadata
+        stays with its payload; discarded frames never enter the muxer ledger.
+        """
+        shed = 0
+        try:
+            self.queue.put_nowait((payload, metadata))
+        except queue.Full:
+            try:
+                self.queue.get_nowait()
+                self.dropped += 1
+                shed += 1
+            except queue.Empty:
+                pass
+            try:
+                self.queue.put_nowait((payload, metadata))
+            except queue.Full:
+                self.dropped += 1
+                shed += 1
+        return shed
+
+    def flush(self) -> None:
+        """Discard everything queued, so a restart resumes both pipes level."""
+        while True:
+            try:
+                self.queue.get_nowait()
+            except queue.Empty:
+                return
+
+    def run(self) -> None:
+        while True:
+            item = self.queue.get()
+            if item is None:  # shutdown sentinel
+                return
+            payload, metadata = item
+            with self._lock:
+                pipe = self.pipe
+                metadata_queue = self.metadata_queue
+            if pipe is None or self.broken.is_set():
+                continue  # ffmpeg is down; discard until it is restarted
+            try:
+                # Unbuffered pipes can return a short write. Every byte must
+                # reach ffmpeg or its raw frame/sample boundaries shift.
+                remaining = memoryview(payload)
+                while remaining:
+                    written = pipe.write(remaining)
+                    if not written:
+                        raise BrokenPipeError("ffmpeg input pipe stopped accepting data")
+                    remaining = remaining[written:]
+                if metadata_queue is not None and metadata is not None:
+                    metadata_queue.put_nowait(metadata)
+            except (BrokenPipeError, OSError, ValueError, queue.Full):
+                # ValueError: write to a closed file during a restart race.
+                with self._lock:
+                    if self.pipe is pipe:
+                        self.broken.set()
+
+    def close(self) -> None:
+        # No producer runs during shutdown. Discard queued media so the
+        # sentinel never waits for a writer blocked inside pipe.write().
+        self.flush()
+        self.queue.put_nowait(None)
+
+
+class HlsSink:
+    """Write the paced stream as an HLS playlist under `directory`."""
+
+    def __init__(self,
+                 directory: str | Path,
+                 video_bitrate_k: int = 4500,
+                 *,
+                 playlist_name: str = "stream.m3u8",
+                 retention_s: int = 120) -> None:
+        if shutil.which("ffmpeg") is None:
+            raise RuntimeError("ffmpeg not found on PATH; install it first")
+        self._directory = Path(directory)
+        self._playlist_name = playlist_name
+        self._bitrate_k = video_bitrate_k
+        if retention_s < SEGMENT_SECONDS * 3:
+            raise ValueError("HLS retention must cover at least three segments")
+        self._retention_s = retention_s
+        self._muxer: MetadataMuxer | None = None
+        self._video: VideoFormat | None = None
+        self._audio: AudioFormat | None = None
+        self._process: subprocess.Popen[bytes] | None = None
+        self._audio_pipe: IO[bytes] | None = None
+        self._video_writer: _PipeWriter | None = None
+        self._audio_writer: _PipeWriter | None = None
+        self._stderr_tail: collections.deque[str] = collections.deque(maxlen=40)
+        self._failures = 0
+        self._last_start_attempt = 0.0
+        self._frames_sent = 0
+        self._dead = False
+        self._video_shed = 0
+        self._audio_shed = 0
+
+    @property
+    def playlist_path(self) -> Path:
+        """Where the web app points the player."""
+        return self._directory / self._playlist_name
+
+    # ------------------------------------------------------------ lifecycle
+
+    async def start(self, video: VideoFormat, audio: AudioFormat) -> None:
+        self._video = video
+        self._audio = audio
+        self._video_writer = _PipeWriter("video", maxsize=int(video.fps * _QUEUE_SECONDS))
+        self._audio_writer = _PipeWriter("audio", maxsize=int(video.fps * _QUEUE_SECONDS))
+        self._video_writer.start()
+        self._audio_writer.start()
+        self._spawn_ffmpeg()
+        # Awaited before the pacer's first tick, so this costs nothing.
+        await asyncio.sleep(_ENCODER_SETTLE_S)
+
+    def _spawn_ffmpeg(self) -> None:
+        assert self._video is not None and self._audio is not None
+        video, audio = self._video, self._audio
+        self._last_start_attempt = time.monotonic()
+
+        self._directory.mkdir(parents=True, exist_ok=True)
+
+        audio_read_fd, audio_write_fd = os.pipe()
+        cmd = [
+            "ffmpeg",
+            "-hide_banner",
+            "-loglevel",
+            "warning",
+            # video in: raw rgb24 on stdin
+            "-f",
+            "rawvideo",
+            "-pix_fmt",
+            "rgb24",
+            "-s",
+            f"{video.width}x{video.height}",
+            "-r",
+            str(video.fps),
+            "-i",
+            "pipe:0",
+            # audio in: raw int16 PCM on an inherited pipe
+            "-f",
+            "s16le",
+            "-ar",
+            str(audio.sample_rate),
+            "-ac",
+            str(audio.channels),
+            "-i",
+            f"pipe:{audio_read_fd}",
+            "-map",
+            "0:v",
+            "-map",
+            "1:a",
+            # Preserve input frame order/count for the metadata ledger.
+            "-fps_mode",
+            "passthrough",
+            "-bf",
+            "0",
+            "-sc_threshold",
+            "0",
+            # video encode
+            "-c:v",
+            "libx264",
+            "-preset",
+            "veryfast",
+            "-tune",
+            "zerolatency",
+            "-pix_fmt",
+            "yuv420p",  # players cannot take 4:4:4
+            "-g",
+            str(video.fps * SEGMENT_SECONDS),  # a keyframe per segment
+            "-b:v",
+            f"{self._bitrate_k}k",
+            "-maxrate",
+            f"{int(self._bitrate_k * 1.2)}k",
+            "-bufsize",
+            f"{self._bitrate_k * 2}k",
+            # audio encode
+            "-c:a",
+            "aac",
+            "-b:a",
+            "128k",
+            "-ar",
+            "44100",
+            "-ac",
+            "2",
+            # A persistent muxer adds timed metadata without re-encoding.
+            "-f",
+            "mpegts",
+            "-muxdelay",
+            "0",
+            "-flush_packets",
+            "1",
+            "pipe:1",
+        ]
+        try:
+            self._process = subprocess.Popen(cmd,
+                                             stdin=subprocess.PIPE,
+                                             stdout=subprocess.PIPE,
+                                             stderr=subprocess.PIPE,
+                                             bufsize=0,
+                                             pass_fds=(audio_read_fd, ))
+        except Exception:
+            os.close(audio_write_fd)
+            raise
+        finally:
+            os.close(audio_read_fd)  # the child inherited its own copy
+
+        audio_pipe = os.fdopen(audio_write_fd, "wb", buffering=0)
+        self._audio_pipe = audio_pipe
+        assert self._video_writer and self._audio_writer
+        # Whatever each queue still held belonged to the dead ffmpeg, and the
+        # two held different amounts; carrying it over starts the new one out
+        # of sync.
+        self._video_writer.flush()
+        self._audio_writer.flush()
+        self._video_shed = self._audio_shed = 0
+        assert self._process.stdout is not None
+        self._muxer = MetadataMuxer(self._process.stdout, self.playlist_path, video.fps, self._retention_s)
+        self._video_writer.attach(self._process.stdin, self._muxer.frames)
+        self._audio_writer.attach(audio_pipe)
+        self._muxer.start()
+
+        threading.Thread(target=self._drain_stderr, args=(self._process, ), daemon=True, name="sink-stderr").start()
+        logger.info("[sink] ffmpeg started: %dx%d@%dfps -> %s", video.width, video.height, video.fps,
+                    self.playlist_path)
+
+    def _drain_stderr(self, process: subprocess.Popen[bytes]) -> None:
+        assert process.stderr is not None
+        with process.stderr:
+            for raw in process.stderr:
+                line = raw.decode(errors="replace").rstrip()
+                if line:
+                    self._stderr_tail.append(line)
+
+    # ----------------------------------------------------------- restarting
+
+    def _ensure_running(self) -> bool:
+        """True when ffmpeg is up; otherwise try to restart it (rate-limited)."""
+        if self._dead:
+            return False
+        process = self._process
+        writers_broken = bool((self._video_writer and self._video_writer.broken.is_set())
+                              or (self._audio_writer and self._audio_writer.broken.is_set()))
+        muxer_finished = self._muxer is not None and self._muxer.finished.is_set()
+        if process is not None and process.poll() is None and not writers_broken and not muxer_finished:
+            return True
+
+        if process is not None and (process.poll() is not None or writers_broken or muxer_finished):
+            tail = "\n".join(list(self._stderr_tail)[-8:])
+            logger.warning("[sink] ffmpeg died (exit=%s)%s", process.poll(), f"\n{tail}" if tail else "")
+            self._teardown_process()
+
+        if time.monotonic() - self._last_start_attempt < _RESTART_COOLDOWN_S:
+            return False
+        try:
+            self._spawn_ffmpeg()
+            self._failures = 0
+            return True
+        except Exception as error:
+            self._failures += 1
+            logger.error("[sink] restart failed (%d/%d): %s", self._failures, _MAX_CONSECUTIVE_FAILURES, error)
+            if self._failures >= _MAX_CONSECUTIVE_FAILURES:
+                logger.error("[sink] giving up; the stream is dead")
+                self._dead = True
+            return False
+
+    def _teardown_process(self) -> None:
+        process, self._process = self._process, None
+        muxer, self._muxer = self._muxer, None
+        if muxer is not None:
+            muxer.cancelled.set()
+        audio_pipe, self._audio_pipe = self._audio_pipe, None
+        if process is None:
+            return
+        # Stop the reader before closing its inputs: a buffered close used
+        # to wait behind a blocked write while ffmpeg was still alive.
+        with contextlib.suppress(ProcessLookupError):
+            process.terminate()
+        # Close the unbuffered inputs now so an encoder waiting for data can
+        # observe EOF and finish. These wrappers have no buffered-write lock;
+        # keeping them also prevents a delayed write from reusing a closed fd.
+        for pipe in (process.stdin, audio_pipe):
+            if pipe is not None:
+                with contextlib.suppress(OSError):
+                    pipe.close()
+        try:
+            process.wait(timeout=_PROCESS_EXIT_TIMEOUT_S)
+        except subprocess.TimeoutExpired:
+            with contextlib.suppress(ProcessLookupError):
+                process.kill()
+            try:
+                process.wait(timeout=_PROCESS_EXIT_TIMEOUT_S)
+            except subprocess.TimeoutExpired:
+                logger.error("[sink] ffmpeg did not exit after SIGKILL")
+
+        if muxer is not None:
+            muxer.join(timeout=_WRITER_EXIT_TIMEOUT_S)
+            if muxer.is_alive():
+                self._dead = True
+                raise RuntimeError("metadata muxer did not stop; refusing concurrent playlist writers")
+        if process.stdout is not None:
+            process.stdout.close()
+
+    # ------------------------------------------------------------- delivery
+
+    def send_video(self, frame: np.ndarray, metadata: bytes = EMPTY_ID3) -> None:
+        if not self._ensure_running():
+            return
+        video = self._video
+        assert video is not None and self._video_writer is not None
+        if frame.shape[0] != video.height or frame.shape[1] != video.width:
+            logger.error("[sink] refusing %sx%s frame (expected %dx%d)", frame.shape[1], frame.shape[0], video.width,
+                         video.height)
+            return
+        if not frame.flags["C_CONTIGUOUS"]:
+            frame = np.ascontiguousarray(frame)
+        self._video_shed += self._video_writer.submit(frame.tobytes(), metadata)
+        self._frames_sent += 1
+        if self._frames_sent % (video.fps * 60) == 0:
+            logger.info(
+                "[sink] %d frames sent (dropped: %d video / %d audio; net A/V skew %+.3fs; "
+                "queue %d)",
+                self._frames_sent,
+                self._video_writer.dropped,
+                self._audio_writer.dropped if self._audio_writer else 0,
+                # What ffmpeg's byte-counted PTS is out by. Zero is the point.
+                (self._video_shed - self._audio_shed) / video.fps,
+                self._video_writer.queue.qsize(),
+            )
+
+    def send_audio(self, samples: np.ndarray) -> None:
+        # Gated exactly like send_video: audio written while video is withheld
+        # would run ahead by that outage once ffmpeg came back.
+        if self._audio_writer is None or not self._ensure_running():
+            return
+        self._audio_shed += self._audio_writer.submit(np.ascontiguousarray(samples, dtype=np.int16).tobytes())
+
+    async def stop(self) -> None:
+        self._dead = True
+        for writer in (self._video_writer, self._audio_writer):
+            if writer:
+                writer.close()
+        await asyncio.to_thread(self._teardown_process)
+        for writer in (self._video_writer, self._audio_writer):
+            if writer is not None and writer.ident is not None:
+                await asyncio.to_thread(writer.join, _WRITER_EXIT_TIMEOUT_S)
+                if writer.is_alive():
+                    logger.warning("[sink] %s did not stop within the shutdown timeout", writer.name)
+        logger.info("[sink] stopped after %d frames", self._frames_sent)
diff --git a/apps/infinite_livestream/infinite_livestream/tests/__init__.py b/apps/infinite_livestream/infinite_livestream/tests/__init__.py
new file mode 100644
index 000000000..e69de29bb
diff --git a/apps/infinite_livestream/infinite_livestream/tests/conftest.py b/apps/infinite_livestream/infinite_livestream/tests/conftest.py
new file mode 100644
index 000000000..aaeed8833
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/conftest.py
@@ -0,0 +1,22 @@
+"""CPU fixtures with placeholder checkpoint paths; no model weights are loaded."""
+
+from dataclasses import replace
+
+import pytest
+
+from infinite_livestream.config import Config, REQUIRED_COMPONENTS
+
+
+@pytest.fixture()
+def app_config(tmp_path, monkeypatch):
+    weights = tmp_path / "weights"
+    weights.mkdir()
+    (weights / "modular_model_index.json").write_text("{}")
+    for component in REQUIRED_COMPONENTS:
+        (weights / component).mkdir()
+    monkeypatch.setenv("OPENAI_API_KEY", "test-key")
+    return replace(
+        Config.load(["--weights", str(weights)]),
+        idle_queue_target=0,
+        hls_dir=str(tmp_path / "hls"),
+    )
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_chat_endpoint.py b/apps/infinite_livestream/infinite_livestream/tests/test_chat_endpoint.py
new file mode 100644
index 000000000..7afb525cc
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_chat_endpoint.py
@@ -0,0 +1,53 @@
+"""POST /chat refuses a rate-limited viewer privately, in their own reply.
+
+The chat feed is shared by every viewer, so a refusal must not go into it: one
+person's rate-limit is not the room's business, and a page full of "not queued"
+lines is noise. The sender learns about it from the status of their own
+request, and their page locks the box until it lifts.
+"""
+
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from infinite_livestream.chat import WebChat
+from infinite_livestream.webapp import DemoWeb
+
+
+@pytest.fixture()
+def web(tmp_path) -> DemoWeb:
+    return DemoWeb(WebChat("!prompt"), tmp_path)
+
+
+def test_a_prompt_is_accepted_and_echoed(web: DemoWeb) -> None:
+    client = TestClient(web.app)
+    assert client.post("/chat", json={"author": "ada", "text": "a lighthouse"}).json() == {"ok": True}
+    assert [(m["kind"], m["author"]) for m in web.state.chat] == [("viewer", "ada")]
+
+
+def test_cooldown_is_refused_with_a_retry_after(web: DemoWeb) -> None:
+    web.cooldown_remaining = lambda author: 4.2 if author == "ada" else 0.0
+    client = TestClient(web.app)
+    response = client.post("/chat", json={"author": "ada", "text": "a lighthouse"})
+    assert response.status_code == 429
+    assert response.json() == {"ok": False, "error": "cooldown", "retry_after": 4.2}
+
+
+def test_a_refused_prompt_never_reaches_the_shared_feed(web: DemoWeb) -> None:
+    web.cooldown_remaining = lambda author: 4.2
+    client = TestClient(web.app)
+    client.post("/chat", json={"author": "ada", "text": "a lighthouse"})
+    assert list(web.state.chat) == [], "the room must not see one viewer's rate-limit"
+
+
+def test_other_viewers_are_unaffected(web: DemoWeb) -> None:
+    web.cooldown_remaining = lambda author: 4.2 if author == "ada" else 0.0
+    client = TestClient(web.app)
+    assert client.post("/chat", json={"author": "ada", "text": "x"}).status_code == 429
+    assert client.post("/chat", json={"author": "grace", "text": "y"}).status_code == 200
+
+
+def test_empty_prompts_are_still_rejected(web: DemoWeb) -> None:
+    client = TestClient(web.app)
+    assert client.post("/chat", json={"author": "ada", "text": "   "}).status_code == 400
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_clip_plan.py b/apps/infinite_livestream/infinite_livestream/tests/test_clip_plan.py
new file mode 100644
index 000000000..9a5206849
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_clip_plan.py
@@ -0,0 +1,86 @@
+"""Clip geometry must match the checkpoint FastVideo actually ships.
+
+`clip_plan` duplicates MiniMax-H3's packing constants instead of importing
+them, because the upstream module pulls in torch and -- through
+fastvideo-kernel's triton autotuning -- needs a live CUDA driver merely to
+import, which would put a GPU in the path of every config test.
+
+Duplication is only safe if something checks it, so that check is here. It
+needs the driver, hence the `gpu` marker: run it whenever the pinned FastVideo
+version moves, not in CI.
+
+The arithmetic tests below need none of that and run anywhere.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from infinite_livestream import clip_plan
+
+
+@pytest.mark.gpu
+def test_constants_match_upstream() -> None:
+    from fastvideo.pipelines.basic.minimax_h3 import packing
+
+    assert clip_plan.FPS == packing.MINIMAX_H3_FPS
+    assert clip_plan._SHORT_EDGE == packing.MINIMAX_H3_SHORT_EDGE
+    assert clip_plan._MAX_PIXELS == packing.MINIMAX_H3_MAX_PIXELS
+    assert clip_plan._CANVAS_MULTIPLE == packing.MINIMAX_H3_CANVAS_MULTIPLE
+    assert clip_plan._MIN_DURATION == packing.MINIMAX_H3_MIN_DURATION
+    assert clip_plan._MAX_DURATION == packing.MINIMAX_H3_MAX_DURATION
+    assert clip_plan._FRAMES_PER_CHUNK == packing.MINIMAX_H3_FRAMES_PER_CHUNK
+    assert clip_plan._LATENTS_PER_CHUNK == packing.MINIMAX_H3_LATENTS_PER_CHUNK
+    assert clip_plan._MIN_ASPECT == packing.MINIMAX_H3_MIN_ASPECT_RATIO
+    assert clip_plan._MAX_ASPECT == packing.MINIMAX_H3_MAX_ASPECT_RATIO
+    # The ceiling is derived rather than a constant, so pin it to upstream's
+    # largest accepted bucket: the cap applies to the aligned frames.
+    assert clip_plan.MAX_FRAMES == packing.MINIMAX_H3_MAX_ALIGNED_FRAMES
+
+
+def test_every_legal_length_round_trips() -> None:
+    """`frames_for_seconds` must land on something the checkpoint can build."""
+    legal = set(clip_plan.legal_frame_counts())
+    assert legal, "the checkpoint must admit at least one clip length"
+    for frames in legal:
+        seconds = clip_plan.seconds_for_frames(frames)
+        assert clip_plan.frames_for_seconds(seconds) == frames
+
+
+def test_published_range_is_generatable() -> None:
+    """Every value a client may legally ask for must snap into range.
+
+    The published bounds are rounded inward precisely so this holds; rounding
+    outward would advertise a length the model then refuses.
+    """
+    for seconds in (
+        clip_plan.MIN_SECONDS_PUBLISHED,
+        clip_plan.MAX_SECONDS_PUBLISHED,
+        (clip_plan.MIN_SECONDS_PUBLISHED + clip_plan.MAX_SECONDS_PUBLISHED) / 2,
+    ):
+        frames = clip_plan.frames_for_seconds(seconds)
+        assert frames in clip_plan.legal_frame_counts()
+
+
+def test_max_frames_respects_the_duration_cap() -> None:
+    """The ceiling is the subtle one: the cap applies to the aligned bucket."""
+    assert clip_plan.MAX_FRAMES == 362
+    assert clip_plan.seconds_for_frames(clip_plan.MAX_FRAMES) > clip_plan._MAX_DURATION
+    assert clip_plan.align_frames(clip_plan.MAX_FRAMES + 1) / clip_plan.FPS > clip_plan._MAX_DURATION
+
+
+def test_canvases_land_on_the_multiple_and_under_the_area_cap() -> None:
+    for aspect in clip_plan.ASPECT_CHOICES:
+        height, width = clip_plan.canvas_for_choice(aspect)
+        assert height % clip_plan._CANVAS_MULTIPLE == 0
+        assert width % clip_plan._CANVAS_MULTIPLE == 0
+        assert height * width <= clip_plan._MAX_PIXELS
+
+
+def test_illegal_aspects_are_refused() -> None:
+    with pytest.raises(ValueError):
+        clip_plan.canvas_for_aspect(5, 1)      # past the 4:1 cap
+    with pytest.raises(ValueError):
+        clip_plan.canvas_for_aspect(0, 1)
+    with pytest.raises(ValueError):
+        clip_plan.canvas_for_choice("21:9")    # not an offered choice
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_config.py b/apps/infinite_livestream/infinite_livestream/tests/test_config.py
new file mode 100644
index 000000000..6fb0d666b
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_config.py
@@ -0,0 +1,156 @@
+"""Reading the config file and the environment.
+
+This is the app's entry surface: everything downstream takes a `Config`, and a
+mistake here is a deployment that starts with settings nobody asked for. The
+split matters too, so it is asserted rather than assumed: settings come from
+the YAML, secrets come from the environment, and neither leaks into the other.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import subprocess
+import sys
+import textwrap
+
+import pytest
+
+from infinite_livestream.config import Config, PresetError, load_model_config, load_preset
+
+
+@pytest.fixture()
+def workspace(tmp_path, monkeypatch):
+    """A config file, a fillers directory, and the two required secrets."""
+    fillers = tmp_path / "fillers"
+    fillers.mkdir()
+    (fillers / "fillers.json").write_text(
+        json.dumps({"style": "house style", "idle_prompts": ["a lighthouse", "a seagull"]}))
+    config = tmp_path / "infinite_livestream.yaml"
+    config.write_text(
+        textwrap.dedent(f"""
+        inference:
+          aspect: "16:9"
+          clip_seconds: 14.375
+        runtime:
+          num_gpus: 4
+        upsampler:
+          model: my-model
+          base_url: https://example.invalid/v1
+          max_chunks: 3
+          viewer_free_style: false
+        moderation:
+          enabled: false
+        director:
+          idle_queue_target: 2
+          chat_cooldown_s: 7
+          chat_command: "!go"
+          fillers: {fillers}
+        output:
+          hls_dir: /tmp/hls-under-test
+          video_bitrate_k: 1234
+        web:
+          host: 127.0.0.1
+          port: 9999
+        """))
+    monkeypatch.setenv("LIVESTREAM_WEIGHTS_PATH", str(tmp_path / "weights"))
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    monkeypatch.delenv("MODERATION_API_KEY", raising=False)
+    return config
+
+
+def test_every_block_reaches_the_config(workspace) -> None:
+    config = Config.load(["--config", str(workspace)])
+    assert config.openai_model == "my-model"
+    assert config.openai_base_url == "https://example.invalid/v1"
+    assert config.max_chunks == 3
+    assert config.viewer_free_style is False
+    assert config.moderation_enabled is False
+    assert config.idle_queue_target == 2
+    assert config.chat_cooldown_s == 7
+    assert config.chat_command == "!go"
+    assert config.hls_dir == "/tmp/hls-under-test"
+    assert config.video_bitrate_k == 1234
+    assert config.web_host == "127.0.0.1"
+    assert config.web_port == 9999
+    assert config.style == "house style"
+    assert config.idle_prompts == ("a lighthouse", "a seagull")
+
+
+def test_secrets_come_only_from_the_environment(workspace) -> None:
+    """A key in a version-controlled file is a key that leaks."""
+    assert "OPENAI_API_KEY" not in workspace.read_text()
+    config = Config.load(["--config", str(workspace)])
+    assert config.openai_api_key == "sk-test"
+    # Moderation falls back to the upsampling credentials, which is right when
+    # one endpoint serves both.
+    assert config.moderation_api_key == "sk-test"
+
+
+def test_cli_overrides_win(workspace, tmp_path) -> None:
+    config = Config.load(["--config", str(workspace), "--port", "4321", "--weights", str(tmp_path / "elsewhere")])
+    assert config.web_port == 4321
+    assert config.weights_path.name == "elsewhere"
+
+
+def test_a_missing_key_stops_startup(workspace, monkeypatch) -> None:
+    """Rewriting runs for the idle filler too, so there is no useful run without it."""
+    monkeypatch.delenv("OPENAI_API_KEY")
+    with pytest.raises(SystemExit, match="OPENAI_API_KEY"):
+        Config.load(["--config", str(workspace)])
+
+
+def test_missing_weights_stops_startup(workspace, monkeypatch) -> None:
+    monkeypatch.delenv("LIVESTREAM_WEIGHTS_PATH")
+    with pytest.raises(SystemExit, match="LIVESTREAM_WEIGHTS_PATH"):
+        Config.load(["--config", str(workspace)])
+
+
+def test_a_missing_config_file_is_named(tmp_path) -> None:
+    with pytest.raises(SystemExit, match="config not found"):
+        Config.load(["--config", str(tmp_path / "nope.yaml")])
+
+
+def test_defaults_apply_when_a_block_is_absent(tmp_path, monkeypatch) -> None:
+    """An operator writing a minimal file must still get a working deployment."""
+    config_file = tmp_path / "minimal.yaml"
+    config_file.write_text("inference:\n  aspect: \"16:9\"\nruntime:\n  num_gpus: 4\n")
+    monkeypatch.setenv("LIVESTREAM_WEIGHTS_PATH", str(tmp_path))
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    config = Config.load(["--config", str(config_file)])
+    assert config.web_port == 8081
+    assert config.chat_cooldown_s == 10
+    assert config.idle_prompts, "the shipped fillers should be used when none is named"
+
+
+def test_model_config_reads_the_same_file(workspace) -> None:
+    model = load_model_config(workspace)
+    assert model.aspect == "16:9"
+    assert model.clip_frames == 345
+    assert model.runtime["num_gpus"] == 4
+
+
+def test_a_fillers_directory_without_the_file_is_named(tmp_path) -> None:
+    with pytest.raises(PresetError, match="fillers.json"):
+        load_preset(tmp_path)
+
+
+def test_the_playlist_default_is_not_the_working_directory(tmp_path, monkeypatch) -> None:
+    """A relative default would scatter .ts segments wherever the server started."""
+    config_file = tmp_path / "minimal.yaml"
+    config_file.write_text("inference:\n  aspect: \"16:9\"\nruntime:\n  num_gpus: 4\n")
+    monkeypatch.setenv("LIVESTREAM_WEIGHTS_PATH", str(tmp_path))
+    monkeypatch.setenv("OPENAI_API_KEY", "sk-test")
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state"))
+    # This default is read at import time. A subprocess avoids replacing the
+    # parent's config classes or leaving its default tied to this fixture.
+    result = subprocess.run(
+        [sys.executable, "-c", "from infinite_livestream.config import Config; print(Config.load().hls_dir)",
+         "--config", str(config_file)],
+        cwd=Path(__file__).resolve().parents[2],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    hls_dir = result.stdout.strip()
+    assert hls_dir.startswith(str(tmp_path / "state")), hls_dir
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_director_admission.py b/apps/infinite_livestream/infinite_livestream/tests/test_director_admission.py
new file mode 100644
index 000000000..c5cc4b2fd
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_director_admission.py
@@ -0,0 +1,155 @@
+"""Whether a viewer's prompt survives, and whether they are told when it does not.
+
+This path had no tests, which is how a silent drop reached a live stream: the
+web app answers the POST with `ok` and echoes the prompt into chat, then the
+director -- downstream of that acknowledgement -- can still refuse it. Anything
+that refuses here has to report back, or the viewer watches their request
+appear and then vanish.
+
+No GPU, no network: the engine, upsampler and moderator are stubs, because what
+is under test is the admission decision, not what happens after it.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any, cast
+
+import pytest
+
+from infinite_livestream.chat import ChatPrompt
+from infinite_livestream.director import Director
+
+
+class FakeEngine:
+    """Just enough of `Engine` for the director's capacity checks."""
+
+    def __init__(self, playout_capacity: int = 10) -> None:
+        self.generation_clips: list[dict] = []
+        self.playout_clips: list[dict] = []
+        self.playout_capacity = playout_capacity
+        self.generation_capacity = 20
+        self.playout_queued = 0
+        self.generation_queued = 0
+        self.min_seconds, self.max_seconds = 5.167, 14.375
+        self.connected = True
+        self.commands: list[tuple[str, dict]] = []
+
+    def add_listener(self, listener) -> None:
+        pass
+
+    async def send_command(self, command: str, data: dict):
+        self.commands.append((command, data))
+        return {"clip": {"clip_id": "x" * 12, "seconds": 14.4, "seed": 1}}
+
+
+class FakeModerator:
+    enabled = True
+
+    def __init__(self, verdict: str | None = None) -> None:
+        self.verdict = verdict
+
+    async def review(self, text: str) -> str | None:
+        return self.verdict
+
+
+def make_director(rejections: list[tuple[str, str]], *, cooldown_s: float = 10.0,
+                  engine: FakeEngine | None = None, moderator: FakeModerator | None = None) -> Director:
+    # Deliberate test doubles: what is under test is the admission decision,
+    # which touches none of the real collaborators' behaviour.
+    return Director(
+        cast("Any", engine or FakeEngine()),
+        upsampler=cast("Any", None),
+        moderator=cast("Any", moderator or FakeModerator()),
+        cooldown_s=cooldown_s,
+        idle_prompts=(),
+        idle_queue_target=0,
+        on_reject=lambda author, reason: rejections.append((author, reason)),
+    )
+
+
+def prompt(author: str = "ada", text: str = "a lighthouse keeper") -> ChatPrompt:
+    return ChatPrompt(source="web", author=author, text=text, command="!prompt")
+
+
+def test_first_prompt_is_accepted() -> None:
+    rejections: list[tuple[str, str]] = []
+    director = make_director(rejections)
+    director.submit(prompt())
+    assert rejections == []
+    assert director._pending.qsize() == 1
+
+
+def test_cooldown_drop_is_reported_to_the_viewer() -> None:
+    """The bug that reached production: accepted, echoed, then silently gone."""
+    rejections: list[tuple[str, str]] = []
+    director = make_director(rejections, cooldown_s=30.0)
+    director.submit(prompt())
+    director.submit(prompt())
+    assert director._pending.qsize() == 1, "the second must not be queued"
+    assert len(rejections) == 1, "and the viewer must be told"
+    author, reason = rejections[0]
+    assert author == "ada"
+    assert "s left" in reason, f"the reason should say how long to wait, got {reason!r}"
+
+
+def test_cooldown_is_per_author() -> None:
+    """Two people must not silence each other."""
+    rejections: list[tuple[str, str]] = []
+    director = make_director(rejections, cooldown_s=30.0)
+    director.submit(prompt(author="ada"))
+    director.submit(prompt(author="grace"))
+    assert rejections == []
+    assert director._pending.qsize() == 2
+
+
+def test_backlog_full_is_reported() -> None:
+    rejections: list[tuple[str, str]] = []
+    director = make_director(rejections, cooldown_s=0.0)
+    for i in range(64):
+        director.submit(prompt(author=f"viewer{i}"))
+    assert rejections, "a full backlog must be reported, not swallowed"
+    assert any("backlog" in reason for _, reason in rejections)
+
+
+def test_moderation_rejection_is_reported() -> None:
+    rejections: list[tuple[str, str]] = []
+    director = make_director(rejections, moderator=FakeModerator(verdict="flagged: violence"))
+    director.submit(prompt())
+    asyncio.run(_drain_once(director))
+    assert rejections == [("ada", "flagged: violence")]
+
+
+def test_viewer_budget_full_is_reported() -> None:
+    """A queue already full of viewer content refuses more, and says so."""
+    rejections: list[tuple[str, str]] = []
+    engine = FakeEngine(playout_capacity=2)
+    engine.playout_clips = [{"metadata": "{}", "clip_id": "a"}, {"metadata": "{}", "clip_id": "b"}]
+    director = make_director(rejections, engine=engine)
+    director.submit(prompt())
+    asyncio.run(_drain_once(director))
+    assert rejections and "already queued" in rejections[0][1]
+
+
+async def _drain_once(director: Director) -> None:
+    """Run the prompt loop just long enough to process what is pending."""
+    task = asyncio.create_task(director.run())
+    for _ in range(50):
+        await asyncio.sleep(0)
+        if director._pending.empty():
+            break
+    await asyncio.sleep(0)
+    task.cancel()
+    with pytest.raises(asyncio.CancelledError):
+        await task
+
+
+def test_cooldown_remaining_reports_the_wait() -> None:
+    """The web app asks this before accepting, so a rate-limited viewer is
+    stopped in their own browser rather than announced to the shared feed."""
+    director = make_director([], cooldown_s=30.0)
+    assert director.cooldown_remaining("ada") == 0.0
+    director.submit(prompt(author="ada"))
+    remaining = director.cooldown_remaining("ada")
+    assert 25.0 < remaining <= 30.0
+    assert director.cooldown_remaining("grace") == 0.0, "and it is per author"
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_frame_metadata.py b/apps/infinite_livestream/infinite_livestream/tests/test_frame_metadata.py
new file mode 100644
index 000000000..82168740b
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_frame_metadata.py
@@ -0,0 +1,126 @@
+"""Frame ownership must survive buffering, repetition, short writes, and drops."""
+
+import asyncio
+import queue
+import threading
+
+import numpy as np
+import pytest
+
+from infinite_livestream.metadata import encode_id3
+from infinite_livestream.pacer import Pacer
+from infinite_livestream.sink import AudioFormat, VideoFormat, _PipeWriter
+
+
+def test_pacer_repeats_and_drops_identity_with_its_frame(monkeypatch):
+    from infinite_livestream import pacer as module
+    monkeypatch.setattr(module, "_BUFFER_SECONDS", 2 / 24)
+    displayed = []
+
+    class Sink:
+        async def start(self, *args):
+            pass
+
+        def send_video(self, frame, metadata):
+            displayed.append((int(frame[0, 0, 0]), metadata))
+            if len(displayed) == 4:
+                raise asyncio.CancelledError
+
+        def send_audio(self, samples):
+            pass
+
+    pacer = Pacer(Sink(), VideoFormat(2, 2, 24), AudioFormat(48000, 1))
+    for value in (1, 2, 3):
+        pacer.submit_video(np.full((2, 2, 3), value, dtype=np.uint8), str(value).encode())
+    with pytest.raises(asyncio.CancelledError):
+        asyncio.run(pacer.run())
+    assert displayed == [(2, b"2"), (3, b"3"), (3, b"3"), (3, b"3")]
+    assert pacer.dropped_frames == 1
+
+
+def test_writer_commits_only_the_surviving_complete_frame():
+    ledger = queue.Queue()
+    written = bytearray()
+
+    class ShortPipe:
+        def write(self, data):
+            # No record may be visible while any bytes remain unwritten.
+            assert ledger.empty()
+            written.extend(data[:2])
+            return min(2, len(data))
+
+    writer = _PipeWriter("metadata-test", 1)
+    writer.attach(ShortPipe(), ledger)
+    writer.submit(b"discarded", b"old-title")
+    assert writer.submit(b"kept frame", b"new-title") == 1
+    writer.start()
+    try:
+        assert ledger.get(timeout=2) == b"new-title"
+        assert written == b"kept frame"
+        assert ledger.empty()
+    finally:
+        writer.close()
+        writer.join(timeout=2)
+
+
+def test_partial_frame_failure_never_commits_a_title():
+    ledger = queue.Queue()
+
+    class BrokenPipe:
+        first = True
+
+        def write(self, data):
+            if self.first:
+                self.first = False
+                return 1
+            raise BrokenPipeError
+
+    writer = _PipeWriter("broken-metadata-test", 1)
+    writer.attach(BrokenPipe(), ledger)
+    writer.start()
+    try:
+        writer.submit(b"incomplete", b"must not appear")
+        assert writer.broken.wait(2)
+        assert ledger.empty()
+    finally:
+        writer.close()
+        writer.join(timeout=2)
+
+
+def test_replaced_encoder_cannot_receive_the_previous_writes_title():
+    entered, release = threading.Event(), threading.Event()
+    old_ledger, new_ledger = queue.Queue(), queue.Queue()
+
+    class OldPipe:
+        def write(self, data):
+            entered.set()
+            assert release.wait(2)
+            return len(data)
+
+    class NewPipe:
+        def write(self, data):
+            return len(data)
+
+    writer = _PipeWriter("restart-metadata-test", 2)
+    writer.attach(OldPipe(), old_ledger)
+    writer.start()
+    try:
+        writer.submit(b"old frame", b"old title")
+        assert entered.wait(2)
+        writer.attach(NewPipe(), new_ledger)
+        writer.submit(b"new frame", b"new title")
+        release.set()
+        assert old_ledger.get(timeout=2) == b"old title"
+        assert new_ledger.get(timeout=2) == b"new title"
+        assert old_ledger.empty() and new_ledger.empty()
+    finally:
+        release.set()
+        writer.close()
+        writer.join(timeout=2)
+
+
+def test_title_encoding_preserves_unicode_and_explicit_black_state():
+    # UTF-8 text must survive as data, including characters meaningful in HTML.
+    value = {"clip_id": "a", "title": "猫 <script> & café"}
+    assert "猫 <script> & café".encode() in encode_id3(value)
+    assert b'"clip":null' in encode_id3(None)
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_hls_metadata.py b/apps/infinite_livestream/infinite_livestream/tests/test_hls_metadata.py
new file mode 100644
index 000000000..23aa102bd
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_hls_metadata.py
@@ -0,0 +1,136 @@
+"""Exercise real FFmpeg/PyAV packets on CPU; no model or API keys are needed."""
+
+import json
+import shutil
+import subprocess
+from fractions import Fraction
+
+import av
+import pytest
+
+from infinite_livestream.metadata import clip_view, encode_id3
+from infinite_livestream.muxer import MetadataMuxer
+
+
+def descriptor(name):
+    return clip_view({"clip_id": name, "prompt": name})
+
+
+def read_record(raw):
+    # Parse the TXXX UTF-8 value independently of the production serializer.
+    assert raw[:3] == b"ID3" and raw[10:14] == b"TXXX" and raw[20] == 3
+    description, value = raw[21:].split(b"\x00", 1)
+    assert description == b"infinite-livestream"
+    return json.loads(value)
+
+
+@pytest.fixture()
+def encoded_source(tmp_path):
+    if not shutil.which("ffmpeg"):
+        pytest.skip("FFmpeg with libx264/AAC is required for the CPU media integration test")
+    source = tmp_path / "source.ts"
+    subprocess.run([
+        "ffmpeg", "-v", "error", "-f", "lavfi", "-i",
+        "color=red:s=160x96:r=24:d=1.125[a];color=green:s=160x96:r=24:d=1.5[b];"
+        "color=blue:s=160x96:r=24:d=3.375[c];[a][b][c]concat=n=3:v=1:a=0",
+        "-f", "lavfi", "-i", "anullsrc=r=48000:cl=mono", "-t", "6",
+        "-c:v", "libx264", "-preset", "ultrafast", "-tune", "zerolatency",
+        "-g", "48", "-sc_threshold", "0", "-bf", "0", "-c:a", "aac",
+        "-f", "mpegts", str(source),
+    ], check=True, capture_output=True, timeout=20)
+    return source
+
+
+def run_mux(source, playlist, prefix=""):
+    with source.open("rb") as stream:
+        muxer = MetadataMuxer(stream, playlist, 24, 120)
+        for frame in range(144):
+            name = "A" if frame < 27 else "B" if frame < 63 else "C"
+            muxer.frames.put_nowait(encode_id3(descriptor(prefix + name)))
+        muxer._mux()
+        assert muxer.frames.empty()
+        return muxer
+
+
+def segment_paths(playlist):
+    return [playlist.parent / line for line in playlist.read_text().splitlines()
+            if line and not line.startswith("#")]
+
+
+def media_packets(paths):
+    result = {"video": [], "audio": []}
+    for path in paths:
+        with av.open(str(path)) as media:
+            for packet in media.demux():
+                if packet.dts is not None and packet.stream.type in result:
+                    result[packet.stream.type].append((packet.pts * packet.time_base,
+                                                       packet.dts * packet.time_base, bytes(packet)))
+    return result
+
+
+def test_metadata_matches_decoded_frames_and_every_segment_start(encoded_source, tmp_path):
+    playlist = tmp_path / "stream.m3u8"
+    run_mux(encoded_source, playlist)
+    segments = segment_paths(playlist)
+    assert len(segments) == 3
+    # No second encode, no retiming, no lost video/audio packets.
+    assert media_packets(segments) == media_packets([encoded_source])
+    transitions = []
+    for path in segments:
+        cues = []
+        with av.open(str(path)) as media:
+            for packet in media.demux():
+                if packet.stream.type == "data" and packet.pts is not None:
+                    cues.append((packet.pts * packet.time_base, read_record(bytes(packet))["clip"]["clip_id"]))
+        with av.open(str(path)) as media:
+            frames = list(media.decode(video=0))
+        assert cues[0][0] == frames[0].pts * frames[0].time_base
+        for frame in frames:
+            at = frame.pts * frame.time_base
+            title = [name for pts, name in cues if pts <= at][-1]
+            # The generated color is an independent oracle for clip identity.
+            rgb = frame.to_ndarray(format="rgb24").mean(axis=(0, 1))
+            assert title == "ABC"[int(rgb.argmax())]
+        transitions.extend(cues)
+    first = transitions[0][0]
+    assert (first + Fraction(27, 24), "B") in transitions
+    assert (first + Fraction(63, 24), "C") in transitions
+
+
+def test_restart_keeps_old_segments_and_marks_the_new_timeline(encoded_source, tmp_path):
+    playlist = tmp_path / "stream.m3u8"
+    first = run_mux(encoded_source, playlist)
+    old_segments = segment_paths(playlist)
+    old_bytes = [p.read_bytes() for p in old_segments]
+    second = run_mux(encoded_source, playlist, prefix="restart-")
+    segments = segment_paths(playlist)
+    assert len(segments) == 6
+    assert first.epoch != second.epoch
+    assert segments[:3] == old_segments
+    assert [p.read_bytes() for p in old_segments] == old_bytes
+    text = playlist.read_text()
+    assert "#EXT-X-DISCONTINUITY\n" + "#EXTINF" in text
+    assert len({p.name for p in segments}) == 6
+    for path in segments[3:]:
+        with av.open(str(path)) as media:
+            packet = next(p for p in media.demux() if p.stream.type == "data" and p.pts is not None)
+            assert read_record(bytes(packet))["clip"]["clip_id"].startswith("restart-")
+
+
+def test_cleanup_preserves_listed_history_and_removes_expired_orphans(tmp_path):
+    import os
+    import time
+    playlist = tmp_path / "stream.m3u8"
+    listed = tmp_path / "seg_previous_01.ts"
+    orphan = tmp_path / "seg_previous_02.ts"
+    recent = tmp_path / "seg_previous_03.ts"
+    for p in (listed, orphan, recent):
+        p.write_bytes(b"media")
+    playlist.write_text("#EXTM3U\n#EXTINF:2,\n" + listed.name + "\n")
+    for p in (listed, orphan):
+        os.utime(p, (time.time() - 300, time.time() - 300))
+    with listed.open("rb") as source:
+        muxer = MetadataMuxer(source, playlist, 24, 120)
+        muxer._cleanup()
+    assert listed.exists() and recent.exists()
+    assert not orphan.exists()
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_import_contract.py b/apps/infinite_livestream/infinite_livestream/tests/test_import_contract.py
new file mode 100644
index 000000000..cc0f7b896
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_import_contract.py
@@ -0,0 +1,99 @@
+"""The app depends on FastVideo and nothing else that serves models.
+
+This app began as a port of a deployment built on the Reactor runtime, whose
+serve process, RPC decorators and wire schema it no longer uses -- the model
+and the broadcast run in one process now. That is easy to regress by copying
+one more module across, so the contract is a test: no `reactor_*` import may
+reappear, and the modules that must stay importable without a GPU must stay
+importable without a GPU.
+"""
+
+from __future__ import annotations
+
+import ast
+import pathlib
+
+import pytest
+
+PACKAGE = pathlib.Path(__file__).resolve().parents[1]
+
+# Modules that must import with no torch, no fastvideo and no GPU: the config
+# and queue logic is pure Python so it can be tested anywhere, and the entry
+# point has to be able to print a dependency error rather than raise one.
+CPU_ONLY_MODULES = (
+    "infinite_livestream.clip_plan",
+    "infinite_livestream.clip_queue",
+    "infinite_livestream.config",
+    "infinite_livestream.group_tag",
+)
+
+
+def _module_files() -> list[pathlib.Path]:
+    return sorted(p for p in PACKAGE.rglob("*.py") if "tests" not in p.parts)
+
+
+def _imported_names(path: pathlib.Path) -> set[str]:
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    names: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            names.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module and node.level == 0:
+            names.add(node.module)
+    return names
+
+
+@pytest.mark.parametrize("path", _module_files(), ids=lambda p: p.name)
+def test_no_reactor_imports(path: pathlib.Path) -> None:
+    offenders = {name for name in _imported_names(path) if name.split(".")[0].startswith("reactor")}
+    assert not offenders, f"{path.name} imports {sorted(offenders)}"
+
+
+@pytest.mark.parametrize("module", CPU_ONLY_MODULES)
+def test_imports_without_a_gpu(module: str) -> None:
+    """These must not drag torch or fastvideo in as a side effect.
+
+    Run in a fresh interpreter, because "did importing X pull in torch" is a
+    question about ``sys.modules``, which is global: any earlier test that
+    imported fastvideo would make this pass or fail for reasons that have
+    nothing to do with the module under test. A subprocess is the only honest
+    way to ask it.
+    """
+    import subprocess
+    import sys
+
+    probe = (
+        f"import {module}, sys; "
+        "leaked = [m for m in ('torch', 'fastvideo') if m in sys.modules]; "
+        "print(','.join(leaked))"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", probe],
+        capture_output=True,
+        text=True,
+        cwd=PACKAGE.parent,
+    )
+    assert result.returncode == 0, f"{module} failed to import:\n{result.stderr}"
+    leaked = result.stdout.strip()
+    assert not leaked, f"{module} imported {leaked} at module level"
+
+
+def test_backend_defers_heavy_imports() -> None:
+    """backend.py names fastvideo only inside functions.
+
+    Module-level would make the config tests, and the entry point's dependency
+    message, need a GPU.
+    """
+    tree = ast.parse((PACKAGE / "backend.py").read_text(encoding="utf-8"))
+    top_level = {
+        alias.name
+        for node in tree.body
+        if isinstance(node, ast.Import)
+        for alias in node.names
+    } | {
+        node.module
+        for node in tree.body
+        if isinstance(node, ast.ImportFrom) and node.module and node.level == 0
+    }
+    heavy = {name for name in top_level if name.split(".")[0] in {"torch", "torchaudio", "fastvideo"}}
+    assert not heavy, f"backend.py imports {sorted(heavy)} at module level"
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_metadata_player.cjs b/apps/infinite_livestream/infinite_livestream/tests/test_metadata_player.cjs
new file mode 100644
index 000000000..dfdf6758e
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_metadata_player.cjs
@@ -0,0 +1,219 @@
+// Adapter regressions; actual cue timing is owned by the browser/player.
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+require('../web/metadata.js');
+
+class Track extends EventTarget {
+  kind = 'metadata';
+  mode = 'disabled';
+  activeCues = [];
+  activate(cues) {
+    this.activeCues = cues;
+    this.dispatchEvent(new Event('cuechange'));
+  }
+}
+class TrackList extends EventTarget {
+  items = [];
+  [Symbol.iterator]() { return this.items[Symbol.iterator](); }
+  add(track) {
+    if (!this.items.includes(track)) this.items.push(track);
+    const event = new Event('addtrack');
+    event.track = track;
+    this.dispatchEvent(event);
+  }
+}
+class Video extends EventTarget {
+  readyState = 2;
+  textTracks = new TrackList();
+}
+function cue(name, startTime = 0, native = false) {
+  const clip = name === null ? null : { clip_id: name, title: name, prompt: name, generated: false };
+  const value = { key: 'TXXX', data: JSON.stringify({ version: 1, clip }) };
+  if (!native) value.info = 'infinite-livestream';
+  return { startTime, endTime: Infinity, value };
+}
+function player() {
+  const video = new Video();
+  const track = new Track();
+  video.textTracks.add(track);
+  const shown = [];
+  const stop = LivestreamMetadata.watch(video, clip => shown.push(clip?.clip_id ?? clip));
+  return { video, track, shown, stop };
+}
+
+test('downloaded future cues do not advance the title; activation does', () => {
+  const p = player();
+  assert.equal(p.track.mode, 'hidden');
+  const a = cue('A');
+  const b = cue('B', 10);
+  p.track.activate([a]);
+  p.track.cues = [a, b]; // The next segment arrived, but it is not playing.
+  p.video.dispatchEvent(new Event('loadeddata'));
+  assert.deepEqual(p.shown, [undefined, 'A']);
+  p.track.activate([b]);
+  assert.deepEqual(p.shown, [undefined, 'A', 'B']);
+  p.stop();
+});
+
+test('viewers keep independent titles during stalls and seeks', () => {
+  const live = player();
+  const delayed = player();
+  live.track.activate([cue('C', 20)]);
+  delayed.track.activate([cue('A', 0)]);
+  delayed.video.dispatchEvent(new Event('waiting'));
+  live.track.activate([cue('D', 30)]);
+  assert.equal(delayed.shown.at(-1), 'A');
+  delayed.track.activate([cue('B', 10)]);
+  delayed.video.dispatchEvent(new Event('seeked'));
+  assert.equal(delayed.shown.at(-1), 'B');
+  assert.equal(live.shown.at(-1), 'D');
+  delayed.track.activate([cue('A')]); // Seek backwards.
+  assert.equal(delayed.shown.at(-1), 'A');
+  live.stop(); delayed.stop();
+});
+
+test('joining mid-clip and repeated segment markers do not need prior events', () => {
+  const video = new Video();
+  const shown = [];
+  const stop = LivestreamMetadata.watch(video, clip => shown.push(clip?.clip_id ?? clip));
+  const track = new Track();
+  track.activeCues = [cue('B', 14)];
+  video.textTracks.add(track);
+  track.activate([cue('B', 16)]);
+  video.textTracks.add(track); // hls.js may reuse a track across attachments.
+  assert.deepEqual(shown, [undefined, 'B']);
+  stop();
+});
+
+test('native overlapping cues pick the latest record, including black frames', () => {
+  const p = player();
+  p.track.activate([cue('B', 10, true), cue('A', 0, true)]);
+  assert.equal(p.shown.at(-1), 'B');
+  p.track.activate([cue('A', 0, true), cue(null, 20, true), cue('B', 10, true)]);
+  assert.equal(p.shown.at(-1), null);
+  p.stop();
+});
+
+test('invalid and unrelated ID3 cannot replace a valid title', () => {
+  const p = player();
+  const good = cue('猫 <script> & café', 1);
+  const unrelated = cue('wrong', 10);
+  unrelated.value.info = 'another-application';
+  p.track.activate([good, unrelated, { startTime: 20, value: { key: 'TXXX', data: 'invalid' } }]);
+  assert.equal(p.shown.at(-1), '猫 <script> & café');
+  const fallback = cue('text-fallback', 30);
+  fallback.text = JSON.stringify(fallback.value);
+  delete fallback.value;
+  p.track.activate([fallback]);
+  assert.equal(p.shown.at(-1), 'text-fallback');
+  p.stop();
+});
+
+test('loading and teardown clear stale titles and detach old listeners', () => {
+  const p = player();
+  p.track.activate([cue('A')]);
+  p.video.readyState = 0;
+  p.video.dispatchEvent(new Event('emptied'));
+  p.track.activate([cue('B')]);
+  assert.equal(p.shown.at(-1), undefined);
+  p.video.readyState = 2;
+  p.video.dispatchEvent(new Event('loadeddata'));
+  assert.equal(p.shown.at(-1), 'B');
+  p.stop();
+  p.track.activate([cue('C')]);
+  p.video.textTracks.add(new Track());
+  p.video.dispatchEvent(new Event('emptied'));
+  assert.equal(p.shown.at(-1), 'B');
+});
+
+
+test('presented frames resolve paused seeks before segment PTS without guessing', () => {
+  const video = new Video();
+  let callback;
+  let cancelled = false;
+  video.requestVideoFrameCallback = fn => { callback = fn; return 1; };
+  video.cancelVideoFrameCallback = id => { assert.equal(id, 1); cancelled = true; };
+  const track = new Track();
+  video.textTracks.add(track);
+  const shown = [];
+  const stop = LivestreamMetadata.watch(video, clip => shown.push(clip?.clip_id ?? clip));
+  const a = cue('A', 2.021333333333333);
+  const b = cue('B', 12.021333333333333);
+  a.endTime = b.startTime;
+  track.cues = [a, b];
+  track.activate([a]);
+  callback(0, { mediaTime: 3 });
+  assert.equal(shown.at(-1), 'A');
+  // Observed Firefox case: currentTime=12, active cue A, but displayed frame B.
+  video.currentTime = 12;
+  callback(0, { mediaTime: 12.021333 });
+  assert.equal(shown.at(-1), 'B');
+  track.activate([a]);
+  assert.equal(shown.at(-1), 'B');
+  // A future download and a stall do not move the presented frame.
+  track.cues.push(cue('C', 20));
+  video.dispatchEvent(new Event('waiting'));
+  assert.equal(shown.at(-1), 'B');
+  callback(0, { mediaTime: 3 });
+  assert.equal(shown.at(-1), 'A');
+  // A paused seek may have no frame callback: resume standard cue scheduling.
+  track.activate([b]);
+  video.dispatchEvent(new Event('seeked'));
+  assert.equal(shown.at(-1), 'B');
+  video.dispatchEvent(new Event('emptied'));
+  assert.equal(shown.at(-1), undefined);
+  stop();
+  assert.equal(cancelled, true);
+});
+
+
+test('a browser advertising native HLS still uses the metadata-capable hls.js path', () => {
+  const fs = require('node:fs');
+  const vm = require('node:vm');
+  const html = fs.readFileSync(require.resolve('../web/index.html'), 'utf8');
+  const source = html.slice(html.indexOf('function startPlayback()'), html.indexOf('video.addEventListener("error"'));
+  let loaded;
+  let attached;
+  class Hls {
+    static isSupported() { return true; }
+    static Events = { ERROR: 'error' };
+    on() {}
+    loadSource(url) { loaded = url; }
+    attachMedia(video) { attached = video; }
+  }
+  const video = { canPlayType: () => 'probably' };
+  const context = vm.createContext({
+    Hls, window: { Hls }, video, PLAYLIST: '/hls/stream.m3u8',
+    LivestreamMetadata: { watch: () => () => {} }, renderPlayback() {},
+  });
+  vm.runInContext(source + '\nstartPlayback();', context);
+  assert.equal(loaded, '/hls/stream.m3u8');
+  assert.equal(attached, video);
+  assert.equal(video.src, undefined);
+  // Preserve native-only devices when Media Source playback is unavailable.
+  Hls.isSupported = () => false;
+  loaded = undefined;
+  vm.runInContext('startPlayback();', context);
+  assert.equal(video.src, '/hls/stream.m3u8');
+  assert.equal(loaded, undefined);
+});
+
+test('missing metadata does not claim an already-playing video is loading', () => {
+  const fs = require('node:fs');
+  const vm = require('node:vm');
+  const html = fs.readFileSync(require.resolve('../web/index.html'), 'utf8');
+  const source = html.slice(html.indexOf('function renderPlayback()'), html.indexOf('function render(state)'));
+  const elements = {};
+  const video = { readyState: 4, paused: false };
+  const context = vm.createContext({
+    video, playbackClip: undefined, playbackError: '', buffering: false,
+    el: id => elements[id] ||= {},
+  });
+  vm.runInContext(source + '\nrenderPlayback();', context);
+  assert.equal(elements.livetext.textContent, 'on air');
+  assert.equal(elements['np-title'].textContent, 'Waiting for title metadata');
+  video.readyState = 0;
+  vm.runInContext('renderPlayback();', context);
+  assert.equal(elements.livetext.textContent, 'loading');
+  assert.equal(elements['np-title'].textContent, 'Waiting for video');
+});
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_prompt_flow.py b/apps/infinite_livestream/infinite_livestream/tests/test_prompt_flow.py
new file mode 100644
index 000000000..17e80b558
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_prompt_flow.py
@@ -0,0 +1,97 @@
+"""A submitted viewer prompt must become ordered clips in the real engine queue.
+
+Only provider calls and GPU readiness are substituted. Chat intake, moderation,
+rewriting, admission, metadata, queue insertion, and web state all run normally.
+"""
+
+import asyncio
+import json
+from types import SimpleNamespace
+
+from fastapi.testclient import TestClient
+import pytest
+
+from infinite_livestream import moderator as moderator_module
+from infinite_livestream import upsampler as upsampler_module
+from infinite_livestream.chat import WebChat
+from infinite_livestream.config import load_model_config
+from infinite_livestream.director import Director
+from infinite_livestream.engine import Engine
+from infinite_livestream.webapp import DemoWeb
+
+
+@pytest.mark.parametrize("scene_count", [1, 3])
+def test_accepted_prompt_reaches_generation_queue(app_config, monkeypatch, scene_count):
+    scenes = [{"prompt": f"A lighthouse keeper feeds seagull {i}", "seconds": 8.0 + i}
+              for i in range(scene_count)]
+    provider_calls = []
+
+    async def moderate(**kwargs):
+        provider_calls.append(("moderation", kwargs["input"]))
+        return SimpleNamespace(results=[SimpleNamespace(flagged=False)])
+
+    async def rewrite(**kwargs):
+        provider_calls.append(("rewrite", kwargs["messages"][-1]["content"]))
+        content = json.dumps({"title": "The lighthouse", "scenes": scenes})
+        return SimpleNamespace(choices=[SimpleNamespace(message=SimpleNamespace(content=content))])
+
+    provider = SimpleNamespace(
+        moderations=SimpleNamespace(create=moderate),
+        chat=SimpleNamespace(completions=SimpleNamespace(create=rewrite)),
+    )
+    monkeypatch.setattr(moderator_module, "AsyncOpenAI", lambda **kwargs: provider)
+    monkeypatch.setattr(upsampler_module, "AsyncOpenAI", lambda **kwargs: provider)
+
+    async def run():
+        engine = Engine(app_config, load_model_config(app_config.config_path))
+        engine._ready.set()  # Queue operations need readiness, never GPU work.
+        await engine.send_command("enqueue", {"prompt": "earlier viewer"})
+        await engine.send_command("enqueue", {"prompt": "idle filler", "metadata": json.dumps({
+            "group_id": "idle", "title": "idle", "author": "filler", "source": "idle",
+            "scene": 1, "scenes": 1, "generated": True,
+        })})
+        chat = WebChat()
+        web = DemoWeb(chat, app_config.hls_dir)
+        engine.add_listener(web.listener)
+        moderator = moderator_module.Moderator("test-key", "test-model", enabled=True)
+        upsampler = upsampler_module.PromptUpsampler("test-key", "test-model", "house style", max_chunks=6)
+        rejections = []
+        director = Director(engine, upsampler, moderator, cooldown_s=10,
+                            on_reject=lambda author, reason: rejections.append((author, reason)))
+        web.cooldown_remaining = director.cooldown_remaining
+        queued = asyncio.Event()
+
+        def on_queue(kind, data):
+            if kind == "queue_update" and len(data["generation"]) == scene_count + 2:
+                queued.set()
+
+        engine.add_listener(on_queue)
+        # Submit before starting intake so TestClient never wakes a queue
+        # waiter owned by a different event loop.
+        with TestClient(web.app) as client:
+            response = client.post("/chat", json={"author": "ada", "text": "a lighthouse keeper"})
+        assert response.status_code == 200 and response.json() == {"ok": True}
+        tasks = [asyncio.create_task(chat.run(director.submit)), asyncio.create_task(director.run())]
+        try:
+            await asyncio.wait_for(queued.wait(), timeout=2)
+            clips = engine.generation_clips
+            assert [c["prompt"] for c in clips] == ["earlier viewer", *[s["prompt"] for s in scenes], "idle filler"]
+            tags = [json.loads(c["metadata"]) for c in clips[1:-1]]
+            assert len({tag["group_id"] for tag in tags}) == 1
+            assert [tag["scene"] for tag in tags] == list(range(1, scene_count + 1))
+            assert all(tag["scenes"] == scene_count and tag["author"] == "ada"
+                       and tag["raw_prompt"] == "a lighthouse keeper" and not tag["generated"] for tag in tags)
+            if scene_count == 1:
+                assert clips[1]["frames"] == 362, "single scenes must use the maximum clip length"
+            assert [c["clip_id"] for c in web.state.generation] == [c["clip_id"] for c in clips]
+            assert all(c["prompt"] == "a lighthouse keeper" for c in web.state.generation[1:-1])
+            assert [name for name, _ in provider_calls] == ["moderation", "rewrite"]
+            assert provider_calls[0][1] == "a lighthouse keeper"
+            assert "a lighthouse keeper" in provider_calls[1][1]
+            assert rejections == []
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    asyncio.run(run())
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_service_lifecycle.py b/apps/infinite_livestream/infinite_livestream/tests/test_service_lifecycle.py
new file mode 100644
index 000000000..8ed400e2c
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_service_lifecycle.py
@@ -0,0 +1,55 @@
+"""Service failures must reach the caller after the other tasks are stopped."""
+
+import asyncio
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+from infinite_livestream import main
+from infinite_livestream.backend import FastH3Backend
+
+
+@pytest.mark.parametrize("failure", ["engine", "pacer", None])
+def test_service_propagates_failure_and_cleans_up(app_config, monkeypatch, failure):
+    error = RuntimeError(f"{failure} startup failed")
+
+    def load():
+        if failure == "engine":
+            raise error
+
+    async def wait_forever():
+        await asyncio.Event().wait()
+
+    async def run_pacer():
+        if failure == "pacer":
+            raise error
+        await wait_forever()
+
+    async def run_web():
+        if failure is None:
+            # Normal server shutdown still exits successfully.
+            await asyncio.sleep(0)
+            return
+        await wait_forever()
+
+    sink = Mock(stop=AsyncMock())
+    web = Mock(run=run_web)
+    pacer = Mock(run=run_pacer)
+    monkeypatch.setattr(FastH3Backend, "load", lambda self: load())
+    monkeypatch.setattr(main, "HlsSink", Mock(return_value=sink))
+    monkeypatch.setattr(main, "DemoWeb", Mock(return_value=web))
+    monkeypatch.setattr(main, "Pacer", Mock(return_value=pacer))
+    monkeypatch.setattr(main, "PromptUpsampler", Mock())
+    monkeypatch.setattr(main, "Moderator", Mock())
+
+    async def run():
+        if failure is None:
+            await main.serve(app_config)
+        else:
+            with pytest.raises(RuntimeError) as caught:
+                await main.serve(app_config)
+            assert caught.value is error
+        sink.stop.assert_awaited_once()
+        assert asyncio.all_tasks() == {asyncio.current_task()}
+
+    asyncio.run(run())
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_sink_shutdown.py b/apps/infinite_livestream/infinite_livestream/tests/test_sink_shutdown.py
new file mode 100644
index 000000000..656ac2c4d
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_sink_shutdown.py
@@ -0,0 +1,128 @@
+"""Use real OS pipes to cover shutdown under encoder backpressure, without GPUs."""
+
+import asyncio
+import os
+import select
+import signal
+import subprocess
+import sys
+import threading
+
+import pytest
+
+from infinite_livestream import sink as sink_module
+from infinite_livestream.sink import HlsSink, _PipeWriter
+
+
+class ObservedPipe:
+    def __init__(self, pipe):
+        self.pipe = pipe
+        self.writing = threading.Event()
+
+    def write(self, payload):
+        self.writing.set()
+        return self.pipe.write(payload)
+
+
+@pytest.mark.skipif(os.name != "posix", reason="the HLS sink uses POSIX pipes")
+@pytest.mark.parametrize("ignore_terminate", [False, True])
+def test_stop_unblocks_full_pipes_and_reaps_process(tmp_path, monkeypatch, ignore_terminate):
+    monkeypatch.setattr(sink_module.shutil, "which", lambda name: "/test/ffmpeg")
+    monkeypatch.setattr(sink_module, "_PROCESS_EXIT_TIMEOUT_S", 0.2, raising=False)
+    sink = HlsSink(tmp_path)
+    audio_read, audio_write = os.pipe()
+    child = (
+        "import signal, time; "
+        + ("signal.signal(signal.SIGTERM, signal.SIG_IGN); " if ignore_terminate else "")
+        + "print('ready', flush=True); time.sleep(30)"
+    )
+    process = subprocess.Popen([sys.executable, "-c", child], stdin=subprocess.PIPE,
+                               stdout=subprocess.PIPE, bufsize=0, pass_fds=(audio_read,))
+    os.close(audio_read)
+    sink._process = process
+    audio_pipe = os.fdopen(audio_write, "wb", buffering=0)
+    sink._audio_pipe = audio_pipe
+    writers = [_PipeWriter("video-test", 1), _PipeWriter("audio-test", 1)]
+    sink._video_writer, sink._audio_writer = writers
+    errors = []
+    ticks = []
+    stopper = None
+    try:
+        assert select.select([process.stdout], [], [], 5)[0], "child failed to become ready"
+        assert process.stdout.readline() == b"ready\n"
+        for writer, pipe in zip(writers, (process.stdin, sink._audio_pipe)):
+            observed = ObservedPipe(pipe)
+            writer.attach(observed)
+            writer.start()
+            writer.submit(b"x" * (2 * 1024 * 1024))
+            assert observed.writing.wait(2), "writer never reached the pipe"
+            writer.submit(b"queued")
+            assert writer.queue.full()
+
+        async def stop_with_heartbeat():
+            task = asyncio.create_task(sink.stop())
+            while not task.done():
+                ticks.append(True)
+                await asyncio.sleep(0.01)
+            await task
+
+        def stop():
+            try:
+                asyncio.run(stop_with_heartbeat())
+            except BaseException as error:
+                errors.append(error)
+
+        # A separate thread makes the timeout effective even if a regression
+        # blocks the event loop inside a synchronous queue/pipe operation.
+        stopper = threading.Thread(target=stop, daemon=True)
+        stopper.start()
+        stopper.join(timeout=5)
+        assert not stopper.is_alive(), "shutdown blocked on a full pipe or queue"
+        assert errors == []
+        expected_signal = signal.SIGKILL if ignore_terminate else signal.SIGTERM
+        assert process.returncode == -expected_signal
+        assert all(not writer.is_alive() for writer in writers)
+        assert process.stdin.closed and audio_pipe.closed
+        assert sink._audio_pipe is None
+        if ignore_terminate:
+            assert len(ticks) > 1, "waiting for FFmpeg blocked the event loop"
+    finally:
+        if process.poll() is None:
+            process.kill()
+        process.wait(timeout=5)
+        if stopper is not None:
+            stopper.join(timeout=5)
+        for writer in writers:
+            writer.close()
+            if writer.ident is not None:
+                writer.join(timeout=2)
+        process.stdin.close()
+        process.stdout.close()
+        if sink._audio_pipe is not None:
+            sink._audio_pipe.close()
+
+
+def test_writer_preserves_the_payload_across_short_writes():
+    payload = b"one complete media frame"
+    written = bytearray()
+    complete = threading.Event()
+
+    class ShortPipe:
+        def write(self, data):
+            count = min(3, len(data))
+            written.extend(data[:count])
+            if len(written) == len(payload):
+                complete.set()
+            return count
+
+    writer = _PipeWriter("short-write-test", 1)
+    writer.attach(ShortPipe())
+    writer.start()
+    try:
+        writer.submit(payload)
+        assert complete.wait(2), "a short write discarded the rest of the media payload"
+        assert written == payload
+    finally:
+        writer.close()
+        writer.join(timeout=2)
+    assert not writer.is_alive()
diff --git a/apps/infinite_livestream/infinite_livestream/tests/test_state_mirror.py b/apps/infinite_livestream/infinite_livestream/tests/test_state_mirror.py
new file mode 100644
index 000000000..9be9e133b
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/tests/test_state_mirror.py
@@ -0,0 +1,76 @@
+"""Chat, queue, and service state stay independent of viewers' playback clocks."""
+
+from __future__ import annotations
+
+from infinite_livestream.webapp import DemoState
+
+
+def clip(clip_id: str = "abcdef123456", prompt: str = "a lighthouse keeper", *, generated: bool = False,
+         scene: int | None = None, scenes: int | None = None) -> dict:
+    import json
+    meta = {"group_id": "g1", "title": prompt, "author": "viewer", "generated": generated, "raw_prompt": prompt}
+    if scene is not None:
+        meta |= {"scene": scene, "scenes": scenes}
+    return {"clip_id": clip_id, "prompt": prompt, "metadata": json.dumps(meta), "frames": 345,
+            "seconds": 14.375, "seed": 1, "ready": True}
+
+
+def test_queue_update_replaces_both_queues() -> None:
+    state = DemoState()
+    state.on_message("queue_update", {"generation": [clip("a")], "playout": [clip("b"), clip("c")]})
+    assert [c["clip_id"] for c in state.generation] == ["a"]
+    assert [c["clip_id"] for c in state.playout] == ["b", "c"]
+    # Replacement, not accumulation: a queue that empties must render empty.
+    state.on_message("queue_update", {"generation": [], "playout": []})
+    assert state.generation == [] and state.playout == []
+
+
+def test_generating_is_the_generation_front() -> None:
+    """Builds consume the queue front-first, so the front is what is in flight."""
+    state = DemoState()
+    assert state.generating is None
+    state.on_message("queue_update", {"generation": [clip("a"), clip("b")], "playout": []})
+    generating = state.generating
+    assert generating is not None and generating["clip_id"] == "a"
+
+
+def test_playout_events_do_not_define_a_viewers_playback_position() -> None:
+    state = DemoState()
+    before = state.snapshot()
+    state.on_message("clip_started", {"clip": clip("a")})
+    state.on_message("clip_finished", {"clip": clip("a"), "seconds_sent": 14.4})
+    assert state.snapshot() == before
+
+
+def test_only_filler_is_announced_in_chat_and_once_per_group() -> None:
+    """Viewer submissions are echoed by the POST handler, so only filler here.
+
+    And one line per group, not per scene: a six-scene story is still one
+    thing somebody asked for.
+    """
+    state = DemoState()
+    state.on_message("clip_queued", {"clip": clip("v", "viewer idea", generated=False)})
+    assert list(state.chat) == []
+    for scene in (1, 2, 3):
+        state.on_message("clip_queued", {"clip": clip(f"f{scene}", "filler idea", generated=True,
+                                                      scene=scene, scenes=3)})
+    assert [c["author"] for c in state.chat] == ["filler"]
+
+
+def test_failed_viewer_clips_are_reported_but_filler_is_not() -> None:
+    state = DemoState()
+    state.on_message("clip_failed", {"clip": clip("f", generated=True), "reason": "boom"})
+    assert list(state.chat) == []
+    state.on_message("clip_failed", {"clip": clip("v", "viewer idea", generated=False), "reason": "boom"})
+    assert [c["kind"] for c in state.chat] == ["error"]
+
+
+def test_snapshot_carries_everything_the_page_reads() -> None:
+    state = DemoState()
+    state.on_message("state_update", {"playing": False, "generation_queued": 1, "generation_capacity": 20,
+                                      "playout_queued": 2, "playout_capacity": 10, "clips_played": 7,
+                                      "width": 1344, "height": 768})
+    snap = state.snapshot()
+    assert set(snap) == {"connected", "generating",
+                         "generation", "playout", "stats", "chat"}
+    assert snap["stats"]["clips_played"] == 7
diff --git a/apps/infinite_livestream/infinite_livestream/upsampler.py b/apps/infinite_livestream/infinite_livestream/upsampler.py
new file mode 100644
index 000000000..955921deb
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/upsampler.py
@@ -0,0 +1,359 @@
+"""Prompt upsampling: a viewer's rough idea into FastH3-ready scenes.
+
+One LLM call per prompt against any OpenAI-compatible endpoint. The model
+picks the shape the idea calls for -- one scene, or a chunked short story of
+up to `max_chunks` clips -- writes each scene as a self-contained
+text-to-video prompt in the configured style, and picks each scene's length.
+
+The system prompt is written around four facts about FastH3. Keep them intact
+when editing it:
+
+  * **Each scene is an independent clip with no memory.** The biggest quality
+    lever by far. "The same forest" renders a *different* forest, so every
+    scene must re-describe setting, subjects, light and style from scratch.
+  * **800 characters is the hard cap per prompt.** The LLM is told 750 for
+    headroom and `_sanitize` truncates anyway, because LLMs do not count
+    characters reliably.
+  * **Audio is generated with the video, speech included.** The prompt asks
+    for quoted dialogue (who speaks, the words, the tone) whenever the idea
+    implies speech, and for a brief soundscape clause. Clips come out flat
+    without them.
+  * **A single-clip generation always runs the maximum length**, enforced in
+    code after validation, so the scene can breathe. Short lengths are
+    reserved for transition chunks inside multi-scene stories.
+
+Safety is `moderator.py`'s job: the idea has already passed it by the time it
+arrives here, so this prompt asks for faithful staging and never for
+softening or reinterpreting.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from dataclasses import dataclass
+
+from openai import AsyncOpenAI
+
+logger = logging.getLogger(__name__)
+
+# The engine's enqueue cap; _sanitize truncates to it.
+MAX_PROMPT_CHARS = 800
+# LLM calls one idea gets before falling back to the raw prompt.
+_MAX_ATTEMPTS = 3
+
+# What the LLM is asked to stay under, leaving headroom for its poor counting.
+# Sized so an overshoot still fits under the 800 hard cap: the sanitizer
+# truncates mid-word at 800, and what it cuts is the prompt's tail — the
+# soundscape sentence the format deliberately puts last.
+_TARGET_PROMPT_CHARS = 700
+
+# What goes in the STYLE slot for a viewer's own request when the deployment
+# lets viewers out of the house style. The filler still carries the preset's
+# identity, which is what gives the stream a look of its own between requests;
+# forcing a viewer's idea into that same look is what makes "a documentary shot
+# of a snow leopard" come back as a cartoon.
+_FREE_STYLE = """No house style is imposed on this request. Choose the look that genuinely
+suits the viewer's idea and commit to it fully — photoreal documentary,
+anime, stop-motion, 90s camcorder, oil painting, whatever the idea calls
+for. If the viewer names a style, medium or era, follow it exactly. Describe
+that look concretely in every scene prompt (lens, lighting, palette, texture,
+grain, motion) so the clip is unmistakably in it."""
+
+_SYSTEM_PROMPT = """\
+You are the scene director of a live, chat-driven AI video stream. Viewers
+send short, rough ideas; you turn each one into one or more polished
+text-to-video prompts for a model that generates short clips with
+synchronized audio.
+
+STYLE / CHARACTER — every scene is rendered in this identity; weave it into
+every scene prompt, never contradict it:
+{style}
+
+HOW THE VIDEO MODEL WORKS (hard constraints):
+- Each scene becomes ONE independent clip. The model has NO memory between
+  clips: every scene prompt must be fully self-contained and re-describe the
+  entire setting, subjects, lighting, palette, mood, and style — even when
+  nothing changed from the previous scene. Anything you omit will vanish or
+  mutate between scenes.
+- Each scene prompt must be under {target_chars} characters. This is a hard
+  limit; prefer cutting adjectives over cutting subjects or setting.
+- Each scene has a duration in seconds, between {min_seconds} and
+  {max_seconds}; the rules below say how to choose it.
+- The model renders picture AND sound, including clear spoken language.
+  When the idea involves someone speaking, write the dialogue out
+  explicitly and unambiguously — name who speaks and give the exact words
+  in quotes (e.g. the fisherman shouts "It's alive!") — and describe the
+  voice's tone. Do not paraphrase speech the viewer asked for.
+- End each scene prompt with one short clause of soundscape (ambience,
+  music mood, or effects) alongside any dialogue.
+- Describe only what the camera sees and the microphone hears: no text
+  overlays, no UI, no scene numbers, no camera jargon the model cannot show.
+
+{scene_count_rules}
+
+WRITING THE SCENE PROMPTS:
+- Be concrete and visual: subject, action, setting, camera angle and motion,
+  lighting, color palette, atmosphere, then the soundscape clause.
+- Strong nouns and verbs over piles of adjectives; vivid but precise.
+- Keep the viewer's idea recognizable — enhance it, do not replace it. The
+  idea has already passed moderation before it reaches you; your job is
+  faithful staging, not policing.
+
+Reply with ONLY this JSON, nothing else:
+{{"title": "short display title for the sequence",
+  "scenes": [{{"prompt": "self-contained scene description...", "seconds": 8.0}}]}}
+The "scenes" array is REQUIRED even when it holds a single scene; never
+flatten a scene's fields to the top level.
+"""
+
+_MULTI_SCENE_RULES = """\
+HOW MANY SCENES, AND HOW LONG — two shapes; pick what the idea calls for:
+- ONE SCENE: a single clip that ALWAYS runs the full {max_seconds} seconds —
+  never shorter — with room for the scene to build, land, and breathe.
+  Right for a mood, a place, a single action or gag. When in doubt, this.
+- CHUNKED SHORT STORY: 3 to {max_chunks} chunks that read as one story with
+  a setup, a development, and a payoff. Content chunks run 8-{max_seconds}
+  seconds; the short end ({min_seconds}-8 s) is ONLY for transitions — an
+  establishing cut, a reaction beat, a snap punchline — never for a chunk
+  that carries the story. Choose this shape when the idea implies
+  narrative: a journey, a transformation, a chase, a build-up.
+- Never more than {max_chunks} scenes. Do not pad a thin idea into many
+  chunks; a story earns its chunks or it is one full-length scene.
+- Consecutive scenes play back-to-back as one sequence. Make them feel
+  continuous: repeat the shared setting and subjects verbatim enough that
+  they read as the same place, and change only what the story moves."""
+
+_SINGLE_SCENE_RULES = """\
+HOW MANY SCENES, AND HOW LONG:
+- Exactly one scene, and it ALWAYS runs the full {max_seconds} seconds.
+  Distill the idea into one complete arc that fills that time."""
+
+
+@dataclass(frozen=True)
+class Scene:
+    """One upsampled scene: a prompt fast-h3 can take verbatim, and a length."""
+
+    prompt: str
+    seconds: float
+
+
+@dataclass(frozen=True)
+class SceneGroup:
+    """The scenes one prompt expanded into, played back-to-back.
+
+    ``generated`` marks filler groups made from the idle prompt list rather
+    than a viewer request; the director may evict their clips from the
+    model's queue to make room for viewer groups.
+    """
+
+    group_id: str
+    title: str
+    author: str
+    source: str
+    raw_prompt: str
+    scenes: list[Scene]
+    generated: bool = False
+
+
+class PromptUpsampler:
+    """Expand chat ideas into styled, self-contained fast-h3 scenes."""
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str,
+        style: str,
+        max_chunks: int,
+        base_url: str | None = None,
+        free_viewer_style: bool = True,
+    ) -> None:
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._model = model
+        self._style = style.strip() or "Cinematic, photoreal, rich natural light."
+        # Filler keeps the preset identity; viewer requests may pick their own.
+        self._free_viewer_style = free_viewer_style
+        self._max_chunks = max_chunks
+
+    async def upsample(
+        self,
+        raw_prompt: str,
+        author: str,
+        source: str,
+        min_seconds: float,
+        max_seconds: float,
+        generated: bool = False,
+        max_chunks: int | None = None,
+    ) -> SceneGroup:
+        """One idea in, one validated scene group out. Never raises.
+
+        `min_seconds`/`max_seconds` are the live bounds from the model's
+        `state_update`, so the LLM always chooses within what the deployment
+        actually accepts. `max_chunks` caps this call below the configured
+        ceiling (the idle filler passes 1 so its groups stay one-clip and
+        evictable). On any LLM failure the raw prompt (styled, truncated)
+        becomes a single scene — the stream keeps moving.
+        """
+        chunk_cap = min(max_chunks or self._max_chunks, self._max_chunks)
+        scene_count_rules = (_MULTI_SCENE_RULES.format(
+            max_chunks=chunk_cap,
+            min_seconds=f"{min_seconds:g}",
+            max_seconds=f"{max_seconds:g}",
+        ) if chunk_cap > 1 else _SINGLE_SCENE_RULES.format(max_seconds=f"{max_seconds:g}"))
+        system = _SYSTEM_PROMPT.format(
+            style=(_FREE_STYLE if self._free_viewer_style and not generated else self._style),
+            target_chars=_TARGET_PROMPT_CHARS,
+            min_seconds=f"{min_seconds:g}",
+            max_seconds=f"{max_seconds:g}",
+            scene_count_rules=scene_count_rules,
+        )
+        group_id = uuid.uuid4().hex[:12]
+        title = ""
+        scenes: list[Scene] = []
+        for attempt in range(1, _MAX_ATTEMPTS + 1):
+            try:
+                title, scenes = await self._attempt(
+                    system=system,
+                    raw_prompt=raw_prompt,
+                    request_tag=f"{group_id}.{attempt}",
+                    chunk_cap=chunk_cap,
+                    min_seconds=min_seconds,
+                    max_seconds=max_seconds,
+                )
+                break
+            except Exception as error:
+                logger.warning(
+                    "[upsampler] unusable reply, attempt %d/%d for %.60r: %s",
+                    attempt,
+                    _MAX_ATTEMPTS,
+                    raw_prompt,
+                    error,
+                )
+        if not scenes:
+            logger.warning(
+                "[upsampler] all %d attempts unusable; falling back to the raw prompt",
+                _MAX_ATTEMPTS,
+            )
+            title = raw_prompt[:60]
+            # The viewer's idea gets the char budget first; the style fills
+            # whatever remains (a long STYLE must never truncate the idea away).
+            idea = _sanitize(raw_prompt)
+            style_room = MAX_PROMPT_CHARS - len(idea) - 2
+            fallback = f"{idea}. {self._style[:style_room]}" if style_room > 20 else idea
+            scenes = [
+                # A single clip, so it takes the maximum length like every
+                # other one-scene generation.
+                Scene(prompt=_sanitize(fallback), seconds=max_seconds)
+            ]
+
+        group = SceneGroup(
+            group_id=group_id,
+            title=title,
+            author=author,
+            source=source,
+            raw_prompt=raw_prompt,
+            scenes=scenes,
+            generated=generated,
+        )
+        for index, scene in enumerate(group.scenes, start=1):
+            logger.info(
+                "[upsampler] %s scene %d/%d (%.1fs): %.100s...",
+                group_id,
+                index,
+                len(group.scenes),
+                scene.seconds,
+                scene.prompt,
+            )
+        return group
+
+    async def _attempt(
+        self,
+        *,
+        system: str,
+        raw_prompt: str,
+        request_tag: str,
+        chunk_cap: int,
+        min_seconds: float,
+        max_seconds: float,
+    ) -> tuple[str, list[Scene]]:
+        """One LLM call, parsed and validated; raises on an unusable reply.
+
+        The request tag makes every attempt a distinct request — the gateway
+        caches identical ones, so a bare retry of a failed prompt would get
+        the same failed reply back in milliseconds.
+        """
+        response = await self._client.chat.completions.create(
+            model=self._model,
+            messages=[
+                {
+                    "role": "system",
+                    "content": system
+                },
+                {
+                    "role": "user",
+                    "content": f"Viewer idea: {raw_prompt}\n\n[request {request_tag}]",
+                },
+            ],
+            temperature=0.8,
+            max_tokens=1800,
+            response_format={"type": "json_object"},
+        )
+        content = response.choices[0].message.content or ""
+        data = json.loads(content or "{}")
+        title = str(data.get("title") or raw_prompt[:60]).strip()
+        raw_scenes = data.get("scenes")
+        if isinstance(raw_scenes, dict):
+            raw_scenes = [raw_scenes]
+        if not raw_scenes and "prompt" in data:
+            # Some models flatten a single scene's fields to the top level
+            # despite the schema; accept it as one scene.
+            raw_scenes = [data]
+        scenes = self._validate_scenes(raw_scenes or [], chunk_cap, min_seconds, max_seconds)
+        if not scenes:
+            raise ValueError("no usable scenes in the reply "
+                             f"(finish={response.choices[0].finish_reason}, head={content[:200]!r})")
+        if len(scenes) == 1:
+            # A single-clip generation always runs the maximum length; short
+            # clips are reserved for transition chunks in stories.
+            scenes = [Scene(prompt=scenes[0].prompt, seconds=max_seconds)]
+        return title, scenes
+
+    def _validate_scenes(self, raw_scenes: list, chunk_cap: int, min_seconds: float, max_seconds: float) -> list[Scene]:
+        """Enforce every constraint the LLM was asked for; trust nothing."""
+        scenes: list[Scene] = []
+        for raw in raw_scenes[:chunk_cap]:
+            if not isinstance(raw, dict):
+                continue
+            prompt = _sanitize(str(raw.get("prompt", "")))
+            if not prompt:
+                continue
+            try:
+                seconds = float(raw.get("seconds", 8.0))
+            except (TypeError, ValueError):
+                seconds = 8.0
+            scenes.append(Scene(prompt=prompt, seconds=_clamp(seconds, min_seconds, max_seconds)))
+        return scenes
+
+
+def _sanitize(prompt: str) -> str:
+    """Collapse whitespace and fit under fast-h3's prompt cap, ending clean.
+
+    LLMs overshoot the character target they are given, and a blind cut at
+    the cap ends the prompt mid-word — worse for the model than losing the
+    final sentence. Over-long prompts are therefore cut at the last sentence
+    boundary that fits; the mid-word cut remains
+    only as the last resort for a prompt written as one giant sentence.
+    """
+    collapsed = " ".join(prompt.split())
+    if len(collapsed) <= MAX_PROMPT_CHARS:
+        return collapsed.strip()
+    head = collapsed[:MAX_PROMPT_CHARS]
+    boundary = max(head.rfind(". "), head.rfind("! "), head.rfind("? "))
+    if boundary > MAX_PROMPT_CHARS // 2:
+        return head[:boundary + 1].strip()
+    return head.strip()
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))
diff --git a/apps/infinite_livestream/infinite_livestream/web/icon.svg b/apps/infinite_livestream/infinite_livestream/web/icon.svg
new file mode 100644
index 000000000..414643899
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/web/icon.svg
@@ -0,0 +1,6 @@
+<svg width="160" height="93" viewBox="0 0 160 93" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M28.8511 91.66L57.6319 1.86368H64.5394L35.7585 91.66H28.8511Z" fill="#356CFF" stroke="#356CFF" stroke-width="2.30244"/>
+<path d="M15.0376 91.66L43.8185 1.86368H46.1209L17.3401 91.66H15.0376Z" fill="#356CFF" stroke="#356CFF" stroke-width="2.30244"/>
+<path d="M1.22217 91.66L30.003 1.86366H31.1543L2.3734 91.66H1.22217Z" fill="#356CFF" stroke="#356CFF" stroke-width="1.15122"/>
+<path d="M71.4465 1.86483L42.666 91.6599H69.144L78.3538 58.2746H123.251L129.007 39.855H84.1099L89.866 22.5868H152.032L157.788 1.86483H71.4465Z" fill="#356CFF" stroke="#356CFF" stroke-width="2.30244"/>
+</svg>
diff --git a/apps/infinite_livestream/infinite_livestream/web/index.html b/apps/infinite_livestream/infinite_livestream/web/index.html
new file mode 100644
index 000000000..3ba39975d
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/web/index.html
@@ -0,0 +1,497 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover, interactive-widget=resizes-content">
+<title>FastH3 · infinite livestream</title>
+<link rel="icon" href="/assets/icon.svg">
+<script src="https://cdn.jsdelivr.net/npm/hls.js@1.5.17/dist/hls.min.js"></script>
+<style>
+  /* Dreamverse's palette: slate on near-white, FastVideo blue as the accent. */
+  :root{
+    --bg:#f5f4f4; --panel:#ffffff; --panel-2:#f8fafc; --line:#e2e8f0;
+    --text:#0f172a; --dim:#64748b; --accent:#356cff; --err:#ef4444;
+    --radius:12px; --shadow:0 1px 2px rgba(15,23,42,.06), 0 8px 24px rgba(15,23,42,.04);
+  }
+  *{box-sizing:border-box}
+  html,body{height:100%}
+  body{margin:0;background:var(--bg);color:var(--text);
+       font:14px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+       display:flex;flex-direction:column;height:100dvh;overflow:hidden}
+  header{flex:0 0 auto;display:flex;align-items:center;gap:14px;padding:10px 20px;
+         background:var(--panel);border-bottom:1px solid var(--line)}
+  header img{height:26px;display:block}
+  .sep{width:1px;height:20px;background:var(--line)}
+  .brand{font-size:14.5px;font-weight:700;letter-spacing:-.15px;white-space:nowrap}
+  .brand .fast{color:var(--accent)}
+  .brand .dotsep{color:#cbd5e1;font-weight:400;margin:0 2px}
+  .brand .sub{color:var(--dim);font-weight:500}
+  .live{margin-left:auto;display:inline-flex;align-items:center;gap:7px;font-size:11px;
+        font-weight:700;text-transform:uppercase;letter-spacing:.7px;color:var(--dim);
+        background:var(--panel-2);border:1px solid var(--line);border-radius:99px;padding:4px 11px}
+  .dot{width:7px;height:7px;border-radius:50%;background:#cbd5e1}
+  .dot.on{background:var(--err);animation:pulse 1.6s infinite}
+  @keyframes pulse{0%,100%{opacity:1}50%{opacity:.3}}
+  .layout{flex:1;min-height:0;display:grid;grid-template-columns:minmax(0,1fr) 372px;
+          gap:18px;padding:18px}
+  .stage{display:flex;flex-direction:column;gap:14px;min-width:0;min-height:0}
+  .video-wrap{position:relative;background:#0b1220;border:1px solid var(--line);
+              border-radius:var(--radius);overflow:hidden;aspect-ratio:7/4;
+              flex:0 1 auto;min-height:0;box-shadow:var(--shadow)}
+  video{width:100%;height:100%;max-width:100%;display:block;background:#0b1220;object-fit:contain}
+  .nowplaying{background:var(--panel);border:1px solid var(--line);border-radius:var(--radius);
+              padding:14px 16px;flex:1 1 auto;min-height:0;overflow:hidden;
+              display:flex;flex-direction:column;box-shadow:var(--shadow)}
+  /* flex:none on both: `.nowplaying` is a column flex container, so with a
+     full queue below them these two shrink to fit and the title's box ends up
+     shorter than its own line box -- which clips the descenders off the last
+     visible line. They are fixed-size content; only the queue below should
+     absorb the pressure. */
+  .nowplaying h2{margin:0 0 6px;font-size:15.5px;font-weight:650;letter-spacing:-.1px;line-height:1.4;
+                 flex:none;
+                 display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
+  .nowplaying .meta{color:var(--dim);font-size:12.5px;flex:none}
+  .card{background:var(--panel);border:1px solid var(--line);border-radius:var(--radius);
+        display:flex;flex-direction:column;min-height:0;overflow:hidden;box-shadow:var(--shadow)}
+  .card > h3{margin:0;padding:12px 16px;border-bottom:1px solid var(--line);
+             font-size:11px;text-transform:uppercase;letter-spacing:.7px;color:var(--dim);
+             font-weight:700;display:flex;justify-content:space-between;align-items:center}
+  .card .scroll{flex:1;min-height:0;overflow-y:auto;padding:10px 12px;
+                display:flex;flex-direction:column;gap:7px}
+  .queuebar{margin-top:12px;border-top:1px solid var(--line);
+            display:flex;flex-direction:column;min-height:0;flex:1 1 auto}
+  .queuebar.collapsed{flex:0 0 auto;margin-top:8px}
+  .queuebar > h3{padding:9px 0 6px;border-bottom:0;font-size:11px;font-weight:700;
+                 text-transform:uppercase;letter-spacing:.7px;color:var(--dim);
+                 display:flex;justify-content:space-between;align-items:center;margin:0}
+  .queuebar.collapsed > h3{padding:5px 0 0}
+  .queuebar.collapsed .scroll{display:none}
+  .queuebar.collapsed .chev{transform:rotate(-90deg)}
+  .queuebar .scroll{flex:1;min-height:0;overflow-y:auto;padding:3px 0 4px;
+                    display:flex;flex-direction:column;gap:7px}
+  .side{display:flex;flex-direction:column;gap:14px;min-height:0;min-width:0}
+  #chat{flex:1 1 auto;min-height:0}
+  #queue-head{cursor:pointer;user-select:none}
+  .chev{transition:transform .15s;color:#94a3b8}
+  .item{background:var(--panel-2);border:1px solid var(--line);border-radius:9px;padding:8px 10px}
+  .item .top{display:flex;gap:8px;align-items:baseline;font-size:12.5px}
+  .item .title{flex:1;min-width:0;font-weight:600;overflow:hidden;
+               text-overflow:ellipsis;white-space:nowrap}
+  .item .prompt{color:var(--dim);font-size:12px;margin-top:2px;
+                overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+  .pill{font-size:9.5px;padding:2px 7px;border-radius:99px;border:1px solid var(--line);
+        color:var(--dim);white-space:nowrap;flex:0 0 auto;font-weight:700;
+        text-transform:uppercase;letter-spacing:.4px;background:var(--panel)}
+  .pill.building{border-color:#c7d7ff;color:var(--accent);background:#eef3ff}
+  .pill.ready{border-color:#bbf7d0;color:#15803d;background:#f0fdf4}
+  .item:first-child .pill.ready{border-color:#c7d7ff;color:var(--accent);background:#eef3ff}
+  .msg{font-size:13.5px;word-wrap:break-word;line-height:1.5}
+  .msg .who{font-weight:700;color:var(--accent)}
+  .msg.filler .who{color:#94a3b8;font-weight:650}
+  .msg.filler{color:var(--dim)}
+  .msg.system{color:var(--dim);font-style:italic}
+  .msg.error{color:var(--err)}
+  form{display:flex;flex-wrap:wrap;gap:8px;padding:12px;border-top:1px solid var(--line);
+       background:var(--panel-2)}
+  input,button{font:inherit;border-radius:9px;border:1px solid var(--line)}
+  button:disabled{opacity:.55;cursor:default;box-shadow:none}
+  input:disabled{opacity:.6}
+  input{min-width:0;background:var(--panel);color:var(--text);padding:9px 11px}
+  input::placeholder{color:#94a3b8}
+  input:focus{outline:2px solid var(--accent);outline-offset:-1px}
+  #who{flex:1 1 88px}
+  #text{flex:3 1 150px}
+  button{background:var(--accent);color:#fff;font-weight:650;padding:9px 17px;
+         border-color:transparent;cursor:pointer;box-shadow:0 1px 2px rgba(53,108,255,.3)}
+  button:hover{filter:brightness(1.06)}
+  .empty{color:#94a3b8;font-size:12.5px;padding:8px 4px}
+  #unmute{position:absolute;left:50%;bottom:14px;transform:translateX(-50%);
+          background:var(--accent);color:#fff;font-weight:700;padding:9px 17px;
+          border:0;border-radius:99px;cursor:pointer;z-index:5}
+  #debug{position:fixed;right:10px;bottom:10px;z-index:20;background:#0f172af2;
+         border-radius:8px;padding:8px 11px;font:11px/1.5 ui-monospace,monospace;
+         color:#93c5fd;pointer-events:none;max-width:46ch}
+  @media (max-width:900px){
+    /* >=16px stops iOS/Chrome auto-zooming the page on focus. */
+    input, #text, #who, button{font-size:16px}
+    .layout{grid-template-columns:minmax(0,1fr);grid-template-rows:auto minmax(200px,1fr);
+            padding:10px;gap:10px;overflow-y:auto}
+    header{padding:8px 12px;gap:10px}
+    header img{height:22px}
+    .brand{font-size:12.5px;min-width:0;white-space:normal}
+    .live{flex-shrink:0}
+    .brand .sub{font-size:12px}
+    .video-wrap{max-height:34dvh}
+    .queuebar .scroll{max-height:24dvh;flex:0 1 auto}
+  }
+  @media (orientation:landscape) and (min-width:560px) and (max-height:600px){
+    input, #text, #who, button{font-size:16px}
+    .layout{grid-template-columns:minmax(0,1fr) minmax(240px,36%);
+            grid-template-rows:minmax(0,1fr);padding:10px;gap:10px;overflow:hidden}
+    .stage{gap:8px;overflow-y:auto}
+    .video-wrap{flex:1 1 0;min-height:110px;max-height:none}
+    .nowplaying{flex:0 0 auto;padding:8px 10px}
+    .nowplaying h2{font-size:14px;margin-bottom:4px}
+    .card > h3{padding:8px 10px}
+    form{display:grid;grid-template-columns:minmax(0,1fr) auto;padding:8px;gap:6px}
+    #who{grid-column:1 / -1}
+    button{padding:9px 12px}
+  }
+</style>
+</head>
+<body>
+<header>
+  <img src="/assets/logo.svg" alt="FastVideo">
+  <div class="sep"></div>
+  <div class="brand"><span class="fast">Fast</span>H3 <span class="dotsep">·</span> <span class="sub">infinite livestream</span></div>
+  <div class="live"><span class="dot" id="dot"></span><span id="livetext">connecting</span></div>
+</header>
+
+<div id="debug" hidden></div>
+<div class="layout">
+  <div class="stage">
+    <div class="video-wrap"><video id="video" controls autoplay playsinline></video>
+      <button id="unmute" hidden>&#128266; Tap for sound</button></div>
+    <div class="nowplaying">
+      <h2 id="np-title">Nothing playing yet</h2>
+      <div class="meta" id="np-meta">The stream holds on black between clips.</div>
+      <div id="queue" class="queuebar collapsed">
+        <h3 id="queue-head">
+          <span>Queue <span class="pill" id="queue-count">0</span></span>
+          <span class="chev" id="queue-chev">&#9662;</span>
+        </h3>
+        <div class="scroll" id="queue-list"><div class="empty">Queue is empty.</div></div>
+      </div>
+    </div>
+  </div>
+
+  <div class="side">
+    <div class="card" id="chat">
+      <h3>Chat</h3>
+      <div class="scroll" id="chat-list"><div class="empty">Type an idea to put it on the stream.</div></div>
+      <form id="chat-form">
+        <input id="who" maxlength="32" placeholder="name" autocomplete="off">
+        <input id="text" maxlength="800" placeholder="say what to generate…" autocomplete="off" required>
+        <button type="submit">Send</button>
+      </form>
+    </div>
+  </div>
+</div>
+
+<script src="/assets/metadata.js"></script>
+<script>
+// ---------------------------------------------------------------- video
+// Timed title cues use the player's own playback clock on both HLS paths.
+const PLAYLIST = "/hls/stream.m3u8";
+const video = document.getElementById("video");
+let playbackClip;
+let playbackError = "";
+let buffering = true;
+let retryTimer = null;
+let stopMetadata = null;
+
+function restartPlayback() {
+  if (retryTimer !== null) return;
+  // Defer destruction until hls.js has finished dispatching the error event.
+  retryTimer = setTimeout(() => {
+    retryTimer = null;
+    if (stopMetadata) stopMetadata();
+    if (window._hls) window._hls.destroy();
+    window._hls = null;
+    video.removeAttribute("src");
+    video.load();
+    startPlayback();
+  }, 3000);
+}
+
+function startPlayback() {
+  stopMetadata = LivestreamMetadata.watch(video, clip => {
+    playbackClip = clip;
+    renderPlayback();
+  });
+  // Native HLS support does not guarantee that the browser exposes ID3 cues.
+  // Use the same metadata parser wherever Media Source playback is supported.
+  if (!window.Hls || !Hls.isSupported()) {
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      video.src = PLAYLIST;
+    } else {
+      playbackError = "This browser cannot play the stream. Try an external browser.";
+      renderPlayback();
+    }
+    return;
+  }
+  const hls = new Hls({ liveSyncDurationCount: 3, lowLatencyMode: true });
+  window._hls = hls;
+  hls.on(Hls.Events.ERROR, (_e, data) => {
+    if (!data.fatal) return;
+    if (data.details === Hls.ErrorDetails.BUFFER_ADD_CODEC_ERROR ||
+        data.details === Hls.ErrorDetails.MANIFEST_INCOMPATIBLE_CODECS_ERROR) {
+      playbackError = "This browser cannot decode the stream. Try an external browser.";
+      renderPlayback();
+      return;
+    }
+    restartPlayback();
+  });
+  hls.loadSource(PLAYLIST);
+  hls.attachMedia(video);
+}
+video.addEventListener("error", restartPlayback);
+video.addEventListener("waiting", () => { buffering = true; renderPlayback(); });
+video.addEventListener("playing", () => { buffering = false; renderPlayback(); });
+video.addEventListener("pause", renderPlayback);
+video.addEventListener("loadeddata", renderPlayback);
+video.addEventListener("canplay", renderPlayback);
+video.addEventListener("seeked", renderPlayback);
+
+let correctedSeek = false;
+video.addEventListener("seeked", () => {
+  if (correctedSeek) { correctedSeek = false; return; }
+  if (!video.paused) return;
+  // hls.js repairs gaps while playing. A paused seek can instead finish just
+  // before a buffered segment while showing its first frame. Move the seek
+  // itself into available media so both the frame and cue clocks agree.
+  for (let i = 0; i < video.buffered.length; i++) {
+    const start = video.buffered.start(i);
+    if (video.currentTime >= start && video.currentTime < video.buffered.end(i)) return;
+    if (video.currentTime < start) {
+      correctedSeek = true;
+      video.currentTime = start + 0.000001; // Inside the boundary at browser timestamp precision.
+      return;
+    }
+  }
+});
+
+// Ask for sound; fall back to muted only if the browser refuses, and say so.
+const unmute = document.getElementById("unmute");
+async function tryUnmuted() {
+  video.muted = false;
+  try {
+    await video.play();
+    unmute.hidden = true;
+  } catch (_) {
+    video.muted = true;
+    try { await video.play(); } catch (__) {}
+    unmute.hidden = false;
+  }
+}
+video.addEventListener("loadedmetadata", tryUnmuted, { once: true });
+unmute.addEventListener("click", tryUnmuted);
+
+// ---------------------------------------------------------------- state
+const el = (id) => document.getElementById(id);
+const esc = (s) => String(s ?? "").replace(/[&<>"']/g, c =>
+  ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+// Requests can be 800 characters; everywhere they are shown inline they get
+// the same short form, so the panel under the video reads like a chat line.
+function short(text, n) {
+  const t = String(text || "").trim().replace(/\s+/g, " ");
+  if (t.length <= n) return t;
+  // Cut on a word boundary where there is one nearby, so the tail is not a
+  // fragment of a word, and always show that something was cut.
+  const cut = t.slice(0, n);
+  const space = cut.lastIndexOf(" ");
+  return (space > n * 0.6 ? cut.slice(0, space) : cut).trimEnd() + "…";
+}
+
+function label(clip) {
+  // clip.prompt is the raw request as typed (webapp fills it from the group
+  // tag's raw_prompt); title is the upsampler's invention.
+  return (clip.prompt || "").trim() || clip.title || clip.clip_id.slice(0, 8);
+}
+
+function renderQueue(state) {
+  // Ordered by how soon each clip plays, which is the only order a viewer
+  // reads this list in. Built clips come FIRST -- they are nearest the screen,
+  // and the front of the playout queue is literally what plays next. Clips
+  // still being built come after, since they are further away in time.
+  //
+  // Listing the generation queue first was backwards: a clip finishing its
+  // build crosses from that queue into the playout queue, so it appeared to
+  // jump to the bottom of the list at the exact moment it got closer to
+  // playing.
+  const items = [
+    ...state.playout.map((c, i) => ({ ...c, status: "ready", pill: i === 0 ? "up next" : "ready" })),
+    ...state.generation.map((c, i) => ({ ...c, status: i === 0 ? "building" : "queued",
+                                         pill: i === 0 ? "building" : "queued" })),
+  ];
+  el("queue-count").textContent = items.length;
+  const list = el("queue-list");
+  if (!items.length) { list.innerHTML = '<div class="empty">Queue is empty.</div>'; return; }
+  list.innerHTML = items.map(c => `
+    <div class="item">
+      <div class="top">
+        <span class="title" title="${esc(c.title || "")}">${esc(short(label(c), 70))}</span>
+        ${c.scenes > 1 ? `<span class="pill">${c.scene}/${c.scenes}</span>` : ""}
+        <span class="pill ${c.status}">${c.pill}</span>
+
+      </div>
+      <div class="prompt" title="${esc(c.expanded)}">${c.generated ? "filler" : "by @" + esc(c.author_label || "viewer")}</div>
+    </div>`).join("");
+}
+
+function renderChat(state) {
+  const list = el("chat-list");
+  if (!state.chat.length) {
+    list.innerHTML = '<div class="empty">Type an idea to put it on the stream.</div>';
+    return;
+  }
+  const atBottom = list.scrollHeight - list.scrollTop - list.clientHeight < 40;
+  const me = (el("who").value.trim() || "viewer");
+  list.innerHTML = state.chat.map(m => {
+    if (m.kind === "viewer" || m.kind === "filler") {
+      return `<div class="msg ${esc(m.kind)}"><span class="who">${esc(m.author)}</span> ${esc(short(m.text, 110))}</div>`;
+    }
+    // An error addressed to one viewer is that viewer's business; the feed is
+    // shared, so everyone else is spared it.
+    if (m.kind === "error" && m.author && m.author !== me) return "";
+    return `<div class="msg ${esc(m.kind)}">${esc(m.text)}</div>`;
+  }).join("");
+  if (atBottom) list.scrollTop = list.scrollHeight;
+}
+
+function renderPlayback() {
+  const np = playbackClip;
+  const hasVideo = video.readyState >= 2;
+  el("dot").className = "dot" + (hasVideo && np !== null ? " on" : "");
+  el("livetext").textContent = playbackError ? "playback error" :
+    (!hasVideo ? "loading" : np === null ? "idle" :
+      video.paused ? "paused" : buffering ? "buffering" : "on air");
+  if (np) {
+    const who = np.generated ? "filler" : ("requested by " + (np.author_label || "viewer"));
+    el("np-title").textContent = `now playing: ${short(label(np), 72)} (${who})`;
+    el("np-title").title = np.title ? (np.title + " — " + (np.expanded || "")) : (np.expanded || "");
+    const bits = [];
+    if (np.scene && np.scenes > 1) bits.push(`scene ${np.scene}/${np.scenes}`);
+    if (typeof np.seconds === "number") bits.push(np.seconds.toFixed(1) + "s");
+    el("np-meta").textContent = bits.join(" · ");
+  } else {
+    el("np-title").textContent = playbackError || (np === null ? "Waiting for the first clip" :
+      hasVideo ? "Waiting for title metadata" : "Waiting for video");
+    el("np-title").title = "";
+    el("np-meta").textContent = "";
+  }
+}
+
+function render(state) {
+  const s = state.stats || {};
+  if (s.generation_capacity != null) {
+    el("queue-count").title =
+      `generation ${s.generation_queued}/${s.generation_capacity} · ` +
+      `playout ${s.playout_queued}/${s.playout_capacity}`;
+  }
+  renderQueue(state);
+  renderChat(state);
+}
+
+// One socket, reconnecting forever: the page outlives any single connection.
+let lastState = null;
+let lastSeq = -1;
+
+function connect() {
+  const proto = location.protocol === "https:" ? "wss" : "ws";
+  const socket = new WebSocket(`${proto}://${location.host}/state`);
+  socket.onmessage = (e) => {
+    try {
+      const next = JSON.parse(e.data);
+      // Keep chat and queue snapshots in order; playback has its own cues.
+      if (typeof next.seq === "number" && next.seq <= lastSeq) return;
+      if (typeof next.seq === "number") lastSeq = next.seq;
+      lastState = next; render(lastState);
+    } catch (_) {}
+  };
+  socket.onclose = () => { lastSeq = -1; setTimeout(connect, 2000); };
+}
+connect();
+startPlayback();
+
+// Debugging reads the cue-driven title; it never supplies a playback clock.
+const DEBUG = new URLSearchParams(location.search).has("debug");
+if (DEBUG) {
+  const box = el("debug");
+  box.hidden = false;
+  setInterval(() => {
+    const buf = video.buffered.length
+      ? (video.buffered.end(video.buffered.length - 1) - video.currentTime).toFixed(1) + "s"
+      : "none";
+    const timing = stopMetadata?.inspect?.();
+    const tracks = timing?.tracks || [];
+    box.textContent = [
+      "title source: timed ID3",
+      `playback ${video.currentTime.toFixed(3)}s · buffer ahead ${buf}`,
+      `clip: ${playbackClip ? playbackClip.clip_id : playbackClip === null ? "black" : "pending"}`,
+      `player: ${window._hls ? "hls.js" : "native"} · ready ${video.readyState}`,
+      `presented frame: ${timing?.frameTime?.toFixed(6) ?? "none"}s`,
+      `metadata: ${tracks.length} tracks · ${tracks.map(t => `${t.count} cues (${t.start?.toFixed(3) ?? "?"}s...)`).join(", ")}`,
+    ].join("\n");
+  }, 500);
+}
+
+// The queue is reference material; chat is what people use. On a narrow
+// screen it starts collapsed so the video and the chat box fit one screen.
+const queueCard = document.getElementById("queue");
+if (!window.matchMedia("(max-width: 900px), (orientation: landscape) and (max-height: 600px)").matches) {
+  queueCard.classList.remove("collapsed");
+}
+document.getElementById("queue-head").addEventListener("click",
+  () => queueCard.classList.toggle("collapsed"));
+
+// ---------------------------------------------------------------- chat box
+// A per-browser default name. Everyone used to fall back to the literal
+// "viewer", which put every anonymous viewer in one cooldown bucket -- two
+// people typing meant one of them was silently rate-limited by the other.
+let saved = localStorage.getItem("fasth3-name");
+if (!saved) {
+  saved = "viewer-" + Math.random().toString(36).slice(2, 6);
+  try { localStorage.setItem("fasth3-name", saved); } catch (_) {}
+}
+el("who").value = saved;
+
+// The send box locks itself while this viewer is on cooldown. Doing it here,
+// rather than reporting a refusal into the chat feed, keeps one person's
+// rate-limit out of everybody else's view -- the feed is shared.
+const sendButton = el("chat-form").querySelector("button");
+const sendLabel = sendButton.textContent;
+let cooldownUntil = 0;
+
+function refreshSendState() {
+  const left = Math.ceil((cooldownUntil - Date.now()) / 1000);
+  if (left > 0) {
+    sendButton.disabled = true;
+    el("text").disabled = true;
+    sendButton.textContent = left + "s";
+  } else if (sendButton.disabled) {
+    sendButton.disabled = false;
+    el("text").disabled = false;
+    sendButton.textContent = sendLabel;
+  }
+}
+setInterval(refreshSendState, 250);
+
+el("chat-form").addEventListener("submit", async (event) => {
+  event.preventDefault();
+  if (Date.now() < cooldownUntil) return;
+  const author = el("who").value.trim() || "viewer";
+  const text = el("text").value.trim();
+  if (!text) return;
+  localStorage.setItem("fasth3-name", author);
+  const previous = text;
+  el("text").value = "";
+  try {
+    const res = await fetch("/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ author, text }),
+    });
+    if (res.status === 429) {
+      // Rate-limited: keep what they typed, and lock the box until it lifts.
+      const body = await res.json().catch(() => ({}));
+      cooldownUntil = Date.now() + (body.retry_after || 5) * 1000;
+      el("text").value = previous;
+      refreshSendState();
+    }
+  } catch (_) { /* the socket's next snapshot tells the real story */ }
+});
+</script>
+</body>
+</html>
diff --git a/apps/infinite_livestream/infinite_livestream/web/logo.svg b/apps/infinite_livestream/infinite_livestream/web/logo.svg
new file mode 100644
index 000000000..0b8b058b5
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/web/logo.svg
@@ -0,0 +1,18 @@
+<svg width="252" height="105" viewBox="0 0 252 105" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M89.4843 55.5457H101.361L87.7028 101H74.638L89.4843 55.5457Z" fill="#356CFF"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M96.0167 1.00057H112.645L118.583 48.273H104.924L103.737 39.7882H79.9827L67.5117 55.5457H85.3273L43.1638 101H28.3174L22.3789 55.5457H33.6621L38.4129 91.3031L58.604 68.2729H44.3515L96.0167 1.00057ZM100.768 13.1217L87.7028 29.4852H103.143L100.768 13.1217Z" fill="#356CFF"/>
+<path d="M37.2252 1.00057L22.3789 48.273H36.0375L40.7884 30.6974L62.6727 30.6974L69.6727 21.0005L43.7576 21.0004L46.7269 11.9096L77.6727 11.9096L86 1.00057L37.2252 1.00057Z" fill="#356CFF"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M108.488 55.5457L94.2351 101C94.2351 101 105.518 101 120.959 101C136.399 101 144.078 93.0133 148.276 79.788C152.432 68.0157 153.027 55.5457 136.399 55.5457C119.771 55.5457 108.488 55.5457 108.488 55.5457ZM109.081 90.697L116.802 65.8487C116.802 65.8487 120.959 65.8487 132.242 65.8487C143.525 65.8487 137.586 78.5759 135.211 84.0304C133.307 88.4021 127.491 90.697 122.74 90.697C117.989 90.697 109.081 90.697 109.081 90.697Z" fill="#356CFF"/>
+<path d="M173.188 1.00056L168.625 11.9096C168.625 11.9096 149.386 11.9092 142.525 11.9095C135.664 11.9098 136.586 20.3944 141.337 20.3944H159.747C168.654 20.3944 166.961 33.6899 163.904 38.5761C160.467 44.0675 157.371 48.273 148.463 48.273L125.188 48.273L124 37.97L147.87 37.97C153.808 37.97 156.184 29.4852 151.433 29.4852H131.836C120.142 29.4852 125.897 1.00043 141.337 1.00043L173.188 1.00056Z" fill="#356CFF"/>
+<path d="M179.938 1.00056L175.688 11.9096L191.221 11.9096L179.938 48.273H192.409L203.692 11.9096L219.132 11.9095L223.289 1.00043L179.938 1.00056Z" fill="#356CFF"/>
+<path d="M161.341 55.5457H202.845L198.5 65.8487H169.654L167.279 73.7268H188.5L184.749 82.8177H164.31L161.934 90.697H190.251L186.624 101H146.494L161.341 55.5457Z" fill="#356CFF"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M230.821 54.9391C255.169 54.9391 251.776 67.0602 249.231 77.9692C246.686 88.8783 240.917 101 217.757 101C194.596 101 195.606 88.8783 199.347 77.9692C203.089 67.0602 206.473 54.9391 230.821 54.9391ZM237.948 77.9692C239.984 70.6965 240.917 65.242 228.446 65.242C215.975 65.242 211.818 71.9087 210.037 77.9692C208.255 84.0298 208.255 91.3025 219.538 91.3025C230.821 91.3025 235.911 85.2419 237.948 77.9692Z" fill="#356CFF"/>
+<path d="M173.188 1.00056L168.625 11.9096C168.625 11.9096 149.386 11.9092 142.525 11.9095C135.664 11.9098 136.586 20.3944 141.337 20.3944M173.188 1.00056C173.188 1.00056 156.777 1.00043 141.337 1.00043M173.188 1.00056L141.337 1.00043M141.337 20.3944C146.088 20.3944 150.839 20.3944 159.747 20.3944M141.337 20.3944H159.747M159.747 20.3944C168.654 20.3944 166.961 33.6899 163.904 38.5761C160.467 44.0675 157.371 48.273 148.463 48.273M148.463 48.273C139.556 48.273 125.188 48.273 125.188 48.273M148.463 48.273L125.188 48.273M125.188 48.273L124 37.97M124 37.97C124 37.97 141.931 37.97 147.87 37.97M124 37.97L147.87 37.97M147.87 37.97C153.808 37.97 156.184 29.4852 151.433 29.4852M151.433 29.4852C146.682 29.4852 138.962 29.4852 131.836 29.4852M151.433 29.4852H131.836M131.836 29.4852C120.142 29.4852 125.897 1.00043 141.337 1.00043M37.2252 1.00057L22.3789 48.273H36.0375L40.7884 30.6974L62.6727 30.6974L69.6727 21.0005L43.7576 21.0004L46.7269 11.9096L77.6727 11.9096L86 1.00057L37.2252 1.00057ZM96.0167 1.00057H112.645L118.583 48.273H104.924L103.737 39.7882H79.9827L67.5117 55.5457H85.3273L43.1638 101H28.3174L22.3789 55.5457H33.6621L38.4129 91.3031L58.604 68.2729H44.3515L96.0167 1.00057ZM87.7028 29.4852L100.768 13.1217L103.143 29.4852H87.7028ZM89.4843 55.5457H101.361L87.7028 101H74.638L89.4843 55.5457ZM108.488 55.5457L94.2351 101C94.2351 101 105.518 101 120.959 101C136.399 101 144.078 93.0133 148.276 79.788C152.432 68.0157 153.027 55.5457 136.399 55.5457C119.771 55.5457 108.488 55.5457 108.488 55.5457ZM116.802 65.8487L109.081 90.697C109.081 90.697 117.989 90.697 122.74 90.697C127.491 90.697 133.307 88.4021 135.211 84.0304C137.586 78.5759 143.525 65.8487 132.242 65.8487C120.959 65.8487 116.802 65.8487 116.802 65.8487ZM179.938 1.00056L175.688 11.9096L191.221 11.9096L179.938 48.273H192.409L203.692 11.9096L219.132 11.9095L223.289 1.00043L179.938 1.00056ZM161.341 55.5457H202.845L198.5 65.8487H169.654L167.279 73.7268H188.5L184.749 82.8177H164.31L161.934 90.697H190.251L186.624 101H146.494L161.341 55.5457ZM230.821 54.9391C255.169 54.9391 251.776 67.0602 249.231 77.9692C246.686 88.8783 240.917 101 217.757 101C194.596 101 195.606 88.8783 199.347 77.9692C203.089 67.0602 206.473 54.9391 230.821 54.9391ZM228.446 65.242C240.917 65.242 239.984 70.6965 237.948 77.9692C235.911 85.2419 230.821 91.3025 219.538 91.3025C208.255 91.3025 208.255 84.0298 210.037 77.9692C211.818 71.9087 215.975 65.242 228.446 65.242Z" stroke="#356CFF" stroke-width="1.18771"/>
+<path d="M15.2524 55.5451L21.191 100.999L24.7541 100.999L18.8156 55.5451L15.2524 55.5451Z" fill="#356CFF" stroke="#356CFF" stroke-width="1.18771"/>
+<path d="M8.12646 55.5451L14.065 100.999L15.2527 100.999L9.31417 55.5451L8.12646 55.5451Z" fill="#356CFF" stroke="#356CFF" stroke-width="1.18771"/>
+<path d="M1 55.5451L6.93853 100.999L7.53239 100.999L1.59385 55.5451L1 55.5451Z" fill="#356CFF" stroke="#356CFF" stroke-width="0.593853"/>
+<path d="M15.2524 48.2724L30.0988 1H33.6619L18.8156 48.2724H15.2524Z" fill="#356CFF" stroke="#356CFF" stroke-width="1.18771"/>
+<path d="M8.12646 48.2724L22.9728 1H24.1605L9.31417 48.2724H8.12646Z" fill="#356CFF" stroke="#356CFF" stroke-width="1.18771"/>
+<path d="M1 48.2724L15.8463 1H16.4402L1.59385 48.2724H1Z" fill="#356CFF" stroke="#356CFF" stroke-width="0.593853"/>
+<path d="M85.3271 55.5457H67.5116L87 12.7363L44.3513 68.2729H58.6038L43.1636 101L85.3271 55.5457Z" fill="#FDC717" stroke="#FDC717" stroke-width="1.18771" stroke-miterlimit="16"/>
+</svg>
diff --git a/apps/infinite_livestream/infinite_livestream/web/metadata.js b/apps/infinite_livestream/infinite_livestream/web/metadata.js
new file mode 100644
index 000000000..695ddb5af
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/web/metadata.js
@@ -0,0 +1,137 @@
+// hls.js and native Safari expose timed ID3 as metadata TextTrack cues.
+// Reuse those cues; where available, select by the actual presented frame PTS.
+(function (scope) {
+  "use strict";
+
+  function recordFromCue(cue) {
+    try {
+      const value = cue.value || JSON.parse(cue.text || "null");
+      if (!value || value.key !== "TXXX" || typeof value.data !== "string") return undefined;
+      if (value.info && value.info !== "infinite-livestream") return undefined;
+      const record = JSON.parse(value.data);
+      if (record.version !== 1) return undefined;
+      if (record.clip === null) return record;
+      const clip = record.clip;
+      if (!clip || typeof clip.clip_id !== "string" || typeof clip.title !== "string" ||
+          typeof clip.prompt !== "string" || typeof clip.generated !== "boolean") return undefined;
+      return record;
+    } catch (_) {
+      return undefined;
+    }
+  }
+
+  function watch(video, onChange) {
+    const tracks = new Map();
+    let previous;
+    let disposed = false;
+    const frameClock = typeof video.requestVideoFrameCallback === "function";
+    let frameTime;
+    let frameCallback;
+
+    function presented(_now, metadata) {
+      frameTime = Number.isFinite(metadata.mediaTime) ? metadata.mediaTime : undefined;
+      update();
+      if (!disposed) frameCallback = video.requestVideoFrameCallback(presented);
+    }
+
+    function update() {
+      if (disposed) return;
+      let selected;
+      let latest = -Infinity;
+      if (video.readyState >= 2) {
+        // Firefox can display a segment's first frame after a paused seek while
+        // currentTime is still just before its PTS. activeCues then names the
+        // old clip. Presented-frame time resolves this without adjusting clocks.
+        const hasFrame = frameTime !== undefined;
+        const at = Math.round(frameTime * 1e6);
+        for (const track of tracks.keys()) {
+          const cues = (hasFrame ? track.cues : track.activeCues) || [];
+          let end = cues.length;
+          if (hasFrame) {
+            // TextTrackCueList is sorted by start time. Binary search avoids
+            // scanning a long viewer's entire buffered history every frame.
+            let lo = 0;
+            while (lo < end) {
+              const mid = (lo + end) >>> 1;
+              // Browsers report frame timestamps at microsecond resolution.
+              if (Math.round(cues[mid].startTime * 1e6) <= at) lo = mid + 1;
+              else end = mid;
+            }
+          }
+          for (let i = end - 1; i >= 0; i--) {
+            const cue = cues[i];
+            if (hasFrame && Math.round(cue.endTime * 1e6) <= at) continue;
+            const record = recordFromCue(cue);
+            // Native players can leave older ID3 cues open. Prefer the latest
+            // applicable record, including the explicit empty/black record.
+            if (record && cue.startTime >= latest) {
+              latest = cue.startTime;
+              selected = record.clip;
+            }
+            if (hasFrame && record) break;
+          }
+        }
+      }
+      const key = selected === undefined ? undefined : JSON.stringify(selected);
+      if (key !== previous) {
+        previous = key;
+        onChange(selected);
+      }
+    }
+
+    function add(track) {
+      if (track.kind !== "metadata" || tracks.has(track)) return;
+      track.mode = "hidden";
+      track.addEventListener("cuechange", update);
+      tracks.set(track, update);
+      update();
+    }
+    function added(event) { add(event.track); }
+    function removed(event) {
+      event.track.removeEventListener("cuechange", update);
+      tracks.delete(event.track);
+      update();
+    }
+    function seeked() {
+      // Some browsers do not issue a frame callback for a paused seek. Their
+      // cue clock remains the fallback until another presented frame arrives.
+      frameTime = undefined;
+      update();
+    }
+    function emptied() {
+      frameTime = undefined;
+      previous = undefined;
+      onChange(undefined);
+    }
+
+    video.textTracks.addEventListener("addtrack", added);
+    video.textTracks.addEventListener("removetrack", removed);
+    video.addEventListener("loadeddata", update);
+    video.addEventListener("seeked", seeked);
+    video.addEventListener("playing", update);
+    video.addEventListener("emptied", emptied);
+    onChange(undefined);
+    for (const track of Array.from(video.textTracks)) add(track);
+    if (frameClock) frameCallback = video.requestVideoFrameCallback(presented);
+
+    const stop = () => {
+      disposed = true;
+      if (frameClock) video.cancelVideoFrameCallback(frameCallback);
+      video.textTracks.removeEventListener("addtrack", added);
+      video.textTracks.removeEventListener("removetrack", removed);
+      video.removeEventListener("loadeddata", update);
+      video.removeEventListener("seeked", seeked);
+      video.removeEventListener("playing", update);
+      video.removeEventListener("emptied", emptied);
+      for (const track of tracks.keys()) track.removeEventListener("cuechange", update);
+      tracks.clear();
+    };
+    stop.inspect = () => ({
+      frameTime,
+      tracks: Array.from(tracks.keys(), track => ({ count: track.cues?.length || 0, start: track.cues?.[0]?.startTime })),
+    });
+    return stop;
+  }
+
+  scope.LivestreamMetadata = { watch };
+})(globalThis);
diff --git a/apps/infinite_livestream/infinite_livestream/webapp.py b/apps/infinite_livestream/infinite_livestream/webapp.py
new file mode 100644
index 000000000..d626b1aa8
--- /dev/null
+++ b/apps/infinite_livestream/infinite_livestream/webapp.py
@@ -0,0 +1,261 @@
+"""The watch page: video on the left, live chat and queue on the right.
+
+Queue and chat state are folded from the engine's own message stream --
+the mirror registers with `Engine.add_listener` and rebuilds itself from
+`state_update`, `queue_update` and the `clip_*` messages -- so this module
+holds no playback clock. Now-playing titles travel with the video as timed ID3.
+
+One HTTP origin serves the page, the HLS segments, the state websocket and the
+chat endpoint, because a tunnel proxies one port: publishing the whole demo is
+pointing `cloudflared` at this server and nothing else.
+
+Routes:
+    GET  /              the page
+    GET  /assets/<file> the logo and favicon it references
+    GET  /hls/<file>    the playlist and segments (written by `sink.py`)
+    GET  /healthz       whether the engine is loaded
+    WS   /state         one JSON snapshot on connect, then one per change
+    POST /chat          {"author": str, "text": str} -> a prompt for the
+                        director; 429 with `retry_after` when that viewer is
+                        still on cooldown, answered here so the refusal stays
+                        out of the shared chat feed
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import time
+from collections import deque
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse, JSONResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+from .chat import WebChat
+from .metadata import clip_view
+
+logger = logging.getLogger("infinite_livestream.webapp")
+
+WEB_DIR = Path(__file__).parent / "web"
+# Chat lines kept for late joiners. The panel is a live feed, not a log: enough
+# to show the room is alive, not so much that a new viewer scrolls history.
+CHAT_HISTORY = 60
+
+
+class DemoState:
+    """The panel's view of the model, rebuilt purely from the message stream."""
+
+    def __init__(self) -> None:
+        self.generation: list[dict[str, Any]] = []
+        self.playout: list[dict[str, Any]] = []
+        self.stats: dict[str, Any] = {}
+        self.chat: deque[dict[str, Any]] = deque(maxlen=CHAT_HISTORY)
+        self.connected = False
+
+    @property
+    def generating(self) -> dict[str, Any] | None:
+        """What the GPUs are building right now.
+
+        Builds consume the generation queue front-first, one at a time, so the
+        front entry is the clip in flight -- there is no separate message that
+        announces a build starting.
+        """
+        return self.generation[0] if self.generation else None
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "connected": self.connected,
+            "generating": self.generating,
+            "generation": self.generation,
+            "playout": self.playout,
+            "stats": self.stats,
+            "chat": list(self.chat),
+        }
+
+    def note(self, kind: str, text: str, author: str = "") -> None:
+        self.chat.append({"kind": kind, "author": author, "text": text, "at": time.time()})
+
+    def on_message(self, kind: str, data: dict[str, Any]) -> None:
+        """Fold one engine message into the mirror. Never raises."""
+        if kind == "queue_update":
+            self.generation = [clip_view(c) for c in data.get("generation", [])]
+            self.playout = [clip_view(c) for c in data.get("playout", [])]
+        elif kind == "state_update":
+            self.connected = True
+            self.stats = {
+                "generation_queued": data.get("generation_queued"),
+                "generation_capacity": data.get("generation_capacity"),
+                "playout_queued": data.get("playout_queued"),
+                "playout_capacity": data.get("playout_capacity"),
+                "clips_played": data.get("clips_played"),
+                "width": data.get("width"),
+                "height": data.get("height"),
+            }
+        elif kind == "clip_queued":
+            # One line per group, not per scene. Viewer submissions are
+            # already echoed by the POST handler, so only filler lands here.
+            clip = clip_view(data.get("clip", {}))
+            scene = clip.get("scene")
+            if clip["generated"] and (scene is None or scene == 1):
+                self.note("filler", clip["prompt"], author="filler")
+        elif kind == "clip_failed":
+            # Failures stay: a viewer whose request vanished deserves to know.
+            clip = clip_view(data.get("clip", {}))
+            if not clip["generated"]:
+                self.note("error", f"build failed: {clip['title'] or clip['clip_id'][:8]}")
+
+
+class DemoWeb:
+    """The web server: the page, the HLS files, the state socket, the chat box."""
+
+    def __init__(self, chat: WebChat, hls_dir: Path | str, *, host: str = "0.0.0.0", port: int = 8081) -> None:
+        self.state = DemoState()
+        self._chat = chat
+        self._hls_dir = Path(hls_dir)
+        self._host, self._port = host, port
+        # Set by `main.py` once the director exists; until then nothing is
+        # rate-limited, which is the right default for a page with no engine.
+        self.cooldown_remaining: Callable[[str], float] = lambda author: 0.0
+        self._clients: set[WebSocket] = set()
+        self._loop: asyncio.AbstractEventLoop | None = None
+        # One writer, never a task per update: a task per broadcast let two
+        # snapshots race, and a client receiving the older one second saw the
+        # panel jump back a clip. The flag also coalesces bursts.
+        self._dirty: asyncio.Event | None = None
+        self._send_lock: asyncio.Lock | None = None
+        self._seq = 0
+        self.app = self._build_app()
+
+    # ------------------------------------------------------------------ wiring
+
+    def listener(self, kind: str, data: dict[str, Any]) -> None:
+        """Hand to `Engine.add_listener`. Folds, then pushes to the page."""
+        try:
+            self.state.on_message(kind, data)
+        except Exception:
+            logger.exception("[web] failed to fold %s", kind)
+            return
+        self.broadcast()
+
+    def broadcast(self) -> None:
+        """Mark the state dirty; the writer sends it. Safe from any thread."""
+        loop, dirty = self._loop, self._dirty
+        if loop is None or dirty is None:
+            return
+        loop.call_soon_threadsafe(dirty.set)
+
+    async def _pump(self) -> None:
+        """The only thing that sends state, so snapshots can never overtake."""
+        assert self._dirty is not None
+        while True:
+            await self._dirty.wait()
+            self._dirty.clear()
+            if not self._clients:
+                continue
+            await self._send(self.state.snapshot())
+
+    async def _send(self, snapshot: dict[str, Any]) -> None:
+        assert self._send_lock is not None
+        async with self._send_lock:
+            self._seq += 1
+            snapshot["seq"] = self._seq
+            payload = json.dumps(snapshot)
+            for socket in list(self._clients):
+                try:
+                    await socket.send_text(payload)
+                except Exception:
+                    self._clients.discard(socket)
+
+    # -------------------------------------------------------------------- app
+
+    def _build_app(self) -> FastAPI:
+        app = FastAPI(title="FastH3 livestream")
+        self._hls_dir.mkdir(parents=True, exist_ok=True)
+        # The playlist must never be cached: it is rewritten every segment, and
+        # a cached copy strands the player on segments that have been deleted.
+        app.mount("/hls", StaticFiles(directory=str(self._hls_dir)), name="hls")
+
+        @app.get("/")
+        async def index() -> FileResponse:
+            """The watch page: video, chat and the queue on one origin.
+
+            Read from disk per request, so iterating on the markup needs no
+            restart.
+            """
+            return FileResponse(WEB_DIR / "index.html")
+
+        # The logo and the favicon the page references.
+        app.mount("/assets", StaticFiles(directory=str(WEB_DIR)), name="assets")
+
+        @app.get("/healthz")
+        async def healthz() -> JSONResponse:
+            return JSONResponse({"connected": self.state.connected})
+
+        @app.post("/chat")
+        async def chat(body: dict[str, Any]) -> JSONResponse:
+            author = str(body.get("author") or "viewer")[:32]
+            text = str(body.get("text") or "")[:800]
+            if not text.strip():
+                return JSONResponse({"ok": False, "error": "empty"}, status_code=400)
+            # Answered here rather than downstream: the chat feed is shared, so
+            # rate-limiting somebody in it would put their business in front of
+            # every other viewer. The sender is told privately, in the reply to
+            # their own request, and their page stops them from sending.
+            wait = self.cooldown_remaining(author)
+            if wait > 0:
+                return JSONResponse({"ok": False, "error": "cooldown", "retry_after": round(wait, 1)}, status_code=429)
+            accepted = self._chat.submit(author, text)
+            self.state.note("viewer" if accepted else "error",
+                            text if accepted else f"dropped (queue full): {text[:80]}",
+                            author=author)
+            self.broadcast()
+            return JSONResponse({"ok": accepted})
+
+        @app.websocket("/state")
+        async def state_socket(socket: WebSocket) -> None:
+            await socket.accept()
+            self._clients.add(socket)
+            try:
+                await self._send(self.state.snapshot())
+                while True:
+                    # The page never sends; this is just how a disconnect is noticed.
+                    await socket.receive_text()
+            except (WebSocketDisconnect, Exception):
+                pass
+            finally:
+                self._clients.discard(socket)
+
+        @app.middleware("http")
+        async def no_cache_playlist(request, call_next) -> Response:
+            response = await call_next(request)
+            if request.url.path.endswith(".m3u8") or request.url.path in ("/", ""):
+                response.headers["Cache-Control"] = "no-store"
+            if request.url.path.startswith("/hls/"):
+                if request.url.path.endswith(".ts"):
+                    response.headers["Content-Type"] = "video/mp2t"
+                elif request.url.path.endswith(".m3u8"):
+                    response.headers["Content-Type"] = "application/vnd.apple.mpegurl"
+            return response
+
+        return app
+
+    async def run(self) -> None:
+        """Serve until cancelled. One task in `main.py`'s gather."""
+        import uvicorn
+
+        self._loop = asyncio.get_running_loop()
+        self._dirty = asyncio.Event()
+        self._send_lock = asyncio.Lock()
+        pump = asyncio.create_task(self._pump(), name="webapp-pump")
+        config = uvicorn.Config(self.app, host=self._host, port=self._port, log_level="warning", access_log=False)
+        server = uvicorn.Server(config)
+        logger.info("[web] serving the demo page on http://%s:%d", self._host, self._port)
+        try:
+            await server.serve()
+        finally:
+            pump.cancel()
diff --git a/apps/infinite_livestream/pyproject.toml b/apps/infinite_livestream/pyproject.toml
new file mode 100644
index 000000000..35dd2928b
--- /dev/null
+++ b/apps/infinite_livestream/pyproject.toml
@@ -0,0 +1,34 @@
+[project]
+name = "infinite-livestream"
+version = "0.1.0"
+description = "Chat-driven FastH3 infinite livestream: prompts in, continuous broadcast out."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "av>=17,<19",
+    "fastapi>=0.115,<1",
+    "fastvideo>=0.2.1",
+    "numpy>=1.24",
+    "openai>=1.40",
+    "pyyaml>=6.0",
+    "uvicorn[standard]>=0.30,<1",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest>=8.0",
+]
+
+[project.scripts]
+infinite-livestream-server = "infinite_livestream.server_entry:cli"
+
+[tool.uv]
+package = false
+
+[tool.uv.sources]
+fastvideo = { workspace = true }
+
+[tool.pytest.ini_options]
+markers = [
+    "gpu: requires real GPU + model weights; skip in CI",
+]
diff --git a/fastvideo/tests/contract/test_merge_ci_plan.py b/fastvideo/tests/contract/test_merge_ci_plan.py
index 967f1ba4a..9fd5713ec 100644
--- a/fastvideo/tests/contract/test_merge_ci_plan.py
+++ b/fastvideo/tests/contract/test_merge_ci_plan.py
@@ -213,6 +213,12 @@ def test_dreamverse_change_relies_on_its_existing_fastcheck_e2e_lane():
     assert plan.encoded_lanes() == ",none,"
 
 
+def test_infinite_livestream_change_relies_on_the_unit_fastcheck_lane():
+    plan = PLAN_MERGE_CI.classify_paths(["apps/infinite_livestream/infinite_livestream/sink.py"])
+
+    assert plan.encoded_lanes() == ",none,"
+
+
 def test_local_only_parity_scaffold_does_not_trigger_unrelated_gpu_lanes():
     plan = PLAN_MERGE_CI.classify_paths(["tests/local_tests/flux/test_flux_dev_component_loaders.py"])
 
diff --git a/pyproject.toml b/pyproject.toml
index bf5fdecaf..87dbba42a 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -110,7 +110,7 @@ dependencies = [
 prerelease = "allow"
 
 [tool.uv.workspace]
-members = ["apps/dreamverse"]
+members = ["apps/dreamverse", "apps/infinite_livestream"]
 
 [tool.uv.sources]
 # PyPI's aarch64 fastvideo-kernel wheels do not cover the NVIDIA DGX Spark /
@@ -153,7 +153,7 @@ lint = [
 
 test = [
     "av",
-    "openai==3.6.0",  # OpenAI video-client compatibility tests; no cloud requests.
+    "openai==3.6.0",  # OpenAI video-client compatibility tests and the livestream app's moderator/upsampler tests; no cloud requests.
     "pytorch-msssim>=1.0.0",
     "pytest",
     "pandas",
@@ -222,6 +222,14 @@ streaming = [
     "websockets",
 ]
 
+infinite-livestream = [
+    "av>=17,<19",
+    "fastapi>=0.115,<1",
+    "openai>=1.40",
+    "pyyaml>=6.0",
+    "uvicorn[standard]>=0.30,<1",
+]
+
 dreamverse = [
     "uvicorn[standard]>=0.41.0",
     "cerebras-cloud-sdk",
@@ -245,16 +253,19 @@ mlx = [
 
 [project.scripts]
 fastvideo = "fastvideo.entrypoints.cli.main:main"
+infinite-livestream-server = "infinite_livestream.server_entry:cli"
 dreamverse-server = "dreamverse.server_entry:cli"
 dreamverse-mock-server = "dreamverse.mock_server:cli"
 
 [tool.setuptools.packages.find]
-where = [".", "apps/dreamverse"]
-exclude = ["assets*", "docker*", "docs", "scripts*", "apps*", "dreamverse.tests*"]
+where = [".", "apps/dreamverse", "apps/infinite_livestream"]
+exclude = ["assets*", "docker*", "docs", "scripts*", "apps*", "dreamverse.tests*",
+           "infinite_livestream.tests*"]
 
 [tool.setuptools.package-data]
 "fastvideo.entrypoints.openai" = ["static/*.html", "static/*.css", "static/*.js"]
 dreamverse = ["prompts/*.md"]
+infinite_livestream = ["configs/*.yaml", "presets/*.json", "web/*"]
 "fastvideo.third_party.rife_mlx" = ["LICENSE"]
 "fastvideo.third_party.taehv" = ["LICENSE"]