Replace H3 nodes with generic sequential video tools

This commit is contained in:
2026-10-11 10:15:36 +00:00
parent b5eb941c4b
commit a4063ef60a
28 changed files with 432 additions and 26528 deletions
+27 -263
View File
@@ -1,281 +1,45 @@
# DumasNodes
`DumasNodes` is a ComfyUI custom-node pack for generic utility workflows under the Dumas brand.
Generic ComfyUI utility nodes under the Dumas brand. The repository contains
image, JSON and video utilities and intentionally has no model-specific video
sampler dependency.
## Included Nodes
## Video nodes
- `Dumas Image Compare`
- Inputs: optional `image1`, optional `image2`
- Outputs: `new image`
- Saves preview images for the built-in compare UI and passes through the second image when present, otherwise the first.
- Bundles a `js/` frontend extension so the compare viewer renders inside both classic ComfyUI and Nodes 2.0.
### Dumas Standalone Video
- `Save Image Dumas`
- Inputs: `images`, `folder`, `pattern`, `format`, `quality`, `embed_workflow`, `save_on_run`, optional `name`, optional `name_2`
- Output: none
- Saves images to any folder, not just ComfyUI's output directory.
- Supports filename tokens including `%input%`, `%input2%`, `%date:yyyy-MM-dd%`, `%counter%`, `%width%`, `%height%`, and `%batch_num%`.
Encodes an IMAGE batch and optional AUDIO into two files:
- `Load Images from Folder Dumas`
- Inputs: configured on-node via folder picker and image gallery
- Outputs: `image`, `mask`, `width`, `height`, `filename`, `index`, `total`
- Loads one or many images from any folder on disk as ComfyUI list outputs.
- Supports manual picks, `Select all`, `First N`, and `Select random` so each run can choose one random image from the visible folder tree.
- `full_clip`: every generated frame, including any continuation overlap
- `complete_clip`: the same clip with `overlap_frames` removed before encoding
- `Dumas H3 Plan Attach Scene Images`
- Inputs: `plan`, `scene_index`, optional `image1`..`image9`
- Outputs: `plan`, `connected_images`
- Attaches up to nine optional image sockets to one MiniMax H3 plan scene while keeping the plan JSON-serializable for the upstream archive system.
- Chain one node per scene that needs its own nine-image bundle.
The full clip is the source for the next sequential generation. The complete
clip is the assembly-ready segment. Removing the overlap before encoding means
the final join does not need to re-encode an already assembled film.
- `Dumas H3 Plan Extract Scene Images`
- Inputs: `plan`, `scene_index`
- Outputs: `plan`, `image1`..`image9`, `connected_images`
- Reads back the nine optional images for a selected MiniMax H3 plan scene, for example by connecting the current `clip_index`.
### Dumas Join Video Clips (No Re-encode)
- `Dumas H3 Long Videos`
- Inputs/outputs: the current upstream `MiniMax-H3-Longvideos` sampler surface, exposed under the existing `DumasH3LongVideos` key for saved Dumas workflows.
- The local Dumas prompt-engineering fork has been removed from this node. Long Videos now wraps the upstream sampler/engine/runtime/audio/conditioning/shot-plan modules directly so it can track the source project again.
- Upstream compatibility keys `H3LongVideos`, `H3LongVideosFL2VA`, `H3LongVideosV1`, and `H3LongVideosREF2VA` are also registered to the same class.
- The old Dumas browser widget grouping script is disabled for this node because it targeted controls that no longer exist on the upstream sampler.
- `handoff_frames` extends the upstream last-frame handoff: `1` keeps the current single keyframe behavior; higher values keep that final-frame keyframe and add earlier tail frames from the previous shot as claimed reference context for the next beat.
- Upstream license text is included in [`H3_LONGVIDEOS_UPSTREAM_LICENSE.txt`](./H3_LONGVIDEOS_UPSTREAM_LICENSE.txt).
Accepts up to six completed clip paths and concatenates them with FFmpeg stream
copy (`-c copy`). It validates codec, dimensions, frame rate, pixel format and
audio compatibility before joining. The input clips must already have their
continuation overlap removed.
- `Dumas H3 Latent Upscale Params`
- Inputs: `mode`, `model_name`, `method`, `width`, `height`, `device`, `precision`, `sampler_name`, `scheduler`, `steps`, `denoise`, `megapixels`, `tile_width`, `tile_height`, `overlap`, `fade_width`, `fade_height`, `overlap_mode`, `overlap_blend`, `tile_size_mode`, `grid_rows`, `grid_cols`, `spatial_w_overlap`, `spatial_h_overlap`, `min_tile_size`, `masked_area_noise`, `brightness_match`, `dynamic_fade`, `dynamic_fade_min`, `chunk_length`, `temporal_overlap`, `resize_conditioning`, `anchor_strength`
- Output: `latent_upscale_param`
- Legacy helper from the abandoned Dumas Long Videos fork. The current upstream-backed `Dumas H3 Long Videos` node does not consume this socket; it uses the upstream latent-upscale controls on the Long Videos node itself.
## Other nodes
- `Dumas H3 Beat Prompt`
- Inputs: authored through the custom front-end beat editor
- Output: `prompt`
- Builds an upstream-compatible Long Videos prompt: optional scene paragraph, optional character sheet, then one blank-line-separated textbox per beat.
- Per-beat helpers only emit upstream-supported state directives: `remove:` / `removed:` / `off:` and `add:` / `wear:` / `wearing:`.
- Old Dumas-only beat directives such as `seconds:`, `continuity:`, `ref_mode:`, `ref_noise_aug:`, `anchor_add:`, `soundscape:`, and `music:` are stripped from the generated prompt so they are not sent to the upstream node as visible text.
- `Dumas H3 Prompt Curator`
- Inputs: `action_prompt`, `anatomy_guard`, `subject_count_guard`, optional `anchor`, optional `soundscape`, optional `bgm`, optional `ref_1` through `ref_9`
- Outputs: `prompt`, `ref_image_1` through `ref_image_9`, `reference_count`, `debug`, `anchor`, `sounds`, `bgm`, `original_ref_1` through `original_ref_9`, `compiled_ref_description_1` through `compiled_ref_description_9`
- Builds one standalone MiniMax H3 prompt from your final action text plus structured character/location references.
- The action text can mention references by character/location name, alias, `<Picture N>`, or `<refN>`. Only mentioned references are emitted, and the output images are compacted/renumbered so skipped inputs do not leave gaps.
- Extra component outputs expose the cleaned anchor, sounds, BGM, and each connected input reference image plus its compiled reference description in original socket order. These inspection/reuse outputs are not trimmed by the action text; only the final prompt and `ref_image_*` H3 reference outputs are trimmed.
- Adds curated reference context, anatomy guard text, optional subject-count guard text, anchor/style text, `overall_soundscape:` text, and `background_music:` text while respecting MiniMax H3's reference-generation shape: one prompt plus up to nine reference images.
- `Dumas H3 Shot Length`
- Inputs: `shot_seconds`, `fps`, optional `cap_to_h3_max`
- Outputs: `seconds`, `frames`, `info`
- Emits one H3-safe shot length as both seconds and a grid-aligned frame count for wiring into the long-video sampler and preview helpers.
- `Dumas H3 Model Inspector`
- Input: `model`
- Outputs: `format`, `report`
- Reports the detected H3 base precision / quant format and the relevant compute-capability hints for the current card.
- `Dumas Character Reference`
- Inputs: `image`, `character_id`, `name`, `alias`, `gender`, `age`, `nationality`, `occupation`, `height_feet`, `height_inches`, `accent`, `description`, `general`, `wardrobe`
- Output: `reference`
- Builds one structured `REFERENCE` object carrying the conditioning image, identity description, wardrobe, general notes, and simple facts together.
- `Dumas Location Reference`
- Inputs: `image`, `location_id`, `name`, `alias`, `description`, `general`
- Output: `reference`
- Builds one structured `REFERENCE` object for a location/environment so H3 can use the same socket type for both character and scenic refs.
- `Dumas Character Helper`
- Inputs: `image1`, `image2`, picture IDs, character identity fields, `general`, `wardrobe`
- Outputs: `image1`, `image2`, `reference_prompt`, `wardrobe`, `reference1`, `reference2`
- Restores the original general-purpose helper shape while also emitting two structured `REFERENCE` objects for the prompt curator.
- The structured references carry the same character name, alias, age, height, gender, nationality, occupation, accent, wardrobe, and notes, so mentioning the character name in `Dumas H3 Prompt Curator` can include both helper images and the character facts automatically.
- `Dumas Location Helper`
- Inputs: `image1`, `image2`, picture IDs, `location_id`, `name`, `alias`, `description`, `general`
- Outputs: `image1`, `image2`, `reference_prompt`, `reference1`, `reference2`
- Matching general-purpose helper for environments/locations: pass two images through unchanged, emit location reference prompt text, and provide two structured `REFERENCE` objects for the prompt curator.
- The structured references carry the same location name, alias, description, and notes, so mentioning the location name in `Dumas H3 Prompt Curator` can include both helper images and the location context automatically.
- `Dumas Anchor Style`
- Inputs: `anchor_style`, `style_description`
- Output: `anchor`
- Offers a large preset dropdown of anchor-style titles such as cinematic action movie, comedy, found footage, 90s sitcom, mobile/cell phone captured, news broadcast, mockumentary, heist thriller, cyberpunk neon, nature documentary, courtroom drama, and more.
- The preset wording is tuned for H3-safe persistent anchors: camera language, lighting, texture, production treatment, and tone, without naming characters or describing one-off actions.
- Selecting a preset fills the editable description field, and the edited multiline description is the `STRING` value passed downstream.
- `Dumas Soundscape Helper`
- Inputs: `soundscape`, `soundscape_description`
- Output: `soundscape`
- Matching soundscape helper for standalone H3 prompts. Pick a preset such as quiet interior, rainy street, cafe, city night, forest, industrial, or silent; the preset fills the editable textbox, and the edited text flows into `Dumas H3 Prompt Curator`.
- `Dumas Background Music Helper`
- Inputs: `bgm`, `bgm_description`
- Output: `bgm`
- Matching BGM helper for standalone H3 prompts. Pick a preset such as subtle tension, cinematic suspense, emotional piano, dark ambient, hopeful orchestral, retro synth, action pulse, lo-fi, or no vocals; the preset fills the editable textbox, and the edited text flows into `Dumas H3 Prompt Curator`.
- `Dumas JSON String to Object`
- Input: `json_string`
- Output: parsed `JSON`
- Use it to turn raw JSON text into a structured object.
- `Dumas JSON Object to String`
- Inputs: `json_object`, `pretty`, `sort_keys`
- Output: serialized `STRING`
- Use it to compact or pretty-print JSON for prompts, logs, or file output.
- `Dumas Strip Iteration Suffix`
- Input: `filename`
- Output: cleaned `STRING`
- Keeps only the part before the first underscore, for example `asset_build_003.png -> asset.png` and `char123_pose.png -> char123.png`.
- `Dumas Slugify String`
- Input: `text`
- Output: slug `STRING`
- Converts text into a lowercase URL/file-safe slug, for example `Crème brûlée 2026 -> creme-brulee-2026`.
- `Dumas JSON Get Value`
- Inputs: `json_object`, `path`
- Output: `JSON`
- Reads a nested value using dot paths like `user.profile.name` or `items.0.id`.
- `Dumas JSON Set Value`
- Inputs: `json_object`, `path`, `value_json`
- Output: updated `JSON`
- Writes a parsed JSON value into a nested path without mutating the original object.
- `Dumas JSON Has Key`
- Inputs: `json_object`, `path`
- Output: `BOOLEAN`
- Checks whether a nested path exists.
- `Dumas JSON Remove Key`
- Inputs: `json_object`, `path`
- Output: updated `JSON`
- Removes a nested key or array item by path.
- `Dumas JSON Pick Fields`
- Inputs: `json_object`, `paths`
- Output: filtered `JSON`
- Builds a new object from newline-separated paths that exist in the input.
- `Dumas JSON Merge Objects`
- Inputs: `base_object`, `overlay_object`
- Output: merged `JSON`
- Deep-merges dictionaries so overlay values replace or extend the base object.
- `Dumas JSON Keys`
- Input: `json_object`
- Outputs: `keys` as JSON array, `count` as integer
- Lists the top-level keys of an object and reports how many there are.
- `Dumas JSON Array Length`
- Input: `json_array`
- Output: `INT`
- Returns the length of a JSON array.
- `Dumas JSON Array Append`
- Inputs: `json_array`, `value_json`
- Output: updated `JSON`
- Appends a parsed JSON value to the end of an array.
- `Dumas JSON Array Slice`
- Inputs: `json_array`, `start`, `end`, `step`
- Output: sliced `JSON`
- Returns an array slice. `end=0` means "slice to the end".
- `Dumas JSON Array Iterator`
- Inputs: `json_input`, `index`, `mode`
- Outputs: `item`, `current_index`, `total_items`
- Returns the current array item and position, with `mode` set to `fixed`, `incr`, or `decr`.
- `Dumas JSON Object Iterator`
- Inputs: `json_input`, `index`, `mode`
- Outputs: `key`, `value`, `current_index`, `total_items`
- Returns the current object entry in insertion order, with `mode` set to `fixed`, `incr`, or `decr`.
- `Dumas JSON Flatten`
- Input: `json_input`
- Output: flat `JSON`
- Flattens nested objects and arrays into dot-path keys.
- `Dumas JSON Unflatten`
- Input: `flat_json_object`
- Output: nested `JSON`
- Rebuilds nested JSON from a flat dot-path object.
All nodes live in the `Dumas/JSON` category.
- Dumas Image Compare
- Save Image Dumas
- Load Images from Folder Dumas
- Dumas JSON helpers
## Installation
1. Change into your ComfyUI custom nodes directory:
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.
```bash
cd /path/to/ComfyUI/custom_nodes
```
## Development
2. Clone this repository:
Run the fast unit tests from the repository root:
```bash
git clone https://git.dumas.ddns.net/chris.dumas/DumasNodes.git
```
3. Restart ComfyUI.
## Usage
Use dot paths for nested access:
```text
user.profile.name
items.0.id
settings.render.width
```bash
python -m unittest discover -s tests -p 'test_*.py'
```
`Dumas JSON Set Value` expects `value_json` to be valid JSON, so strings should be quoted:
```json
"Dumas"
```
```json
{"enabled": true, "retries": 3}
```
`Dumas JSON Pick Fields` expects one path per line:
```text
user.name
meta.active
items.0.id
```
`Dumas JSON Array Slice` treats `end=0` as "use the rest of the array".
`Dumas JSON Array Iterator` clamps to valid bounds:
```text
fixed -> use index as-is
incr -> use index + 1
decr -> use index - 1
```
`Dumas JSON Object Iterator` uses the same index rules and iterates object entries in their existing key order.
`Dumas JSON Flatten` and `Dumas JSON Unflatten` use the same dot-path format as the other path-based nodes.
`Dumas Image Compare` accepts one or two images. The `new image` socket forwards `image2` when connected so you can keep the "after" image moving through the workflow, and falls back to `image1` if only one input is present.
`Save Image Dumas` leaves `folder` empty to use ComfyUI's output directory. `name` feeds `%input%` and `name_2` feeds `%input2%`, so a pattern like `project/%input%_%input2%_%counter%` can combine two upstream strings into the saved filename.
`Dumas H3 Plan Attach Scene Images` and `Dumas H3 Plan Extract Scene Images` are a companion pair for `ComfyUI-MiniMaxH3-Contex-Loop` and the local `ref2v` lane. The upstream H3 plan node cannot dynamically grow nine new image sockets for every JSON-defined scene, so Dumas stores scene image bindings beside the plan using a lightweight token and an in-memory registry. That keeps `plan.json` archiving intact while still letting you wire up nine IMAGE sockets per scene through chained helper nodes.
`Dumas Character Helper` is the restored two-image/text helper for general H3 workflows, and `Dumas Location Helper` mirrors it for scene/environment references. Both helpers also emit structured `REFERENCE` sockets for the curator. The structured `Dumas Character Reference` and `Dumas Location Reference` nodes remain available separately for workflows that want a single `REFERENCE` socket. `Dumas H3 Prompt Curator` consumes those structured references plus optional anchor, soundscape, and BGM strings, assigns the final `<Picture N>` numbering, and outputs compacted `ref_image_*` sockets for only the references the prompt actually mentions. Its `original_ref_*` and `compiled_ref_description_*` outputs mirror the connected input sockets for reuse/debugging even when a reference is not mentioned in the final prompt.
`Dumas Strip Iteration Suffix` keeps the part before the first underscore and drops the rest. Names like `char123_pose_final.png` become `char123.png`, while names with no underscore such as `char123.png` are left untouched.
`Dumas Slugify String` lowercases text, strips accents, replaces non-alphanumeric runs with `-`, and trims leading or trailing dashes.
## Roadmap
This repo is intended to grow into a broader set of Dumas-branded generic utility nodes, including JSON helpers and adjacent data-manipulation tools.
## License
MIT.