From c42cf436c53393bb6a9c0b1e0555cb0bb159b94b Mon Sep 17 00:00:00 2001 From: Chris Dumas Date: Fri, 28 Aug 2026 11:43:11 +0000 Subject: [PATCH] Document H3 long videos node --- H3_LONG_VIDEOS_GUIDE.md | 767 ++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 768 insertions(+) create mode 100644 H3_LONG_VIDEOS_GUIDE.md diff --git a/H3_LONG_VIDEOS_GUIDE.md b/H3_LONG_VIDEOS_GUIDE.md new file mode 100644 index 0000000..63a6282 --- /dev/null +++ b/H3_LONG_VIDEOS_GUIDE.md @@ -0,0 +1,767 @@ +# Dumas H3 Long Videos Guide + +This guide explains `Dumas H3 Long Videos (FL2VA + REF2VA)` in simple language. + +The node does two jobs at once: + +- It turns one prompt with several beats into a chain of H3 shots. +- It can condition those shots from a first frame, character references, location references, or both. + +Think of it like this: + +- `prompt` decides what happens. +- `shot_seconds`, `per_beat_length`, and beat-level `seconds:` decide how long each beat is allowed to be. +- `first_frame` and the handoff system decide continuity. +- `ref_1` to `ref_9` decide identity and location reference conditioning. + +## How The Node Thinks + +The node builds the final video one shot at a time. + +1. It splits the prompt into beats. +2. It decides how long each beat should be. +3. It decides which reference images and/or handoff frame each beat should carry. +4. It samples each beat. +5. It joins the beats into one video. + +That means many settings do not act alone. They work together. + +## Group 1: Main Inputs + +These are the inputs you always start with. + +### `model` + +The H3 diffusion model. + +### `clip` + +The H3 text encoder. + +### `vae` + +The H3 video VAE. + +### `audio_vae` + +The H3 audio VAE. + +### `prompt` + +This is the main shot description. + +How it is used: + +- First paragraph: the persistent anchor, unless `anchor_override` is filled in. +- Later paragraphs: the beat list. + +What belongs here: + +- character identity +- camera direction +- action +- dialogue +- scene events + +What does not belong in the anchor paragraph: + +- clothing that needs to change later + +Put changeable clothing in `character_memory` or a beat-level `wardrobe:` line. + +### `resolution` + +This chooses the shape, not the size. + +Examples: + +- `16:9` +- `21:9` +- `1:1` + +### `megapixels` + +This chooses the pixel budget. + +Simple rule: + +- `resolution` picks the shape +- `megapixels` picks how big that shape is + +Higher values give: + +- more detail +- more VRAM use +- usually shorter safe shot lengths + +Lower values give: + +- less detail +- less VRAM use +- usually longer safe shot lengths + +### `steps` + +Main-pass sampling steps. + +Default H3 usage is built around about `20` steps. + +### `cfg` + +Leave this at `1.0` unless you are deliberately experimenting. + +This node is built around H3's CFG-free behavior. + +### `sampler_name` + +Main-pass sampler. + +Usually leave this at the default unless you have a known reason to change it. + +### `scheduler` + +Main-pass scheduler. + +Usually leave this at the default unless you have a known reason to change it. + +### `seed` + +The base seed for the chain. + +With `vary_seed_per_shot` off, all beats use the same base noise field for better continuity. + +## Group 2: Prompt Structure And Beat Splitting + +These settings decide how the prompt becomes beats. + +### `anchor_override` + +If this is filled in, the node does not consume the first prompt paragraph as the anchor. + +Use it when: + +- you want every prompt paragraph to be a beat +- you want the persistent look controlled separately from the beat text + +### `beat_split` + +This controls how the prompt box is split into beats. + +- `auto`: blank lines first, then multi-line paragraphs can still split line by line +- `each line`: every content line becomes a beat + +### `character_memory` + +Persistent wardrobe and style memory for tracked characters. + +Good for: + +- clothing that should stay stable +- clothing changes you want to control clearly + +### `auto_wardrobe` + +Lets the node detect clothing removals directly from beat prose. + +### `auto_props` + +Lets the node carry props and objects across beats. + +### `lock_restraints` + +Keeps restraint items persistent until explicitly removed. + +### `exposed_terms` + +Persistent terms for exposed body states when you need them described consistently. + +### `prevent_nudity` + +Stops the node from explicitly stating a nude state in the prompt. + +## Group 3: Beat Duration And Timing + +This is the most important group to understand. + +These settings work together: + +- `shot_seconds` +- `per_beat_length` +- beat-level `seconds:` or `duration:` +- `allow_oversize_shots` +- `megapixels` +- `vram_headroom_gb` +- `allow_res_backoff` + +### The Short Version + +`shot_seconds` is a ceiling, not a promise. + +A beat-level `seconds:` line is a request, not absolute law. + +The final beat length is limited by: + +- H3's hard single-shot max +- the VRAM budget +- the current resolution and pixel budget + +### Exact Decision Order + +For each beat, the node decides length like this: + +1. If the beat has `seconds:` or `duration:`, use that as the requested length. +2. Otherwise, if `per_beat_length` is on, estimate the beat length from its content. +3. Otherwise, use the global shot ceiling. +4. Clamp that result to the global `shot_seconds` ceiling if one is set. +5. Clamp again if H3 or VRAM will not allow that size. +6. Snap the result to H3's frame grid. + +### `shot_seconds` + +Global per-shot ceiling. + +Important: + +- This does not mean every beat will be exactly this long. +- It means no beat is allowed to be longer than this, unless other limits clamp it first. + +If left unconnected or set to `0`, the node uses the largest safe shot length it can budget automatically. + +### `per_beat_length` + +When on, the node estimates beat length from the beat content if there is no explicit beat-level `seconds:` line. + +That means: + +- short simple beats become shorter shots +- more complex beats become longer shots + +When off: + +- every beat uses the full global ceiling unless that beat has its own explicit `seconds:` line + +### Beat-Level `seconds:` Or `duration:` + +Inside a beat, you can write: + +```text +seconds: 8 +``` + +or + +```text +duration: 8 +``` + +This has the highest priority for that beat. + +But it can still be clamped down if: + +- it exceeds the global `shot_seconds` ceiling +- it exceeds H3's hard max shot length +- it exceeds the VRAM budget and `allow_oversize_shots` is off + +### `allow_oversize_shots` + +This only affects forced global `shot_seconds`. + +When off: + +- too-long requests are clamped down to what fits + +When on: + +- the node will try to honor the requested global ceiling even if it exceeds the safe VRAM budget + +Trade-off: + +- slower renders +- possible spill to system RAM +- possible OOM + +This does not bypass H3's hard max shot size. + +### `vram_headroom_gb` + +This reserves VRAM safety margin before the node decides the safe shot length. + +Higher headroom: + +- safer +- shorter shots + +Lower headroom: + +- longer shots +- more crash risk + +### `allow_res_backoff` + +If a render does not fit, the node can step the resolution down instead of failing immediately. + +This can save a render, but it also changes the effective size of later shots. + +### What Actually Makes A 20-Second Beat + +In the current node, a beat does **not** automatically become 20 seconds just because it says `seconds: 20`. + +Why: + +- H3 has a hard single-shot frame cap +- the node also respects a VRAM budget + +So `seconds: 20` means: + +- "try for 20 seconds" +- then clamp it to what H3 and VRAM allow + +If you need around 20 seconds of action, you usually need: + +- two beats +- or a different workflow structure + +## Group 4: Continuity And Shot Chaining + +These settings control how one beat connects to the next. + +### `first_frame` + +Optional opening keyframe for shot 1. + +If empty, the first shot begins from text/reference conditioning alone. + +### `trim_seam` + +Drops the first frame of each later shot. + +Use this to avoid showing the same handoff moment twice. + +### `handoff_offset` + +Hands an earlier frame to the next shot instead of the literal last frame. + +Useful when: + +- a shot ends with an open mouth +- the next shot starts with awkward lip motion + +### `vary_seed_per_shot` + +Changes the seed between beats. + +Usually leave this off for a continuous take. + +Turning it on makes cuts feel more separate because micro-detail resets between beats. + +### Beat-Level `continuity:` + +You can override continuity for one beat inside the beat text. + +Examples: + +```text +continuity: hard cut +continuity: keyframe carry +continuity: handoff ref +continuity: soft carry +``` + +## Group 5: References And Identity + +These settings decide how reference images are used. + +### `ref_1` To `ref_9` + +These are the real reference slots. + +Feed them with: + +- `Dumas Character Reference` +- `Dumas Location Reference` + +Each slot has a stable picture number: + +- `ref_1` = `` +- `ref_2` = `` +- and so on + +### `ref_image_1` To `ref_image_9` + +Legacy compatibility aliases for older graphs. + +You should prefer `ref_1` to `ref_9` in new work. + +### `ref_mode` + +Controls which beats receive the reference images. + +Modes: + +- `auto ref2v`: if tags exist, use them; otherwise condition every shot +- `where tagged`: only tagged shots get refs, with first-shot fallback when no tags exist +- `first shot`: references only on shot 1 +- `every shot`: references on every shot +- `every shot + handoff ref`: references on every shot plus previous frame as an extra soft ref + +### `ref_image_size` + +Controls how large the reference is encoded. + +- `match`: cheaper, usually enough +- `max`: stronger identity/location fidelity, slower and heavier + +### `ref_noise_aug` + +Controls how literally the model follows the reference image. + +Higher: + +- cleaner +- more literal +- more likely to reproduce the reference closely + +Lower: + +- softer +- more approximate +- more likely to drift + +### Beat-Level `ref_mode:` And `ref_noise_aug:` + +You can override these inside a beat. + +Examples: + +```text +ref_mode: every shot +ref_noise_aug: 0.95 +``` + +### How The Ref Settings Work Together + +The node uses reference data in two different ways: + +- the image itself for real visual conditioning +- the text metadata for prompt context + +Character refs can now contribute actual image identity when the beat names the character, not just when you explicitly tag the picture slot. + +Simple usage patterns: + +- one character, no special routing: use `auto ref2v` +- one location plus named characters: use character names in the beat and tag the location when needed +- exact slot control: use explicit `` tags + +## Group 6: Audio And Sound + +These settings shape the soundtrack behavior. + +### `global_soundscape` + +Persistent ambient sound for the whole chain. + +Examples: + +- rain +- room tone +- crowd murmur +- engine hum + +### `non_diegetic_music` + +Background score that the characters do not hear. + +### `auto_soundscape` + +Lets the node derive an ambient bed from the prompt/anchor. + +Modes: + +- `off` +- `fill if blank` +- `always` + +### `auto_silence_nonspeech` + +Adds prompt-side silence control to beats with no quoted dialogue. + +### `allow_nonspeech_vocals` + +Allows screams, gasps, sobs, and similar non-dialogue sounds in otherwise non-speaking beats. + +### `mute_nonspeech_audio` + +Hard mutes the audio for non-dialogue beats. + +This is the deterministic anti-babble switch. + +Trade-off: + +- you also lose the generated ambience for those beats + +### `mute_fade_ms` + +Smooths the edges of audible shots next to muted ones. + +### How The Audio Settings Work Together + +There are two layers: + +- prompt-level guidance +- hard muting + +If you want the safest anti-babble setup: + +- leave `auto_silence_nonspeech` on +- leave `mute_nonspeech_audio` on + +If you want distress sounds like sobbing or gasping: + +- leave `auto_silence_nonspeech` on +- turn `allow_nonspeech_vocals` on +- usually leave `mute_nonspeech_audio` off for those shots + +## Group 7: Model Sampling And Flow Shifts + +These settings are for H3's internal scheduling. + +### `apply_model_sampling` + +Applies the H3 video/audio sampling schedule inside the node. + +Usually leave this on. + +### `shift_video` + +Video flow shift. + +### `shift_audio` + +Audio flow shift. + +These two belong together. + +If you change `shift_video`, you usually need to change `shift_audio` in proportion. + +## Group 8: Detail Pass + +This is the optional second pass. + +### `detail_pass` + +Enables the refinement pass. + +### `detail_sampler_name` + +Sampler for the refinement pass. + +### `detail_scheduler` + +Scheduler for the refinement pass. + +### `detail_steps` + +Extra steps for the refinement pass. + +### `detail_denoise` + +How strongly the refinement pass is allowed to rewrite the beat. + +### How The Detail-Pass Settings Work Together + +The detail pass starts from the first-pass result and tries to polish it. + +Gentle settings: + +- low to medium `detail_steps` +- low `detail_denoise` + +Aggressive settings: + +- high `detail_steps` +- high `detail_denoise` + +Aggressive settings can improve texture, but they can also: + +- change faces +- pull away from references +- break continuity + +Good starting point: + +- `detail_pass = on` +- `detail_sampler_name = euler` +- `detail_scheduler = beta` +- `detail_steps = 4` to `8` +- `detail_denoise = 0.20` to `0.35` + +## Group 9: Performance, Decode, And Upscale + +These settings help the job fit in memory and decide what happens after sampling. + +### `decode_tile_frames` + +Temporal tiling for VAE decode. + +Useful when decode is the memory bottleneck. + +### `decode_tile_size` + +Spatial tiling for VAE decode. + +Useful on tighter cards at larger resolutions. + +### `cleanup_between_shots` + +Moves completed shot data off the GPU and clears memory between beats. + +Good default for long chains. + +### `upscale` + +Optional post-pass upscale mode. + +### `upscale_model` + +Upscale model when `upscale = model`. + +### `upscale_target_short_edge` + +Resize target for the final output. + +### `upscale_batch` + +How many frames are upscaled at once. + +### How These Settings Work Together + +Use them in this order: + +1. Get the render stable. +2. If decode fails, use decode tiling. +3. If shot length is too short, reduce pixel cost before forcing oversize. +4. Only upscale after the base render is working. + +## Group 10: Overlay Controls + +These settings affect only the final frames, not the model prompt. + +### `watermark_text` + +Text watermark added after rendering. + +### `watermark_position` + +Watermark placement. + +### `watermark_size` + +Watermark size. + +### `watermark_opacity` + +Watermark transparency. + +### `watermark_margin` + +Watermark edge spacing. + +### `intro_text` + +Opening title text. + +### `intro_position` + +Title placement. + +### `intro_seconds` + +How long the title stays fully visible before fading. + +### `intro_fade` + +Fade length for the title. + +### `intro_size` + +Title size. + +### `overlay_font` + +Font used for overlays. + +### `overlay_stroke` + +Outline thickness around the text. + +## Group 11: Safety And Geometry Guards + +These are prompt-side stabilizers. + +### `subject_count_guard` + +Helps stop accidental character duplication. + +### `anatomy_guard` + +Helps stop extra limbs and hand duplication. + +### `motion_guard` + +Helps keep movement smooth and physically continuous. + +### `contact_guard` + +Helps keep multiple bodies aligned correctly in contact scenes. + +### `solidity_guard` + +Helps stop bodies clipping through objects. + +### How The Guard Settings Work Together + +These are best treated as stabilizers, not magic fixes. + +Recommended pattern: + +- leave most on `auto` +- only force `on` when you know that failure mode is likely + +## Quick Recipes + +### Simple One-Character Ref2V Chain + +- one character ref in `ref_1` +- `ref_mode = auto ref2v` +- no explicit `` tags needed +- `per_beat_length = on` + +### Two Characters Plus One Location + +- character refs in two slots +- location ref in another slot +- name the characters in the beats +- tag the location slot explicitly when location control matters + +### Exact Per-Beat Timing + +- use `shot_seconds` as a safe ceiling +- put `seconds:` inside beats that need exact control +- check `plan_only` first +- expect clamping if you ask for more than H3 or VRAM allows + +## Best Way To Check What Will Really Happen + +Use `plan_only`. + +That is the quickest way to see: + +- beat count +- planned shot count +- actual per-shot lengths +- clamps +- ref placement +- continuity choices + +If the plan looks wrong, the render will too. diff --git a/README.md b/README.md index 1f68614..387ec27 100644 --- a/README.md +++ b/README.md @@ -38,6 +38,7 @@ - Outputs: `images`, `audio`, `info`, `script`, `frames_per_shot`, `total_frames`, `shots`, `video_seconds`, `fps`, `fps_int`, `latent`, `soundscape` - First-pass Dumas port of the `MiniMax-H3-Longvideos` sampler, brought in as a local starting point for long-form H3 chaining work. - Keeps the upstream split-beats / handoff / ref-routing behavior close to source so future Dumas-specific improvements can be compared against a known baseline. + - Full user guide: [`H3_LONG_VIDEOS_GUIDE.md`](./H3_LONG_VIDEOS_GUIDE.md) - Only the canonical `DumasH3LongVideos` node key is exposed now; the older FL2VA/REF2VA alias entries are no longer duplicated in the Add Node menu. - Prompt `` tags now map to the actual ref socket numbers you wire, even with gaps such as only `ref_2` and `ref_7` connected. - Character refs now contribute appearance and wardrobe context from the same structured object, while location refs contribute environment context from theirs.