tts-voice-creator-clone-and-design-2/architecture/character-visual-identity.md

SOP — Character visual identity and appearance forms

Status: implemented. Covers how a character's avatar and concept (reference) sheet stay the same person, and how one character holds several appearances ("forms") without splitting into several characters or voices.

Single source of truth

• Appearance facts come from the sheet's physical, clothing, age_estimate, race_species, gender, title, profession, archetype (and the user overrides visual_appearance, visual_species, visual_costume). Both prompts are built by _character_visual_facts in routes/conversation.py; the active form is overlaid first (_character_form_sheet, which never lets a form change its own id/name).
• image_prompt (portrait) and concept_art_prompt (reference sheet) are deterministic — built server-side from those facts with fixed camera/lighting/period text. Sheet extraction no longer asks the LLM to write image_prompt (it drifted from the concept sheet); the prompt is generated right after extraction by csAutoGenerateExternalPrompts, and again before any avatar-only or per-form generation. A hand-edited prompt (*_user_edited) is never overwritten.
• Only the two prompts describe an appearance. voice_design_prompt and the SillyTavern prompt belong to the character as a whole, so they always live on the base sheet.

Stale detection

_character_identity_fingerprint (server) and _libIdentityFingerprint (browser) hash the same field list; a test runs the browser code in Node and compares, including list values and non-BMP characters. The three visual_* overrides are appended only when set, so pairs made before they existed keep a valid fingerprint. A pair needs review when its prompt version is not current, its fingerprint is missing or differs, or identity_consistent is false. Regenerating only the avatar or only the reference image sets identity_consistent = false on an existing pair, because a lone regeneration produces a new face.

Where the data lives

	base appearance	a form
profile image	record image	form.image
reference image, version, fingerprint, digests, identity_consistent	sheet.*	form.*
Physical / Clothing text	sheet.physical/clothing	form.physical/clothing

All visual results are written through one function (_libSaveCharacterVisual), which re-reads the stored record, writes to the active form or the base, and saves. (It used to write the base reference image to the record root, and the consistent-pair generator kept it in memory only, so a base pair lost its reference image and metadata on reload.)

GET /api/characters/visual-pair-review checks the base pair and every form that has images, each against its own metadata and its own fingerprint, and reports form pairs under the form name.

Forms (max 8 per character, enforced in core/validation.py)

Add (starts as a copy of the base Physical/Clothing; only non-empty keys are stored because an empty key would blank the base value when overlaid), rename (unique, ≤160 chars), delete (confirm; the character, its voice and the base look stay), show, and generate matched images for one form or for all forms. Generation rebuilds that form's prompts first (unless hand-edited), saves the pair on that form, then restores whichever appearance was active. Editing Physical/Clothing while a form is active changes only that form.

Image prompt hygiene and the turnaround (1.34.x)

• Setting. Prompts describe the books as The Dark Eye high-fantasy medieval dress (about 900-1300 AD: wool and linen tunics, belted robes, leather, mail where the sheet names it). The earlier "early Renaissance 1420-1500" wording pulled uniforms, coats, hats and boots that read as musketeer/cowboy/wartime.
• Wording. Extracted costume text is rewritten at prompt time (_period_wording: Uniform, Weste, Hut, Sporen, Jacke, Schal … become surcoat, jerkin, hood, boots, tunic …). Stored sheets are not changed.
• Injuries and dirt. _strip_injury_clauses removes clauses about blood, wounds, bandages, burns, limping, torn clothes, soot and dirt from appearance, costume and the story moment; the rest of the sentence stays. The portrait baseline asks for clean skin and garments.
• Variety. Characters with armour or weapons get an individual garment cut and colour scheme (_character_design_variation, stable per name; colours the sheet names win) instead of one shared list.
• Same person in portrait and sheet. The profile picture is a crop of the full-body identity image. The front, side and rear views are drawn one by one with the edit model using that identity image as the only reference (no pose guides), then stitched into the three-panel image the compositor already crops. The old text-only triptych produced a different face.
• Props get an object-only period sentence, so a tile no longer turns into a portrait of the character.
• Older saved prompts are cleaned the same way at render time. Existing image pairs are unchanged until regenerated.