Skip to content
Back to search

h3lite

SkillWorks with Claude CodeGitHub

Use when configuring, repairing, planning, or running MiniMax H3 locally on a Windows NVIDIA computer, especially when installation compatibility, component sets, resolution, generation-time budget, path, low-VRAM risk, or H3 prompt mode must be chosen from hardware and user requirements.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rimagination--h3lite/badge.svg)](/listings/rimagination--h3lite)

HTML

<a href="/listings/rimagination--h3lite"><img src="/api/listings/rimagination--h3lite/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 784 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: h3lite
  3. description: Use when configuring, repairing, planning, or running MiniMax H3 locally on a Windows NVIDIA computer, especially when installation compatibility, component sets, resolution, generation-time budget, path, low-VRAM risk, or H3 prompt mode must be chosen from hardware and user requirements.
  4. ---
  5. # MiniMax H3 Local Video
  6. Use this skill to turn a user's local computer into a reproducible MiniMax H3 audio-video workstation and to generate short clips. The validated primary route is Windows + NVIDIA + ComfyUI; macOS Apple Silicon is a community/experimental alternative, not an equivalent tested backend. Treat platform selection, path selection, hardware-aware planning, prompt writing, execution, timing, and verification as one workflow. The default is the validated fast route; other modes must be chosen explicitly or justified by a time budget.
  7. ## Platform scope and routing
  8. Detect the operating system and accelerator before giving installation commands or model links. Do not give CUDA, Windows virtual-environment, `.bat`, or Windows path instructions to a macOS user.
  9. | Platform | h3lite status | Guidance |
  10. | --- | --- | --- |
  11. | Windows + NVIDIA CUDA | Primary, locally validated | Use the ComfyUI/H3 Lite fast path and the Windows doctor/planner/preflight scripts. |
  12. | macOS Apple Silicon | Community alternative, not h3lite-equivalent | Explain that the documented ComfyUI route is not validated on Metal. Offer the MLX/`mmh3turbo` route as an optional external alternative, with its own weights, commands, and timing. |
  13. | macOS Intel | Not recommended | Do not promise local H3 generation; suggest a hosted/API or another backend. |
  14. | Linux + NVIDIA | Unverified | The model concepts may transfer, but Windows paths, packaged nodes, and timings do not. Require an explicit experimental choice. |
  15. For a non-Windows user, preserve the useful cross-platform guidance (prompt structure, 32-pixel canvas alignment, low-resolution preview, disk/log/output checks), but label every resource and timing as platform-specific. A community implementation that can run H3 on a Mac is evidence for feasibility, not evidence that this ComfyUI skill supports Metal.
  16. The Mac alternative described in the project notes uses MLX/Metal and a third-party `mmh3turbo` package. If a Mac user explicitly chooses that route, point them to the author's [community bundle](https://huggingface.co/yunfengwang/mmh3turbo-bundles) and package (`uvx mmh3turbo`), and state that these are external resources with independent licensing, updates, and validation. It may reduce the download footprint with GGUF/4-bit bundles, but it is outside this skill's tested component sets. Do not silently install it, mix its weights with ComfyUI models, or present its 30–43 minute 5-second 720p timings as Windows benchmarks.
  17. ## Agent production workflow
  18. For complex creative requests, use the compact workflow contract in
  19. [`references/agent-workflow.md`](references/agent-workflow.md):
  20. ```text
  21. intent route → reference/identity anchors → prompt enhancement → execute → verify
  22. ```
  23. Route from the user's input and acceptance criteria, not from a style adjective.
  24. Use `I2VA` for a specified opening frame, `FL2VA`/`L2VA` for endpoint anchors,
  25. and `Ref2VA` only after its model, text encoder, and workflow are confirmed.
  26. For recurring characters or multi-shot work, define stable subject/reference
  27. labels, what must be retained, what may change, and what drift is forbidden
  28. before writing the timeline. This workflow pattern is local and does not add a
  29. cloud service, MCP dependency, second model, or second inference pass.
  30. When a creative brief is vague (for example, it only says “more cinematic”
  31. or “make it a nice 3D animation”), optionally read
  32. [`references/prompt-assist.md`](references/prompt-assist.md). It adapts the
  33. public Higgsfield prompt structure—stable style/identity lock, one clear scene
  34. action, physical camera motion, audio, and compact anti-drift constraints—to
  35. H3's native fields. Use it as a writing aid only: do not call Higgsfield, copy
  36. model-specific flags or capabilities, or let a web lookup change the local
  37. route, resolution, component set, or verification rules. If a live lookup is
  38. needed, follow the host `web-access` skill and use public pages only.
  39. ## Operating rules
  40. - **Hot path first:** for an ordinary text-to-video request on an already validated installation, run `scripts/h3_fastpath.py` once. It combines `/system_stats`, fresh-cache reuse, in-process planning/preflight, queue submission, and one bounded completion watch. Do not issue repeated one-shot status calls, reread the full reference set, run `--help`, or ask nonessential questions during this path. If the command yields a running terminal cell, wait on that cell; do not start another monitor.
  41. - **Keep cold work out of the hot path:** model download manifests, hash or size verification, Torch/custom-node repair, repository checks, browser workflow discovery, and full recursive doctor scans belong to installation, migration, repair, or first-run validation. A normal generation on an unchanged machine must not pay those costs.
  42. - **Cold path can be heavier when it prevents hour-scale waste:** during installation or repair, verify download source, target folder, expected size/hash when available, runtime imports, and model-role mapping before queueing. Store the result so later prompts reuse it instead of repeating it.
  43. - Inspect before changing anything. Run `scripts/h3_doctor.py --json` and locate the target ComfyUI directory before installing packages, nodes, or weights.
  44. - On first contact, run a platform/accelerator check before the Windows doctor. If the machine is not Windows + NVIDIA, stop the CUDA installation branch and route the user using the platform matrix above.
  45. - Prefer an isolated ComfyUI directory when no installation is supplied. Never overwrite an existing installation or silently replace model files.
  46. - Keep the deployment path configurable. Do not copy paths from another computer into scripts or workflows.
  47. - Report required disk space before large downloads. Use resumable downloads and verify file size or hash when a source provides one.
  48. - Before a long generation or multi-shot batch, check free space and pagefile headroom and keep per-shot logs. A pipeline that filters away the process exit code or traceback is not a successful run; preserve the full log and stop on the first failed shot.
  49. - If the user can only download from the public internet, run a cold-path download plan before fetching multi-GB files: test candidate raw URLs with a small ranged download, choose the fastest stable source, estimate wall-clock time, then use resumable `.part` downloads. Do not pretend scripts can beat the user's real bandwidth.
  50. - Before downloading large assets, run the doctor compatibility probe. Stop on a Torch import error; treat a comfy-kitchen/Torch mismatch as a repair decision, not a post-download surprise. Do not silently substitute model files or start unlimited parallel downloads.
  51. - Treat the diffusion checkpoint, text encoder, Turbo LoRA, workflow, and node revisions as one component set. Read `references/component-sets.md` during installation, migration, model replacement, or kernel repair. Never construct an unvalidated set from individually plausible filenames.
  52. - Use `--component-set auto` for one unambiguous installed set, or explicitly select `A`/`validated-low-vram-a` or `B`/`portable-16gb-b` when both sets are installed. Record the selected set in the run manifest; never resolve a partial set role by role.
  53. - Prefer the maintained Baidu package for the registered A/B component sets. Keep the selected set atomic, and respect the licenses of model weights and third-party nodes when using either the package or upstream sources.
  54. - Prefer the ComfyUI HTTP API with an API-format workflow JSON. Use browser/CDP capture only as a recovery path when no reusable workflow JSON exists.
  55. - Check `http://127.0.0.1:8188/system_stats` before starting anything. If ComfyUI is already healthy, reuse it and do not restart it or rediscover its workflow history.
  56. - Preserve MiniMax H3's audio path and flow/sigma-shift handling when the user wants native audio. Do not remove audio VAE, audio conditioning, or the H3 sampling node merely to make a graph look simpler.
  57. - **Zero-inference optimization constraint:** hardware compatibility checks, timing calibration, face routing, and media QA may run before or after generation, but must not add sampling steps, extra generation models, or a second video inference pass. Keep the selected graph unchanged unless the user explicitly requests a different quality profile.
  58. - **Face-quality routing:** if the user needs a recognizable or speaking human face, do not treat low-VRAM W4A8 T2VA at 640x352 as a final-quality route. Prefer I2VA with a clear first-frame reference; prefer Ref2VA when identity must persist across shots. Read `references/face-quality.md`, confirm `MiniMaxH3ReferenceToVideo` through `/object_info`, and confirm the matching reference-capable text encoder/projection and workflow before selecting that route. A registered node alone is not enough; the bundled Ref2VA templates are an experimental local path until a complete run passes media and manual identity QA.
  59. - **Anchor before prompt:** for multi-shot or identity-sensitive requests, first create an internal anchor sheet with stable subject/picture labels, retention rules, allowed changes, and forbidden drift. Use the same labels in the prompt, output prefix, and run manifest; read `references/agent-workflow.md` for the compact contract.
  60. - **Assist vague creative briefs without inventing facts:** when the request lacks a concrete camera, action, sound, or finish, read `references/prompt-assist.md` and use its bounded defaults or ask one targeted question if the omission changes the route or acceptance criteria. A public Higgsfield lookup is optional and pattern-only; fall back to the local references when browsing is unavailable.
  61. - On current ComfyUI builds, the API class `MiniMaxH3SigmaShift` is the native `ModelSamplingMiniMaxH3` node and uses the merged `ModelSamplingAV` video/audio schedule fix. Detect it by `/object_info` or the local source before adding a custom dual-clock sampler; do not duplicate the fix merely because the API class keeps its compatibility name.
  62. - Run the read-only planner before a non-trivial generation. It must report selected mode, resolution, steps, cache policy, paths, and an estimated time range. Do not present an estimate as a guarantee.
  63. - Run the read-only preflight after the doctor and planner. Treat low available RAM/VRAM as a caution, but stop when the pagefile is critically low, required assets are missing, or the doctor recommends an alternative backend.
  64. - Do not perform a full recursive doctor scan for every prompt. Cache the environment report under `<ComfyUI>/user/h3lite_runs/_environment/`; reuse it for a normal session (normally no older than 30 minutes), invalidate it after ComfyUI/model/node/driver changes or a failed run, and use `h3_preflight.py --refresh-runtime` for volatile resource fields.
  65. - Do not revalidate large model files before every prompt. Trust the cached download/component manifest unless the file is missing, has a different size/mtime than recorded, the user changed components, or the previous run failed with a model/node/loader error.
  66. - For registered Set B files, require the recorded SHA-256 on first use or after a size/mtime change. A same-size corrupted W4A8 checkpoint produced colored mosaic frames, so byte count alone is not proof of integrity; reuse the cached integrity result on unchanged files.
  67. - Treat every submission as an auditable run: save the effective prompt, mutated API workflow, configuration fingerprint, queue ID, actual execution time, and verified output in the run manifest.
  68. - For identity-sensitive or multi-shot runs, the runtime also writes `anchors.json` beside `manifest.json` and records advisory `anchor_qa` comparisons; these signals support manual continuity review but are not face recognition.
  69. - Keep agent-facing status compact: omit ComfyUI's full history graph by default; use verbose history only when diagnosing a failure.
  70. - Never submit an identical configuration while its manifest is `submitting`, `queued`, or `running`. Return the existing prompt ID instead; use `--allow-duplicate` only when the user explicitly asks for a second identical run.
  71. - Treat low-VRAM timing as an empirical estimate. The first run can be much slower because kernels compile and weights move between system RAM and VRAM.
  72. - For expensive renders, use a cheap preview pass first: validate the complete prompt/shot list at the smallest supported canvas (for example 256p or the local fast bucket), then promote only approved shots to the requested resolution. This is especially important for multi-shot work; it is a planning optimization, not a second quality-generation pass for a single requested clip.
  73. - Prefer `NORMAL_VRAM` when a validated 16 GB system can keep Set B resident. In a same-model/workflow/prompt/seed 640x352 comparison, an RTX 4060 Ti 16 GB run took 77.08 seconds versus 591.22 seconds on an RTX 4070 Laptop 8 GB using `LOW_VRAM`; treat dynamic loading/offload as the main operational explanation, not as a pure GPU benchmark or a promise.
  74. - When launching ComfyUI as a background process, redirect stdout and stderr to persistent files. A detached pipe can become invalid after the launching session is cleaned up, leaving ComfyUI alive but causing tqdm/logger writes to fail with `OSError: [Errno 22] Invalid argument`. On that signature, restart ComfyUI with persistent logs; do not redownload models or rerun a full doctor unless the restart exposes another error.
  75. - Keep media verification attached to the selected ComfyUI root. The verifier searches system `PATH`, `H3LITE_FFPROBE`, and common locations in or beside `<ComfyUI>` for `ffprobe`; both `h3_generate --watch` and standalone `h3_status` must receive or infer that root. Standalone status may infer the parent only when `--output-dir` points exactly `<ComfyUI>\output`; otherwise pass `--comfyui` explicitly. Treat `ffprobe_not_found` as a missing verifier, not evidence that generation failed, and do not requeue the video until the existing output has been inspected.
  76. - Treat run-history cleanup as explicit maintenance, never hot-path work. Use `scripts/h3_cleanup.py` in dry-run mode first and require `--apply` before deleting eligible run snapshots. Preserve `_environment`, `_hotpath`, `_workflows`, `_experiments`, prompt folders, timing data, and generated output files.
  77. ## Preferred component download source
  78. For installation or repair, use the maintained Baidu package before assembling
  79. the set from multiple upstream repositories. Select one complete package after
  80. the hardware check; do not ask the user to download both sets or mix their
  81. exclusive files.
  82. | Default hardware match | Package | Share link | Code |
  83. | --- | --- | --- | --- |
  84. | About 8 GB VRAM, low-VRAM fast route | Set A | [Baidu Netdisk](https://pan.baidu.com/s/1IBlH0VY7tWGvxqMtniraow) | `4hri` |
  85. | 16 GB-class VRAM, FP8 compatibility route | Set B | [Baidu Netdisk](https://pan.baidu.com/s/1x5GGuJv0h8chApgVoDgIaQ) | `1hjx` |
  86. Guide the user to open the matching link, enter the code, and download the
  87. whole package. If the `baidu-drive` skill or a Baidu Drive connector is
  88. available, use it for the download; otherwise give the link and code directly
  89. and continue after the user places the files locally. Merge the package's
  90. `models` and
  91. `custom_nodes` folders into the selected `<ComfyUI>` root, then import or copy
  92. the packaged workflows and keep `component-manifest.json` with the install.
  93. Run the doctor after the merge.
  94. Set A contains the INT4 text encoder and optional low-VRAM acceleration nodes.
  95. Set B contains the FP8 text encoder and validated compatibility workflows. Both
  96. packages include their own shared ClipProj and VAE files, so a user only needs
  97. one link. If the Baidu package is unavailable or the user explicitly requests
  98. upstream downloads, use the exact sources, filenames, sizes, and hashes in
  99. `references/component-sets.md`.
  100. ## Installation target contract
  101. Before installing, downloading, or moving any component, establish one explicit
  102. deployment target and state it to the user:
  103. ```text
  104. Install mode: reuse-existing | current-project | dedicated-folder
  105. ComfyUI: <absolute path>
  106. Models: <ComfyUI>\models
  107. Custom nodes: <ComfyUI>\custom_nodes
  108. Output: <ComfyUI>\output
  109. ```
  110. Use these rules:
  111. - `reuse-existing`: use the exact existing ComfyUI path supplied by the user or discovered and confirmed by the user. Do not clone, reinstall, or create a second model directory.
  112. - `current-project`: keep everything under the active workspace in `<workspace>\.h3lite\ComfyUI` so the project-scoped choice is unambiguous and does not scatter models across the repository.
  113. - `dedicated-folder`: use the user's absolute path, preferably a non-repository path such as `D:\AI\MiniMax-H3\ComfyUI` or `F:\MiniMax-H3\ComfyUI`. Put the venv, custom nodes, models, user data, and output under this ComfyUI root.
  114. - If no existing installation and no target path are available, recommend `dedicated-folder` and ask the user to confirm the absolute path before downloading large files. Never silently choose a drive or install into the current project root.
  115. - If the user says “当前项目” without naming the workspace, resolve and display the active workspace path before proceeding. If the user gives a path ending in `ComfyUI`, use it directly; if they give a parent install folder, append `ComfyUI` and display the resulting path for confirmation.
  116. After the target is selected, read `references/deployment-matrix.md` and present
  117. the component checklist, exact destination folders, estimated disk budget, and
  118. the launch command. Install or repair in this order: runtime prerequisites,
  119. ComfyUI, required custom nodes, model files, doctor verification, then launch.
  120. Do not start a generation while any required node class or model asset is
  121. missing.
  122. ## Adaptive planning contract
  123. Before generation, separate the user's requirements into four independent
  124. choices:
  125. - **Intent:** `fast` (default), `balanced`, or `quality`.
  126. - **Wall-clock budget:** maximum expected generation time, such as “within 10
  127. minutes”; this is different from the requested clip duration.
  128. - **Canvas:** `auto`, landscape/`16:9`, portrait/`9:16`, square/`1:1`, or an
  129. explicit `WIDTHxHEIGHT`. Keep pixel size as a ComfyUI parameter, not as
  130. prompt prose. The prompt should describe framing such as landscape
  131. composition, medium close-up, macro shot, or slow push-in.
  132. - **Target path:** `reuse-existing`, `current-project`, or `dedicated-folder`.
  133. Run the planner after the doctor scan. It is read-only and does not create
  134. folders:
  135. ```powershell
  136. python scripts/h3_plan.py `
  137. --root <hardware-or-disk-root> `
  138. --comfyui <ComfyUI-path> `
  139. --install-mode reuse-existing `
  140. --mode auto `
  141. --target-minutes 10 `
  142. --aspect landscape `
  143. --megapixels 0.4 `
  144. --video-seconds 5 `
  145. --json
  146. ```
  147. Use the planner result as the source of truth for `--profile`, `--resolution`,
  148. `--steps`, `--length`, and `--fps`. If no quality or time requirement is
  149. given, `auto` selects `fast` and preserves the validated 640x352, 4-step,
  150. Block-Cache route. On an 8 GB laptop, `balanced` keeps 640x352 and increases
  151. steps while bypassing T8 Block Cache; `quality` does the same with 8 steps.
  152. Only the mid/high-VRAM plan promotes balanced/quality to an official-style
  153. ComfyUI bucket by default.
  154. ComfyUI's native H3 templates commonly use `ResolutionSelector`: aspect ratio
  155. + target megapixels + a 32-pixel multiple. For example, `16:9`, `0.4 MP`,
  156. `multiple=32` gives `864x480`. Treat that as the normal official-style H3
  157. canvas, while H3 Lite's `640x352` remains the low-VRAM fast baseline. If the
  158. user asks for "official template size", "normal quality", or "0.4MP", use
  159. `--megapixels 0.4` unless hardware/time preflight blocks it.
  160. The 32-pixel alignment is a practical model/decoder constraint: the VAE's
  161. 16-pixel spatial reduction and the DiT's 2-pixel patching must both align. Do
  162. not advertise consumer labels such as "720p" as exact model sizes when the
  163. nearest legal canvas is different; report the actual canvas (for example
  164. `1280x704`) and keep the requested label as a human-friendly preset name.
  165. For a prompt with several ordered actions, prioritize adherence before pixels.
  166. Use the fast 640x352 baseline first; 736x416 is an experimental adherence
  167. bucket between the fast canvas and 0.4 MP. Do not assume 768p follows complex
  168. shot structure better: community reports describe stronger Ref2VA/keyframe
  169. adherence around 352p-416p, while extra steps mainly improve coherence and
  170. detail. Promote 736x416 only after a same-prompt comparison succeeds locally.
  171. When the user supplies an explicit resolution, treat that canvas choice as
  172. already confirmed: issue one concise OOM/time warning, then continue unless
  173. preflight is `blocked`. Do not ask the same resolution question again. If a
  174. separate wall-clock budget conflicts with the explicit canvas, state the
  175. conflict once and keep the user's explicit canvas. Never silently trade away
  176. the audio path or change the installation target to make the estimate fit.
  177. ## Fast path for ordinary text-to-video
  178. Use this path for a short H3 clip on a machine that passes the low-VRAM doctor
  179. check. With no frame arguments it is T2VA; adding `--first-frame` or
  180. `--last-frame` selects the native reference route automatically:
  181. ```powershell
  182. python scripts/h3_fastpath.py `
  183. --comfyui <ComfyUI-path> `
  184. --prompt-text "<rewritten H3 prompt>" `
  185. --resolution 640x352 `
  186. --video-seconds 5 `
  187. --filename-prefix video/H3Lite_my_clip `
  188. --json
  189. ```
  190. For image-to-video, pass the reference image directly. The helper stages an
  191. external image into `<ComfyUI>/input` using a content-addressed filename, then
  192. connects it to the native `MiniMaxH3ImageToVideo` node. No extra I2V node or
  193. manual JSON editing is required:
  194. ```powershell
  195. python scripts/h3_fastpath.py `
  196. --comfyui <ComfyUI-path> `
  197. --mode i2va `
  198. --first-frame <path-to-first-frame.png> `
  199. --prompt-text "<rewritten I2VA prompt>" `
  200. --resolution 640x352 `
  201. --video-seconds 5 `
  202. --filename-prefix video/H3Lite_i2va `
  203. --json
  204. ```
  205. Use `--mode fl2va --first-frame <first> --last-frame <last>` for fixed first
  206. and last images, or `--mode l2va --last-frame <last>` for a last-frame route;
  207. the helper removes the I2V template's first-frame placeholder automatically in
  208. the latter case.
  209. When `--mode auto` is left in place, the mode is inferred from the supplied
  210. frame arguments. The low-VRAM baseline remains 640x352, 124 frames, 4 steps,
  211. and native H3 audio. A validated RTX 4070 Laptop 8 GB I2VA run at that
  212. baseline took about 12 minutes; treat that as local empirical timing, not a
  213. guarantee.
  214. 已配置环境的复跑路径就是这一条命令;不要再分别调用 doctor、plan、preflight、generate 和 status。Windows/Git Bash 路径请写 `F:/MiniMax-H3/ComfyUI`,不要写 `/f/MiniMax-H3/ComfyUI`。
  215. The helper reuses `<ComfyUI>/user/h3lite_runs/_environment/doctor.json` for 30
  216. minutes, invalidating it only for a cold start, explicit `--force-doctor`, an
  217. installation change, or failure recovery. It writes the plan and prompt into
  218. the run root, keeps the native audio path unless the prompt explicitly asks
  219. for complete silence, and waits with one compact `--watch` monitor. An
  220. explicit resolution is already confirmed; continue after one concise risk
  221. warning unless preflight is `blocked`. `--dynamic-check` is on by default;
  222. use `--skip-dynamic-check` only for an intentionally static clip.
  223. Hot-path budget rule: spend only the time needed to rewrite the prompt, refresh
  224. volatile runtime status, submit, watch, and verify. Do not check Git remotes,
  225. download pages, model hashes, dependency versions, or official docs during a
  226. normal generation unless the previous command returns a concrete error pointing
  227. there. If cache is valid, proceed directly to generation.
  228. ### Native Windows progress window
  229. On Windows, the fastpath opens the native monitor by default, so every normal
  230. desktop generation has a visible progress window without an extra flag. Use
  231. `--no-monitor-gui` for a run that must stay terminal-only; `--monitor-gui`
  232. explicitly forces it on. The window discovers the fresh H3 run manifest
  233. automatically. It uses a native Windows Tkinter window, reuses the manifest's
  234. ComfyUI `client_id`, and listens to the native `/ws`
  235. channel, including the newer `progress_state` node events, while HTTP polling
  236. supplies queue state, elapsed/estimated time, GPU memory, RAM, pagefile, output
  237. path, and failure state. It is monitor-only: closing it does not interrupt
  238. generation.
  239. The node count is structural workflow progress, not elapsed-time progress: H3
  240. nodes have very different runtimes. The window therefore shows node completion
  241. separately, displays the current node's observed runtime, and keeps ETA on the
  242. empirical timing estimate instead of treating `4/5` as `80%` of the time. The
  243. track is segmented by workflow node so completed, active, and pending nodes
  244. remain visually distinct.
  245. The default window is `760x620`; its content area has a vertical scrollbar and
  246. mouse-wheel support for smaller displays or larger system scaling.
  247. The monitor JSON marks these semantics as `progress_basis` (`node_completion`
  248. or `sampling_steps`) and `eta_basis` (`empirical` or `live_progress`) so an
  249. Agent can report them without inventing a time percentage.
  250. When available, elapsed time comes from the run manifest's measured execution
  251. time; the wall-clock timestamp is only the fallback before that field exists.
  252. Old `running` manifests are ignored during automatic discovery; pass
  253. `--prompt-id` to inspect a specific historical run.
  254. To open the monitor independently:
  255. ```powershell
  256. python scripts/h3_monitor_gui.py `
  257. --comfyui <ComfyUI-path>
  258. ```
  259. Use `--once --no-websocket` for a one-shot JSON diagnostic. If the optional
  260. WebSocket client is unavailable, the window remains usable through HTTP
  261. polling, but the progress track stays static and explicitly reports that live
  262. quantifiable progress is unavailable. It never substitutes an animated bar
  263. for a measured percentage. An MCP wrapper is unnecessary for this local GUI;
  264. an Agent can query the same monitor JSON separately when it needs status.
  265. Use the lower-level `h3_doctor.py`, `h3_plan.py`, `h3_preflight.py`,
  266. `h3_generate.py`, and `h3_status.py` commands only for installation, recovery,
  267. custom workflows, or diagnosis. Never replace the fastpath with repeated
  268. one-shot status commands during a normal generation.
  269. Use the history/object-info/browser fallback only when the bundled template is
  270. incompatible, a Ref2VA/custom graph is needed, or the queue reports a missing
  271. node/model. T2VA, I2VA, FL2VA, and L2VA are now first-class bundled routes.
  272. ## Workflow
  273. ### 1. Diagnose the computer
  274. Run:
  275. ```powershell
  276. $environment = '<ComfyUI>\user\h3lite_runs\_environment'
  277. python scripts/h3_doctor.py `
  278. --json `
  279. --report-file "$environment\doctor.json" `
  280. --root <chosen-root> `
  281. --comfyui <ComfyUI-path>
  282. ```
  283. Record GPU name and VRAM, system RAM, free disk, Python, CUDA/PyTorch visibility, ComfyUI location, model presence, and custom-node presence. If there is no NVIDIA CUDA device, do not promise this local CUDA route; explain the limitation and offer API/cloud or another backend as an alternative.
  284. The doctor also records available physical RAM, available Windows pagefile, and
  285. GPU compute processes. Low available RAM or VRAM is a warning because the
  286. validated 8 GB route can still finish with offload. A nearly exhausted
  287. pagefile is different: it previously caused `hostbuf_file_reader_read failed`
  288. and system-level paging failures, so `h3_preflight.py` blocks that run.
  289. Use `references/deployment-matrix.md` to choose a profile. For an 8 GB laptop, start with the tested W4A8 profile, not the larger official INT8/32B profile.
  290. If the user asked for installation or repair, report the selected installation
  291. target before the doctor result. The doctor is read-only; it does not install
  292. ComfyUI, nodes, Python packages, or model weights.
  293. ### 2. Select a profile
  294. - **Fast (default):** a registered W4A8/4B/Turbo component set, 4B ClipProj, FP16 video VAE, FP32 audio VAE, 640x352, 124 frames, and 4 steps. The launch profile uses `--lowvram` for the very-low/8 GB tiers; 10–16 GB systems use normal VRAM mode unless preflight or a prior OOM justifies offload. Use Block Cache only when its classes are actually loaded; otherwise use the compatibility workflow. This is the success-rate baseline.
  295. - **Balanced:** keep the low-VRAM canvas on an 8 GB laptop, use 6 steps, and bypass Block Cache. On a mid/high-VRAM machine, the planner may select 864x480.
  296. - **Quality:** use 8 steps and bypass Block Cache. On an 8 GB laptop, keep 640x352 and warn that W4A8/4B remains a quality ceiling; on a mid/high-VRAM machine, the planner may select 864x480.
  297. The accelerated fast graph is paired with the registered LightX2V/Turbo 4-step
  298. LoRA. `minimax_h3_turbo_v4_step600_ema.safetensors` is a compatibility-workflow
  299. quality variant: H3 Lite rejects it when Sage/Sol/Chunk/T8 acceleration nodes are
  300. present, because that combination produced severe ghosting and color artifacts in
  301. local validation. Use a `*_compat_api.json` workflow for v4, or use the registered
  302. LightX2V/Turbo 4-step LoRA for the fast route.
  303. - **6 GB experimental:** when the machine has roughly 6 GB VRAM, 32 GB system RAM, an SSD, and sufficient pagefile headroom, permit a cautious first run at 608x352, 4 steps, and low-VRAM offload. Treat community timings as orientation only: reported I2V runs include about 345 seconds at 608x352/4 seconds and 441 seconds at 864x480/5 seconds, while another 640x480/5-second report took about 13.7 minutes. These used different official/community model and workflow combinations, so do not transfer the numbers to the bundled W4A8 graph as a promise.
  304. - **Below roughly 6 GB or insufficient RAM/disk:** stop before downloading or queueing. Explain the missing capacity and propose a hosted/API or alternative model.
  305. Do not infer that a smaller file or INT8 label is automatically faster. On low-VRAM systems, CPU offload, RAM bandwidth, kernel compatibility, and first-run compilation often dominate.
  306. The planner's `--target-minutes` option chooses the highest-quality mode whose
  307. conservative upper estimate fits the budget. Without that option, `auto`
  308. always selects fast. The estimate must include a cold-start warning and the
  309. final report must include ComfyUI's actual execution time.
  310. ### 3. Install or repair the environment
  311. Use the official ComfyUI H3 tutorial and the component list in
  312. `references/deployment-matrix.md`. Create or reuse the selected ComfyUI root
  313. and place every component below that root. Pin or record the ComfyUI and
  314. custom-node commits used for a successful run. Install only nodes referenced by
  315. the selected workflow. The baseline requires `ComfyUI-ClipProj` or a compatible
  316. implementation. KJNodes, H3 Turbo helper nodes, Sol Attention, and T8 Block
  317. Cache are optional unless the selected accelerated graph explicitly uses them.
  318. `h3_fastpath.py --workflow-template auto` is the default. It queries
  319. `/object_info` when available and uses the accelerated T2V or I2V graph only
  320. when the Sage, Sol, Chunk Feed Forward, and T8 classes are actually loaded.
  321. Pass `--component-set A` or `--component-set B` when both complete sets are
  322. installed. Set B is validated with the compatibility graph on RTX 4060 Ti
  323. 16 GB and RTX 4070 Laptop 8 GB systems, so `auto` selects that graph. Its full
  324. Sage/Sol/Chunk/T8 acceleration chain is not yet the validated default; use
  325. `--acceleration fast` only for an intentional trial. Use `--acceleration
  326. compat` to force the validated compatibility graph.
  327. Both graphs preserve the H3 sampler, native audio, ClipProj, LoRA, dual VAEs,
  328. and native first/last-frame inputs without optional patches.
  329. The bundled multi-image Ref2VA graphs reuse this same registered component set:
  330. there is no separate Ref2VA checkpoint to download. They add the native
  331. `MiniMaxH3ReferenceToVideo` route and bind repeated reference images through the
  332. resident ClipProj path. Before downloading anything, reuse the local W4A8,
  333. 4B encoder, ClipProj, dual VAE, and Turbo LoRA files when their manifest and
  334. loader checks pass.
  335. Keep optional INT8 loaders and experimental cache nodes disabled until the baseline works. Start ComfyUI with a profile-appropriate command; the very-low/8 GB launch profile commonly uses `--lowvram` and `--fast-disk`, while 10–16 GB systems normally omit `--lowvram` unless preflight or an earlier OOM justifies it. Add Sage Attention only after its PyTorch/CUDA compatibility is confirmed. Treat Easy Cache and generic cache nodes as opt-in experiments: community reports and local experience show that some settings can blur or damage motion/detail. Never enable a cache solely from a speed claim; compare a short output against the uncached baseline first.
  336. After installation, rerun the doctor and stop if any required model or node is missing. Do not start a long generation while the graph contains unresolved node classes.
  337. Cold-path validation is deliberately allowed to spend extra seconds or minutes:
  338. record component URLs, selected replacement filenames, file sizes or hashes,
  339. local loader choices, Python import probes, and any small compatibility patch
  340. that was applied. This is cheaper than discovering a wrong 20 GB model or a
  341. Torch/custom-node mismatch after queueing. Once the baseline succeeds, write or
  342. refresh the cached environment/component report and return to the hot path for
  343. future prompts.
  344. When public internet is the only source for a large model such as the W4A8
  345. diffusion checkpoint, do not start a blind long transfer. First probe the
  346. official raw URL, configured mirror raw URL, and any user-provided proxy URL
  347. with a small resumable/ranged request. Report the fastest measured speed,
  348. estimated time, and selected command. Prefer `aria2c` with conservative
  349. connections when available and the server supports ranges; otherwise use
  350. `curl.exe -L -C -`. Keep partially downloaded files as `.part` and resume them;
  351. do not delete progress or restart from byte zero unless the size/hash proves
  352. the file is unrecoverable.
  353. Before queueing, run:
  354. ```powershell
  355. python scripts/h3_plan.py `
  356. --doctor-json <ComfyUI>\user\h3lite_runs\_environment\doctor.json `
  357. --install-mode reuse-existing `
  358. --comfyui <ComfyUI-path> `
  359. --mode auto `
  360. --aspect landscape `
  361. --video-seconds 5 `
  362. --report-file <ComfyUI>\user\h3lite_runs\_environment\plan.json `
  363. --json
  364. python scripts/h3_preflight.py `
  365. --doctor-json <ComfyUI>\user\h3lite_runs\_environment\doctor.json `
  366. --plan-json <ComfyUI>\user\h3lite_runs\_environment\plan.json `
  367. --refresh-runtime `
  368. --require-audio `
  369. --json
  370. ```
  371. `ready` means no observed risk, `caution` means the run may proceed with an
  372. explicit warning, and `blocked` means fix the environment or use another
  373. backend first. The preflight ignores the Python process used by ComfyUI and
  374. zero-memory desktop helpers; it warns only for meaningful external GPU
  375. competitors. This is a runtime gate, not a promise of success.
  376. ### 4. Rewrite the user's request into an H3 prompt
  377. Identify the generation mode before writing:
  378. - text only → `T2VA`
  379. - one first-frame image → `I2VA`
  380. - first and last images → `FL2VA`
  381. - last-frame image → `L2VA`
  382. - reusable images/video/audio references → `Ref2VA`
  383. Read `references/prompt-writing.md` when composing or revising a prompt. For
  384. multi-shot, identity-sensitive, or reference-heavy requests, also read
  385. `references/agent-workflow.md` and build the route/anchor sheet before writing.
  386. For an underspecified creative request, also read
  387. `references/prompt-assist.md`: it supplies the optional
  388. `STYLE/IDENTITY LOCK → SCENE → MOTION → AUDIO → NEGATIVE` scaffold and the
  389. rules for translating it back to H3. Ask only for information that materially
  390. changes the route or acceptance criteria; otherwise state the bounded default
  391. and continue. Never make a website lookup a runtime dependency.
  392. Use the exact field names and ordering required by the selected mode. For
  393. native base modes, the core order is:
  394. ```text
  395. integrated_multimodal_description: ...
  396. overall_soundscape: ...
  397. non_diegetic_music: ...
  398. ```
  399. For user-facing 5-second quick-start examples, teach the same idea as a memorable three-part structure: **scene and atmosphere → action and camera → sound**. Present it as one natural-language prompt that can be copied directly; do not require users to write schema labels. Treat this as an explanation aid, then translate it internally into the workflow's required prompt schema.
  400. For full-reference mode, use the six-section structure in the reference. Write the rewritten description in English, but preserve user-provided dialogue, lyrics, and visible scene text in the original language.
  401. Make the prompt operational:
  402. - establish style, framing, subjects, environment, lighting, and initial state in Shot 1;
  403. - make each important person's orientation relative to the camera explicit when identity or facial visibility matters; “watching the sunset” alone often implies a back view. State front-facing, three-quarter, profile, or back-facing, and say whether the face and eyes must remain visible;
  404. - describe observable actions and state changes in playback order;
  405. - use later shot cut times only when a real cut introduces new information;
  406. - write camera motion as a natural sentence with motion type, amplitude, and speed when useful;
  407. - describe dialogue, singing, and diegetic sound in the timeline body;
  408. - describe ambient/physical sound in `overall_soundscape` and audience-only music in `non_diegetic_music`;
  409. - Resolve the audio policy before submission: `auto`/ordinary prompts require the native H3 audio path; “no dialogue” does not disable sound. Only explicit complete-silence wording may remove the `CreateVideo` audio input.
  410. - Interpret `不要对白` / `无对白` / `no dialogue` as a dialogue-only constraint: keep native ambience, sound effects, animal or action sounds, and the audio stream. Disable all audio only when the user explicitly requests `完全静音`, `无任何声音`, or `no audio`.
  411. - use stable speaker IDs and exact text for dialogue;
  412. - use `N/A` for music only when no non-diegetic music is desired, and use `overall_soundscape: N/A` only for explicitly complete silence.
  413. If the selected ComfyUI graph uses a ClipProj/krea2 or another custom prompt schema, inspect its example workflow first. Adapt the official semantic structure to the node's accepted field while preserving the graph's required fields; do not blindly paste a T2VA prompt into a Ref2VA input or vice versa.
  414. - For a face-quality attempt, constrain the first shot to one face, a front or three-quarter orientation, visible eyes, stable hair/clothing anchors, and static or small-amplitude motion. Treat dialogue as a second-stage stressor. A valid MP4 with dynamic/color/audio checks can still have unusable faces; visually inspect face consistency at first/middle/last frames.
  415. - For Chinese prompts, avoid an extremely short noun-only description. H3's long multimodal sequence can make a one- or two-token Chinese prompt easy for the seed to dominate. Add concrete subject traits, setting, framing, lighting, and motion; as a practical starting point, use roughly 30–50 Chinese characters or an equivalent amount of structured detail, then validate with a cheap preview.
  416. - For a director-level multi-shot sequence (establishing + over-the-shoulder + reverse + reveal) where H3's single-continuous-shot limit blocks real coverage, see `references/director-sequences.md`. It covers splitting the scene into separate I2VA segments, generating consistent first-frame images with ImageGen (watermark crop, reference-image identity inheritance), locking character identity across prompts, W4A8 skin-quality phrasing, and stitching with ffmpeg `xfade`/`acrossfade`.
  417. ### 5. Generate through ComfyUI
  418. For installation, recovery, or custom-workflow debugging, the lower-level
  419. helpers remain available. A normal text-only request should use
  420. `h3_fastpath.py` above:
  421. ```powershell
  422. python scripts/h3_generate.py `
  423. --base-url http://127.0.0.1:8188 `
  424. --workflow-template h3_w4a8_t2v `
  425. --prompt-file prompts/current.txt `
  426. --comfyui <ComfyUI-path> `
  427. --filename-prefix video/H3Lite_my_clip `
  428. --run-root <ComfyUI>\user\h3lite_runs `
  429. --component-set auto `
  430. --resolve-models `
  431. --audio-policy auto `
  432. --profile fast `
  433. --resolution 640x352 `
  434. --seed 20260813 `
  435. --watch `
  436. --watch-interval 20 `
  437. --watch-timeout 3600 `
  438. --json
  439. ```
  440. For a lower-level I2VA or FL2VA run, use the matching bundled template and
  441. frame flags. `--workflow <file>` remains supported for custom Ref2VA or other
  442. graphs; the same flags will bind any existing `LoadImage` reference input, or
  443. add one when the H3 node has no connection yet:
  444. ```powershell
  445. python scripts/h3_generate.py `
  446. --workflow-template h3_w4a8_i2v `
  447. --prompt-text "<rewritten I2VA prompt>" `
  448. --first-frame <path-to-first-frame.png> `
  449. --comfyui <ComfyUI-path> `
  450. --output-dir <ComfyUI>\output `
  451. --resolution 640x352 `
  452. --length 124 `
  453. --steps 4 `
  454. --component-set auto `
  455. --resolve-models `
  456. --watch `
  457. --json
  458. ```
  459. This lower-level command now submits and monitors in the same foreground
  460. process. Use `--queue-only` only when another process must own monitoring.
  461. For the bundled multi-image Ref2VA route, repeat `--ref-image` in the order
  462. that the prompt names `<Picture 1>`, `<Picture 2>`, and so on. The native
  463. `MiniMaxH3ReferenceToVideo` node accepts image references in fixed order; do
  464. not combine `--ref-image` with `--first-frame` or `--last-frame`:
  465. ```powershell
  466. python scripts/h3_generate.py `
  467. --workflow-template h3_w4a8_ref2va_compat `
  468. --prompt-file prompts/ref2va.txt `
  469. --ref-image <identity.png> `
  470. --ref-image <scene.png> `
  471. --ref-image <wardrobe-or-prop.png> `
  472. --comfyui <ComfyUI-path> `
  473. --output-dir <ComfyUI>\output `
  474. --resolution 640x352 `
  475. --length 124 `
  476. --steps 4 `
  477. --component-set A `
  478. --resolve-models `
  479. --watch `
  480. --json
  481. ```
  482. The Ref2VA encoder is kept resident because the installed ClipProj node's
  483. dynamic image path is not reliable with the low-VRAM int8 encoder. Resident
  484. mode can consume more VRAM than I2VA; preflight may therefore block an 8 GB
  485. machine or recommend a small preview. Treat `--ref-image` as a real reference
  486. conditioning input, not as a style-only attachment.
  487. The native `MiniMaxH3ReferenceToVideo` node also exposes reference-video and
  488. reference-audio inputs. The bundled fastpath deliberately exposes repeated
  489. `--ref-image` first because that path is the most predictable to bind and
  490. verify; use a native/custom workflow when those other reference types are
  491. required.
  492. ```powershell
  493. python scripts/h3_status.py `
  494. --base-url http://127.0.0.1:8188 `
  495. --prompt-id <prompt-id> `
  496. --comfyui <ComfyUI-path> `
  497. --output-dir <ComfyUI>\output `
  498. --run-root <ComfyUI>\user\h3lite_runs `
  499. --require-audio `
  500. --dynamic-check `
  501. --anchor-check `
  502. --compact `
  503. --json
  504. ```
  505. The JSON result is compact by default; use `--verbose` only when a failed run
  506. needs the full ComfyUI history graph. For a bounded foreground monitor, add
  507. `--watch --watch-interval 20 --watch-timeout 3600`. A pending response has
  508. `ok: false` and `complete: false`; only a completed, verified media response
  509. has `ok: true`.
  510. Do not describe a faster second run as a reused result. ComfyUI may retain model weights and reuse unchanged upstream node outputs such as encoder or VAE loading, but a changed prompt or seed still causes the sampler to generate a new video. Explain this distinction when a user asks why later runs are faster.
  511. The accelerated bundled template contains the prompt node, W4A8 model path, 4B
  512. ClipProj, dual VAE, Turbo LoRA, H3 sigma shifts, Sage/Sol/T8 patches, native
  513. audio, 124 frames, 640x352, and 4 steps. The compatibility template removes
  514. the optional Sage/Sol/T8 chain. `--resolve-models` switches the complete
  515. registered A/B component set atomically; use `--component-set B` when both
  516. sets are installed. Override `--seed`, `--width`,
  517. `--height`, `--length`, `--steps`, `--fps`, `--profile`, or `--resolution` only
  518. when needed. Prefer `--megapixels` for ComfyUI ResolutionSelector-style canvas
  519. choices such as `16:9 0.4MP -> 864x480`. `fast` keeps Block Cache; `balanced`
  520. uses 6 steps and bypasses Block Cache; `quality` uses 8 steps and bypasses
  521. Block Cache. For a custom API
  522. workflow, pass `--workflow <file>`; the prompt field can still be discovered or
  523. selected with `--prompt-node` and `--prompt-field`.
  524. Do not use synchronous wait mode from a terminal command with a short timeout.
  525. `h3_fastpath.py` uses `h3_generate.py --watch` so submission and verification
  526. stay in one bounded foreground process; use `--queue-only` only when another
  527. process must own monitoring.
  528. For the low-VRAM baseline, use 124 frames at 24 fps (about 5 seconds), 4 steps, `res_multistep`, and `simple`. Use 640x352 for the normal fast output; use the ComfyUI official-style 0.4MP bucket (`864x480` for 16:9) only when the planner approves the hardware/time trade-off or the user explicitly asks for it.
  529. ### 6. Verify and report
  530. Do not report success from a queue ID alone. Confirm:
  531. - the job completed without an execution error;
  532. - an MP4 or other intended video file exists;
  533. - the file has a video stream and, for native H3 output, an audio stream;
  534. - duration, frame count, and FPS are close to the requested values;
  535. - the first/middle/last samples are not black, flat, or classified as `suspected_mosaic`; when the user asked for an action, dynamic QA must classify the clip as `dynamic`;
  536. - when identity, clothing, props, or a reference composition is an acceptance condition, sampled frames preserve the declared anchors and do not silently drift;
  537. - the output path and elapsed time are reported.
  538. - the plan's estimated range is compared with the actual ComfyUI execution time;
  539. - the configuration fingerprint and run manifest are recorded so a retry can be distinguished from an accidental duplicate;
  540. - the selected ComfyUI, models, custom_nodes, and output paths are recorded.
  541. If verification returns `ffprobe_not_found`, keep the generated file and repair
  542. only the verifier path. Set `H3LITE_FFPROBE` to an absolute `ffprobe.exe` when
  543. the executable lives outside the bounded ComfyUI locations; do not rerun the
  544. model merely because metadata inspection was unavailable.
  545. When diagnosing failures, use this order:
  546. 1. critically low pagefile, unavailable RAM, or another GPU process;
  547. 2. missing model or custom node;
  548. 3. wrong model folder or filename;
  549. 4. CUDA/PyTorch/custom-kernel incompatibility;
  550. 5. out-of-memory or excessive CPU offload;
  551. 6. invalid H3 flow/audio graph;
  552. 7. prompt or reference alignment problem.
  553. For black/mosaic output, restore the official H3 flow/sigma-shift node and simplify optional attention/cache patches. For distorted audio at 4 steps, check the H3 audio/video schedules and use the compatible H3 Turbo sampler on older ComfyUI builds.
  554. ## Video upscale (post-processing)
  555. Super-resolution is post-processing, not another H3 generation pass: it never
  556. changes the generation graph, adds sampling steps, or silently follows a run.
  557. The registered low-VRAM route has been validated around 0.5 MP (for example,
  558. 960x544), but that is not a model-wide H3 limit. Official/native H3 workflows
  559. support larger canvases; use the doctor, planner, and preflight result as the
  560. source of truth for the selected local canvas. Add upscale only when the user
  561. explicitly asks for a target beyond that selected canvas, and never promise
  562. pixel-exact consumer labels ("1080p") as model output sizes. Read
  563. [`references/video-upscale.md`](references/video-upscale.md) for the routes,
  564. portable path discovery, measured case studies, and the problem table.
  565. Rules:
  566. - **Primary route (when actually installed): Topaz Video AI.** The user selects
  567. the enhancement model (Starlight/Astra Fast for H3-style clips, Proteus/Rhea
  568. for general footage), the output scale, and exports from the GUI. Do not
  569. assume a Topaz install, model list, or path copied from another machine.
  570. Topaz has no stable public CLI contract; log command lines are diagnostic
  571. evidence only, never a scriptable runtime dependency.
  572. - **Pre-export checks:** discover the actual Topaz/model roots, inspect free
  573. VRAM with `scripts/h3_vram.py --json`, and confirm any competitor is idle.
  574. Treat model presence and SHA-512 catalog checks as machine-local facts; do
  575. not state that a model is installed or missing without checking this machine.
  576. - **During export:** do not start another heavy CUDA job (no H3 generation on
  577. the same card); a 2x Starlight export of a ~210-frame clip takes on the
  578. order of 20 minutes at 0.3 fps while decoding.
  579. - **After export:** ffprobe must show the expected size, 24 fps, an audio
  580. stream, and near-original duration; the `videoai=Enhanced using ...`
  581. metadata tag marks an already-enhanced file — do not upscale it again.
  582. - **Fallbacks (scriptable, offline):** use FlashVSR only after discovering
  583. <FlashVSR_ROOT>, its environment, the exact CLI fork/commit, and the model
  584. pack. Invoke the script by absolute path, for example
  585. <FlashVSR_ROOT>\ComfyUI-FlashVSR_Stable\cli_main.py; a bare
  586. `cli_main.py` depends on the current working directory and is not portable.
  587. Preserve the validated tiling/chunking settings from the local reference,
  588. verify frame count and audio after export, and treat truncated output as a
  589. failed run. If FlashVSR is absent, use the discovered ComfyUI venv plus a
  590. verified 4x-UltraSharp weight, or plain ffmpeg for previews. Never invent a
  591. missing wrapper, model, venv, or path.
  592. ## GPU memory contention with other heavy CUDA apps
  593. A machine may host several heavy CUDA workloads at once (ComfyUI plus an
  594. independent video tool, game streaming, another generation backend). Windows
  595. WDDM reporting hides per-process VRAM: `nvidia-smi --query-compute-apps`
  596. returns N/A or 0 MiB per process, while PyTorch's free-memory figure stays
  597. optimistically high. Failures then look like CUDA OOM at tiny allocation sizes
  598. ("Tried to allocate 28.00 MiB ... 8.91 GiB free") or like a plain access
  599. violation (Windows exit code 0xC0000005) with no OOM text at all.
  600. Rules:
  601. - When preflight flags a meaningful competitor or a fragile job fails at
  602. allocation, run `python scripts/h3_vram.py --json` to see who holds the
  603. VRAM. Read the reported process scope and WDDM LUIDs; do not treat a
  604. process row from an unmapped adapter as proof that it competes for the
  605. selected CUDA GPU.
  606. - Confirm the competitor is idle before touching it. For ComfyUI, check
  607. `http://127.0.0.1:8188/queue` (running + pending empty), and remember an
  608. empty queue does not release resident models: the process still shows
  609. several GB until ComfyUI restarts or offloads.
  610. - Never stop a ComfyUI that has queued or running items; losing a run wastes
  611. the whole generation.
  612. - Gate only after the report shows a comparable adapter scope. The
  613. `--check-free-gb` command fails closed with exit code 2 when the
  614. scope is unknown; choose the threshold from the selected workload and
  615. hardware rather than assuming 5 GB. Use `--allow-scope-mismatch`
  616. only when the user explicitly accepts a global `nvidia-smi`-only
  617. check.
  618. - A destructive stop requires `--confirm-stop` and the exact
  619. `--process-name` from the report. For ComfyUI also pass
  620. `--queue-url`; the helper refuses to stop when the queue cannot be
  621. read or is non-empty.
  622. - Read `references/gpu-contention.md` for the measured case (ComfyUI holding
  623. 9,805 MB resident on a 16 GB card while a Topaz Video AI Starlight export
  624. failed at a 28 MiB VAE allocation) and the diagnostic commands.
  625. ## Bundled resources
  626. - `references/deployment-matrix.md`: tested low-VRAM profile, official fallback profile, model folders, node roles, launch flags, and failure triage.
  627. - `references/component-sets.md`: registered model/workflow sets, exact known byte sizes, runtime ABI record, and download-integrity rules.
  628. - `references/prompt-writing.md`: concise operational digest of MiniMax's official H3 prompt guide and prompt-writing skill.
  629. - `references/director-sequences.md`: end-to-end workflow for multi-segment director sequences (divide a scene into separate I2VA shots, generate consistent first frames with ImageGen including watermark crop and reference-image identity inheritance, lock character identity across prompts, W4A8 skin-quality phrasing, and stitch with ffmpeg `xfade`/`acrossfade` using the cumulative-offset formula).
  630. - `references/agent-workflow.md`: intent routing, reference/identity anchors, five-pass prompt enhancement, and local capability boundaries.
  631. - `references/prompt-assist.md`: optional Higgsfield-inspired prompt-pattern lookup for vague creative briefs; maps style/scene/motion/audio/negative cards back to H3 fields without adding a cloud dependency.
  632. - `references/face-quality.md`: face-first routing, official Ref2VA identity controls, low-VRAM trade-offs, and the limits of dynamic/color QA.
  633. - `references/gpu-contention.md`: Windows/WDDM VRAM contention between ComfyUI and other heavy CUDA apps; per-process memory via the GPU Process Memory counter, idle-queue checks, the stop/restart order, and a measured 16 GB case plus a Topaz Video AI repair appendix.
  634. - `references/video-upscale.md`: post-process video upscale routes (Topaz Video AI primary, a discovered/pinned FlashVSR CLI root as the scripted backup — run command, model pack, VRAM tier table, the measured tiled-seam grid case and fix, frame-count truncation check), 4x-UltraSharp via the discovered ComfyUI venv, plain ffmpeg fallback, and the problem/consequence table for contention, corrupt weights, audio, and frame-rate pitfalls.
  635. - `assets/h3_w4a8_t2v_api.json`: reusable low-VRAM T2VA API graph based on the validated W4A8/4B/audio route.
  636. - `assets/h3_w4a8_t2v_compat_api.json`: core T2VA graph without optional Sol Attention, Chunk Feed Forward, or T8 Block Cache nodes.
  637. - `assets/h3_w4a8_i2v_api.json`: reusable low-VRAM I2VA graph with native first-frame input and optional acceleration patches.
  638. - `assets/h3_w4a8_i2v_compat_api.json`: core I2VA graph with native first-frame input and no optional acceleration patches.
  639. - `assets/h3_w4a8_ref2va_api.json`: experimental multi-image Ref2VA graph with the native `MiniMaxH3ReferenceToVideo` node.
  640. - `assets/h3_w4a8_ref2va_compat_api.json`: compatibility Ref2VA graph without optional Sage/Sol/Chunk/T8 patches.
  641. - `scripts/h3_doctor.py`: dependency-free hardware, disk, model, and node diagnosis.
  642. - `scripts/h3_plan.py`: read-only hardware, resolution, time-budget, aspect-ratio, profile, and installation-path planner.
  643. - `scripts/h3_preflight.py`: read-only pagefile/RAM/VRAM/process/model/node gate before queueing.
  644. - `scripts/h3_generate.py`: fast template-based or custom-workflow submission with profile, resolution, prompt/settings overrides, native first/last-frame binding, atomic A/B component-set selection, and queue-only mode.
  645. - `scripts/h3_anchor.py`: deterministic prompt/reference anchor-card generation and optional JSON declaration loading; it does not add inference or rewrite the prompt.
  646. - `scripts/h3_status.py`: compact one-shot or bounded watch status, actual execution-time, media metadata verification, optional first/middle/last dynamic QA, advisory anchor continuity QA, and empirical timing-cache updates.
  647. - `scripts/h3_fastpath.py`: single-entry T2V/I2V route that reuses the environment cache, probes loaded node classes, routes component sets, and keeps queueing plus bounded verification in one command.
  648. - `scripts/h3_monitor_gui.py`: native Windows Tkinter progress window for live queue/sampling/resource/output visibility; it does not replace ComfyUI or interrupt a run.
  649. - `scripts/h3_paths.py`: Windows path normalization for `F:/...` and Git Bash `/f/...` inputs.
  650. - `scripts/h3_cleanup.py`: dry-run-first maintenance for old timestamped run snapshots; preserves environment state and recent runs.
  651. - `scripts/h3_vram.py`: read-only Windows per-process dedicated-VRAM report (preserving WDDM adapter LUIDs, with `--query-compute-apps` fallback), scope-aware free-VRAM gate, and guarded destructive stop requiring an exact process name, explicit confirmation, and optional queue check.
  652. ## Sources
  653. - Official H3 prompt guide: <https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md>
  654. - Official H3 prompt-writing skill: <https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing>
  655. - Official ComfyUI H3 tutorial: <https://docs.comfy.org/tutorials/video/minimax/minimax-h3>
  656. - H3 Turbo ComfyUI nodes: <https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo>
  657. - Cinema DNA 21:9 × 3: <https://github.com/dacnay816y62-hub/cinema-dna-21x9x3>
  658. - Official H3 repository and prompting guidance: <https://github.com/MiniMax-AI/MiniMax-H3>
  659. - Public agent-workflow design reference (not a runtime dependency): <https://github.com/higgsfield-ai/skills>
  660. - Public prompt-pattern references (optional writing aid, not a runtime dependency): <https://github.com/higgsfield-ai/skills/blob/main/higgsfield-video-explainer/references/prompts.md>, <https://higgsfield.ai/ai-prompt-generator>
  661. - Community Mac/Metal MLX port and operational notes (reference only; not a tested h3lite backend): <https://zhuanlan.zhihu.com/p/2069479566171812707>
  662. - Community Apple Silicon local-deployment troubleshooting (reference only; not a Windows resource source): <https://mp.weixin.qq.com/s/hN60KLN7Pkpqb0pbk-r4WQ>
README.md · README · 343 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # H3 Lite
  2. <p align="center">
  3. <img src="assets/h3-lite-hero.gif" alt="H3 Lite — MiniMax H3 本地部署与视频生成 Skill" width="100%">
  4. </p>
  5. <p align="center">
  6. <img alt="License MIT" src="https://img.shields.io/badge/License-MIT-1F5E4A?style=for-the-badge">
  7. <img alt="Hosts Codex" src="https://img.shields.io/badge/Hosts-Codex-4B6B8A?style=for-the-badge">
  8. <img alt="Route Low VRAM Fast" src="https://img.shields.io/badge/Route-Low--VRAM%20Fast-D9A441?style=for-the-badge">
  9. </p>
  10. <p align="center">中文 | <a href="README.en.md">English</a> | <a href="#参考资料">参考资料</a></p>
  11. `H3 Lite` 是给 Codex、WorkBuddy 等 AI Agent 使用的 MiniMax H3 本地视频生成 Skill。描述想看的画面后,Agent 会根据电脑配置选择 ComfyUI 路线、准备组件、生成带原生声音的视频并检查结果。
  12. ## 模型定位与适用范围
  13. H3 Lite 面向 Windows + NVIDIA + ComfyUI 的低显存本地视频生成。Set A 使用 W4A8 扩散模型和 4B INT4 文本编码器,Set B 使用 4B FP8 文本编码器;两套组件分别对应低显存快速路线和 FP8 兼容路线。
  14. 当前已验证的主路线是 **Windows + NVIDIA + ComfyUI**:
  15. | 平台 | 支持状态 | 指导 |
  16. |---|---|---|
  17. | Windows + NVIDIA | 主支持路线 | 使用本仓库的 ComfyUI、doctor、planner 和 fastpath。 |
  18. | macOS Apple Silicon | 社区路线 | 可参考 MLX/Metal 的 `mmh3turbo`。 |
  19. | macOS Intel | 未验证 | 使用托管/API 或其他后端。 |
  20. | Linux + NVIDIA | 实验路线 | 需自行适配路径、节点和运行参数。 |
  21. Mac 社区路线可参考[社区权重包](https://huggingface.co/yunfengwang/mmh3turbo-bundles)和 `uvx mmh3turbo`,与本 Skill 的 ComfyUI 组件分开使用。
  22. ## 从需求到成片:四步工作流
  23. 复杂视频按“**意图路由 → 参考图锚点 → 提示词增强 → 生成与验收**”处理。
  24. | 你的目标 | 优先路线 | 关键做法 |
  25. |---|---|---|
  26. | 纯文字描述完整视频 | `T2VA` | 先写开场状态,再按时间顺序写动作、镜头和声音。 |
  27. | 指定视频第一帧 | `I2VA` | 把参考图锁定在 `0.00s`,只描述后续变化。 |
  28. | 指定首尾画面 | `FL2VA` | 描述两个锚点之间连续、可见的变化。 |
  29. | 多张图/视频/音频参考 | `Ref2VA` | 先定义每份素材的角色、保留项和可变项,再写分镜。 |
  30. 人物或多镜头任务先建立锚点卡,固定角色、服装、道具、场景和光线,并为参考素材使用稳定名称,如 `Subject A`、`Picture 1`。若 Ref2VA 组件不完整,Agent 会改用 I2VA 或标记为实验路线。
  31. 运行时会把锚点卡保存为 `anchors.json`,并在 `manifest.json` 记录路径。`anchor_qa` 用首/中/尾帧检查画面连续性,身份、服饰和构图仍需人工复核。
  32. 提示词按“意图 → 场景与角色 → 动作与分镜 → 运镜与声音 → 防漂移约束”增强,最后转换为 H3 的 `integrated_multimodal_description`、`overall_soundscape`、`non_diegetic_music` 字段。
  33. 模糊需求可参考 [`references/prompt-assist.md`](references/prompt-assist.md) 补齐场景、动作、运镜和声音。
  34. ## 快速开始
  35. 把下面这句话发给 Codex 或 WorkBuddy:
  36. ```text
  37. 请帮我安装 H3 Lite,并根据我的电脑配置准备本地 MiniMax H3 视频生成环境:
  38. https://github.com/Rimagination/h3lite
  39. ```
  40. 如果不想占用系统盘,把目标位置写进同一条消息:
  41. ```text
  42. 请把 MiniMax H3 和 ComfyUI 安装到 F:\MiniMax-H3;如果那里已经有健康环境就直接复用。
  43. ```
  44. 首次安装时间取决于模型大小、网络和硬盘速度。
  45. ## 硬件与路线选择
  46. 主支持配置为 Windows + NVIDIA。显存、系统内存、pagefile、磁盘和笔记本功耗都会影响速度。
  47. | 已验证电脑 | GPU | 内存 | 路线 |
  48. |---|---|---|---|
  49. | 机械革命翼龙 15 Pro | RTX 4070 Laptop 8 GB | Ryzen 7 8845H / 32 GB | `LOW_VRAM`;Set A T2VA/I2VA,Set B 兼容 T2VA |
  50. | Windows 10 台式机 | RTX 4060 Ti 16 GB | i5-13400F / 32 GB | Set B;`NORMAL_VRAM`;T2VA/I2VA |
  51. 同一套 Set B、兼容工作流、提示词、seed 和 `640×352 / 4 步` 参数下,RTX 4060 Ti 16 GB 约 77.08 秒,RTX 4070 Laptop 8 GB 约 591.22 秒。
  52. 默认使用 `fast`:4 步、原生音频、640×352。需要更高画质时使用 `balanced`(6 步)或 `quality`(8 步)。
  53. ### Set A 路线对比
  54. 下面六条视频都使用红球滚动场景、同一套提示词、Set A 组件和 `640×352 / 4 步 / 原生音频`,只改变加速节点组合。点击海报打开播放器。
  55. 场景:一颗小型哑光红色橡胶球从画面左侧进入,在灰色混凝土地面上向右滚动并滚出画面。
  56. <table>
  57. <tr>
  58. <td align="center" width="33%">
  59. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-compat">
  60. <img src="docs/gallery/seta-lightx2v-compat.jpg" width="280" alt="Set A LightX2V 兼容基线">
  61. </a><br>
  62. <strong>兼容基线</strong><br>
  63. 640×352 · 5 秒 · 原生音频
  64. </td>
  65. <td align="center" width="33%">
  66. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-sage">
  67. <img src="docs/gallery/seta-lightx2v-sage.jpg" width="280" alt="Set A LightX2V Sage">
  68. </a><br>
  69. <strong>仅 Sage</strong><br>
  70. 640×352 · 5 秒 · 原生音频
  71. </td>
  72. <td align="center" width="33%">
  73. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-ffn">
  74. <img src="docs/gallery/seta-lightx2v-ffn.jpg" width="280" alt="Set A LightX2V FFN">
  75. </a><br>
  76. <strong>仅 FFN</strong><br>
  77. 640×352 · 5 秒 · 原生音频
  78. </td>
  79. </tr>
  80. <tr>
  81. <td align="center" width="33%">
  82. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-blockcache">
  83. <img src="docs/gallery/seta-lightx2v-blockcache.jpg" width="280" alt="Set A LightX2V Block Cache">
  84. </a><br>
  85. <strong>仅 Block Cache</strong><br>
  86. 640×352 · 5 秒 · 原生音频
  87. </td>
  88. <td align="center" width="33%">
  89. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-sol">
  90. <img src="docs/gallery/seta-lightx2v-sol.jpg" width="280" alt="Set A LightX2V Sol">
  91. </a><br>
  92. <strong>仅 Sol</strong><br>
  93. 640×352 · 5 秒 · 原生音频
  94. </td>
  95. <td align="center" width="33%">
  96. <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-all-accel">
  97. <img src="docs/gallery/seta-lightx2v-all-accel.jpg" width="280" alt="Set A LightX2V 全加速">
  98. </a><br>
  99. <strong>全加速</strong><br>
  100. Sage + Sol + FFN + Block Cache
  101. </td>
  102. </tr>
  103. </table>
  104. 展示页使用 GitHub Pages 播放器、`docs/videos/` 中的 MP4 和仓库内海报;[`assets-rolling-redball` Release](https://github.com/Rimagination/h3lite/releases/tag/assets-rolling-redball) 提供这六条路线的下载备份。
  105. ### 常见视频分辨率
  106. 分辨率使用 32 的倍数。不指定时默认 **640×352**;`864×480` 是 16:9、约 0.4 MP 的常用质量档。
  107. | 预设用途 | 实际分辨率 | MP |
  108. |---|---:|---:|
  109. | 6 GB/8 GB 低显存预览 | 608×352 | 0.21 |
  110. | H3 Lite 默认快速路线 | 640×352 | 0.23 |
  111. | 复杂动作实验档 | 736×416 | 0.31 |
  112. | 约 480p、16:9 | 864×480 | 0.41 |
  113. | 约 704p、16:9 | 1216×704 | 0.86 |
  114. | 约 720p、16:9 | 1280×704 | 0.90 |
  115. | 约 768p、16:9 | 1376×768 | 1.06 |
  116. | 约 1080p、16:9 | 1920×1056 | 2.03 |
  117. 高分辨率或多镜头任务先用低分辨率预览,再提升画布。
  118. ## 安装与组件
  119. ### 先确定安装位置
  120. | 方式 | 位置 | 适合情况 |
  121. |---|---|---|
  122. | 复用现有环境 | 已有 `<ComfyUI>` | 保留现有模型和节点 |
  123. | 独立目录 | 如 `F:\MiniMax-H3\ComfyUI` | 推荐,避免占用系统盘或污染项目 |
  124. | 当前项目 | `<项目>\.h3lite\ComfyUI` | 环境随项目保存 |
  125. 下载前先确定 ComfyUI、模型、节点和输出目录。
  126. ### 只选择一套组件
  127. Set A 与 Set B 各自包含匹配的模型、节点、工作流和清单,选择一套即可:
  128. | 组件集 | 已验证起点 | 分享链接 | 提取码 |
  129. |---|---|---|---|
  130. | Set A | RTX 4070 Laptop 8 GB + 32 GB,低显存快速路线 | [百度网盘](https://pan.baidu.com/s/1IBlH0VY7tWGvxqMtniraow) | `4hri` |
  131. | Set B | RTX 4060 Ti 16 GB + 32 GB,FP8 兼容路线;T2VA 也在 RTX 4070 Laptop 8 GB 上验证 | [百度网盘](https://pan.baidu.com/s/1x5GGuJv0h8chApgVoDgIaQ) | `1hjx` |
  132. 将包内 `models` 和 `custom_nodes` 合并到 `<ComfyUI>`,导入工作流 JSON,并保留 `component-manifest.json`。上游文件清单见 [`references/component-sets.md`](references/component-sets.md)。
  133. **Ref2VA 使用同一组件集。** 多图工作流复用 W4A8、文本编码器、ClipProj、双 VAE 和 Turbo LoRA。
  134. ### 手动安装 Skill
  135. 打开仓库页面,选择 **Code → Download ZIP**。解压后把 `h3lite` 文件夹放入 Codex 的 skills 文件夹,再重新打开 Codex。
  136. ## 第一次验证
  137. 安装完成后,先用动作简单、声音明确的 5 秒视频检查整条链路:
  138. ```text
  139. 请使用 H3 Lite,生成一个 5 秒横屏视频:一颗小型哑光红色橡胶球,在灰色混凝土地面上弹跳两次,然后向右滚出画面。低机位固定镜头,阴冷的多云日光,浅景深、35mm 电影质感;保留两次撞击地面的声音和滚动声,不配音乐。
  140. ```
  141. [![H3 Lite 红球弹跳视频封面](docs/gallery/case-red-ball.jpg)](https://rimagination.github.io/h3lite/?video=case-red-ball)
  142. 点击封面打开播放器。
  143. 检查视频、动作、画面运动和原生声音,确认后再提高画布或复杂度。
  144. ## 提示词与案例
  145. 短视频提示词按三部分组织:
  146. 1. **画面与氛围**:主体、环境、光线、景别和风格。
  147. 2. **动作与镜头**:按播放顺序描述动作和运镜。
  148. 3. **声音**:环境声、动作声、音乐或对白。
  149. “不要对白”保留环境声和动作声;“完全静音”才关闭音频。中文提示词补充主体、环境、镜头、光线和动作。
  150. ### 模糊需求的提示词辅助
  151. 模糊需求先补齐主体、动作、运镜和声音;写作模板见 [`references/prompt-assist.md`](references/prompt-assist.md)。
  152. ### 分段提示:金毛幼犬醒来
  153. ```text
  154. 请使用 H3 Lite 生成一个 5 秒视频:
  155. [0s-2s] 一只金毛幼犬蜷缩着睡在洒满阳光的木地板上,晨光透过窗户倾泻而入,尘埃微粒在空气中漂浮。
  156. [2s-5s] 幼犬慢慢醒来,前爪向前伸展,打了个带着细小吱声的哈欠,然后坐起身,用明亮好奇的眼睛环顾四周,尾巴开始摇晃。
  157. ```
  158. [![H3 Lite 金毛幼犬视频封面](docs/gallery/case-golden-retriever.jpg)](https://rimagination.github.io/h3lite/?video=case-golden-retriever)
  159. 点击封面打开播放器。
  160. ### 文生视频:星舰跃迁
  161. 这个 8 秒 T2VA 案例化用自 MiniMax H3 官方可复现案例,适合观察复杂时序、转场和声音设计:
  162. ```text
  163. 请使用 H3 Lite,生成一个 8 秒 16:9 视频:昏暗而宽阔的星舰舰桥内,一位短发女舰长背对镜头站在弧形观察窗前,窗外的深紫色星云中排列着庞大的黑色舰队。镜头先缓慢推近,舰队尾部的蓝色引擎逐渐增强;约 3.5 秒时切到舰长面部特写,舰队突然跃迁,强烈白光淹没舰桥,冲击使镜头剧烈震动,舰长踉跄后重新站稳。白光消退,窗外只剩空旷星云,她缓缓闭上眼睛。保留舰桥低沉嗡鸣、引擎蓄能声、跃迁爆响和金属震动声,配以逐渐增强的太空歌剧管弦乐。
  164. ```
  165. [![H3 Lite 星舰跃迁视频封面](docs/gallery/case-starship-jump.jpg)](https://rimagination.github.io/h3lite/?video=case-starship-jump)
  166. 点击封面打开播放器。
  167. ### 图生视频:恶搞之家式客厅换台
  168. 下载或直接附上[示例首帧](assets/examples/h3lite-i2va-familyguy-first-frame.png),并明确指定它为视频第一帧。这个案例使用原创角色和原创场景,保留美式成人动画的粗黑轮廓、平涂色彩与夸张表情,展示 I2VA 如何在保持人物、服装和客厅构图的同时推进连续动作。
  169. ![H3 Lite I2VA 恶搞之家式客厅示例首帧](assets/examples/h3lite-i2va-familyguy-first-frame.png)
  170. 当前示例:`864×480 · 5 秒 · 8 步 · Set A 兼容路线 · 原生音频`。
  171. ```text
  172. 请使用 H3 Lite,将我在这条消息中附上的图片作为视频 0 秒的第一帧,生成一个 5 秒横屏视频。保持原创美式成人动画风格、四位家庭成员、服装、客厅布局、电视位置、粗黑轮廓、平涂色彩和中广角固定构图。父亲突然前倾,用遥控器对着电视换台;母亲抱臂翻白眼;儿子和女儿转向父亲,露出夸张的不耐烦表情。电视光轻微闪烁,爆米花碗轻轻晃动;结尾父亲得意地指着电视,其他人一起盯着他。保留电视环境声、遥控器按键声、沙发摩擦声、爆米花碗轻响和短促的非语言反应,配轻快的情景喜剧音乐,不要清晰对白。
  173. ```
  174. [![H3 Lite 恶搞之家式客厅 8 步视频封面](assets/examples/h3lite-i2va-familyguy-first-frame.png)](https://rimagination.github.io/h3lite/?video=case-familyguy)
  175. 点击封面打开播放器。
  176. ### Ref2VA:视频与声音参考
  177. 下载 MiniMax 官方案例的[参考视频](assets/examples/minimax-official-ref2va-pink-suit-black-lamb.mp4)和[男声音色参考](assets/examples/minimax-official-ref2va-voice-reference.mp3),分别指定画面、动作、声音和对白的参考来源。
  178. 多镜头任务先用低分辨率跑完整分镜,再提升画布;长任务保留每个镜头的日志。
  179. ### Ref2VA:多张图片参考
  180. 把图片按提示词中的顺序重复附加为 `Picture 1`、`Picture 2`、`Picture 3`。建议一张主图负责人物身份,其余图片分别负责场景、服装/道具或姿势;不要让每张图片都要求“完整复制”。对应的命令形式是:
  181. ```powershell
  182. python scripts/h3_fastpath.py `
  183. --comfyui F:\MiniMax-H3\ComfyUI `
  184. --prompt-file prompts/ref2va.txt `
  185. --ref-image identity.png `
  186. --ref-image scene.png `
  187. --ref-image wardrobe.png `
  188. --mode ref2va `
  189. --resolution 640x352 `
  190. --profile fast `
  191. --json
  192. ```
  193. 当前 Ref2VA 模板使用 ClipProj `resident` 模式,显存占用高于 I2VA。提示词和角色分配见 [`references/prompt-writing.md`](references/prompt-writing.md) 与 [`references/agent-workflow.md`](references/agent-workflow.md)。
  194. 底层 `MiniMaxH3ReferenceToVideo` 也支持参考视频和音频,可通过原生工作流接入。
  195. ## 不打开网页也能看进度
  196. Windows 上运行 fastpath 时会弹出原生进度窗口,显示:
  197. - 显示排队、采样、解码、写入视频等阶段;
  198. - 直接读取 ComfyUI 原生 WebSocket 的步骤和节点进度;
  199. - 同时显示已用时间、预计剩余时间、显存、内存和 pagefile;
  200. - 输出路径和任务状态。
  201. 窗口读取 ComfyUI 的 WebSocket 节点进度,并显示节点阶段、采样步骤、耗时、ETA、显存、内存、pagefile 和输出路径。默认大小 `760×620`,内容区带滚动条。节点完成度是结构进度,ETA 使用实测耗时估计。终端-only 运行加 `--no-monitor-gui`。
  202. 窗口直接连接 ComfyUI,关闭窗口不会中断生成。也可以独立打开:
  203. ```powershell
  204. python scripts/h3_monitor_gui.py `
  205. --comfyui F:\MiniMax-H3\ComfyUI
  206. ```
  207. 没有任务时显示等待状态;`--once --no-websocket` 可用于诊断。
  208. ## 组件完整性与故障排查
  209. H3 Lite 将扩散模型、文本编码器、ClipProj、Turbo LoRA、双 VAE、工作流和节点版本作为一套组件管理。Set B 的关键文件首次使用或发生变化时校验 SHA-256,并缓存结果。
  210. 排查顺序:磁盘/pagefile → 模型和节点 → 模型路径/文件名 → CUDA/PyTorch/custom node → OOM/CPU 卸载 → H3 音视频流程 → 提示词和参考素材。灰屏或马赛克优先检查权重、VAE、sigma-shift 和可选补丁。
  211. ### 同机其他 CUDA 程序抢占显存
  212. ComfyUI 队列清空后仍可能让模型常驻显存;Windows WDDM 驱动下 `nvidia-smi --query-compute-apps` 查不到单进程占用,CUDA 会在“看似空闲”时连几 MiB 的分配都失败,甚至直接访问违例(退出码 0xC0000005)而不是报 OOM。诊断用 `python scripts/h3_vram.py --json` 查看进程显存、WDDM LUID 和适配器范围;不要把不同适配器的 WDDM 计数器直接当成同一张 CUDA 卡的占用。提交脆弱任务前,用 `--check-free-gb <阈值>` 作门禁;范围无法比较时脚本返回 2,只有明确接受全局 `nvidia-smi` 检查时才加 `--allow-scope-mismatch`。确认对方的队列空闲后才能停止它,空队列不等于模型已释放。详见 [references/gpu-contention.md](references/gpu-contention.md)。
  213. ## 视频超分(后处理,Topaz 主推)
  214. 本仓库的低显存 H3 路线已验证约 0.5 MP(960x544),这不是模型或所有硬件的全局上限;需要 1080p/4K 时不要把“放大”交给重新生成——超分是明确的、用户主动请求的后处理步骤,不改变生成图。若本机已安装并授权 Topaz Video AI,可按 GUI 中实际可用的 Starlight/Astra Fast、Proteus 或 Rhea 路线处理;不要假设模型名称、安装目录或授权状态。导出前用 `scripts/h3_vram.py --json` 确认目标适配器范围和显存,再确认 ComfyUI 的 `/queue` 为空;文件名对不代表权重完整。导出后校验视频、音频、帧数和 `videoai=Enhanced using ...` 元数据,不要对已增强视频再次超分。
  215. 备选(可脚本化、离线):只有在本机先发现并验证 FlashVSR 根目录、Python 环境、CLI 分支/提交和模型包后,才使用 `<FlashVSR_ROOT>`。调用时必须传入实际的绝对脚本路径(例如 `<FlashVSR_ROOT>\ComfyUI-FlashVSR_Stable\cli_main.py`),不要在任意工作目录直接运行裸的 `cli_main.py`,也不要把某台机器的启动器或模型清单当成通用依赖。文档中的 `--tile_size 256 --tile_overlap 64 --frame_chunk_size 50 --keep_models_on_cpu` 是一组已测案例参数,不是所有显卡的固定答案;输出不含音轨,需用本机发现的 ffmpeg 从源复制。ComfyUI venv + 4x-UltraSharp 也必须使用实际的 `<ComfyUI>\models\upscale_models\4x-UltraSharp.pth` 和 Python 路径。所有路线跑完都要用 ffprobe 校验 `nb_frames`、尺寸、帧率和音频流,避免把截断输出误判为画质问题。详见 [references/video-upscale.md](references/video-upscale.md)。
  216. ## 参考资料
  217. - [MiniMax H3 ComfyUI 教程](https://docs.comfy.org/tutorials/video/minimax/minimax-h3)
  218. - [MiniMax-H3 官方仓库](https://github.com/MiniMax-AI/MiniMax-H3)
  219. - [H3 prompt-writing skill](https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing)
  220. - [Agent 工作流参考:路由、锚点、提示词增强与验收](references/agent-workflow.md)
  221. - [Higgsfield 公开 Agent Skills(设计参考)](https://github.com/higgsfield-ai/skills)
  222. - [Higgsfield 提示词模板与生成器(提示词辅助)](references/prompt-assist.md)
  223. - [社区 Mac/Metal MLX 移植实录](https://zhuanlan.zhihu.com/p/2069479566171812707)
  224. - [社区 Apple Silicon 本地部署排错实录](https://mp.weixin.qq.com/s/hN60KLN7Pkpqb0pbk-r4WQ)
  225. - [完整组件集与校验值](references/component-sets.md)
  226. - [硬件、分辨率与部署矩阵](references/deployment-matrix.md)
  227. ## License
  228. H3 Lite 使用 MIT License。MiniMax 模型权重、ComfyUI、第三方 custom nodes 和上游资料分别遵循各自许可证。
  229. ## Star History
  230. <p align="center">
  231. <a href="https://www.star-history.com/?repos=Rimagination%2Fh3lite&type=date&legend=top-left">
  232. <img alt="Star History Chart" src="h3lite-star-history-final.png" width="600" />
  233. </a>
  234. </p>
  235. > Interactive/live chart: [Star History](https://www.star-history.com/?repos=Rimagination%2Fh3lite&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.