README: overhaul — v4-600 EMA is the current recommended checkpoint

README.md

@@ -11,117 +11,129 @@ tags:
 pipeline_tag: text-to-video
 ---
 
-# MiniMax-H3 Turbo LoRA — 4-step audio-video generation (preview)
+# MiniMax-H3 Turbo LoRA — few-step audio-video generation
 
 A LoRA for [MiniMax-H3](https://huggingface.co/Comfy-Org/MiniMax-H3) that renders
-joint **video + synchronized stereo audio** in **4 sampling steps** instead of
-the usual ~20 — roughly a 5× speedup in sampling wall-clock.
-
-> ⚠️ **Preview — sharp, but with known artifacts.** The current weights
-> (`ckpt850`) are the **final checkpoint of this training round**. Detail and
-> sharpness at 4 steps are now high — a large step up from earlier checkpoints —
-> but serious issues are surfacing at this point: **plastic-looking skin and
-> over-sharp grain/noise**. Training of this round is **paused while we address
-> them**, so treat these as a sharp-but-imperfect preview, not a finished model.
-> The ComfyUI nodes are also prototype code: **functionality and compatibility
-> are not guaranteed.** **If something breaks, please open an issue** on the
-> [node repo](https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo/issues).
+joint **video + synchronized stereo audio** in as few as **4 sampling steps**
+instead of the usual ~20 — a ~5× sampling speedup — and keeps getting better as
+you add steps.
 
-## Use it in ComfyUI (recommended)
+## Current best — `v4` at step 600 (EMA)
 
-Custom nodes: **[Larryvrh/ComfyUI-MiniMax-H3-Turbo](https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo)**
-— or search **"MiniMax-H3 Turbo"** in ComfyUI-Manager.
+**Download `minimax_h3_turbo_v4_step600_ema.safetensors`.** It's the strongest
+checkpoint we've released:
+
+- **Static and small-motion shots** are much improved — clean, stable, natural.
+- **Micro-detail** (faces, fingers, fine texture) is markedly better.
+- The **over-sharpening / plastic look** of the earlier `v1` (~850) line is
+  **fully resolved**.
+
+Two things still fall short of where we want them, and are what we're working on
+next:
+
+- **audio** quality and consistency;
+- **behaviour under fast, intense motion**.
 
-> 🔄 **Keep the node updated** — it's actively evolving and features land in new
-> versions (e.g. pruned-base support arrived after the first release). Update via
-> ComfyUI-Manager or `git pull`.
+Everything else is in good shape. It's still a preview — training is ongoing — but
+a considerably stronger one than the earlier rounds.
 
-1. Install the nodes (Manager, or `git clone` into `ComfyUI/custom_nodes`).
-2. Download a `.safetensors` from this repo into `ComfyUI/models/loras/`.
-3. Start from the official [MiniMax-H3 workflow](https://docs.comfy.org/tutorials/video/minimax/minimax-h3)
-   (text-to-video or image-to-video) and make two changes:
+## Steps and strength — read this
+
+- **4 steps is the recommended *minimum*; 4–8 is the useful range.** 6–8 steps
+  look noticeably better than 4, so add steps if you can afford them. Past **8
+  steps** it stops helping and can start to introduce **over-sharp artifacts** —
+  there's no benefit to going higher, so stay in **4–8**.
+- **Keep strength at `1.0`.** It's tuned for 1.0 and holds up well across the 4–8
+  step range. Only reach for the strength dial if a *specific* clip misbehaves —
+  then **blurry ghosting / smear → nudge up** (`~1.05–1.2`), **over-sharp grain →
+  nudge down** (`~0.8–0.95`).
+- Keep the scheduler on `simple`.
+
+## Use it in ComfyUI (recommended)
+
+Custom nodes: **[Larryvrh/ComfyUI-MiniMax-H3-Turbo](https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo)**
+— or search **"MiniMax-H3 Turbo"** in ComfyUI-Manager. (Keep the node updated; it
+evolves alongside these weights.)
+
+1. Install the nodes (Manager, or `git clone` into `ComfyUI/custom_nodes`) and put
+   a `.safetensors` from this repo into `ComfyUI/models/loras/`. You also need the
+   base MiniMax-H3 model, VAEs and text encoder — see the
+   [MiniMax-H3 tutorial](https://docs.comfy.org/tutorials/video/minimax/minimax-h3).
+2. Start from the official MiniMax-H3 workflow (t2v or i2v) and make two changes:
    - insert **MiniMax-H3 Turbo LoRA** between the model loader and the sampler;
-   - replace the sampler feeding `SamplerCustomAdvanced` with **MiniMax-H3 Turbo
-     Sampler (4-step)**, and set the scheduler to **4 steps** (`simple`).
+   - feed `SamplerCustomAdvanced` from **MiniMax-H3 Turbo Sampler**, and set the
+     scheduler to `simple` at **≥ 4 steps**.
 
-Everything else stays as in the official workflow, so both t2v and i2v work. A
-ready-made t2v workflow is included here (`minimax_h3_t2v_turbo.json`) and in the
+Everything else stays as in the official graph, so both text-to-video and
+image-to-video work. A ready-made t2v workflow ships in the
 [node repo](https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo/tree/main/example_workflows)
-— drag it into ComfyUI. The custom sampler **auto-adapts to your ComfyUI version**:
-MiniMax-H3 runs video and audio on two different flow schedules; recent ComfyUI
-handles that natively (`ModelSamplingAV`), so on those builds the Turbo Sampler
-steps as a plain single-schedule sampler (and a stock `euler` works too), while on
-older ComfyUI it steps each stream on its own clock so the audio doesn't break at
-4 steps. Keep it in the workflow and it does the right thing either way.
-
-- **Steps**: with `ckpt850`, **4 steps is already sharp** (earlier checkpoints
-  needed 6–8 to firm up). Any count **≥ 4** is valid; more steps still help a
-  little. Keep the scheduler on `simple`.
-- **LoRA strength** (default `1.0`) is the dial for the sharpness/artifact
-  trade-off: if the result shows **blurry ghosting / smear**, nudge strength
-  **up** (e.g. `1.05–1.2`); if it shows **over-sharp grain / artifacts**, nudge
-  it **down** (e.g. `0.8–0.95`).
-- **Base model**: works with any MiniMax-H3 base — full (`bf16`, `int8_convrot`)
-  **and the pruned/curve variants** (`pruned_int8`, `pruned_fp8`); the ComfyUI
-  node auto-detects a pruned base and re-injects the time-conditioning at run
-  time, so one LoRA covers every base.
-- **`low_vram`** (node switch): off by default (applies the LoRA at run time —
-  sharpest, some extra peak VRAM). Turn it **on** if you run out of memory: it
-  merges the LoRA into the weights for the lowest peak VRAM, at the cost of a
-  **softer result on quantized (`int8` / `fp8` / pruned) bases**. Lowering the
-  resolution or frame count also helps.
+(and here as `minimax_h3_t2v_turbo.json`) — drag it in.
+
+- **Base model**: any MiniMax-H3 base — full (`bf16`, `int8_convrot`) **and the
+  pruned/curve variants** (`pruned_int8`, `pruned_fp8`). The node auto-detects a
+  pruned base and re-injects the time-conditioning at run time, so **one LoRA file
+  covers every base**.
+- **`low_vram`** switch: **off** applies the LoRA at run time (sharpest,
+  recommended); **on** merges it into the weights for the lowest peak VRAM (a bit
+  softer on quantized bases). Turn it on only if you run out of memory.
+- The custom sampler **auto-adapts to your ComfyUI version**: MiniMax-H3 runs
+  video and audio on two different flow schedules; recent ComfyUI handles that
+  natively (`ModelSamplingAV`) and older ComfyUI doesn't — the Turbo Sampler
+  detects which and does the right thing either way, so nothing to change when you
+  update ComfyUI.
 
 ## Weights
 
-All bf16, ~744 MB, applied as a standard low-rank update
-(`W_eff = W + lora_B @ lora_A`, alpha = rank so no extra scaling):
+All bf16, ~744 MB, applied as a plain low-rank update
+(`W_eff = W + lora_B @ lora_A`, alpha = rank, so no extra scaling). **Prefer the
+EMA files**; the non-EMA ones are for comparison.
 
-| file | ~step | notes |
-|---|---|---|
-| `minimax_h3_turbo_4step_ema_ckpt850.safetensors` | ~850 | **recommended — current final checkpoint** (time-averaged EMA, sharp at 4 steps) |
-| `minimax_h3_turbo_4step_ckpt850.safetensors` | ~850 | ckpt850 non-EMA — even sharper but over-sharpened; for comparison/analysis |
-| `minimax_h3_turbo_4step_ckpt500.safetensors` | ~500 | older, non-EMA (softer) |
-| `minimax_h3_turbo_4step_ema_ckpt500.safetensors` | ~500 | older EMA |
-| `minimax_h3_turbo_4step.safetensors` | ~200 | initial release, non-EMA |
-| `minimax_h3_turbo_4step_ema.safetensors` | ~200 | initial release, EMA (superseded) |
+| file | notes |
+|---|---|
+| **`minimax_h3_turbo_v4_step600_ema.safetensors`** | **recommended — current best.** Strong static/small-motion, good micro-detail, no over-sharpening. |
+| `minimax_h3_turbo_v4_step600.safetensors` | v4-600 non-EMA (comparison). |
+| `minimax_h3_turbo_v4_step150_ema.safetensors` | earlier v4 checkpoint. |
+| `minimax_h3_turbo_4step_ema_ckpt850.safetensors` | `v1` line (~850) — sharp but over-sharpened / plastic; **superseded by v4**. |
+| `minimax_h3_turbo_4step_ema_ckpt500.safetensors` | older `v1` (~500), softer. |
+| `minimax_h3_turbo_4step_ema.safetensors` | initial release (~200). |
 
-`ckpt850` is the final checkpoint of this training round (paused — see the note
-at the top). Prefer the EMA file for the cleanest result.
+*Naming:* `v4` is the current training recipe and `stepN` is the training step.
+Older files carry the previous `4step_ckptN` naming, where `4step` referred to the
+sampler-step count.
 
 ## Standalone (no ComfyUI graph)
 
-`generate.py` is a single self-contained file — loads the base DiT + a LoRA,
-encodes the prompt, runs the 4-step dual-schedule sampler, decodes and muxes an
+`generate.py` is a single self-contained file — it loads the base DiT + a LoRA,
+encodes the prompt, runs the few-step dual-schedule sampler, decodes and muxes an
 mp4. It still needs a ComfyUI checkout for the H3 model / VAE / text-encoder
 definitions:
 
 ```bash
-# ComfyUI (pinned to the commit these weights were validated against)
 git clone https://github.com/comfyanonymous/ComfyUI
-cd ComfyUI && git checkout 14b05228cef127ce529bc0c08660770d4af3e9a8
-pip install -r requirements.txt && cd ..
-pip install -r requirements.txt   # this repo: torch, safetensors, imageio-ffmpeg
+cd ComfyUI && pip install -r requirements.txt && cd ..
+pip install -r requirements.txt          # this repo: torch, safetensors, imageio-ffmpeg
 
 # base weights from Comfy-Org/MiniMax-H3 into a models/ tree, then:
 python generate.py \
   --comfyui ./ComfyUI \
   --base   models/diffusion_models/minimax_h3_fl2va_bf16.safetensors \
-  --lora   minimax_h3_turbo_4step_ema_ckpt850.safetensors \
+  --lora   minimax_h3_turbo_v4_step600_ema.safetensors \
   --te     models/text_encoders/qwen3vl_32b_minimax_h3_int8_convrot.safetensors \
   --video-vae models/vae/minimax_h3_video_vae_fp16.safetensors \
   --audio-vae models/vae/minimax_h3_audio_vae_fp32.safetensors \
   --prompt "A corgi in a chef hat flipping a pancake, sizzling sounds and a cheerful bark." \
-  --width 1344 --height 768 --frames 124 --out corgi.mp4
+  --width 1344 --height 768 --frames 124 --steps 6 --out corgi.mp4
 ```
 
 ## Notes
 
-- **Resolution / duration**: width/height are multiples of 32; the short edge is
-  typically 768. Frame count is at 24 fps and snaps to the model's 17·k+5 grid
+- **Resolution / duration**: width and height are multiples of 32 (short edge
+  typically 768). Frame count is at 24 fps and snaps to the model's 17·k+5 grid
   (124 ≈ 5 s). Validated range ~124–362 frames (~5–15 s).
 - **VRAM**: the base model is large (~33 B); an 80 GB GPU is comfortable at the
-  largest resolutions. The ComfyUI node streams the base and adds a `low_vram`
-  switch (see above), so it runs on much smaller GPUs. In the standalone script,
+  largest resolutions. The ComfyUI node streams the base and adds the `low_vram`
+  switch, so it runs on much smaller GPUs. In the standalone script,
   `--offload-adaln` trades ~13 GB of VRAM for CPU RAM.
 - **Audio**: 32 kHz stereo, aligned to the video; the two streams ride different
-  flow schedules and are integrated each on its own clock.
+  flow schedules and are integrated each on its own clock. (Audio is one of the
+  two areas still being improved — see the top.)