Upload README.md with huggingface_hub

README.md

@@ -58,56 +58,143 @@ and reference images, videos and audio (`ref2va`); those paths are not ported
 and the vision tower is not packed. What is here is `t2va`: prompt in, video
 and audio out.
 
-## Getting a file
+## Running it
+
+### 1. Get the runtime
+
+`cortiq` is one Rust binary. Either install it —
+
+```bash
+cargo install cortiq-cli          # needs Rust 1.85+; brings the GPU backend
+```
+
+— or take a prebuilt archive from the
+[latest release](https://github.com/infosave2007/cmf/releases/latest)
+(Linux x86-64, macOS on Apple Silicon and Intel, Windows x86-64 and ARM64;
+each ships a `.sha256`). Nothing else is required: no Python, no PyTorch, no
+CUDA toolkit, no ffmpeg.
+
+Check it took:
 
 ```bash
-huggingface-cli download infosave/MiniMax-H3-Turbo-cmf \
-  --include 'parts-q4tp/part_*' --local-dir .
-cat parts-q4tp/part_* > mmh3-turbo-q4tp.cmf
+cortiq --version
+```
 
+### 2. Get the weights
+
+One file, 23.5 GB.
+
+```bash
+pip install -U "huggingface_hub[cli]"      # only to fetch the file
+hf download infosave/MiniMax-H3-Turbo-cmf mmh3-turbo-q4tp.cmf --local-dir .
+```
+
+Confirm it arrived whole — the container carries a hash per tensor:
+
+```bash
+cortiq verify mmh3-turbo-q4tp.cmf     # → ✓ all tensor hashes match
+cortiq info   mmh3-turbo-q4tp.cmf     # → arch, layers, 47.83B params
+```
+
+### 3. Render
+
+```bash
 cortiq animate mmh3-turbo-q4tp.cmf \
   --prompt "A corgi in a chef hat flipping a pancake, sizzling sounds and a cheerful bark." \
-  --width 512 --height 288 --frames 39 --out corgi.avi
+  --width 512 --height 288 --frames 39 --steps 4 --seed 42 \
+  --out corgi.avi
+```
+
+That writes `corgi.avi` — MJPEG video with PCM stereo, playable in VLC, mpv,
+QuickTime and Windows Media Player — and `corgi.wav` beside it. The JPEG
+encoder and the RIFF muxer are inside the binary: a pipeline that ends in a
+shell-out to a 20 MB dependency is not a pipeline you can ship. If you want an
+mp4 for a browser, remux it yourself; the model never needs one.
+
+**On a GPU.** The device path is opt-in for this model while its kernels earn
+their keep (see below):
+
+```bash
+CMF_MMH3_GPU=1 cortiq animate mmh3-turbo-q4tp.cmf --prompt "…" --out corgi.avi
 ```
 
-`cortiq animate` writes an MJPEG+PCM AVI and the stereo track beside it as
-`.wav`. There is no ffmpeg in the loop and nothing to install: the JPEG encoder
-and the RIFF muxer are part of the binary, because a pipeline that ends in a
-shell-out to a 20 MB dependency is not a pipeline you can ship.
+### Options that matter
+
+| flag | default | what it does |
+|---|---|---|
+| `--width` / `--height` | 512 × 288 | multiples of 32. The trained short edge is 768; below ~256 the model drifts off-distribution |
+| `--frames` | 39 | at 24 fps, snapped **up** to the model's 17k+5 grid: 5, 22, 39, 56, … 124. 124 ≈ 5 s, and 124–362 is the validated range |
+| `--steps` | 4 | what the Turbo LoRA is trained for. More still helps a little |
+| `--seed` | 42 | same seed, same prompt, same size → the same clip, byte for byte |
+| `--quality` | 92 | JPEG quality of the AVI's frames |
+| `--stock-sampler` | off | integrate the audio on the video's clock, as a single-schedule sampler does. Wrong at 4 steps — it is here to hear how wrong |
 
-Width and height are multiples of 32. Frame counts snap **up** to the model's
-17k+5 grid (5, 22, 39, 56, … 124), which is the grid the temporal VAE and the
-DiT's frame-span pattern agree on. 4 steps is what the LoRA is trained for;
-more still helps a little.
+| environment | what it does |
+|---|---|
+| `CMF_MMH3_GPU=1` | opt into the device path |
+| `CMF_THREADS=n` | cap the worker pool (defaults to the machine's cores) |
+| `CMF_ANIM_PROF=1` | per-step rms of both latent streams and both velocities |
+
+### What it needs
+
+RAM at least the file's size — 24 GB — or every step faults on non-resident
+pages; the weights are memory-mapped, not read. Disk: 24 GB. A GPU is optional
+and wants ~14 GB of VRAM for the DiT's planes. No network access at run time.
 
 ## What it costs to run
 
 The file is memory-mapped, so plan on RAM at least its size or every step
 touches non-resident pages.
 
-Measured on 48 CPU cores, 4 steps:
+512×288, 39 frames, 4 steps, one machine — 48 CPU cores and one RTX PRO 6000
+Blackwell:
 
-| | tokens in the pack | denoise (4 steps) | decode | total |
-|---|---|---|---|---|
-| 256×160, 22 frames (0.9 s) | 375 | 45.0 s | 10.7 s | **55.7 s** |
-| 512×288, 39 frames (1.6 s) | 1 879 | 220.8 s | 150.0 s | **371.3 s** |
+| | denoise | decode | total |
+|---|---|---|---|
+| host | 198.2 s | 147.8 s | **346.5 s** |
+| `CMF_MMH3_GPU=1` | 96.8 s | 74.7 s | **172.0 s** |
 
-Nearly all of the decode is the video VAE — the vocoder is 4 s of the 150.
+and the smaller size, on the device: 256×160 over 22 frames in **29.2 s**.
 
-The packed sequence is `[text | audio | video]` and everything attends to
-everything, so cost grows with the token count and then with its square. A
+Nearly all of the decode is the video VAE — the vocoder is 4 s of it. The
+packed sequence is `[text | audio | video]` and everything attends to
+everything, so cost grows with the token count and then with its square: a
 512×288 second is five times the tokens of a 256×160 one.
 
-**The GPU path is off, on purpose.** `cortiq`'s wide-GEMM arm on wgpu is
-measured three times faster than the host here and it is also wrong: on an
-RTX PRO 6000 Blackwell the DiT's first step disagrees with the CPU (video
-velocity rms 1.32 against 1.73, audio 0.16 against 1.01) and the second step
-returns NaN — a flat grey frame and a clipped waveform. The op probe cannot
-notice: it only times the two arms, and it runs the bad one for real while it
-is deciding. So `cortiq animate` pins `CMF_GPU=0` before the backend comes up,
-which is early enough to be sure. `CMF_MMH3_GPU=1` opts back in if you want to
-watch it fail. Fixing that kernel is the next thing worth doing to this model —
-it is the whole difference between minutes and hours.
+**A free 2× on the decoder, if you want it.** The video VAE decodes in
+256-pixel tiles, always, and grows the OVERLAP rather than the tile count —
+so a 288-pixel edge is covered by two 256-pixel tiles overlapping by 224, and
+you pay for 512 rows to get 288. An edge of exactly 256 is one tile. 512×256
+therefore decodes three tiles where 512×288 decodes six, for 89% of the
+pixels. The schedule is the reference's and this port reproduces it exactly;
+picking an edge that lands on it is free.
+
+**Host and device do not agree to the last bit, and neither is wrong.** The
+host arm quantizes activations to int8 (`CMF_SDOT`) where the device
+dequantizes to f32, so the two renders differ by a few per cent in latent rms
+and visibly in fine texture. Set `CMF_SDOT=0` on both sides to compare
+arithmetic instead of that approximation.
+
+**Why the device is opt-in.** Getting it right took three fixes, and one
+thing is still held back.
+
+The engine's blocked f32 GEMM cached its weight-side device buffer **by
+pointer address**. Every batched attention allocates one k/v scratch pair per
+call and refills it per head — same address, different matrix — so head 0's
+keys came back for every head, on the GPU only, silently. It is keyed on a
+content fingerprint now. The same GEMM also took every job over 4 M MACs on
+sight with no CPU arm to lose to, which on this model's decoder was three
+times *slower* than the host it displaced; it goes through the same
+measure-don't-assume probe as every other op class now, and on this stack the
+probe hands that work back (0.24 ms device against 0.13 host) while sending
+the weight GEMMs to the card (25.8 ms against 92.0).
+
+Still held: **the cooperative-matrix kernel runs this model out of f16 range.**
+At 256×160 the render is correct; at 512×288 the audio stream goes NaN on the
+second sampling step and the video follows. Bisected — `CMF_BAKE_GPU=0` does
+not help, `CMF_COOP=0` does — so `cortiq animate` pins `CMF_COOP=0`. Tensor
+cores are worth having here; the kernel needs to carry a scale before it can
+carry these activations. That is the next real speedup in this model.
 
 ## What the conversion did