217 lines
10 KiB
Markdown
217 lines
10 KiB
Markdown
# DumasNodes
|
||
|
||
## Vendored MiniMax H3 packs
|
||
|
||
DumasNodes contains complete, license-preserving source copies of the three
|
||
upstream packs used by the MiniMax H3 workflow:
|
||
|
||
- `vendor/dumas_h3_continuum/`
|
||
- `vendor/dumas_minimax_h3_refmod/`
|
||
- `vendor/dumas_h3_refmod_picker/`
|
||
|
||
Their registrations and browser extensions are loaded by DUMAS. Every vendored
|
||
node is registered with a stable DUMAS-prefixed ID and under a DUMAS category:
|
||
|
||
- `DumasH3Continuum_*` → `Dumas/MiniMax H3/Continuum`
|
||
- `DumasMiniMaxH3RefMod_*` → `Dumas/MiniMax H3/RefMod`
|
||
- `DumasH3RefModPicker_*` → `Dumas/MiniMax H3/RefMod Picker`
|
||
|
||
This prevents the vendored nodes from replacing or colliding with an upstream
|
||
node of the same name. Existing workflows that use the upstream IDs are not
|
||
silently rewritten; they must continue to use the upstream pack or be
|
||
reconnected to the DUMAS nodes. The original packs should still not be loaded
|
||
alongside this copy because their server routes can overlap even though the
|
||
node IDs are now isolated.
|
||
|
||
The upstream source is imported as git subtrees, making future reviews and
|
||
selective updates possible without losing provenance. DUMAS-specific changes
|
||
belong outside `vendor/` unless an upstream implementation is intentionally
|
||
being amended.
|
||
|
||
Generic ComfyUI utility nodes under the Dumas brand. MiniMax H3-specific
|
||
nodes are grouped under `Dumas/MiniMax H3/...` so they can be installed
|
||
as the self-contained H3 installation; do not install the separate upstream
|
||
packs alongside this vendored copy.
|
||
|
||
## Sequential video assembly
|
||
|
||
### Dumas Standalone Video
|
||
|
||
`DumasStandaloneVideo` saves both the complete generated clip and a full copy.
|
||
For a continuation clip, set `reference_frames` to the number of frames taken
|
||
from the previous clip for continuity. The value is returned as the final
|
||
`reference_frames` output so it can be wired directly into
|
||
`DumasJoinVideoClips`.
|
||
|
||
### Dumas Join Video Clips (No Re-encode)
|
||
|
||
`DumasJoinVideoClips` accepts one reference-frame input for each clip. It trims
|
||
that many frames from the beginning of any clip whose value is greater than
|
||
zero, then concatenates the resulting files with FFmpeg stream copy. This
|
||
avoids a full re-encode of the assembled video. Clip 1 normally remains at
|
||
zero; continuation clips receive the reference-frame output from their
|
||
standalone nodes.
|
||
|
||
Stream-copy trimming is codec/keyframe-aware: the requested boundary is
|
||
converted using the clip's frame rate, but a codec may choose the nearest safe
|
||
packet boundary. For exact frame cuts, use the existing `complete_clip` output
|
||
or accept a re-encoded workflow.
|
||
|
||
## Project rendering
|
||
|
||
## MiniMax H3 tiled latent upscale
|
||
|
||
`DumasMMH3TiledLatentUpscale` is a thin integration node for the native
|
||
`MMH3UltimateUpscale` node used by the MiniMax-H3 workflow. It accepts the
|
||
native H3 latent-upscale, temporal-split, and spatial-split parameter objects,
|
||
but creates a separate upscale sampler, scheduler, sigma schedule, noise seed,
|
||
denoise value, steps value, and CFG value. The base H3 sampling pass is not
|
||
changed.
|
||
|
||
Typical wiring:
|
||
|
||
```text
|
||
base H3 latent + model + conditioning
|
||
-> Dumas MiniMax-H3 Tiled Latent Upscale
|
||
H3 Latent Upscale Params --------------------^
|
||
H3 Temporal Split Params ---------------------^
|
||
H3 Spatial Split Params -----------------------^
|
||
```
|
||
|
||
The node requires the ComfyUI installation to provide `MMH3UltimateUpscale`,
|
||
`RandomNoise`, `KSamplerSelect`, and `BasicScheduler`. It does not copy or
|
||
redistribute the third-party H3 LongVideos implementation. The native node's
|
||
current socket types are `H3_UPSCALE_PARAM`, `H3_TEMPORAL_PARAM`, and
|
||
`H3_SPATIAL_PARAM`; these are deliberately used unchanged for workflow
|
||
compatibility.
|
||
|
||
### DUMAS H3 Sequence Prompt Builder
|
||
|
||
`DumasH3SequencePromptBuilder` provides the tabbed, timeline-oriented prompt
|
||
editor used for multi-chunk H3 jobs. It emits one absolute sequence prompt,
|
||
the chunk count, the shared chunk duration, and a per-chunk reference bundle.
|
||
Reference images are inserted as `@R1` through `@R9`; routing is based on the
|
||
shared directive, soundscape, music, and each chunk's full prompt text.
|
||
|
||
The builder also accepts an optional `H3_REF_MODS` input. Visual RefMods are
|
||
assigned after any connected image-reference slots, automatically described in
|
||
the generated shared directive, and emitted together with their slot offset.
|
||
Connect those two outputs to `DUMAS H3 RefMods to Continuum` so the bridge can
|
||
merge RefMods and ordinary image references into one Continuum bundle.
|
||
|
||
The prompt builder intentionally uses the `ReferenceImagesV39Bundle` class
|
||
from the installed upstream H3 Continuum pack. Install that pack alongside
|
||
DumasNodes; DumasNodes does not copy or replace the upstream reference-image
|
||
implementation.
|
||
|
||
### DUMAS H3 RefMod Save
|
||
|
||
`DUMAS H3 RefMod Save` accepts the `H3_REF_MODS` bundle produced by the
|
||
MiniMax H3 RefMod nodes and adds explicit DUMAS-owned storage policy:
|
||
|
||
- `Registered RefMods` is the default and saves to ComfyUI's first registered
|
||
`refmods` root, preserving normal loader discovery.
|
||
- `Input folder` saves beside a server-side source folder supplied through the
|
||
`input_folder` socket. Standard IMAGE/VIDEO tensors do not contain their
|
||
original filesystem path, so this path must be supplied explicitly.
|
||
- `Custom folder` saves to an explicitly supplied server-side folder.
|
||
- `Increment filename` is the default collision policy; `Replace` and `Fail`
|
||
are also available.
|
||
|
||
All writes use the RefMod object's atomic save operation. The node reports the
|
||
resolved `.safetensors` paths through `saved_paths`. External folders are not
|
||
automatically persistent across restarts, but they are registered as RefMod
|
||
roots for the current ComfyUI process so the DUMAS picker can discover them.
|
||
For persistence across restarts, add the folder to ComfyUI's `refmods` mapping
|
||
in `extra_model_paths.yaml`.
|
||
|
||
### DUMAS H3 RefMod Visual Picker
|
||
|
||
`DUMAS H3 RefMod Visual Picker` provides a small browser button for selecting
|
||
registered RefMod `.safetensors` files. It supports the maintained upstream
|
||
loader's standalone and bundle formats, including embedded visual/audio
|
||
members, and appends the selected rows to an optional existing `H3_REF_MODS`
|
||
bundle. Video and audio weights are independent, and values above 1 repeat a
|
||
reference as additional weighted rows, matching the companion add-on's
|
||
behaviour. The picker shows matching preview images when present.
|
||
|
||
The maintained MiniMax H3 RefMod reader must be installed alongside DUMAS;
|
||
DUMAS does not duplicate that reader or override its node IDs.
|
||
|
||
The vendored `DUMAS H3 Continuum · H3 Continuum Sampler V3.9` also exposes an
|
||
optional `RefMods (Optional)` socket. Connect the `H3_REF_MODS` output from a
|
||
RefMod loader or creator directly to that socket; the sampler clones the model
|
||
and attaches the RefMod bridge only for that run. `RefMod Retention` and
|
||
`RefMod Token Budget` are available beside the socket, while ordinary image
|
||
reference routing remains unchanged. The separate model bridge node is still
|
||
available for V3.8 and other samplers.
|
||
|
||
### DUMAS H3 RefMods to Continuum
|
||
|
||
`DUMAS H3 RefMods to Continuum` is the minimal compatibility bridge for the
|
||
upstream Continuum sampler. It decodes one visual frame from each selected
|
||
RefMod with the H3 video VAE and emits Continuum's native nine-slot V3.9
|
||
Reference Images bundle. Continuum then performs its normal resize, VAE encode,
|
||
prompt presentation, and physical-group routing.
|
||
|
||
Connect the sequence prompt and choose `Prompt @R tags` to route each RefMod
|
||
only to chunks whose prompt section contains its `@R1`–`@R9` tag. Choose `All
|
||
chunks` to provide every decoded visual reference to every chunk. Audio-only
|
||
RefMods are skipped because Continuum's image-reference socket is visual-only.
|
||
The native image bundle has no per-reference strength field, so picker weights
|
||
are intentionally not carried across this compatibility boundary.
|
||
|
||
This bridge intentionally avoids patching Continuum's internal conditioning
|
||
runtime. Direct latent injection would need to alter its per-group reference
|
||
contracts, storage fingerprints, and prompt-picture mapping, and would be a
|
||
much larger and more fragile fork. The trade-off is one decode followed by
|
||
Continuum's normal reference encode; pooled/training RefMods will therefore
|
||
retain only the visual information present in their stored latent.
|
||
|
||
### DUMAS H3 Continuum Tiled Latent Upscale (Per Clip)
|
||
|
||
`DumasH3ContinuumTiledLatentUpscalePerClip` is a replacement for the upstream
|
||
Second Pass when tiled latent upscale is required. It applies the native H3
|
||
tiled upscale independently to each physical Continuum clip, passes the
|
||
first-pass audio latents through unchanged, and returns the updated assembly
|
||
plan plus status. It accepts the Continuum `refine_context` and uses the
|
||
upstream refine bridge when no direct conditioning is connected. Its sampler,
|
||
scheduler, sigma input, steps, denoise, CFG, and noise seed are separate from
|
||
the base generation pass. Connected sockets take precedence over node
|
||
defaults. The node preserves one LATENT list item per physical clip to avoid
|
||
concatenating a long sequence into one oversized VRAM allocation.
|
||
|
||
The CSGlide `Render Project` control is the generation orchestrator: it renders
|
||
clips sequentially, adopts each completed render, extracts the previous clip's
|
||
tail, fills the next clip's `CONTINUE FROM` guide, and waits before advancing.
|
||
DumasNodes intentionally remains model-agnostic and handles clean individual
|
||
outputs, tail preparation and optional final assembly rather than duplicating
|
||
CSGlide's MiniMax generation loop.
|
||
|
||
### Dumas Prepare Continuation
|
||
|
||
Give this node the raw output of a continuation generation and its reference
|
||
frame count. It produces a clean presentation clip and a `next_reference`
|
||
tail clip. Only the tail is intended to feed the next generation; the entire
|
||
previous clip is never passed forward as the continuity input.
|
||
|
||
## Other nodes
|
||
|
||
- Dumas Image Compare
|
||
- Save Image Dumas
|
||
- Load Images from Folder Dumas
|
||
- Dumas JSON helpers
|
||
|
||
## Installation
|
||
|
||
Copy or clone this repository into `ComfyUI/custom_nodes/DumasNodes` and restart
|
||
ComfyUI. FFmpeg and FFprobe must be available on `PATH` for the video nodes.
|
||
|
||
## Development
|
||
|
||
Run the fast unit tests from the repository root:
|
||
|
||
```bash
|
||
python -m unittest discover -s tests -p 'test_*.py'
|
||
```
|