alisson-anjos-ComfyUI-BFSNodes/web/js/docs/BFSShotPlanner.md

BFS Shot Planner / Shot Loop

Turn a long video into shots a video model can actually follow, give every shot its own reference image and prompt, run the rest of the workflow once per shot, and join the results back into one video with the original timing and soundtrack.

Why

A video model only follows a guide reliably inside the clip length it was trained on. An H3 body-swap LoRA trained on 107-frame clips keeps the scene, framing and motion at 4.5 s and loses them at 10 s, where it starts summarising the clip instead of following it frame by frame. Splitting the source into model-sized shots, at camera cuts when there are any, keeps every shot inside that range.

Nodes

node	what it does
BFS Shot Planner	Pick a video, split it on a timeline, set a reference and prompt per shot. Outputs the shots as a ComfyUI list.
BFS Shot Unpack	Opens one shot into plain values: guide frames, reference pictures (a list), prompt, length, first frame, audio, size, index. Use it with any model.
BFS Shot Repack	Puts edited pieces back into a shot: Unpack's shot output goes to Repack's shot, the edited piece (e.g. the reference with its background removed) to its input. Unconnected inputs keep their values; timing, cuts and audio are unchanged.
BFS Shot H3 Conditioning	The common MiniMax H3 path with the important controls only: aligned Add Guide and/or native video reference, references, optional audio conditioning, the Planner's inpaint mode and source-subject blur.
BFS Shot H3 Conditioning (Advanced)	The full conditioning node. Adds the setting reference, the first-frame anchor and the experimental mask-guide controls; its model input passes through to model (older workflows routed the model through it). The duet lives in BFS Shot H3 Duet (1.113 took it out of this node).
BFS Shot Join	Concatenates the decoded shots in order, trims each to its true length, cross-fades soft joins and returns the soundtrack. With comparison on it also returns a side-by-side video (original shot | references | result) with the shot's info and your label on top and its prompt below, ready for Create Video. save to = mp4 file writes the video (and the comparison) straight to MP4 files instead, one shot in memory at a time (long videos); video_path gives the file.
BFS Shot H3 Duet	Renders one shot with H3: the shot's clip pinned beside the video (duet, no LoRA), the shot as an aligned guide (for body-swap LoRAs), or both.

The panel

Use the language selector in the top bar to switch the interface between English, Portuguese, Spanish and Simplified Chinese. The choice is saved in this browser and does not alter the workflow plan or prompt text. Tour opens an optional step-by-step introduction when clicked; it never appears automatically.

The planner's panel has five tabs, in the order you work. The timeline stays on top of every tab.

tab	what is there
🎞 Video	pick or upload the video, audio, how it is split into shots (cuts or fixed length), generation size
🎬 Shots	one card per shot (scroll sideways, ← → move between shots), the preview player and the selected shot's editor: reference & prompt, who is replaced (mask, generation mode, {target}), continuity, Copy to other shots
👥 People / Filters / Masks	the cast found by face, shot filters and the global mask settings
📝 Prompts & refs	the global reference and prompt, the VLM and the reference descriptions ({details})
▶ Run	Checks (what to fix before running, with a button to each shot) and how the shots run (shot by shot / queue loop / auto loop)

Shot cards show badges for what each shot has: 🎯 mask, 🎭 / ✂ generation mode, 🧑 {target}, ⛓ continuity and ⚠ problems. The header's ⚠ count opens the checks.

Copy to other shots (in the shot editor) copies the chosen parts of the selected shot to all shots, or to the shots after it: references, prompt, mask text, mask points (each shot gets them on its frame at the same relative position), generation mode, {target}, continuity. It replaces the old "→ all" buttons.

How the loop works

ComfyUI runs any node that receives a list once per item and pairs several lists by index. The planner's shots output is a list, so everything downstream of it (conditioning, sampler, decode) runs once per shot, and shot i always gets guide i, reference i and prompt i. Single values such as the model and VAE are shared by every run. The join takes the whole list back (it is an INPUT_IS_LIST node) and puts the video together.

Three run modes:

• One run, shot by shot (default): one Queue renders every shot in order inside the same run. Each shot is stored on disk; then BFS Shot Join expands the part of the graph between the planner and itself (ComfyUI node expansion) for the next shot, so that shot is conditioned after the previous one exists and continuity (head / history) works. No browser re-queue (the tab can be closed), Save Video fires once with the full video, and after a failure a new Queue resumes from the stored shots (Redo all regenerates every shot). Previews connected inside the shot's part of the graph show every shot. Needs exactly one BFS Shot Planner before the join. Same idea as the recursive loop of Ethanfel's MiniMax H3 Context Loop.
• Queue loop (one shot per run): each run generates the next pending shot and stores it on disk. The join blocks every node after it until the last shot, then outputs the full video, so a Save Video node only fires once. With Auto-queue the next shot on (default), the panel re-queues the workflow after each shot, so one click still renders the whole video (keep the ComfyUI tab open: the panel does the re-queue). Redo all regenerates every shot. Changing the plan starts a new run. It resumes from the stored shots after a failure, and continuity head / history needs it: each shot reads the result of the one before.
• Auto loop (all shots at once): every shot in one queue run, each node runs for every shot before the next node. Holds all decoded shots in memory. Continuity head / history does not work here (all shots are conditioned before any is sampled).

Memory

• Status at the top (🧠) and a Memory card in the Run tab. BFS Shot Join records every shot it receives on this GPU: its size (latent tokens = generated frames, with the continuity head, × resolution) and the peak VRAM of its run. Before running, every planned shot is compared with the biggest shot that already ran on this GPU: ✓ within it, a bit bigger (it will probably fit, maybe slower), or ⚠ may run out of memory (also listed in Checks). There is no fixed "GB per frame" for H3 (ComfyUI offloads weights as needed), so nothing is guessed: until a first shot has run, the status says no memory data yet. The record lives in ComfyUI's user/bfs_shotloop_vram.json.
• Between shots (Run tab, shot by shot and queue loop): keep models loaded (fastest) or free memory, which unloads every model and empties the GPU after each shot so the next one starts clean (low VRAM, or a later shot that runs out of memory); models load again for every shot, so it is slower.
• What makes a shot lighter: lower Megapixels, a shorter Max seconds / shot, head 5 instead of 22 (the head adds its frames to every shot), Crop (the generation is the subject's box), and ComfyUI's own options (--lowvram, fp8 / GGUF weights, tiled VAE decode).
• The final join (after the last shot) is where long videos used to run out of RAM (not VRAM: the process is killed, e.g. Terminated under WSL). It now reads one stored shot at a time into the final video. Measured on 11 shots at 960×544 (~50 s): +15.8 GB before, +8.2 GB now with save to = images (that is the video itself, which an IMAGE output must hold), and +2.1 GB with save to = mp4 file, which streams the video to ffmpeg and stays at about one shot whatever the length (also with the comparison, which is streamed 16 frames at a time: +2.1 GB measured at comparison_height 1024, against ~32 GB as images). For long videos use mp4 file (BFS Shot Join), or the panel's Combine.
• RAM guard: before an images join, BFS Shot Join asks ComfyUI's cache to drop earlier outputs and estimates what the video (and the comparison) need; when that does not fit in the free RAM it writes MP4 files instead and says so in the console, instead of the whole ComfyUI being killed.
• The outputs are never empty: with mp4 file (chosen or by the RAM guard) the images and comparison outputs still carry the video, read back from the written files at a size that fits the free RAM (the console says the scale; the files keep the full size), the join shows the files on its node, and video_path gives the path.
• Default: save_to = images (the result comes out inside ComfyUI, for the next nodes). The panel's Checks warn when the video is long for this machine (as images it needs about 12 bytes per pixel per frame, ~3.5x with the comparison, against the free RAM) and advise mp4 file for that video.
• comparison_height is the height of each column: the comparison is three columns wide plus text bars, so it costs about 3× the video at the same height. 360–512 is plenty to review a long video.

Stored shots (cache, redo, combine)

In the shot by shot and queue loop runs every generated shot is stored, and the Run tab's Stored shots card manages them.

• Shot cache: Keep (default) stores them in ComfyUI's output folder, output/bfs_shotloop/<run>: they survive a restart, so a stopped run resumes and a single shot can be redone. Temp uses ComfyUI's temp folder, which ComfyUI empties at every start (before 1.104 every run was stored there).

• Shot storage (the format of each stored shot, measured on 145 frames at 1280×720):

  Storage	Size	Quality
  Lossless (FFV1, default)	~34 MB	exact: the final video is unchanged
  Smaller (H.264 RGB, crf 8)	~21 MB	visually lossless (PSNR ~52 dB)
  Smallest (H.264 RGB, crf 14)	~9 MB	light loss (PSNR ~48 dB)
  Raw frames (.pt)	~401 MB	exact; needs no ffmpeg

  The final video of a stored run is assembled from the stored shots, and the continuity head reads them: a lossy storage reaches the output (the panel warns). Without ffmpeg a shot falls back to raw frames. With comparison on, the shot's source frames for the comparison's original column are kept as shot_NNNN_orig.mkv (visually lossless: they are only shown); the .pt itself holds only the shot's info (a few KB).

• One folder per source video. Each shot remembers the settings it was made with (its range, prompt, references, mask, crop, continuity, the generation size, the global prompt / references and the references or prompt connected to the planner). The next Queue runs only the shots that are not stored or whose settings changed, plus the shots that continue from a shot that was made again (head, history, previous shot as reference / first frame), so every seam matches. Shot cards show 💾 (stored, up to date) or ⏳ (runs next time).

• Model, LoRA, seed, sampler (1.112.0): the planner reads them from the queued workflow (every node that feeds BFS Shot Join's images: loaders, LoRAs, sampler, seed, conditioning settings), so changing any of them runs every shot again. The join's own settings (crossfade, comparison) don't. A seed set to randomize changes on every Queue, so every Queue then runs every shot; fix the seed to keep the stored shots.

• ↻ Redo a shot (Stored shots card): it runs again on the next Queue, and the shots that continue from it run after it. Tick ↻ redoes only that shot to keep the next shots as they are (the seam after it may then not match).

• 🎬 Combine stored shots: puts the stored shots together into an MP4 in the output folder now, without generating (one shot in memory at a time), on the plan's timeline: the soundtrack, the original video where a shot is skipped, and also where a shot is not stored yet or out of date, so it previews a run in progress. A link to the file appears in the card.

• When every shot is stored, a Queue still runs the last shot again so the join can output the video: use Combine to only assemble.

• Recovering a run outside ComfyUI (e.g. ComfyUI was killed during the final join): python tools/bfs_assemble_shots.py output/bfs_shotloop/<run> video.mp4 --audio input/<source video> (ComfyUI's Python, ffmpeg on the PATH) does the same as Combine with one shot in memory; it reads the old raw .pt shots too.

Guide frames and lengths

Each shot is generated at a length the model accepts (frame grid: H3 17n+5, LTX/Wan 8n+1, Wan 4n+1, or any). When a shot is shorter than that length, the extra guide frames come from the video that follows it, so the guide never repeats or stretches. The join cuts each result back to the shot's own frames, which keeps the timing identical to the source. Those extra frames are also a real overlap, which the join uses to cross-fade boundaries that are not camera cuts.

Splitting

• Camera cuts (default): cuts from PySceneDetect (adaptive or content; install scenedetect), or the built-in detector when the package is missing. Shots shorter than the minimum merge into a neighbour when the merge still fits; shots longer than the maximum split into equal parts.
• Fixed length: equal parts no longer than the maximum.
• One shot (whole range): the whole selected range as a single shot, whatever its length; Max seconds / shot is not applied. For "N seconds in one piece" set Range length, seconds = N, right next to the mode (it moves the end frame). For pieces of at most X seconds use Fixed length with Max seconds / shot = X.
• By hand: drag the white handles on the timeline to move a boundary, double-click the shot bar to split, ⇥ Merge to join, or select a shot and press Delete to remove the cut at its start (it merges into the previous shot). Your edits are what runs.

Range (🎞 Video tab, with its own player): Start frame / End frame (timeline frames; end 0 = the end of the video) limit the plan to a part of the video, before anything is split, analysed or generated. Play or scrub the player (or click the timeline) and press ⇤ start here / ⇥ end here to take its exact frame. The timeline dims what is outside; the join and the soundtrack cover only the range.

Max seconds / shot is converted to frames and snapped down to the grid (4.5 s at 24 fps = 107 frames for H3). Max shots in the Video tab caps how many shots are used.

Audio

The source card shows whether the video has a usable audio track (rate, channels) or why not. Use the video's audio or silent track. Without a usable track (none, unreadable, or silent chosen) the planner's audio, BFS Shot Join's audio and the H3 Duet nodes return a silent track of the right length instead of nothing, so Create Video / Save Video always work. Audio is read with ffmpeg, or with PyAV when the ffmpeg binary is missing.

Preview

Play shot plays only the selected shot, from its first to its last frame, and stops (or loops with loop shot); every shot card has its own ▶. Play all plays the whole plan and jumps over shots that will not run. The panel shows the shot's start, end and current time (and frame), a yellow playhead follows on the timeline, and clicking the timeline seeks. The source video streams from the input folder, so only what you play is loaded.

Shot filters (People / Filters / Masks tab)

Skip shots that should not run, decided per shot from a few sampled frames:

filter	skips a shot when
Needs a person	no person is detected
Min person size	the largest person covers less than that fraction of the frame (wide shots)
Max people	more people than that (crowds)
Needs a face	no face is detected
Skip dark / fades	the mean brightness is below the level
Skip static	there is almost no motion (title cards, freeze frames)
Min frames	the shot is shorter than that

People and faces use YOLO from models/ultralytics (person_yolov8m-seg.pt, face_yolov8m.pt, the Impact Pack files) with OpenCV fallbacks. Analyse people & faces shows the numbers on every shot card. Each shot can override the filters (always run / always skip).

Skipped shots do not run. Connect the planner's timeline output to BFS Shot Join and they are filled with the original video, keeping the full duration and soundtrack, or removed (with the matching audio) when Skipped shots in the output is set to remove them.

Cast (people by face)

Find people samples the video every 0.5 s, detects faces and groups them into people by face identity, on the CPU (it never touches the GPU; the result is cached per video). No extra package is needed: by default it uses OpenCV Zoo's YuNet (detection) + SFace (recognition), Apache-2.0 models run by OpenCV itself and downloaded once into models/opencv_face (0.2 + 37 MB). If InsightFace is installed (buffalo_l in models/insightface) it is used instead (a bit more accurate; mind its license). Last resort, without either: SAM 3.1 faces grouped by colours (hair, skin, clothes). Each person card shows the face, screen share and first/last appearance (click the face to seek). The ignore checkbox excludes a detected identity from cast-based filters. Every shot card shows the people detected in it, with the main person highlighted.

option	effect
Split where the main person changes	adds a boundary where the largest face switches to another person for at least a second, then re-splits
Only run shots with a detected person	shots with no detected, non-ignored person are skipped

Face identities are used for filtering and optional shot splitting. References and marker colors are selected globally or per shot; they are not assigned to detected identities.

References and prompts

Up to 12 reference pictures (1.113.0): the global list starts with one slot and + adds more; they are <Picture 1> to <Picture 12>, in order. Click a slot to upload a picture (the + takes several files at once), or drop image files on a slot (replaces it) or anywhere on the box (adds them). A filled slot has ✕: a global picture is taken out (the next ones move up), a shot's own picture falls back to the global one.

Every shot can have its own pictures and prompt. A shot's empty slot uses the global picture at the same position (shown faded), so a shot can change only <Picture 2> and keep the rest. Copy to other shots gives a shot's pictures to every shot. The last ten pictures you picked are shown under the shot editor: click = picture 1, shift+click = add it as the next picture, or drag it onto any slot.

Under every prompt (global and per shot) there is a chip per picture: PictureN inserts <Picture N> at the cursor, 📝 inserts {details@Picture N} (that picture's description, below).

The node no longer has ref_image / ref_image_2 inputs (the pictures live in the panel); a workflow saved with them connected still runs, and the log says the images are ignored. A connected prompt input still overrides the global prompt. The planner outputs refs (every picture the shots use, without repeats, as a list) and ref_count where ref_image / ref_image_2 were. BFS Shot Unpack outputs refs, every picture of the shot as a list (the next node runs once per picture, e.g. a background remover), and ref_count; BFS Shot Repack's refs input takes that list back and gives each shot its own pictures (a workflow from before 1.113 that wired ref_image still works). BFS Shot H3 Conditioning passes every picture of the shot (the use_ref_2 switch left in 1.114: the pictures are chosen in the planner); H3's own node stops at 9 and LoRAs trained like OpenJutsu saw up to 9, so the log notes a shot with more.

Mask & crop (SAM 3)

Generate only part of the frame. In a shot's editor (Select region), type what to segment in English (person in white, woman with red hair, red car; up to 32 tokens, commas for several things) or click 🎯 Points to pick positive / negative points on any frame of the shot, then 👁 Preview (red = mask, yellow = crop box). Then pick how the shot is generated:

mode	what is generated	crop / uncrop
Full frame	the whole frame; the mask only feeds {target} and the setting picture	no
🧩 Frame + paste	the whole frame (so the model follows the guide's pose freely and the new person may be bigger); BFS Shot Join then pastes only the person onto the original frame: the shot's mask plus the new subject's outline (SAM 3 on the result with the shot's new subject text, default person; paste_new_outline)	no crop; paste in the Join
🎭 Mask only	only the mask, on the whole frame; everything else stays exactly as it was	no
✂ Crop	a box around the mask (more pixels for a small person); BFS Shot Join pastes it back	yes
✂🎭 Crop + mask	only the mask, inside the crop: the most detail with the background kept	yes

Frame + paste is the safest for a different body (e.g. a woman in profile replaced by a man facing the camera): Mask only binds the new person to the old outline, Frame + paste does not. The two mask modes need BFS Shot H3 Conditioning → inpaint = per shot (planner) (the default; only the mask forces it on every shot, off never). The crop is one box around the mask (the union over all its frames, so it does not shake), at the source resolution, sent to the model at the generation size; BFS Shot Join pastes the result back, feathered by the mask (or the whole box). BFS Shot Unpack also outputs the shot's mask (mask), e.g. for an inpainting model. In BFS Shot Join's comparison video, cropped shots show their mask (red) and crop box (yellow) over the original column (comparison_mask, on by default).

Mask opacity (mask modes, per shot, slider under the modes): the value of the white inside the generation mask. 1 regenerates the masked area completely. A grey mask (e.g. 0.85) keeps part of the original there: H3 puts those rows at opacity × the noise level, so they start from the original partly visible. 0.8-0.9 keeps pose, outline and lighting while still swapping; too low copies the original person. With guide_mode = aligned guide the model also sees the whole original shot as its guide, so it follows the motion either way.

🎨 Colored Mark is an optional translucent overlay on the source video: each marked person is tinted with the color of the picture they become, and the prompt gets the mapping ("the person marked in red becomes the character from <Picture 3>"), for any model or LoRA. Every picture has its Mark color (under it in Prompts & refs: green, purple, red, blue, yellow, magenta, cyan, orange, white, brown, pink, olive by default); change it when it is too close to a color in the video. In a shot, turn on Colored Mark and pick which picture the shot's selection (its SAM 3 text or points) becomes; + Mark another person adds a person with their own picture and text or 🎯 points (the points window has one point set per person). This is only a visual marker: it does not create an inpainting mask or change Full frame, Mask only or crop behavior. More than one marked person needs Crop off, and the shot must have every picture the marks use. The overlay keeps movement and facial expression visible. Plans before 1.113 (a second region for ref 2) open with that region as <Picture 2>.

body_swap: subject_definitions: <Subject 1> is the character shown in <Picture 1>, whose identity, face, head, hair or fur, skin, body shape, proportions and clothing define the green-marked replacement. <Subject 2> is the character shown in <Picture 2>, whose identity, face, head, hair or fur, skin, body shape, proportions and clothing define the purple-marked replacement. In the guide video, the translucent green and purple tints are temporary editing markers, not character appearance. Replace the green-tinted person only with <Subject 1> and the purple-tinted person only with <Subject 2>. The guide video provides the scene and the complete performance of both people, including their body poses, gestures, head motion, gaze, speech and facial expressions.

summary: [video generation + references] Replace the green-tinted guide person with <Subject 1> from <Picture 1> and the purple-tinted guide person with <Subject 2> from <Picture 2>, preserving the scene, camera and complete motion and expression of both people.

detailed_description: [Shot 1] Replace the person marked by the translucent green tint with <Subject 1> from <Picture 1>, and the person marked by the translucent purple tint with <Subject 2> from <Picture 2>. Each character follows that person's exact position, timing, body pose, gestures, head motion, gaze, speech and facial expressions in the guide. Remove both temporary color markers completely. Keep the two reference identities distinct and stable in every frame. Preserve their interaction, the background, lighting, camera and all unselected content from the guide video. Prevent identity drift, clothing changes, texture crawling and flicker. The result is a real, photographic video.

The VLM's shot analysis suggests a SAM 3 text selection from the original frames; it does not assign guide colors or decide that two detections are the same identity. Describe target only describes the first shot selection. For two-color swaps, choose both selections and identities yourself, and use the explicit mapping above (or let 🤖 Auto prompt write it: it is told which tinted person becomes which picture).

Mask guide (experimental, Mask only shots, BFS Shot H3 Conditioning → mask_guide): the shot with only the masked region visible, the rest grey, so the model looks at the subject's pose and outline on its own while the mask limits where it generates. + extra guide adds it as a second aligned guide next to the normal one (the model sees both); instead of the full guide replaces the normal one; + reference video gives it as a native reference video (<Video n>, after the shot's own one when guide_mode uses it; write {mask_video} in the prompt where its tag goes, otherwise a sentence is added). mask_guide_look sets what it shows of the subject: grey blurred (default: volume, light and head direction, no colours or face, so the model follows the motion without copying the old subject), colour (as it is; can make the model copy the old subject), silhouette (flat shape), edges (outlines) or pose (people) (the skeleton of the people in the mask, OpenPose colours; needs ultralytics and a YOLO pose model in models/ultralytics, e.g. pose/yolov8m-pose.pt). mask_ref_size makes that reference video smaller (default 1/2, ~1/4 of the tokens): it only has to show the pose and outline. Compare with off: the LoRAs were trained with one full guide, and it can also pull the old subject's look.

Masks from a video (rotoscoping) instead of SAM 3

A mask made elsewhere (After Effects Roto Brush, DaVinci Resolve Magic Mask, another ComfyUI workflow…) can replace SAM 3. It is a black and white video, white = the subject, and it works with every mode (Mask only, Crop, Crop + mask), {target}, the setting picture and the comparison overlay. Three places, the most specific wins:

where	covers	wins over
shot editor → 🎞 mask video	only that shot (its first frame = the shot's first frame)	everything
the shot's own SAM 3 text / points	that shot	the two below
the planner's optional mask input (MASK or IMAGE batch, e.g. Load Video + Convert Image to Mask)	the whole video, one mask per source frame	the panel's mask video
People / Filters / Masks → 🎞 Mask video (whole video)	the whole video, matched by time	SAM 3 for shots without a mask

Any size and frame rate: it is matched to the shot by time and resized. The console says which mask each shot used.

Stitch finishing (BFS Shot Join, cropped shots only; adapted from Neko (Nekodificador)'s NKD Inpaint Stitch, MIT, built on AbleJones's workflow and nodes):

Option	What it does
edge_hardness (0-1)	hardens the soft edge of the paste; raise it when a faint ghost of the original person shows around the new one
match_colors (0-1)	corrects the colour / brightness drift of the generated patch (Reinhard in LAB), with statistics over the whole shot so it does not flicker
match_region	around the subject (swap): measured on a ring of background around the mask, so a new person keeps their own colours. inside the subject: measured inside the mask, for retouching the same content
seamless_edges	Poisson blend (OpenCV) for stubborn seams; slower

Which mode. A generation mask alone keeps the background exact but generates the person at the frame's own size, so a small person gets few pixels; a crop alone gives the person more resolution, but the whole box is regenerated and pasted back (that is what the finishing above is for). Mask only is the simplest when the person fills a good part of the frame; Crop + mask is best for small people. In the mask modes the latent starts from the shot's own frames and its SAM 3 mask (grown by expand plus one latent cell) becomes the H3 generation mask. Raise expand when the new person is bigger than the old one (longer hair, wider body): the generated area cannot go past the grown mask; their shadow or reflection outside the mask stays from the original.

Credit to Neko (Nekodificador) and AbleJones, whose workflow and nodes the crop + generation mask follows. ComfyUI builds without native H3 generation masks need a per-row mask patch on the model (e.g. ComfyUI-MiniMaxH3-PerRowMasking).

The People / Filters / Masks tab holds the global mask settings, with defaults that work as they are: fill holes on, temporal expand 2 frames (less flicker), expand 16 px, feather 12 px, padding 15 %, paste the whole box with feathered edges, blockify off (16 aligns the mask to H3's latent grid), threshold 0.5, 4 objects. Show masks on shots overlays the preview on the shot cards. SAM 3 uses the official sam3.1_multiplex_fp16.safetensors in models/checkpoints, downloaded from Comfy-Org/sam3.1 the first time.

VLM suggestions

Connect a vision-language model to the planner's vlm input (CLIPLoader with qwen3vl_4b or qwen3vl_8b). It looks at a few frames of every shot and suggests what to segment, a description of the shot (camera, framing, action) and whether to run it. In the Prompts & refs tab: Use the VLM when the workflow runs applies the suggestions at run time (mask text for shots without one; {shot} in a prompt becomes that shot's description), Analyse shots asks from the panel (after one run with the VLM connected), and each shot's editor shows its suggestion with buttons to apply it. The summary output lists them too.

Describe references ({details})

The VLM can describe the references, for any task (not tied to swaps), and any subject: a person, a creature, a robot, an animal or a cartoon character (it says what the subject is first). In the Prompts & refs tab pick an instruction preset: object (a noun phrase for a prop, product, vehicle...: what it is, shape, materials, colors, text), short (the default: one noun phrase of at most ~20 words that fits inside a sentence, e.g. green goblin with long pointed ears in a torn brown leather vest, for <Subject 1> is the {details} shown in <Picture 1>), full body (face, hair, skin, age, build, clothing piece by piece), head / face, face attributes (a short comma-separated list), outfit, or custom (your own instruction). 📝 Describe refs writes one description per picture (see below), saved in the plan and editable. Write {details} anywhere in a prompt and every shot gets the description of its own first picture; a picture without a description is described by the VLM at run time (no click needed).

Image max side (VLM) controls the longest side of reference and shot images prepared for VLM analysis (1024 px by default). Aspect ratio is preserved; the model's own image processor may resize them further. Increase it when fine reference details matter, or lower it to reduce analysis cost. This does not change the generated video size.

When a shot has two references, the planner expands a one-reference template at run time to include <Subject 2> and {details2} for <Picture 2> (not when the prompt already names <Picture 2> or uses {details@Picture n}). Existing one-reference templates remain unchanged in shots with only one reference. You can also use {details2} explicitly in any template.

🤖 Auto prompt (1.113.0)

Visual edits and color bindings (1.115.4): the guide fixes the assigned performers' motion, action timing, head movement, gaze and expressions. Explicitly request the target style, background, lighting, weather, outfit or camera changes. For example: Replace the man with the goblin from <Picture 1>, render the whole scene in anime style, and use the hall from <Picture 2> as the setting. Keep the guide performance and timing. A setting can also be described in text. Use full frame generation for changes to the entire scene; masked generation only changes the generated region.

References can have different roles. In the example above, Picture 1 defines the character and Picture 2 defines the environment. To describe the latter, choose scene / setting in that picture's description preset. For several characters, bind colors only to their character references: The subject marked in green uses <Picture 1>; the subject marked in purple uses <Picture 2>; <Picture 3> defines the setting. Picture indices stay unchanged. A marking color identifies the same performer across position changes, occlusion and cuts; it is not a target skin/clothing color. Facial highlights are performance annotations. Prompt wording is generic and does not require a specific 2D/3D marking implementation. This update changes prompt writing, not the existing marking renderer or tracking behavior.

After updating, restart ComfyUI, hard-refresh the browser and click Write all prompts to regenerate previously written prompts with these rules. Existing written prompts are preserved until rewritten.

1.115.5: a setting replacement alone does not request a new rendering style. The writer preserves the source medium unless the actual request or an explicitly designated style reference changes it; instructional examples must not supply unrequested target attributes. For background replacement, use full-frame generation, disable paste/crop-only composition and inpainting outside a subject mask, set first_frame to none, and leave setting_ref off (that option adds the original source location). The full aligned guide still contains source scene geometry, so a correct prompt alone does not guarantee complete background replacement by a checkpoint.

In Prompts & refs → 🤖 Auto prompt, Write the prompts with the VLM turns the prompt boxes (global and per shot) into requests ("replace the bottle with the red can from Picture 2", "Picture 1 dances in the rain"), and the VLM writes each shot's MiniMax H3 prompt in the official full-reference format (MiniMaxAI/MiniMax-H3 docs/VIDEO_PROMPT_WRITING_GUIDE_ref_en.md): subject_definitions, summary with its task type, retention_analysis, detailed_description ([Shot 1], the official camera vocabulary, sounds in time), overall_soundscape and non_diegetic_music. It looks at:

• key frames of the shot with their times (Key frames: auto = about 1.5 per second, 3 to 8);
• the shot's pictures and their descriptions (Describe references);
• the request, the shot's Colored Marks (which tinted person becomes which picture; the mapping is added if the writer leaves a color out), its selection / {target} and its mode (Mask only: only the subject is regenerated; Crop: the frames are a crop);
• how the source is given: guide video (aligned guide, no tag) or <Video 1> (native reference video) — match the conditioning node's guide_mode.

Template: with Auto prompt on, the planner's prompt input (e.g. the template a LoRA was trained with, body_swap: subject_definitions: ...) is the template and the panel's text is the request applied to it ("Troque a mulher no vídeo pela mulher da <Picture 1>"). The template is kept as it is: same sentences, same order, its trigger word first; the writer applies the request, adds the pictures' visible features and, after [Shot 1], this shot's camera, place, light and actions. The panel's 🤖 Write uses the template of the last run (shown in the card). A request that is itself a whole prompt (H3 sections) is used as the template the same way. Style picks how a prompt without template is written: H3 official (the six sections) or OpenJutsu captions, the short style of the OpenJutsu training captions ("Replace the dog in the video with the gaunt goblin … from <Picture 1>. Replace the cat … from <Picture 2>. Keep the same background and location as in the video, and maintain the motion, camera angle, and timing."). Without a template, a short request gets the full six-section prompt. Without a VLM, the template (else the request) is the prompt.

Cuts: the writer gets the shot's real camera cuts (the planner's cut detector) and writes [Shot N] At MM:SS.mmm exactly there, with at least one key frame in each piece between cuts; a shot with no cut gets no timestamp at all. Labels always keep their < >.

🤖 Write all prompts (or only the missing) writes them now; each shot shows its written prompt in the Shots tab, editable, with 🤖 Write / Write again. A shot without one is written when the workflow runs (with the VLM on the planner, before any SAM 3 work) and the panel keeps it, so the next run uses the same text. When the request, pictures, marks, selection or mode change after a prompt was written, the shot says it is older; it is still used until you write it again. A written prompt is part of the stored shot's signature, so editing it re-renders the shot. Without a VLM and without a written prompt, the request is used as the prompt.

One description per picture (1.113.0)

Descriptions are per picture: 📝 Describe refs describes every picture the plan uses by itself, once per image. {details} is picture 1's description, {details2} picture 2's and {details@Picture n} (or {details@Picture3}) picture n's, so each shot gets the descriptions of its pictures. The dropdown next to the button sets what is described for every picture; a picture can have its own (e.g. full body for a character sheet, head / face for a close-up, outfit, or custom with its own instruction), and 🔄 describes only that picture again. A picture without a description is described at run time by the planner's VLM, else by the conditioning node's VLM, else it becomes "character". Descriptions saved by older plans (per reference set) are read as those pictures'.

Fit the prompt (on by default, next to 📝 Describe refs): the VLM gets the sentence of the prompt that holds the marker, with a blank in its place (e.g. <Subject 1> is the ___ shown in <Picture 1>), and writes the description for it, so the description adapts to the prompt and not the other way round (no "the A goblin", no paragraph inside a sentence). The panel buttons use the global prompt (or the shot's own); at run time the prompt the shot really uses.

The VLM buttons in the panel work after the workflow has run once with the VLM connected (ComfyUI only hands models to nodes when they run). Tested with Qwen3-VL 8B; some smaller or modified models return empty answers for some wordings: the planner retries with a reworded request and with sampling, but if a preset stays empty, use the 8B or another preset.

Settings reference

Every setting in the panel has a hover tooltip (ⓘ). The main ones:

setting	what it does
Mode	Camera cuts (shots start at cuts, long ones split evenly), fixed length, or one shot (the whole range)
Detector / Sensitivity	PySceneDetect adaptive or content, or the built-in one; higher sensitivity finds more cuts
Frame grid	frame counts the model accepts (H3 17n+5, LTX/Wan 8n+1, Wan 4n+1)
Max / Min seconds per shot	longest shot sent to the model; shorter shots merge into a neighbour
Timeline fps	the frame rate the planner works on (generation and audio use it)
Max shots	test on the first shots only
Generation size	Megapixels (default), source video resolution, or custom width and height; dimensions snap to the size multiple
Run	one run, shot by shot (default) / queue loop (one shot per run) / auto loop (all shots at once)
Skipped shots in the output	keep the original video there or remove those shots
Mask: padding / expand / feather / temporal expand / blockify	crop context, paste-back growth and softness, flicker hold, square blocks
Mask: threshold / max objects / paste back	SAM 3 text matching, objects tracked, paste only the mask or the whole box
VLM: frames per shot / max tokens / image max side	how much the VLM sees, its answer limit, and the longest side of images sent for analysis

One seed per shot: BFS Shot Seed (1.94.0)

A seed widget on the sampler gives every shot the SAME seed (the node runs once per shot with the same value). BFS Shot Seed (shot in, seed out) makes it a choice: same for every shot, increment per shot (seed, seed+1 ...) or random per shot (unrelated but repeatable seeds from the base seed). overrides pins single shots, e.g. 3:12345, 5:777, to keep the shots that came out well and re-roll only the others.

Structured starting noise: BFS Shot Noise (1.94.0, experimental)

Optional. BFS Shot Noise gives the NOISE for SamplerCustomAdvanced; with every amount at 0 it is exactly RandomNoise.

Input	What it does
shot_seed (+ shot, overrides)	the seed of each shot: same / increment / random per shot, as BFS Shot Seed
shared_base	the coarse pattern of the noise comes from base_seed: the same for every shot, at any resolution and any length (it is a tape along the timeline); the fine detail stays per shot. Put the seed of a result that worked in base_seed to keep its coarse noise
distribution	gaussian (default), laplacian, student-t or uniform, all at unit variance
spectrum_tilt	1/f^alpha spectrum: > 0 puts more energy in the large blobs ("fractal" noise), < 0 in the fine grain
pyramid	coarser layers of noise added on top
static_share	a part of the noise identical in every frame
guide_structure (vae, guide_frames, mask)	outside the mask, the guide's latent is mixed into the noise
ref_tint (vae, ref_image, mask)	inside the mask, the noise leans toward the reference's average latent

All mixes keep unit variance. The model was trained on plain noise: use small amounts and compare with 0.

{details} filled automatically (1.92.0)

A {details} in a shot's prompt is filled without pressing 📝 Describe refs: the planner's VLM describes the shot's references before any SAM 3 work; with no VLM on the planner, the slot is left for BFS Shot H3 Conditioning or BFS Shot H3 Duet, whose vlm input (the same Qwen3-VL CLIPLoader) describes them (the short preset, fitted to the sentence). Edited descriptions always win. With no VLM anywhere it becomes "character" and the log says so.

Source blur (1.91.0, finer in 1.110.0)

source_blur on BFS Shot H3 Conditioning (and its Simple version), BFS Shot H3 Duet, BFS H3 Duet and BFS H3 Duet Conditioning blurs the source person in what the model sees of the source (aligned guide, native reference video, duet panel): the model still reads the pose and the motion but has no face to copy, so the identity comes from the reference. The kept area of Mask only and the output are never blurred. Trick shared by JalenBrunson (Sapiens2 there) for reliable ref2v swaps.

Modes read <region> (<what stays sharp>):

region	what is blurred
face	the face (and neck)
head + hands	also the hair and the hands
person	the whole body: only for big changes, the pose then comes from the blurred shape
masked area	the shot's own mask (the person being replaced, with its expand); no extra segmentation. Without a mask on the shot (or in the plain Duet nodes) it blurs the whole person

sharp
keep mouth	lips, teeth and tongue stay sharp (the lips carry a lot of the likeness and the lip sync)
keep lips + tongue	the teeth are blurred too (always uses Sapiens2 for the lips)
mouth too	nothing stays sharp

source_blur_segmenter: SAM 3.1 (text prompts, already used by the planner; the 1.91 behaviour) or Sapiens2 (Meta's body-part segmentation, 28 classes with lips, teeth and tongue apart from the face; one pass for every part, finer around the mouth). Sapiens2 marks every person in the frame, like the SAM prompts here. Its weights (facebook/sapiens2-seg-0.4b, 1.6 GB) download to models/sapiens2/ the first time; it runs on the GPU in half precision and goes back to RAM after each shot. Sapiens2 License.

source_blur_effect: blur (no detail left) or invert colours (keeps the shapes and the expression but not the skin tone or the colours; some users get better likeness with it).

Big videos (upload)

ComfyUI refuses any single request bigger than --max-upload-size (100 MB by default), which is why big videos fail to upload in most nodes. The planner's ⬆ Upload (source video, mask videos, pictures) sends files of 32 MB or more in 8 MB pieces that are written straight to disk and assembled in the input folder, so any size works without changing how ComfyUI is started (a dropped piece is sent again). For other nodes, start ComfyUI with a higher limit, e.g. --max-upload-size 4096, or copy the file into ComfyUI/input and pick it from the list.

A newly selected or uploaded source starts as one shot covering at most its first 15 seconds. This is only the initial plan: widen the range or choose Camera cuts / Fixed length and press Auto split when you want multiple shots. Existing saved plans keep their own range and split mode.

Continuity between shots

Each shot (after the first) can continue from the previous shot's generated result: in the shot editor, Continuity = previous shot as reference adds a frame of it as one more <Picture n> after the shot's own references (good across camera cuts, keeps the person consistent), and previous shot as first frame anchors it at frame 0 of the shot (for continuous action without a cut). Pick which frame: the previous result's first, middle or last. Copy to other shots with continuity ticked applies it to every shot after the first.

It needs the previous result to exist: it works shot by shot and in the queue loop (the planner reads the stored result) and in the auto loop with BFS Shot H3 Duet (it renders shot by shot and keeps the last result). BFS Shot Unpack also outputs it as previous_result. This is different from H3 Conditioning's first_frame, which anchors the shot's own frame from the source video.

History: a long take, window by window (1.87.0)

Continuity = previous shot's end as history carries the last 5, 22, 39 or 56 frames of the previous shot's result into the next shot as clean frames placed just before frame 0 on H3's timeline: the model sees them as the immediate past of the video it is generating, so motion, camera, light and the new look continue across the join (instead of one still frame). Idea from Akatz's H3 Relay windowed edit and Ethanfel's MiniMax H3 Context Loop; this is BFS's own implementation (a process-local patch of H3's packed layout that moves the video, its audio and the other guides past the history; ComfyUI files are not edited).

• Plans saved before keep what they had; head (below) is now the default for new shots.
• Same take only. A shot that starts at a camera cut skips it (nothing to continue). For one long take, split it with Mode = fixed length (or let Camera cuts split long shots) and set history on every shot after the first with Copy to other shots → continuity. Shots still exist: they are the windows, and cuts reset the history.
• Every mode: full frame, Frame + paste, Mask only (the mask regenerates the target; the history is a condition outside it), Crop (the history is cut with this shot's box) and the duet canvas (the source frames under the history go into the panel strip). Not with duet shifted RoPE. The aligned guide still drives this shot's own frames, so sync stays frame-exact.
• BFS Shot H3 Conditioning and BFS Shot H3 Duet both use it (duet canvas or aligned guide).
• Shot by shot / queue loop: shots run in order and each reads the stored result of the one before. Auto loop: taken from the previous render when it matches.
• Video only for now (the previous audio is not carried). History can use 5, 22, 39 or 56 frames; longer windows use more memory.
• Only 17k+5 frames work. H3's VAE encodes 17-frame clips into 5 latent steps and drops the last 3 steps of the whole video, so 17 frames come back as just their first 5: the old 17 / 34 / 51 options left a 12-frame (0.5 s) hole between the history and the shot, seen as a jump or drift at every join. Plans saved with 17 / 34 / 51 are read as 22 / 39 / 56.

Head: the shot starts on the previous result (default)

Continuity = previous shot's end as this shot's start generates the shot from 5, 22 or 39 frames earlier: those first frames are the previous shot's result, encoded into this shot's latent and kept by the sampler (noise mask 0), so they are not generated or swapped again, and the new frames continue straight from them. BFS Shot Join cuts them off, so the timing is unchanged. Same masked-prefix continuation as the Context Loop's masked AV mode, whose tested default is 22.

• On by default, 22 frames, for every shot after the first. Set Continuity = off (or history) to change it.
• Same take only: skipped at a camera cut, after a skipped shot, and on grids other than H3's.
• Shot by shot or queue loop. In the auto loop the previous result does not exist yet when the shot is conditioned, so the planner generates the shot without a head (and says so in the console).
• Works with full frame, Frame + paste, Mask only / Crop + mask (the head is kept whatever the mask says), Crop (the head is cut with this shot's box) and the duet canvas. Not with duet shifted RoPE. Pinned in BFS Shot H3 Conditioning; other workflows still generate and cut the extra frames.
• Costs those frames of generation per shot (a 60-frame shot is generated at 90 frames instead of 73).
• Keep colors (BFS Shot Join, on by default). A shot that starts on the previous result comes out a little more saturated right after it, and the next shot inherits that: measured on a 5-shot take, the new subject's saturation went 75 → 88 → 105 → 124, with almost no change inside each shot (the jump is at every join). With keep_colors the first shot of each take records its subject's colours, and every shot that continues from the one before has its subject's chroma (CIELAB a, b: one transform per shot, so no flicker) matched to them before it is stored; the next shot then starts from the anchored colours and nothing accumulates (same take: 69–73 on every shot). The subject is where the result differs from the source video (soft edge); the background and the lightness are not touched. A camera cut or a shot without continuity starts a new take (new anchor). keep_colors_strength blends it (1 = fully). It applies to stored runs (shot by shot, queue loop), where continuity exists.

MiniMax H3 with an aligned guide (example)

BFS Shot Planner ── shots ──► BFS Shot H3 Conditioning (clip, vae, guide_mode = aligned guide)
                                 └─ positive, latent ─► CFGGuider / sampler ─► VAE Decode ─┐
BFS Shot Join ◄── images ─────────────────────────────────────────────────────────────────┘
      └─► Create Video (fps, audio) ─► Save Video

For other models, use BFS Shot Unpack and wire guide_frames, refs, prompt and length into that model's own guide and reference nodes; the list mapping works the same way.

Choosing who is replaced ({target}), step by step

With several people on screen, a prompt that says "replace the person" leaves the model to guess. {target} puts a short description of the right person into the prompt of every shot ("the young woman with dark hair in a pink top"), so the model knows WHICH one to swap. The selection is made with SAM 3, and the description by the VLM, so it works for anyone or anything you can click on.

What you need

• The planner's vlm input connected to a Qwen3-VL (CLIPLoader, type stable_diffusion, qwen3vl_8b recommended).
• The workflow run once with it connected. ComfyUI only hands models to nodes when they run; after that the panel buttons can use it.
• Without a VLM it still works: you get the cut-out and type the description yourself.

1. Put {target} in the prompt

Write {target} wherever the prompt names the person being replaced: in the global prompt (all shots) or in a shot's own prompt. For example, the swap caption the H3 LoRAs were trained with:

... only the face, body and clothing of {target} are replaced.  summary: [video generation + reference] Replace
{target} in the guide video with <Subject 1>, keeping the scene, camera and the complete motion and facial
performance of the guide video.  detailed_description: [Shot 1] <Subject 1> takes the exact place of {target}
and moves with the same timing, body pose, gestures, ...

{target} can be combined with {details} (the description of the references) and {shot} (the VLM's description of the shot).

2. Select the person

Open a shot and click 🎯 Points…. The modal shows one frame of the shot; the slider below picks the frame.

• Click on the person's body (torso), not only the face. A click on the face selects the head, and the description then misses the clothes.
• Right-click (or shift+click) puts an exclude point, e.g. on a second person standing close.
• 👁 Segment shows what SAM 3 picked (red). Add or remove points until only that person is red.
• Instead of points you can just type what to segment (woman in pink, man with glasses, dog): no clicking is needed, SAM 3 finds and tracks it through the shot. Points are for when the text is ambiguous (two similar people). Points win when both are set. Copy to other shots with mask text (and mode) ticked gives the text (and the generation mode) to every shot.

Then save:

Button	What it does
Save (this shot)	keeps the selection on this shot only
Save → all shots	applies the same points to every shot, each on its frame at the same relative position as the frame you clicked on (e.g. clicked in the middle of this shot → every shot uses its middle frame)

Save → all shots is for a person who stays in the same place across shots (a sequential video, a fixed camera).

🎯 Track → whole video (in the points window) is for a person who moves around: the selection is tracked by SAM 3 through the whole video (or the range), forward and backward from the frame you clicked on, and every shot without its own selection takes its part of that track. Also type a short text (e.g. woman in pink top): after a camera cut the tracker uses it to find the subject again. The People / Filters / Masks tab shows the track and removes it. The first run tracks the whole range (a minute or two per few hundred frames); the result is cached until the selection changes.

3. Describe the person

Click 🧑 Describe target in the shot's editor:

• SAM 3 cuts the person out of the selected frame, and a thumbnail of the cut-out appears next to the field.
• The VLM writes a short phrase into the {target} field.
• The field stays editable: correct it or write your own. Keep it short and visual (who, hair, main clothes with colours) and start it with "the".
• Copy to other shots with {target} ticked copies the description to every shot. Use it when the same person is replaced throughout; otherwise describe shot by shot.

4. Check and fix

• 👁 Preview on a few shots shows the selection on several frames of each shot.
• In a shot where the selection picked the wrong thing, ✕ Clear removes its points, text and mode. Select again in that shot only (Save (this shot)) and describe again.
• Copy to other shots with mask points ticked copies that shot's points to every shot without opening the modal.

What happens when the workflow runs

Every shot's prompt gets its own {target} text: the one you wrote or made with 🧑 Describe target; when the field is empty but the shot has a selection (mask text, points or a mask video) and the VLM is connected, the subject is cut out and described automatically (written for the prompt's {target} sentence). A shot with neither gets "the person". The selection is only used to make the description: it does not crop or mask anything unless the shot's mode is Mask only, Crop or Crop + mask.

Examples

• Two people, swap only one: in the first shot, click on the woman's torso, put an exclude point on the man, then Save → all shots and 🧑 Describe target → "the young woman with long black hair in a white blouse". Copy to other shots with {target} ticked.
• The person changes between shots: describe shot by shot, e.g. shot 1 "the man in the grey suit", shot 2 "the woman in the red dress". Each shot keeps its own text.
• Animals: it works the same way, e.g. "the small black dog in front".

Troubleshooting

Problem	Fix
"No VLM yet"	connect the vlm input and run the workflow once, or type the description
"Select the person first"	the shot has no points or mask text: use 🎯 Points…
"SAM 3 found nothing"	click again on the person (on the torso), or try another frame with the slider
Only the face or the hair is described	the click was on the head: click the body
The other person is described	add an exclude point (right-click) on the other person, 👁 Segment, save, describe again
The swap still hits the wrong person	make the description more specific (position: "on the left", clothing colours)

Cancel a pending redo

After marking a stored shot for redo, click Undo redo to keep its previous take. Clear redo selection cancels all pending redo selections and preserves stored files and loop progress. Once a shot has been regenerated, its previous take cannot be restored through this control. Refresh status rereads the cache status; it cannot recover files deleted by older versions of Reset loop. Changing the seed, model or other render settings still invalidates stored shots even after cancelling redo.

Experimental native temporal motion transfer

BFS Shot H3 Conditioning now has native temporal alignment (experimental) in guide_mode. Connect MODEL in and route its MODEL output to the guider. This uses the matching experimental LoRA, the shot as native <Video 1>, temporal RoPE alignment and soft temporal attention; it does not use Add Guide. Use 24 fps and disable continuity/first-frame/mask guides and VSA. Simple appends a MODEL output without moving existing outputs. The standalone BFS MiniMax H3 Native Temporal Alignment (Experimental) node provides the same patch for native workflows. See H3_NATIVE_TEMPORAL.md for the full contract and validation limits.

Native temporal performance (1.115.11): native_temporal_backend defaults to flash partitions (no compile), preserving the same temporal penalty. native_guide_scale can reduce only guide resolution (try 0.5); output dimensions and frame count stay unchanged. The original Flex backend remains available for comparison.

Prompt bindings (1.115.12): completed short captions are no longer expanded into legacy two-subject templates. Auto-written prompts whose request/reference/mark signature is outdated are regenerated with a connected Planner VLM; otherwise use Write again before rendering. The writer rejects picture indices beyond the connected references after its bounded retry. Character outfits come from identity references, while requested setting changes override conflicting source scenery/lighting.