character-consistency

character-consistency

Lock a character's visual identity into agents/reference/ai-video/<project>/characters/<id>.json so every scene reuses the exact same tokens verbatim. Downstream skills (video-director, pixar-storyteller, motion-choreographer) read this file and never paraphrase. Verified by visual regression (pixel similarity ≥ 95%, Phase 6 Step 3).

When to use

• A multi-scene run names the same character on screen more than once — Character Lock is mandatory before the second scene drafts.
• A character drift bug landed (face / outfit / prop changed between scenes) — re-lock and rerun the affected scenes.
• A series, episode, or recurring ad uses the same on-screen identity.

Do NOT use when:

• One-shot scene with no recurring character — overhead is wasted.
• The "character" is an environment or set (a place, not an entity) — use a style.json lock pattern in the project's notes instead. Recurring creatures, vehicles, and hero objects DO get a real lock — pick the matching subject_class below.

Procedure

Step 0: Inspect

1. Check agents/reference/ai-video/<project>/characters/ — if a lock already exists for this id, read it, do not redraft. Edits require an explicit revision note (Phase 6 visual regression must rerun).
2. Confirm the character will appear in ≥ 2 scenes; one-shot → skip.

Step 1: Draft identity tokens

Emit a JSON file at agents/reference/ai-video/<project>/characters/<character-id>.json with the following fields. Every field is mandatory; missing field → fail the lock.

{
  "id": "kebab-case-id",
  "name": "Display Name",
  "subject_class": "humanoid | creature | vehicle | abstract | object",
  "silhouette": "one-line read of the body shape from 30m",
  "palette": ["#hex1", "#hex2", "#hex3"],
  "wardrobe": "garment list, materials, era",
  "signature_prop": "the one object that travels with them",
  "posture_default": "how they stand when not acting",
  "eye_behavior": "blink rhythm, glance habit",
  "face": "age band, skin tone, hair (length / color / texture), distinguishing marks",
  "voice_note": "timbre + cadence for native-audio adapters; null if N/A",
  "reference_frame": "scenes/<id>/frames/<n>.png or null",
  "version": 1
}

Subject-class token matrix

Field NAMES are fixed (downstream consumers extract them verbatim); their SEMANTICS shift per subject_class. Missing subject_class → humanoid (back-compat with existing locks). The blueprint layer stays subject-agnostic on purpose — it only consumes the rendered SUBJECT string; class semantics live here, in the one file the drafting agent reads.

Universal slots (id, name, palette, reference_frame, version) keep one meaning across all classes.

Worked example — creature:

{
  "id": "moor-wyrm",
  "name": "Moor Wyrm",
  "subject_class": "creature",
  "silhouette": "low six-limbed serpentine bulk, head held below shoulder line",
  "palette": ["#2e4a3f", "#c9b458", "#1a1a1a"],
  "wardrobe": "moss-green plated scales, gold-flecked underbelly, mud-matted ridge fur",
  "signature_prop": "broken left tusk capped with a brass ring",
  "posture_default": "coiled low, weight on forelimbs, tail tip always moving",
  "eye_behavior": "slow horizontal nictitating blink; ears flatten before lunges",
  "face": "blunt muzzle, four-nostril ridge, amber eyes with horizontal pupils",
  "voice_note": "sub-bass rumble with clicking overtones; null if scenes are scored only",
  "reference_frame": null,
  "version": 1
}

Step 2: Reference frame

1. After the first scene renders, copy the highest-quality frame showing the character full-face and full-body to agents/reference/ai-video/<project>/characters/<id>.ref.png.
2. Update reference_frame in the JSON to point at it.
3. Phase 6 visual regression compares every subsequent scene's character frame against this reference (ImageMagick compare ≥ 95% similarity).

Step 3: Validate

1. JSON parses (jq . characters/<id>.json exits 0).
2. All mandatory fields present and non-empty.
3. subject_class (when present) is one of humanoid | creature | vehicle | abstract | object; each field reads per the matrix row for that class — a creature lock with a garment list in wardrobe is a drafting error, not a style choice.
4. Palette has ≥ 2 and ≤ 5 hex values.
5. Downstream skills cite this file by path, never paraphrase its contents.

Output format

1. agents/reference/ai-video/<project>/characters/<id>.json — locked identity tokens, schema above.
2. agents/reference/ai-video/<project>/characters/<id>.ref.png — reference frame (added after first render).
3. agents/reference/ai-video/<project>/characters/CHANGELOG.md — one line per revision: v<n> · YYYY-MM-DD · reason · scenes-to-rerun.

Gotcha

• A non-humanoid lock without subject_class reads as humanoid downstream — the lock is structurally weaker and nobody can tell. Always set the class for non-humanoid subjects.
• The model wants to "improve" identity tokens on each scene — this is the silent drift failure. Tokens are immutable until a revision note bumps version.
• Palette without a count fails downstream — adapters need a small closed set (2–5 hex).
• voice_note: null is explicit; missing the key entirely breaks the schema validator.
• Reference frame is captured after the first successful render, not before — bootstrap scenes have no reference and only the JSON locks them.
• A revision (version bumped) requires Phase 6 visual regression to rerun against every prior scene that used the old version.

Do NOT

• Do NOT paraphrase identity tokens when drafting scene prompts — copy verbatim or break the lock.
• Do NOT edit a locked JSON in place without bumping version and adding a CHANGELOG line.
• Do NOT skip the reference frame after the first render — visual regression has nothing to compare against.
• Do NOT lock a character that appears in only one scene.

Policies

When a character lock would identify or render a real person, consult before emitting the JSON:

• agents/settings/policies/media/likeness.md — real-person identity tokens require a cited likeness release.
• agents/settings/policies/media/public-figures.md — recognised public figures carry the harder gate (publicity rights + transformative-intent).
• agents/settings/policies/media/voice-cloning.md — when voice_note references a real person's voice.
• agents/settings/policies/media/disclosure.md — outputs carrying a real-person lock require the non-removable AI-generation disclosure downstream.

Refuse-and-surface the file path; do not silently sanitise the prompt.