Document H3 long videos node

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` = `<Picture 1>`
+- `ref_2` = `<Picture 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 `<Picture N>` 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 `<Picture 1>` 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.

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 `<Picture N>` 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.