"""The instruction board that ships on the Starter workflow's canvas. One source for six `MarkdownNote` cards laid out to the left of the loaders. `build_notes.py` writes them into `workflows/HandTieClips_Starter.json`. Why on the canvas at all: the craft lives in `PROMPTING.md`, `prompt_pack/` and the editor's Templates panel, and all three require leaving the graph. The rules that decide whether a first render works are needed at the moment beats are being written, which is on the canvas. This is a condensation, not a copy. `PROMPTING.md` stays the long-form authority and every card says so; what is here is the part needed to get a first render right. Keep the cards short enough to read at a glance -- a wall of text on the canvas is the same as no text on the canvas. Layout: two columns of three at x=-960 and x=-480, 440 wide, so the board ends at x=-40 and the loaders (which start at x=0) are untouched. Reading order is down column A, then down column B. """ YELLOW = ("#432", "#653") # what the existing Note uses GREEN = ("#232", "#353") # ComfyUI's green -- card 1 only, so the entry # point is unmistakable in a wall of yellow GROUP = { "id": 1, "title": "READ ME -- writing for this node", "bounding": [-990, -465, 980, 3200], "color": "#3f789e", "font_size": 24, } # `extra.ds` is restored on load rather than fitted, so without this the board # sits off-screen to the left and is never found. Screen = (world + offset) * # scale, so an offset of 500 puts world x=-500 at the left edge: column B, the # loaders and the left of the chain node all in view at once. DS = {"scale": 0.8264462809917354, "offset": [500, -281.1386834420914]} START_HERE = """\ ## Start here Two hops of 5 s, joined into one 10 s clip. ### Requires The MODEL wire is a turbo stack, not a bare loader: ``` UNETLoader -> LoRA Loader Stack (turbo LoRA) -> H3 AdaLN LoRA Fix -> MiniMax H3 Low VRAM Attention -> H3 SLA Attention -> Model Preview Override -> this node ``` | pack | nodes | |---|---| | **ComfyUI-PlagueKind-Nodes** | LoRA Loader Stack, AdaLN Fix, SLA Attention | | **ComfyUI-KJNodes** | Low VRAM Attention (experimental), Model Preview Override | Also on disk: the **turbo LoRA** named in the loader, and `taeh3.safetensors` for the live preview (or set `tiny_vae` to `none`). **CLIP goes to this node from the LoRA loader, not from the encoder.** That is what makes the text half of every LoRA land. Do not rewire it back. `steps` is **7**, which only works with the turbo LoRA. Missing a pack? Its nodes load as red boxes -- delete them, wire the loader straight into `model` and the encoder into `clip`, and raise `steps` to 20 or so. 1. Point the four **loaders** at your H3 files. 2. Queue. 3. Read the **SHOTS** cards on the node. **Shot 1 is the whole opening. Every later shot is only the new beat.** The node writes the identity lock, the live-frame citation and the join itself -- so re-describing the face, the clothes or the room after shot 1 competes with the frame pin instead of reinforcing it. This plan ships with **no references on purpose**, so it runs before you have supplied any pictures. ### Adding pictures - Open **REFERENCES**, add a row, drop a photo on its thumbnail. Files land in `ComfyUI/input/h3_refs`. There is no Load Image node to wire. - Give the row a `@tag`, and group photos of the same person under one subject. - Write the tag into the beat: `@hero_face stands at the counter in @kitchen`. The long-form guide is `PROMPTING.md` in the pack folder.\ """ RULES = """\ ## The rules that decide whether it works Not style preferences. This is how this model fails. ### 1. The prompt is additive Sampling runs at **cfg 1.0 with no negative branch**. Every concept you name is added, and nothing can be removed by mentioning it -- `no cut` puts the word *cut* in front of the encoder. **Never write a negation.** ### 2. Never name the thing you want to end "The cook stops talking" keeps her talking. Write the state you want as **a pose plus a sound**: > leans back against the counter with her lips closed, and lets her eyes move > slowly across the room. The kitchen is quiet apart from the low hum of the > refrigerator. Audio is always generated. Silence written as an absence comes back as speech, so **silence has to be written as a sound** -- room tone, a fridge, a single click. Keep it narrowband: "faint street noise" renders as a five-second hiss. **The ban is on the idea, not on a word list.** *Fades, passes, wanes, subsides, dies down, eases off* all name an ending as surely as *stops* does, and all of them add the thing they describe. Ask of each sentence: is this happening, or has it finished happening? ### 3. A state change belongs at the END of the previous shot Every hop opens holding the frames it was handed, and the audio pin carries the previous hop's tail across the join. Nothing you write in shot 3 can make shot 3 start quiet. **Arrive there before the previous shot ends.** ### 4. A hop that ends on dialogue keeps talking Speech at the end of hop N opens hop N+1 and propagates down the whole chain. Land each line **mid-hop** and leave a non-verbal action running into the seam -- slicing, walking, a hand on a doorframe. Give every hop with no dialogue a sound bed of its own. ### 5. A walk between two rooms is `match_cut` `join: continuous` across a real location change makes the model morph one room into the other mid-movement. ### 6. Set `tail` on your last shot Left at `ongoing`, the model is told action is still underway at the final frame and will invent something to satisfy it. Use `settle` or `hold`.\ """ REFERENCES = """\ ## References and @tags A picture in the register does not make the model use it. **The beat is what drives the frame** -- write the tag into the action line. Phrase a place as a place that is *depicted*, not as a container to be placed inside: "at the counter in `@kitchen`", not "steps into `@kitchen`". ### Fields | field | what it does | |---|---| | `tag` | what you write in beats as `@tag` | | `file` | a bare filename in `input/h3_refs` | | `subject` | groups pictures **of the same person** | | `retention` | `fully_preserved` / `partially_copy` / `reference` | | `shots` | the 1-based hops this picture rides | **One subject number per person.** Two different people under one number makes the model render the average of their faces. ### `shots` is the part that decides continuity **A reference with no `shots` list rides hop 1 only.** Right for a **place** plate: a room still riding a hop set somewhere else beats the frame pin, and the model follows the still. **List every hop a picture belongs on.** **A face plate is the opposite — put it on every hop.** A hop scheduled with no face reference came back a different person, and no later hop recovered. Identity drift does not self-correct. - Every **face** ref gets every hop: `"shots": [1, 2, 3, 4, 5, 6]`. - Keep a **place** ref on the hops set in that place, and off the rest. ### `locked` and `context` Per-subject prose that rides **every hop**, with no picture citation, so it carries identity across a hop where the photograph is absent. Give every subject a `locked`, and a `name` -- from hop 2 on, `@tag` for a person resolves to that name. **Name a colour or it drifts.** A noun with no adjective is unanchored: each hop is an independent encode, so "the bowl" on hop 4 came back stainless steel. Put properties in `context` -- "the bowl is white porcelain" -- never locations, and repeat the adjective in every beat.\ """ DIRECTIVES = """\ ## Directives Five axes, all optional, set per shot. An unset axis emits nothing at all and costs no tokens. | axis | values | |---|---| | `join` | `continuous`, `match_cut`, `hard_cut` -- **omit on shot 1** | | `camera` | `hold`, `pan_follow`, `push_in`, `pull_back`, `orbit`, `handheld` | | `framing` | `keep`, `wide`, `medium`, `close` | | `pace` | `slow`, `steady`, `brisk` | | `tail` | `ongoing` (default), `settle`, `hold` | They compile in that order -- `join` first, because it describes how this hop meets the previous one. ### Two combinations the node warns about **`join: continuous` + a framing change + `camera: hold`.** A framing change asks the audience to be somewhere new; with the camera still, the only way there is a cut. Earn it on the move (`push_in`, `pull_back`, `pan_follow`) or use `framing: keep`. **`push_in` + `wide`, or `pull_back` + `close`.** The move points the opposite way from the destination. Both are warnings, not errors. They are legitimate things to want -- they just rarely read the way you meant. ### Duration Per-shot `duration` overrides the chain, using exactly these labels: `"5 s"`, `"7 s"`, `"8 s"`, `"10 s"`, `"15 s"`.\ """ CHECK = """## Check before you render A chain is minutes to hours. These three dials cost seconds and catch almost everything. ### `dry_run = on` Compiles every hop's prompt and stops. No model, no sampler. Read the result on **`info`**, or as a page on **`contact_sheet`**. What you wrote is not what the encoder gets -- directives, continuation scaffolding, the identity lock and the `` citations are all assembled at render time. This is the only way to see the real thing first. Every plan warning prints on the way through, too. ### `render_through = N` Stop after N hops. With `cache_hops=on`, 3 then 5 then 8 builds the chain up and only ever renders the new hops. The plan is **not** truncated -- shot 4 still keys exactly as it will in the full run. ### `quality = draft` 0.3 MP, 6 steps. Enough to read blocking, camera and whether a join lands. Both values are in the cache key, so a draft never overwrites its final. It is a **fidelity** lever more than a speed one. Measured: ~42 s/hop against ~45 s/hop at 7 steps. If you already render at 0.3 MP and 6-8 steps it saves almost nothing -- `dry_run` is the fast button. Draft earns its place when your final is genuinely heavier, 1.0 MP at 14 steps. --- Afterwards: **`contact_sheet = on`** gives one row per hop -- first and last delivered frame, beat, directives, seed, cache hit, tone correction. Wire it to a Save Image. And **H3 Seam Report** -- already wired on this canvas -- takes the chain's `images` and measures every join: invisible / marginal / visible, plus the chain's cumulative drift. **Set `hops` to your shot count.** It derives hop length from frames, hops and overlap, so a wrong `hops` does not error -- it returns a plausible length and puts every seam at a frame where no join exists. A single reading includes whatever the scene did across the cut, so it is an upper bound. To isolate the seam, A/B two renders from the same seed and cache changing only `tone_compensate`; the hop store writes before tone is applied, so the second run re-grades from cache in seconds. """ TROUBLE = """\ ## When it goes wrong | symptom | cause | fix | |---|---|---| | The clip cuts to the reference photo in its last seconds | The beat finished before the frames did | Set `tail`, give the beat enough to do | | A stray gesture or line in the closing second | `tail: ongoing` on the final shot | `settle` or `hold` | | She keeps talking after you asked for quiet | You named the ending | Pose plus a sound | | Dialogue continues into hops that have none written | The hop before ended on speech | Land the line early; non-verbal action into the seam; a sound bed on every quiet hop | | A character walks between two rooms and one morphs into the other | `continuous` across a location change | `match_cut` | | Silence renders as speech | Silence written as an absence | Name room tone, a fridge, a distant car | | Ambience is a five-second hiss | Broadband wording | Narrowband, or one discrete event | | Two characters' faces merge | Both declared as the same `subject` | One subject number per person | | The face becomes a different person partway through | A hop scheduled with no face plate. `locked` holds a face that is still right; only a plate rebuilds one that is gone, and the drift never self-corrects | Put the face ref on **every** hop | | A stylised plan renders photoreal | The node's hop-1 establishing line asserts live action | Name the medium in shot 1's first sentence, or clear the `establish` widget | | The film gets darker every hop | Each hop dims across its own frames and hands the darker tail on. Seam correction cannot see it | `tone_compensate=anchor`. `tone_anchor=0.35` removed ~60% of measured drift; 0.6 removes ~78% and costs ~0.5/255 more seam step. Also restate the light as a positive property in every beat | | A location introduced mid-plan drifts | It has no place plate of its own | Plate it, on the hop it arrives and every hop after | | A prop or garment changes colour or material | Named with no adjective, so each hop's encode is free to invent one | Repeat the adjective in every beat, and state it as a property in `context` | | A hard cut ~1.5 s into a hop, mid-scene | The previous hop over-delivered, so this beat instructs what its own live frame already did | One movement per hop; write the next beat so it is true from either ending | | A continuous join reads as a cut | Framing change with `camera: hold` | Earn it on the move, or `framing: keep` | | The run stops, naming a reference | That row's picture is not in `h3_refs` | Drop the file on the row, or clear its picture to run without it | | A reference has no effect on some hop | Its `shots` list leaves that hop out | List every hop the picture should ride | | A deliberately dark scene keeps being brightened | `anchor` cannot tell intent from drift | `"tone": "rebase"` on that scene's first shot | | You cannot tell which hop broke | 114 s is a lot to scrub | `contact_sheet=on` -- one row per hop, first and last frame | | A pasted plan is rejected as invalid JSON | Escaped double quotes mangled in transit | Single quotes around dialogue | Every error message names the shot or the reference it came from. Nothing guesses.\ """ AUTHOR = """\ ## Let a model write your plan `prompt_pack/` in the pack folder turns any chat model into a plan writer. In LM Studio, or anything with a system-prompt box: 1. Load a model with **context 16384 or more**. The prompt is ~4,700 tokens and the reply another 1,000-2,000; a small window truncates the rules and you get invented directive names. 2. Paste **`prompt_pack/SYSTEM_PROMPT.md`** into the **System Prompt** box. Nothing else goes in that box. 3. **Temperature 0.3-0.5.** Higher and the JSON grows trailing commas and smart quotes. 4. Describe the scene, and say how many hops and what pictures you have: > Six hops. A cook in a kitchen; she says one line, walks out into a hallway, > waits by a window, then comes back. I have a face photo, a photo of her > apron, and a photo of the kitchen. 5. Each panel section has its own **JSON** disclosure at the bottom. The first ```json``` block goes in the one under **SCRIPT** (`shot_plan`), the second in the one under **REFERENCES** (`ref_plan`). Bad JSON keeps the last good version on screen and says so, rather than discarding your paste. 6. **If the node rejects it, paste the error straight back into the chat.** One round trip usually fixes it. Want it to match a shape? Paste `prompt_pack/EXAMPLE_6_HOP.md` first. Small models (7B-8B) hold the JSON schema but drift on the prose rules -- they write negations. Skim the beats before queueing. ## Fixing one hop without re-rendering the rest Set **`cache_hops` to `on` before your first run.** It is off by default, and a hop that was never cached cannot be reused. Nothing to install. The cache key **chains**, so editing shot 5 of 8 re-renders 5 to 8 and reuses 1 to 4 off disk. Hop 6 was rendered *from* hop 5, so it has to. **Edit the earliest hop you dislike and work forward** -- that way each hop is paid for once. Anything chain-wide re-renders everything: resolution, aspect, overlap, sampler, scheduler, either shift, `ref_image_size`, `pin_to_qwen`, the LoRA stack, or **any reference picture** (keyed on pixels, so a re-crop counts even under the same filename). That is the usual reason the cache looks broken. Loved a hop? Put `"locked": true` and a stable `"id"` on that shot and it keeps that exact take even when its inputs move. Unrelated to `subjects.N.locked`, which is identity text. Full detail in `PROMPTING.md`, under *Re-rolling one hop*.\ """ SHOWCASE_NOTE = """\ Hand Tie Clips -- SHOWCASE (6 hops x 7 s = 39.2 s) A continuity stress test, and the honest demonstration of what the reference register buys you. REQUIRES a turbo stack on the MODEL wire, which is how this node is actually run here: UNETLoader -> LoRA Loader Stack (turbo LoRA) -> H3 AdaLN LoRA Fix -> MiniMax H3 Low VRAM Attention -> H3 SLA Attention -> Model Preview Override -> this node ComfyUI-PlagueKind-Nodes -> LoRA Loader Stack, AdaLN Fix, SLA Attention ComfyUI-KJNodes -> Low VRAM Attention (experimental), Model Preview Override On disk as well: the turbo LoRA named in the loader, and taeh3.safetensors for the live preview (or set tiny_vae to none). CLIP reaches this node FROM THE LORA LOADER, not from the encoder. That is what makes the text half of every LoRA land. Do not rewire it back. `steps` is 7, which only works with the turbo LoRA. Missing a pack? Its nodes load as red boxes -- delete them, wire the loader straight into `model` and the encoder into `clip`, and raise `steps` to 20 or so. BEFORE YOU RUN IT, supply three pictures. Open REFERENCES on the node and drop your own onto each thumbnail, or put files in ComfyUI/input/h3_refs named: ref_face.jpg head-and-shoulders, even light -> @hero_face ref_outfit.jpg full length, same person -> @hero_outfit ref_room.jpg the room, wide -> @kitchen Without them the run stops and names the reference it could not find. Nothing guesses. What each hop is testing: 1 kitchen, dialogue all three references active 2 lateral move to the window kitchen only 3 exits through the doorway kitchen only 4 hallway - UNSEEN space face re-asserted; no room reference exists 5 dialogue, ZERO references identity, wardrobe and voice ride on the frame pin plus subjects.1.locked/context alone 6 returns to the kitchen on a MATCH CUT, not a continuous join -- one unbroken take across two rooms makes the model morph one into the other mid-movement Hop 5 is the point of the whole thing. If the cook is still the same person in the same apron with the same voice, with no picture in front of the encoder, the register is doing its job. `shots` on each reference is what schedules this. On a continuation chain, omitting `shots` means HOP 1 ONLY. Right for a place plate, wrong for a face: put every face reference on every hop, or the identity drifts and stays drifted. List every hop a still should appear on. Settings that are deliberate, not defaults: control_after_generate = fixed or no two runs are comparable tone_compensate = frame_shift counters the drift that accumulates over six hops. Set it to `off` and re-queue for a same-seed A/B: tone mode is not in the hop key, so every hop replays from cache in seconds instead of re-rendering. cache_hops = on edit shot 4 and only shots 4-6 re-render """ CARDS = [ # key, title, pos, size, colour ("start", "START HERE", [-960, -400], [440, 940], GREEN, START_HERE), ("rules", "The rules", [-960, 600], [440, 760], YELLOW, RULES), ("refs", "References and @tags", [-960, 1420], [440, 640], YELLOW, REFERENCES), ("directives", "Directives", [-480, -400], [440, 640], YELLOW, DIRECTIVES), ("trouble", "When it goes wrong", [-480, 280], [440, 900], YELLOW, TROUBLE), ("check", "Check before you render", [-480, 1220], [440, 800], GREEN, CHECK), ("author", "Let a model write it", [-480, 2060], [440, 620], YELLOW, AUTHOR), ]