Fix Color Guide reference history and add global colors

bfs_shot_loop.py

@@ -429,7 +429,8 @@ def plan_segments(n: int, cuts: list[int], mode: str, max_len: int, min_len: int
 DEFAULT_PLAN = {
     "video": "", "fps": 24.0, "grid": DEFAULT_GRID, "mode": "shots", "max_s": 4.5, "min_s": 1.0,
     "sensitivity": 0.5, "max_parts": 0, "max_total_s": 0.0, "start_s": 0.0, "end_s": 0.0, "bounds": [], "segs": [],
-    "global_ref": "", "global_ref2": "", "global_prompt": "", "megapixels": 0.15, "multiple": 32,
+    "global_ref": "", "global_ref2": "", "global_prompt": "", "global_color_guide_ref1": "#00ff00",
+    "global_color_guide_ref2": "#9b30ff", "megapixels": 0.15, "multiple": 32,
     "detector": "adaptive", "run": "auto", "filters": {}, "skip_fill": "original",
     "cast": {}, "cast_assign": True, "cast_split": False, "cast_only": False, "mask_cfg": {}, "vlm_cfg": {}, "audio_mode": "auto", "ref_details": {},
 }
@@ -481,12 +482,37 @@ def resolve_plan(plan: dict, analysis: dict, path: str | None = None) -> list[di
         s["inpaint"] = bool(m.get("inpaint"))
         s["paste"] = bool(m.get("paste")) and not s["crop"] and not s["inpaint"]
         s["paste_text"] = str(m.get("paste_text") or "")
+        s["color_guide"] = bool(m.get("color_guide"))
+        s["color_guide_person"] = m.get("color_guide_person")
+        s["color_guide_color"] = str(m.get("color_guide_color") or "")
+        s["color_guide_text2"] = str(m.get("color_guide_text2") or "")
+        s["color_guide_person2"] = m.get("color_guide_person2")
+        s["color_guide_color2"] = str(m.get("color_guide_color2") or "")
+        s["color_guide_opacity"] = min(0.8, max(0.05, float(m.get("color_guide_opacity") or 0.35)))
         s["strength"] = min(1.0, max(0.05, float(m.get("strength") or 1.0)))
         s["mask"] = m.get("mask") or {}
         s["target"] = m.get("target") or ""
         s["cut_before"] = bool(s.get("cut_before")) or (s["start"] in cuts)
         s["gen_len"] = snap_up(s["end"] - s["start"], grid)
         s["people"], s["main"] = [], -1
+        guide_pid = s.get("color_guide_person")
+        if guide_pid is not None:
+            s["color_guide_color"] = str(m.get("color_guide_color") or
+                                           (plan.get("cast") or {}).get(str(guide_pid), {}).get("guide_color") or "")
+        guide_pid2 = s.get("color_guide_person2")
+        if guide_pid2 is not None:
+            s["color_guide_color2"] = str(m.get("color_guide_color2") or
+                                            (plan.get("cast") or {}).get(str(guide_pid2), {}).get("guide_color") or "")
+        s["color_guide_color"] = s["color_guide_color"] or str(plan.get("global_color_guide_ref1") or "#00ff00")
+        s["color_guide_color2"] = s["color_guide_color2"] or str(plan.get("global_color_guide_ref2") or "#9b30ff")
+        if s.get("color_guide"):
+            cast_entries = plan.get("cast") or {}
+            first_person = cast_entries.get(str(s.get("color_guide_person"))) or {}
+            second_person = cast_entries.get(str(s.get("color_guide_person2"))) or {}
+            if not m.get("ref") and first_person.get("ref"):
+                s["ref"] = first_person["ref"]
+            if not m.get("ref2") and second_person.get("ref"):
+                s["ref2"] = second_person["ref"]
         if cast is not None:
             sp = shot_people(cast, s["start"], s["end"])
             s["people"], s["main"] = sp["people"], sp["main"]
@@ -1320,6 +1346,12 @@ def paste_back(result: torch.Tensor, shot: dict, new_outline: bool = True, **fin
     sm = shot_mask(ms["path"], ms["analysis"], ms["start"], ms["length"], ms["spec"])["masks"]
     n = min(result.shape[0], base.shape[0], sm.shape[0])
     m = torch.nn.functional.interpolate(sm[:n, None].float(), size=(H, W), mode="nearest")[:, 0]
+    second_text = str(shot.get("color_guide_text2") or "").strip()
+    if second_text:
+        sm2 = shot_mask(ms["path"], ms["analysis"], ms["start"], ms["length"],
+                        dict(DEFAULT_MASK, text=second_text, max_objects=1))["masks"]
+        sm2 = torch.nn.functional.interpolate(sm2[:n, None].float(), size=(H, W), mode="nearest")[:, 0]
+        m = torch.maximum(m, sm2)
     if new_outline and bool(m.any()):
         x0, y0, x1, y1 = box_px(crop_box(m, 0.5), W, H)              # where the new person may be
         s = 640 / max(H, W)
@@ -2507,6 +2539,14 @@ class BFSShotPlanner:
                         r["masks"][:, None, by0:by1, bx0:bx1].float(), size=(chh, cw), mode="nearest")[:, 0]
             hist, hist_src = (history_for(path, a, src, s, i, prev_len, queue, rid, W, H, crop, ft)
                               if s["chain"] == "history" and i > 0 else (None, None))
+            shot_prompt = fill_target(fill_details((s["prompt"] or written.get(i) or g_prompt or "").replace(
+                "{shot}", sug["shot"] if (sug and vcfg["auto_shot"]) else ""),
+                s["ref"] or g_names["ref"], s["ref2"] or g_names["ref2"], ref, ref2),
+                s.get("target", "") or auto_target.get(i, ""))
+            if s.get("color_guide"):
+                shot_prompt = color_guide_prompt(shot_prompt, s.get("color_guide_color") or "#00ff00",
+                                                 (s.get("color_guide_color2") or "#9b30ff")
+                                                 if s.get("color_guide_text2") else "")
             shots.append({
                 "index": i, "count": len(segs), "start": s["start"], "end": s["end"],
                 "length": s["end"] - s["start"], "gen_length": s["gen_len"], "fps": fps,
@@ -2514,11 +2554,13 @@ class BFSShotPlanner:
                 "crop": crop, "full_frames": full_frames, "mask_src": mask_src,
                 "inpaint": bool(s.get("inpaint")), "inpaint_strength": float(s.get("strength") or 1.0),
                 "paste": bool(s.get("paste")), "paste_text": s.get("paste_text") or "",
+                "color_guide": bool(s.get("color_guide")),
+                "color_guide_color": str(s.get("color_guide_color") or "#00ff00"),
+                "color_guide_opacity": float(s.get("color_guide_opacity") or 0.35),
+                "color_guide_text2": str(s.get("color_guide_text2") or ""),
+                "color_guide_color2": str(s.get("color_guide_color2") or "#9b30ff"),
                 "ref": ref, "ref2": ref2,
-                "prompt": fill_target(fill_details((s["prompt"] or written.get(i) or g_prompt or "").replace(
-                    "{shot}", sug["shot"] if (sug and vcfg["auto_shot"]) else ""),
-                    s["ref"] or g_names["ref"], s["ref2"] or g_names["ref2"], ref, ref2),
-                    s.get("target", "") or auto_target.get(i, "")),
+                "prompt": shot_prompt,
                 "audio": _slice_audio(audio, s["start"] / fps, s["gen_len"] / fps),
                 "run_id": rid, "queue": queue,
                 "chain": s["chain"], "chain_frame": s["chain_frame"], "chain_image": chain_img,
@@ -2819,6 +2861,48 @@ def masked_only(frames: torch.Tensor, mask: torch.Tensor, grey: float = 0.5, loo
     return guide_look(frames, look) * m + grey * (1 - m)
 
 
+def color_guide(frames: torch.Tensor, mask: torch.Tensor, color: str = "#00ff00",
+                opacity: float = 0.35) -> torch.Tensor:
+    """Tint a selected subject in the guide while keeping its underlying motion and expression visible."""
+    try:
+        rgb = torch.tensor([int(color[i:i + 2], 16) / 255 for i in (1, 3, 5)], dtype=torch.float32)
+    except (TypeError, ValueError, IndexError):
+        raise ValueError(f"Color Guide: invalid color {color!r}; expected a hex color such as #00ff00") from None
+    if mask.ndim == 2:
+        mask = mask[None]
+    m = torch.nn.functional.interpolate(mask[:, None].float(), size=frames.shape[1:3], mode="nearest")[:, 0]
+    idx = torch.clamp(torch.arange(frames.shape[0]), max=m.shape[0] - 1)
+    alpha = m[idx][..., None] * min(0.8, max(0.05, float(opacity)))
+    tint = rgb.to(device=frames.device, dtype=frames.dtype)
+    return (frames[..., :3].float() * (1 - alpha) + tint * alpha).clamp(0, 1)
+
+
+_COLOR_GUIDE_NAMES = {"#00ff00": "green", "#ff2020": "red", "#168cff": "blue", "#ffe600": "yellow",
+                      "#ff00d4": "magenta", "#00e5c0": "cyan", "#9b30ff": "purple"}
+
+
+def color_guide_prompt(prompt: str, color1: str, color2: str = "") -> str:
+    """Add explicit temporary-marker-to-reference mapping for the colors actually enabled on this shot."""
+    name1 = _COLOR_GUIDE_NAMES.get(str(color1).lower(), "green")
+    lines = [f"The translucent {name1} color overlay is a temporary marker for the selected guide person; "
+             f"replace only that person with <Subject 1> from <Picture 1>, and remove the color overlay completely."]
+    if color2:
+        name2 = _COLOR_GUIDE_NAMES.get(str(color2).lower(), "purple")
+        lines.append(f"The translucent {name2} color overlay marks a different guide person; replace only that person "
+                     f"with <Subject 2> from <Picture 2>, and remove that overlay completely.")
+    lines.append("Each person keeps their own original timing, body motion, gestures, head motion, gaze, speech and facial "
+                 "expression. Preserve the scene, camera and unmarked content from the guide video.")
+    mapping = " ".join(lines)
+    # Keep the color contract inside the matching sections of the user's existing structured prompt.
+    text, n = re.subn(r"(?is)(\bsubject_definitions\s*:.*?)(\s+summary\s*:)",
+                      lambda m: m.group(1) + " " + mapping + m.group(2), str(prompt or ""), count=1)
+    if not n:
+        text = (str(prompt or "").rstrip() + "\n\n" + mapping).strip()
+    detailed, n = re.subn(r"(?is)(\bdetailed_description\s*:.*?)(\s+overall_soundscape\s*:)",
+                          lambda m: m.group(1) + " " + mapping + m.group(2), text, count=1)
+    return detailed if n else text
+
+
 def mask_report(m: torch.Tensor) -> str:
     """'37 frames 512x288, covers 12.3% (min 8.1%, max 15.0%)' for console logs."""
     cov = m.float().flatten(1).mean(1) if m.ndim == 3 and m.shape[0] else m.float().mean()[None]
@@ -2948,7 +3032,9 @@ class BFSShotH3Conditioning:
                     "Optional prompt writer for the duet. 'planner prompt' (default) uses the shot's prompt from the "
                     "planner as it is. A task writes the prompt of every shot in the duet format instead: with a VLM "
                     "connected it looks at the shot and its references and writes it; without one, a template for the "
-                    "task. Needs duet on (canvas or shifted RoPE). See the written text on the prompt output."}),
+                    "task. Needs duet on (canvas or shifted RoPE). See the written text on the prompt output. For two "
+                    "Color Guide people with separate references, use 'planner prompt': the automatic character-swap "
+                    "template assumes the pictures show one identity."}),
                 "instruction": ("STRING", {"default": "", "multiline": True, "tooltip":
                     "What changes, in seen words, for the task: 'a 1990s anime cel style', 'a sunny beach at sunset', "
                     "'an elderly woman with short grey hair'. Empty is fine for character swap (the person comes from "
@@ -3023,6 +3109,15 @@ class BFSShotH3Conditioning:
             refs["ref_image_0"] = shot["ref"]
         if use_ref_2 and shot["ref2"] is not None:
             refs[f"ref_image_{len(refs)}"] = shot["ref2"]
+        if shot.get("color_guide") and shot.get("color_guide_text2"):
+            if not use_ref_2 or shot.get("ref2") is None:
+                raise ValueError("Color Guide's second person is marked, but no second reference is being passed. Set the shot's ref 2 and enable use_ref_2.")
+            if str(shot.get("color_guide_color", "#00ff00")).lower() == str(shot.get("color_guide_color2", "#9b30ff")).lower():
+                raise ValueError("Color Guide needs a different color for each reference in the same shot. Change the color assigned to ref 2 or its cast identity.")
+            if task != "planner prompt":
+                raise ValueError("The automatic duet prompt templates treat multiple pictures as views of one character. For two Color Guide people, use task = 'planner prompt' and the color-mapping template in the Shot Planner guide.")
+        if shot.get("color_guide") and shot.get("ref") is None:
+            raise ValueError("Color Guide needs ref 1 for the selected person. Add a reference to this shot or its cast identity.")
         prev = chain_image(shot)
         if prev is not None and shot.get("chain") == "reference":
             refs[f"ref_image_{len(refs)}"] = prev   # one more <Picture n>, after the shot's own
@@ -3074,6 +3169,28 @@ class BFSShotH3Conditioning:
         # what the model sees of the source; the kept area (keep_video) stays the original
         seen = blur_source(shot["frames"], source_blur, float(source_blur_strength), gtag) \
             if source_blur and source_blur != "off" else shot["frames"]
+        if shot.get("color_guide"):
+            if not shot.get("mask_src") and not shot.get("crop"):
+                raise ValueError(f"{gtag}: Color Guide needs a person selection (SAM 3 text/points or a mask video)")
+            cmask = generation_mask(shot, log=gtag)
+            seen = color_guide(seen, cmask, shot.get("color_guide_color", "#00ff00"),
+                               shot.get("color_guide_opacity", 0.35))
+            text2 = str(shot.get("color_guide_text2") or "").strip()
+            if text2:
+                ms = shot.get("mask_src")
+                if not ms:
+                    raise ValueError(f"{gtag}: the second Color Guide selection needs a full-frame shot mask source; turn off Crop for this shot")
+                spec2 = dict(DEFAULT_MASK, text=text2, max_objects=1)
+                r2 = shot_mask(ms["path"], ms["analysis"], ms["start"], ms["length"], spec2)
+                cmask2 = torch.nn.functional.interpolate(r2["masks"][:, None].float(),
+                                                         size=shot["frames"].shape[1:3], mode="nearest")[:, 0]
+                seen = color_guide(seen, cmask2, shot.get("color_guide_color2", "#9b30ff"),
+                                   shot.get("color_guide_opacity", 0.35))
+                print(f"{gtag}: second Color Guide selection {text2!r}, "
+                      f"{shot.get('color_guide_color2', '#9b30ff')} at {float(shot.get('color_guide_opacity', 0.35)):.2f}, "
+                      f"{mask_report(cmask2)}", flush=True)
+            print(f"{gtag}: Color Guide {shot.get('color_guide_color', '#00ff00')} at "
+                  f"{float(shot.get('color_guide_opacity', 0.35)):.2f} opacity, {mask_report(cmask)}", flush=True)
         pg = mask_guide if mask_guide in MASK_GUIDES[1:] else None
         if pg and (not use_mask or shot.get("crop") or on_canvas):
             print(f"{gtag}: mask_guide ignored: it is for 'Mask only' shots (mask, no crop, no duet)", flush=True)
@@ -3835,7 +3952,13 @@ try:
             a = analyze(path, float(p["fps"]))
             segs = resolve_plan(p, a, path)
             seg = segs[int(body.get("index", 0))]
-            spec = plan_spec(p, body.get("mask") or seg.get("mask"), path)
+            mask_override = body.get("mask")
+            spec = plan_spec(p, mask_override or seg.get("mask"), path)
+            if isinstance(mask_override, dict):
+                for key in ("threshold", "max_objects", "invert", "fill_holes", "temporal_expand", "blockify",
+                            "padding", "expand", "feather", "paste"):
+                    if key in mask_override:
+                        spec[key] = mask_override[key]
             import asyncio   # SAM 3 takes seconds: keep the server responsive
             _outside_prompt()
             out = await asyncio.get_running_loop().run_in_executor(

pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "bfsnodes"
-description = "Custom ComfyUI nodes for reference-guided video: BFS Sampler (guide-driven IC-LoRAs, auto crop, mask inpainting, temporal chunking), LTX Multiple Controls / Identity Transfer / Edit Anything, Head-Swap and Anime2Real conditioning, MiniMax-H3 latent guides, RoPE layouts and loaders, LoRA Surgery, and Shot Planner / Shot Loop (tabbed panel): split long videos into shots at camera cuts, face-tracked cast, SAM 3 mask per shot with four generation modes (full frame, mask only, crop, crop + mask), optional Qwen3-VL to suggest settings, describe references ({details}) and the person to replace ({target}), continuity between shots, H3 conditioning with an optional duet and prompt writer, join with the original timing, audio and a side-by-side comparison. H3 Duet: pin a source clip beside the video, training-free."
-version = "1.94.1"
+description = "Custom ComfyUI nodes for reference-guided video: BFS Sampler (guide-driven IC-LoRAs, auto crop, mask inpainting, temporal chunking), LTX Multiple Controls / Identity Transfer / Edit Anything, Head-Swap and Anime2Real conditioning, MiniMax-H3 latent guides, RoPE layouts and loaders, LoRA Surgery, and Shot Planner / Shot Loop (tabbed panel): split long videos into shots at camera cuts, face-tracked cast, SAM 3 mask per shot with full frame, paste, mask, crop and crop + mask generation modes, optional translucent Color Guide for one or two manually selected regions with cast identity color reuse, optional Qwen3-VL to suggest settings, describe references ({details}) and the person to replace ({target}), continuity between shots, H3 conditioning with an optional duet and prompt writer, join with the original timing, audio and a side-by-side comparison. H3 Duet: pin a source clip beside the video, training-free."
+version = "1.97.0"
 license = {file = "LICENSE"}
 dependencies = [
     "torch",

web/js/bfs_shot_loop.js

@@ -11,8 +11,8 @@
 import { app } from "../../scripts/app.js";
 import { api } from "../../scripts/api.js";
 import { showGuide } from "./bfs_md_view.js";
-import { createApp, ref, reactive, computed, watch, nextTick, onMounted, onBeforeUnmount, h } from "./vendor/vue.esm-browser.prod.mjs";
-import { DEFAULTS, MASK_DEFAULTS, VLM_DEFAULTS, snapUp, snapDown, segKey, hasMask, pill } from "./shotloop/common.js";
+import { createApp, ref, reactive, computed, watch, nextTick, onMounted, onBeforeUnmount } from "./vendor/vue.esm-browser.prod.mjs";
+import { h, t, uiLanguage, setUiLanguage, DEFAULTS, MASK_DEFAULTS, VLM_DEFAULTS, snapUp, snapDown, segKey, hasMask, pill } from "./shotloop/common.js";
 import { styles } from "./shotloop/styles.js";
 import { timelineCard } from "./shotloop/view_timeline.js";
 import { videoTab } from "./shotloop/view_video.js";
@@ -20,7 +20,7 @@ import { shotsTab } from "./shotloop/view_shots.js";
 import { peopleTab } from "./shotloop/view_people.js";
 import { promptsTab } from "./shotloop/view_prompts.js";
 import { runTab } from "./shotloop/view_run.js";
-import { busyBar, pointsModal } from "./shotloop/view_modal.js";
+import { busyBar, pointsModal, tourModal } from "./shotloop/view_modal.js";
 
 const viewUrl = name => {
   if (!name) return "";
@@ -65,9 +65,10 @@ function Panel(io) {
   const targetCrop = ref({});    // "start-end" -> data URL of the subject the description was made from
   const tab = ref(store.get("bfs.shotloop.tab", "shots"));
   watch(tab, v => store.set("bfs.shotloop.tab", v));
+  const tour = ref(0); // opened only by the user's Tour button; never shown automatically
   // what "Copy to other shots" copies (remembered per browser)
   const copyOpts = reactive(store.get("bfs.shotloop.copy", { ref: true, prompt: false, mask_text: false, points: false, crop: false,
-                                                              target: false, chain: false, scope: "all" }));
+                                                              target: false, chain: false, color_guide: false, scope: "all" }));
   watch(copyOpts, v => store.set("bfs.shotloop.copy", { ...v }), { deep: true });
 
   const load = () => {
@@ -215,7 +216,10 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
         plan.bounds = j.segs.slice(1).map(s => s.start);
         const keep = plan.segs; plan.segs = j.segs.map((_, i) => ({ enabled: true, ref: keep[i]?.ref || "", ref2: keep[i]?.ref2 || "", prompt: keep[i]?.prompt || "",
           chain: keep[i]?.chain || "history", chain_frame: keep[i]?.chain_frame || "first", chain_history: keep[i]?.chain_history || 17,
-          crop: !!keep[i]?.crop, inpaint: !!keep[i]?.inpaint, paste: !!keep[i]?.paste, paste_text: keep[i]?.paste_text || "", strength: keep[i]?.strength ?? 1, mask: keep[i]?.mask || {}, target: keep[i]?.target || "" }));
+          crop: !!keep[i]?.crop, inpaint: !!keep[i]?.inpaint, paste: !!keep[i]?.paste, paste_text: keep[i]?.paste_text || "", strength: keep[i]?.strength ?? 1, mask: keep[i]?.mask || {}, target: keep[i]?.target || "",
+          color_guide: !!keep[i]?.color_guide, color_guide_color: keep[i]?.color_guide_color || "", color_guide_opacity: keep[i]?.color_guide_opacity ?? 0.35,
+          color_guide_person: keep[i]?.color_guide_person ?? null, color_guide_text2: keep[i]?.color_guide_text2 || "",
+          color_guide_color2: keep[i]?.color_guide_color2 || "", color_guide_person2: keep[i]?.color_guide_person2 ?? null }));
         sel.value = 0; save();
       }
     } catch (e) { error.value = String(e.message || e); }
@@ -244,7 +248,7 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
   }
   const setCast = (id, k, v) => {
     plan.cast = { ...plan.cast, [String(id)]: { ...castOf(id), [k]: v } };
-    if (k !== "ignore") remember(v);
+    if (k === "ref" || k === "ref2") remember(v);
     save();
   };
   async function describeTarget(i) {
@@ -255,7 +259,7 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
       const j = await r.json(); if (j.error) throw new Error(j.error);
       targetCrop.value = { ...targetCrop.value, [segKey(s)]: j.crop };
       if (j.desc) setMeta(i, "target", j.desc);
-      else error.value = "No VLM yet: connect it to the planner's vlm input and run once, or type the description yourself.";
+      else error.value = "The SAM 3 target cutout was created (shown below), but no VLM is loaded to describe it. Connect Qwen3-VL to the Shot Planner's vlm input and queue the workflow once; then click Describe target again. You can also type the target description yourself.";
     } catch (e) { error.value = String(e.message || e); }
     busy.value = "";
   }
@@ -324,7 +328,7 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
   };
   // copy the chosen settings of shot `from` to the other shots (all of them, or the ones after it)
   const COPY_FIELDS = { ref: "references", prompt: "prompt", mask_text: "mask text", points: "mask points", mask_video: "mask video", crop: "mode",
-                        target: "{target}", chain: "continuity" };
+                        target: "{target}", chain: "continuity", color_guide: "Color Guide" };
   const copyFrom = (from, fields = copyOpts, scope = copyOpts.scope) => {
     const src = segs.value[from]; if (!src) return 0;
     const to = targets(scope, from);
@@ -336,6 +340,12 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
       if (fields.mask_video) m.mask = { ...(m.mask || {}), video: src.mask.video || "" };
       if (fields.crop && (hasMask(x) || src.mask.text || fields.mask_text)) { m.crop = src.crop; m.inpaint = src.inpaint; m.paste = src.paste; m.paste_text = src.pasteText; m.strength = src.strength; }
       if (fields.target) m.target = src.target;
+      if (fields.color_guide) {
+        m.color_guide = src.color_guide; m.color_guide_color = src.color_guide_color;
+        m.color_guide_opacity = src.color_guide_opacity; m.color_guide_person = src.color_guide_person;
+        m.color_guide_text2 = src.color_guide_text2; m.color_guide_color2 = src.color_guide_color2;
+        m.color_guide_person2 = src.color_guide_person2;
+      }
       if (fields.chain && i > 0) { m.chain = src.chain; m.chain_frame = src.chainFrame; m.chain_history = src.chainHistory; }
     });
     if (fields.points && (src.mask.points || []).length) pointsTo(src.mask.points, src.mask.key ?? Math.floor(src.len / 2), undefined, from, scope);
@@ -573,14 +583,18 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
   // ---- references
   // the last 10 references picked, remembered across workflows (per browser)
   const RECENT_KEY = "bfs.shotloop.recentRefs";
-  const recent = ref(store.get(RECENT_KEY, []));
+  const isColorValue = name => typeof name === "string" && /^#[0-9a-f]{6}$/i.test(name);
+  const savedRecent = store.get(RECENT_KEY, []);
+  const recent = ref((Array.isArray(savedRecent) ? savedRecent : []).filter(name => typeof name === "string" && !isColorValue(name)));
+  if (recent.value.length !== (Array.isArray(savedRecent) ? savedRecent.length : 0)) store.set(RECENT_KEY, recent.value);
   const remember = name => {
-    if (!name) return;
+    if (!name || typeof name !== "string" || isColorValue(name)) return;
     recent.value = [name, ...recent.value.filter(x => x !== name)].slice(0, 10);
     store.set(RECENT_KEY, recent.value);
   };
   // target: shot index or "global"; field: ref | ref2 (global_ref | global_ref2 for "global")
   const setRef = (target, field, name) => {
+    if (isColorValue(name)) return; // colors belong to Color Guide settings, never to image references
     if (target === "global") plan[field] = name; else meta(target)[field] = name;
     remember(name); save();
   };
@@ -604,7 +618,7 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
   const c = {
     api, plan, files, an, cuts, detectorUsed, size, busy, error, status, busySince, now, upPct, sel, zoom, hover, prog, tlEl,
     stats, people, maskPrev, showMasks, vlmSug, modal, segPeople, targetCrop, tab, copyOpts, COPY_FIELDS, vid, play, recent, clearRecent, clearAllRefs,
-    n, range, setRange, maxLen, segs, active, pxPerFrame, tlWidth, filtersOn, refSets, usedRefs, checks,
+    n, range, setRange, maxLen, segs, active, pxPerFrame, tlWidth, filtersOn, refSets, usedRefs, checks, tour,
     MODES, modeOf, modeName, viewUrl, save, meta, setMeta, setMode, setPlan, whoIn, castOf, linked, castRef, personOf, statFor, skipWhy, refOf, promptOf, checksFor,
     refreshFiles, analyze, autoSplit, analyzeContent, findPeople, setCast, describeTarget, previewMask, setMask, setMaskCfg,
     openPoints, savePoints, savePointsAll, saveTrack, clearTrack, pointsTo, clearMask, copyFrom, analyseVLM, describeRefs, setDetail, setVlmCfg,
@@ -622,7 +636,15 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
         + (range.value.lo > 0 || range.value.hi < N ? " (range)" : ""), "ok") : null,
       warns ? h("span", { class: "pill warn", style: "cursor:pointer", title: "open the checks (Run tab)", onClick: () => { tab.value = "run"; } }, `⚠ ${warns}`) : null,
       h("span", { class: "grow" }),
+      h("label", { class: "langpick", title: t("Language") }, [
+        h("span", { class: "hint" }, "🌐"),
+        h("select", { value: uiLanguage.value, "aria-label": t("Language"), onChange: e => setUiLanguage(e.target.value) }, [
+          h("option", { value: "en" }, "English"), h("option", { value: "pt" }, "Português"),
+          h("option", { value: "es" }, "Español"), h("option", { value: "zh" }, "中文"),
+        ]),
+      ]),
       pill(plan.run === "queue" ? "queue loop" : "auto loop"),
+      h("button", { title: t("Shot Planner tour"), onClick: () => { tour.value = 1; tab.value = "video"; } }, t("🧭 Tour")),
       h("button", { title: "Open the full guide (every setting explained, with examples)", onClick: () => showGuide(guideUrl) }, "📖 Guide"),
     ]);
     const counts = { shots: S.length || null, people: people.value.length || null };
@@ -639,6 +661,7 @@ const meta = i => { while (plan.segs.length <= i) plan.segs.push({}); return pla
       an.value ? timelineCard(c) : null,
       views[cur](c),
       pointsModal(c),
+      tourModal({ tour, tab }),
     ]);
   };
 }

web/js/docs/BFSShotPlanner.md

@@ -25,6 +25,10 @@ every shot inside that range.
 
 ## 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 |
@@ -192,6 +196,38 @@ rows at *opacity* × the noise level, so they start from the original partly vis
 person. With `guide_mode = aligned guide` the model also sees the whole original shot as its guide, so it follows
 the motion either way. (Not applied with the duet panel.)
 
+**🎨 Color Guide** is a separate optional visual cue. Turn it on for a shot with a mask and choose the marker color
+for ref 1. The default colors for the global references are set below each image in **Prompts & refs**; a shot may
+override them. The selected region is tinted in the source guide, while the image detail,
+movement and expression remain visible underneath. This does not turn on `Mask only` or create an H3 generation
+mask. The prompt must explain that the tint is temporary and that the matching reference replaces the tinted person.
+
+For consistency across shots, **People & masks → Find people** groups sampled faces by identity (ArcFace through
+InsightFace when installed; otherwise YuNet + SFace, or a weaker appearance fallback). Choose the matching `Person N`
+in each shot to inherit that cast member's Color Guide color. This is a user-confirmed link: profile views, small faces
+and occlusion can make identity grouping uncertain. Leave the shot on `manual identity` when unsure. The shot's mask
+still selects the actual region to tint, and its color can be overridden for that shot.
+
+For two people in one shot, open **+ Add a second person**, use **ref 2** for that selection, and choose a different
+color (purple by default; duplicate colors are disabled). Enable *use_ref_2* on BFS Shot H3 Conditioning. The
+second SAM 3 text selection is optional; preview it before queuing. Color opacity and ArcFace identity links are
+under the optional settings. Use this prompt and replace the color names if you choose another palette:
+
+```text
+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. The VLM prompt
+writer for *duet* is a separate split-screen task; its generic character-swap draft assumes the supplied pictures
+show one character, so use *planner prompt* for this two-character template. `Describe refs` also treats ref and ref 2
+as views of one identity; write the two subject definitions explicitly when ref 2 is a different person.
+
 **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

web/js/shotloop/common.js

@@ -1,11 +1,225 @@
 // Shot Planner: constants and small helpers shared by the panel and its views (no side effects: ComfyUI loads every
 // .js under web/js as an extension, so this module only exports).
-import { h, reactive } from "../vendor/vue.esm-browser.prod.mjs";
+import { h as vueH, reactive, ref } from "../vendor/vue.esm-browser.prod.mjs";
+
+// UI language is a browser preference, not part of the workflow or generation prompts.
+const LANG_KEY = "bfs.shotloop.language";
+const savedLanguage = (() => { try { return localStorage.getItem(LANG_KEY) || "en"; } catch { return "en"; } })();
+export const uiLanguage = ref(["en", "pt", "es", "zh"].includes(savedLanguage) ? savedLanguage : "en");
+export function setUiLanguage(value) {
+  if (!["en", "pt", "es", "zh"].includes(value)) return;
+  uiLanguage.value = value;
+  try { localStorage.setItem(LANG_KEY, value); } catch { /* private mode */ }
+}
+
+const TEXT = {
+  "🎞 Video": ["🎞 Vídeo", "🎞 Vídeo", "🎞 视频"], "🎬 Shots": ["🎬 Shots", "🎬 Planos", "🎬 镜头"],
+  "👥 People & masks": ["👥 Pessoas e máscaras", "👥 Personas y máscaras", "👥 人物和蒙版"],
+  "📝 Prompts & refs": ["📝 Prompts e referências", "📝 Prompts y referencias", "📝 提示词和参考图"],
+  "▶ Run": ["▶ Executar", "▶ Ejecutar", "▶ 运行"], "📖 Guide": ["📖 Guia", "📖 Guía", "📖 指南"],
+  "🧭 Tour": ["🧭 Tour", "🧭 Recorrido", "🧭 引导"], "Language": ["Idioma", "Idioma", "语言"],
+  "Source video": ["Vídeo de origem", "Vídeo de origen", "源视频"], "Range": ["Trecho", "Rango", "范围"],
+  "Split into shots": ["Dividir em planos", "Dividir en planos", "拆分镜头"], "Generation size": ["Tamanho da geração", "Tamaño de generación", "生成尺寸"],
+  "Camera cuts": ["Cortes de câmera", "Cortes de cámara", "镜头切换"], "Fixed length": ["Duração fixa", "Duración fija", "固定时长"],
+  "One shot (whole range)": ["Um plano (trecho inteiro)", "Un plano (rango completo)", "单个镜头（整个范围）"],
+  "Mode": ["Modo", "Modo", "模式"], "Detector": ["Detector", "Detector", "检测器"], "Sensitivity": ["Sensibilidade", "Sensibilidad", "灵敏度"],
+  "Frame grid": ["Grade de frames", "Múltiplo de fotogramas", "帧步长"], "Max seconds / shot": ["Máx. segundos por plano", "Máx. segundos por plano", "每个镜头最长秒数"],
+  "Min seconds / shot": ["Mín. segundos por plano", "Mín. segundos por plano", "每个镜头最短秒数"], "Timeline fps": ["FPS da linha do tempo", "FPS de la línea de tiempo", "时间轴帧率"],
+  "Megapixels": ["Megapixels", "Megapíxeles", "百万像素"], "Size multiple": ["Múltiplo do tamanho", "Múltiplo del tamaño", "尺寸倍数"],
+  "✂ Auto split": ["✂ Dividir automaticamente", "✂ División automática", "✂ 自动拆分"], "↻ Re-analyse": ["↻ Analisar novamente", "↻ Volver a analizar", "↻ 重新分析"],
+  "Reference & prompt": ["Referência e prompt", "Referencia y prompt", "参考图和提示词"], "Who is replaced": ["Quem será substituído", "Quién se reemplaza", "替换对象"],
+  "Continuity": ["Continuidade", "Continuidad", "连续性"], "Copy to other shots": ["Copiar para outros planos", "Copiar a otros planos", "复制到其他镜头"],
+  "Global reference & prompt": ["Referência e prompt globais", "Referencia y prompt globales", "全局参考图和提示词"],
+  "Describe references ({details})": ["Descrever referências ({details})", "Describir referencias ({details})", "描述参考图（{details}）"],
+  "VLM": ["VLM", "VLM", "视觉语言模型"], "Use the VLM when the workflow runs": ["Usar o VLM ao executar o workflow", "Usar el VLM al ejecutar el flujo", "运行工作流时使用 VLM"],
+  "Fill the mask text": ["Preencher o texto da máscara", "Completar el texto de la máscara", "填写蒙版描述"],
+  "Fill {shot} in the prompt": ["Preencher {shot} no prompt", "Completar {shot} en el prompt", "在提示词中填入 {shot}"],
+  "Frames per shot": ["Frames por plano", "Fotogramas por plano", "每个镜头的帧数"], "Max tokens": ["Máx. tokens", "Máx. tokens", "最大 token 数"],
+  "🤖 Analyse shots": ["🤖 Analisar planos", "🤖 Analizar planos", "🤖 分析镜头"], "📝 Describe refs": ["📝 Descrever referências", "📝 Describir referencias", "📝 描述参考图"],
+  "🎨 Color Guide": ["🎨 Guia de cores", "🎨 Guía de color", "🎨 颜色引导"], "Ref 1 color": ["Cor da ref. 1", "Color de ref. 1", "参考图 1 的颜色"],
+  "Ref 2": ["Ref. 2", "Ref. 2", "参考图 2"], "+ Add a second person (optional)": ["+ Adicionar segunda pessoa (opcional)", "+ Añadir segunda persona (opcional)", "+ 添加第二个人（可选）"],
+  "Second person · Ref 2": ["Segunda pessoa · Ref. 2", "Segunda persona · Ref. 2", "第二个人 · 参考图 2"],
+  "Describe the second person for SAM 3": ["Descreva a segunda pessoa para o SAM 3", "Describe la segunda persona para SAM 3", "为 SAM 3 描述第二个人"],
+  "👁 Preview": ["👁 Prévia", "👁 Vista previa", "👁 预览"], "More options": ["Mais opções", "Más opciones", "更多选项"],
+  "Keep ref 2 color consistent across shots (optional)": ["Manter a cor da ref. 2 nos outros planos (opcional)", "Mantener el color de ref. 2 en otros planos (opcional)", "在其他镜头中保持参考图 2 的颜色（可选）"],
+  "Ref 1 identity": ["Identidade da ref. 1", "Identidad de ref. 1", "参考图 1 的身份"], "Ref 2 identity": ["Identidade da ref. 2", "Identidad de ref. 2", "参考图 2 的身份"],
+  "Choose manually": ["Escolher manualmente", "Elegir manualmente", "手动选择"], "↩ cast color": ["↩ cor do elenco", "↩ color del reparto", "↩ 使用角色颜色"],
+  "Opacity": ["Opacidade", "Opacidad", "不透明度"], "The default keeps movement and expression visible.": ["O padrão mantém o movimento e a expressão visíveis.", "El valor predeterminado mantiene visibles el movimiento y la expresión.", "默认值会保留动作和表情。"],
+  "Full frame": ["Quadro inteiro", "Fotograma completo", "整帧"], "🧩 Frame + paste": ["🧩 Quadro + colar", "🧩 Fotograma + pegar", "🧩 整帧生成并贴回"],
+  "🎭 Mask only": ["🎭 Somente máscara", "🎭 Solo máscara", "🎭 仅蒙版"], "✂ Crop": ["✂ Recorte", "✂ Recorte", "✂ 裁剪"], "✂🎭 Crop + mask": ["✂🎭 Recorte + máscara", "✂🎭 Recorte + máscara", "✂🎭 裁剪并蒙版"],
+  "People & masks": ["Pessoas e máscaras", "Personas y máscaras", "人物和蒙版"], "Cast": ["Elenco", "Reparto", "角色"],
+  "Mask & crop settings": ["Configurações de máscara e recorte", "Ajustes de máscara y recorte", "蒙版和裁剪设置"],
+  "Color Guide identity color": ["Cor de identidade do Guia de cores", "Color de identidad de la Guía de color", "颜色引导身份颜色"],
+  "No Color Guide color": ["Sem cor", "Sin color", "无颜色引导颜色"], "Green": ["Verde", "Verde", "绿色"], "Purple": ["Roxo", "Morado", "紫色"],
+  "Red": ["Vermelho", "Rojo", "红色"], "Blue": ["Azul", "Azul", "蓝色"], "Yellow": ["Amarelo", "Amarillo", "黄色"], "Magenta": ["Magenta", "Magenta", "品红"], "Cyan": ["Ciano", "Cian", "青色"],
+  "Checks": ["Verificações", "Comprobaciones", "检查"], "Run": ["Executar", "Ejecutar", "运行"], "Filters": ["Filtros", "Filtros", "筛选"],
+  "Auto loop (one run)": ["Loop automático (uma execução)", "Bucle automático (una ejecución)", "自动循环（一次运行）"],
+  "Queue loop (one shot per run)": ["Fila (um plano por execução)", "Cola (un plano por ejecución)", "队列循环（每次运行一个镜头）"],
+  "Skipped shots in the output": ["Planos ignorados na saída", "Planos omitidos en la salida", "输出中跳过的镜头"], "Keep original video": ["Manter vídeo original", "Mantener vídeo original", "保留原视频"],
+  "Remove them": ["Removê-los", "Quitarlos", "移除"], "Max shots (0 = all)": ["Máx. planos (0 = todos)", "Máx. planos (0 = todos)", "镜头上限（0 = 全部）"],
+  "Max total seconds (0 = all)": ["Máx. duração total (0 = tudo)", "Duración total máx. (0 = todo)", "总时长上限（0 = 全部）"],
+  "Auto-queue the next shot": ["Enfileirar próximo plano automaticamente", "Añadir automáticamente el siguiente plano a la cola", "自动将下一个镜头加入队列"],
+  "Needs a person": ["Precisa ter uma pessoa", "Debe haber una persona", "需要有人物"], "Needs a face": ["Precisa ter um rosto", "Debe haber un rostro", "需要有人脸"],
+  "Skip dark / fades": ["Ignorar cenas escuras / fades", "Omitir escenas oscuras / fundidos", "跳过暗场/淡入淡出"], "Skip static shots": ["Ignorar planos estáticos", "Omitir planos estáticos", "跳过静止镜头"],
+  "👤 Analyse people & faces": ["👤 Analisar pessoas e rostos", "👤 Analizar personas y rostros", "👤 分析人物和人脸"],
+  "Video": ["Vídeo", "Vídeo", "视频"], "Shots": ["Planos", "Planos", "镜头"], "People": ["Pessoas", "Personas", "人物"], "Prompts": ["Prompts", "Prompts", "提示词"],
+  "Back": ["Voltar", "Atrás", "上一步"], "Next": ["Avançar", "Siguiente", "下一步"], "Close tour": ["Fechar tour", "Cerrar recorrido", "关闭引导"],
+  "Shot Planner tour": ["Tour do Shot Planner", "Recorrido de Shot Planner", "Shot Planner 引导"], "Shot": ["Plano", "Plano", "镜头"],
+  "This tour is optional. Use Next to visit each main tab; close it whenever you like.": ["Este tour é opcional. Use Avançar para conhecer cada aba; feche quando quiser.", "Este recorrido es opcional. Pulsa Siguiente para visitar cada pestaña; puedes cerrarlo cuando quieras.", "此引导为可选。点击下一步浏览各个主选项卡，也可随时关闭。"],
+  "Choose a video, set the frame range, split at camera cuts, then set the generation size.": ["Escolha um vídeo e o trecho, divida nos cortes de câmera e defina o tamanho da geração.", "Elige un vídeo y un rango, divídelo en cortes de cámara y define el tamaño de generación.", "选择视频和范围，按镜头切换拆分，然后设置生成尺寸。"],
+  "Review each shot, assign its references and prompt, and choose how the result is applied.": ["Revise cada plano, associe referências e prompt e escolha como aplicar o resultado.", "Revisa cada plano, asigna referencias y prompt, y elige cómo aplicar el resultado.", "检查每个镜头，设置参考图和提示词，并选择结果的应用方式。"],
+  "Link detected people to references. Set masks here or per shot; ArcFace links are a guide and need your review.": ["Associe as pessoas detectadas às referências. Configure máscaras aqui ou por plano; revise os vínculos ArcFace.", "Vincula las personas detectadas con referencias. Configura máscaras aquí o por plano; revisa los enlaces ArcFace.", "将检测到的人物关联到参考图。可在此处或逐镜头设置蒙版；请检查 ArcFace 关联。"],
+  "Set shared references, prompts and optional VLM assistance. Written prompts are kept exactly as authored.": ["Defina referências, prompts e assistência opcional do VLM. Os prompts escritos são preservados como estão.", "Configura referencias, prompts y asistencia opcional del VLM. Los prompts escritos se conservan tal cual.", "设置共享参考图、提示词和可选的 VLM 辅助。提示词会保持原样。"],
+  "Check warnings, choose auto or queue loop, and set filters or quick-run limits.": ["Confira avisos, escolha loop automático ou fila e configure filtros e limites de teste.", "Revisa avisos, elige bucle automático o cola y configura filtros y límites de prueba.", "查看警告，选择自动循环或队列，并设置筛选条件和快速运行限制。"],
+  "Color Guide adds a translucent marker to a selected person. Ref 1 and Ref 2 must use different colors in the same shot.": ["O Guia de cores aplica uma cor translúcida à pessoa selecionada. Ref. 1 e Ref. 2 precisam de cores diferentes no mesmo plano.", "La Guía de color aplica una marca translúcida a la persona seleccionada. Ref. 1 y Ref. 2 deben tener colores distintos en el mismo plano.", "颜色引导会给选中的人物添加半透明颜色。同一镜头中的参考图 1 和参考图 2 必须使用不同颜色。"],
+  "🎬 Shot Planner": ["🎬 Planejador de planos", "🎬 Planificador de planos", "🎬 镜头规划器"],
+  "— choose a video from the input folder —": ["— escolha um vídeo da pasta de entrada —", "— elige un vídeo de la carpeta de entrada —", "— 从输入文件夹选择视频 —"],
+  "⬆ Upload": ["⬆ Enviar", "⬆ Subir", "⬆ 上传"], "Pick or upload a video to start": ["Escolha ou envie um vídeo para começar", "Elige o sube un vídeo para empezar", "选择或上传视频以开始"],
+  "It is split into shots the model can generate; every shot then gets its own reference, prompt and mask.": ["O vídeo será dividido em planos que o modelo consegue gerar; cada plano terá sua própria referência, prompt e máscara.", "El vídeo se divide en planos que el modelo puede generar; cada uno tendrá su referencia, prompt y máscara.", "视频会拆分为模型可生成的镜头，每个镜头都有自己的参考图、提示词和蒙版。"],
+  "work on a part of the video": ["trabalhe em um trecho do vídeo", "trabaja en una parte del vídeo", "处理视频的一部分"],
+  "Start frame": ["Frame inicial", "Fotograma inicial", "起始帧"], "End frame (0 = end)": ["Frame final (0 = fim)", "Fotograma final (0 = final)", "结束帧（0 = 末尾）"],
+  "⇤ start here": ["⇤ começar aqui", "⇤ empezar aquí", "⇤ 从此处开始"], "⇥ end here": ["⇥ terminar aqui", "⇥ terminar aquí", "⇥ 在此处结束"], "✕ whole video": ["✕ vídeo inteiro", "✕ vídeo completo", "✕ 整个视频"],
+  "Camera cuts or fixed length, on the model's frame grid": ["Cortes de câmera ou duração fixa, na grade de frames do modelo", "Cortes de cámara o duración fija, según la cuadrícula de fotogramas del modelo", "按镜头切换或固定时长，并符合模型帧步长"],
+  "re-analyses": ["reanalisar", "vuelve a analizar", "重新分析"], "ignores Max seconds / shot": ["ignora Máx. segundos por plano", "ignora Máx. segundos por plano", "忽略每个镜头的最长秒数"],
+  "cropped shots use it for the crop": ["planos recortados usam esse valor no recorte", "los planos recortados usan este valor", "裁剪镜头会使用此尺寸"],
+  "Shots use their main person's reference": ["Usar a referência da pessoa principal do plano", "Usar la referencia de la persona principal del plano", "镜头使用主要人物的参考图"],
+  "Split where the main person changes": ["Dividir quando a pessoa principal mudar", "Dividir cuando cambie la persona principal", "主要人物变化时拆分"],
+  "Only run shots with a linked person": ["Executar apenas planos com pessoa vinculada", "Ejecutar solo planos con una persona vinculada", "仅运行已关联人物的镜头"],
+  "a shot without its own reference takes the reference of the person with the most screen time in it": ["um plano sem referência própria usa a referência da pessoa que aparece por mais tempo nele", "un plano sin referencia propia usa la de la persona que aparece más tiempo", "没有单独参考图的镜头会使用出镜时间最长人物的参考图"],
+  "adds a boundary when the biggest face switches to someone else (re-splits the plan)": ["cria uma divisão quando o maior rosto muda para outra pessoa (refaz a divisão)", "añade un corte cuando el rostro más grande cambia de persona (vuelve a dividir)", "最大人脸切换到其他人时添加分界（重新拆分计划）"],
+  "shots where no linked person appears are skipped": ["planos sem pessoa vinculada são ignorados", "se omiten los planos sin una persona vinculada", "跳过没有关联人物的镜头"],
+  "Nobody found yet.": ["Nenhuma pessoa encontrada.", "Aún no se encontraron personas.", "尚未检测到人物。"], "↻ Re-analyse people": ["↻ Analisar pessoas novamente", "↻ Volver a analizar personas", "↻ 重新分析人物"], "👥 Find people": ["👥 Encontrar pessoas", "👥 Buscar personas", "👥 查找人物"],
+  "faces sampled every 0.5 s and grouped by identity (InsightFace, CPU)": ["rostos amostrados a cada 0,5 s e agrupados por identidade (InsightFace, CPU)", "rostros muestreados cada 0,5 s y agrupados por identidad (InsightFace, CPU)", "每 0.5 秒采样人脸并按身份分组（InsightFace，CPU）"],
+  "detects faces across the video and groups them into people": ["detecta rostos no vídeo e os agrupa por pessoa", "detecta rostros en el vídeo y los agrupa por persona", "检测视频中的人脸并按人物分组"],
+  "track faces, link each person to a reference, split and assign shots by who is on screen": ["rastreie rostos, associe cada pessoa a uma referência e divida os planos por quem aparece", "rastrea rostros, vincula cada persona a una referencia y divide los planos según quién aparece", "跟踪人脸、关联参考图，并按出镜人物拆分镜头"],
+  "Each shot picks what it marks (🎯 text or points, or 🎞 its own mask video) and how it is generated (": ["Cada plano define a seleção (🎯 texto, pontos ou 🎞 vídeo de máscara) e o modo de geração (", "Cada plano define la selección (🎯 texto, puntos o 🎞 vídeo de máscara) y el modo de generación (", "每个镜头设置选区（🎯 文本、点或 🎞 蒙版视频）和生成方式（"],
+  "🎞 Mask video (whole video)": ["🎞 Vídeo de máscara (vídeo inteiro)", "🎞 Vídeo de máscara (vídeo completo)", "🎞 蒙版视频（整个视频）"],
+  "— none: SAM 3 per shot —": ["— nenhum: SAM 3 por plano —", "— ninguno: SAM 3 por plano —", "— 无：每个镜头使用 SAM 3 —"], "Fill holes": ["Preencher buracos", "Rellenar huecos", "填充孔洞"], "Invert": ["Inverter", "Invertir", "反转"],
+  "Show masks on shots": ["Mostrar máscaras nos planos", "Mostrar máscaras en los planos", "在镜头卡片上显示蒙版"], "Expand (px)": ["Expandir (px)", "Expandir (px)", "扩展（像素）"],
+  "Temporal expand (frames)": ["Expansão temporal (frames)", "Expansión temporal (fotogramas)", "时间扩展（帧）"], "Detection threshold": ["Limiar de detecção", "Umbral de detección", "检测阈值"], "Max objects": ["Máx. objetos", "Máx. objetos", "最大对象数"],
+  "Crop padding (%)": ["Margem do recorte (%)", "Margen del recorte (%)", "裁剪边距（%）"], "Feather (px)": ["Suavização da borda (px)", "Suavizado del borde (px)", "羽化（像素）"], "Paste back": ["Colar de volta", "Pegar de vuelta", "贴回方式"],
+  "only the mask (feathered)": ["somente a máscara (suavizada)", "solo la máscara (suavizada)", "仅蒙版（羽化边缘）"], "the whole box (feathered)": ["a caixa inteira (suavizada)", "todo el cuadro (suavizado)", "整个框（羽化边缘）"], "Blockify (px, 0 = off)": ["Blocos (px, 0 = desligado)", "Bloques (px, 0 = desactivado)", "块化（像素，0 = 关闭）"],
+  "Uses the official sam3.1_multiplex_fp16 checkpoint (models/checkpoints), downloaded from Comfy-Org/sam3.1 the first time.": ["Usa o checkpoint oficial sam3.1_multiplex_fp16 (models/checkpoints), baixado de Comfy-Org/sam3.1 na primeira utilização.", "Usa el checkpoint oficial sam3.1_multiplex_fp16 (models/checkpoints), descargado de Comfy-Org/sam3.1 la primera vez.", "使用官方 sam3.1_multiplex_fp16 检查点（models/checkpoints），首次运行时从 Comfy-Org/sam3.1 下载。"],
+  "SAM 3": ["SAM 3", "SAM 3", "SAM 3"], "track faces, link each person to a reference, split and assign shots by who is on screen": ["rastreie rostos, associe cada pessoa a uma referência e organize os planos por quem aparece", "rastrea rostros, vincula cada persona a una referencia y organiza los planos según quién aparece", "跟踪人脸、关联参考图，并按出镜人物分配镜头"],
+  "Global reference & prompt": ["Referência e prompt globais", "Referencia y prompt globales", "全局参考图和提示词"], "defaults for every shot": ["padrão para todos os planos", "valor predeterminado para cada plano", "所有镜头的默认设置"],
+  "who the shot becomes": ["em quem o plano será transformado", "en quién se transforma el plano", "镜头中的人物将替换为谁"], "Prompt for this shot (empty = global prompt). Placeholders: {target} {details} {shot} {setting}": ["Prompt deste plano (vazio = prompt global). Variáveis: {target} {details} {shot} {setting}", "Prompt de este plano (vacío = prompt global). Variables: {target} {details} {shot} {setting}", "此镜头的提示词（留空则使用全局提示词）。占位符：{target} {details} {shot} {setting}"],
+  "recent (click = ref, shift+click = ref 2):": ["recentes (clique = ref., Shift+clique = ref. 2):", "recientes (clic = ref., Mayús+clic = ref. 2):", "最近使用（点击 = 参考图，Shift+点击 = 参考图 2）："], "✕ clear": ["✕ limpar", "✕ borrar", "✕ 清除"], "✕ clear all": ["✕ limpar tudo", "✕ borrar todo", "✕ 全部清除"], "Use global": ["Usar global", "Usar global", "使用全局设置"],
+  "empty slots use the person's reference (Cast) or the global one (Prompts & refs tab)": ["campos vazios usam a referência da pessoa (Elenco) ou a global (aba Prompts e referências)", "los campos vacíos usan la referencia de la persona (Reparto) o la global (Prompts y referencias)", "空白项使用人物参考图（角色）或全局参考图（提示词和参考图选项卡）"],
+  "Full frame": ["Quadro inteiro", "Fotograma completo", "整帧"], "The whole frame is regenerated. The mask, if any, only feeds {target} / the setting picture.": ["O quadro inteiro é gerado novamente. A máscara, se houver, só fornece {target} / a imagem de cenário.", "Se vuelve a generar todo el fotograma. La máscara, si existe, solo aporta {target} / la imagen del escenario.", "重新生成整帧。蒙版（如有）仅用于提供 {target} / 场景参考图。"],
+  "Only the mask is regenerated, on the whole frame: the rest stays exactly as it was. No crop / uncrop.": ["Somente a área da máscara é regenerada; o restante permanece igual. Sem recorte.", "Solo se regenera el área de la máscara; el resto permanece igual. Sin recorte.", "仅重新生成蒙版区域，其余部分保持不变。不进行裁剪。"],
+  "A box around the mask is regenerated (more pixels for a small subject); BFS Shot Join pastes it back.": ["A caixa ao redor da máscara é regenerada (mais pixels para pessoas pequenas); o BFS Shot Join cola o resultado de volta.", "Se regenera el cuadro alrededor de la máscara (más píxeles para sujetos pequeños); BFS Shot Join lo pega de vuelta.", "重新生成蒙版周围的区域（为较小主体提供更多像素）；BFS Shot Join 会将其贴回。"],
+  "Inside the crop, only the mask is regenerated: the most detail with the background kept.": ["Dentro do recorte, somente a máscara é regenerada: mais detalhes e fundo preservado.", "Dentro del recorte, solo se regenera la máscara: más detalle y fondo conservado.", "仅重新生成裁剪区域内的蒙版：细节更多，同时保留背景。"],
+  "The whole frame is generated (the pose follows the guide, the new subject may be bigger); BFS Shot Join pastes only the subject onto the original: background exact.": ["O quadro inteiro é gerado (a pose segue o guia e o novo sujeito pode ser maior); o BFS Shot Join cola apenas o sujeito no original e preserva o fundo.", "Se genera todo el fotograma (la pose sigue la guía y el sujeto puede ser más grande); BFS Shot Join pega solo al sujeto sobre el original y conserva el fondo.", "生成整帧（姿势遵循引导，主体可更大）；BFS Shot Join 仅将主体贴回原画面，背景保持原样。"],
+  "🎯 Points…": ["🎯 Pontos…", "🎯 Puntos…", "🎯 点…"], "👁 Preview": ["👁 Prévia", "👁 Vista previa", "👁 预览"], "✕ Clear": ["✕ Limpar", "✕ Borrar", "✕ 清除"],
+  "🎞 mask video": ["🎞 vídeo de máscara", "🎞 vídeo de máscara", "🎞 蒙版视频"], "↳ global prompt": ["↳ prompt global", "↳ prompt global", "↳ 全局提示词"], "— no prompt —": ["— sem prompt —", "— sin prompt —", "— 无提示词 —"],
+  "▶ Play all": ["▶ Reproduzir todos", "▶ Reproducir todos", "▶ 播放全部"], "■ Stop": ["■ Parar", "■ Detener", "■ 停止"], "loop shot": ["repetir plano", "repetir plano", "循环播放镜头"],
+  "Click the timeline to seek. Play all skips shots that will not run.": ["Clique na linha do tempo para buscar. Reproduzir todos ignora planos que não serão executados.", "Haz clic en la línea de tiempo para buscar. Reproducir todos omite los planos que no se ejecutarán.", "点击时间轴进行定位。播放全部会跳过不运行的镜头。"],
+  "Reference & prompt": ["Referência e prompt", "Referencia y prompt", "参考图和提示词"], "Who is replaced": ["Quem será substituído", "Quién se reemplaza", "替换对象"], "Continuity": ["Continuidade", "Continuidad", "连续性"],
+  "Global reference & prompt": ["Referência e prompt globais", "Referencia y prompt globales", "全局参考图和提示词"], "Describe references ({details})": ["Descrever referências ({details})", "Describir referencias ({details})", "描述参考图（{details}）"],
+  "Custom": ["Personalizado", "Personalizado", "自定义"], "short": ["curto", "breve", "简短"], "full body": ["corpo inteiro", "cuerpo entero", "全身"], "head / face": ["cabeça / rosto", "cabeza / rostro", "头部/面部"], "face attributes": ["características do rosto", "rasgos faciales", "面部特征"], "outfit": ["roupa", "ropa", "服装"],
+  "Apply suggestions → all": ["Aplicar sugestões → todos", "Aplicar sugerencias → todos", "应用建议 → 全部"], "fit the prompt": ["ajustar ao prompt", "ajustar al prompt", "适配提示词"],
+  "Connect a Qwen3-VL (CLIPLoader) to the planner's vlm input. The VLM buttons work after the workflow has run once with it connected (ComfyUI only hands models to nodes when they run). Each shot's suggestion shows in its editor.": ["Conecte um Qwen3-VL (CLIPLoader) à entrada vlm do planner. Os botões do VLM funcionam depois que o workflow executar uma vez com ele conectado. A sugestão de cada plano aparece no editor.", "Conecta un Qwen3-VL (CLIPLoader) a la entrada vlm del planificador. Los botones del VLM funcionan después de ejecutar el flujo una vez con él conectado. La sugerencia de cada plano aparece en su editor.", "将 Qwen3-VL（CLIPLoader）连接到规划器的 vlm 输入。工作流连接后运行一次，VLM 按钮即可使用。每个镜头的建议会显示在其编辑器中。"],
+  "look at every shot and suggests the mask, a description and whether to run it": ["analisa cada plano e sugere máscara, descrição e se deve ser executado", "analiza cada plano y sugiere una máscara, una descripción y si debe ejecutarse", "分析每个镜头并建议蒙版、描述及是否运行"],
+  "🎯 Track → whole video": ["🎯 Rastrear → vídeo inteiro", "🎯 Seguir → vídeo completo", "🎯 跟踪 → 整个视频"], "Save (this shot)": ["Salvar (este plano)", "Guardar (este plano)", "保存（此镜头）"], "Save → all shots": ["Salvar → todos os planos", "Guardar → todos los planos", "保存 → 所有镜头"], "Cancel": ["Cancelar", "Cancelar", "取消"], "Clear points": ["Limpar pontos", "Borrar puntos", "清除点"], "👁 Segment": ["👁 Segmentar", "👁 Segmentar", "👁 分割"],
+  "Apply these points to EVERY shot, each on its frame at the same relative position (a subject that stays in place)": ["Aplicar estes pontos a TODOS os planos, na mesma posição relativa (para um sujeito que não muda de lugar)", "Aplicar estos puntos a TODOS los planos, en la misma posición relativa (si el sujeto no se mueve)", "将这些点应用到每个镜头的相同相对位置（适用于位置不变的主体）"],
+  "the range starts at the player's frame": ["o trecho começa no frame atual do player", "el rango empieza en el fotograma actual", "范围从播放器当前帧开始"], "the range ends after the player's frame": ["o trecho termina após o frame atual do player", "el rango termina después del fotograma actual", "范围在播放器当前帧之后结束"],
+  "Nothing to fix in the shots that run.": ["Nenhum problema nos planos que serão executados.", "No hay nada que corregir en los planos que se ejecutarán.", "将运行的镜头没有需要修复的问题。"], "all good": ["tudo certo", "todo bien", "一切正常"], "warning(s)": ["aviso(s)", "aviso(s)", "条警告"], "note(s)": ["observação(ões)", "nota(s)", "条备注"],
+  "quick tests": ["testes rápidos", "pruebas rápidas", "快速测试"], "from the start of the range": ["a partir do início do trecho", "desde el inicio del rango", "从范围起点开始"], "Each run generates one shot and stores it. Nodes after BFS Shot Join only run on the last shot, with the full video.": ["Cada execução gera e salva um plano. Os nodes após BFS Shot Join só executam no último plano, com o vídeo completo.", "Cada ejecución genera y guarda un plano. Los nodos posteriores a BFS Shot Join solo se ejecutan en el último plano, con el vídeo completo.", "每次运行生成并保存一个镜头。BFS Shot Join 后的节点仅在最后一个镜头运行，并接收完整视频。"],
+  "skipped shots do not run": ["planos ignorados não são executados", "los planos omitidos no se ejecutan", "跳过的镜头不会运行"], "only shots that run": ["somente planos executados", "solo los planos que se ejecutan", "仅统计将运行的镜头"],
+  "off": ["desligado", "desactivado", "关闭"], "on": ["ligado", "activado", "开启"], "run": ["executar", "ejecutar", "运行"], "skip": ["ignorar", "omitir", "跳过"], "filters decide": ["filtros decidem", "deciden los filtros", "由筛选条件决定"], "always run": ["sempre executar", "ejecutar siempre", "始终运行"], "always skip": ["sempre ignorar", "omitir siempre", "始终跳过"], "⏸ Disable": ["⏸ Desativar", "⏸ Desactivar", "⏸ 禁用"], "▶ Enable": ["▶ Ativar", "▶ Activar", "▶ 启用"], "✂ Split": ["✂ Dividir", "✂ Dividir", "✂ 拆分"], "⇥ Merge": ["⇥ Unir", "⇥ Unir", "⇥ 合并"],
+  "Advanced": ["Avançado", "Avanzado", "高级"], "English": ["Inglês", "Inglés", "英语"], "Português": ["Português", "Portugués", "葡萄牙语"], "Español": ["Espanhol", "Español", "西班牙语"], "中文": ["Chinês", "Chino", "中文"],
+  "Color Guide": ["Guia de cores", "Guía de color", "颜色引导"], "Video": ["Vídeo", "Vídeo", "视频"], "Shots": ["Planos", "Planos", "镜头"], "Prompts": ["Prompts", "Prompts", "提示词"],
+  "Guide color · Ref 1": ["Cor guia · Ref. 1", "Color guía · Ref. 1", "引导颜色 · 参考图 1"], "Guide color · Ref 2": ["Cor guia · Ref. 2", "Color guía · Ref. 2", "引导颜色 · 参考图 2"],
+  "These colors are defaults for the global references. Turn on Color Guide on a shot to apply them; shot-level colors can override them.": ["Estas cores são os padrões das referências globais. Ative o Guia de cores no plano para aplicá-las; cada plano pode substituí-las.", "Estos colores son los valores predeterminados de las referencias globales. Activa la Guía de color en un plano para aplicarlos; cada plano puede cambiarlos.", "这些颜色是全局参考图的默认值。启用镜头的颜色引导即可应用；镜头也可以单独覆盖。"],
+  "Audio": ["Áudio", "Audio", "音频"], "use the video's audio": ["usar o áudio do vídeo", "usar el audio del vídeo", "使用视频音频"], "silent track": ["faixa silenciosa", "pista silenciosa", "静音音轨"],
+  "auto": ["automático", "automático", "自动"], "fixed": ["fixo", "fijo", "固定"], "single": ["único", "único", "单个"], "adaptive": ["adaptativo", "adaptativo", "自适应"], "content": ["conteúdo", "contenido", "内容"], "builtin": ["integrado", "integrado", "内置"],
+  "PySceneDetect adaptive": ["PySceneDetect adaptativo", "PySceneDetect adaptativo", "PySceneDetect 自适应"], "PySceneDetect content": ["PySceneDetect por conteúdo", "PySceneDetect por contenido", "PySceneDetect 内容检测"], "Built-in": ["Integrado", "Integrado", "内置"],
+  "Auto loop": ["Loop automático", "Bucle automático", "自动循环"], "Queue loop": ["Loop em fila", "Bucle en cola", "队列循环"], "queue loop": ["loop em fila", "bucle en cola", "队列循环"], "auto loop": ["loop automático", "bucle automático", "自动循环"],
+  "no audio": ["sem áudio", "sin audio", "无音频"], "silent track": ["faixa silenciosa", "pista silenciosa", "静音音轨"], "timeline": ["linha do tempo", "línea de tiempo", "时间轴"], "generate at": ["gerar em", "generar a", "生成尺寸"],
+  "Max person size (0-1 of frame)": ["Tamanho mínimo da pessoa (0–1 do quadro)", "Tamaño mínimo de persona (0–1 del fotograma)", "人物最小尺寸（占画面 0–1）"], "Min person size (0-1 of frame)": ["Tamanho mínimo da pessoa (0–1 do quadro)", "Tamaño mínimo de persona (0–1 del fotograma)", "人物最小尺寸（占画面 0–1）"],
+  "Max people (0 = any)": ["Máx. pessoas (0 = qualquer)", "Máx. personas (0 = cualquiera)", "人物上限（0 = 不限）"], "Min frames (0 = off)": ["Mín. frames (0 = desligado)", "Mín. fotogramas (0 = desactivado)", "最少帧数（0 = 关闭）"], "Frames sampled / shot": ["Frames amostrados por plano", "Fotogramas muestreados por plano", "每个镜头采样帧数"], "Dark below (0-1)": ["Escuro abaixo de (0–1)", "Oscuro por debajo de (0–1)", "暗度低于（0–1）"], "Static below": ["Estático abaixo de", "Estático por debajo de", "静止度低于"],
+  "e.g. 0.03 skips wide shots": ["ex.: 0,03 ignora planos abertos", "p. ej., 0,03 omite planos amplios", "例如 0.03 会跳过远景镜头"], "skip crowds": ["ignorar multidões", "omitir multitudes", "跳过人群"], "re-analyses": ["reanalisar", "vuelve a analizar", "重新分析"],
+  "Describe target": ["Descrever alvo", "Describir objetivo", "描述目标"], "🧑 Describe target": ["🧑 Descrever alvo", "🧑 Describir objetivo", "🧑 描述目标"], "new subject": ["novo sujeito", "nuevo sujeto", "新主体"], "person (or dog, cat, car… what the result shows)": ["pessoa (ou cão, gato, carro… o que aparecerá no resultado)", "persona (o perro, gato, coche… lo que aparecerá en el resultado)", "人物（或狗、猫、汽车等结果中的主体）"],
+  "The second person (optional)": ["Segunda pessoa (opcional)", "Segunda persona (opcional)", "第二个人（可选）"], "Follow cast": ["Seguir identidade", "Seguir reparto", "跟随角色"], "manual identity": ["identidade manual", "identidad manual", "手动身份"],
+  "Guide video": ["Vídeo guia", "Vídeo guía", "引导视频"], "Reference": ["Referência", "Referencia", "参考图"], "Prompt": ["Prompt", "Prompt", "提示词"], "reference": ["referência", "referencia", "参考图"],
+  "on": ["ativado", "activado", "开启"], "off": ["desativado", "desactivado", "关闭"], "not analysed": ["não analisado", "sin analizar", "未分析"], "not analyzed": ["não analisado", "sin analizar", "未分析"],
+  "No shots yet": ["Nenhum plano ainda", "Aún no hay planos", "尚无镜头"], "No video": ["Nenhum vídeo", "Sin vídeo", "没有视频"], "No faces": ["Nenhum rosto", "Sin rostros", "没有人脸"], "no faces": ["sem rostos", "sin rostros", "没有人脸"],
+  "cut": ["corte", "corte", "切换"], "run": ["executar", "ejecutar", "运行"], "skip": ["ignorar", "omitir", "跳过"], "skip this shot": ["ignorar este plano", "omitir este plano", "跳过此镜头"],
+  "people": ["pessoas", "personas", "人物"], "person": ["pessoa", "persona", "人物"], "shots": ["planos", "planos", "镜头"], "shot(s)": ["plano(s)", "plano(s)", "个镜头"], "linked": ["vinculada", "vinculada", "已关联"], "main": ["principal", "principal", "主要"],
+  "No VLM yet": ["Nenhum VLM carregado", "Aún no hay un VLM", "尚未加载 VLM"], "Connect a Qwen3-VL": ["Conecte um Qwen3-VL", "Conecta un Qwen3-VL", "连接 Qwen3-VL"],
+  "↻ Status": ["↻ Status", "↻ Estado", "↻ 状态"], "⟲ Reset loop": ["⟲ Reiniciar loop", "⟲ Reiniciar bucle", "⟲ 重置循环"], "Queue loop": ["Loop em fila", "Bucle en cola", "队列循环"],
+  "Start here": ["Começar aqui", "Empezar aquí", "从此处开始"], "End here": ["Terminar aqui", "Terminar aquí", "在此处结束"], "reset": ["redefinir", "restablecer", "重置"], "all shots": ["todos os planos", "todos los planos", "所有镜头"], "this shot": ["este plano", "este plano", "此镜头"],
+  "Describe target": ["Descrever alvo", "Describir objetivo", "描述目标"], "Settings": ["Configurações", "Ajustes", "设置"], "mask text": ["texto da máscara", "texto de máscara", "蒙版描述"],
+  "The global reference and prompt are used when a shot has no values of its own.": ["A referência e o prompt globais são usados quando um plano não tem valores próprios.", "La referencia y el prompt globales se usan cuando un plano no tiene valores propios.", "镜头没有单独设置时会使用全局参考图和提示词。"],
+  "A VLM is optional": ["O VLM é opcional", "El VLM es opcional", "VLM 为可选项"], "Optional": ["Opcional", "Opcional", "可选"], "optional": ["opcional", "opcional", "可选"],
+  "person in white": ["pessoa de branco", "persona de blanco", "穿白衣的人"], "woman in pink top": ["mulher de blusa rosa", "mujer con blusa rosa", "穿粉色上衣的女人"],
+  "nothing found": ["nada encontrado", "no se encontró nada", "未找到内容"], "not found": ["não encontrado", "no encontrado", "未找到"], "Preview": ["Prévia", "Vista previa", "预览"],
+  "Mask only / Crop + mask": ["Somente máscara / Recorte + máscara", "Solo máscara / Recorte + máscara", "仅蒙版 / 裁剪并蒙版"], "per shot (planner)": ["por plano (planner)", "por plano (planificador)", "逐镜头（规划器）"],
+  "Person": ["Pessoa", "Persona", "人物"], "shot": ["plano", "plano", "镜头"], "shot(s)": ["plano(s)", "plano(s)", "个镜头"],
+  "mask covers": ["máscara cobre", "la máscara cubre", "蒙版覆盖"], "nothing to fix": ["nada a corrigir", "nada que corregir", "无需修复"],
+  "Camera cuts: shots start at the detected cuts, long ones are split evenly. Fixed length: equal parts no longer than the maximum.": ["Cortes de câmera: os planos começam nos cortes detectados; planos longos são divididos igualmente. Duração fixa: partes iguais limitadas pelo máximo.", "Cortes de cámara: los planos empiezan en los cortes detectados; los largos se dividen por igual. Duración fija: partes iguales con el máximo indicado.", "镜头切换：镜头从检测到的切点开始，较长镜头会均匀拆分。固定时长：拆分为不超过上限的等长片段。"],
+  "Cut detector. PySceneDetect adaptive works on most footage (fast camera moves don't trigger it); content is stricter on hard cuts; built-in needs no package.": ["Detector de cortes. O modo adaptativo do PySceneDetect funciona na maioria dos vídeos (movimentos rápidos de câmera não acionam cortes); o modo conteúdo é mais rigoroso; o integrado não exige pacote.", "Detector de cortes. El modo adaptativo de PySceneDetect funciona en la mayoría de vídeos (los movimientos rápidos no activan cortes); contenido es más estricto; el integrado no requiere paquetes.", "镜头切换检测器。PySceneDetect 自适应模式适用于大多数素材（快速运镜不会触发切点）；内容模式对硬切更严格；内置模式无需额外软件包。"],
+  "How easily a change counts as a cut. Higher finds more cuts (and more false ones).": ["O quanto uma mudança é considerada corte. Um valor maior encontra mais cortes e também mais falsos positivos.", "Facilidad con la que un cambio cuenta como corte. Un valor mayor detecta más cortes y también más falsos positivos.", "变化被判定为切点的难易程度。数值越高，检测到的切点越多，误报也越多。"],
+  "Frame counts the model accepts. H3: 17n+5, LTX/Wan: 8n+1, Wan: 4n+1. Each shot is generated at the next valid length and trimmed back.": ["Contagens de frames aceitas pelo modelo. H3: 17n+5; LTX/Wan: 8n+1; Wan: 4n+1. Cada plano é gerado no próximo comprimento válido e depois aparado.", "Cantidad de fotogramas que acepta el modelo. H3: 17n+5; LTX/Wan: 8n+1; Wan: 4n+1. Cada plano se genera con la siguiente duración válida y luego se recorta.", "模型接受的帧数规则。H3：17n+5；LTX/Wan：8n+1；Wan：4n+1。每个镜头按下一个有效长度生成后再裁短。"],
+  "Longest shot sent to the model. Keep it within what the model / LoRA was trained on (H3 body swap: about 4.5 s).": ["Duração máxima enviada ao modelo. Mantenha dentro do que o modelo/LoRA aprendeu (body swap H3: cerca de 4,5 s).", "Duración máxima enviada al modelo. Respeta lo usado en el entrenamiento del modelo/LoRA (body swap H3: unos 4,5 s).", "发送给模型的镜头最长时长。应符合模型/LoRA 的训练长度（H3 换人约 4.5 秒）。"],
+  "Shorter shots merge into a neighbour when the merge still fits the maximum.": ["Planos mais curtos são unidos ao vizinho quando a junção ainda respeita o máximo.", "Los planos más cortos se unen al vecino si la unión respeta el máximo.", "较短镜头会在合并后仍未超过上限时与相邻镜头合并。"],
+  "The planner works on this frame rate (the source is resampled). Generated video and audio use it too.": ["O planner usa esta taxa de frames (o vídeo de origem é reamostrado). O vídeo e áudio gerados também a usam.", "El planificador usa esta frecuencia de fotogramas (el origen se remuestrea). El vídeo y el audio generados también la usan.", "规划器使用此帧率（源视频会重新采样）。生成的视频和音频也会使用此帧率。"],
+  "Only the first N shots (0 = all). Handy for quick tests.": ["Somente os primeiros N planos (0 = todos). Útil para testes rápidos.", "Solo los primeros N planos (0 = todos). Útil para pruebas rápidas.", "仅处理前 N 个镜头（0 = 全部）。适合快速测试。"],
+  "Only the first N seconds of the video (0 = all).": ["Somente os primeiros N segundos do vídeo (0 = todos).", "Solo los primeros N segundos del vídeo (0 = todos).", "仅处理视频前 N 秒（0 = 全部）。"],
+  "Generation size: the source aspect ratio at this pixel area (0.15 ≈ 512×288). Cropped shots use it for the crop.": ["Tamanho da geração: mantém a proporção do vídeo nessa área de pixels (0,15 ≈ 512×288). Planos recortados usam esse valor no recorte.", "Tamaño de generación: mantiene la proporción de origen con esta área de píxeles (0,15 ≈ 512×288). Los planos recortados usan este valor.", "生成尺寸：按此像素面积保持源视频宽高比（0.15 ≈ 512×288）。裁剪镜头使用此尺寸。"],
+  "Width and height snap to this multiple (32 for H3 and most video models).": ["Largura e altura são ajustadas a este múltiplo (32 para H3 e a maioria dos modelos de vídeo).", "El ancho y alto se ajustan a este múltiplo (32 para H3 y la mayoría de modelos de vídeo).", "宽度和高度会对齐到此倍数（H3 和多数视频模型使用 32）。"],
+  "Auto loop: every shot in one queue run. Queue loop: one shot per run, stored on disk, the join outputs the video after the last shot.": ["Loop automático: todos os planos em uma execução da fila. Loop em fila: um plano por execução, salvo em disco; o join gera o vídeo após o último plano.", "Bucle automático: todos los planos en una ejecución. Bucle en cola: un plano por ejecución, guardado en disco; el join genera el vídeo al terminar el último.", "自动循环：一次队列运行所有镜头。队列循环：每次运行一个镜头并保存到磁盘；最后一个镜头完成后由 Join 输出视频。"],
+  "Shots that do not run: keep the original video there, or remove them (with their audio).": ["Planos não executados: manter o vídeo original nesses trechos ou removê-los junto com o áudio.", "Planos que no se ejecutan: conserva el vídeo original en ese tramo o elimínalo junto con su audio.", "未运行的镜头：保留对应原视频片段，或连同音频一起移除。"],
+  "Context kept around the mask's box, as a % of the box. More context blends better; less gives the model more pixels on the subject.": ["Contexto mantido ao redor da caixa da máscara, como porcentagem da caixa. Mais contexto mistura melhor; menos dá mais pixels ao sujeito.", "Contexto alrededor del cuadro de la máscara, como porcentaje. Más contexto mezcla mejor; menos ofrece más píxeles al sujeto.", "蒙版边框周围保留的上下文比例。上下文越多越容易融合；越少则主体像素越多。"],
+  "Grow the mask by this many pixels: before pasting a cropped result back, and for the generation mask (inpaint 'only the mask'). Raise it when the new person is bigger than the old one (longer hair, wider body).": ["Expande a máscara por esta quantidade de pixels antes de colar o recorte e na máscara de geração. Aumente se a nova pessoa for maior (cabelo mais comprido, corpo mais largo).", "Amplía la máscara esta cantidad de píxeles antes de pegar el recorte y para la máscara de generación. Auméntala si la persona nueva es más grande.", "粘贴裁剪结果前以及生成蒙版时，将蒙版扩展指定像素。新人物更大时（头发更长、身体更宽）可调高。"],
+  "Soft edge of the paste-back, in pixels.": ["Suavização da borda ao colar de volta, em pixels.", "Suavizado del borde al pegar de vuelta, en píxeles.", "贴回时边缘的柔化像素数。"],
+  "Hold the mask this many frames before and after: removes flicker where SAM 3 drops a frame.": ["Estende a máscara por esta quantidade de frames antes e depois; reduz falhas quando o SAM 3 perde um frame.", "Mantiene la máscara estos fotogramas antes y después; reduce parpadeos cuando SAM 3 pierde uno.", "蒙版前后延续指定帧数，减少 SAM 3 漏掉某帧时的闪烁。"],
+  "Square blocks of this size (0 = off). 16 matches H3's latent grid, useful as an inpainting mask.": ["Blocos quadrados deste tamanho (0 = desligado). 16 corresponde à grade latente do H3 e pode ser útil como máscara de inpainting.", "Bloques cuadrados de este tamaño (0 = desactivado). 16 coincide con la cuadrícula latente de H3 y sirve para inpainting.", "使用此尺寸的方块（0 = 关闭）。16 与 H3 潜空间网格匹配，可用于修补蒙版。"],
+  "SAM 3 score needed to keep a text match. Lower finds more (and more wrong) objects.": ["Pontuação mínima do SAM 3 para manter uma correspondência por texto. Valores menores encontram mais objetos, inclusive incorretos.", "Puntuación mínima de SAM 3 para conservar una coincidencia de texto. Un valor menor encuentra más objetos, también erróneos.", "保留文本匹配所需的 SAM 3 分数。调低会找到更多对象，也会增加误检。"],
+  "How many matches of the text prompt are tracked together.": ["Quantas correspondências do texto serão rastreadas juntas.", "Cuántas coincidencias del texto se siguen a la vez.", "同时跟踪多少个符合文本的对象。"],
+  "Only the mask: the result replaces the masked pixels. The whole box: the full crop is pasted with feathered borders.": ["Somente máscara: o resultado substitui os pixels mascarados. Caixa inteira: todo o recorte é colado com bordas suaves.", "Solo máscara: el resultado sustituye los píxeles enmascarados. Cuadro completo: se pega todo el recorte con bordes suavizados.", "仅蒙版：结果替换蒙版像素。整个框：粘贴完整裁剪区域并柔化边缘。"],
+  "How many frames of each shot the VLM looks at.": ["Quantos frames de cada plano o VLM analisa.", "Cuántos fotogramas de cada plano analiza el VLM.", "VLM 分析每个镜头的帧数。"], "Longest VLM answer. Raise it for long descriptions.": ["Tamanho máximo da resposta do VLM. Aumente para descrições longas.", "Longitud máxima de respuesta del VLM. Auméntala para descripciones largas.", "VLM 回复的最大长度。长描述可调高。"],
+};
+export function t(value) {
+  const s = String(value ?? ""), lang = uiLanguage.value;
+  if (lang === "en") return s;
+  const entry = TEXT[s];
+  if (entry) return entry[{ pt: 0, es: 1, zh: 2 }[lang]];
+  let m;
+  if ((m = s.match(/^Person (\d+)$/))) return `${t("Person")} ${m[1]}`;
+  if ((m = s.match(/^Shot #(\d+)( · points)?$/))) return `${t("Shot")} #${m[1]}${m[2] ? ` · ${lang === "pt" ? "pontos" : lang === "es" ? "puntos" : "点"}` : ""}`;
+  if ((m = s.match(/^(\d+) people · (\d+) linked$/))) return lang === "pt" ? `${m[1]} pessoas · ${m[2]} vinculadas` : lang === "es" ? `${m[1]} personas · ${m[2]} vinculadas` : `${m[1]} 人物 · 已关联 ${m[2]} 人`;
+  if ((m = s.match(/^(\d+) shot\(s\) will run$/))) return lang === "pt" ? `${m[1]} plano(s) serão executados` : lang === "es" ? `se ejecutarán ${m[1]} plano(s)` : `将运行 ${m[1]} 个镜头`;
+  if ((m = s.match(/^(\d+) suggestions$/))) return lang === "pt" ? `${m[1]} sugestões` : lang === "es" ? `${m[1]} sugerencias` : `${m[1]} 条建议`;
+  if ((m = s.match(/^(\d+) shot\(s\)$/))) return lang === "pt" ? `${m[1]} plano(s)` : lang === "es" ? `${m[1]} plano(s)` : `${m[1]} 个镜头`;
+  if ((m = s.match(/^(\d+) warning\(s\) · (\d+) note\(s\)$/))) return lang === "pt" ? `${m[1]} aviso(s) · ${m[2]} observação(ões)` : lang === "es" ? `${m[1]} aviso(s) · ${m[2]} nota(s)` : `${m[1]} 条警告 · ${m[2]} 条备注`;
+  return s;
+}
+function localizeProps(props) {
+  if (!props || typeof props !== "object") return props;
+  let changed = false; const out = { ...props };
+  for (const k of ["title", "placeholder", "aria-label"]) if (typeof out[k] === "string") { const v = t(out[k]); changed ||= v !== out[k]; out[k] = v; }
+  return changed ? out : props;
+}
+function localizeChildren(value) {
+  if (typeof value === "string") return t(value);
+  if (Array.isArray(value)) return value.map(localizeChildren);
+  return value;
+}
+// All view modules use this h wrapper, so labels, placeholders, tooltips and section titles stay in sync.
+export function h(type, props, children) {
+  const hasChildrenArg = arguments.length >= 3;
+  if (!hasChildrenArg && props?.__v_isVNode) return vueH(type, null, props);
+  const p = localizeProps(props);
+  if (hasChildrenArg) return vueH(type, p, localizeChildren(children));
+  if (typeof props === "string" || Array.isArray(props)) return vueH(type, localizeChildren(props));
+  return vueH(type, p);
+}
 
 export const GRIDS = { "H3 (17n+5)": [17, 5], "LTX / Wan (8n+1)": [8, 1], "Wan (4n+1)": [4, 1], "any": [1, 0] };
 export const DEFAULTS = {
   video: "", fps: 24, grid: "H3 (17n+5)", mode: "shots", max_s: 4.5, min_s: 1.0, sensitivity: 0.5,
-  max_parts: 0, max_total_s: 0, start_s: 0, end_s: 0, start_f: null, end_f: null, track: null, bounds: [], segs: [], global_ref: "", global_ref2: "", global_prompt: "", mask_video: "",
+  max_parts: 0, max_total_s: 0, start_s: 0, end_s: 0, start_f: null, end_f: null, track: null, bounds: [], segs: [], global_ref: "", global_ref2: "", global_prompt: "", global_color_guide_ref1: "#00ff00", global_color_guide_ref2: "#9b30ff", mask_video: "",
   megapixels: 0.15, multiple: 32, detector: "adaptive", run: "auto", auto_continue: true,
   skip_fill: "original", audio_mode: "auto", ref_details: {}, mask_cfg: {}, vlm_cfg: {}, cast: {}, cast_assign: true, cast_split: false, cast_only: false,
   filters: { person: false, min_person_area: 0, max_persons: 0, face: false, skip_dark: false, dark_level: 0.06,

web/js/shotloop/styles.js

@@ -141,6 +141,8 @@ const CSS = `
 .bsl .refslot.sm{width:56px;height:56px;font-size:10px}
 .bsl .refslot.via{border-style:solid;border-color:#3b5b3b}
 .bsl .rslot{display:flex;flex-direction:column;gap:3px;align-items:center}
+.bsl .guidecolor{display:flex;flex-direction:column;align-items:center;gap:2px;max-width:112px}
+.bsl .guidecolor select{width:100%;font-size:10px;padding:2px 4px}
 .bsl .rbtns{display:flex;gap:3px;min-height:20px}
 .bsl .rbtns button{padding:1px 6px;font-size:10px}
 .bsl .recent{display:flex;gap:4px;flex-wrap:wrap;margin-top:6px;align-items:center}
@@ -180,6 +182,12 @@ const CSS = `
 .bsl .ck .lvl{font-size:12px}
 .bsl .prog{height:7px;border-radius:4px;background:#26262e;overflow:hidden}
 .bsl .prog>div{height:100%;background:linear-gradient(90deg,#3a63e0,#7fe0a8)}
+.bsl .langpick{display:flex;gap:5px;align-items:center}
+.bsl .langpick select{width:auto;min-width:100px;padding:4px 6px}
+.bsl .tourback{position:fixed;inset:0;z-index:10001;background:rgba(0,0,0,.68);display:flex;align-items:center;justify-content:center;padding:16px}
+.bsl .tourbox{width:min(480px,94vw);background:#1d1d23;border:1px solid #4a4a58;border-radius:12px;padding:16px;box-shadow:0 12px 48px #0009}
+.bsl .tourbox h3{margin:18px 0 8px;color:var(--hi)}
+.bsl .tourbox p{line-height:1.55}
 
 /* points window (teleported to <body>) */
 .bsl .mmodal{position:fixed;inset:0;background:rgba(0,0,0,.72);z-index:10000;display:flex;align-items:center;justify-content:center}

web/js/shotloop/view_modal.js

@@ -1,6 +1,6 @@
 // The busy bar and the points window (🎯 Points…: click on a frame to pick the subject for SAM 3).
-import { h, Teleport } from "../vendor/vue.esm-browser.prod.mjs";
-import { hint } from "./common.js";
+import { Teleport } from "../vendor/vue.esm-browser.prod.mjs";
+import { h, hint, t } from "./common.js";
 
 export function busyBar(c, msg) {
   const { busySince, now, upPct, status } = c;
@@ -60,3 +60,37 @@ export function pointsModal(c) {
     ]),
   ])));
 }
+
+const TOUR_STEPS = [
+  ["video", "Video", "Choose a video, set the frame range, split at camera cuts, then set the generation size."],
+  ["shots", "Shots", "Review each shot, assign its references and prompt, and choose how the result is applied."],
+  ["people", "People", "Link detected people to references. Set masks here or per shot; ArcFace links are a guide and need your review."],
+  ["prompts", "Prompts", "Set shared references, prompts and optional VLM assistance. Written prompts are kept exactly as authored."],
+  ["shots", "Color Guide", "Color Guide adds a translucent marker to a selected person. Ref 1 and Ref 2 must use different colors in the same shot."],
+  ["run", "Run", "Check warnings, choose auto or queue loop, and set filters or quick-run limits."],
+];
+
+export function tourModal(c) {
+  const { tour, tab } = c;
+  const step = tour.value - 1;
+  if (step < 0 || step >= TOUR_STEPS.length) return null;
+  const [targetTab, title, body] = TOUR_STEPS[step];
+  return h(Teleport, { to: "body" }, h("div", { class: "bsl", style: "background:none;padding:0" },
+    h("div", { class: "tourback", role: "dialog", "aria-modal": "true", "aria-label": t("Shot Planner tour"),
+      onKeydown: e => { if (e.key === "Escape") tour.value = 0; }, onPointerdown: e => { if (e.target === e.currentTarget) tour.value = 0; } }, [
+    h("div", { class: "tourbox" }, [
+      h("div", { class: "row" }, [h("b", t("Shot Planner tour")), h("span", { class: "grow" }), h("span", { class: "hint" }, `${step + 1} / ${TOUR_STEPS.length}`),
+        h("button", { class: "ghost", title: t("Close tour"), "aria-label": t("Close tour"), onClick: () => { tour.value = 0; } }, "✕")]),
+      h("h3", t(title)),
+      h("p", t(body)),
+      h("p", { class: "hint" }, t("This tour is optional. Use Next to visit each main tab; close it whenever you like.")),
+      h("div", { class: "row", style: "justify-content:flex-end;margin-top:12px" }, [
+        step > 0 ? h("button", { onClick: () => { tour.value--; tab.value = TOUR_STEPS[step - 1][0]; } }, t("Back")) : null,
+        h("button", { class: "pri", onClick: () => {
+          if (step === TOUR_STEPS.length - 1) tour.value = 0;
+          else { tour.value++; tab.value = TOUR_STEPS[step + 1][0]; }
+        } }, t(step === TOUR_STEPS.length - 1 ? "Close tour" : "Next")),
+      ]),
+    ]),
+  ])));
+}

web/js/shotloop/view_people.js

@@ -1,6 +1,8 @@
 // 👥 People & masks tab: the cast found by face (each person linked to a reference) and the global SAM 3 mask settings.
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { fmtT, fld, check, section, pill, hint } from "./common.js";
+import { h, fmtT, fld, check, section, pill, hint } from "./common.js";
+
+const CAST_COLORS = [["", "No Color Guide color"], ["#00ff00", "Green"], ["#9b30ff", "Purple"], ["#ff2020", "Red"], ["#168cff", "Blue"],
+  ["#ffe600", "Yellow"], ["#ff00d4", "Magenta"], ["#00e5c0", "Cyan"]];
 
 function castSection(c) {
   const { plan, people, busy, usedRefs } = c;
@@ -19,6 +21,11 @@ function castSection(c) {
         h("img", { class: "face", src: p.thumb, title: `first seen ${fmtT(p.first, fps)} (click to seek)`, onClick: () => c.seek(p.first) }),
         h("div", { class: "t" }, [h("b", `Person ${p.id}`), ` · ${(p.share * 100).toFixed(1)}%`]),
         h("div", { class: "t" }, `${fmtT(p.first, fps)} → ${fmtT(p.last, fps)}`),
+        h("div", { class: "row", style: "margin-top:4px;align-items:center" }, [
+          h("span", { class: "hint" }, "Color Guide identity color"),
+          h("select", { value: cc.guide_color || "", style: "width:auto", onChange: e => c.setCast(p.id, "guide_color", e.target.value) },
+            CAST_COLORS.map(([v, label]) => h("option", { value: v }, label))),
+        ]),
         h("div", { class: "refbox" }, ["ref", "ref2"].map(k => h("div", { class: "rslot" }, [
           h("div", { class: "refslot sm", title: cc[k] ? cc[k] + " (click to replace)" : "click to upload",
             onClick: () => c.pickFile("image/*", name => c.setCast(p.id, k, name)) }, cc[k] ? [h("img", { src: c.viewUrl(cc[k]) })] : [k === "ref" ? "⬆ ref" : "⬆ ref 2"]),

web/js/shotloop/view_prompts.js

@@ -1,6 +1,8 @@
 // 📝 Prompts & refs tab: the global reference / prompt, the VLM (shot suggestions) and the reference descriptions ({details}).
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { fld, check, section, pill, hint, select } from "./common.js";
+import { h, fld, check, section, pill, hint, select } from "./common.js";
+
+const GUIDE_COLORS = [["#00ff00", "Green"], ["#9b30ff", "Purple"], ["#ff2020", "Red"], ["#168cff", "Blue"],
+  ["#ffe600", "Yellow"], ["#ff00d4", "Magenta"], ["#00e5c0", "Cyan"]];
 
 function globalSection(c) {
   const { plan } = c;
@@ -8,6 +10,14 @@ function globalSection(c) {
     h("div", { class: "refslot", title: name ? name + " (click to replace)" : "click to upload", onClick: () => c.uploadRef("global", field) },
       name ? [h("img", { src: c.viewUrl(name) })] : [label]),
     h("div", { class: "rbtns" }, [name ? h("button", { title: "remove", onClick: () => c.setRef("global", field, "") }, "✕") : null]),
+    h("label", { class: "guidecolor" }, [
+      h("span", { class: "hint" }, field === "global_ref" ? "Guide color · Ref 1" : "Guide color · Ref 2"),
+      h("select", { value: field === "global_ref" ? (plan.global_color_guide_ref1 || "#00ff00") : (plan.global_color_guide_ref2 || "#9b30ff"),
+        disabled: !name,
+        title: "Default Color Guide marker when this global reference is used",
+        onChange: e => c.setPlan(field === "global_ref" ? "global_color_guide_ref1" : "global_color_guide_ref2", e.target.value) },
+        GUIDE_COLORS.map(([v, text]) => h("option", { value: v }, text))),
+    ]),
   ]);
   return section("Global reference & prompt", [
     h("div", { class: "row", style: "align-items:flex-start;gap:10px" }, [
@@ -21,6 +31,7 @@ function globalSection(c) {
       "Used by shots without their own. Connected ref_image / ref_image_2 / prompt inputs on the node override these. Placeholders: ",
       h("b", "{target}"), " who is replaced (per shot) · ", h("b", "{details}"), " description of the shot's references · ",
       h("b", "{shot}"), " the VLM's description of the shot · ", h("b", "{setting}"), " the setting picture (H3 Conditioning)."]),
+    h("div", { class: "hint", style: "margin-top:4px" }, "These colors are defaults for the global references. Turn on Color Guide on a shot to apply them; shot-level colors can override them."),
   ], { sub: "defaults for every shot" });
 }
 

web/js/shotloop/view_run.js

@@ -1,6 +1,5 @@
 // ▶ Run tab: checks before running, how the loop runs (auto / queue), which shots run (filters) and test limits.
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { fld, check, section, pill, hint, select } from "./common.js";
+import { h, fld, check, section, pill, hint, select } from "./common.js";
 
 function checksSection(c) {
   const { checks, tab } = c;

web/js/shotloop/view_shots.js

@@ -1,7 +1,10 @@
 // 🎬 Shots tab: one card per shot, then the selected shot's editor (preview, reference & prompt, who is replaced,
 // continuity, copy to other shots).
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { hue, fmtT, segKey, hasMask, maskSource, pill, hint, check, section } from "./common.js";
+import { h, hue, fmtT, segKey, hasMask, maskSource, pill, hint, check, section } from "./common.js";
+import { h as rawH } from "../vendor/vue.esm-browser.prod.mjs";
+
+const GUIDE_COLORS = [["#00ff00", "Green"], ["#9b30ff", "Purple"], ["#ff2020", "Red"], ["#168cff", "Blue"],
+  ["#ffe600", "Yellow"], ["#ff00d4", "Magenta"], ["#00e5c0", "Cyan"]];
 
 const bdg = (text, kind = "", title = "") => h("span", { class: ["bdg", kind], title }, text);
 
@@ -20,6 +23,7 @@ function shotCard(c, s, i) {
         track: bdg("🎯 track", "", "its part of the whole-video SAM 3 track"),
         sam: bdg("🎯 " + (s.mask.text ? s.mask.text.slice(0, 14) : `${(s.mask.points || []).length} pts`), "", s.mask.text || `${(s.mask.points || []).length} points`) }[maskSource(s)] || null,
       s.crop || s.inpaint || s.paste ? bdg({ paste: "🧩 frame+paste", mask: "🎭 mask only", crop: "✂ crop", cropmask: "✂🎭 crop+mask" }[c.modeOf(s)] + (s.inpaint && s.strength < 1 ? ` ${Number(s.strength).toFixed(2)}` : ""), "on", c.modeName(s)) : null,
+      s.color_guide ? bdg("🎨 color guide", "on", `${s.color_guide_color || "cast color"} · opacity ${s.color_guide_opacity ?? 0.35}`) : null,
       s.target ? bdg("🧑 target", "on", s.target) : null,
       i > 0 && s.chain !== "off" ? bdg("⛓", "on", s.chain === "history" ? `continues the previous shot's last ${s.chainHistory} frames (history)` : `continues from the previous shot's ${s.chainFrame} frame as ${s.chain}`) : null,
       warnN ? bdg(`⚠ ${warnN}`, "warn", issues.map(x => x.text).join("\n")) : null,
@@ -40,7 +44,8 @@ function shotCard(c, s, i) {
       h("img", { class: "rt", style: "width:56px", src: showMasks.value && mp?.frames?.length
         ? mp.frames[Math.floor(mp.frames.length / 2)].src : c.thumbFor(s.start + Math.floor(s.len / 2)) }),
     ]),
-    h("div", { class: "p" }, s.prompt ? s.prompt : (plan.global_prompt ? "↳ global prompt" : "— no prompt —")),
+    s.prompt ? rawH("div", { class: "p" }, s.prompt)
+      : h("div", { class: "p" }, plan.global_prompt ? "↳ global prompt" : "— no prompt —"),
   ]);
 }
 
@@ -82,6 +87,9 @@ function editor(c, cur) {
   const { plan, sel, segs, maskPrev, targetCrop, vlmSug, busy, usedRefs, copyOpts, COPY_FIELDS } = c;
   const i = sel.value, S = segs.value, k = segKey(cur), mp = maskPrev.value[k], g = vlmSug.value[k];
   const issues = c.checksFor(i);
+  const guideColor1 = cur.color_guide_color || (cur.color_guide_person != null
+    ? (c.castOf(cur.color_guide_person).guide_color || plan.global_color_guide_ref1 || "#00ff00")
+    : (plan.global_color_guide_ref1 || "#00ff00"));
   const viaRef = f => cur[f] ? "" : (c.castRef(cur, f) || plan["global_" + f] || "");
 
   const head = h("div", { class: "edhd" }, [
@@ -111,7 +119,7 @@ function editor(c, cur) {
       h("div", { style: "flex:1;min-width:200px" }, [
         h("textarea", { placeholder: "Prompt for this shot (empty = global prompt). Placeholders: {target} {details} {shot} {setting}",
           value: cur.prompt, onChange: e => c.setMeta(i, "prompt", e.target.value) }),
-        !cur.prompt && plan.global_prompt ? hint(`↳ uses the global prompt: ${plan.global_prompt.slice(0, 120)}${plan.global_prompt.length > 120 ? "…" : ""}`) : null,
+        !cur.prompt && plan.global_prompt ? rawH("span", { class: "hint" }, `↳ uses the global prompt: ${plan.global_prompt.slice(0, 120)}${plan.global_prompt.length > 120 ? "…" : ""}`) : null,
       ]),
     ]),
     usedRefs.value.length ? h("div", { class: "recent" }, [hint("recent (click = ref, shift+click = ref 2):"),
@@ -164,6 +172,69 @@ function editor(c, cur) {
       ["crop", "✂ Crop", "A box around the mask is regenerated (more pixels for a small subject); BFS Shot Join pastes it back."],
       ["cropmask", "✂🎭 Crop + mask", "Inside the crop, only the mask is regenerated: the most detail with the background kept."],
     ].map(([k, t, d]) => mode(c.modeOf(cur) === k, t, d, () => c.setMode(i, k)))),
+    h("div", { class: "row", style: "margin-top:8px;align-items:center;gap:8px" }, [
+      check(!!cur.color_guide, v => c.setMeta(i, "color_guide", v), "🎨 Color Guide",
+        "Tint the selected person in the source guide. This is a translucent visual cue; it does not enable H3 mask-only inpainting."),
+      cur.color_guide ? h("label", { class: "row", style: "gap:6px;align-items:center" }, [
+        h("span", { class: "hint" }, "Ref 1 color"),
+        h("select", { value: cur.color_guide_color ||
+          (cur.color_guide_person != null ? (c.castOf(cur.color_guide_person).guide_color || plan.global_color_guide_ref1 || "#00ff00")
+            : (plan.global_color_guide_ref1 || "#00ff00")),
+          onChange: e => c.setMeta(i, "color_guide_color", e.target.value) },
+          GUIDE_COLORS.map(([v, label]) => h("option", { value: v }, label))),
+      ]) : null,
+    ]),
+    cur.color_guide ? h("details", { class: "note", style: "margin:4px 0;padding:6px 8px", open: !!cur.color_guide_text2 }, [
+      h("summary", { style: "cursor:pointer" }, cur.color_guide_text2 ? "Second person · Ref 2" : "+ Add a second person (optional)"),
+      h("div", { class: "row", style: "margin-top:8px;align-items:center;gap:8px" }, [
+        h("span", { class: "hint", style: "white-space:nowrap" }, "Ref 2"),
+        h("input", { type: "text", value: cur.color_guide_text2 || "", style: "flex:1;min-width:160px",
+          placeholder: "Describe the second person for SAM 3",
+          onChange: e => c.setMeta(i, "color_guide_text2", e.target.value) }),
+        h("button", { disabled: !!busy.value || !cur.color_guide_text2,
+          onClick: () => c.previewMask(i, { text: cur.color_guide_text2, max_objects: 1 }) }, "👁 Preview"),
+        h("select", { value: cur.color_guide_color2 || (cur.color_guide_person2 != null
+          ? (c.castOf(cur.color_guide_person2).guide_color || plan.global_color_guide_ref2 || "#9b30ff")
+          : (plan.global_color_guide_ref2 || "#9b30ff")),
+          title: "Choose the marker color for the person matched to ref 2",
+          onChange: e => c.setMeta(i, "color_guide_color2", e.target.value) },
+          GUIDE_COLORS.map(([v, label]) => h("option", { value: v, disabled: v === guideColor1 }, label))),
+      ]),
+      h("details", { style: "margin-top:6px" }, [
+        h("summary", { class: "hint", style: "cursor:pointer" }, "Keep ref 2 color consistent across shots (optional)"),
+        h("div", { class: "row", style: "margin-top:6px;gap:8px" }, [
+          h("span", { class: "hint" }, "Ref 2 identity"),
+          h("select", { value: cur.color_guide_person2 == null ? "" : String(cur.color_guide_person2),
+            onChange: e => { c.setMeta(i, "color_guide_person2", e.target.value === "" ? null : Number(e.target.value)); c.setMeta(i, "color_guide_color2", ""); } },
+            [h("option", { value: "" }, "Choose manually"), ...c.people.value.map(p => h("option", { value: String(p.id) }, `Person ${p.id}`))]),
+        ]),
+      ]),
+      h("details", { style: "margin-top:6px" }, [
+        h("summary", { class: "hint", style: "cursor:pointer" }, `Advanced · opacity ${Number(cur.color_guide_opacity ?? 0.35).toFixed(2)}`),
+        h("div", { class: "row", style: "margin-top:6px;align-items:center" }, [
+          h("span", { class: "hint" }, "Opacity"),
+          h("input", { type: "range", min: 0.05, max: 0.8, step: 0.01, value: cur.color_guide_opacity ?? 0.35,
+            style: "flex:1;max-width:320px", onInput: e => { c.meta(i).color_guide_opacity = parseFloat(e.target.value); }, onChange: c.save }),
+          hint("The default keeps movement and expression visible."),
+        ]),
+      ]),
+    ]) : null,
+    cur.color_guide ? h("details", { style: "margin:4px 0" }, [
+      h("summary", { class: "hint", style: "cursor:pointer" }, `More options · opacity ${Number(cur.color_guide_opacity ?? 0.35).toFixed(2)}`),
+      h("div", { class: "row", style: "margin-top:6px;gap:8px;align-items:center" }, [
+        h("span", { class: "hint" }, "Ref 1 identity"),
+        h("select", { value: cur.color_guide_person == null ? "" : String(cur.color_guide_person),
+          onChange: e => { c.setMeta(i, "color_guide_person", e.target.value === "" ? null : Number(e.target.value)); c.setMeta(i, "color_guide_color", ""); } },
+          [h("option", { value: "" }, "Choose manually"), ...c.people.value.map(p => h("option", { value: String(p.id) }, `Person ${p.id}`))]),
+        cur.color_guide_person != null ? h("button", { class: "ghost", title: "Use the cast member's assigned color",
+          onClick: () => c.setMeta(i, "color_guide_color", "") }, "↩ cast color") : null,
+        h("span", { class: "hint" }, "Opacity"),
+        h("input", { type: "range", min: 0.05, max: 0.8, step: 0.01, value: cur.color_guide_opacity ?? 0.35,
+          style: "flex:1;max-width:240px", onInput: e => { c.meta(i).color_guide_opacity = parseFloat(e.target.value); }, onChange: c.save }),
+      ]),
+    ]) : null,
+    cur.color_guide && !hasMask(cur) ? h("div", { class: "err" }, "Color Guide needs this shot's person selection: add mask text, points or a mask video, then preview it.") : null,
+    cur.color_guide && cur.crop && cur.color_guide_text2 ? h("div", { class: "err" }, "The second Color Guide selection uses the full frame; choose Full frame, Frame + paste or Mask only for this shot.") : null,
     (cur.crop || cur.inpaint || cur.paste) && !hasMask(cur) ? h("div", { class: "err" }, `${c.modeName(cur)} needs a mask on this shot: a mask text, points or a mask video (or the planner's mask input).`) : null,
     cur.inpaint ? h("div", { class: "row", style: "margin-bottom:6px;align-items:center",
       title: "Opacity of the generation mask: the value of the white inside the mask (1 = fully white, the default). H3 reads a grey mask value as 'regenerate this much': at 0.85 the masked area starts at 85% of the noise and keeps ~15% of the original there. 0.8-0.9 keeps pose, outline and lighting while still swapping; too low copies the original person." }, [

web/js/shotloop/view_timeline.js

@@ -1,6 +1,5 @@
 // Timeline: thumbnails, cut marks, cut score, shot bars (click = select, drag the white handles, double-click = split).
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { hue, fmtT, pill } from "./common.js";
+import { h, hue, fmtT, pill } from "./common.js";
 
 export function timelineCard(c) {
   const { plan, an, segs, sel, n, pxPerFrame, tlWidth, maxLen, cuts, hover, tlEl, zoom, play, vid, active } = c;

web/js/shotloop/view_video.js

@@ -1,6 +1,5 @@
 // 🎞 Video tab: the source video, how it is split into shots, and the generation size.
-import { h } from "../vendor/vue.esm-browser.prod.mjs";
-import { GRIDS, fld, select, section, pill, hint, fmtT } from "./common.js";
+import { h, GRIDS, fld, select, section, pill, hint, fmtT } from "./common.js";
 
 export function videoTab(c) {
   const { plan, an, files, size, busy, detectorUsed, maxLen } = c;