From e64ad0fae499031c46e7ad85aa443cd8586bc32e Mon Sep 17 00:00:00 2001 From: Chris Dumas Date: Fri, 28 Aug 2026 12:48:33 +0000 Subject: [PATCH] Expand H3 reference-node documentation --- H3_LONG_VIDEOS_GUIDE.md | 161 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) diff --git a/H3_LONG_VIDEOS_GUIDE.md b/H3_LONG_VIDEOS_GUIDE.md index b923c21..e2847b0 100644 --- a/H3_LONG_VIDEOS_GUIDE.md +++ b/H3_LONG_VIDEOS_GUIDE.md @@ -891,6 +891,77 @@ The node uses reference data in two different ways: Character refs can now contribute actual image identity when the beat names the character, not just when you explicitly tag the picture slot. +### Character Reference Node: what the fields actually do + +`Dumas Character Reference` packages one image plus metadata into one `REFERENCE` socket. + +What the long-videos code actually uses: + +- `image`: the real reference image H3 sees when that slot is selected for a shot +- `name`, `character_id`, `alias`: used for character-name matching in beat text +- `description`: injected as persistent appearance text when that character ref is matched +- `wardrobe`: injected as persistent wardrobe text when matched, and also used to seed `character_memory` if the long-videos node field is blank +- `general`: injected as extra character notes when matched +- `gender`, `age`, `nationality`, `occupation`, `height`, `accent`: turned into one "Character facts" sentence when matched + +What this means in practice: + +- the image and the text metadata are separate channels +- a character image can still condition a shot even if its metadata was not injected into the beat text +- wardrobe from character refs is only promoted into live tracked wardrobe state when `character_memory` is empty + +### When character data gets used + +There are three different moments: + +1. Shot ref routing chooses whether the character image is attached to that beat at all. +2. Text matching decides whether the character metadata is injected into that beat text. +3. Chain-state seeding decides whether the character ref wardrobe becomes the starting `character_memory`. + +The important detail is that these do not always happen together. + +Character image conditioning: + +- happens according to `ref_mode` +- can be forced with `` +- can also be pulled in by naming the character in the beat + +Character text metadata injection: + +- happens only when the beat explicitly tags the slot with `` +- or when the beat mentions the character by `name`, `id`, or `alias` + +Character wardrobe seeding: + +- happens once at chain setup +- only if the long-videos `character_memory` field is blank +- only for character refs that actually contain wardrobe text + +### Location Reference Node: what the fields actually do + +`Dumas Location Reference` is simpler. It packages one environment image plus environment metadata into one `REFERENCE` socket. + +What the long-videos code actually uses: + +- `image`: the real location reference image H3 sees when that slot is selected for a shot +- `description`: injected as location context when that slot is explicitly tagged +- `general`: injected as location notes when that slot is explicitly tagged +- `name`, `location_id`, `alias`: used mainly as labels in summaries and injected sentences, not for automatic prose matching + +Important difference from character refs: + +- location refs are **not** auto-matched from location names in beat prose +- if you write `in the cafe` and do not tag ``, the location image may still be in the shot because of `ref_mode`, but the location text metadata is not auto-injected just from that name + +### When location data gets used + +Location node data has two separate paths: + +1. The location image can be attached to shots through normal ref routing. +2. The location text metadata is only injected when you explicitly tag that slot with ``. + +So location references are more tag-driven than character references. + Simple usage patterns: - one character, no special routing: use `auto ref2v` @@ -904,6 +975,96 @@ What to remember: - location refs are often tagged because they are about where the shot happens - character refs are often named because they are about who is in the shot +### Scenarios + +### Scenario: one hero character, no location ref + +Setup: + +- `ref_1` = Maya character reference +- beat text says `Maya crosses the road and looks back` +- `ref_mode = auto ref2v` + +What happens: + +- Maya's image is attached to the shot +- Maya's character metadata is injected because the beat names `Maya` +- if `character_memory` is blank, Maya's `wardrobe` field also seeds the live wardrobe tracker at chain start + +### Scenario: two characters plus one tagged location + +Setup: + +- `ref_1` = Maya character reference +- `ref_2` = Jon character reference +- `ref_3` = warehouse location reference +- beat says `Maya argues with Jon near the loading bay ` + +What happens: + +- Maya and Jon can be matched by name, so their character metadata can be injected +- the warehouse location metadata is injected because `` tags it +- the image refs used on the shot still depend on `ref_mode` + +Why this pattern works well: + +- character refs can be driven by names +- location refs usually need explicit tags when you want the environment text to be stated clearly + +### Scenario: location image works, but location notes do not seem to + +Setup: + +- `ref_3` = cafe location reference +- beat says `They sit in the cafe window booth` +- no `` tag + +What happens: + +- with `auto ref2v` or `every shot`, the cafe image may still be conditioning the shot +- but the location `description` and `general` fields are not auto-injected from the word `cafe` + +What to do: + +- add `` on the beat where the location wording matters + +### Scenario: character face is partly right, but identity is weak + +Setup: + +- character refs are connected +- beat prose uses `she` and `he`, but never names the characters +- `character_memory` contains clothing and height-like facts + +What happens: + +- the beat can still pick up some tracked wardrobe/state language +- but the strongest character-ref match path is weaker because the beat is not naming the people +- that can produce "same role, wrong face" results + +What to do: + +- name the characters in the beat, or tag their slots explicitly +- keep `ref_noise_aug` high +- use `every shot` when identity matters more than soft continuity + +### Scenario: character wardrobe from the ref node does not update later + +Setup: + +- character ref has wardrobe filled in +- long-videos `character_memory` is also filled in with different clothing + +What happens: + +- the long-videos `character_memory` wins as the live starting wardrobe state +- the wardrobe field inside the character ref is still usable as injected descriptive text when matched, but it does not replace the explicit `character_memory` sheet + +What to do: + +- put the canonical changing outfit in `character_memory` +- treat character-ref wardrobe as a fallback/default seed, not the main changing state source + ### If faces drift or people turn into random lookalikes Check these in this order: