[albertleal]

Change / 改动

I like the character library in the latest versions. Until now, though, I still had to write into every prompt what each reference picture shows (a tattoo on the back, a scar, a detail of the outfit…), because a card only carried its description plus a sheet and a face. This is a small enhancement for that need. Merge it if it fits, or take it as inspiration and build it your own way. I know CONTRIBUTING asks for an issue first. I'm happy to open one, or you can close this and keep it as a feature request.

Character cards

• A caption for each picture (optional, one line, up to 200 characters). It goes into the prompt next to its picture tag:
  subject_definitions: <Subject 1> is Pepa: a young courier. <Picture 1> to <Picture 4> show its appearance; <Picture 3> shows the rabbit tattoo on her neck.
  The wording is the same in drama.subject_definitions (Agent) and subjectDefinitions (web/cast_mention.js, Studio @-mentions). If the prompt is over the limit, captions are shortened along with descriptions (with_cast).
• Up to 24 pictures per card (was 6). The limits are MAX_CAST_IMAGES and MAX_CAST_CAPTION in agent/schema.py, mirrored in web/cast_library.js. The sheet still uses at most 6 views, and candidates stay at 6.
• API: images[].caption on create/update and in the card view. "" removes a caption; leaving the field out keeps it. The agent can't change a caption the user set (same changed_by_user rule as for pictures). The agent guide and schema descriptions are updated.

Character dialog

• A Description box for the card description, which prompts already use. "Generate with AI" fills it with the description it generated from, unless the user typed something else.
• A caption field under each picture. Tiles grow as pictures are added (several files at once, by file picker or drag and drop). Removing a picture moves the next ones up.

What a shot carries

• A fresh shot now carries every picture of each person instead of the sheet + face. Pictures keep the card order, with the stand-in (face, else front, else three-quarter) last. When the 32 references run out, a person keeps their first pictures and the stand-in. Continuing shots are unchanged. The same rule applies to the Agent (person_pictures, cast_references) and to Studio mentions (cardPictures).
• Mentioned characters follow their card. Mention rows carry the card revision. After a card is edited, that character's rows in the media list are rebuilt in place (pictures, captions, description). The @ handle stays the same and switched-off pictures stay off (staleCast, withCurrentCard).

Studio

• A Full prompt button next to @ shows the exact text sent to H3, with its length and a Copy button. The text comes from the node's own serializer, so it includes the subject definitions, captions and the Replace person prefix.

Open points

• Sending every picture changes a policy that drama.py says was chosen after your reference tests, and it adds reference tokens to each shot. I have no before/after speed or VRAM measurements.
• Studio "Continue from video" with one character: continuation.pick_pictures keeps the first 3 rows, so a card with more than 3 pictures loses its stand-in, which is now last. Keeping the first two plus the last would fix this.
• tests/fixtures/subject_definitions.json isn't in the public repo and needs a case with captions.
• Not updated: the tutorial step that says "up to 5 images from other angles" (web/tutorial_book_content.js) and its screenshot, the version and the release notes.

中文简述：角色卡的每张图片可加一句说明（如“背上的龙纹身”），生成时以 <Picture N> shows … 写进提示词；每个角色最多 24 张图片；角色窗口可编辑描述；新镜头带上角色的全部图片（代表图放最后；超出 32 个参考时保留前几张和代表图），接续镜头不变；已 @ 的角色在角色卡修改后自动更新；创作面板新增“完整提示词”查看。

Validation / 验证

• Ran the PR checks locally: node --check on every web/*.js, node scripts/test_freevideo_entry.mjs and node scripts/test_prompt_guide.mjs.
• New case in scripts/test_freevideo_entry.mjs: after its card is edited, a mentioned character gets every picture with its caption and the new description. A switched-off picture stays off, and an unchanged card rewrites nothing.
• Manual checks in ComfyUI ([OS, GPU]):
  • Created and edited a character with more than 6 pictures, captions and a description; after reopening it, everything was kept.
  • @-mentioned it in the Studio and checked in Full prompt that each <Picture N> shows … matches its row in the media list.
  • Edited the card while it was mentioned; the media rows updated to match.
  • Generated with a captioned character: [result].
• Not measured: speed and VRAM with many reference pictures.

AI disclosure: written with help from GitHub Copilot. I reviewed and ran every change.