the-node.md

The node

Everything is on one node. From top to bottom:

• The rail: buttons for attaching images, video, audio and LoRAs, plus the cast, presets, the gallery and settings.
• The prompt box: your prompt, with attached files cited by @ name.
• The pills: duration, aspect, resolution and the sampler row. The model pill says which family and checkpoint this render lands on.
• Render.

Drop the node, type, press Render. That is the whole workflow.

Attaching files

Type @ anywhere in the prompt. The menu lists what is already attached first, then the cast, the cast library, piece references and your input folder. Picking a file that isn't attached yet attaches it.

The rail buttons open the same library as a full picker: a tab per kind, search, shelves, favourites and upload, plus a Renders tab over your output folder, so a clip you just made can go straight back in as a reference.

A shelf is a folder on disk and nothing else. The "+" makes the directory, dragging a thumbnail onto a chip moves the file into it, and the row shows what is actually there, so a folder you delete from a terminal is gone from the picker on the next listing. An empty one you made by mistake has a Remove shelf at the end of the row; a folder with anything in it is a file manager's job.

Every attachment gets a colour, and its chip in the sentence wears the same one. Citing a file by name in the prompt matters: the models here don't take free text plus a pile of images, they take structured prompts where each reference is addressed, and writing use @img-1 for their face is what lets the compiler build that structure for you.

Scope: what a reference contributes

Each reference chip has a scope dial that narrows what the file is for:

Kind	Scopes
Image	full, person, object, scene, style, action
Video	the image scopes, plus camera, edit, continue
Audio	full, voice, music, ambience, copy

On person, "them from @img-1" stops dragging that image's background, palette and pose along with the face. action is the opposite cut: the action alone, carried onto whoever the prompt puts in the shot - a clip lends the whole movement, a still lends its pose. On a clip, camera borrows the camera move without the people in it, edit means "change something in this footage", and continue picks up where the clip ends.

Trimming, and picture vs sound

Video and audio chips open a segment editor: scrub, drag the handles, or slide a fixed-length selection along the waveform. Three buttons decide what a video contributes: picture and sound, picture only, or sound only. A clip attached for its sound alone scopes with the audio dial, since there is no picture left to narrow.

Editing a picture: crop, turn, mirror, cut out

Every picture and clip wears a pen. Press it - on a chip, on a picker cell, on a clip card, on a pre-stage chip - and one editor opens on the source file: drag a window over the part that is the reference (one subject off a sheet of four), resize it by its corners, lock it to the shot's shape, turn or mirror the picture under it, and on a still, switch the scissors on to lift the subject off its background - click the subject you mean, shift-click what should go, and the window shows the cutout as it will be used. A clip gets a scrub bar so the window can be checked across the segment.

The file on disk is never touched. The framing is kept on the chip, survives reloading the workflow, and is applied wherever the file is read - as a reference, a start or end frame, a guide, a clip card on the strip, a picture in the pre-stage, or a RefMod being kept. A cutout is built once as a plate, with the source and the clicks remembered so the editor opens on the photograph again. Thumbnails show the picture as edited, and a canvas that follows a picture follows its window.

Cutting out runs in the picker, not in a render. With only BiRefNet installed it grabs the most prominent subject automatically; SAM 3 is what the clicks ask. Files for both are in models.md; with nothing picked under the weights control, the first of each the install has is used.

The cast

A reference is a file. A subject is who is in the video, and the two are kept apart. People are cast, not attached: press Cast on the rail, name them, and hang files on them - a face from a few stills, a walk from a clip, a voice from an mp3, or footage they take somebody's place in.

Then write with them: @anna walks in and looks at @ben. Citing a subject carries their files into that shot, so a shot that never names them doesn't pay for their pictures. A name and a description with no files behind it is a valid subject too, and it is what keeps a character consistent from shot 1 to shot 9.

Hanging a file on a cast member sets its scope dial for you.

Each file on a member has its own menu, from its tile. At its head is a line for what the file shows of them - "her face, front-lit", "the green coat", "the golf swing" - which is written after that file's label in the subject definition, so the model knows which picture is which and what the clip is of. Under the roles is the size the file is encoded at, match or max, the same choice the reference card offers, and it is kept with the member: a member taken out of the cast library comes back with each picture at the size it was kept at. A tile wears a small max when it is encoded at full detail and a dot when words are attached to it.

Under that line is a second one: the words the file wakes on. Leave it blank and the file comes with the member into every shot that names them. Write hat, cap on the plate of the red hat and it is in a shot only while the sentence says one of those words - at the start of a word, so smok on a smoking sheet wakes on "smoking", "smokes" and "smoke", and hat wakes on "hats" but not on "what". This is how a character with thirty plates - costumes, props, action sheets, a reel per gesture - is written as a sentence: "@vera, in her hat, lights a cigarette" brings the face, the hat and the smoking sheet, and leaves the other twenty-seven out, under the nine-picture cap. A file the sentence names outright (@img-3) is awake whatever its words, a muted file stays muted whatever the sentence says, and a {hat|cap} wakes the plate the seed picks. On the card the chip says wakes on hat, cap behind a ring - filled while the file is in, hollow while it waits - the word that woke it is underlined in the member's hue in the sentence, and a member every one of whose plates is asleep is refused by name with the words that would wake one. The tile wears the ring hollow. The words are kept with the member in the cast library and follow a picture onto its RefMod.

A muted file on the cast card has a dimmed thumbnail and a mute badge. Its claim stays on the member, but it is not sent to the model. Deleting the last mention of a name mutes what it brought; writing the name back - typed, pasted, undone, picked from the prompt menu or pressed on the shelf - brings it live again, within the usual reference limits. A name still written whose file is muted was muted in the row on purpose, and a second mention leaves it so; the row's mute switch is the way back, there and for a shared pool file. Reopening a saved workflow changes no mute. If every source of a cited member is unavailable, untouched default rows such as face and hair do not count as a description: enable a source or give the member an actual description before rendering.

A member can also wear a LoRA. On the open card, under the tiles, the line wears holds the LoRAs hung on them - + LoRA opens the LoRA manager on the member's own stack - and each chip says the file, its weight and its trigger words. A LoRA on a person goes on the model in every shot that names them and no other, with its trigger words put in front of that shot's prompt; a shot that never cites them is not patched with it. The chip's menu holds the trigger words and a weight slider, a mute, and the way off; Set up in the LoRA manager reaches the full card - the wide weight range, which checkpoint it claims, the words its sidecar suggests. A member with a LoRA and a trigger word and nothing else is a valid member: the definition line binds their label to the word (<Subject 1> is the person, ohwx anna). A shot's own stack entry for the same file wins over the member's, the way it wins over the piece's. The LoRA is kept with the member in the cast library, weight and words included, and comes back with them into any piece; the library's own sheet edits it under Wearing.

To have somebody perform an action the way another person does it, hang the clip or still of that person on them as "their action comes from this", and say what the action is on the tile. (The blob and the prompt keep the guide's own word for it, motion.) The definition then reads "whose appearance comes from Picture 1 and whose motion comes from Video 1 (the golf swing)", and the retention line says the movement is followed. Several files are several actions - the swing on a clip, the smoking gesture on a sheet - and each can wake on its own words.

Saved references (RefMods)

A picture's reference tokens ride through every sampling step, and a member built out of three stills at max is several thousand tokens. The ledger under a member's tiles says what their looks cost a render — Encoded on every render · MiniMax H3 · 2 pictures + 1 clip at max · ≈8,200+ tokens — and offers Save as RefMod. A RefMod is a reference encoded once and kept as a file: the saved-latent format ComfyUI-MiniMaxH3Mod reads and writes, so a character made or downloaded there works here and one saved here loads in their nodes (their newer one-reference bundles read too; a bundle of several is refused by count).

A mod is for one family. A latent belongs to one VAE: an H3 mod is a tensor in the H3 video VAE's space and means nothing to Flux 2 Klein, whose references are Flux 2 VAE latents. So the picture stays the member's look, and it carries its saved renditions, one per family that keeps them — refmods/cast/anna for H3, refmods/cast/anna.flux2 for Klein — and the family rendering the picture reads the one in its own space, or encodes the picture as it always has. Nothing about that is chosen at render time by anyone: a clip on an H3 piece reads the H3 mod, a chat still drawn on Klein reads the Klein mod, a family with neither reads the picture. The save menu is a section per family this machine can encode for (the piece's own first, the others by the VAE remembered in their weights controls), each row naming what it would cost there; a tile wears mod when it carries one for the piece's family, and the shut line's amber count is that family's. Families that keep none — Ideogram is an API, LTX 2.5 reads one composited sheet per card — are not offered. With more than one family's VAE picked the menu leads with Every family: the same pictures through each VAE, one job after the other. A picture framed again forgets its renditions: they were latents of the old window.

Downloaded Klein sets. The Flux 2 Klein files on malcolmrey's browser (fk9_<name>_v1_refmod.safetensors) are picture sets — a batch of twenty or so latents of one person, made by his ComfyUI-Flux2Klein9Mod — and they read here as one RefMod of that many members (DainamoLabs' ComfyUI-FluxKleinRefMods files too). Dropped on the Cast tab's Import they cast a member as an H3 mod does; on a Klein still that member's set rides in as one reference slot, every member chained onto the conditioning the way both Klein packs apply it, costing every member's cells. On an H3 clip the same member is their words — a Klein latent is nothing to H3, and the render says so by name rather than reading it.

The menu's shapes, and what each costs:

• One file — everything stacked. Every still and clip in their looks, each pooled to a 16×16 grid, laid end to end as one video RefMod — which is what that pack's own vanellope_example is (four photos and three clips, 44 frames). One portable file that includes their motion, cited as one <Video n>. Not a budget move: a still is 64 tokens, a clip is six frames of them, and the whole is fitted under 5,120 by thinning the clips.
• Compressed, per picture: the encode pooled to a 48-grid and refined against it, a few hundred tokens — 432 for a 3:4 portrait. Renders like Full at under half the cost. Pooled any further a face comes back with colour stains (the sibling pack's 16-grid is 48 tokens for that portrait, and unusable for a person), which is why the grid is where it is. Stills only.
• Full, per picture: the encode at a 1024 short edge, about a thousand tokens. Stills only. On Flux 2 Klein the same two rows are the family's own numbers — a 1 MP picture is a 64×64 grid there and every cell is a token, so Full is 4,096 and Compressed (a 32-grid) a quarter of it.
• Each clip — its own file. A clip encoded whole at the 768 reference canvas, up to a minute of it, kept as one video RefMod and cited as one <Video n>: long motion for a few hundred tokens a frame, read off the file instead of decoded every render — the shape the sibling pack's own motion references take (issue #53). The route also takes capture: "motion", their frame-difference capture, which nothing in the UI offers yet. H3 only: a still family has no time axis.

Either way the render reads the latent off the file and shows the model a picture decoded from it as the label it cites.

The per-picture shapes hang the mod on the picture: the member's looks, the handles in the prompt and the words on each file are untouched, and the ledger reads Saved as a RefMod · MiniMax H3 · compressed · 432 tokens · refmods/cast/anna with Download and Show in library beside it. The stack is the exception, as it always was: one file in the place of every still and clip, and the pictures leave the piece unless another member or a hand-written @handle still needs them. A mod tile wears mod where a picture's would wear max, and its menu hands out the .safetensors. A shut line shows the cost too, amber once every look is a mod.

Importing a RefMod is casting them. A RefMod is a character, so a .safetensors dropped on the Cast tab's Import — or the picker's RefMod tab — lands in models/refmods and a member is made out of it on the spot, named after the file and described from its header, and their page opens — Cast @name into this piece is at its foot. Importing the same file twice is still one member. The Cast tab's right-hand column is Saved references: every RefMod on the machine, what each costs, which members are built out of it. A stray one's menu casts it (or opens their page), hangs it on an existing member, downloads it, renames or moves it (members follow), rewrites the description in its header, or deletes it. A member's own page lists their files as rows — role, filename, words, and how each is encoded — with the same ledger under them, and Pick a saved reference attaches a mod already on the machine. The picker's RefMod tab has the same import.

What a mod is not: a concept extractor. Pooling keeps colour, build and large structure and loses fine detail, and nothing about it stops identity, clothing and background mixing any more than a picture does — that is still what the member's words and takes are for. Audio mods are not taken; a voice is bound as a file. Saving for a family needs that family's VAE picked in its weights control; a mod made elsewhere needs nothing. A mod file on its own is a reference only where its family renders — a member built out of an H3 mod alone is their words in a Klein still, since a still family loads its pictures by name and a mod is a latent.

A cast member can be swapped for another with Recast from library at the foot of their card: the replacement takes over their clips, their slot in the cast order, and every sentence that named the old name is rewritten to the new one. Removing a member removes only what they were built out of (their pictures, voice, movement clips); footage they were cast into stays attached.

Screens

When a shot has a phone, a tablet, a laptop, a monitor or a TV in it that should show something specific, press Add screen on the rail and pick the picture or clip it should show. The screen gets a handle, @phone-1 or @laptop-1 after its device, and you write it into the prompt where the screen is, the way you cite an attachment: "a woman holds up her phone; the screen shows @phone-1". Typing @ offers it. Nothing is added to the prompt for you, so a screen the prompt never cites is refused with a warning under the box. Changing a screen's device renames its handle, and the prompt with it.

The model never sees your file. It is shown a flat green placeholder where you cited the screen, and after the render the screen pass finds the green in every frame and puts your file on it. Text on the screen comes out as sharp as the file itself, even on a fast, low-resolution render.

Press a screen's chip to set it up. The pair at the top of the popover is the whole idea: what the model is shown on the left, what replaces it on the right. Under it:

• Device sets the placeholder's shape, from a tall phone to a 16:9 TV, or any ratio up to 4:1 as Custom.
• Fit fills the screen and crops what overhangs, fits the whole file in with black bars, or stretches it.
• For a clip: where it starts, what happens if it runs out (hold the last frame, loop, or go back to the first), and whether it keeps playing or starts over at a cut the model makes inside the shot.

A shot can have two screens. The second is keyed in a second colour, so the two can be told apart. Anything that passes in front of a screen (a hand, a person walking by) stays in front of it. H3's own dynamic island stays on top of a phone screen; its home bar is covered.

Screens work on MiniMax H3 and on every still model that takes reference pictures (Qwen Image Edit, Flux 2 Klein, Qwen Image 2.1, and Krea 2 with its reference adapter). Each screen takes one reference slot. They are not available on LTX 2.5, whose references ride as one sheet, or on a pass that merges several cards.

The placeholder's colour and markers are a setting (Settings → Rendering → Screens). Plain green is the default and came out cleanest. White with a marker grid follows a screen better while something covers most of it for a long stretch. Screen files there can also keep the raw render and an overlay of what the pass saw, beside the finished file, for when a screen comes out wrong.

Spoken lines

Close a quote in the prompt and a small menu opens:

• Spoken turns the words into an actual line of dialogue, in the exact form H3 was trained to voice. You pick who says it (from the cast, or a description typed on the spot), in which language, and how: says, asks, replies, whispers, shouts, sings, or an off-screen voiceover.
• Written in the picture leaves the quotes alone, because plain double quotes are already how you ask for a sign, a banner or a subtitle.

A spoken line is drawn with a rule down its left edge in the speaker's colour (dashed for a voiceover). Press it to edit the words, the speaker, the language or the delivery, or to turn it back into on-screen text.

Variations

Braces holding alternatives separated by bars are one prompt that can become many videos:

@anna walks {along the beach|through a mansion} {at dawn|at dusk|at night},
{medium shot|close-up}, and {laughs|frowns}

The seed decides. Every render picks one alternative from each group, the same seed always picks the same ones, and rolling the seed (the seed pill's randomize does it on every render) is what asks for a new combination. Groups nest - {on the beach {in the shade|in hard sun}|in a mansion {at night|by day}} - an alternative may be empty ({|, smiling} sometimes adds the smile), and a cast member or a file is an alternative like any other word: {@anna|@ben} turns to the camera casts whoever is picked, and only their files ride into the shot. A file named only inside an alternative the seed passes over is muted for that render, and its chip on the reference row is greyed to say so. A brace pair with no bar in it is ordinary text.

The box shows the choice as you type: the braces and bars take the accent colour, and the alternatives this seed passes over fade, so what stands at full strength is the shot the next Render makes. What the model reads shows the finished prompt with the choice made.

On a timeline every card chooses on its own, so one sentence on three cards gives three scenarios; a card retaken on its own seed chooses on that seed. A group in the global prompt is chosen once for the whole piece, because the standing description is one description. Refine keeps every group and may expand the alternatives inside it; a rewrite that quietly settled a choice is reported under the panel, like a dropped quote.

Refine

The Refine button rewrites your sentence into the long, structured description the target family was trained on, and puts the result in an editable box under the prompt. It is a button rather than a queue-time step so you see what the model will read before minutes of sampling. Everything you named survives the rewrite; quoted words are checked mechanically and carried through verbatim.

Two ways to run it, chosen in the refiner's settings:

• This ComfyUI: a small Qwen3-VL text encoder loaded in-process, evicted like any other model when the sampler needs the VRAM. See models.md for the file.
• A server: any OpenAI-compatible endpoint - LM Studio, Ollama, llama.cpp, vLLM, or a hosted API with a key. The key is stored server-side on your machine, never in the browser or a workflow file. "Eject when done" asks a local server to unload the model as soon as the rewrite is in, so the sampler gets the memory back. Reasoning is asked off; a build that thinks anyway (Ollama's Qwen3-VL tags do) needs a larger reply length than the default, or it spends the whole reply on the trace and returns nothing.

Your own prompting

Put a .md file in the node's creator/skills/ folder and the refiner's settings offer it by name, either added to the built-in prompting or replacing it outright. A file can pick its mode in its own frontmatter (mode: replace). Agent skill packages (.skill) go in the same folder.

The pre-stage

The pipeline eats stills: start frames, end frames, references. The pre-stage pill spawns a second card that generates them on the same canvas, with any of the stills families (Krea 2, Ideogram 4.0, Qwen Image Edit, Flux 2 Klein) or H3 itself. Its result card writes the finished still straight into the shot as a start frame, end frame or reference, or back into the pre-stage as the next edit's subject. With an edit model, edit on the result is one press, and editing the edit is most of what an edit model is for.

One Queue runs both cards; an untouched pre-stage is a cache hit and doesn't re-render.

Sampler row extras

• Turbo engages the family's distillation (a LoRA on H3 and Qwen Image Edit, a checkpoint swap on Krea 2 and Flux 2 Klein) and presets the sampler row. Releasing it restores your row exactly.
• Faces runs a second small generation per pass: each face is tracked, cropped, re-drawn at 512 px and pasted back under a feathered mask. Needs the SAM 3 checkpoint.
• VDN-H3 samples the shot through Video Delta Net: nearby frames keep exact attention and the rest of the shot goes through a linear-attention branch, so the cost grows with the length of a shot instead of squaring. Pick a stage from models/vdn (see models); the port that runs it ships with the pack. It is for long shots — under about fifteen latent frames it falls back to plain attention and only costs — and it is slower per step than the int8 attention routes, so a strip of two-second cards gains nothing from it and a strip of fifteen-second ones does. Throwing the pill throws turbo with it: the stage's own 8-step adapter is the distillation, so the row is set to 8 steps, er_sde + beta on the checkpoints' own shifts (the port's example row), the turbo file is left off the run and the quality stops are not drawn. Turbo off under VDN is the 50-step stage. Switching VDN off gives the row back to the turbo file, or releases the switch if the pill was what threw it. The turbo lead-in holds the adapter off for its opening steps the way it holds the file off. Does not combine with sage attention (both replace the same forward) or with SLA (its windows run exact attention, so there would be nothing to sparsify); kitchen attention, the caches, Spectrum and low vram compose.
• Attention is one pill with four positions, because a model has one attention: the checkpoint's own, sage (KJNodes, quantized), kitchen (core's int8 kernel, nothing to install) and sla — block-sparse attention from ComfyUI-PlagueKind-Nodes, which attends a fraction of the key blocks rather than a cheaper kernel over all of them. SLA is at the pack's own tuning, pays off in proportion to how long and large the shot is (short ones fall back to dense on their own), and is the inference path the lightx2v SLA turbo LoRA was distilled against, so it is at its best with that LoRA on the stack. It needs Triton; the pack registers the node only where it can run.
• Accelerator pills (caches, sage attention, low vram, and so on) appear when the matching optional pack is installed. All caches trade fidelity for speed, so A/B against a native render before trusting one on a final piece.

Sampling on two GPUs

H3 can sample one shot across several cards, which on a pair is roughly half the wall clock. Install the Raylight community fork, since the upstream Raylight has no H3 path, and a Sampling row appears at the top of the weights popover. Pick Raylight · 2 GPUs and queue as usual: the checkpoint is loaded into one Ray worker per card and the sequence is split across them, while the prompt is still encoded and the video still decoded on your own card. Preview frames keep working if you have KJNodes and taeh3.safetensors.

It carries the first sampling pass and nothing else. These are refused before the queue starts, with a message saying what to switch off, rather than quietly dropped from the render:

• the refine (two-pass upscale), faces and re-detail passes,
• the turbo lead-in,
• sound seams on a ComfyUI build without native audio-guide support,
• ControlNet guides: they reach H3 through the conditioning, so they would arrive intact and then be ignored by Raylight's own forward pass,
• every accelerator except sage attention, which Raylight runs itself,
• device pins from ComfyUI-MultiGPU: the Ray workers want the cards,
• a strip that routes to both checkpoints. Force the route to Ref2VA; it takes everything FL2VA does.

Blended sound seams use native audio keyframes on compatible ComfyUI builds, including a shot continuing the previous soundtrack or joining a supplied clip's sound. Continuity checks that fractional audio anchors and mixed keyframe/reference payloads work before queueing; older or incompatible cores refuse the seam with an update or single-GPU option. Ordinary audio references and unblended sound seams keep their existing reference behavior. This path is verified at the CPU conditioning and layout level; multi-GPU generation and audio quality have not been verified.

One thing changes without being refused: LoRAs are merged inside the workers by ComfyUI's own loader instead of this pack's H3 stack, which is worse on quantized checkpoints. Picture seams, the sigma shift, GGUF checkpoints and everything the compiler does are unaffected.

The pre-stage's stills always sample on one card. Starting a Ray cluster to make one frame costs far more than it saves.