h3lite
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.
Badge for your README
Markdown
[](/listings/rimagination--h3lite)HTML
<a href="/listings/rimagination--h3lite"><img src="/api/listings/rimagination--h3lite/badge.svg" alt="findsafeskills safety rating" /></a>Install
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)
- ---
- name: h3lite
- 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.
- ---
- # MiniMax H3 Local Video
- 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.
- ## Platform scope and routing
- 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.
- | Platform | h3lite status | Guidance |
- | --- | --- | --- |
- | Windows + NVIDIA CUDA | Primary, locally validated | Use the ComfyUI/H3 Lite fast path and the Windows doctor/planner/preflight scripts. |
- | 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. |
- | macOS Intel | Not recommended | Do not promise local H3 generation; suggest a hosted/API or another backend. |
- | Linux + NVIDIA | Unverified | The model concepts may transfer, but Windows paths, packaged nodes, and timings do not. Require an explicit experimental choice. |
- 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.
- 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.
- ## Agent production workflow
- For complex creative requests, use the compact workflow contract in
- [`references/agent-workflow.md`](references/agent-workflow.md):
- ```text
- intent route → reference/identity anchors → prompt enhancement → execute → verify
- ```
- Route from the user's input and acceptance criteria, not from a style adjective.
- Use `I2VA` for a specified opening frame, `FL2VA`/`L2VA` for endpoint anchors,
- and `Ref2VA` only after its model, text encoder, and workflow are confirmed.
- For recurring characters or multi-shot work, define stable subject/reference
- labels, what must be retained, what may change, and what drift is forbidden
- before writing the timeline. This workflow pattern is local and does not add a
- cloud service, MCP dependency, second model, or second inference pass.
- When a creative brief is vague (for example, it only says “more cinematic”
- or “make it a nice 3D animation”), optionally read
- [`references/prompt-assist.md`](references/prompt-assist.md). It adapts the
- public Higgsfield prompt structure—stable style/identity lock, one clear scene
- action, physical camera motion, audio, and compact anti-drift constraints—to
- H3's native fields. Use it as a writing aid only: do not call Higgsfield, copy
- model-specific flags or capabilities, or let a web lookup change the local
- route, resolution, component set, or verification rules. If a live lookup is
- needed, follow the host `web-access` skill and use public pages only.
- ## Operating rules
- - **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.
- - **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.
- - **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.
- - Inspect before changing anything. Run `scripts/h3_doctor.py --json` and locate the target ComfyUI directory before installing packages, nodes, or weights.
- - 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.
- - Prefer an isolated ComfyUI directory when no installation is supplied. Never overwrite an existing installation or silently replace model files.
- - Keep the deployment path configurable. Do not copy paths from another computer into scripts or workflows.
- - Report required disk space before large downloads. Use resumable downloads and verify file size or hash when a source provides one.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - **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.
- - **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.
- - **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.
- - **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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - Keep agent-facing status compact: omit ComfyUI's full history graph by default; use verbose history only when diagnosing a failure.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- - 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.
- ## Preferred component download source
- For installation or repair, use the maintained Baidu package before assembling
- the set from multiple upstream repositories. Select one complete package after
- the hardware check; do not ask the user to download both sets or mix their
- exclusive files.
- | Default hardware match | Package | Share link | Code |
- | --- | --- | --- | --- |
- | About 8 GB VRAM, low-VRAM fast route | Set A | [Baidu Netdisk](https://pan.baidu.com/s/1IBlH0VY7tWGvxqMtniraow) | `4hri` |
- | 16 GB-class VRAM, FP8 compatibility route | Set B | [Baidu Netdisk](https://pan.baidu.com/s/1x5GGuJv0h8chApgVoDgIaQ) | `1hjx` |
- Guide the user to open the matching link, enter the code, and download the
- whole package. If the `baidu-drive` skill or a Baidu Drive connector is
- available, use it for the download; otherwise give the link and code directly
- and continue after the user places the files locally. Merge the package's
- `models` and
- `custom_nodes` folders into the selected `<ComfyUI>` root, then import or copy
- the packaged workflows and keep `component-manifest.json` with the install.
- Run the doctor after the merge.
- Set A contains the INT4 text encoder and optional low-VRAM acceleration nodes.
- Set B contains the FP8 text encoder and validated compatibility workflows. Both
- packages include their own shared ClipProj and VAE files, so a user only needs
- one link. If the Baidu package is unavailable or the user explicitly requests
- upstream downloads, use the exact sources, filenames, sizes, and hashes in
- `references/component-sets.md`.
- ## Installation target contract
- Before installing, downloading, or moving any component, establish one explicit
- deployment target and state it to the user:
- ```text
- Install mode: reuse-existing | current-project | dedicated-folder
- ComfyUI: <absolute path>
- Models: <ComfyUI>\models
- Custom nodes: <ComfyUI>\custom_nodes
- Output: <ComfyUI>\output
- ```
- Use these rules:
- - `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.
- - `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.
- - `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.
- - 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.
- - 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.
- After the target is selected, read `references/deployment-matrix.md` and present
- the component checklist, exact destination folders, estimated disk budget, and
- the launch command. Install or repair in this order: runtime prerequisites,
- ComfyUI, required custom nodes, model files, doctor verification, then launch.
- Do not start a generation while any required node class or model asset is
- missing.
- ## Adaptive planning contract
- Before generation, separate the user's requirements into four independent
- choices:
- - **Intent:** `fast` (default), `balanced`, or `quality`.
- - **Wall-clock budget:** maximum expected generation time, such as “within 10
- minutes”; this is different from the requested clip duration.
- - **Canvas:** `auto`, landscape/`16:9`, portrait/`9:16`, square/`1:1`, or an
- explicit `WIDTHxHEIGHT`. Keep pixel size as a ComfyUI parameter, not as
- prompt prose. The prompt should describe framing such as landscape
- composition, medium close-up, macro shot, or slow push-in.
- - **Target path:** `reuse-existing`, `current-project`, or `dedicated-folder`.
- Run the planner after the doctor scan. It is read-only and does not create
- folders:
- ```powershell
- python scripts/h3_plan.py `
- --root <hardware-or-disk-root> `
- --comfyui <ComfyUI-path> `
- --install-mode reuse-existing `
- --mode auto `
- --target-minutes 10 `
- --aspect landscape `
- --megapixels 0.4 `
- --video-seconds 5 `
- --json
- ```
- Use the planner result as the source of truth for `--profile`, `--resolution`,
- `--steps`, `--length`, and `--fps`. If no quality or time requirement is
- given, `auto` selects `fast` and preserves the validated 640x352, 4-step,
- Block-Cache route. On an 8 GB laptop, `balanced` keeps 640x352 and increases
- steps while bypassing T8 Block Cache; `quality` does the same with 8 steps.
- Only the mid/high-VRAM plan promotes balanced/quality to an official-style
- ComfyUI bucket by default.
- ComfyUI's native H3 templates commonly use `ResolutionSelector`: aspect ratio
- + target megapixels + a 32-pixel multiple. For example, `16:9`, `0.4 MP`,
- `multiple=32` gives `864x480`. Treat that as the normal official-style H3
- canvas, while H3 Lite's `640x352` remains the low-VRAM fast baseline. If the
- user asks for "official template size", "normal quality", or "0.4MP", use
- `--megapixels 0.4` unless hardware/time preflight blocks it.
- The 32-pixel alignment is a practical model/decoder constraint: the VAE's
- 16-pixel spatial reduction and the DiT's 2-pixel patching must both align. Do
- not advertise consumer labels such as "720p" as exact model sizes when the
- nearest legal canvas is different; report the actual canvas (for example
- `1280x704`) and keep the requested label as a human-friendly preset name.
- For a prompt with several ordered actions, prioritize adherence before pixels.
- Use the fast 640x352 baseline first; 736x416 is an experimental adherence
- bucket between the fast canvas and 0.4 MP. Do not assume 768p follows complex
- shot structure better: community reports describe stronger Ref2VA/keyframe
- adherence around 352p-416p, while extra steps mainly improve coherence and
- detail. Promote 736x416 only after a same-prompt comparison succeeds locally.
- When the user supplies an explicit resolution, treat that canvas choice as
- already confirmed: issue one concise OOM/time warning, then continue unless
- preflight is `blocked`. Do not ask the same resolution question again. If a
- separate wall-clock budget conflicts with the explicit canvas, state the
- conflict once and keep the user's explicit canvas. Never silently trade away
- the audio path or change the installation target to make the estimate fit.
- ## Fast path for ordinary text-to-video
- Use this path for a short H3 clip on a machine that passes the low-VRAM doctor
- check. With no frame arguments it is T2VA; adding `--first-frame` or
- `--last-frame` selects the native reference route automatically:
- ```powershell
- python scripts/h3_fastpath.py `
- --comfyui <ComfyUI-path> `
- --prompt-text "<rewritten H3 prompt>" `
- --resolution 640x352 `
- --video-seconds 5 `
- --filename-prefix video/H3Lite_my_clip `
- --json
- ```
- For image-to-video, pass the reference image directly. The helper stages an
- external image into `<ComfyUI>/input` using a content-addressed filename, then
- connects it to the native `MiniMaxH3ImageToVideo` node. No extra I2V node or
- manual JSON editing is required:
- ```powershell
- python scripts/h3_fastpath.py `
- --comfyui <ComfyUI-path> `
- --mode i2va `
- --first-frame <path-to-first-frame.png> `
- --prompt-text "<rewritten I2VA prompt>" `
- --resolution 640x352 `
- --video-seconds 5 `
- --filename-prefix video/H3Lite_i2va `
- --json
- ```
- Use `--mode fl2va --first-frame <first> --last-frame <last>` for fixed first
- and last images, or `--mode l2va --last-frame <last>` for a last-frame route;
- the helper removes the I2V template's first-frame placeholder automatically in
- the latter case.
- When `--mode auto` is left in place, the mode is inferred from the supplied
- frame arguments. The low-VRAM baseline remains 640x352, 124 frames, 4 steps,
- and native H3 audio. A validated RTX 4070 Laptop 8 GB I2VA run at that
- baseline took about 12 minutes; treat that as local empirical timing, not a
- guarantee.
- 已配置环境的复跑路径就是这一条命令;不要再分别调用 doctor、plan、preflight、generate 和 status。Windows/Git Bash 路径请写 `F:/MiniMax-H3/ComfyUI`,不要写 `/f/MiniMax-H3/ComfyUI`。
- The helper reuses `<ComfyUI>/user/h3lite_runs/_environment/doctor.json` for 30
- minutes, invalidating it only for a cold start, explicit `--force-doctor`, an
- installation change, or failure recovery. It writes the plan and prompt into
- the run root, keeps the native audio path unless the prompt explicitly asks
- for complete silence, and waits with one compact `--watch` monitor. An
- explicit resolution is already confirmed; continue after one concise risk
- warning unless preflight is `blocked`. `--dynamic-check` is on by default;
- use `--skip-dynamic-check` only for an intentionally static clip.
- Hot-path budget rule: spend only the time needed to rewrite the prompt, refresh
- volatile runtime status, submit, watch, and verify. Do not check Git remotes,
- download pages, model hashes, dependency versions, or official docs during a
- normal generation unless the previous command returns a concrete error pointing
- there. If cache is valid, proceed directly to generation.
- ### Native Windows progress window
- On Windows, the fastpath opens the native monitor by default, so every normal
- desktop generation has a visible progress window without an extra flag. Use
- `--no-monitor-gui` for a run that must stay terminal-only; `--monitor-gui`
- explicitly forces it on. The window discovers the fresh H3 run manifest
- automatically. It uses a native Windows Tkinter window, reuses the manifest's
- ComfyUI `client_id`, and listens to the native `/ws`
- channel, including the newer `progress_state` node events, while HTTP polling
- supplies queue state, elapsed/estimated time, GPU memory, RAM, pagefile, output
- path, and failure state. It is monitor-only: closing it does not interrupt
- generation.
- The node count is structural workflow progress, not elapsed-time progress: H3
- nodes have very different runtimes. The window therefore shows node completion
- separately, displays the current node's observed runtime, and keeps ETA on the
- empirical timing estimate instead of treating `4/5` as `80%` of the time. The
- track is segmented by workflow node so completed, active, and pending nodes
- remain visually distinct.
- The default window is `760x620`; its content area has a vertical scrollbar and
- mouse-wheel support for smaller displays or larger system scaling.
- The monitor JSON marks these semantics as `progress_basis` (`node_completion`
- or `sampling_steps`) and `eta_basis` (`empirical` or `live_progress`) so an
- Agent can report them without inventing a time percentage.
- When available, elapsed time comes from the run manifest's measured execution
- time; the wall-clock timestamp is only the fallback before that field exists.
- Old `running` manifests are ignored during automatic discovery; pass
- `--prompt-id` to inspect a specific historical run.
- To open the monitor independently:
- ```powershell
- python scripts/h3_monitor_gui.py `
- --comfyui <ComfyUI-path>
- ```
- Use `--once --no-websocket` for a one-shot JSON diagnostic. If the optional
- WebSocket client is unavailable, the window remains usable through HTTP
- polling, but the progress track stays static and explicitly reports that live
- quantifiable progress is unavailable. It never substitutes an animated bar
- for a measured percentage. An MCP wrapper is unnecessary for this local GUI;
- an Agent can query the same monitor JSON separately when it needs status.
- Use the lower-level `h3_doctor.py`, `h3_plan.py`, `h3_preflight.py`,
- `h3_generate.py`, and `h3_status.py` commands only for installation, recovery,
- custom workflows, or diagnosis. Never replace the fastpath with repeated
- one-shot status commands during a normal generation.
- Use the history/object-info/browser fallback only when the bundled template is
- incompatible, a Ref2VA/custom graph is needed, or the queue reports a missing
- node/model. T2VA, I2VA, FL2VA, and L2VA are now first-class bundled routes.
- ## Workflow
- ### 1. Diagnose the computer
- Run:
- ```powershell
- $environment = '<ComfyUI>\user\h3lite_runs\_environment'
- python scripts/h3_doctor.py `
- --json `
- --report-file "$environment\doctor.json" `
- --root <chosen-root> `
- --comfyui <ComfyUI-path>
- ```
- 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.
- The doctor also records available physical RAM, available Windows pagefile, and
- GPU compute processes. Low available RAM or VRAM is a warning because the
- validated 8 GB route can still finish with offload. A nearly exhausted
- pagefile is different: it previously caused `hostbuf_file_reader_read failed`
- and system-level paging failures, so `h3_preflight.py` blocks that run.
- 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.
- If the user asked for installation or repair, report the selected installation
- target before the doctor result. The doctor is read-only; it does not install
- ComfyUI, nodes, Python packages, or model weights.
- ### 2. Select a profile
- - **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.
- - **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.
- - **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.
- The accelerated fast graph is paired with the registered LightX2V/Turbo 4-step
- LoRA. `minimax_h3_turbo_v4_step600_ema.safetensors` is a compatibility-workflow
- quality variant: H3 Lite rejects it when Sage/Sol/Chunk/T8 acceleration nodes are
- present, because that combination produced severe ghosting and color artifacts in
- local validation. Use a `*_compat_api.json` workflow for v4, or use the registered
- LightX2V/Turbo 4-step LoRA for the fast route.
- - **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.
- - **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.
- 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.
- The planner's `--target-minutes` option chooses the highest-quality mode whose
- conservative upper estimate fits the budget. Without that option, `auto`
- always selects fast. The estimate must include a cold-start warning and the
- final report must include ComfyUI's actual execution time.
- ### 3. Install or repair the environment
- Use the official ComfyUI H3 tutorial and the component list in
- `references/deployment-matrix.md`. Create or reuse the selected ComfyUI root
- and place every component below that root. Pin or record the ComfyUI and
- custom-node commits used for a successful run. Install only nodes referenced by
- the selected workflow. The baseline requires `ComfyUI-ClipProj` or a compatible
- implementation. KJNodes, H3 Turbo helper nodes, Sol Attention, and T8 Block
- Cache are optional unless the selected accelerated graph explicitly uses them.
- `h3_fastpath.py --workflow-template auto` is the default. It queries
- `/object_info` when available and uses the accelerated T2V or I2V graph only
- when the Sage, Sol, Chunk Feed Forward, and T8 classes are actually loaded.
- Pass `--component-set A` or `--component-set B` when both complete sets are
- installed. Set B is validated with the compatibility graph on RTX 4060 Ti
- 16 GB and RTX 4070 Laptop 8 GB systems, so `auto` selects that graph. Its full
- Sage/Sol/Chunk/T8 acceleration chain is not yet the validated default; use
- `--acceleration fast` only for an intentional trial. Use `--acceleration
- compat` to force the validated compatibility graph.
- Both graphs preserve the H3 sampler, native audio, ClipProj, LoRA, dual VAEs,
- and native first/last-frame inputs without optional patches.
- The bundled multi-image Ref2VA graphs reuse this same registered component set:
- there is no separate Ref2VA checkpoint to download. They add the native
- `MiniMaxH3ReferenceToVideo` route and bind repeated reference images through the
- resident ClipProj path. Before downloading anything, reuse the local W4A8,
- 4B encoder, ClipProj, dual VAE, and Turbo LoRA files when their manifest and
- loader checks pass.
- 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.
- 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.
- Cold-path validation is deliberately allowed to spend extra seconds or minutes:
- record component URLs, selected replacement filenames, file sizes or hashes,
- local loader choices, Python import probes, and any small compatibility patch
- that was applied. This is cheaper than discovering a wrong 20 GB model or a
- Torch/custom-node mismatch after queueing. Once the baseline succeeds, write or
- refresh the cached environment/component report and return to the hot path for
- future prompts.
- When public internet is the only source for a large model such as the W4A8
- diffusion checkpoint, do not start a blind long transfer. First probe the
- official raw URL, configured mirror raw URL, and any user-provided proxy URL
- with a small resumable/ranged request. Report the fastest measured speed,
- estimated time, and selected command. Prefer `aria2c` with conservative
- connections when available and the server supports ranges; otherwise use
- `curl.exe -L -C -`. Keep partially downloaded files as `.part` and resume them;
- do not delete progress or restart from byte zero unless the size/hash proves
- the file is unrecoverable.
- Before queueing, run:
- ```powershell
- python scripts/h3_plan.py `
- --doctor-json <ComfyUI>\user\h3lite_runs\_environment\doctor.json `
- --install-mode reuse-existing `
- --comfyui <ComfyUI-path> `
- --mode auto `
- --aspect landscape `
- --video-seconds 5 `
- --report-file <ComfyUI>\user\h3lite_runs\_environment\plan.json `
- --json
- python scripts/h3_preflight.py `
- --doctor-json <ComfyUI>\user\h3lite_runs\_environment\doctor.json `
- --plan-json <ComfyUI>\user\h3lite_runs\_environment\plan.json `
- --refresh-runtime `
- --require-audio `
- --json
- ```
- `ready` means no observed risk, `caution` means the run may proceed with an
- explicit warning, and `blocked` means fix the environment or use another
- backend first. The preflight ignores the Python process used by ComfyUI and
- zero-memory desktop helpers; it warns only for meaningful external GPU
- competitors. This is a runtime gate, not a promise of success.
- ### 4. Rewrite the user's request into an H3 prompt
- Identify the generation mode before writing:
- - text only → `T2VA`
- - one first-frame image → `I2VA`
- - first and last images → `FL2VA`
- - last-frame image → `L2VA`
- - reusable images/video/audio references → `Ref2VA`
- Read `references/prompt-writing.md` when composing or revising a prompt. For
- multi-shot, identity-sensitive, or reference-heavy requests, also read
- `references/agent-workflow.md` and build the route/anchor sheet before writing.
- For an underspecified creative request, also read
- `references/prompt-assist.md`: it supplies the optional
- `STYLE/IDENTITY LOCK → SCENE → MOTION → AUDIO → NEGATIVE` scaffold and the
- rules for translating it back to H3. Ask only for information that materially
- changes the route or acceptance criteria; otherwise state the bounded default
- and continue. Never make a website lookup a runtime dependency.
- Use the exact field names and ordering required by the selected mode. For
- native base modes, the core order is:
- ```text
- integrated_multimodal_description: ...
- overall_soundscape: ...
- non_diegetic_music: ...
- ```
- 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.
- 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.
- Make the prompt operational:
- - establish style, framing, subjects, environment, lighting, and initial state in Shot 1;
- - 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;
- - describe observable actions and state changes in playback order;
- - use later shot cut times only when a real cut introduces new information;
- - write camera motion as a natural sentence with motion type, amplitude, and speed when useful;
- - describe dialogue, singing, and diegetic sound in the timeline body;
- - describe ambient/physical sound in `overall_soundscape` and audience-only music in `non_diegetic_music`;
- - 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.
- - 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`.
- - use stable speaker IDs and exact text for dialogue;
- - use `N/A` for music only when no non-diegetic music is desired, and use `overall_soundscape: N/A` only for explicitly complete silence.
- 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.
- - 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.
- - 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.
- - 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`.
- ### 5. Generate through ComfyUI
- For installation, recovery, or custom-workflow debugging, the lower-level
- helpers remain available. A normal text-only request should use
- `h3_fastpath.py` above:
- ```powershell
- python scripts/h3_generate.py `
- --base-url http://127.0.0.1:8188 `
- --workflow-template h3_w4a8_t2v `
- --prompt-file prompts/current.txt `
- --comfyui <ComfyUI-path> `
- --filename-prefix video/H3Lite_my_clip `
- --run-root <ComfyUI>\user\h3lite_runs `
- --component-set auto `
- --resolve-models `
- --audio-policy auto `
- --profile fast `
- --resolution 640x352 `
- --seed 20260813 `
- --watch `
- --watch-interval 20 `
- --watch-timeout 3600 `
- --json
- ```
- For a lower-level I2VA or FL2VA run, use the matching bundled template and
- frame flags. `--workflow <file>` remains supported for custom Ref2VA or other
- graphs; the same flags will bind any existing `LoadImage` reference input, or
- add one when the H3 node has no connection yet:
- ```powershell
- python scripts/h3_generate.py `
- --workflow-template h3_w4a8_i2v `
- --prompt-text "<rewritten I2VA prompt>" `
- --first-frame <path-to-first-frame.png> `
- --comfyui <ComfyUI-path> `
- --output-dir <ComfyUI>\output `
- --resolution 640x352 `
- --length 124 `
- --steps 4 `
- --component-set auto `
- --resolve-models `
- --watch `
- --json
- ```
- This lower-level command now submits and monitors in the same foreground
- process. Use `--queue-only` only when another process must own monitoring.
- For the bundled multi-image Ref2VA route, repeat `--ref-image` in the order
- that the prompt names `<Picture 1>`, `<Picture 2>`, and so on. The native
- `MiniMaxH3ReferenceToVideo` node accepts image references in fixed order; do
- not combine `--ref-image` with `--first-frame` or `--last-frame`:
- ```powershell
- python scripts/h3_generate.py `
- --workflow-template h3_w4a8_ref2va_compat `
- --prompt-file prompts/ref2va.txt `
- --ref-image <identity.png> `
- --ref-image <scene.png> `
- --ref-image <wardrobe-or-prop.png> `
- --comfyui <ComfyUI-path> `
- --output-dir <ComfyUI>\output `
- --resolution 640x352 `
- --length 124 `
- --steps 4 `
- --component-set A `
- --resolve-models `
- --watch `
- --json
- ```
- The Ref2VA encoder is kept resident because the installed ClipProj node's
- dynamic image path is not reliable with the low-VRAM int8 encoder. Resident
- mode can consume more VRAM than I2VA; preflight may therefore block an 8 GB
- machine or recommend a small preview. Treat `--ref-image` as a real reference
- conditioning input, not as a style-only attachment.
- The native `MiniMaxH3ReferenceToVideo` node also exposes reference-video and
- reference-audio inputs. The bundled fastpath deliberately exposes repeated
- `--ref-image` first because that path is the most predictable to bind and
- verify; use a native/custom workflow when those other reference types are
- required.
- ```powershell
- python scripts/h3_status.py `
- --base-url http://127.0.0.1:8188 `
- --prompt-id <prompt-id> `
- --comfyui <ComfyUI-path> `
- --output-dir <ComfyUI>\output `
- --run-root <ComfyUI>\user\h3lite_runs `
- --require-audio `
- --dynamic-check `
- --anchor-check `
- --compact `
- --json
- ```
- The JSON result is compact by default; use `--verbose` only when a failed run
- needs the full ComfyUI history graph. For a bounded foreground monitor, add
- `--watch --watch-interval 20 --watch-timeout 3600`. A pending response has
- `ok: false` and `complete: false`; only a completed, verified media response
- has `ok: true`.
- 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.
- The accelerated bundled template contains the prompt node, W4A8 model path, 4B
- ClipProj, dual VAE, Turbo LoRA, H3 sigma shifts, Sage/Sol/T8 patches, native
- audio, 124 frames, 640x352, and 4 steps. The compatibility template removes
- the optional Sage/Sol/T8 chain. `--resolve-models` switches the complete
- registered A/B component set atomically; use `--component-set B` when both
- sets are installed. Override `--seed`, `--width`,
- `--height`, `--length`, `--steps`, `--fps`, `--profile`, or `--resolution` only
- when needed. Prefer `--megapixels` for ComfyUI ResolutionSelector-style canvas
- choices such as `16:9 0.4MP -> 864x480`. `fast` keeps Block Cache; `balanced`
- uses 6 steps and bypasses Block Cache; `quality` uses 8 steps and bypasses
- Block Cache. For a custom API
- workflow, pass `--workflow <file>`; the prompt field can still be discovered or
- selected with `--prompt-node` and `--prompt-field`.
- Do not use synchronous wait mode from a terminal command with a short timeout.
- `h3_fastpath.py` uses `h3_generate.py --watch` so submission and verification
- stay in one bounded foreground process; use `--queue-only` only when another
- process must own monitoring.
- 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.
- ### 6. Verify and report
- Do not report success from a queue ID alone. Confirm:
- - the job completed without an execution error;
- - an MP4 or other intended video file exists;
- - the file has a video stream and, for native H3 output, an audio stream;
- - duration, frame count, and FPS are close to the requested values;
- - 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`;
- - when identity, clothing, props, or a reference composition is an acceptance condition, sampled frames preserve the declared anchors and do not silently drift;
- - the output path and elapsed time are reported.
- - the plan's estimated range is compared with the actual ComfyUI execution time;
- - the configuration fingerprint and run manifest are recorded so a retry can be distinguished from an accidental duplicate;
- - the selected ComfyUI, models, custom_nodes, and output paths are recorded.
- If verification returns `ffprobe_not_found`, keep the generated file and repair
- only the verifier path. Set `H3LITE_FFPROBE` to an absolute `ffprobe.exe` when
- the executable lives outside the bounded ComfyUI locations; do not rerun the
- model merely because metadata inspection was unavailable.
- When diagnosing failures, use this order:
- 1. critically low pagefile, unavailable RAM, or another GPU process;
- 2. missing model or custom node;
- 3. wrong model folder or filename;
- 4. CUDA/PyTorch/custom-kernel incompatibility;
- 5. out-of-memory or excessive CPU offload;
- 6. invalid H3 flow/audio graph;
- 7. prompt or reference alignment problem.
- 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.
- ## Video upscale (post-processing)
- Super-resolution is post-processing, not another H3 generation pass: it never
- changes the generation graph, adds sampling steps, or silently follows a run.
- The registered low-VRAM route has been validated around 0.5 MP (for example,
- 960x544), but that is not a model-wide H3 limit. Official/native H3 workflows
- support larger canvases; use the doctor, planner, and preflight result as the
- source of truth for the selected local canvas. Add upscale only when the user
- explicitly asks for a target beyond that selected canvas, and never promise
- pixel-exact consumer labels ("1080p") as model output sizes. Read
- [`references/video-upscale.md`](references/video-upscale.md) for the routes,
- portable path discovery, measured case studies, and the problem table.
- Rules:
- - **Primary route (when actually installed): Topaz Video AI.** The user selects
- the enhancement model (Starlight/Astra Fast for H3-style clips, Proteus/Rhea
- for general footage), the output scale, and exports from the GUI. Do not
- assume a Topaz install, model list, or path copied from another machine.
- Topaz has no stable public CLI contract; log command lines are diagnostic
- evidence only, never a scriptable runtime dependency.
- - **Pre-export checks:** discover the actual Topaz/model roots, inspect free
- VRAM with `scripts/h3_vram.py --json`, and confirm any competitor is idle.
- Treat model presence and SHA-512 catalog checks as machine-local facts; do
- not state that a model is installed or missing without checking this machine.
- - **During export:** do not start another heavy CUDA job (no H3 generation on
- the same card); a 2x Starlight export of a ~210-frame clip takes on the
- order of 20 minutes at 0.3 fps while decoding.
- - **After export:** ffprobe must show the expected size, 24 fps, an audio
- stream, and near-original duration; the `videoai=Enhanced using ...`
- metadata tag marks an already-enhanced file — do not upscale it again.
- - **Fallbacks (scriptable, offline):** use FlashVSR only after discovering
- <FlashVSR_ROOT>, its environment, the exact CLI fork/commit, and the model
- pack. Invoke the script by absolute path, for example
- <FlashVSR_ROOT>\ComfyUI-FlashVSR_Stable\cli_main.py; a bare
- `cli_main.py` depends on the current working directory and is not portable.
- Preserve the validated tiling/chunking settings from the local reference,
- verify frame count and audio after export, and treat truncated output as a
- failed run. If FlashVSR is absent, use the discovered ComfyUI venv plus a
- verified 4x-UltraSharp weight, or plain ffmpeg for previews. Never invent a
- missing wrapper, model, venv, or path.
- ## GPU memory contention with other heavy CUDA apps
- A machine may host several heavy CUDA workloads at once (ComfyUI plus an
- independent video tool, game streaming, another generation backend). Windows
- WDDM reporting hides per-process VRAM: `nvidia-smi --query-compute-apps`
- returns N/A or 0 MiB per process, while PyTorch's free-memory figure stays
- optimistically high. Failures then look like CUDA OOM at tiny allocation sizes
- ("Tried to allocate 28.00 MiB ... 8.91 GiB free") or like a plain access
- violation (Windows exit code 0xC0000005) with no OOM text at all.
- Rules:
- - When preflight flags a meaningful competitor or a fragile job fails at
- allocation, run `python scripts/h3_vram.py --json` to see who holds the
- VRAM. Read the reported process scope and WDDM LUIDs; do not treat a
- process row from an unmapped adapter as proof that it competes for the
- selected CUDA GPU.
- - Confirm the competitor is idle before touching it. For ComfyUI, check
- `http://127.0.0.1:8188/queue` (running + pending empty), and remember an
- empty queue does not release resident models: the process still shows
- several GB until ComfyUI restarts or offloads.
- - Never stop a ComfyUI that has queued or running items; losing a run wastes
- the whole generation.
- - Gate only after the report shows a comparable adapter scope. The
- `--check-free-gb` command fails closed with exit code 2 when the
- scope is unknown; choose the threshold from the selected workload and
- hardware rather than assuming 5 GB. Use `--allow-scope-mismatch`
- only when the user explicitly accepts a global `nvidia-smi`-only
- check.
- - A destructive stop requires `--confirm-stop` and the exact
- `--process-name` from the report. For ComfyUI also pass
- `--queue-url`; the helper refuses to stop when the queue cannot be
- read or is non-empty.
- - Read `references/gpu-contention.md` for the measured case (ComfyUI holding
- 9,805 MB resident on a 16 GB card while a Topaz Video AI Starlight export
- failed at a 28 MiB VAE allocation) and the diagnostic commands.
- ## Bundled resources
- - `references/deployment-matrix.md`: tested low-VRAM profile, official fallback profile, model folders, node roles, launch flags, and failure triage.
- - `references/component-sets.md`: registered model/workflow sets, exact known byte sizes, runtime ABI record, and download-integrity rules.
- - `references/prompt-writing.md`: concise operational digest of MiniMax's official H3 prompt guide and prompt-writing skill.
- - `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).
- - `references/agent-workflow.md`: intent routing, reference/identity anchors, five-pass prompt enhancement, and local capability boundaries.
- - `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.
- - `references/face-quality.md`: face-first routing, official Ref2VA identity controls, low-VRAM trade-offs, and the limits of dynamic/color QA.
- - `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.
- - `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.
- - `assets/h3_w4a8_t2v_api.json`: reusable low-VRAM T2VA API graph based on the validated W4A8/4B/audio route.
- - `assets/h3_w4a8_t2v_compat_api.json`: core T2VA graph without optional Sol Attention, Chunk Feed Forward, or T8 Block Cache nodes.
- - `assets/h3_w4a8_i2v_api.json`: reusable low-VRAM I2VA graph with native first-frame input and optional acceleration patches.
- - `assets/h3_w4a8_i2v_compat_api.json`: core I2VA graph with native first-frame input and no optional acceleration patches.
- - `assets/h3_w4a8_ref2va_api.json`: experimental multi-image Ref2VA graph with the native `MiniMaxH3ReferenceToVideo` node.
- - `assets/h3_w4a8_ref2va_compat_api.json`: compatibility Ref2VA graph without optional Sage/Sol/Chunk/T8 patches.
- - `scripts/h3_doctor.py`: dependency-free hardware, disk, model, and node diagnosis.
- - `scripts/h3_plan.py`: read-only hardware, resolution, time-budget, aspect-ratio, profile, and installation-path planner.
- - `scripts/h3_preflight.py`: read-only pagefile/RAM/VRAM/process/model/node gate before queueing.
- - `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.
- - `scripts/h3_anchor.py`: deterministic prompt/reference anchor-card generation and optional JSON declaration loading; it does not add inference or rewrite the prompt.
- - `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.
- - `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.
- - `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.
- - `scripts/h3_paths.py`: Windows path normalization for `F:/...` and Git Bash `/f/...` inputs.
- - `scripts/h3_cleanup.py`: dry-run-first maintenance for old timestamped run snapshots; preserves environment state and recent runs.
- - `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.
- ## Sources
- - Official H3 prompt guide: <https://huggingface.co/MiniMaxAI/MiniMax-H3/blob/main/docs/VIDEO_PROMPT_WRITING_GUIDE_base_en.md>
- - Official H3 prompt-writing skill: <https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing>
- - Official ComfyUI H3 tutorial: <https://docs.comfy.org/tutorials/video/minimax/minimax-h3>
- - H3 Turbo ComfyUI nodes: <https://github.com/Larryvrh/ComfyUI-MiniMax-H3-Turbo>
- - Cinema DNA 21:9 × 3: <https://github.com/dacnay816y62-hub/cinema-dna-21x9x3>
- - Official H3 repository and prompting guidance: <https://github.com/MiniMax-AI/MiniMax-H3>
- - Public agent-workflow design reference (not a runtime dependency): <https://github.com/higgsfield-ai/skills>
- - 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>
- - Community Mac/Metal MLX port and operational notes (reference only; not a tested h3lite backend): <https://zhuanlan.zhihu.com/p/2069479566171812707>
- - 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)
- # H3 Lite
- <p align="center">
- <img src="assets/h3-lite-hero.gif" alt="H3 Lite — MiniMax H3 本地部署与视频生成 Skill" width="100%">
- </p>
- <p align="center">
- <img alt="License MIT" src="https://img.shields.io/badge/License-MIT-1F5E4A?style=for-the-badge">
- <img alt="Hosts Codex" src="https://img.shields.io/badge/Hosts-Codex-4B6B8A?style=for-the-badge">
- <img alt="Route Low VRAM Fast" src="https://img.shields.io/badge/Route-Low--VRAM%20Fast-D9A441?style=for-the-badge">
- </p>
- <p align="center">中文 | <a href="README.en.md">English</a> | <a href="#参考资料">参考资料</a></p>
- `H3 Lite` 是给 Codex、WorkBuddy 等 AI Agent 使用的 MiniMax H3 本地视频生成 Skill。描述想看的画面后,Agent 会根据电脑配置选择 ComfyUI 路线、准备组件、生成带原生声音的视频并检查结果。
- ## 模型定位与适用范围
- H3 Lite 面向 Windows + NVIDIA + ComfyUI 的低显存本地视频生成。Set A 使用 W4A8 扩散模型和 4B INT4 文本编码器,Set B 使用 4B FP8 文本编码器;两套组件分别对应低显存快速路线和 FP8 兼容路线。
- 当前已验证的主路线是 **Windows + NVIDIA + ComfyUI**:
- | 平台 | 支持状态 | 指导 |
- |---|---|---|
- | Windows + NVIDIA | 主支持路线 | 使用本仓库的 ComfyUI、doctor、planner 和 fastpath。 |
- | macOS Apple Silicon | 社区路线 | 可参考 MLX/Metal 的 `mmh3turbo`。 |
- | macOS Intel | 未验证 | 使用托管/API 或其他后端。 |
- | Linux + NVIDIA | 实验路线 | 需自行适配路径、节点和运行参数。 |
- Mac 社区路线可参考[社区权重包](https://huggingface.co/yunfengwang/mmh3turbo-bundles)和 `uvx mmh3turbo`,与本 Skill 的 ComfyUI 组件分开使用。
- ## 从需求到成片:四步工作流
- 复杂视频按“**意图路由 → 参考图锚点 → 提示词增强 → 生成与验收**”处理。
- | 你的目标 | 优先路线 | 关键做法 |
- |---|---|---|
- | 纯文字描述完整视频 | `T2VA` | 先写开场状态,再按时间顺序写动作、镜头和声音。 |
- | 指定视频第一帧 | `I2VA` | 把参考图锁定在 `0.00s`,只描述后续变化。 |
- | 指定首尾画面 | `FL2VA` | 描述两个锚点之间连续、可见的变化。 |
- | 多张图/视频/音频参考 | `Ref2VA` | 先定义每份素材的角色、保留项和可变项,再写分镜。 |
- 人物或多镜头任务先建立锚点卡,固定角色、服装、道具、场景和光线,并为参考素材使用稳定名称,如 `Subject A`、`Picture 1`。若 Ref2VA 组件不完整,Agent 会改用 I2VA 或标记为实验路线。
- 运行时会把锚点卡保存为 `anchors.json`,并在 `manifest.json` 记录路径。`anchor_qa` 用首/中/尾帧检查画面连续性,身份、服饰和构图仍需人工复核。
- 提示词按“意图 → 场景与角色 → 动作与分镜 → 运镜与声音 → 防漂移约束”增强,最后转换为 H3 的 `integrated_multimodal_description`、`overall_soundscape`、`non_diegetic_music` 字段。
- 模糊需求可参考 [`references/prompt-assist.md`](references/prompt-assist.md) 补齐场景、动作、运镜和声音。
- ## 快速开始
- 把下面这句话发给 Codex 或 WorkBuddy:
- ```text
- 请帮我安装 H3 Lite,并根据我的电脑配置准备本地 MiniMax H3 视频生成环境:
- https://github.com/Rimagination/h3lite
- ```
- 如果不想占用系统盘,把目标位置写进同一条消息:
- ```text
- 请把 MiniMax H3 和 ComfyUI 安装到 F:\MiniMax-H3;如果那里已经有健康环境就直接复用。
- ```
- 首次安装时间取决于模型大小、网络和硬盘速度。
- ## 硬件与路线选择
- 主支持配置为 Windows + NVIDIA。显存、系统内存、pagefile、磁盘和笔记本功耗都会影响速度。
- | 已验证电脑 | GPU | 内存 | 路线 |
- |---|---|---|---|
- | 机械革命翼龙 15 Pro | RTX 4070 Laptop 8 GB | Ryzen 7 8845H / 32 GB | `LOW_VRAM`;Set A T2VA/I2VA,Set B 兼容 T2VA |
- | Windows 10 台式机 | RTX 4060 Ti 16 GB | i5-13400F / 32 GB | Set B;`NORMAL_VRAM`;T2VA/I2VA |
- 同一套 Set B、兼容工作流、提示词、seed 和 `640×352 / 4 步` 参数下,RTX 4060 Ti 16 GB 约 77.08 秒,RTX 4070 Laptop 8 GB 约 591.22 秒。
- 默认使用 `fast`:4 步、原生音频、640×352。需要更高画质时使用 `balanced`(6 步)或 `quality`(8 步)。
- ### Set A 路线对比
- 下面六条视频都使用红球滚动场景、同一套提示词、Set A 组件和 `640×352 / 4 步 / 原生音频`,只改变加速节点组合。点击海报打开播放器。
- 场景:一颗小型哑光红色橡胶球从画面左侧进入,在灰色混凝土地面上向右滚动并滚出画面。
- <table>
- <tr>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-compat">
- <img src="docs/gallery/seta-lightx2v-compat.jpg" width="280" alt="Set A LightX2V 兼容基线">
- </a><br>
- <strong>兼容基线</strong><br>
- 640×352 · 5 秒 · 原生音频
- </td>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-sage">
- <img src="docs/gallery/seta-lightx2v-sage.jpg" width="280" alt="Set A LightX2V Sage">
- </a><br>
- <strong>仅 Sage</strong><br>
- 640×352 · 5 秒 · 原生音频
- </td>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-ffn">
- <img src="docs/gallery/seta-lightx2v-ffn.jpg" width="280" alt="Set A LightX2V FFN">
- </a><br>
- <strong>仅 FFN</strong><br>
- 640×352 · 5 秒 · 原生音频
- </td>
- </tr>
- <tr>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-blockcache">
- <img src="docs/gallery/seta-lightx2v-blockcache.jpg" width="280" alt="Set A LightX2V Block Cache">
- </a><br>
- <strong>仅 Block Cache</strong><br>
- 640×352 · 5 秒 · 原生音频
- </td>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-sol">
- <img src="docs/gallery/seta-lightx2v-sol.jpg" width="280" alt="Set A LightX2V Sol">
- </a><br>
- <strong>仅 Sol</strong><br>
- 640×352 · 5 秒 · 原生音频
- </td>
- <td align="center" width="33%">
- <a href="https://rimagination.github.io/h3lite/?video=seta-lightx2v-all-accel">
- <img src="docs/gallery/seta-lightx2v-all-accel.jpg" width="280" alt="Set A LightX2V 全加速">
- </a><br>
- <strong>全加速</strong><br>
- Sage + Sol + FFN + Block Cache
- </td>
- </tr>
- </table>
- 展示页使用 GitHub Pages 播放器、`docs/videos/` 中的 MP4 和仓库内海报;[`assets-rolling-redball` Release](https://github.com/Rimagination/h3lite/releases/tag/assets-rolling-redball) 提供这六条路线的下载备份。
- ### 常见视频分辨率
- 分辨率使用 32 的倍数。不指定时默认 **640×352**;`864×480` 是 16:9、约 0.4 MP 的常用质量档。
- | 预设用途 | 实际分辨率 | MP |
- |---|---:|---:|
- | 6 GB/8 GB 低显存预览 | 608×352 | 0.21 |
- | H3 Lite 默认快速路线 | 640×352 | 0.23 |
- | 复杂动作实验档 | 736×416 | 0.31 |
- | 约 480p、16:9 | 864×480 | 0.41 |
- | 约 704p、16:9 | 1216×704 | 0.86 |
- | 约 720p、16:9 | 1280×704 | 0.90 |
- | 约 768p、16:9 | 1376×768 | 1.06 |
- | 约 1080p、16:9 | 1920×1056 | 2.03 |
- 高分辨率或多镜头任务先用低分辨率预览,再提升画布。
- ## 安装与组件
- ### 先确定安装位置
- | 方式 | 位置 | 适合情况 |
- |---|---|---|
- | 复用现有环境 | 已有 `<ComfyUI>` | 保留现有模型和节点 |
- | 独立目录 | 如 `F:\MiniMax-H3\ComfyUI` | 推荐,避免占用系统盘或污染项目 |
- | 当前项目 | `<项目>\.h3lite\ComfyUI` | 环境随项目保存 |
- 下载前先确定 ComfyUI、模型、节点和输出目录。
- ### 只选择一套组件
- Set A 与 Set B 各自包含匹配的模型、节点、工作流和清单,选择一套即可:
- | 组件集 | 已验证起点 | 分享链接 | 提取码 |
- |---|---|---|---|
- | Set A | RTX 4070 Laptop 8 GB + 32 GB,低显存快速路线 | [百度网盘](https://pan.baidu.com/s/1IBlH0VY7tWGvxqMtniraow) | `4hri` |
- | Set B | RTX 4060 Ti 16 GB + 32 GB,FP8 兼容路线;T2VA 也在 RTX 4070 Laptop 8 GB 上验证 | [百度网盘](https://pan.baidu.com/s/1x5GGuJv0h8chApgVoDgIaQ) | `1hjx` |
- 将包内 `models` 和 `custom_nodes` 合并到 `<ComfyUI>`,导入工作流 JSON,并保留 `component-manifest.json`。上游文件清单见 [`references/component-sets.md`](references/component-sets.md)。
- **Ref2VA 使用同一组件集。** 多图工作流复用 W4A8、文本编码器、ClipProj、双 VAE 和 Turbo LoRA。
- ### 手动安装 Skill
- 打开仓库页面,选择 **Code → Download ZIP**。解压后把 `h3lite` 文件夹放入 Codex 的 skills 文件夹,再重新打开 Codex。
- ## 第一次验证
- 安装完成后,先用动作简单、声音明确的 5 秒视频检查整条链路:
- ```text
- 请使用 H3 Lite,生成一个 5 秒横屏视频:一颗小型哑光红色橡胶球,在灰色混凝土地面上弹跳两次,然后向右滚出画面。低机位固定镜头,阴冷的多云日光,浅景深、35mm 电影质感;保留两次撞击地面的声音和滚动声,不配音乐。
- ```
- [](https://rimagination.github.io/h3lite/?video=case-red-ball)
- 点击封面打开播放器。
- 检查视频、动作、画面运动和原生声音,确认后再提高画布或复杂度。
- ## 提示词与案例
- 短视频提示词按三部分组织:
- 1. **画面与氛围**:主体、环境、光线、景别和风格。
- 2. **动作与镜头**:按播放顺序描述动作和运镜。
- 3. **声音**:环境声、动作声、音乐或对白。
- “不要对白”保留环境声和动作声;“完全静音”才关闭音频。中文提示词补充主体、环境、镜头、光线和动作。
- ### 模糊需求的提示词辅助
- 模糊需求先补齐主体、动作、运镜和声音;写作模板见 [`references/prompt-assist.md`](references/prompt-assist.md)。
- ### 分段提示:金毛幼犬醒来
- ```text
- 请使用 H3 Lite 生成一个 5 秒视频:
- [0s-2s] 一只金毛幼犬蜷缩着睡在洒满阳光的木地板上,晨光透过窗户倾泻而入,尘埃微粒在空气中漂浮。
- [2s-5s] 幼犬慢慢醒来,前爪向前伸展,打了个带着细小吱声的哈欠,然后坐起身,用明亮好奇的眼睛环顾四周,尾巴开始摇晃。
- ```
- [](https://rimagination.github.io/h3lite/?video=case-golden-retriever)
- 点击封面打开播放器。
- ### 文生视频:星舰跃迁
- 这个 8 秒 T2VA 案例化用自 MiniMax H3 官方可复现案例,适合观察复杂时序、转场和声音设计:
- ```text
- 请使用 H3 Lite,生成一个 8 秒 16:9 视频:昏暗而宽阔的星舰舰桥内,一位短发女舰长背对镜头站在弧形观察窗前,窗外的深紫色星云中排列着庞大的黑色舰队。镜头先缓慢推近,舰队尾部的蓝色引擎逐渐增强;约 3.5 秒时切到舰长面部特写,舰队突然跃迁,强烈白光淹没舰桥,冲击使镜头剧烈震动,舰长踉跄后重新站稳。白光消退,窗外只剩空旷星云,她缓缓闭上眼睛。保留舰桥低沉嗡鸣、引擎蓄能声、跃迁爆响和金属震动声,配以逐渐增强的太空歌剧管弦乐。
- ```
- [](https://rimagination.github.io/h3lite/?video=case-starship-jump)
- 点击封面打开播放器。
- ### 图生视频:恶搞之家式客厅换台
- 下载或直接附上[示例首帧](assets/examples/h3lite-i2va-familyguy-first-frame.png),并明确指定它为视频第一帧。这个案例使用原创角色和原创场景,保留美式成人动画的粗黑轮廓、平涂色彩与夸张表情,展示 I2VA 如何在保持人物、服装和客厅构图的同时推进连续动作。
- 
- 当前示例:`864×480 · 5 秒 · 8 步 · Set A 兼容路线 · 原生音频`。
- ```text
- 请使用 H3 Lite,将我在这条消息中附上的图片作为视频 0 秒的第一帧,生成一个 5 秒横屏视频。保持原创美式成人动画风格、四位家庭成员、服装、客厅布局、电视位置、粗黑轮廓、平涂色彩和中广角固定构图。父亲突然前倾,用遥控器对着电视换台;母亲抱臂翻白眼;儿子和女儿转向父亲,露出夸张的不耐烦表情。电视光轻微闪烁,爆米花碗轻轻晃动;结尾父亲得意地指着电视,其他人一起盯着他。保留电视环境声、遥控器按键声、沙发摩擦声、爆米花碗轻响和短促的非语言反应,配轻快的情景喜剧音乐,不要清晰对白。
- ```
- [](https://rimagination.github.io/h3lite/?video=case-familyguy)
- 点击封面打开播放器。
- ### Ref2VA:视频与声音参考
- 下载 MiniMax 官方案例的[参考视频](assets/examples/minimax-official-ref2va-pink-suit-black-lamb.mp4)和[男声音色参考](assets/examples/minimax-official-ref2va-voice-reference.mp3),分别指定画面、动作、声音和对白的参考来源。
- 多镜头任务先用低分辨率跑完整分镜,再提升画布;长任务保留每个镜头的日志。
- ### Ref2VA:多张图片参考
- 把图片按提示词中的顺序重复附加为 `Picture 1`、`Picture 2`、`Picture 3`。建议一张主图负责人物身份,其余图片分别负责场景、服装/道具或姿势;不要让每张图片都要求“完整复制”。对应的命令形式是:
- ```powershell
- python scripts/h3_fastpath.py `
- --comfyui F:\MiniMax-H3\ComfyUI `
- --prompt-file prompts/ref2va.txt `
- --ref-image identity.png `
- --ref-image scene.png `
- --ref-image wardrobe.png `
- --mode ref2va `
- --resolution 640x352 `
- --profile fast `
- --json
- ```
- 当前 Ref2VA 模板使用 ClipProj `resident` 模式,显存占用高于 I2VA。提示词和角色分配见 [`references/prompt-writing.md`](references/prompt-writing.md) 与 [`references/agent-workflow.md`](references/agent-workflow.md)。
- 底层 `MiniMaxH3ReferenceToVideo` 也支持参考视频和音频,可通过原生工作流接入。
- ## 不打开网页也能看进度
- Windows 上运行 fastpath 时会弹出原生进度窗口,显示:
- - 显示排队、采样、解码、写入视频等阶段;
- - 直接读取 ComfyUI 原生 WebSocket 的步骤和节点进度;
- - 同时显示已用时间、预计剩余时间、显存、内存和 pagefile;
- - 输出路径和任务状态。
- 窗口读取 ComfyUI 的 WebSocket 节点进度,并显示节点阶段、采样步骤、耗时、ETA、显存、内存、pagefile 和输出路径。默认大小 `760×620`,内容区带滚动条。节点完成度是结构进度,ETA 使用实测耗时估计。终端-only 运行加 `--no-monitor-gui`。
- 窗口直接连接 ComfyUI,关闭窗口不会中断生成。也可以独立打开:
- ```powershell
- python scripts/h3_monitor_gui.py `
- --comfyui F:\MiniMax-H3\ComfyUI
- ```
- 没有任务时显示等待状态;`--once --no-websocket` 可用于诊断。
- ## 组件完整性与故障排查
- H3 Lite 将扩散模型、文本编码器、ClipProj、Turbo LoRA、双 VAE、工作流和节点版本作为一套组件管理。Set B 的关键文件首次使用或发生变化时校验 SHA-256,并缓存结果。
- 排查顺序:磁盘/pagefile → 模型和节点 → 模型路径/文件名 → CUDA/PyTorch/custom node → OOM/CPU 卸载 → H3 音视频流程 → 提示词和参考素材。灰屏或马赛克优先检查权重、VAE、sigma-shift 和可选补丁。
- ### 同机其他 CUDA 程序抢占显存
- 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)。
- ## 视频超分(后处理,Topaz 主推)
- 本仓库的低显存 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 ...` 元数据,不要对已增强视频再次超分。
- 备选(可脚本化、离线):只有在本机先发现并验证 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)。
- ## 参考资料
- - [MiniMax H3 ComfyUI 教程](https://docs.comfy.org/tutorials/video/minimax/minimax-h3)
- - [MiniMax-H3 官方仓库](https://github.com/MiniMax-AI/MiniMax-H3)
- - [H3 prompt-writing skill](https://github.com/MiniMax-AI/MiniMax-H3/tree/main/skills/h3-prompt-writing)
- - [Agent 工作流参考:路由、锚点、提示词增强与验收](references/agent-workflow.md)
- - [Higgsfield 公开 Agent Skills(设计参考)](https://github.com/higgsfield-ai/skills)
- - [Higgsfield 提示词模板与生成器(提示词辅助)](references/prompt-assist.md)
- - [社区 Mac/Metal MLX 移植实录](https://zhuanlan.zhihu.com/p/2069479566171812707)
- - [社区 Apple Silicon 本地部署排错实录](https://mp.weixin.qq.com/s/hN60KLN7Pkpqb0pbk-r4WQ)
- - [完整组件集与校验值](references/component-sets.md)
- - [硬件、分辨率与部署矩阵](references/deployment-matrix.md)
- ## License
- H3 Lite 使用 MIT License。MiniMax 模型权重、ComfyUI、第三方 custom nodes 和上游资料分别遵循各自许可证。
- ## Star History
- <p align="center">
- <a href="https://www.star-history.com/?repos=Rimagination%2Fh3lite&type=date&legend=top-left">
- <img alt="Star History Chart" src="h3lite-star-history-final.png" width="600" />
- </a>
- </p>
- > 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 inFree to use. If it’s helped, pass it on.