Upload folder using huggingface_hub

.gitattributes

@@ -33,3 +33,13 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/desk-laptop.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/night-drive.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/rayuela.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/street-parked-car.mp4 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp3 filter=lfs diff=lfs merge=lfs -text
+src/small_cuts/seed_media/the-stumble.mp4 filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+uv.lock
+
+# Models / large artifacts
+*.gguf
+models/
+flagged/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Env — never commit secrets
+.env
+.env.*
+.playwright-mcp/
+ui-proposal.jpeg
+aimode-content.yml

.hfignore

@@ -0,0 +1,18 @@
+.git/
+.venv/
+.github/
+.claude/
+ios/
+kb/
+docs/
+modal_app/
+tests/
+scripts/
+CLAUDE.md
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.playwright-mcp/
+xcodebuild-*.log
+*.mov
+*.mp4

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Crespo Macaya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,13 +1,154 @@
 ---
 title: Small Cuts
-emoji: 🐠
-colorFrom: purple
-colorTo: yellow
+emoji: 🎬
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
 sdk_version: 6.18.0
-python_version: '3.13'
 app_file: app.py
-pinned: false
+hf_oauth: true
+pinned: true
+license: mit
+short_description: A deadpan narrator for your life, from small open models.
+models:
+  - Qwen/Qwen3-VL-8B-Instruct
+tags:
+  - track:wood
+  - sponsor:modal
+  - achievement:offgrid
+  - achievement:offbrand
+  - achievement:llama
+  - achievement:fieldnotes
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Small Cuts 🎬
+
+> *"And that was the moment Carlos realized the coffee had been decaf all along."*
+
+**Small Cuts** turns first-person moments into grounded, cinematic, **spoken** narration —
+an omniscient, slightly-too-honest narrator in the spirit of *The Invention of Lying* —
+using only **small (≤32B) open models**. No script, no cloud LLM: a small vision-language
+model watches your moment and a small text-to-speech voice speaks the line, the way a film
+narrator would if your life were the film.
+
+There is exactly **one narrator**: a single deadpan, unnamed voice. No menus, no director to
+pick. You point at what's happening; it tells you what it means.
+
+This is a submission to the **Build Small Hackathon** ("Small Models, Big Adventures" —
+Gradio × Hugging Face).
+
+---
+
+## Two paths, one finished cut
+
+Small Cuts is a deliberate comparison of two techniques that both land as the **same** finished
+artifact in this Space — a clip with a generated title, narration, Kokoro voice, synced
+captions, a library tile, and a source badge.
+
+| Path | Who | Channel | What it proves | Badge |
+|---|---|---|---|---|
+| **Whole video, one pass** | A judge, in this Space | Past events, any recording | It is **real and running** — verify it yourself, no access to the maker's hardware needed | `source="upload"` |
+| **Pieces + hints** | The wearer (Ray-Ban Meta glasses / iOS) | Clips from ~3s ago | The **soul** — embodied, off-grid, narrated in-ear *while the moment is still recent past* | `source="glasses"` |
+
+The public Space never reaches the maker's local hardware; the private home engine never exposes
+inference hardware to the public. Same output shape, two very different journeys.
+
+---
+
+## How judges can try it
+
+The Space is the **view platform + library** half of the loop:
+
+- **A live stage** with the current moment and movie-style subtitles over a constant dark bar,
+  advancing with the voice-over.
+- **Voice-over replay** in a compact custom player whose video, sound, captions, and progress all
+  share one audio clock.
+- **A public library** of real Ray-Ban Meta glasses moments, generated through the same local
+  engine path so the channel is never empty. Source clips and mark points are curated; the visible
+  titles, narration, voice, thumbnails, and clips are **produced by Small Cuts**.
+- **"Try it"** — a tucked-away, HF-login upload drawer. Sign in, drop a short video, and a private
+  **Modal** GPU service runs the real Qwen + Kokoro pipeline and replays your generated cut in the
+  same theater. This is the judge-verifiable path: no glasses or iOS required. **Privacy-first:**
+  your upload is narrated *only for your session* — it's never added to the public library or shown
+  to anyone else, and a refresh clears it. The library you browse is separate, curated, persistent
+  content (real glasses moments); your private try-it never mixes into it.
+
+---
+
+## Architecture in one glance
+
+```
+Ray-Ban Meta glasses ──image frames──▶  home engine (small VLM + TTS)  ──▶  narration in your ear
+                                              │
+                                              └──── finished cuts ────▶  the Space (watch · library)
+
+judge's browser ──short video──▶  Modal GPU (Qwen3-VL-8B + Kokoro)  ──▶  finished cut in the Space
+```
+
+You walk through a moment, tap **Action!**, then tap **Cut!** when the scene has a readable beat.
+The narrator watches a selected first-person frame and speaks one grounded, deadpan line back in
+your ear while the moment is still recent past. The finished cut lands in the Space as a short POV
+clip with synced captions, title, voice, and library thumbnail.
+
+---
+
+## How it was built
+
+| Piece | Choice | Why |
+|---|---|---|
+| Narrator (VLM) | `Qwen/Qwen3-VL-8B-Instruct` | Strong grounded captioning at **8B — well under 32B** |
+| Voice (TTS) | **Kokoro** (24 kHz) | Tiny, expressive, open; one signature deadpan delivery |
+| Space runtime | Gradio 6 on CPU | Public theater + library; uploads call Modal instead of warming models |
+| Judge upload service | **Modal** GPU app (`small-cuts-postcut`) | Finished-video verification path with real Qwen + Kokoro output |
+| Local live engine | FastAPI WS home node, **llama.cpp** | The in-ear loop + demo video; no cloud LLM/TTS API |
+| Capture | iOS app for Ray-Ban Meta glasses (`ios/SmallCuts/`) | First-person moments, the way it's meant to be lived |
+
+Built by **Carlos Crespo Macaya** as architect and lead. Development was accelerated with an
+AI toolchain — Claude (Opus) for design critique, Codex (GPT-5.x) for paired implementation,
+GLM for review, and Gemini for eval — all directed by Carlos.
+
+---
+
+## ≤32B compliance
+
+Every model is small and open-weight:
+
+- **Narrator:** `Qwen/Qwen3-VL-8B-Instruct` — **8B parameters**, comfortably under the 32B cap.
+- **Voice:** **Kokoro** — a tiny open TTS model.
+
+There is no cloud LLM anywhere in the loop. The live, in-ear path runs entirely on local hardware
+through **llama.cpp**; the judge upload path runs the same small models on a Modal GPU so reviewers
+can verify real output without touching the maker's machine.
+
+---
+
+## Hackathon compliance
+
+| Rule | How Small Cuts complies |
+|---|---|
+| Gradio app hosted as a Space under the org | Final submission promotes to `build-small-hackathon/small-cuts` after personal-profile staging passes |
+| Every model < 32B | 8B VLM narrator + small Kokoro TTS, all open weights |
+| Demo video | Filmed POV with Ray-Ban Meta glasses → narrated by the app *(link below)* |
+| Social post | Linked from this README *(link below)* |
+| Track 2 — **Thousand Token Wood** (`track:wood`) | Whimsical, delightful, AI-load-bearing, original |
+| Best Use of Modal (`sponsor:modal`) | The judge upload path runs Qwen + Kokoro on a Modal GPU |
+| Off the Grid (`achievement:offgrid`) | Live inference/TTS run on local hardware; the public Space reads finished cuts only |
+| Off-Brand (`achievement:offbrand`) | Custom cinematic frontend past the stock Gradio look |
+| Llama (`achievement:llama`) | The live engine runs through `llama.cpp` |
+| Field Notes (`achievement:fieldnotes`) | Public write-up — [field notes on the HF blog](https://huggingface.co/blog/build-small-hackathon/small-cuts-field-notes) |
+
+### Submission links
+
+- 📹 **Demo video (YouTube):** _TODO — add public link before submission_
+- 📣 **Social post (Reddit):** _TODO — add link before submission_
+- 📣 **Social post (LinkedIn):** _TODO — add link before submission_
+- 📝 **Field notes / write-up:** [hf.co/blog/build-small-hackathon/small-cuts-field-notes](https://huggingface.co/blog/build-small-hackathon/small-cuts-field-notes)
+
+> **Integrity note:** every preselected/hero clip in this Space is narrated by the **actual
+> Small Cuts pipeline** (real Qwen3-VL-8B + Kokoro output) — never hand-written narration.
+
+---
+
+## License
+
+Released under the **MIT License** — see [`LICENSE`](LICENSE) in the repository.

app.py

@@ -0,0 +1,101 @@
+"""Hugging Face Space entrypoint for Small Cuts.
+
+Local dev keeps the lazy/mock defaults. On a Space this module refuses unsafe
+CPU local inference and never lets startup failures crash-loop the container:
+
+- ``import spaces`` happens before anything touches torch (ZeroGPU hijack).
+- The narrator loads lazily inside the ``@spaces.GPU`` event handler.
+- TTS runs inside @spaces.GPU workers too (kokoro's torch use poisons
+  worker forks if it ever runs in the main process).
+"""
+
+import os
+import sys
+import warnings
+from pathlib import Path
+
+import gradio as gr
+from starlette.exceptions import StarletteDeprecationWarning
+
+ROOT = Path(__file__).resolve().parent
+SRC = ROOT / "src"
+if str(SRC) not in sys.path:
+    sys.path.insert(0, str(SRC))
+
+warnings.filterwarnings(
+    "ignore",
+    message=r".*HTTP_422_UNPROCESSABLE_ENTITY.*HTTP_422_UNPROCESSABLE_CONTENT.*",
+    category=StarletteDeprecationWarning,
+)
+
+ON_SPACE = bool(os.environ.get("SPACE_ID"))
+ENGINE_MODE = bool(os.environ.get("SMALL_CUTS_ENGINE_URL", "").strip())
+
+from small_cuts.hf_relay import RELAY_BUCKET_ENV  # noqa: E402
+
+RELAY_MODE = bool(os.environ.get(RELAY_BUCKET_ENV, "").strip())
+MODAL_UPLOAD_MODE = bool(os.environ.get("SMALL_CUTS_MODAL_API_URL", "").strip())
+VIEWER_ONLY_MODE = ENGINE_MODE or RELAY_MODE or MODAL_UPLOAD_MODE
+NEEDS_LOCAL_INFERENCE = not VIEWER_ONLY_MODE
+
+try:
+    import spaces  # noqa: F401  (must precede torch imports for ZeroGPU)
+except ImportError:  # local dev / CI: no ZeroGPU
+    spaces = None
+
+if ON_SPACE and NEEDS_LOCAL_INFERENCE:
+    os.environ.setdefault("SMALL_CUTS_BACKEND", "transformers")
+    os.environ.setdefault("SMALL_CUTS_TTS_BACKEND", "kokoro")
+
+from small_cuts.observability import capture_exception, init_sentry  # noqa: E402
+from small_cuts.space_hooks import install_relay_hooks  # noqa: E402
+from small_cuts.viewer import THEME, build_viewer_app  # noqa: E402
+
+init_sentry()
+
+STARTUP_ERROR: str | None = None
+
+
+def _allow_cpu_inference() -> bool:
+    return os.environ.get("SMALL_CUTS_ALLOW_CPU_INFERENCE", "").strip().lower() in (
+        "1",
+        "true",
+        "yes",
+    )
+
+
+def _validate_startup_mode() -> None:
+    if ON_SPACE and NEEDS_LOCAL_INFERENCE and spaces is None and not _allow_cpu_inference():
+        raise RuntimeError(
+            "refusing local inference on a Space without ZeroGPU; configure relay, engine, "
+            "or Modal upload mode, or set SMALL_CUTS_ALLOW_CPU_INFERENCE=1 explicitly"
+        )
+
+
+def _degraded_app(message: str) -> gr.Blocks:
+    with gr.Blocks(title="Small Cuts") as degraded:
+        gr.Markdown(
+            f"# Small Cuts is temporarily unavailable\n\nStartup configuration failed: `{message}`"
+        )
+    return degraded
+
+
+def _build_demo() -> gr.Blocks:
+    _validate_startup_mode()
+    # In engine/relay/upload modes the Space is a public reader and upload front door, so it must
+    # not warm local model weights. In local-inference mode, ZeroGPU loads lazily inside the
+    # Gradio handler decorated with @spaces.GPU.
+    app = build_viewer_app()
+    install_relay_hooks(app.app)
+    return app
+
+
+try:
+    demo = _build_demo()
+except Exception as exc:
+    capture_exception(exc)
+    STARTUP_ERROR = str(exc)
+    demo = _degraded_app(STARTUP_ERROR)
+
+if __name__ == "__main__":
+    demo.launch(theme=THEME)

pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "small-cuts"
+version = "0.1.0"
+description = "An omniscient cinematic narrator for moments of your life, powered by small open models (Build Small Hackathon)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "gradio>=5.0",
+    "itsdangerous>=2.2",
+    "pillow>=10.0",
+    "pillow-heif>=0.18",
+    "av>=12.0",
+    "huggingface-hub>=1.19",
+    "sentry-sdk>=2.0",
+    # core viewer dep: decodes seed durations + writes generated voice-overs (viewer.py),
+    # imported at module scope — must be in the base install (and CI), not just the tts extra.
+    "soundfile>=0.12",
+]
+
+[project.optional-dependencies]
+local = [
+    "transformers>=4.49",
+    "torch>=2.4",
+    "torchvision>=0.19",
+    "accelerate>=1.0",
+]
+tts = [
+    "kokoro>=0.9",
+    "soundfile>=0.12",
+]
+llama = [
+    "llama-cpp-python>=0.3",
+]
+engine = [
+    "fastapi>=0.110",
+    "uvicorn>=0.30",
+    "websockets>=12",
+    "jsonschema>=4.21",
+    "soundfile>=0.12",
+    "httpx>=0.27",
+]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+    "jsonschema>=4.21",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/small_cuts"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"docs/contracts/control.schema.json" = "small_cuts/contracts/control.schema.json"
+"docs/contracts/moment.schema.json" = "small_cuts/contracts/moment.schema.json"
+"docs/contracts/narrated-scene.schema.json" = "small_cuts/contracts/narrated-scene.schema.json"
+"docs/contracts/scene-audio.schema.json" = "small_cuts/contracts/scene-audio.schema.json"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]

requirements.txt

@@ -0,0 +1,10 @@
+# Hugging Face Space runtime for live-demo viewer mode. Gradio + spaces are
+# platform-managed; inference and TTS run on the Mac Studio engine.
+pillow>=10.0
+pillow-heif>=0.18
+av>=12.0
+httpx>=0.27
+huggingface-hub>=1.19
+itsdangerous>=2.2
+sentry-sdk>=2.0
+soundfile>=0.12

src/small_cuts/__init__.py

@@ -0,0 +1,9 @@
+"""Small Cuts — an omniscient cinematic narrator powered by small open models."""
+
+from pillow_heif import register_heif_opener
+
+# iPhones shoot HEIC by default; registering once here covers every entry
+# point (Gradio app, eval harness) that opens images through PIL.
+register_heif_opener()
+
+__version__ = "0.1.0"

src/small_cuts/_icons.py

@@ -0,0 +1,24 @@
+# ruff: noqa: E501
+"""Generated icon mask-image CSS (from Carlos's small_cuts_icon_set).
+
+Each glyph is a 24x24 SVG rendered as a CSS mask so it inherits `currentColor`
+via `.sc-icbtn` (see VIEWER_CSS). Regenerate from the icon set if it changes.
+"""
+
+ICON_CSS = """
+:root { --sc-ico-glasses-mask: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-glasses-view%22%20fill%3D%22none%22%3E%20%3Ctitle%20id%3D%22title-glasses-view%22%3EGlasses%20view%3C%2Ftitle%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M3.8%2012.5c.3-2.4%201.6-3.7%203.6-3.7h2.1c1.1%200%201.8.8%201.8%201.8v1.9c0%202-1.5%203.7-3.6%203.7S4%2014.6%203.8%2012.5Z%22%2F%3E%20%3Cpath%20d%3D%22M20.2%2012.5c-.3-2.4-1.6-3.7-3.6-3.7h-2.1c-1.1%200-1.8.8-1.8%201.8v1.9c0%202%201.5%203.7%203.6%203.7s3.7-1.6%203.9-3.7Z%22%2F%3E%20%3Cpath%20d%3D%22M11.3%2011h1.4%22%2F%3E%20%3Cpath%20d%3D%22M4.6%209.9%203%208.7M19.4%209.9%2021%208.7%22%2F%3E%20%3Cpath%20d%3D%22M7.1%2010.4h1.8M15.1%2010.4h1.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+:root { --sc-ico-upload-mask: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Ctitle%20id%3D%22title-upload-video%22%3EUpload%20video%3C%2Ftitle%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-glasses { -webkit-mask-image: var(--sc-ico-glasses-mask); mask-image: var(--sc-ico-glasses-mask); }
+.sc-ico-upload { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-upload-video%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2018.5H6.9a4.1%204.1%200%200%201-.8-8.1%205.9%205.9%200%200%201%2011.1-1.8%204.7%204.7%200%200%201%20.8%209.9h-.8%22%2F%3E%20%3Cpath%20d%3D%22M12%2018.5V9.2%22%2F%3E%20%3Cpath%20d%3D%22m8.9%2012.3%203.1-3.1%203.1%203.1%22%2F%3E%20%3Crect%20x%3D%2215.5%22%20y%3D%2215.2%22%20width%3D%224%22%20height%3D%223%22%20rx%3D%22.6%22%2F%3E%20%3Cpath%20d%3D%22m19.5%2016%201.4-.8v3l-1.4-.8%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-rewind { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-rewind%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M11.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L10%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M20.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L19%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-rewind%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M11.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L10%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M20.2%206.4v11.2c0%20.62-.7.98-1.2.62l-7.2-5.6a.78.78%200%200%201%200-1.24L19%205.78c.5-.36%201.2%200%201.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-forward { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-forward%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M12.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L14%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M3.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L5%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-forward%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M12.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L14%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3Cpath%20d%3D%22M3.8%206.4v11.2c0%20.62.7.98%201.2.62l7.2-5.6a.78.78%200%200%200%200-1.24L5%205.78c-.5-.36-1.2%200-1.2.62Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-like { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2011.2v7.3H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.5a1.4%201.4%200%200%201%201.4-1.4h2.4Z%22%2F%3E%20%3Cpath%20d%3D%22M7.2%2011.2%2010.8%205c.42-.72%201.5-.48%201.58.35l.18%201.9a4.2%204.2%200%200%201-.53%202.43l-.75%201.32h5.6a2%202%200%200%201%201.95%202.45l-1%204.2a2.4%202.4%200%200%201-2.34%201.85H7.2%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M7.2%2011.2v7.3H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.5a1.4%201.4%200%200%201%201.4-1.4h2.4Z%22%2F%3E%20%3Cpath%20d%3D%22M7.2%2011.2%2010.8%205c.42-.72%201.5-.48%201.58.35l.18%201.9a4.2%204.2%200%200%201-.53%202.43l-.75%201.32h5.6a2%202%200%200%201%201.95%202.45l-1%204.2a2.4%202.4%200%200%201-2.34%201.85H7.2%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-like-filled { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like-filled%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M7.2%2011.15v7.35H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.55a1.4%201.4%200%200%201%201.4-1.4h2.4Zm1.2%207.35h6.75a2.45%202.45%200%200%200%202.38-1.88l1-4.15A2.02%202.02%200%200%200%2016.57%2010h-3.64l.18-.33a4.35%204.35%200%200%200%20.55-2.52l-.18-1.87c-.16-1.66-2.32-2.1-3.16-.66L8.4%207.93v10.57Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-like-filled%22%20fill%3D%22none%22%3E%20%3Cpath%20d%3D%22M7.2%2011.15v7.35H4.8a1.4%201.4%200%200%201-1.4-1.4v-4.55a1.4%201.4%200%200%201%201.4-1.4h2.4Zm1.2%207.35h6.75a2.45%202.45%200%200%200%202.38-1.88l1-4.15A2.02%202.02%200%200%200%2016.57%2010h-3.64l.18-.33a4.35%204.35%200%200%200%20.55-2.52l-.18-1.87c-.16-1.66-2.32-2.1-3.16-.66L8.4%207.93v10.57Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-flag { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-flag-filled { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag-filled%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-flag-filled%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Cpath%20d%3D%22M6.5%2020V5.2%22%2F%3E%20%3Cpath%20d%3D%22M6.5%205.2c2.7-1.2%205.1.8%207.8-.4%201.2-.5%202.2-.6%203.2-.3v8.4c-1-.3-2-.2-3.2.3-2.7%201.2-5.1-.8-7.8.4Z%22%20fill%3D%22currentColor%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-mark { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-small-cuts-mark%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Crect%20x%3D%225%22%20y%3D%224.5%22%20width%3D%2214%22%20height%3D%2215%22%20rx%3D%222.2%22%2F%3E%20%3Cpath%20d%3D%22M9%204.5v15M15%204.5v15%22%2F%3E%20%3Cpath%20d%3D%22M5%208.5h4M15%208.5h4M5%2015.5h4M15%2015.5h4%22%2F%3E%20%3Cpath%20d%3D%22M8.5%2016.5%2015.8%207.2%22%2F%3E%20%3Cpath%20d%3D%22M10.8%2017.2h4.7%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20role%3D%22img%22%20aria-labelledby%3D%22title-small-cuts-mark%22%20fill%3D%22none%22%3E%20%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%20%3Crect%20x%3D%225%22%20y%3D%224.5%22%20width%3D%2214%22%20height%3D%2215%22%20rx%3D%222.2%22%2F%3E%20%3Cpath%20d%3D%22M9%204.5v15M15%204.5v15%22%2F%3E%20%3Cpath%20d%3D%22M5%208.5h4M15%208.5h4M5%2015.5h4M15%2015.5h4%22%2F%3E%20%3Cpath%20d%3D%22M8.5%2016.5%2015.8%207.2%22%2F%3E%20%3Cpath%20d%3D%22M10.8%2017.2h4.7%22%2F%3E%20%3C%2Fg%3E%20%3C%2Fsvg%3E"); }
+.sc-ico-play { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M8.5%206.7v10.6c0%20.72.78%201.17%201.4.8l8.36-5.3a.95.95%200%200%200%200-1.6L9.9%205.9c-.62-.39-1.4.06-1.4.8Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cpath%20d%3D%22M8.5%206.7v10.6c0%20.72.78%201.17%201.4.8l8.36-5.3a.95.95%200%200%200%200-1.6L9.9%205.9c-.62-.39-1.4.06-1.4.8Z%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); }
+.sc-ico-pause { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Crect%20x%3D%227%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3Crect%20x%3D%2213.4%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Crect%20x%3D%227%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3Crect%20x%3D%2213.4%22%20y%3D%225.6%22%20width%3D%223.6%22%20height%3D%2212.8%22%20rx%3D%221.1%22%20fill%3D%22currentColor%22%2F%3E%3C%2Fsvg%3E"); }
+.sc-ico-volume { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22M15.2%209.2a4.2%204.2%200%200%201%200%205.6%22%2F%3E%3Cpath%20d%3D%22M17.5%207a7.4%207.4%200%200%201%200%2010%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22M15.2%209.2a4.2%204.2%200%200%201%200%205.6%22%2F%3E%3Cpath%20d%3D%22M17.5%207a7.4%207.4%200%200%201%200%2010%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); }
+.sc-ico-volume-muted { -webkit-mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22m16%209.2%204.2%204.2M20.2%209.2%2016%2013.4%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); mask-image: url("data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%3E%3Cg%20fill%3D%22none%22%20stroke%3D%22currentColor%22%20stroke-width%3D%221.8%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20vector-effect%3D%22non-scaling-stroke%22%3E%3Cpath%20d%3D%22M4.5%2014.5h3.1l4.5%203.4V6.1L7.6%209.5H4.5v5Z%22%2F%3E%3Cpath%20d%3D%22m16%209.2%204.2%204.2M20.2%209.2%2016%2013.4%22%2F%3E%3C%2Fg%3E%3C%2Fsvg%3E"); }
+"""

src/small_cuts/demo_seed.py

@@ -0,0 +1,81 @@
+"""Seeded 'hero' library — curated VIDEO cuts so the Space loads alive.
+
+Real first-person glasses moments, **muted** (the generated narration is the only
+audio, which also strips any incidental conversation), narrated in the one signature
+deadpan voice. The live "Try it" sandbox runs the real model; this seed just gives a
+first-time visitor a channel with a few finished cuts to scroll. Five short, compressed,
+face-free clips so the Space boots fast and respects bystander privacy.
+"""
+
+from __future__ import annotations
+
+import os
+
+from PIL import Image
+
+STYLE_KEY = "deadpan"
+SEED_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "seed_media")
+
+# (clip, poster, title, narration, visibility) — ordered oldest → newest.
+SEED: list[tuple[str, str, str, str, str]] = [
+    (
+        "desk-laptop.mp4",
+        "desk-laptop.jpg",
+        "Debugging His Own Ambition",
+        "It is late — the specific, self-inflicted late of someone building a thing nobody "
+        "asked for. On the monitor a small game he is making flickers half-finished, its rules "
+        "still being argued into existence. His hands move with the patience of a man debugging "
+        "his own ambition, and the coffee, just off-frame, went cold around the last good idea.",
+        "private",
+    ),
+    (
+        "the-stumble.mp4",
+        "the-stumble.jpg",
+        "He Meant to Do That",
+        "He has stepped out of the bar for air and the small chemical comfort of the vape, and "
+        "the pavement, sensing an opening, tilts very slightly underfoot. He recovers, as one "
+        "does, with the careful dignity of a man who would prefer the record to show he meant to "
+        "do that. The night says nothing. It has seen steadier, and worse.",
+        "private",
+    ),
+    (
+        "street-parked-car.mp4",
+        "street-parked-car.jpg",
+        "Just Five Minutes",
+        "The car is parked with the easy confidence of a driver who said 'just five minutes' and "
+        "meant it the way everyone means it. The street is in no hurry to disagree. Somewhere "
+        "nearby a meter is running, patient and unread.",
+        "public",
+    ),
+    (
+        "night-drive.mp4",
+        "night-drive.jpg",
+        "Photographs Well at Night",
+        "The city slides past at the speed of someone who knows the way and feels no need to "
+        "prove it. Streetlight opens and closes on the windshield; the older facades hold their "
+        "glow a little longer than the new ones. He is driving through the part of town that "
+        "photographs well at night, which is, if one is honest about Barcelona, most of it.",
+        "public",
+    ),
+    (
+        "rayuela.mp4",
+        "rayuela.jpg",
+        "The Stone Almost Never Reaches the Sky",
+        "Through the wire, a hopscotch waits on the schoolyard floor, its chalk gone soft with "
+        "weather. At the bottom is the Earth; at the top, the Sky — and the old difficulty "
+        "between them, that the stone, nudged by the toe of a shoe, almost never reaches the "
+        "Sky. He passes on the far side of the fence now, a grown man in grown shoes, and does "
+        "not stop. The ingredients were always so small: a sidewalk, a stone, the tip of a shoe.",
+        "public",
+    ),
+]
+
+
+def clip_path(name: str) -> str:
+    """Absolute path to a bundled seed clip (served via gr.set_static_paths)."""
+    return os.path.join(SEED_DIR, name)
+
+
+def load_poster(name: str) -> Image.Image:
+    """Load a bundled poster frame (the still shown before the clip plays / in the shelf)."""
+    return Image.open(os.path.join(SEED_DIR, name)).convert("RGB")

src/small_cuts/engine/__init__.py

@@ -0,0 +1,9 @@
+"""Home-node narration engine — mobile-facing WebSocket session (Team Inference).
+
+Optional install: `uv sync --extra engine`. Nothing in the existing app path
+imports this package, so the Space/UI keep working without the extra.
+"""
+
+from .app import build_engine_app
+
+__all__ = ["build_engine_app"]

src/small_cuts/engine/__main__.py

@@ -0,0 +1,33 @@
+"""Run the engine: `uv run python -m small_cuts.engine`."""
+
+import contextlib
+import os
+import signal
+
+import uvicorn
+
+from .app import build_engine_app
+
+
+def main() -> None:
+    from small_cuts import narrator
+
+    def shutdown(signum, frame):  # noqa: ARG001
+        with contextlib.suppress(Exception):
+            backend = narrator.get_backend()
+            close = getattr(backend, "close", None)
+            if close is not None:
+                close()
+        raise SystemExit(0)
+
+    signal.signal(signal.SIGTERM, shutdown)
+    uvicorn.run(
+        build_engine_app(),
+        host=os.environ.get("SMALL_CUTS_ENGINE_HOST", "127.0.0.1"),
+        port=int(os.environ.get("SMALL_CUTS_ENGINE_PORT", "8077")),
+        ws_max_size=int(os.environ.get("SMALL_CUTS_ENGINE_WS_MAX_SIZE", str(64 * 1024 * 1024))),
+    )
+
+
+if __name__ == "__main__":
+    main()

src/small_cuts/engine/app.py

@@ -0,0 +1,152 @@
+"""App factory for the home-node narration engine (Team Inference).
+
+One WebSocket per wearing session (`/v1/session`), plus the viewer-facing
+side of docs/contracts: the scene library REST API (D6) and the live SSE
+scene stream with Last-Event-ID resume (D7).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any, Literal
+
+from fastapi import FastAPI, HTTPException, Query, Request, WebSocket
+from fastapi.responses import FileResponse, StreamingResponse
+from pydantic import BaseModel
+
+from .library import SceneLibrary
+from .session import EngineState, SceneSink, SessionRunner
+
+SSE_HEARTBEAT_S = 15.0
+
+Visibility = Literal["private", "shared", "public"]
+
+
+class VisibilityPatch(BaseModel):
+    visibility: Visibility
+
+
+def _sse_event(event: dict[str, Any]) -> str:
+    data = f"data: {json.dumps(event)}\n\n"
+    seq = event.get("seq")
+    # No seq -> ephemeral event (error frames): no id line, so it never becomes
+    # a Last-Event-ID resume cursor and is never expected in replay.
+    return data if seq is None else f"id: {seq}\n{data}"
+
+
+def _last_event_id(raw: str | None) -> int | None:
+    """SSE resume cursor; absent or unparsable means a fresh connect, live only."""
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+async def scene_event_stream(
+    library: SceneLibrary, last_event_id: int | None, heartbeat_s: float
+) -> AsyncIterator[str]:
+    """SSE body: replay seq > Last-Event-ID, then live events; pings while idle.
+
+    Live events without a seq (pipeline errors) pass straight through —
+    they are ephemeral and never part of replay.
+    """
+    queue = library.subscribe()
+    try:
+        last_seq = -1
+        if last_event_id is not None:
+            last_seq = last_event_id
+            for scene in library.scenes_since(last_event_id):
+                last_seq = scene["seq"]
+                yield _sse_event(scene)
+        while True:
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=heartbeat_s)
+            except asyncio.TimeoutError:
+                yield ": ping\n\n"
+                continue
+            # Invariant: the library publishes each seq exactly once, so live
+            # events never need dedupe against each other. `last_seq` stays
+            # frozen at the replay boundary — it only filters scenes that were
+            # both replayed and queued (stored before replay, published after
+            # subscribe). It must NOT advance here: store() commits seq under
+            # the lock in a worker thread but publishes later on the loop, so
+            # concurrent sessions can publish out of seq order, and a moving
+            # cursor would drop the lower seq forever.
+            seq = event.get("seq")
+            if seq is not None and seq <= last_seq:
+                continue
+            yield _sse_event(event)
+    finally:
+        library.unsubscribe(queue)
+
+
+def build_engine_app(
+    scene_sink: SceneSink | None = None,
+    library: SceneLibrary | None = None,
+    sse_heartbeat_s: float = SSE_HEARTBEAT_S,
+) -> FastAPI:
+    """Engine app: session socket + scene library + SSE stream, per docs/contracts.
+
+    By default scenes are persisted to a `SceneLibrary` (root from
+    `SMALL_CUTS_LIBRARY_DIR`); pass `library` to inject one, or `scene_sink`
+    to replace the sink entirely (tests).
+    """
+    lib = library if library is not None else SceneLibrary()
+    sink = scene_sink if scene_sink is not None else lib
+    # Errors fan out to the viewer stream too (D9): the timeline shows failures.
+    state = EngineState(sink=sink, error_sink=lib.publish_event)
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        try:
+            yield
+        finally:
+            close = getattr(app.state.library, "close", None)
+            if close is not None:
+                close()
+
+    app = FastAPI(title="small-cuts engine", lifespan=lifespan)
+    app.state.library = lib
+
+    @app.websocket("/v1/session")
+    async def session(websocket: WebSocket) -> None:
+        await websocket.accept()
+        await SessionRunner(websocket, state).run()
+
+    @app.get("/v1/scenes")
+    def list_scenes(
+        session: str | None = None,
+        visibility: Visibility | None = None,
+        limit: Annotated[int, Query(ge=1, le=1000)] = 100,
+    ) -> dict[str, list[dict[str, Any]]]:
+        return {"scenes": lib.list_scenes(session_id=session, visibility=visibility, limit=limit)}
+
+    @app.get("/v1/scenes/stream")
+    async def stream_scenes(request: Request) -> StreamingResponse:
+        resume_from = _last_event_id(request.headers.get("last-event-id"))
+        return StreamingResponse(
+            scene_event_stream(lib, resume_from, sse_heartbeat_s),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache"},
+        )
+
+    @app.patch("/v1/scenes/{scene_id}")
+    def set_visibility(scene_id: str, patch: VisibilityPatch) -> dict[str, Any]:
+        scene = lib.set_visibility(scene_id, patch.visibility)
+        if scene is None:
+            raise HTTPException(status_code=404, detail=f"unknown scene {scene_id}")
+        return scene
+
+    @app.get("/media/{scene_id}/{filename}")
+    def media(scene_id: str, filename: str) -> FileResponse:
+        path = lib.media_path(scene_id, filename)
+        if path is None:  # unknown name, traversal attempt, or missing file
+            raise HTTPException(status_code=404, detail="no such media")
+        return FileResponse(path)
+
+    return app

src/small_cuts/engine/library.py

@@ -0,0 +1,377 @@
+"""Engine-side scene library: filesystem media + sqlite index (D6).
+
+The real `SceneSink`. Every successful narration is persisted — frame JPEG,
+title card, voice WAV, one sqlite row — and fanned out to live SSE
+subscribers (D7). Blocking writes run in a worker thread via
+`asyncio.to_thread`; the publish happens back on the event loop. Stored
+entries and live events share the same NarratedScene shape, per
+docs/contracts/narrated-scene.schema.json.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import os
+import sqlite3
+import sys
+import threading
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from PIL import Image
+
+from small_cuts import narrator, tts
+from small_cuts.frames import pick_key_frame
+from small_cuts.title_card import TITLE_MAX_LEN, derive_title, render_title_card
+
+from .session import CONTRACT_VERSION, _wav_bytes
+
+DEFAULT_ROOT = "~/.small-cuts/library"
+OWNER = "carlos"  # v1 engines are single-user; the field is reserved for multi-user
+VISIBILITIES = ("private", "shared", "public")
+MEDIA_FILES = ("frame.jpg", "card.webp", "voice.wav", "clip.mp4")
+STORAGE_TIMEOUT_S = 30.0
+SUBSCRIBER_QUEUE_MAX = 256
+CLIP_MP4_FPS = 12
+CLIP_BLEND_STEPS = 1
+H264_MIN_DIMENSION = 2
+POSTER_JPEG_QUALITY = 90
+RGB_MODE = "RGB"
+VIDEO_PIXEL_FORMAT = "yuv420p"
+PRIMARY_VIDEO_CODEC = "libx264"
+FALLBACK_VIDEO_CODEC = "h264"
+
+_SCHEMA = """\
+CREATE TABLE IF NOT EXISTS scenes (
+    scene_id    TEXT PRIMARY KEY,
+    seq         INTEGER NOT NULL UNIQUE,
+    moment_id   TEXT NOT NULL,
+    session_id  TEXT NOT NULL,
+    captured_at TEXT NOT NULL,
+    created_at  TEXT NOT NULL,
+    style_key   TEXT NOT NULL,
+    title       TEXT NOT NULL,
+    narration   TEXT NOT NULL,
+    visibility  TEXT NOT NULL DEFAULT 'private',
+    owner       TEXT NOT NULL,
+    engine      TEXT NOT NULL
+)"""
+
+_INSERT = """\
+INSERT INTO scenes (scene_id, seq, moment_id, session_id, captured_at, created_at,
+                    style_key, title, narration, visibility, owner, engine)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"""
+
+
+class SceneLibrary:
+    """Scene store + in-process pub/sub. The instance itself is the async SceneSink.
+
+    Layout: `<root>/library.sqlite3` + `<root>/media/<scene_id>/{frame.jpg,
+    card.webp, voice.wav}`. One sqlite connection, guarded by a lock: the
+    sink writes from worker threads, queries come from request handlers.
+    """
+
+    def __init__(self, root: str | Path | None = None) -> None:
+        base = root or os.environ.get("SMALL_CUTS_LIBRARY_DIR") or DEFAULT_ROOT
+        self.root = Path(base).expanduser().resolve()
+        self.media_dir = self.root / "media"
+        self.media_dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()  # guards the connection and seq allocation
+        self._db = sqlite3.connect(self.root / "library.sqlite3", check_same_thread=False)
+        self._db.row_factory = sqlite3.Row
+        with self._lock, self._db:
+            # WAL + busy_timeout: viewer reads don't block sink writes, and a
+            # briefly locked database waits instead of raising immediately.
+            self._db.execute("PRAGMA journal_mode=WAL")
+            self._db.execute("PRAGMA busy_timeout=5000")
+            self._db.execute(_SCHEMA)
+        self._subscribers: list[asyncio.Queue[dict[str, Any]]] = []
+
+    # -- the sink -----------------------------------------------------------------
+
+    async def __call__(self, scene: dict[str, Any]) -> None:
+        """SceneSink entry point: persist off the event loop, then publish.
+
+        A failed store (disk full, sqlite error) must not be silent data loss:
+        the mobile client already received its SceneAudio, so log to stderr and
+        fan an error ControlFrame to the viewer stream — the timeline stays
+        honest. `_hand_to_sink`'s suppression remains the last-resort backstop.
+        """
+        try:
+            narrated = await asyncio.wait_for(
+                asyncio.to_thread(self.store, scene), timeout=STORAGE_TIMEOUT_S
+            )
+        except (Exception, asyncio.TimeoutError) as exc:
+            print(
+                f"small_cuts.engine: library write failed for scene {scene['scene_id']}: {exc!r}",
+                file=sys.stderr,
+            )
+            self.publish_event(
+                {
+                    "contract_version": CONTRACT_VERSION,
+                    "kind": "error",
+                    "moment_id": scene["moment_id"],
+                    "error": {
+                        "stage": "storage",
+                        "code": "library_write_failed",
+                        "message": str(exc)[:300],
+                        "retryable": False,
+                    },
+                }
+            )
+            return
+        self.publish_event(narrated)
+
+    def publish_event(self, payload: dict[str, Any]) -> None:
+        """Fan any event (stored scene or ControlFrame error) to live subscribers.
+
+        Events without a seq (errors) are EPHEMERAL: not persisted, not in Last-Event-ID replay.
+        """
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(payload)
+            except asyncio.QueueFull:
+                self.unsubscribe(queue)
+
+    def store(self, scene: dict[str, Any]) -> dict[str, Any]:
+        """Persist media + index row (blocking); returns the stored NarratedScene."""
+        scene_id: str = scene["scene_id"]
+        narration: str = scene["narration"]
+        style_key: str = scene["style_key"]
+        title = _stored_title(scene.get("title"), narration)
+
+        scene_dir = self.media_dir / scene_id
+        scene_dir.mkdir(parents=True, exist_ok=True)
+        clip_frames = scene.get("clip_frames") or []
+        poster = pick_key_frame(clip_frames) if clip_frames else scene["image"]
+        poster.convert(RGB_MODE).save(scene_dir / "frame.jpg", "JPEG", quality=POSTER_JPEG_QUALITY)
+        if len(clip_frames) >= 2:
+            try:
+                _write_clip_mp4(scene_dir / "clip.mp4", clip_frames)
+            except Exception as exc:
+                print(
+                    f"small_cuts.engine: clip write failed for scene {scene_id}: {exc!r}",
+                    file=sys.stderr,
+                )
+        render_title_card(title, style_key).save(scene_dir / "card.webp", "WEBP")
+        (scene_dir / "voice.wav").write_bytes(_wav_bytes(scene["audio"], scene["sample_rate"]))
+
+        narrator_backend = narrator.get_backend()
+        tts_backend = tts.get_tts_backend()
+        engine = {
+            "narrator_model": narrator_backend.model_id,
+            "narrator_backend": narrator_backend.name,
+            "tts_model": tts_backend.model_id,
+            "latency_ms": scene["latency_ms"],
+        }
+        with self._lock, self._db:
+            # max+1 under the lock: monotonic across the process AND across restarts.
+            seq = self._db.execute("SELECT COALESCE(MAX(seq), -1) + 1 FROM scenes").fetchone()[0]
+            self._db.execute(
+                _INSERT,
+                (
+                    scene_id,
+                    seq,
+                    scene["moment_id"],
+                    scene["session_id"],
+                    _normalize_datetime(scene["captured_at"]),
+                    _normalize_datetime(scene["created_at"]),
+                    style_key,
+                    title,
+                    narration,
+                    "private",
+                    _owner(),
+                    json.dumps(engine),
+                ),
+            )
+        stored = self.get(scene_id)
+        if stored is None:
+            raise RuntimeError(f"scene {scene_id} missing immediately after insert")
+        return stored
+
+    # -- queries ---------------------------------------------------------------------
+
+    def to_narrated_scene(self, row: sqlite3.Row) -> dict[str, Any]:
+        """Contract-valid NarratedScene (1.1.0) for one stored row."""
+        scene_id = row["scene_id"]
+        media = {
+            "frame_url": f"/media/{scene_id}/frame.jpg",
+            "card_url": f"/media/{scene_id}/card.webp",
+            "audio_url": f"/media/{scene_id}/voice.wav",
+        }
+        if (self.media_dir / scene_id / "clip.mp4").is_file():
+            media["clip_url"] = f"/media/{scene_id}/clip.mp4"
+        return {
+            "contract_version": CONTRACT_VERSION,
+            "scene_id": scene_id,
+            "moment_id": row["moment_id"],
+            "session_id": row["session_id"],
+            "captured_at": row["captured_at"],
+            "created_at": row["created_at"],
+            "style_key": row["style_key"],
+            "title": row["title"],
+            "narration": row["narration"],
+            "visibility": row["visibility"],
+            "seq": row["seq"],
+            "owner": row["owner"],
+            "media": media,
+            "engine": json.loads(row["engine"]),
+        }
+
+    def list_scenes(
+        self,
+        session_id: str | None = None,
+        visibility: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        """Newest bounded window, returned in scene chronology for the viewer."""
+        clauses, params = [], []
+        if session_id is not None:
+            clauses.append("session_id = ?")
+            params.append(session_id)
+        if visibility is not None:
+            clauses.append("visibility = ?")
+            params.append(visibility)
+        where = f" WHERE {' AND '.join(clauses)}" if clauses else ""
+        query = (
+            "SELECT * FROM ("
+            f"SELECT * FROM scenes{where} ORDER BY seq DESC LIMIT ?"
+            ") ORDER BY captured_at, seq"
+        )
+        with self._lock:
+            rows = self._db.execute(query, (*params, limit)).fetchall()
+        return [self.to_narrated_scene(row) for row in rows]
+
+    def get(self, scene_id: str) -> dict[str, Any] | None:
+        with self._lock:
+            row = self._db.execute(
+                "SELECT * FROM scenes WHERE scene_id = ?", (scene_id,)
+            ).fetchone()
+        return self.to_narrated_scene(row) if row is not None else None
+
+    def set_visibility(self, scene_id: str, visibility: str) -> dict[str, Any] | None:
+        """The viewer's only write (D7). Returns the updated scene, or None if unknown."""
+        if visibility not in VISIBILITIES:
+            raise ValueError(f"Unknown visibility {visibility!r}; expected one of {VISIBILITIES}")
+        with self._lock, self._db:
+            updated = self._db.execute(
+                "UPDATE scenes SET visibility = ? WHERE scene_id = ?", (visibility, scene_id)
+            ).rowcount
+        return self.get(scene_id) if updated else None
+
+    def scenes_since(self, seq: int) -> list[dict[str, Any]]:
+        """Scenes with seq > `seq`, ordered by seq — the SSE Last-Event-ID replay."""
+        with self._lock:
+            rows = self._db.execute(
+                "SELECT * FROM scenes WHERE seq > ? ORDER BY seq", (seq,)
+            ).fetchall()
+        return [self.to_narrated_scene(row) for row in rows]
+
+    def media_path(self, scene_id: str, filename: str) -> Path | None:
+        """Resolve a media file, or None: unknown name, traversal, or missing file."""
+        if filename not in MEDIA_FILES:
+            return None
+        path = (self.media_dir / scene_id / filename).resolve()
+        if not path.is_relative_to(self.media_dir):  # traversal via scene_id
+            return None
+        return path if path.is_file() else None
+
+    # -- pub/sub ----------------------------------------------------------------------
+
+    def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        """New-scene feed for one SSE connection; pair with `unsubscribe`."""
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=SUBSCRIBER_QUEUE_MAX)
+        self._subscribers.append(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        with contextlib.suppress(ValueError):
+            self._subscribers.remove(queue)
+
+    def close(self) -> None:
+        with self._lock:
+            self._db.close()
+
+
+def _write_clip_mp4(
+    path: Path,
+    frames: list[Image.Image],
+    fps: int = CLIP_MP4_FPS,
+    blend_steps: int = CLIP_BLEND_STEPS,
+) -> None:
+    """Render a small browser-playable MP4 from sampled POV frames."""
+    import av
+
+    rgb_frames = [frame.convert(RGB_MODE) for frame in frames]
+    width, height = rgb_frames[0].size
+    # H.264/yuv420p expects even dimensions. Preserve portrait aspect and only
+    # shave one pixel if needed; capture frames are already downscaled upstream.
+    width = max(H264_MIN_DIMENSION, width - (width % 2))
+    height = max(H264_MIN_DIMENSION, height - (height % 2))
+    encode_frames = _smooth_clip_frames(rgb_frames, blend_steps=blend_steps, size=(width, height))
+
+    container = av.open(str(path), "w")
+    try:
+        try:
+            stream = container.add_stream(PRIMARY_VIDEO_CODEC, rate=fps)
+        except Exception:
+            stream = container.add_stream(FALLBACK_VIDEO_CODEC, rate=fps)
+        stream.width = width
+        stream.height = height
+        stream.pix_fmt = VIDEO_PIXEL_FORMAT
+
+        for image in encode_frames:
+            frame = av.VideoFrame.from_image(image)
+            for packet in stream.encode(frame):
+                container.mux(packet)
+        for packet in stream.encode():
+            container.mux(packet)
+    finally:
+        container.close()
+
+
+def _smooth_clip_frames(
+    frames: list[Image.Image],
+    blend_steps: int = CLIP_BLEND_STEPS,
+    size: tuple[int, int] | None = None,
+) -> list[Image.Image]:
+    """Insert tiny cross-dissolve frames so sampled POV clips do not hard-cut."""
+    if not frames:
+        return []
+    prepared = []
+    for image in frames:
+        image = image.convert(RGB_MODE)
+        if size is not None and image.size != size:
+            image = image.resize(size, Image.Resampling.LANCZOS)
+        prepared.append(image)
+    if blend_steps <= 0 or len(prepared) < 2:
+        return prepared
+
+    smoothed = [prepared[0]]
+    for previous, current in zip(prepared, prepared[1:], strict=False):
+        for step in range(1, blend_steps + 1):
+            alpha = step / (blend_steps + 1)
+            smoothed.append(Image.blend(previous, current, alpha))
+        smoothed.append(current)
+    return smoothed
+
+
+def _stored_title(raw_title: object, narration: str) -> str:
+    if isinstance(raw_title, str) and raw_title.strip():
+        return derive_title(raw_title, max_len=TITLE_MAX_LEN)
+    return derive_title(narration, max_len=TITLE_MAX_LEN)
+
+
+def _owner() -> str:
+    return os.environ.get("SMALL_CUTS_ENGINE_OWNER", OWNER)
+
+
+def _normalize_datetime(value: str) -> str:
+    raw = value.replace("Z", "+00:00")
+    parsed = datetime.fromisoformat(raw)
+    if parsed.tzinfo is None:
+        raise ValueError(f"timestamp must include timezone: {value}")
+    return parsed.astimezone(timezone.utc).isoformat()

src/small_cuts/engine/read_gate.py

@@ -0,0 +1,108 @@
+"""Read-only public gate for the live-demo engine surface.
+
+The capture/write socket stays private on Tailnet. This app is the origin behind the public
+Cloudflare Tunnel hostname and only proxies viewer/library reads through to the local engine.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.responses import PlainTextResponse, Response, StreamingResponse
+
+ORIGIN_ENV = "SMALL_CUTS_ORIGIN_ENGINE_URL"
+DEFAULT_ORIGIN = "http://127.0.0.1:8077"
+READ_TIMEOUT = httpx.Timeout(connect=5.0, read=30.0, write=5.0, pool=5.0)
+STREAM_TIMEOUT = httpx.Timeout(connect=5.0, read=None, write=5.0, pool=5.0)
+BLOCKED_TEXT = "small-cuts public endpoint is read-only\n"
+HOP_BY_HOP_HEADERS = {
+    "connection",
+    "keep-alive",
+    "proxy-authenticate",
+    "proxy-authorization",
+    "te",
+    "trailer",
+    "transfer-encoding",
+    "upgrade",
+}
+
+
+def is_public_read_allowed(method: str, path: str) -> bool:
+    if method.upper() != "GET":
+        return False
+    return path in ("/v1/scenes", "/v1/scenes/stream") or path.startswith("/media/")
+
+
+def _forward_headers(headers: httpx.Headers | dict[str, str]) -> dict[str, str]:
+    return {
+        key: value
+        for key, value in headers.items()
+        if key.lower() not in HOP_BY_HOP_HEADERS and key.lower() != "host"
+    }
+
+
+def _origin_url(origin_url: str, request: Request) -> str:
+    url = f"{origin_url.rstrip('/')}{request.url.path}"
+    return f"{url}?{request.url.query}" if request.url.query else url
+
+
+def _timeout_for_path(path: str) -> httpx.Timeout:
+    return STREAM_TIMEOUT if path == "/v1/scenes/stream" else READ_TIMEOUT
+
+
+async def _proxy_body(upstream: httpx.Response) -> AsyncIterator[bytes]:
+    try:
+        async for chunk in upstream.aiter_raw():
+            yield chunk
+    finally:
+        await upstream.aclose()
+
+
+def build_read_gate_app(origin_url: str | None = None) -> FastAPI:
+    origin = (origin_url or os.environ.get(ORIGIN_ENV) or DEFAULT_ORIGIN).rstrip("/")
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        app.state.client = httpx.AsyncClient()
+        try:
+            yield
+        finally:
+            await app.state.client.aclose()
+
+    app = FastAPI(title="small-cuts public read gate", lifespan=lifespan)
+
+    @app.api_route(
+        "/{path:path}",
+        methods=["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
+        response_model=None,
+    )
+    async def public_gate(path: str, request: Request) -> Response:
+        if not is_public_read_allowed(request.method, request.url.path):
+            return PlainTextResponse(BLOCKED_TEXT, status_code=403)
+
+        client: httpx.AsyncClient = request.app.state.client
+        upstream = await client.send(
+            client.build_request(
+                "GET",
+                _origin_url(origin, request),
+                headers=_forward_headers(request.headers),
+                timeout=_timeout_for_path(request.url.path),
+            ),
+            stream=True,
+        )
+
+        return StreamingResponse(
+            _proxy_body(upstream),
+            status_code=upstream.status_code,
+            headers=_forward_headers(upstream.headers),
+            media_type=upstream.headers.get("content-type"),
+        )
+
+    return app
+
+
+app = build_read_gate_app()

src/small_cuts/engine/session.py

@@ -0,0 +1,470 @@
+"""Mobile-facing WebSocket session for the narration engine.
+
+MomentEnvelope in, ControlFrame + SceneAudio out, per docs/contracts.
+Backpressure is D8 (queue depth <= 1, coalesce-to-newest); freshness is D9
+(`play_by` = created_at + 60 s). Pipeline failures become error frames —
+the socket itself never crashes on a bad moment.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import contextlib
+import inspect
+import io
+import json
+import os
+import sys
+import time
+import uuid
+import wave
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import numpy as np
+from fastapi import WebSocket, WebSocketDisconnect
+from PIL import Image
+
+from small_cuts import narrator, tts
+from small_cuts.styles import DEFAULT_STYLE_KEY
+
+CONTRACT_VERSION = "1.1.0"
+PLAY_BY_SECONDS = 60
+MAX_FRAME_SIDE = 1024  # contract cap: decoded longest side <= 1024 px (moment.schema.json)
+SEEN_MOMENTS_CAP = 4096  # a day of moments is far less
+CONTRACTS_DIR_ENV = "SMALL_CUTS_CONTRACTS_DIR"
+_SOURCE_CONTRACTS = Path(__file__).resolve().parents[3] / "docs" / "contracts"
+
+SceneSink = Callable[[dict[str, Any]], Any]
+"""Receives every successful scene; Task 2 plugs the library/SSE fan-out here."""
+
+
+def _contract_text(name: str) -> str:
+    configured = os.environ.get(CONTRACTS_DIR_ENV)
+    if configured:
+        return (Path(configured) / name).read_text()
+    source_contract = _SOURCE_CONTRACTS / name
+    if source_contract.exists():
+        return source_contract.read_text()
+    return (resources.files("small_cuts") / "contracts" / name).read_text()
+
+
+def _validator(name: str) -> jsonschema.Draft202012Validator:
+    return jsonschema.Draft202012Validator(json.loads(_contract_text(name)))
+
+
+_MOMENT = _validator("moment.schema.json")
+_SCENE_AUDIO = _validator("scene-audio.schema.json")
+_BACKGROUND_STORAGE_TASKS: set[asyncio.Task[None]] = set()
+
+
+def _noop_sink(scene: dict[str, Any]) -> None:
+    return None
+
+
+class MomentIdLRU:
+    """Bounded dedupe set: insertion-ordered, oldest ids evicted past `cap`."""
+
+    def __init__(self, cap: int = SEEN_MOMENTS_CAP) -> None:
+        self._cap = cap
+        self._ids: OrderedDict[str, None] = OrderedDict()
+
+    def __contains__(self, moment_id: object) -> bool:
+        return moment_id in self._ids
+
+    def add(self, moment_id: str) -> None:
+        self._ids[moment_id] = None
+        self._ids.move_to_end(moment_id)
+        while len(self._ids) > self._cap:
+            self._ids.popitem(last=False)
+
+    def discard(self, moment_id: str) -> None:
+        self._ids.pop(moment_id, None)
+
+
+@dataclass
+class EngineState:
+    """Process-lifetime state shared across session sockets."""
+
+    sink: SceneSink = _noop_sink
+    error_sink: SceneSink | None = None  # receives every error ControlFrame (viewer fan-out, D9)
+    seen_moment_ids: MomentIdLRU = field(default_factory=MomentIdLRU)
+
+
+@dataclass
+class _Queued:
+    envelope: dict[str, Any]
+    queued_at: float
+
+
+class _ValidationFailure(Exception):
+    """Post-admission validation failure (undecodable or over-cap frame); never retryable."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _log_worker_failure(task: asyncio.Task) -> None:
+    """A drain-task bug must fail loudly, not strand moments as unretrieved exceptions."""
+    if task.cancelled():
+        return
+    exc = task.exception()
+    if exc is not None:
+        print(f"small_cuts.engine: session worker task crashed: {exc!r}", file=sys.stderr)
+
+
+def _retain_background_storage(task: asyncio.Task[None]) -> None:
+    """Keep shielded scene storage alive after the client WebSocket is gone."""
+    _BACKGROUND_STORAGE_TASKS.add(task)
+    task.add_done_callback(_BACKGROUND_STORAGE_TASKS.discard)
+
+
+class SessionRunner:
+    """One connected capture app: admission, the single queue slot, the pipeline."""
+
+    def __init__(self, ws: WebSocket, state: EngineState) -> None:
+        self._ws = ws
+        self._state = state
+        self._send_lock = asyncio.Lock()
+        self._pending: _Queued | None = None
+        self._worker: asyncio.Task | None = None
+        self._processing = False
+        self._last_status: tuple[bool, int] | None = None
+
+    async def run(self) -> None:
+        try:
+            while True:
+                message = await self._ws.receive()
+                if message["type"] == "websocket.disconnect":
+                    break
+                text = message.get("text")
+                if text is None:  # binary frame: not in the contract, but don't drop the socket
+                    await self._send_ack(None, "rejected", "binary frames not supported")
+                    continue
+                await self._admit(text)
+        except WebSocketDisconnect:
+            pass
+        finally:
+            if self._worker is not None:
+                self._worker.cancel()
+
+    # -- admission (every envelope gets exactly one ack) ----------------------
+
+    async def _admit(self, raw: str) -> None:
+        try:
+            envelope = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            await self._send_ack(None, "rejected", f"invalid JSON: {exc}")
+            return
+        moment_id = envelope.get("moment_id") if isinstance(envelope, dict) else None
+        if not isinstance(moment_id, str):
+            moment_id = None
+        error = jsonschema.exceptions.best_match(_MOMENT.iter_errors(envelope))
+        if error is not None:
+            await self._send_ack(moment_id, "rejected", error.message)
+            return
+        dedupe_key = _moment_dedupe_key(envelope)
+        if dedupe_key in self._state.seen_moment_ids:
+            await self._send_ack(moment_id, "duplicate")
+            return
+        self._state.seen_moment_ids.add(dedupe_key)
+
+        queued = _Queued(envelope, time.perf_counter())
+        if not self._processing:
+            self._processing = True
+            await self._send_ack(moment_id, "accepted")
+            self._worker = asyncio.create_task(self._drain(queued))
+            self._worker.add_done_callback(_log_worker_failure)
+        elif self._pending is None:
+            self._pending = queued
+            await self._send_ack(moment_id, "accepted")
+        else:  # D8: replace the un-started moment; stale narration is worse than none
+            dropped = self._pending
+            self._pending = queued
+            await self._send_ack(dropped.envelope["moment_id"], "dropped_coalesced")
+            await self._send_ack(moment_id, "accepted")
+        await self._emit_status()
+
+    # -- processing ------------------------------------------------------------
+
+    async def _drain(self, queued: _Queued) -> None:
+        current: _Queued | None = queued
+        try:
+            while current is not None:
+                await self._process(current)
+                current, self._pending = self._pending, None
+                await self._emit_status()
+        finally:
+            self._processing = False
+        await self._emit_status()  # skipped on cancellation: the socket is gone
+
+    async def _process(self, item: _Queued) -> None:
+        envelope = item.envelope
+        moment_id: str = envelope["moment_id"]
+        context = envelope.get("context") or {}
+        style_key = context.get("style_key") or DEFAULT_STYLE_KEY
+        started = time.perf_counter()
+        queue_ms = _ms(started - item.queued_at)
+        stage = "narration"
+        try:
+            image, narration = await asyncio.to_thread(
+                _decode_and_narrate,
+                envelope,
+                style_key,
+                context.get("user_hint", ""),
+            )
+            narration_ms = _ms(time.perf_counter() - started)
+            stage = "tts"
+            tts_started = time.perf_counter()
+            speech = await asyncio.to_thread(tts.speak, narration.text)
+            audio_b64 = base64.b64encode(_wav_bytes(speech.audio, speech.sample_rate)).decode()
+            tts_ms = _ms(time.perf_counter() - tts_started)
+
+            stage = "storage"  # the outgoing SceneAudio is the engine's stored artifact
+            created_at = datetime.now(timezone.utc)
+            payload = {
+                "contract_version": CONTRACT_VERSION,
+                "scene_id": str(uuid.uuid4()),
+                "moment_id": moment_id,
+                "created_at": created_at.isoformat(),
+                "play_by": (created_at + timedelta(seconds=PLAY_BY_SECONDS)).isoformat(),
+                "format": "wav_complete",
+                "audio_b64": audio_b64,
+                "sample_rate": speech.sample_rate,
+                "narration": narration.text,
+            }
+            _SCENE_AUDIO.validate(payload)  # outgoing drift becomes an error frame, never silence
+            await self._send_json(payload)
+        except _ValidationFailure as exc:
+            # The resend would fail the same way, but dedupe only what produced a scene.
+            self._state.seen_moment_ids.discard(_moment_dedupe_key(envelope))
+            await self._send_error(moment_id, "validation", exc, code=exc.code, retryable=False)
+            return
+        except Exception as exc:
+            # Drop the id so a client resend is genuinely re-processed (honest retryable).
+            self._state.seen_moment_ids.discard(_moment_dedupe_key(envelope))
+            retryable = stage in ("narration", "tts")
+            code = "scene_audio_schema_drift" if stage == "storage" else None
+            await self._send_error(moment_id, stage, exc, code=code, retryable=retryable)
+            return
+
+        storage_task = asyncio.create_task(
+            self._finish_scene_storage(
+                envelope=envelope,
+                image=image,
+                scene_audio=payload,
+                narration_text=narration.text,
+                title=narration.title,
+                speech=speech,
+                style_key=style_key,
+                queue_ms=queue_ms,
+                narration_ms=narration_ms,
+                tts_ms=tts_ms,
+            )
+        )
+        _retain_background_storage(storage_task)
+        try:
+            await asyncio.shield(storage_task)
+        except asyncio.CancelledError:
+            storage_task.add_done_callback(_log_worker_failure)
+            raise
+
+    async def _finish_scene_storage(
+        self,
+        *,
+        envelope: dict[str, Any],
+        image: Image.Image,
+        scene_audio: dict[str, Any],
+        narration_text: str,
+        title: str,
+        speech: tts.Speech,
+        style_key: str,
+        queue_ms: int,
+        narration_ms: int,
+        tts_ms: int,
+    ) -> None:
+        clip_frames = await asyncio.to_thread(
+            _decode_clip_frames_for_storage, envelope, image, scene_audio["scene_id"]
+        )
+        await self._hand_to_sink(
+            self._state.sink,
+            {
+                "scene_id": scene_audio["scene_id"],
+                "moment_id": envelope["moment_id"],
+                "session_id": envelope["session_id"],
+                "captured_at": envelope["captured_at"],
+                "created_at": scene_audio["created_at"],
+                "style_key": style_key,
+                "title": title,
+                "narration": narration_text,
+                "image": image,
+                "clip_frames": clip_frames,
+                "audio": speech.audio,
+                "sample_rate": speech.sample_rate,
+                "latency_ms": {
+                    "queue": queue_ms,
+                    "narration": narration_ms,
+                    "tts": tts_ms,
+                    "total": queue_ms + narration_ms + tts_ms,
+                },
+            },
+        )
+
+    async def _hand_to_sink(self, sink: SceneSink | None, payload: dict[str, Any]) -> None:
+        if sink is None:
+            return
+        with contextlib.suppress(Exception):  # a sink bug must not kill the session
+            result = sink(payload)
+            if inspect.isawaitable(result):
+                await result
+
+    # -- outbound frames ---------------------------------------------------------
+
+    async def _send_ack(self, moment_id: str | None, result: str, detail: str = "") -> None:
+        ack: dict[str, Any] = {"result": result}
+        if detail:
+            ack["detail"] = detail[:200]
+        await self._send_json(
+            {
+                "contract_version": CONTRACT_VERSION,
+                "kind": "ack",
+                "moment_id": moment_id,
+                "ack": ack,
+            }
+        )
+
+    async def _send_error(
+        self,
+        moment_id: str,
+        stage: str,
+        exc: Exception,
+        *,
+        retryable: bool,
+        code: str | None = None,
+    ) -> None:
+        frame = {
+            "contract_version": CONTRACT_VERSION,
+            "kind": "error",
+            "moment_id": moment_id,
+            "error": {
+                "stage": stage,
+                "code": (code or type(exc).__name__)[:60],
+                "message": str(exc)[:300],
+                "retryable": retryable,
+            },
+        }
+        await self._send_json(frame)
+        # D9 honest timeline: the same failure fans out to the viewer stream.
+        await self._hand_to_sink(self._state.error_sink, frame)
+
+    async def _emit_status(self) -> None:
+        snapshot = (self._processing, int(self._pending is not None))
+        if snapshot == self._last_status:
+            return
+        self._last_status = snapshot
+        await self._send_json(
+            {
+                "contract_version": CONTRACT_VERSION,
+                "kind": "status",
+                "moment_id": None,
+                "status": {"busy": snapshot[0], "queue_depth": snapshot[1]},
+            }
+        )
+
+    async def _send_json(self, payload: dict[str, Any]) -> None:
+        text = json.dumps(payload)  # serialization bugs must surface, not be swallowed
+        async with self._send_lock:
+            with contextlib.suppress(Exception):  # client gone mid-send; run() closes out
+                await self._ws.send_text(text)
+
+
+def _decode_and_narrate(
+    envelope: dict[str, Any], style_key: str, scene_hint: str
+) -> tuple[Image.Image, narrator.Narration]:
+    """Decode the selected frame + narrate it in one worker-thread hop."""
+    try:
+        selected = _decode_frame(envelope["frames"][0])
+        _validate_frame_size(selected)
+    except _ValidationFailure:
+        raise
+    except Exception as exc:
+        raise _ValidationFailure("frame_decode_failed", f"undecodable frame: {exc}") from exc
+    return (
+        selected,
+        narrator.narrate(selected, style_key=style_key, scene_hint=scene_hint),
+    )
+
+
+def _decode_frame(frame: dict[str, Any]) -> Image.Image:
+    data = base64.b64decode(frame["jpeg_b64"])
+    image = Image.open(io.BytesIO(data))
+    image.load()
+    return image
+
+
+def _moment_dedupe_key(envelope: dict[str, Any]) -> str:
+    return f"{envelope['session_id']}:{envelope['moment_id']}"
+
+
+def _validate_frame_size(image: Image.Image) -> None:
+    longest = max(image.size)
+    if longest > MAX_FRAME_SIDE:
+        raise _ValidationFailure(
+            "frame_exceeds_cap",
+            f"decoded longest side {longest} px exceeds the {MAX_FRAME_SIDE} px contract cap",
+        )
+
+
+def _decode_clip_frames(envelope: dict[str, Any], selected: Image.Image) -> list[Image.Image]:
+    decoded: list[tuple[int, int, Image.Image]] = [
+        (int(envelope["frames"][0].get("ts_offset_ms", 0)), 0, selected)
+    ]
+    for index, frame in enumerate(envelope["frames"][1:], start=1):
+        image = _decode_frame(frame)
+        _validate_frame_size(image)
+        decoded.append((int(frame.get("ts_offset_ms", index)), index, image))
+    return [image for _, _, image in sorted(decoded, key=lambda item: (item[0], item[1]))]
+
+
+def _decode_clip_frames_for_storage(
+    envelope: dict[str, Any], selected: Image.Image, scene_id: str
+) -> list[Image.Image]:
+    """Decode viewer-only supplemental frames after SceneAudio is already sent."""
+    if len(envelope["frames"]) < 2:
+        return [selected]
+    try:
+        return _decode_clip_frames(envelope, selected)
+    except Exception as exc:
+        print(
+            f"small_cuts.engine: clip frame decode failed for scene {scene_id}: {exc!r}",
+            file=sys.stderr,
+        )
+        return [selected]
+
+
+def _wav_bytes(audio: np.ndarray, sample_rate: int) -> bytes:
+    buffer = io.BytesIO()
+    try:
+        import soundfile
+
+        soundfile.write(buffer, audio, sample_rate, format="WAV", subtype="PCM_16")
+    except ImportError:
+        pcm = (np.clip(audio, -1.0, 1.0) * 32767.0).astype("<i2")
+        with wave.open(buffer, "wb") as wav:
+            wav.setnchannels(1)
+            wav.setsampwidth(2)
+            wav.setframerate(sample_rate)
+            wav.writeframes(pcm.tobytes())
+    return buffer.getvalue()
+
+
+def _ms(seconds: float) -> int:
+    return max(0, round(seconds * 1000))

src/small_cuts/eval.py

@@ -0,0 +1,162 @@
+"""M1 model-evaluation harness: candidate VLMs × images × styles → markdown report.
+
+Designed to run on a CUDA box (DGX Spark) so results transfer to ZeroGPU:
+
+    uv sync --extra local
+    uv run python -m small_cuts.eval --images ~/eval-photos --out eval-report.md
+
+Smoke test anywhere (no weights):
+
+    uv run python -m small_cuts.eval --images ~/eval-photos --backend mock
+"""
+
+from __future__ import annotations
+
+import argparse
+import tempfile
+import time
+from pathlib import Path
+
+from PIL import Image
+
+from .narrator import MockBackend, Narration, TransformersBackend, narrate
+
+CANDIDATE_MODELS = [
+    "HuggingFaceTB/SmolVLM2-2.2B-Instruct",
+    "Qwen/Qwen2.5-VL-3B-Instruct",
+    "Qwen/Qwen2.5-VL-7B-Instruct",
+    "google/gemma-3-4b-it",
+]
+
+EVAL_STYLES = ["deadpan", "noir", "nature_doc"]
+
+# .heic/.heif (iPhone default) decode via pillow-heif, registered in small_cuts/__init__.py
+IMAGE_SUFFIXES = {".jpg", ".jpeg", ".png", ".webp", ".heic", ".heif"}
+
+# Real Small Cuts input is video (Ray-Ban / phone clips). When a directory holds
+# videos, we sample frames so the model eval runs on representative stills.
+VIDEO_SUFFIXES = {".mov", ".mp4", ".m4v", ".webm", ".avi", ".mkv"}
+
+RUBRIC = (
+    "Score each cell 1-5 on: **S**pecificity (names real visible things), "
+    "**G**roundedness (no invented objects/people), **V**oice (style lands). "
+    "A model needs S>=4 and G>=4 on most images to be the pick."
+)
+
+
+def _sample_video_frames(
+    video: Path,
+    every_n_seconds: float = 3.0,
+    output_dir: Path | None = None,
+) -> list[Path]:
+    """Extract frames from a video into an output directory; return their paths."""
+    from .frames import sample_frames
+
+    images = sample_frames(video, every_n_seconds=every_n_seconds)
+    output = output_dir or Path(tempfile.mkdtemp(prefix="small-cuts-eval-frames-"))
+    output.mkdir(parents=True, exist_ok=True)
+    out_paths: list[Path] = []
+    for i, img in enumerate(images):
+        out = output / f"{video.stem}_frame{i:06d}.jpg"
+        img.save(out)
+        out_paths.append(out)
+    return out_paths
+
+
+def load_images(images_dir: Path, frame_dir: Path | None = None) -> list[Path]:
+    if not images_dir.exists():
+        raise SystemExit(f"Directory does not exist: {images_dir}")
+    entries = sorted(p for p in images_dir.iterdir() if p.is_file())
+    paths = [p for p in entries if p.suffix.lower() in IMAGE_SUFFIXES]
+    videos = [p for p in entries if p.suffix.lower() in VIDEO_SUFFIXES]
+    for video in videos:
+        print(f"Sampling frames from {video.name}")
+        paths.extend(_sample_video_frames(video, output_dir=frame_dir))
+    if not paths:
+        listing = "\n".join(f"  {p.name}" for p in entries) or "  (directory is empty)"
+        raise SystemExit(
+            f"No images or videos found in {images_dir}.\n"
+            f"Directory contains:\n{listing}\n"
+            f"Recognized image suffixes: {sorted(IMAGE_SUFFIXES)}\n"
+            f"Recognized video suffixes: {sorted(VIDEO_SUFFIXES)}"
+        )
+    return sorted(paths)
+
+
+def run_model(
+    model_id: str, image_paths: list[Path], styles: list[str], backend_name: str
+) -> dict[tuple[str, str], Narration]:
+    backend = MockBackend() if backend_name == "mock" else TransformersBackend(model_id=model_id)
+    results: dict[tuple[str, str], Narration] = {}
+    for path in image_paths:
+        image = Image.open(path).convert("RGB")
+        for style in styles:
+            result = narrate(image, style_key=style, backend=backend)
+            results[(path.name, style)] = result
+            print(f"  {model_id} | {path.name} | {style} | {result.latency_s:.1f}s")
+    return results
+
+
+def render_report(
+    all_results: dict[str, dict[tuple[str, str], Narration]],
+    image_paths: list[Path],
+    styles: list[str],
+) -> str:
+    lines = [
+        "# Small Cuts — M1 Narrator Model Eval",
+        "",
+        f"Generated {time.strftime('%Y-%m-%d %H:%M:%S')}.",
+        "",
+        RUBRIC,
+        "",
+    ]
+    for path in image_paths:
+        lines.append(f"## {path.name}")
+        lines.append("")
+        lines.append("| Model | Style | Narration | Latency | S | G | V |")
+        lines.append("|---|---|---|---|---|---|---|")
+        for model_id, results in all_results.items():
+            for style in styles:
+                narration = results.get((path.name, style))
+                if narration is None:
+                    lines.append(f"| {model_id} | {style} | (failed) | - |  |  |  |")
+                    continue
+                text = narration.text.replace("\n", " ").replace("|", "\\|")
+                lines.append(
+                    f"| {model_id} | {style} | {text} | {narration.latency_s:.1f}s |  |  |  |"
+                )
+        lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--images", type=Path, required=True, help="Directory of eval photos")
+    parser.add_argument("--models", nargs="*", default=CANDIDATE_MODELS)
+    parser.add_argument("--styles", nargs="*", default=EVAL_STYLES)
+    parser.add_argument("--out", type=Path, default=Path("eval-report.md"))
+    parser.add_argument("--backend", choices=["transformers", "mock"], default="transformers")
+    args = parser.parse_args(argv)
+
+    with tempfile.TemporaryDirectory(prefix="small-cuts-eval-frames-") as frame_dir:
+        image_paths = load_images(args.images, frame_dir=Path(frame_dir))
+        models = args.models if args.backend == "transformers" else ["mock"]
+        all_results = {}
+        failures = []
+        for model_id in models:
+            try:
+                all_results[model_id] = run_model(model_id, image_paths, args.styles, args.backend)
+            except Exception as exc:  # one gated/broken model must not kill the eval
+                failures.append(f"{model_id}: {type(exc).__name__}: {exc}")
+                print(f"  FAILED {model_id}: {exc}")
+        if not all_results:
+            raise SystemExit("All models failed:\n" + "\n".join(failures))
+        report = render_report(all_results, image_paths, args.styles)
+        if failures:
+            report += "\n## Failed models\n\n" + "\n".join(f"- {f}" for f in failures) + "\n"
+        args.out.write_text(report)
+    print(f"\nReport written to {args.out}")
+
+
+if __name__ == "__main__":
+    main()

src/small_cuts/frames.py

@@ -0,0 +1,82 @@
+"""Video frame sampling utilities for Small Cuts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image, ImageFilter, ImageStat
+
+
+def sample_frames(
+    path: str | Path,
+    every_n_seconds: float = 3.0,
+    max_frames: int | None = None,
+) -> list[Image.Image]:
+    """Decode *path* with PyAV and return a list of RGB PIL Images.
+
+    Every ``int(fps * every_n_seconds)``-th frame is kept (indices 0, step,
+    2*step, …).  No files are written.  Decoding stops as soon as
+    *max_frames* images have been collected (when *max_frames* is not None).
+    """
+    import av  # PyAV — ffmpeg-backed, reliable ARM64 wheels
+
+    kept: list[Image.Image] = []
+    container = av.open(str(path))
+    try:
+        stream = container.streams.video[0]
+        fps = float(stream.average_rate or stream.guessed_rate or 30)
+        step = max(1, int(fps * every_n_seconds))
+        for i, frame in enumerate(container.decode(stream)):
+            if i % step == 0:
+                img = frame.to_image().convert("RGB")
+                kept.append(img)
+                if max_frames is not None and len(kept) >= max_frames:
+                    break
+    finally:
+        container.close()
+    return kept
+
+
+def pick_frame(frames: list[Image.Image]) -> Image.Image:
+    """Return the middle frame (``frames[len(frames) // 2]``).
+
+    Raises ``ValueError`` when *frames* is empty.
+    """
+    if not frames:
+        raise ValueError("frames list is empty")
+    return frames[len(frames) // 2]
+
+
+def pick_key_frame(frames: list[Image.Image]) -> Image.Image:
+    """Return the most useful library/poster frame from sampled video frames.
+
+    The score is intentionally deterministic and dependency-light: prefer frames
+    that are exposed near mid-brightness, have contrast, and have visible edges.
+    A centrality bonus breaks near-ties toward the middle of the clip, which is
+    usually more representative than the capture start or the trailing frame.
+    """
+    if not frames:
+        raise ValueError("frames list is empty")
+    middle = (len(frames) - 1) / 2
+    best_index, _best_score = max(
+        enumerate(frames),
+        key=lambda item: (_frame_quality(item[1]) + _centrality(item[0], middle), -item[0]),
+    )
+    return frames[best_index]
+
+
+def _frame_quality(frame: Image.Image) -> float:
+    gray = frame.convert("L")
+    gray.thumbnail((160, 160), Image.Resampling.LANCZOS)
+    stats = ImageStat.Stat(gray)
+    brightness = stats.mean[0] / 255.0
+    contrast = min(stats.stddev[0] / 96.0, 1.0)
+    exposure = 1.0 - min(abs(brightness - 0.5) / 0.5, 1.0)
+    edges = ImageStat.Stat(gray.filter(ImageFilter.FIND_EDGES)).mean[0] / 255.0
+    return exposure * 0.45 + contrast * 0.35 + min(edges * 3.0, 1.0) * 0.20
+
+
+def _centrality(index: int, middle: float) -> float:
+    if middle <= 0:
+        return 0.0
+    return (1.0 - min(abs(index - middle) / middle, 1.0)) * 0.08

src/small_cuts/hf_relay.py

@@ -0,0 +1,306 @@
+"""Hugging Face bucket relay for finished Small Cuts scenes.
+
+The Space uses this as a read-only scene source. The private engine or a local
+publisher writes finished scene manifests + media into an HF bucket; the Space
+downloads those files into a temp cache and serves them through Gradio.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import tempfile
+import threading
+import time
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Protocol
+from urllib.parse import quote, urlparse
+
+import httpx
+
+RELAY_BUCKET_ENV = "SMALL_CUTS_RELAY_BUCKET"
+RELAY_PREFIX_ENV = "SMALL_CUTS_RELAY_PREFIX"
+DEFAULT_RELAY_PREFIX = "relay"
+RELAY_MANIFEST = "manifest.json"
+RELAY_CACHE_DIR = Path(tempfile.gettempdir()) / "small-cuts-hf-relay"
+GRADIO_FILE_ROUTE = "/gradio_api/file="
+DEFAULT_SCENE_LIMIT = 60
+MEDIA_KEYS = ("frame_url", "card_url", "audio_url", "clip_url")
+PUBLISH_VISIBILITIES = frozenset({"shared", "public"})
+HTTP_TIMEOUT_S = 20.0
+MANIFEST_CACHE_TTL_S = 5.0
+RELAY_CACHE_MAX_BYTES = 512 * 1024 * 1024
+
+
+class BucketFileSystem(Protocol):
+    def cat(self, path: str) -> bytes: ...
+
+
+class BucketRelayError(RuntimeError):
+    """Raised when the bucket relay cannot read or hydrate its manifest."""
+
+
+@dataclass(frozen=True)
+class RelaySnapshot:
+    path: Path
+    scene_count: int
+    manifest_path: Path
+
+
+def gradio_file_url(path: str | Path) -> str:
+    return f"{GRADIO_FILE_ROUTE}{quote(str(path))}"
+
+
+def _normalize_prefix(prefix: str) -> str:
+    return prefix.strip().strip("/")
+
+
+def _safe_bucket_slug(bucket_id: str) -> str:
+    return bucket_id.replace("/", "__")
+
+
+class BucketSceneClient:
+    """Read finished NarratedScene payloads from a Hugging Face bucket manifest."""
+
+    base_url = ""
+    readonly = True
+
+    def __init__(
+        self,
+        bucket_id: str,
+        *,
+        prefix: str = DEFAULT_RELAY_PREFIX,
+        fs: BucketFileSystem | None = None,
+        cache_dir: str | Path | None = None,
+        register_static_paths: Any | None = None,
+        manifest_cache_ttl_s: float = MANIFEST_CACHE_TTL_S,
+        cache_max_bytes: int = RELAY_CACHE_MAX_BYTES,
+    ) -> None:
+        self.bucket_id = bucket_id.strip()
+        if not self.bucket_id:
+            raise ValueError("bucket_id is required")
+        self.prefix = _normalize_prefix(prefix)
+        self.root = f"hf://buckets/{self.bucket_id}"
+        if self.prefix:
+            self.root = f"{self.root}/{self.prefix}"
+        self._fs = fs
+        self.cache_dir = (
+            Path(cache_dir)
+            if cache_dir is not None
+            else (RELAY_CACHE_DIR / _safe_bucket_slug(self.bucket_id))
+        )
+        if cache_dir is None and self.prefix:
+            self.cache_dir = self.cache_dir / self.prefix
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        if register_static_paths is not None:
+            register_static_paths([self.cache_dir])
+        self.manifest_cache_ttl_s = manifest_cache_ttl_s
+        self.cache_max_bytes = cache_max_bytes
+        self._manifest_lock = threading.Lock()
+        self._media_lock = threading.Lock()
+        self._manifest_cache: tuple[float, list[dict[str, Any]]] | None = None
+        self._prune_cache()
+
+    @property
+    def fs(self) -> BucketFileSystem:
+        if self._fs is None:
+            from huggingface_hub import HfFileSystem
+
+            self._fs = HfFileSystem()
+        return self._fs
+
+    def list_scenes(self, limit: int = DEFAULT_SCENE_LIMIT) -> list[dict[str, Any]]:
+        with self._manifest_lock:
+            now = time.monotonic()
+            if (
+                self._manifest_cache is not None
+                and now - self._manifest_cache[0] < self.manifest_cache_ttl_s
+            ):
+                return copy.deepcopy(self._manifest_cache[1][-limit:])
+            try:
+                raw = self.fs.cat(f"{self.root}/{RELAY_MANIFEST}")
+            except FileNotFoundError:
+                self._manifest_cache = (now, [])
+                return []
+            try:
+                manifest = json.loads(raw.decode("utf-8"))
+                scenes = manifest.get("scenes", [])
+                if not isinstance(scenes, list):
+                    raise ValueError("relay manifest scenes must be a list")
+                hydrated = []
+                for scene in scenes:
+                    try:
+                        hydrated.append(self._hydrate_scene(scene))
+                    except FileNotFoundError:
+                        continue
+                self._manifest_cache = (now, hydrated)
+                return copy.deepcopy(hydrated[-limit:])
+            except (OSError, json.JSONDecodeError, KeyError, TypeError, ValueError) as exc:
+                raise BucketRelayError(
+                    f"could not read relay bucket {self.bucket_id}: {exc}"
+                ) from exc
+
+    def media_url(self, path: str | None) -> str | None:
+        if not path:
+            return None
+        if path.startswith(("http://", "https://", "data:", GRADIO_FILE_ROUTE)):
+            return path
+        relative = self._relative_media_path(path)
+        target = self.cache_dir / relative
+        with self._media_lock:
+            if not target.exists():
+                target.parent.mkdir(parents=True, exist_ok=True)
+                tmp = target.with_name(f".{target.name}.{os.getpid()}.{threading.get_ident()}.tmp")
+                try:
+                    tmp.write_bytes(self.fs.cat(f"{self.root}/{relative.as_posix()}"))
+                    tmp.replace(target)
+                finally:
+                    tmp.unlink(missing_ok=True)
+                self._prune_cache(protected=target)
+        return gradio_file_url(target)
+
+    def _hydrate_scene(self, scene: dict[str, Any]) -> dict[str, Any]:
+        hydrated = copy.deepcopy(scene)
+        media = hydrated.get("media")
+        if not isinstance(media, dict):
+            hydrated["media"] = {}
+            return hydrated
+        for key in MEDIA_KEYS:
+            media[key] = self.media_url(media.get(key))
+        return hydrated
+
+    def _relative_media_path(self, path: str) -> Path:
+        value = path.strip().lstrip("/")
+        if self.prefix and value.startswith(f"{self.prefix}/"):
+            value = value[len(self.prefix) + 1 :]
+        relative = Path(value)
+        if relative.is_absolute() or ".." in relative.parts:
+            raise ValueError(f"unsafe bucket media path: {path}")
+        return relative
+
+    def _prune_cache(self, protected: Path | None = None) -> None:
+        if self.cache_max_bytes <= 0 or not self.cache_dir.exists():
+            return
+        protected_resolved = protected.resolve() if protected is not None else None
+        files = [path for path in self.cache_dir.rglob("*") if path.is_file()]
+        total = sum(path.stat().st_size for path in files)
+        if total <= self.cache_max_bytes:
+            return
+        for path in sorted(files, key=lambda item: item.stat().st_mtime):
+            if protected_resolved is not None and path.resolve() == protected_resolved:
+                continue
+            size = path.stat().st_size
+            path.unlink(missing_ok=True)
+            total -= size
+            if total <= self.cache_max_bytes:
+                break
+
+
+def prepare_relay_snapshot(
+    engine_url: str,
+    output_dir: str | Path,
+    *,
+    limit: int = DEFAULT_SCENE_LIMIT,
+    include_private: bool = False,
+    source: str | None = None,
+    client: httpx.Client | None = None,
+) -> RelaySnapshot:
+    """Stage a bucket-ready manifest + media snapshot from the private engine."""
+    base_url = engine_url.rstrip("/")
+    output = Path(output_dir)
+    media_root = output / "media"
+    output.mkdir(parents=True, exist_ok=True)
+    media_root.mkdir(parents=True, exist_ok=True)
+    close_client = client is None
+    http = client or httpx.Client(timeout=HTTP_TIMEOUT_S)
+    try:
+        response = http.get(f"{base_url}/v1/scenes")
+        response.raise_for_status()
+        scenes = response.json().get("scenes", [])[-limit:]
+        published = [
+            _stage_scene_media(base_url, output, scene, http, source=source)
+            for scene in scenes
+            if _should_publish_scene(scene, include_private=include_private)
+        ]
+    finally:
+        if close_client:
+            http.close()
+    manifest = {
+        "contract_version": "1.1.0",
+        "published_at": datetime.now(timezone.utc).isoformat(),
+        "source_engine": base_url,
+        "scenes": published,
+    }
+    manifest_path = output / RELAY_MANIFEST
+    manifest_path.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n")
+    return RelaySnapshot(output, len(published), manifest_path)
+
+
+def _should_publish_scene(scene: dict[str, Any], *, include_private: bool) -> bool:
+    if include_private:
+        return True
+    return scene.get("visibility") in PUBLISH_VISIBILITIES
+
+
+def _stage_scene_media(
+    engine_url: str,
+    output_dir: Path,
+    scene: dict[str, Any],
+    client: httpx.Client,
+    *,
+    source: str | None = None,
+) -> dict[str, Any]:
+    staged = copy.deepcopy(scene)
+    if source:
+        staged["source"] = source
+        staged["source_icon"] = source
+    media = staged.get("media")
+    if not isinstance(media, dict):
+        staged["media"] = {}
+        return staged
+    scene_dir = _safe_path_segment(str(staged.get("scene_id") or "scene"))
+    for key in MEDIA_KEYS:
+        media[key] = _download_media(engine_url, output_dir, scene_dir, media.get(key), client)
+    return staged
+
+
+def _download_media(
+    engine_url: str,
+    output_dir: Path,
+    scene_dir: str,
+    url: str | None,
+    client: httpx.Client,
+) -> str | None:
+    if not url:
+        return None
+    if url.startswith(("data:", GRADIO_FILE_ROUTE)):
+        return None
+    absolute = url if url.startswith(("http://", "https://")) else f"{engine_url}/{url.lstrip('/')}"
+    relative = _relay_media_path(url, scene_dir)
+    target = output_dir / relative
+    target.parent.mkdir(parents=True, exist_ok=True)
+    response = client.get(absolute)
+    response.raise_for_status()
+    target.write_bytes(response.content)
+    return relative.as_posix()
+
+
+def _relay_media_path(url: str, scene_dir: str) -> Path:
+    parsed = urlparse(url)
+    source_path = (parsed.path if parsed.scheme else url.split("?", 1)[0]).lstrip("/")
+    if source_path.startswith("media/"):
+        relative = Path(source_path)
+    else:
+        filename = _safe_path_segment(Path(source_path).name or "media.bin")
+        relative = Path("media") / scene_dir / filename
+    if relative.is_absolute() or ".." in relative.parts:
+        raise ValueError(f"unsafe relay media path: {url}")
+    return relative
+
+
+def _safe_path_segment(value: str) -> str:
+    cleaned = "".join(ch if ch.isalnum() or ch in ("-", "_", ".") else "-" for ch in value)
+    return cleaned.strip(".-") or "item"

src/small_cuts/modal_upload.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+
+class ModalUploadError(RuntimeError):
+    """Raised when hosted post-cut inference fails."""
+
+
+@dataclass
+class ModalUploadClient:
+    base_url: str
+    token: str
+    http_client: httpx.Client | None = None
+    poll_interval_s: float = 1.0
+    timeout_s: float = 900.0
+
+    def submit_video(
+        self,
+        video_path: str | Path,
+        *,
+        uploader_hf_username: str,
+        style_key: str = "deadpan",
+        scene_hint: str = "",
+    ) -> dict[str, Any]:
+        close = self.http_client is None
+        client = self.http_client or httpx.Client(timeout=30.0, follow_redirects=True)
+        try:
+            job_id = self._submit(
+                client,
+                Path(video_path),
+                uploader_hf_username,
+                style_key,
+                scene_hint,
+            )
+            return self._poll(client, job_id)
+        finally:
+            if close:
+                client.close()
+
+    def _submit(
+        self,
+        client: httpx.Client,
+        video_path: Path,
+        uploader_hf_username: str,
+        style_key: str,
+        scene_hint: str,
+    ) -> str:
+        with video_path.open("rb") as handle:
+            response = client.post(
+                f"{self.base_url.rstrip('/')}/v1/cuts",
+                headers={"Authorization": f"Bearer {self.token}"},
+                data={
+                    "style_key": style_key,
+                    "scene_hint": scene_hint,
+                    "uploader_hf_username": uploader_hf_username,
+                },
+                files={"video": (video_path.name, handle, "video/mp4")},
+            )
+        response.raise_for_status()
+        job_id = response.json().get("job_id")
+        if not isinstance(job_id, str) or not job_id:
+            raise ModalUploadError("Modal did not return a job_id")
+        return job_id
+
+    def _poll(self, client: httpx.Client, job_id: str) -> dict[str, Any]:
+        deadline = time.monotonic() + self.timeout_s
+        while time.monotonic() < deadline:
+            response = client.get(
+                f"{self.base_url.rstrip('/')}/v1/cuts/{job_id}",
+                headers={"Authorization": f"Bearer {self.token}"},
+            )
+            if response.status_code == 202:
+                time.sleep(self.poll_interval_s)
+                continue
+            response.raise_for_status()
+            payload = response.json()
+            scene = payload.get("scene")
+            if not isinstance(scene, dict):
+                raise ModalUploadError("Modal completed without a scene payload")
+            return scene
+        raise ModalUploadError("Modal upload timed out")

src/small_cuts/narrator.py

@@ -0,0 +1,491 @@
+"""Narration pipeline with pluggable model backends.
+
+Backend selection is controlled by the SMALL_CUTS_BACKEND env var:
+
+- ``mock``         deterministic, no model weights — CI, tests, UI development
+- ``transformers`` small vision-language model via Hugging Face transformers
+- ``llama_cpp``    GGUF model via llama.cpp (CPU fallback / Llama Champion quest)
+
+All backends are local: no cloud APIs (Off the Grid quest).
+"""
+
+from __future__ import annotations
+
+import atexit
+import base64
+import io
+import json
+import os
+import shutil
+import socket
+import subprocess
+import threading
+import time
+from dataclasses import dataclass
+from functools import cache
+from pathlib import Path
+from typing import Protocol
+
+import httpx
+from PIL import Image
+
+from .styles import DEFAULT_STYLE_KEY, STYLES, build_messages, clean_scene_hint
+from .title_card import TITLE_MAX_LEN, derive_title
+
+# M1 final pick (docs/eval/run-006-scored.md): beats Qwen2.5-VL-7B head-to-head
+# for BOTH judges (Codex 7/10 vs 0/10, Gemini 9/10 vs 0/10 images passing).
+DEFAULT_MODEL_ID = "Qwen/Qwen3-VL-8B-Instruct"
+LLAMA_REPO_ID = "Qwen/Qwen3-VL-8B-Instruct-GGUF"
+LLAMA_GGUF_FILENAME = "Qwen3VL-8B-Instruct-Q4_K_M.gguf"
+LLAMA_MMPROJ_FILENAME = "mmproj-Qwen3VL-8B-Instruct-F16.gguf"
+LLAMA_TIMEOUT_S = 120.0
+DEFAULT_MAX_NEW_TOKENS = 160
+
+
+@dataclass(frozen=True)
+class Narration:
+    text: str
+    style_key: str
+    backend: str
+    model_id: str
+    latency_s: float
+    title: str = ""
+
+
+class Backend(Protocol):
+    name: str
+    model_id: str
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str: ...
+
+
+class MockBackend:
+    """Deterministic narrator used in CI and UI development.
+
+    Derives a few real features from the image (dimensions, brightness,
+    dominant hue) so the output visibly depends on the input without any
+    model weights.
+    """
+
+    name = "mock"
+    model_id = "mock-narrator-0"
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        style = STYLES[style_key]
+        r, g, b = image.convert("RGB").resize((1, 1)).getpixel((0, 0))
+        brightness = (r + g + b) / 3
+        light = "well-lit" if brightness > 127 else "dimly lit"
+        shape = "wide" if image.width >= image.height else "tall"
+        clean_hint = clean_scene_hint(scene_hint)
+        hint = f" {clean_hint}" if clean_hint else ""
+        narration = (
+            f"[{style.label}] The frame is {shape} and {light}, and the narrator has "
+            f"seen it all before.{hint} What happens next was, frankly, inevitable."
+        )
+        return json.dumps({"title": derive_title(narration), "narration": narration})
+
+
+class TransformersBackend:
+    """Small VLM via transformers. Lazily loads on first use.
+
+    On a ZeroGPU Space, decorate the hot path with ``spaces.GPU`` (handled in
+    app.py so this module stays importable without the ``spaces`` package).
+    """
+
+    name = "transformers"
+
+    def __init__(self, model_id: str | None = None) -> None:
+        self.model_id = model_id or os.environ.get("SMALL_CUTS_MODEL_ID", DEFAULT_MODEL_ID)
+        self._pipe = None
+        self._load_lock = threading.Lock()
+
+    def _load(self):
+        with self._load_lock:
+            if self._pipe is None:
+                import torch
+                from transformers import AutoModelForImageTextToText, AutoProcessor
+
+                self._processor = AutoProcessor.from_pretrained(self.model_id)
+                if torch.cuda.is_available():
+                    # Explicit .to("cuda") — ZeroGPU packs weights on this call;
+                    # accelerate's device_map dispatch would fight it.
+                    self._model = AutoModelForImageTextToText.from_pretrained(
+                        self.model_id, torch_dtype=torch.bfloat16
+                    ).to("cuda")
+                else:
+                    self._model = AutoModelForImageTextToText.from_pretrained(
+                        self.model_id, torch_dtype=torch.float32, device_map="auto"
+                    )
+                self._pipe = True
+        return self._processor, self._model
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        processor, model = self._load()
+        image = _downscale(image)
+        messages = build_messages(style_key, scene_hint)
+        # Attach the image to the user turn in the chat-template format.
+        chat = [
+            {"role": "system", "content": [{"type": "text", "text": messages[0]["content"]}]},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "image", "image": image},
+                    {"type": "text", "text": messages[1]["content"]},
+                ],
+            },
+        ]
+        inputs = processor.apply_chat_template(
+            chat,
+            add_generation_prompt=True,
+            tokenize=True,
+            return_dict=True,
+            return_tensors="pt",
+        ).to(model.device)
+        # Low temperature: judged eval showed small VLMs confabulate; sampling
+        # heat feeds it. Overridable per-run for eval sweeps.
+        temperature = _temperature()
+        output = model.generate(
+            **inputs,
+            max_new_tokens=_max_output_tokens(),
+            do_sample=temperature > 0,
+            temperature=temperature,
+        )
+        text = processor.batch_decode(
+            output[:, inputs["input_ids"].shape[1] :], skip_special_tokens=True
+        )[0]
+        return text.strip()
+
+
+def _downscale(image: Image.Image, max_side: int = 1024) -> Image.Image:
+    """Return a copy whose longest side is at most max_side."""
+    if max(image.size) <= max_side:
+        return image
+    resized = image.copy()
+    resized.thumbnail((max_side, max_side), Image.Resampling.LANCZOS)
+    return resized
+
+
+class LlamaCppBackend:
+    """GGUF vision model via llama.cpp — CPU fallback and Llama Champion quest."""
+
+    name = "llama_cpp"
+
+    def __init__(self, gguf_path: str | None = None, mmproj_path: str | None = None) -> None:
+        self._external_url = os.environ.get("SMALL_CUTS_LLAMA_URL", "").rstrip("/")
+        self._gguf_path = gguf_path or os.environ.get("SMALL_CUTS_GGUF_PATH", "")
+        self._mmproj_path = mmproj_path or os.environ.get("SMALL_CUTS_MMPROJ_PATH", "")
+        self.model_id = Path(self._gguf_path).name if self._gguf_path else LLAMA_REPO_ID
+        self._server_url = ""
+        self._process: subprocess.Popen | None = None
+        self._stderr_fh = None
+        self._cleanup_registered = False
+        self._spawn_lock = threading.Lock()
+
+    def generate(self, image: Image.Image, style_key: str, scene_hint: str) -> str:
+        if self._external_url:
+            server_url = self._external_url
+        else:
+            with self._spawn_lock:  # Gradio handlers are threaded; spawn once
+                server_url = self._ensure_server()
+        body = self._build_request(image, style_key, scene_hint)
+        try:
+            response = httpx.post(
+                f"{server_url}/v1/chat/completions",
+                json=body,
+                timeout=LLAMA_TIMEOUT_S,
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as exc:
+            raise RuntimeError(
+                f"llama-server at {server_url} returned HTTP "
+                f"{exc.response.status_code} for chat completion."
+            ) from exc
+        except httpx.RequestError as exc:
+            raise RuntimeError(f"Could not reach llama-server at {server_url}: {exc}") from exc
+
+        try:
+            content = response.json()["choices"][0]["message"]["content"]
+        except (ValueError, KeyError, IndexError, TypeError) as exc:
+            raise RuntimeError(
+                f"Unexpected llama-server response from {server_url}; expected "
+                "choices[0].message.content."
+            ) from exc
+        if not isinstance(content, str):
+            raise RuntimeError(
+                f"Unexpected llama-server response from {server_url}; message content was not text."
+            )
+        return content.strip()
+
+    def close(self) -> None:
+        process = self._process
+        if process is not None and process.poll() is None:
+            process.terminate()
+            try:
+                process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait(timeout=10)
+        self._process = None
+        self._server_url = ""
+        if self._stderr_fh is not None and not self._stderr_fh.closed:
+            self._stderr_fh.close()
+
+    def _build_request(self, image: Image.Image, style_key: str, scene_hint: str) -> dict:
+        messages = build_messages(style_key, scene_hint)
+        data_uri = _image_data_uri(_downscale(image))
+        return {
+            "messages": [
+                {"role": "system", "content": messages[0]["content"]},
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "image_url", "image_url": {"url": data_uri}},
+                        {"type": "text", "text": messages[1]["content"]},
+                    ],
+                },
+            ],
+            "temperature": _temperature(),
+            "max_tokens": _max_output_tokens(),
+        }
+
+    def _ensure_server(self) -> str:
+        if self._server_url and self._process is not None and self._process.poll() is None:
+            return self._server_url
+        if self._process is not None and self._process.poll() is not None:
+            self._process = None
+            self._server_url = ""
+
+        binary = _llama_server_binary()
+        gguf_path, mmproj_path = self._model_paths()
+        port = _free_port()
+        self._server_url = f"http://127.0.0.1:{port}"
+        command = [
+            binary,
+            "-m",
+            gguf_path,
+            "--mmproj",
+            mmproj_path,
+            "--port",
+            str(port),
+            "-c",
+            "8192",
+            "--image-max-tokens",
+            "1024",
+            "--host",
+            "127.0.0.1",
+        ]
+        try:
+            self._process = subprocess.Popen(
+                command,
+                stdout=subprocess.DEVNULL,
+                stderr=self._stderr_file(),
+            )
+        except OSError as exc:
+            self._server_url = ""
+            raise RuntimeError(
+                f"Could not start llama-server with {binary!r}. Install llama.cpp "
+                "with `brew install llama.cpp`, set SMALL_CUTS_LLAMA_SERVER to the "
+                "binary path, or point SMALL_CUTS_LLAMA_URL at an already-running server."
+            ) from exc
+
+        if not self._cleanup_registered:
+            atexit.register(self.close)
+            self._cleanup_registered = True
+        self._wait_for_health(self._server_url)
+        return self._server_url
+
+    def _model_paths(self) -> tuple[str, str]:
+        gguf_path = self._gguf_path
+        mmproj_path = self._mmproj_path
+        if gguf_path and mmproj_path:
+            return gguf_path, mmproj_path
+
+        try:
+            from huggingface_hub import hf_hub_download
+        except ImportError as exc:
+            raise RuntimeError(
+                "huggingface_hub is required to resolve the default llama.cpp model. "
+                "Install the local dependencies, or set SMALL_CUTS_GGUF_PATH and "
+                "SMALL_CUTS_MMPROJ_PATH to local files."
+            ) from exc
+
+        if not gguf_path:
+            gguf_path = hf_hub_download(LLAMA_REPO_ID, LLAMA_GGUF_FILENAME)
+        if not mmproj_path:
+            mmproj_path = hf_hub_download(LLAMA_REPO_ID, LLAMA_MMPROJ_FILENAME)
+        return gguf_path, mmproj_path
+
+    def _stderr_file(self):
+        import tempfile
+
+        if self._stderr_fh is not None and not self._stderr_fh.closed:
+            self._stderr_fh.close()
+        self._stderr_path = Path(tempfile.gettempdir()) / f"llama-server-{os.getpid()}.err"
+        self._stderr_fh = self._stderr_path.open("w")
+        return self._stderr_fh
+
+    def _stderr_tail(self, lines: int = 5) -> str:
+        path = getattr(self, "_stderr_path", None)
+        if not path or not Path(path).exists():
+            return ""
+        tail = Path(path).read_text().splitlines()[-lines:]
+        return (" Last stderr lines: " + " | ".join(tail)) if tail else ""
+
+    def _wait_for_health(self, server_url: str) -> None:
+        deadline = time.monotonic() + LLAMA_TIMEOUT_S
+        while time.monotonic() < deadline:
+            if self._process is not None and self._process.poll() is not None:
+                raise RuntimeError(
+                    f"llama-server exited before becoming healthy at {server_url} "
+                    f"(a port conflict is possible).{self._stderr_tail()} "
+                    "Check the GGUF/mmproj paths and llama.cpp installation."
+                )
+            try:
+                response = httpx.get(f"{server_url}/health", timeout=2.0)
+                if response.status_code == 200:
+                    return
+            except httpx.RequestError:
+                pass
+            time.sleep(0.5)
+
+        self.close()
+        raise RuntimeError(
+            f"Timed out waiting for llama-server at {server_url}/health after "
+            f"{int(LLAMA_TIMEOUT_S)} seconds. Check model load time, GGUF/mmproj paths, "
+            "or use SMALL_CUTS_LLAMA_URL to point at a server you started manually."
+        )
+
+
+def _image_data_uri(image: Image.Image) -> str:
+    buffer = io.BytesIO()
+    image.convert("RGB").save(buffer, format="JPEG", quality=90)
+    encoded = base64.b64encode(buffer.getvalue()).decode("ascii")
+    return f"data:image/jpeg;base64,{encoded}"
+
+
+def _temperature() -> float:
+    try:
+        return float(os.environ.get("SMALL_CUTS_TEMPERATURE", "0.3"))
+    except ValueError as exc:
+        raise RuntimeError("SMALL_CUTS_TEMPERATURE must be a floating-point number.") from exc
+
+
+def _max_output_tokens() -> int:
+    raw = os.environ.get("SMALL_CUTS_MAX_NEW_TOKENS", "").strip()
+    if not raw:
+        return DEFAULT_MAX_NEW_TOKENS
+    try:
+        value = int(raw)
+    except ValueError as exc:
+        raise RuntimeError("SMALL_CUTS_MAX_NEW_TOKENS must be an integer.") from exc
+    if value < 1:
+        raise RuntimeError("SMALL_CUTS_MAX_NEW_TOKENS must be greater than zero.")
+    return value
+
+
+def _llama_server_binary() -> str:
+    configured = os.environ.get("SMALL_CUTS_LLAMA_SERVER", "")
+    binary = configured or shutil.which("llama-server")
+    if binary and _is_executable(binary):
+        return binary
+    raise RuntimeError(
+        "llama.cpp backend needs a llama-server binary. Install it with "
+        "`brew install llama.cpp`, set SMALL_CUTS_LLAMA_SERVER to the binary path, "
+        "or set SMALL_CUTS_LLAMA_URL to an already-running llama-server."
+    )
+
+
+def _is_executable(path: str) -> bool:
+    resolved = path if os.path.sep in path else shutil.which(path)
+    return bool(resolved and Path(resolved).is_file() and os.access(resolved, os.X_OK))
+
+
+def _free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+_BACKENDS = {
+    "mock": MockBackend,
+    "transformers": TransformersBackend,
+    "llama_cpp": LlamaCppBackend,
+}
+
+
+@cache
+def _backend_instance(key: str) -> Backend:
+    return _BACKENDS[key]()
+
+
+def get_backend(name: str | None = None) -> Backend:
+    key = (name or os.environ.get("SMALL_CUTS_BACKEND", "mock")).lower()
+    if key not in _BACKENDS:
+        raise ValueError(f"Unknown backend {key!r}; expected one of {sorted(_BACKENDS)}")
+    # One instance per backend: model weights load once per process, not per call.
+    return _backend_instance(key)
+
+
+def narrate(
+    image: Image.Image,
+    style_key: str = DEFAULT_STYLE_KEY,
+    scene_hint: str = "",
+    backend: Backend | None = None,
+) -> Narration:
+    """Narrate a single moment. The one entry point the UI calls."""
+    if style_key not in STYLES:
+        raise ValueError(f"Unknown style {style_key!r}")
+    backend = backend or get_backend()
+    start = time.perf_counter()
+    raw = backend.generate(image, style_key, scene_hint)
+    title, text = _parse_generation(raw)
+    return Narration(
+        text=text,
+        style_key=style_key,
+        backend=backend.name,
+        model_id=backend.model_id,
+        latency_s=time.perf_counter() - start,
+        title=title,
+    )
+
+
+def _parse_generation(raw: str) -> tuple[str, str]:
+    """Return (title, narration), tolerating legacy plain-text model output."""
+    text = raw.strip()
+    if not text:
+        return "Untitled Scene", ""
+    parsed = _json_object_from_model(text)
+    if parsed is not None:
+        narration = str(parsed.get("narration", "")).strip()
+        title = _clean_title(str(parsed.get("title", "")).strip(), fallback=narration)
+        if narration:
+            return title, narration
+    return derive_title(text), text
+
+
+def _json_object_from_model(text: str) -> dict | None:
+    candidates = [text]
+    if text.startswith("```"):
+        stripped = text.strip("`").strip()
+        if stripped.lower().startswith("json"):
+            stripped = stripped[4:].strip()
+        candidates.append(stripped)
+    first = text.find("{")
+    last = text.rfind("}")
+    if first != -1 and last > first:
+        candidates.append(text[first : last + 1])
+    for candidate in candidates:
+        try:
+            value = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(value, dict):
+            return value
+    return None
+
+
+def _clean_title(title: str, fallback: str) -> str:
+    title = " ".join(title.replace("\n", " ").split())
+    if not title:
+        return derive_title(fallback)
+    return derive_title(title, max_len=TITLE_MAX_LEN)

src/small_cuts/observability.py

@@ -0,0 +1,74 @@
+"""Optional Sentry observability for demo/runtime failures.
+
+No Sentry traffic is sent unless ``SENTRY_DSN`` is configured. Payload scrubbing
+keeps frames, audio, cookies, and auth headers out of events.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+SENTRY_DSN_ENV = "SENTRY_DSN"
+SENTRY_ENV_ENV = "SENTRY_ENVIRONMENT"
+SENTRY_RELEASE_ENV = "SENTRY_RELEASE"
+SENSITIVE_HEADERS = {"authorization", "cookie", "x-api-key", "x-forwarded-for"}
+
+_INITIALIZED = False
+
+
+def init_sentry(dsn: str | None = None, *, sdk: Any | None = None) -> bool:
+    global _INITIALIZED
+    dsn = dsn if dsn is not None else os.environ.get(SENTRY_DSN_ENV, "").strip()
+    if not dsn:
+        return False
+    if _INITIALIZED:
+        return True
+    sdk = sdk or _import_sentry_sdk()
+    if sdk is None:
+        return False
+    sdk.init(
+        dsn=dsn,
+        environment=os.environ.get(SENTRY_ENV_ENV) or os.environ.get("SPACE_ID") or "local",
+        release=os.environ.get(SENTRY_RELEASE_ENV) or os.environ.get("SPACE_COMMIT_SHA"),
+        send_default_pii=False,
+        attach_stacktrace=True,
+        traces_sample_rate=0.0,
+        before_send=_scrub_event,
+    )
+    _INITIALIZED = True
+    return True
+
+
+def capture_exception(exc: BaseException, *, sdk: Any | None = None) -> None:
+    if not _INITIALIZED and not init_sentry(sdk=sdk):
+        return
+    sdk = sdk or _import_sentry_sdk()
+    if sdk is not None:
+        sdk.capture_exception(exc)
+
+
+def _import_sentry_sdk() -> Any | None:
+    try:
+        import sentry_sdk
+    except ImportError:
+        return None
+    return sentry_sdk
+
+
+def _scrub_event(event: dict[str, Any], _hint: dict[str, Any]) -> dict[str, Any]:
+    request = event.get("request")
+    if isinstance(request, dict):
+        request.pop("data", None)
+        request.pop("cookies", None)
+        headers = request.get("headers")
+        if isinstance(headers, dict):
+            request["headers"] = {
+                key: value for key, value in headers.items() if key.lower() not in SENSITIVE_HEADERS
+            }
+    return event
+
+
+def reset_for_tests() -> None:
+    global _INITIALIZED
+    _INITIALIZED = False

src/small_cuts/seed_media/desk-laptop.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c50d9aef2c2b3b591b37d28eb24eb1207ee1c1bbd67fd2c387b2de5ed0733480
+size 257229

src/small_cuts/seed_media/desk-laptop.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c6d9e22a67888f755c03d70de70c45ccc2d8b853e0c2f7b6bf00ae58e2f472be
+size 2537344

src/small_cuts/seed_media/night-drive.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e8dc4b2d254d62e571e57fba1df98f87e233b75d78426841a864ea135a033040
+size 246573

src/small_cuts/seed_media/night-drive.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:06c1866c429bb5a47333e38a56f57ae536b5eb806e6cfedbbb201aea225e26f2
+size 3427164

src/small_cuts/seed_media/rayuela.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:dfd85e684c1c231aa0301c47949d427e31646e750ab01d7f52a72b961add1010
+size 294957

src/small_cuts/seed_media/rayuela.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3878bd95d642e3befdc767d2b54d4c4acce8cb43ffef46d1c232ba793cebed01
+size 4268710

src/small_cuts/seed_media/street-parked-car.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c7b15be641666c6e99a4038d94fd09f47bce3dada55fa66d10f63c80c6af76b5
+size 169965

src/small_cuts/seed_media/street-parked-car.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3d8444745071aab9dc208e77753328b248f472eac11861a920e77e7e607bee8e
+size 4136123

src/small_cuts/seed_media/the-stumble.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ddd9eab9ae92d64c90a94b98759db0f4aa31ccc9cd79ca89c9ef6ea9184e3c2e
+size 233901

src/small_cuts/seed_media/the-stumble.mp4

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f8c6ba5d9c32717da065e2a1c923e9c1e96e7830aa5e00038a0e88d367d19baf
+size 3395323

src/small_cuts/space_hooks.py

@@ -0,0 +1,113 @@
+"""Push hooks for relay-scene updates in the Gradio Space.
+
+The Space should not poll Hugging Face control-plane APIs or repeatedly poll the
+relay bucket. The local publisher calls the protected hook after it writes a new
+manifest; browser clients keep one SSE connection open and refresh once per
+hook event.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import hmac
+import json
+import os
+from collections.abc import AsyncIterator
+from typing import Annotated, Any
+
+from fastapi import Body, FastAPI, Header, HTTPException, Request
+from fastapi.responses import StreamingResponse
+
+RELAY_HOOK_TOKEN_ENV = "SMALL_CUTS_RELAY_HOOK_TOKEN"
+RELAY_HOOK_PATH = "/small-cuts/hooks/relay-scene"
+RELAY_EVENTS_PATH = "/small-cuts/events"
+SSE_HEARTBEAT_S = 15.0
+
+
+class RelayEventHub:
+    def __init__(self) -> None:
+        self._next_id = 0
+        self._subscribers: set[asyncio.Queue[dict[str, Any]]] = set()
+
+    def subscribe(self) -> asyncio.Queue[dict[str, Any]]:
+        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue(maxsize=8)
+        self._subscribers.add(queue)
+        return queue
+
+    def unsubscribe(self, queue: asyncio.Queue[dict[str, Any]]) -> None:
+        self._subscribers.discard(queue)
+
+    async def publish(self, payload: dict[str, Any] | None = None) -> dict[str, Any]:
+        self._next_id += 1
+        event = {"id": self._next_id, "payload": payload or {}}
+        stale: list[asyncio.Queue[dict[str, Any]]] = []
+        for queue in list(self._subscribers):
+            try:
+                queue.put_nowait(event)
+            except asyncio.QueueFull:
+                stale.append(queue)
+        for queue in stale:
+            self.unsubscribe(queue)
+        return event
+
+
+def install_relay_hooks(app: FastAPI, *, hub: RelayEventHub | None = None) -> RelayEventHub:
+    if getattr(app.state, "small_cuts_relay_hooks_installed", False):
+        return app.state.small_cuts_relay_event_hub
+
+    event_hub = hub or RelayEventHub()
+    app.state.small_cuts_relay_hooks_installed = True
+    app.state.small_cuts_relay_event_hub = event_hub
+
+    @app.post(RELAY_HOOK_PATH, status_code=202)
+    async def relay_scene_hook(
+        payload: Annotated[dict[str, Any] | None, Body()] = None,
+        authorization: Annotated[str | None, Header()] = None,
+    ) -> dict[str, Any]:
+        _require_hook_authorization(authorization)
+        event = await event_hub.publish(payload or {})
+        return {"status": "accepted", "event_id": event["id"]}
+
+    @app.get(RELAY_EVENTS_PATH)
+    async def relay_events(request: Request) -> StreamingResponse:
+        return StreamingResponse(
+            relay_event_stream(event_hub, request, heartbeat_s=SSE_HEARTBEAT_S),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "X-Accel-Buffering": "no"},
+        )
+
+    return event_hub
+
+
+async def relay_event_stream(
+    event_hub: RelayEventHub,
+    request: Request,
+    *,
+    heartbeat_s: float = SSE_HEARTBEAT_S,
+) -> AsyncIterator[str]:
+    queue = event_hub.subscribe()
+    try:
+        yield _sse("ready", {"status": "connected"})
+        while True:
+            if await request.is_disconnected():
+                break
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=heartbeat_s)
+            except asyncio.TimeoutError:
+                yield ": ping\n\n"
+                continue
+            yield _sse("relay-scene", event)
+    finally:
+        event_hub.unsubscribe(queue)
+
+
+def _require_hook_authorization(authorization: str | None) -> None:
+    expected = os.environ.get(RELAY_HOOK_TOKEN_ENV, "").strip()
+    if not expected:
+        raise HTTPException(status_code=503, detail="relay hook is not configured")
+    if not authorization or not hmac.compare_digest(authorization, f"Bearer {expected}"):
+        raise HTTPException(status_code=401, detail="unauthorized")
+
+
+def _sse(event: str, data: dict[str, Any]) -> str:
+    return f"event: {event}\ndata: {json.dumps(data, separators=(',', ':'))}\n\n"

src/small_cuts/styles.py

@@ -0,0 +1,146 @@
+"""Director style presets and prompt construction for the narrator."""
+
+from dataclasses import dataclass
+
+# v3 — evidence-based rebalance. The judged A/B (docs/eval/prompt-ab-comparison.md)
+# showed v2's "find the story" license cost gemma -0.77 S and -0.67 G with zero V
+# gain. v3 restores v1's hard grounding and moves all voice into tone, not facts.
+SYSTEM_PROMPT = (
+    "You are the omniscient narrator of this person's life, in the spirit of the "
+    "narrators in 'The Invention of Lying': you can only say what is true, you see "
+    "the scene exactly as it is, and you describe it with cinematic certainty. "
+    "Narrate ONLY what is visible or directly inferable from the image. Never invent "
+    "objects, people, actions, weather, or sounds. If you are not certain something "
+    "is in the image, leave it out. Quote text on signs only when it is clearly "
+    "legible. Pick the one or two most telling visible details and build the "
+    "narration on them — the director's style changes the TONE of your sentences, "
+    "never the facts. Write 2 to 4 sentences, present tense, third person. "
+    "Also write a short movie-title style title grounded in the same visible facts. "
+    "Output only a compact JSON object with exactly two string keys: "
+    "`title` and `narration`. No markdown, no commentary, no emoji."
+)
+
+
+@dataclass(frozen=True)
+class DirectorStyle:
+    """A narration style, presented to users as a director's cut."""
+
+    key: str
+    label: str
+    direction: str
+    example: str  # one-shot example narration to anchor the voice
+
+
+STYLES: dict[str, DirectorStyle] = {
+    style.key: style
+    for style in (
+        DirectorStyle(
+            key="deadpan",
+            label="Deadpan Omniscient (the classic)",
+            direction=(
+                "Flat, matter-of-fact omniscience. Gentle comic timing comes from "
+                "stating slightly-too-honest truths plainly, the way the narrators "
+                "in 'The Invention of Lying' would."
+            ),
+            example=(
+                "He stirs the coffee for the fourth time, though nothing about it "
+                "has changed. It is, and will remain, slightly too bitter. He "
+                "drinks it anyway, because the mug was a gift and he is sentimental."
+            ),
+        ),
+        DirectorStyle(
+            key="noir",
+            label="Noir Detective",
+            direction=(
+                "Hard-boiled 1940s noir voiceover. Shadows, rain, cigarettes that "
+                "aren't there. World-weary metaphors grounded in what's actually visible."
+            ),
+            example=(
+                "The desk lamp threw its light like an accusation. Somewhere in "
+                "that pile of cables was an answer, and answers in this town never "
+                "came cheap."
+            ),
+        ),
+        DirectorStyle(
+            key="nature_doc",
+            label="Nature Documentary",
+            direction=(
+                "Hushed, reverent wildlife-documentary narration. Treat the subject "
+                "as a fascinating specimen observed in its natural habitat."
+            ),
+            example=(
+                "Here, in the fluorescent clearing of the open-plan office, the "
+                "adult male attempts a ritual as old as the species itself: the "
+                "fourth coffee before noon."
+            ),
+        ),
+        DirectorStyle(
+            key="trailer",
+            label="Epic Trailer Voice",
+            direction=(
+                "Booming movie-trailer gravitas. Short punchy sentences. 'In a "
+                "world...' energy applied to a completely ordinary moment."
+            ),
+            example=("One man. One sandwich. This summer, lunch... changes everything."),
+        ),
+        DirectorStyle(
+            key="telenovela",
+            label="Telenovela",
+            direction=(
+                "Breathless melodrama. Every glance is betrayal, every object holds "
+                "a secret. Spanish-telenovela emotional stakes for mundane scenes."
+            ),
+            example=(
+                "She looks at the empty fridge — the same fridge that promised her "
+                "so much on Sunday. Inside, only mustard remains. Mustard... and lies."
+            ),
+        ),
+        DirectorStyle(
+            key="symmetrist",
+            label="Wes Anderson Symmetrist",
+            direction=(
+                "Precise, whimsical, faux-naive storybook narration. Note colors, "
+                "symmetry, and small formal details. Affectionate melancholy."
+            ),
+            example=(
+                "The bicycle is mustard yellow, which is also the color of the "
+                "third button on his cardigan. He parked it at exactly the angle "
+                "his father would have disapproved of, which is why he did."
+            ),
+        ),
+    )
+}
+
+DEFAULT_STYLE_KEY = "deadpan"
+MAX_SCENE_HINT_CHARS = 280
+
+
+def clean_scene_hint(scene_hint: str) -> str:
+    return scene_hint.strip()[:MAX_SCENE_HINT_CHARS]
+
+
+def style_choices() -> list[tuple[str, str]]:
+    """(label, key) pairs for UI dropdowns."""
+    return [(style.label, style.key) for style in STYLES.values()]
+
+
+def build_messages(style_key: str, scene_hint: str = "") -> list[dict]:
+    """Build the chat messages (minus the image, attached by the backend)."""
+    style = STYLES[style_key]
+    hint = clean_scene_hint(scene_hint)
+    user_text = (
+        f"Director's cut: {style.label}.\n"
+        f"Style direction: {style.direction}\n"
+        f"Example of the voice (different scene): {style.example}\n"
+    )
+    if hint:
+        user_text += f"Context offered by the person living this moment: {hint}\n"
+    user_text += (
+        "Now title and narrate the attached moment as JSON, for example: "
+        '{"title":"The Fourth Coffee","narration":"He stirs the coffee again. '
+        'Nothing about it improves."}'
+    )
+    return [
+        {"role": "system", "content": SYSTEM_PROMPT},
+        {"role": "user", "content": user_text},
+    ]

src/small_cuts/theme.py

@@ -0,0 +1,73 @@
+"""Off-Brand Gradio theme for Small Cuts."""
+
+from __future__ import annotations
+
+import gradio as gr
+
+from .title_card import STYLE_CARDS
+
+CANVAS = STYLE_CARDS["trailer"][0]
+MARQUEE_GOLD = STYLE_CARDS["trailer"][1]
+BONE_WHITE = STYLE_CARDS["noir"][1]
+LIFTED_CANVAS = "#16161C"
+BORDER = "#2A292F"
+
+
+class OffBrand(gr.themes.Base):
+    """Dark cinematic Gradio theme using the Small Cuts house palette."""
+
+    def __init__(self) -> None:
+        super().__init__(
+            font=[gr.themes.GoogleFont("Spectral"), "serif"],
+            font_mono=[gr.themes.GoogleFont("IBM Plex Mono"), "monospace"],
+        )
+        self.set(
+            body_background_fill=CANVAS,
+            body_background_fill_dark=CANVAS,
+            body_text_color=BONE_WHITE,
+            body_text_color_dark=BONE_WHITE,
+            background_fill_primary=CANVAS,
+            background_fill_primary_dark=CANVAS,
+            background_fill_secondary=LIFTED_CANVAS,
+            background_fill_secondary_dark=LIFTED_CANVAS,
+            block_background_fill=LIFTED_CANVAS,
+            block_background_fill_dark=LIFTED_CANVAS,
+            block_border_color=BORDER,
+            block_border_color_dark=BORDER,
+            block_title_text_color=MARQUEE_GOLD,
+            block_title_text_color_dark=MARQUEE_GOLD,
+            border_color_primary=BORDER,
+            border_color_primary_dark=BORDER,
+            input_background_fill=STYLE_CARDS["noir"][0],
+            input_background_fill_dark=STYLE_CARDS["noir"][0],
+            input_background_fill_focus=CANVAS,
+            input_background_fill_focus_dark=CANVAS,
+            input_border_color=BORDER,
+            input_border_color_dark=BORDER,
+            link_text_color=MARQUEE_GOLD,
+            link_text_color_dark=MARQUEE_GOLD,
+            button_primary_background_fill=MARQUEE_GOLD,
+            button_primary_background_fill_dark=MARQUEE_GOLD,
+            button_primary_border_color=MARQUEE_GOLD,
+            button_primary_border_color_dark=MARQUEE_GOLD,
+            button_primary_text_color=CANVAS,
+            button_primary_text_color_dark=CANVAS,
+            button_secondary_background_fill=LIFTED_CANVAS,
+            button_secondary_background_fill_dark=LIFTED_CANVAS,
+            button_secondary_text_color=BONE_WHITE,
+            button_secondary_text_color_dark=BONE_WHITE,
+            button_secondary_border_color=BORDER,
+            button_secondary_border_color_dark=BORDER,
+            # P0 contrast fixes (#28): code chips rendered near-white-on-white
+            # and the in-block labels were too dim on the charcoal canvas.
+            code_background_fill=STYLE_CARDS["noir"][0],
+            code_background_fill_dark=STYLE_CARDS["noir"][0],
+            block_label_text_color=MARQUEE_GOLD,
+            block_label_text_color_dark=MARQUEE_GOLD,
+            block_label_background_fill=LIFTED_CANVAS,
+            block_label_background_fill_dark=LIFTED_CANVAS,
+        )
+
+
+def build_theme() -> gr.themes.Base:
+    return OffBrand()

src/small_cuts/title_card.py

@@ -0,0 +1,183 @@
+"""Deterministic movie-style title cards for Small Cuts."""
+
+from PIL import Image, ImageDraw, ImageFont
+
+from .styles import STYLES
+
+TITLE_MAX_LEN = 60
+
+STYLE_CARDS = {
+    "deadpan": ("#F2EFE6", "#1A1A1A", "rules"),
+    "noir": ("#0D0D0F", "#E8E4D8", "hard_frame"),
+    "nature_doc": ("#0E2A1B", "#F0E9D2", "double_frame"),
+    "trailer": ("#101014", "#D4AF37", "spaced"),
+    "telenovela": ("#5C0A14", "#FFE9EC", "ornament"),
+    "symmetrist": ("#F7D6C9", "#5B3A29", "thin_frame"),
+}
+
+
+def derive_title(text: str, max_len: int = TITLE_MAX_LEN) -> str:
+    value = text.strip()
+    if value.startswith("["):
+        tag_end = value.find("]")
+        if tag_end != -1:
+            value = value[tag_end + 1 :].strip()
+    if not value:
+        return "Untitled Scene"
+    title = _first_clause(value).strip()
+    if not title:
+        return "Untitled Scene"
+    return _truncate_title(title, max_len)
+
+
+def render_title_card(
+    title: str,
+    style_key: str,
+    size: tuple[int, int] = (1280, 720),
+) -> Image.Image:
+    style = STYLES[style_key]
+    bg, fg, treatment = STYLE_CARDS[style_key]
+    width, height = size
+    image = Image.new("RGB", size, bg)
+    draw = ImageDraw.Draw(image)
+    if treatment == "hard_frame":
+        inset = max(8, min(width, height) // 22)
+        box = (inset, inset, width - inset - 1, height - inset - 1)
+        draw.rectangle(box, outline=fg, width=2)
+    elif treatment == "double_frame":
+        inset = max(8, min(width, height) // 24)
+        for offset in (inset, inset + max(4, inset // 3)):
+            box = (offset, offset, width - offset - 1, height - offset - 1)
+            draw.rectangle(box, outline=fg)
+    elif treatment == "thin_frame":
+        draw.rectangle((8, 8, width - 9, height - 9), outline=fg)
+    margin = max(12, width // 9)
+    content_width = max(1, width - margin * 2)
+    max_title_height = max(24, int(height * 0.42))
+    spaced = treatment == "spaced"
+    for size_px in range(max(12, int(height * 0.12)), 5, -2):
+        title_font = _font(size_px)
+        lines = _wrap(draw, title.strip().upper(), title_font, content_width, spaced)
+        block_width, block_height = _block(draw, lines, title_font)
+        if block_width <= content_width and block_height <= max_title_height:
+            break
+    else:
+        title_font = _font(6)
+        lines = _wrap(draw, title.strip().upper(), title_font, content_width, spaced)
+        _, block_height = _block(draw, lines, title_font)
+    kicker_font = _font(max(10, int(height * 0.04)))
+    subtitle_font = _font(max(10, int(height * 0.035)))
+    _center(draw, "A SMALL CUTS PICTURE", width, int(height * 0.17), kicker_font, fg)
+    if lines:
+        title_top = max(int(height * 0.28), (height - block_height) // 2)
+        title_size = getattr(title_font, "size", 12)
+        if treatment == "rules":
+            top_rule = max(8, title_top - title_size // 2)
+            bottom_rule = min(height - 8, title_top + block_height + title_size // 2)
+            draw.line((margin, top_rule, width - margin, top_rule), fill=fg)
+            draw.line((margin, bottom_rule, width - margin, bottom_rule), fill=fg)
+        line_height = _measure(draw, "Ag", title_font)[1]
+        y = title_top
+        for line in lines:
+            _center(draw, line, width, y, title_font, fg)
+            y += line_height
+        if treatment == "ornament":
+            _center(draw, "♦ ─── ♦", width, y + max(8, title_size // 4), subtitle_font, fg)
+    subtitle_y = min(height - getattr(subtitle_font, "size", 10) * 2, int(height * 0.78))
+    _center(draw, style.label.upper(), width, subtitle_y, subtitle_font, fg)
+    return image
+
+
+def _first_clause(text: str) -> str:
+    index = 0
+    while index < len(text):
+        if text.startswith("...", index):
+            if _ellipsis_ends_clause(text, index, 3):
+                return text[:index]
+            index += 3
+            continue
+        if text[index] == "…":
+            if _ellipsis_ends_clause(text, index, 1):
+                return text[:index]
+        elif text[index] in ".!?;—":
+            return text[:index]
+        index += 1
+    return text
+
+
+def _ellipsis_ends_clause(text: str, index: int, width: int) -> bool:
+    if len(text[:index].split()) < 3:
+        return False
+    next_index = index + width
+    if next_index >= len(text) or not text[next_index].isspace():
+        return False
+    while next_index < len(text) and text[next_index].isspace():
+        next_index += 1
+    return next_index < len(text) and text[next_index].isupper()
+
+
+def _truncate_title(title: str, max_len: int) -> str:
+    if max_len < 1:
+        return ""
+    if len(title) <= max_len:
+        return title
+    if max_len == 1:
+        return "…"
+    cut = -1
+    for index, char in enumerate(title[:max_len]):
+        if char.isspace():
+            cut = index
+    if cut <= 0:
+        return "…"
+    return f"{title[:cut].rstrip()}…"
+
+
+def _font(size):
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:
+        return ImageFont.load_default()
+
+
+def _wrap(draw, text, font, max_width, spaced):
+    def show(value):
+        return " ".join(value) if spaced else value
+
+    def fits(value):
+        return _measure(draw, show(value), font)[0] <= max_width
+
+    lines = []
+    current = ""
+    for word in text.split():
+        candidate = f"{current} {word}".strip()
+        if fits(candidate):
+            current = candidate
+            continue
+        if current:
+            lines.append(show(current))
+        current = word
+        while len(current) > 1 and not fits(current):
+            split = 1
+            while split < len(current) and fits(current[: split + 1]):
+                split += 1
+            lines.append(show(current[:split]))
+            current = current[split:]
+    if current:
+        lines.append(show(current))
+    return lines
+
+
+def _block(draw, lines, font):
+    line_height = _measure(draw, "Ag", font)[1]
+    widths = [_measure(draw, line, font)[0] for line in lines]
+    return max(widths, default=0), len(lines) * line_height
+
+
+def _center(draw, text, width, y, font, fill):
+    x = (width - _measure(draw, text, font)[0]) / 2
+    draw.text((x, y), text, font=font, fill=fill)
+
+
+def _measure(draw, text, font):
+    left, top, right, bottom = draw.textbbox((0, 0), text, font=font)
+    return right - left, bottom - top

src/small_cuts/tts.py

@@ -0,0 +1,133 @@
+"""Text-to-speech pipeline with pluggable local backends."""
+
+from __future__ import annotations
+
+import os
+import threading
+import time
+from dataclasses import dataclass
+from functools import cache
+from typing import Protocol
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class Speech:
+    sample_rate: int
+    audio: np.ndarray
+    backend: str
+    model_id: str
+    latency_s: float
+
+
+class TTSBackend(Protocol):
+    name: str
+    model_id: str
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]: ...
+
+
+class MockTTSBackend:
+    name = "mock"
+    model_id = "mock-tts-0"
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]:
+        sample_rate = 24_000
+        duration_s = min(2.0, max(0.2, len(text) / 40))
+        encoded = text.encode("utf-8")
+        frequency = 220 + sum((i + 1) * byte for i, byte in enumerate(encoded)) % 220
+        samples = int(sample_rate * duration_s)
+        t = np.arange(samples, dtype=np.float32) / sample_rate
+        audio = 0.25 * np.sin(2 * np.pi * frequency * t)
+        return sample_rate, audio.astype(np.float32, copy=False)
+
+
+class KokoroBackend:
+    name = "kokoro"
+    model_id = "hexgrad/Kokoro-82M"
+
+    def __init__(self) -> None:
+        self._pipeline = None
+        self._load_lock = threading.Lock()
+
+    def _load(self):
+        with self._load_lock:
+            if self._pipeline is None:
+                try:
+                    from kokoro import KPipeline
+                except ImportError as exc:
+                    raise RuntimeError(
+                        "Kokoro TTS is not installed. Run `uv sync --extra tts` to enable it."
+                    ) from exc
+                # Pin to CPU: on ZeroGPU the hijacked CUDA is only usable inside
+                # @spaces.GPU, and the speak path runs outside it. Forcing
+                # map_location keeps torch.load from initializing CUDA in the
+                # main process while restoring the checkpoint — that cuInit
+                # poisons every later ZeroGPU worker fork ("No CUDA GPUs are
+                # available").
+                import torch
+
+                device = os.environ.get("SMALL_CUTS_TTS_DEVICE", "cpu")
+                original_load = torch.load
+
+                def _cpu_load(*args, **kwargs):
+                    kwargs["map_location"] = "cpu"
+                    return original_load(*args, **kwargs)
+
+                torch.load = _cpu_load
+                try:
+                    self._pipeline = KPipeline(lang_code="a", device=device)
+                finally:
+                    torch.load = original_load
+        return self._pipeline
+
+    def synthesize(self, text: str) -> tuple[int, np.ndarray]:
+        pipeline = self._load()
+        voice = os.environ.get("SMALL_CUTS_TTS_VOICE", "af_heart")
+        segments = []
+        for _, _, audio in pipeline(text, voice=voice):
+            if hasattr(audio, "detach"):
+                audio = audio.detach().cpu().numpy()
+            segment = np.asarray(audio, dtype=np.float32).reshape(-1)
+            segments.append(segment)
+        if not segments:
+            return 24_000, np.zeros(0, dtype=np.float32)
+        return 24_000, np.clip(np.concatenate(segments), -1.0, 1.0).astype(np.float32, copy=False)
+
+
+_BACKENDS = {
+    "mock": MockTTSBackend,
+    "kokoro": KokoroBackend,
+}
+
+
+@cache
+def _backend_instance(key: str) -> TTSBackend:
+    return _BACKENDS[key]()
+
+
+def get_tts_backend(name: str | None = None) -> TTSBackend:
+    key = (name or os.environ.get("SMALL_CUTS_TTS_BACKEND", "mock")).lower()
+    if key not in _BACKENDS:
+        raise ValueError(f"Unknown TTS backend {key!r}; expected one of {sorted(_BACKENDS)}")
+    # One instance per backend: the Kokoro pipeline loads once per process.
+    return _backend_instance(key)
+
+
+def speak(text: str, backend: TTSBackend | None = None) -> Speech:
+    text = text.strip()
+    if not text:
+        raise ValueError("Cannot synthesize empty text")
+    backend = backend or get_tts_backend()
+    start = time.perf_counter()
+    sample_rate, audio = backend.synthesize(text)
+    audio = np.asarray(audio, dtype=np.float32).reshape(-1)
+    audio = np.clip(audio, -1.0, 1.0).astype(np.float32, copy=False)
+    return Speech(
+        sample_rate=sample_rate,
+        audio=audio,
+        backend=backend.name,
+        model_id=backend.model_id,
+        latency_s=time.perf_counter() - start,
+    )

src/small_cuts/ui.py

@@ -0,0 +1,126 @@
+"""Gradio UI for Small Cuts."""
+
+from __future__ import annotations
+
+import gradio as gr
+import numpy as np
+from PIL import Image
+
+from .frames import pick_key_frame, sample_frames
+from .narrator import get_backend, narrate
+from .styles import DEFAULT_STYLE_KEY, style_choices
+from .theme import build_theme
+from .title_card import derive_title, render_title_card
+from .tts import speak
+
+TITLE = "🎬 Small Cuts"
+TAGLINE = (
+    "Your life, narrated. Drop in a moment — from your phone, webcam, or "
+    "smart-glasses footage — pick a director, and hear what scene you're really in. "
+    "Every model under 32B. Everything runs in this Space."
+)
+
+# Off-Brand cinematic theme for the M2 custom UI quest.
+THEME = build_theme()
+
+
+def _gpu(duration: int = 90):
+    """Mark an event handler for ZeroGPU. No-op off-Space.
+
+    ZeroGPU's startup scan looks for the GPU mark on the functions Gradio
+    binds — decorating an inner helper instead leaves requests unscheduled
+    (worker dies with "No CUDA GPUs are available"). TTS is marked too:
+    any torch forward in the main process poisons later worker forks.
+    """
+
+    def deco(fn):
+        try:
+            import spaces
+        except ImportError:
+            return fn
+        return spaces.GPU(duration=duration)(fn)
+
+    return deco
+
+
+def _narrate_core(
+    image: Image.Image | None, style_key: str, scene_hint: str, empty_text: str
+) -> tuple[Image.Image, str]:
+    if image is None:
+        text = empty_text
+    else:
+        result = narrate(image, style_key=style_key, scene_hint=scene_hint or "")
+        text = result.text
+    return render_title_card(derive_title(text), style_key), text
+
+
+@_gpu()
+def _narrate_handler(
+    image: Image.Image | None, style_key: str, scene_hint: str
+) -> tuple[Image.Image, str]:
+    return _narrate_core(
+        image,
+        style_key,
+        scene_hint,
+        "The narrator clears his throat, looks at the empty screen, and waits. "
+        "Some scenes, after all, require a scene.",
+    )
+
+
+@_gpu()
+def _narrate_video_handler(
+    video_path: str | None, style_key: str, scene_hint: str
+) -> tuple[Image.Image, str]:
+    frame = pick_key_frame(sample_frames(video_path)) if video_path else None
+    return _narrate_core(
+        frame,
+        style_key,
+        scene_hint,
+        "The narrator squints at the projector. Nothing. He has narrated "
+        "blank screens before, but never by choice.",
+    )
+
+
+@_gpu(duration=30)
+def _speak_handler(text: str) -> tuple[int, np.ndarray] | None:
+    if not text.strip():
+        return None
+    speech = speak(text)
+    return speech.sample_rate, speech.audio
+
+
+def build_app() -> gr.Blocks:
+    backend = get_backend()
+    with gr.Blocks(title=TITLE) as demo:
+        gr.Markdown(f"# {TITLE}\n{TAGLINE}")
+        with gr.Row():
+            with gr.Column(scale=1):
+                image = gr.Image(label="Your moment", type="pil", sources=["upload", "webcam"])
+                video = gr.Video(
+                    label="…or a clip (glasses or phone, narrates the middle of the scene)",
+                    sources=["upload"],
+                )
+                style = gr.Dropdown(
+                    choices=style_choices(),
+                    value=DEFAULT_STYLE_KEY,
+                    label="Director's cut",
+                )
+                hint = gr.Textbox(
+                    label="Anything the narrator should know? (optional)",
+                    placeholder="e.g. this is my third coffee today",
+                )
+                go = gr.Button("🎬 Roll narration", variant="primary")
+            with gr.Column(scale=1):
+                card = gr.Image(label="Title card", interactive=False)
+                narration = gr.Textbox(label="The narrator says…", lines=8)
+                speak_btn = gr.Button("🔊 Read it to me", variant="secondary")
+                audio = gr.Audio(label="The narrator speaks…", interactive=False)
+                gr.Markdown(
+                    f"<sub>backend: `{backend.name}` · model: `{backend.model_id}` · "
+                    "no cloud APIs — Off the Grid 🏕️</sub>"
+                )
+        go.click(_narrate_handler, inputs=[image, style, hint], outputs=[card, narration])
+        image.change(_narrate_handler, inputs=[image, style, hint], outputs=[card, narration])
+        video.change(_narrate_video_handler, inputs=[video, style, hint], outputs=[card, narration])
+        speak_btn.click(_speak_handler, inputs=[narration], outputs=[audio])
+    return demo