feat(video): 77-second demo video with README preview

.gitignore

@@ -51,3 +51,15 @@ sim/results*.xml
 
 # FPGA build products (fpga/ice40/build.sh)
 fpga/ice40/build/
+
+# Demo video (video/): render output, caches, local TTS toolchain and model weights
+video/out/
+video/.cache/
+video/.venv-tts/
+video/tts-models/
+video/scripts/_work/
+
+# generated audio (rebuild with video/scripts/make_*.py); the final MP4 is out/
+video/public/audio/*.wav
+video/public/sfx/*.wav
+video/node_modules

README.md

@@ -51,8 +51,35 @@ JavaScript re-implementation of the CPU sits between you and the design.
 
 ---
 
+## 🎬 Watch the demo
+
+<p align="center">
+  <a href="docs/media/tinycpu-demo.mp4">
+    <img src="docs/media/tinycpu-demo-teaser.gif" alt="TinyCPU demo: a RISC-V CPU running a bubble sort in the browser" width="880" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="docs/media/tinycpu-demo.mp4"><strong>▶ Full 77-second demo with narration</strong></a><br/>
+  <sub>1920×1080 · the real web app and the real CPU run, nothing mocked up</sub>
+</p>
+
+| Time | Scene |
+|:---:|:---|
+| 0:00 | A real processor, running in your browser |
+| 0:06 | From SystemVerilog to WebAssembly |
+| 0:16 | Pick a program and run it |
+| 0:22 | Five instructions moving through the pipeline, stage by stage |
+| 0:36 | Forwarding, load-use stalls and branch flushes |
+| 0:48 | Datapath, program comparison and the memory heat map |
+| 0:55 | 40 official tests, 260 random programs, a golden model, an FPGA |
+| 1:06 | Open the CPU and take the first clock cycle |
+
+---
+
 ## 📑 Contents
 
+- [Watch the demo](#-watch-the-demo)
 - [What is TinyCPU?](#-what-is-tinycpu)
 - [Features](#-features)
 - [How it works](#️-how-it-works)
@@ -249,7 +276,8 @@ Run one example through the golden model: `cd sim && python -m golden.cli run ..
 | `wasm/` | Verilator and Emscripten harness: `harness.cpp`, the build script, the Node test |
 | `web/` | Astro and React app: the assembler, the views, the landing page, the docs pages |
 | `fpga/` | iCE40 top level, constraints, the synthesis script, memory image generator |
-| `docs/` | Plan, architecture, the state schema between the WASM module and the browser |
+| `docs/` | Plan, architecture, the state schema between the WASM module and the browser. `docs/media/` holds the demo video and its teaser |
+| `video/` | Remotion project that renders the demo video from the app's own components and real run data ([details](video/README.md)) |
 
 ## 🧰 Tech stack
 

vercel.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://openapi.vercel.sh/vercel.json",
+  "installCommand": "cd web && npx -y pnpm@12.14.0 install --frozen-lockfile",
+  "buildCommand": "cd web && npx -y pnpm@12.14.0 run build",
+  "outputDirectory": "web/dist"
+}

video/README.md

@@ -0,0 +1,40 @@
+# TinyCPU demo video
+
+A ~70 second product demo, built with [Remotion](https://www.remotion.dev). The interface you see in it is
+the real interface: the video imports the web app's own React components (`web/src/components/*`) and feeds
+them numbers produced by the real WebAssembly build of the RTL, so nothing on screen is mocked up.
+
+| Layer | Source |
+|---|---|
+| UI components | `../web/src/components/*` (via the `@web` alias in `remotion.config.ts`) |
+| CPU data | `scripts/gen-data.ts` runs the app's assembler and `web/public/tiny_cpu.mjs` and writes `src/data/run-data.json` |
+| Colors, fonts | the app's tokens (`web/src/styles/global.css`), Inter + JetBrains Mono, logo bar colors as the 5 pipeline stages |
+| Narration | `script/script.json` -> `scripts/make_voice.py` (Kokoro, local, Apache-2.0; male voice blend) |
+| Music + SFX | `scripts/make_music.py` (synthesized with numpy, 120 BPM; every scene cut lands on a beat) |
+| Timeline | `src/timing.json` (scene lengths come from the narration length, rounded up to whole beats) |
+
+## Rebuild
+
+```bash
+cd video
+npm install                                   # node_modules may live in /dev/shm on a slow disk
+npx tsx scripts/gen-data.ts                   # real CPU run data (needs web/public/tiny_cpu.mjs)
+
+python3 -m venv .venv-tts && .venv-tts/bin/pip install kokoro-onnx soundfile numpy scipy
+# model weights (not committed): kokoro-v1.0.onnx + voices-v1.0.bin from
+# https://github.com/thewh1teagle/kokoro-onnx/releases/tag/model-files-v1.0  -> tts-models/
+.venv-tts/bin/python scripts/make_voice.py    # narration + src/timing.json
+.venv-tts/bin/python scripts/make_music.py    # music bed + sound effects
+
+npx remotion studio src/index.ts              # preview
+npm run render                                # out/tinycpu-demo.mp4 (1920x1080, 30 fps, h264)
+```
+
+Change the script, rerun the two audio commands, and the whole video re-times itself: scenes, captions, camera
+moves, cursor clicks and sound effects all derive from `timing.json`.
+
+## Layout measurements
+
+Camera framing uses real DOM positions of the app panels (`src/ui/layout.json`). If the app's layout changes,
+regenerate it: start `node scripts/collect.mjs`, then render stills of the `Debug` composition at frames 0 to 3
+(`npx remotion still src/index.ts Debug out/d.png --frame N`) and merge `out/layout-*.json`.