Extensions/Hand Tie Clips
ComfyUI Extension

Hand Tie Clips

Native MiniMax H3 Ref2VA chain: persistent references, previous-segment clip+audio pin, one queue.

By sandpies·Created 3 months ago·Updated about 14 hours ago· 12
dntpi/ComfyUI-Hand-Tie-Clips
Nodes—
On cloudLocal install
Stars12
Updatedabout 14 hours ago
Readme

license: mit tags:

  • comfyui
  • comfyui-nodes
  • custom-nodes
  • video
  • video-generation
  • text-to-video
  • image-to-video
  • minimax-h3

Hand Tie Clips — Multi-Shot Studio for MiniMax H3

Multi-hop MiniMax H3 video from one ComfyUI node. Author shot cards, manage reference stills and voices on a visual rail, lock or solo-retake individual hops from a lossless cache, run guided character/head swaps, and upscale to 2 MP.

Six consecutive frames across a join

Six consecutive frames crossing the join between Hop 1 and Hop 2 — no cut, flash, or identity jump.

🚀 Launch the Interactive Node UI Demo in Your Browser (docs/demo.html) — Click through Script · Refs · Timeline · Media · Write · Swap and the ⚙ (RUN) render-controls page live, toggle shot locks, solo-retake hops, and inspect the 10-hop hand_tie setup (compatible with both Classic LiteGraph and ComfyUI Vue Nodes 2.0).

<div align="center"> <p><strong>New: Sand Tie one-take music video, 2:03, no cuts, song locked</strong></p> <video controls preload="metadata" width="50%" style="max-width:480px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-mv-walk-me-through-the-night.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-mv-walk-me-through-the-night.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/sand-tie-mv-walk-me-through-the-night.mp4" type="video/mp4"> </video> </div> <div align="center"> <p><strong>Sand Tie: two people, one 52 s take, street to boardwalk to bench</strong></p> <video controls preload="metadata" width="50%" style="max-width:480px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-two-person-place-change-52s.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-two-person-place-change-52s.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/sand-tie-two-person-place-change-52s.mp4" type="video/mp4"> </video> </div> <div align="center"> <p><strong>Sand Tie: 65 s walking selfie, one take, upsampled</strong></p> <video controls preload="metadata" width="30%" style="max-width:300px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-walking-selfie-65s.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/sand-tie-walking-selfie-65s.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/sand-tie-walking-selfie-65s.mp4" type="video/mp4"> </video> </div> <div align="center"> <p><strong>Hand-Tie 10x8s example</strong></p> <video controls preload="metadata" width="50%" style="max-width:480px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/hand-tie-10hop-00138.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/hand-tie-10hop-00138.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/hand-tie-10hop-00138.mp4" type="video/mp4"> </video> </div> <div align="center"> <p><strong>Hand-Tie music video: 12x15s, one take, the song locked (<code>master_audio_file</code>)</strong></p> <video controls preload="metadata" width="40%" style="max-width:360px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/hand-tie-mv-hold-me-anyway.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/hand-tie-mv-hold-me-anyway.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/hand-tie-mv-hold-me-anyway.mp4" type="video/mp4"> </video> </div>

What You Can Do

| Tab / Surface | What It Does | |---|---| | 🎬 SCRIPT (Simple & Shots) | Switch to Simple mode (chains = 1) to paste standard MiniMax H3 ref2va / t2va 6-field prompts (passed through untouched!) or plain prose for single-clip generations with the upscale 2nd pass — or switch to Shots mode to author per-hop cards (5 s – 15 s each) with camera, framing, pace, and join controls. | | 🖼️ REFS (@tags & RefMod) | Drop up to 9 character/setting stills straight onto the node. Assign stable @tags, subject numbers, per-photo megapixel caps (the video model's copy, plus an optional qwen size for what the text encoder sees), per-hop schedules (rides hops), and per-character voice clips without wiring Load Image chains. | | 🎞️ TIMELINE (Retake Board) | Scrub every rendered hop, inspect the exact join frames, lock the shots you want to keep, or click ⏵ on Shot 3 to re-roll only Shot 3 while Shots 1–2 load from the lossless cache. | | 🎵 MEDIA (Clips, Voices & Lip-Sync) | Load a starting frame, up to 3 reference videos, 3 voice timbre clips, a background music bed (with auto-ducking), or a Master Audio File that locks lip-sync across the entire film. | | ✍️ WRITE (AI Draft Assistant — WIP) | Connect a local OpenAI-compatible server (nInfer / LM Studio / llama.cpp) to propose films, draft shot cards, surgically edit individual hops (Edit shots), or lay out bar-synced music videos (Song → Lay out). Note: WRITE is an experimental work-in-progress drafting tool, not a 100% hands-off autopilot — always review the generated beats and photo descriptions before rendering. | | 🎭 SWAP (Guided Video Swap) | Standalone one-hop character or head swap driven by a reference video's motion and audio (replace_person, head_swap, face_only, keep_person) with a free-text wardrobe override box and automatic dual Swap LoRA loading. Leaves your multi-shot SCRIPT and REFS untouched. | | 📄 STANDARD (SandTie Scribe) | Native clean-room single-generation H3 prompt rig (Ref2VA, T2VA, I2VA/FL2VA/L2VA, Start-Frame Prep) with 19 domain-locked dials, Reference Bible, 2.5 MP Eye Scan, Time-Tied beats, and 24-FPS Video → Beats extractor. Also available as the standalone SandTie PromptRig (H3) node. |


Three Ways to Join Shots (pin_mech)

| Mode | Status & Best Use Case | How It Works & Honest Tradeoffs | |---|---|---| | motion_context (Default — Built-In) | Stable — Continuous relays (~5–6 hops on Turbo, ~7–8 hops on non-Turbo with Refine) & multi-scene restart cuts | Built directly into Hand Tie Clips (no separate node install required; credit to NikoDemon80's ComfyUI-H3-Motion-Context for the latent-slice + end-aligned audio timeline design). Relays the previous hop's sampler AV latent into the next hop with in-latent head inpainting and distribution locking — and resets cleanly on restart cuts. | | hand_tie (Single-Take Previs) | Public Experimental — Continuous one-location walking vlogs & tracking shots (🎬 10-Hop 72 s Example), and one-take music videos on a master_audio_file (🎬 12-Hop 2:51 MV) | Renders one low-res single-take bridge previs first and ties each full-res hop's opening and closing 0.9 s to those clean windows via 7 per-step Motion-Context keyframes (with muted-window audio stripping and ambient floor locking) so hops never copy texture from each other.<br><br>Previs Compiler Model (Recommended in ComfyUI/models/text_encoders/): Drop any qwen3vl_4b*.safetensors or qwen3vl_8b*.safetensors into models/text_encoders/ — e.g. qwen3vl_4b_fp8_scaled.safetensors (Comfy-Org), qwen3vl_4b (silveroxides/K2Q), or qwen3vl_8b_int8_convrot.safetensors (Comfy-Org). It loads at the start of the run to compile your beats into continuous bridge moments and unloads from VRAM before H3 starts.<br><br>Caveat: Because every hop must meet its bridge window, beats that ask for a sudden location change, hard camera angle jump, or fast prop action across a join can cause the previs to cut or morph. It works best when the camera and subject flow continuously in one setting, and may occasionally need a seed re-roll if a beat moves too far. | | sand_tie (One Continuous Take) | New — Long continuous takes with no joins: a whole song as one walking shot (🎬 2:03 One-Take MV), a two-person scene that moves from street to boardwalk to bench (🎬 52 s Two-Person Take), selfie vlogs (🎬 65 s Walking Selfie, upsampled). Song-locked (master_audio_file) takes keep lip sync for the whole song. | Each take (every hop up to the next anchor: restart) is rendered as one video: its hops are overlapping windows, each drawn continuing the one before it, then the whole take is finished together, so there is no join to see. Retake one hop and only that hop's window is re-drawn between its kept neighbours. tone_lock keeps a long take from drifting brighter window after window. Write every hop of a take with the same camera sentence and the action on an At mm:ss-mm:ss, timeline (PROMPTING.md, "One continuous take"); WRITE does this for you.<br><br>Needs a ComfyUI with MiniMax H3 context windows (Comfy-Org/ComfyUI#17425) and overlap 0.9 s; without it the node says so before encoding anything. A take decodes into a self-deleting temp file on disk, so a 2-minute take does not have to fit in RAM. |

How references are shown to the text encoder. Core hands Qwen3-VL the same small copy of a reference that the video model gets, so a big character sheet reaches it as a thumbnail. HTC shows Qwen its own view instead, chosen by the row's retention: character sheets and garments (fully_preserved, partially_copy) from the original file at about 1 MP (or the render's size, if larger), props small, everything else as Core sends it. The video model's copy is unchanged, so render time barely moves. To override it for one picture, set the qwen box on its REFS row (0.3-8 MP; blank = auto). The log shows @tag: Qwen sees the original at WxH.


Built-In Finishing (⚙ RUN Page)

1. Single clips (Simple mode) + upscale 2nd pass

  • Using HTC for standard single generations (ref2va / t2va): You don't need a multi-hop chain to use Hand Tie Clips — switch SCRIPT to Simple mode (chains = 1 in ⚙ RUN) and paste your standard 6-field MiniMax H3 ref2va / t2va prompt (subject_definitions:, summary:, detailed_description:, etc.) or plain prose. HTC detects structured H3 prompts and passes them through untouched while giving you the visual REFS rail, the upscale 2nd pass and upsample on a single clip.
  • Steps (author's advice): run the first pass at 6–8 steps so the audio fully resolves, unless you use a 4-step turbo LoRA.
  • Upscale 2nd pass (⚙ RUN → upscale 2nd pass) re-draws the finished clip at a higher resolution. 2–3 steps is plenty; pick by taste. Its LoRA slots are for your own LoRAs and use case — HTC does not suggest any.
<div align="center"> <p><strong>Simple Mode (15s · 2 MP Upsample) example</strong></p> <video controls preload="metadata" width="50%" style="max-width:480px; border-radius:8px;" src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/simple-realism-boost-2mp-00008.mp4"> <source src="https://huggingface.co/sandpies/ComfyUI-Hand-Tie-Clips/resolve/main/docs/img/simple-realism-boost-2mp-00008.mp4" type="video/mp4"> <source src="https://media.githubusercontent.com/media/sandpies/ComfyUI-Hand-Tie-Clips/main/docs/img/simple-realism-boost-2mp-00008.mp4" type="video/mp4"> </video> </div>

2. Refine Pass (hop_refine: full) — Honest Limitations

  • Runs a gentle low-sigma detail pass per hop (supports wiring a stock 30-step H3 DiT to refine_model while your main wire runs a Turbo model).
  • The honest truth on chain length: Refine holds back relay degradation and keeps joins clean, pushing continuous motion_context chains to 5–6 clips on Turbo before very visible texture changes appear, and 7–8 clips on non-Turbo. Under motion_context, plan to transition to a cut (anchor: "restart") every 4–5 clips or so to maintain the integrity of your textures (or use pin_mech: sand_tie for one continuous take with no joins).

3. Upsample (upsample: on) & standalone nodes

After the last hop the film is sized up to upsample_megapixels (default 2.0 MP) in latent chunks and re-drawn. Choose how in ⚙ RUN → UPSAMPLE → upsample method:

  • regen2k (default): re-draws detail with an Open-H3-Regenerate-2K LoRA, picked in regen2k lora. 3 Euler steps from sigma 0.6 (0.8 is the original recipe: sharper, but faces drift more), LoRA strength upsample_denoise 0.8 (0 only enlarges), each hop's own prompt as conditioning (regen2k_cond), seed 42.
  • ic (in-context): keeps each piece's own frames in view, and hears its soundtrack, while it re-draws, so faces, lettering and mouths stay the film's own. Slower. It needs the plain, unpruned minimax_h3_ref2va_* DiT with no LoRAs, on upsample_dit (or on the MODEL wire if upsample_dit is empty); fl2va, pruned and merged models cannot run it, and the run stops before any hop renders and names the fix. No text encoder is loaded for it.
  • upsample steps: 3 (recipe) or 2 (faster), about a third faster and re-draws a little less. Applies to both methods.

Long films are cut into overlapping chunks (102 frames, 17 shared) that are re-drawn together, so the joins don't show; tiles size themselves to your GPU (upsample_tile_tokens 0 learns what your card can take; a number fixes it). Sparse attention is used for speed. With a ComfyUI-KJNodes older than 2026-09-06, sparse attention falls back to dense by itself and the log says so; update KJNodes to get it back. On by default in the shipped workflows. An optional HTC Upsample Settings node on the upsample_settings socket exposes every number. Toggling upsample on a cached chain skips the hops and runs only the upsample.

Required Files for Upsampling:

  1. Latent Upscaler (ComfyUI/models/latent_upscale_models/): Download minimax_h3_latent_upscaler_3d_conv_v1_bf16.safetensors from LBH-123-AI/Minimax_h3_latent_Upscaler (the old name minimax_h3_latent_upscaler_3d_bf16.safetensors still loads, as does h3_upscaler_lms_v0.1.safetensors). Or the 2D one, minimax_h3_latent_upscaler_2d_conv_v1_bf16.safetensors (182M parameters against the 3D one's 345M), picked in upsample_model: it takes upsample_sharpness 1-6 (1 = most faithful, about the 3D one's look; 6 = sharpest). The standalone upsampler nodes have the same sharpness widget.
  2. regen2k LoRA (ComfyUI/models/loras/): Download open_h3_regenerate_2k_r256pp_bf16.safetensors (3.77 GB, a rank-256 compression of NVlabs' Open-H3-Regenerate-2K LoRA).
  3. ic only (ComfyUI/models/loras/): minimax_h3_open_regenerate_2k_ic_lora_avg_rank_21_bf16 (200 MB) + minimax_h3_hyperflow_8step_v1.0 (+ minimax_h3_lms_v1.0_r64 if you have it), and the DiT minimax_h3_ref2va_int8_convrot.
  4. upsample_dit wire (optional for regen2k): a separate model for the re-draw, e.g. a plain H3 UNETLoader with no LoRAs. Unwired, the re-draw uses the MODEL wire with the hop LoRAs stripped.

The old h3upscale x2 LoRA is retired: upsample_lora is ignored.

Want to upscale any existing video outside a chain? Use the included H3 Video Upsampler (file to file) node (workflows/HandTieClips_Upsample_Video_File.json, flat RAM at any length) or H3 Video Upsampler (finished clip) (workflows/HandTieClips_Upsample_Video.json) or the standalone repo: sandpies/ComfyUI-H3-Video-Upsampler.

Quick Start (60 Seconds)

From your ComfyUI/custom_nodes/ folder:

git clone https://github.com/sandpies/ComfyUI-Hand-Tie-Clips.git
  1. Restart ComfyUI and hard-refresh your browser (Ctrl+Shift+R). Zero pip dependencies.
  2. Drag workflows/HandTieClips_Starter.json onto ComfyUI and point the loaders at your MiniMax H3 ref2va checkpoint, text encoder, and VAEs.
  3. In REFS, drop your character photo onto Row 1 and give it a tag like @maya.
  4. In SCRIPT, write one beat per shot card and press Queue.
<details> <summary>Recommended Companion Packs & Optional Models</summary>

| Component | Where to Get It | |---|---| | Turbo / SLA / AdaLN Nodes | ComfyUI-PlagueKind-Nodes & ComfyUI-KJNodes | | Upscaler LoRA & Standalone Pack | sandpies/ComfyUI-H3-Video-Upsampler (HF) · GitHub | | Latent Upscaler Weights (3D / 2D) | LBH-123-AI/Minimax_h3_latent_Upscaler (models/latent_upscale_models/) | | Hand-Tie Previs Compiler (models/text_encoders/) | qwen3vl_4b_fp8_scaled.safetensors (5.2 GB) · silveroxides/K2Q (4B) · qwen3vl_8b_int8_convrot.safetensors (9.3 GB) |

</details>

Prompting Cheat-Sheet (The 5 Golden Rules)

MiniMax H3 samples at CFG 1.0 with no negative prompt — every word you write is added to the scene.

| ❌ Don't Write | ✅ Write Instead | |---|---| | "She stops talking." (Names talking → keeps her talking) | "She smiles with her lips closed. The low hum of the refrigerator." | | "No background music, silent room." (Silence = model invents speech) | Always name a specific room tone: "Soft rain on the windowpane, distant traffic hum." | | Re-describing hair, face, and clothes on Shots 2, 3, 4 | Describe only the new action on Shots 2+ — the reference rail and join pin carry her look. | | Ending Shot 2 mid-sentence when Shot 3 should be quiet | Finish the action/sentence at the end of Shot 2 so Shot 3 inherits a settled state. | | Leaving the final shot's tail on ongoing | Set the last shot's tail to settle or hold so the film lands cleanly. |

Full authoring guide: PROMPTING.md · Release history: CHANGELOG.md · Credits & Notices: THIRD_PARTY_NOTICES.md

<details> <summary>Included Nodes (Category: "Hand Tie Clips")</summary>
  • H3 Ref2VA Chain (HandTieClips): The main studio node (images, audio, info, contact_sheet).
  • H3 Chain Preview (HTCChainPreview): Live progress, seam side-by-side viewer, and end-of-run A/V drift monitor.
  • H3 Video Upsampler (HTCVideoUpsampler): Standalone node to upscale any finished video clip with the same tiled latent upsampler recipe.
  • H3 Video Upsampler (file to file) (HTCVideoUpsamplerToFile): The same upsampler from Load Video straight to an MP4, read, encoded, re-drawn, decoded and saved a chunk at a time so RAM stays flat at any length.
  • HTC Video Frames (lean) (HTCVideoFrames): Drop-in for Get Video Components with half its peak RAM; start_seconds, duration_seconds, a 24 fps re-time and a resize applied while decoding.
  • HTC Load Video (path) (HTCLoadVideoPath): Load Video from a file path: no upload, no copy, no 100 MB upload limit; reports resolution, fps (variable-rate flagged), length, codec and audio.
  • H3 Tiled Upsampler (HTCTiledUpsampler): Latent-input tiled upsampler for custom graphs.
  • HTC Upsample Settings (HTCUpsampleSettings): Every number of the chain's upsample, on its optional upsample_settings socket; unwired, the defaults (Regen2K from 0.6, stepped joins).
  • HTC Save Video (long-form) (HTCSaveVideo): Replaces RTX Frame Generation -> CreateVideo -> SaveVideo for long films: streams the frames, frame generation per pair on the GPU, NVENC constant quality, a keyframe on every cut.
  • H3 RefMod Builder (HTCRefModBuilder): Builds reusable visual/voice reference modules for the REFS rail.
  • H3 Token LoRA (HTC) (HTCTokenLoRA): A LoRA loader with one strength per kind of token: video, reference pictures, prompt and soundtrack. Slots A/B/C plus Add LoRA, each with its own strengths and block range; a checkbox switches a slot off. Audio 0 keeps the soundtrack on the plain model (a look LoRA no longer changes voices); reference 0 keeps the reference pictures read by the plain model. All 1 = a normal loader. Chain several to stack LoRAs. Works with chunked feed-forward and sparse attention.
  • H3 Cache (HTCH3Cache): Residual step cache on the MODEL wire (silveroxides / PlagueKind; see THIRD_PARTY_NOTICES.md).
  • SandTie PromptRig (H3) (SandTiePromptRig): Standalone plug-and-play MiniMax H3 prompt rig (Ref2VA, T2VA, I2VA/FL2VA/L2VA, Start-Frame Prep, and 0-VRAM CPU Tie). Outputs prompt (for a stock H3 node) and, with wire_mode = Direct H3 Conditioning, positive + latent.
  • HTC Sparse Attention (HTCSparseAttention): Sparse and low-VRAM attention for H3 on Comfy Kitchen's sol_attn kernels, with presets (turbo_sla_* for turbo LoRAs, native_sol_* for plain checkpoints, dense_low_vram). A preset overrides the numeric widgets; pick manual to set them yourself. The Starter uses it in place of external attention nodes.
  • HTC Steering Dials (HTCSteeringDials) / Make Steering Dial (HTCMakeSteeringDial): Push motion, expression and energy (or any dial you build from A ||| B prompt pairs) in H3's prompt space, without touching weights or LoRAs. Dials live in models/loras/dials/.
  • HTC AdaLN LoRA Fix (HTCAdaLNFix): Ports dense-trained LoRAs' AdaLN keys onto pruned (curve-form) H3 checkpoints and back. HTCTokenLoRA, the upsamplers and realism boost already do this on their own; the node is for other LoRA loaders. Adapted from PlagueKind's MIT fix (see THIRD_PARTY_NOTICES.md).
</details>

Credits & Inspirations (SandTie PromptRig)

  • LD Studio (H3Studio-LD) — Inspired the modular CFG=1 multi-dial prompt architecture, vocal/speech register controls, and positive-only additive prompting discipline.
  • wangweihong (comfyui-cinematic-gallery) — H3-verified camera motion trajectories, lens/film stock looks, and visual style references.
  • loopforge0 (minimaxh3-shots-skills) — Empirical MiniMax H3 12-primitive camera grammar, Open-End Range Law, Background-Plate amplitude scaling, zero-hardware phrasing, and audio semicolon findings.