feat(examples): vllm-video-studio — a standalone browser console for MiniMax-H3

[localai-bot]

Supersedes #286, which put this in examples/server.

Driving three modalities from curl means hand-writing JSON and — for fl2va and ref2va — producing a binary PPM at exactly the output resolution first. This is a console that does both, with a job queue and playback.

Why it is its own binary

My first attempt put the UI in examples/server and grew the shared library to serve it (a static mount, plus engine-lifecycle routes on ApiServer). That was wrong twice over: examples/server is the OpenAI-compatible API surface and a browser console doesn't belong in it, and adding library surface for one consumer's benefit is exactly what ARCH-ONE-SURFACE exists to stop.

The API server and api_server.{h,cpp} are untouched by this change.

It's a thin client of the public C ABI — vllm.h and nothing from the internal tree. Loading, generating, swapping weights, building the ffmpeg argv: all ABI calls. Everything the console can do, an FFI consumer can do.

Three things the engine's shape dictated

• The browser converts images. Reference frames must be P6 at the output geometry and no codec or resampler is vendored, so the page resamples in a canvas (cover-fit, centre-crop, so an odd aspect never letterboxes black into the conditioning) and posts a data: URL.
• The ledger is the interface, not the form. A render is 13 min to 2.5 h — what matters is live elapsed time, a step-rate ETA, and jobs in localStorage because a render outlives the tab.
• Renders are serialised. These checkpoints are tens of GB resident and this class of box OOMs — and an OOM takes the machine down, not just the request.

Checkpoint swapping, with no library change

vllm_video_engine_free + vllm_video_engine_load were already on the ABI. Unload happens first, so the old weights are never held while the new ones are built; a failed load leaves nothing loaded and says so, rather than quietly serving the partition you just asked to leave.

Verified live

GET /            200  16567b   ("H3 console" ×2)
GET /api/engine  {"loaded":false,...}    ← correct with no --dit
GET /api/jobs    []
startup          studio: no --dit; load one from the console

No shell for paths (std::filesystem) and none for the mux (fork/execvp on the library-built argv).

Usage

vllm-video-studio --dit MiniMax-H3-FL2VA-Q4_K_M.gguf --partition fl2va \
  --encoder qwen3vl-32B-MiniMax-H3-Q4_K_M.gguf --tokenizer tokenizer.json \
  --video-vae video_vae.safetensors --video-vae-config video_vae_config.json \
  --audio-vae audio_vae.safetensors --audio-vae-config audio_vae_config.json \
  --ui examples/video_studio/webui --port 8080

--dit is optional: start bare and load a checkpoint from the console.

[localai-bot]

Landed on main as c5452190 via row/H3-VIDEO-STUDIO-2, rebuilt on current main. The example and its docs/USAGE.md entry are in.

Three things needed fixing, and only the first was cosmetic:

1. Trailers. Both commits had FOLLOWING_AGENTS_PROTOCOL glued to Assisted-by with no blank line, both Following-Agents-Protocol and AI-Assisted missing, and an Assisted-by identity with a space before the colon that the format cannot parse. Repaired; content byte-identical.

2. A real documentation gap. check-doc-checkpoint refused it for adding a user-facing executable without documenting it — correctly. A browser console anyone can run is exactly what USAGE.md exists to describe. Since that gate is per-commit, a later fix commit could not satisfy it, so the branch is squashed to one commit carrying the example and its docs together. The entry records why it is a separate binary rather than a route on the API server, and points at the existing MiniMax-H3 section for the weights rather than restating the five-file table.

3. A test weakening, dropped. The tip reverted main's .scale(0.0) strengthening in tests/vllm/test_hf_config.cpp and test_gguf_qwen36_loader.cpp — stale base, since main tightened those after this branch last merged. Landing it as it stood would have silently weakened a deliberately strict test: the comment it deleted records that a bare doctest::Approx(1e-6) carries an absolute tolerance of ~1.19e-5 and so accepts any eps below it, including the 1e-05 the same file uses elsewhere, verified by mutation. Main's version is kept.

Gate: scripts/agent-preflight.sh rc=0 on the row branch. CI is queue-blocked (#274), so the operator gate run is the authority per AGENTS.md.