Add mm-prompter skill: SKILL.md, format references, worked example, validator
This commit is contained in:
parent
cc8431ad52
commit
8759ead141
33
README.md
33
README.md
@ -1,3 +1,34 @@
|
||||
# Moxie Multimedia Prompt Creator
|
||||
|
||||
the how to use will be filled in here
|
||||
An agent skill that turns a vague prompt plus a total video length (seconds) into a
|
||||
ready-to-run generation package:
|
||||
|
||||
- `segments.txt` — N segment prompts in full-reference (ref2va) format, joined by `|`.
|
||||
The video creator node splits the total length evenly across segments
|
||||
(`N = max(1, round(total_seconds / 10))`) and generates them one by one.
|
||||
- `Image-N.json` — one 16:9 character-sheet text-to-image prompt per character that
|
||||
has no user-provided image reference, consumed one at a time by a ComfyUI workflow.
|
||||
- `image-map.txt` — manifest mapping each `<Subject N>` to its image file
|
||||
(user-provided filename or generated `Image-N.json`).
|
||||
|
||||
## Layout
|
||||
|
||||
| Path | Purpose |
|
||||
| --- | --- |
|
||||
| `SKILL.md` | Skill entry point: triggers, pipeline, output contract, validation checklist |
|
||||
| `references/ref2va-segment-format.md` | Authoritative per-segment format (sections, labels, shots, audio template) |
|
||||
| `references/t2i-character-sheet.md` | Character-sheet caption rules and the two-key JSON contract |
|
||||
| `references/worked-example.md` | Complete end-to-end example, including the audio (singing) variant |
|
||||
| `scripts/validate_outputs.py` | Optional validator the agent can run on its outputs |
|
||||
| `segment-guide.md`, `t2i-prompt-rules/` | Source rule documents the skill was adapted from |
|
||||
|
||||
## Usage
|
||||
|
||||
1. Pull this repo into your agent's skills folder so that `SKILL.md` is discoverable.
|
||||
2. Give the agent a vague scene prompt and the total video length in seconds, plus
|
||||
optionally: song lyrics, an audio file mention (e.g. "use midnight.mp3"),
|
||||
per-character image references, and style hints.
|
||||
3. The agent writes `segments.txt`, `Image-N.json` for characters lacking references,
|
||||
and `image-map.txt` into the project folder.
|
||||
4. Verify before use: `python3 scripts/validate_outputs.py --segments segments.txt
|
||||
--expected-n <N> [--dir .] [--lyrics-file lyrics.txt]`
|
||||
|
||||
143
SKILL.md
Normal file
143
SKILL.md
Normal file
@ -0,0 +1,143 @@
|
||||
---
|
||||
name: mm-prompter
|
||||
description: Writes multi-segment ref2va video prompts plus T2I character-sheet prompts from a vague scene idea and a total video length in seconds. Use when the user gives a rough video/scene concept (optionally with song lyrics or an audio file name) and wants numbered video-generation segments joined by "|", character sheets as Image-N.json for characters that lack an image reference, and an image-map.txt manifest.
|
||||
---
|
||||
|
||||
# MM Prompt Creator
|
||||
|
||||
Turn one vague prompt and one number (total seconds) into a complete, ready-to-run
|
||||
generation package:
|
||||
|
||||
1. `segments.txt` — N segment prompts in full-reference (ref2va) format, joined by `|`.
|
||||
The downstream video creator node splits the total length evenly across segments and
|
||||
generates them one by one.
|
||||
2. `Image-N.json` — one 16:9 character-sheet text-to-image prompt per character that has
|
||||
no user-provided image reference. Consumed one at a time by a ComfyUI workflow.
|
||||
3. `image-map.txt` — manifest that says which `<Subject N>` maps to which image file.
|
||||
|
||||
Read `references/ref2va-segment-format.md` before drafting the first segment, and
|
||||
`references/t2i-character-sheet.md` before writing the first JSON. A complete end-to-end
|
||||
example (including the audio variant) is in `references/worked-example.md`.
|
||||
|
||||
## Inputs
|
||||
|
||||
| Input | Required | Notes |
|
||||
| --- | --- | --- |
|
||||
| Vague prompt | yes | Rough scene/idea text from the user |
|
||||
| Total video length in seconds | yes | Drives segment count |
|
||||
| Song lyrics | no | Guide pacing only; NEVER appear in any output |
|
||||
| Audio file mention | no | e.g. "use midnight.mp3" → enables `<Audio 1>` |
|
||||
| Per-character image references | no | User-supplied files (e.g. `mary.png`) |
|
||||
| Style hints | no | Honor if given; otherwise invent and lock |
|
||||
|
||||
Make reasonable creative choices and proceed. Do not block on questions; this skill
|
||||
exists to expand vagueness into concrete, consistent detail.
|
||||
|
||||
## Scope rules
|
||||
|
||||
- Subjects are **recurring on-screen characters only**: people, animals, creatures,
|
||||
robots that act as characters. Settings, props, and crowds stay in prose; they never
|
||||
get `<Subject N>` numbers or sheets.
|
||||
- Numbering is **global across the whole video**, assigned in order of first on-screen
|
||||
appearance: `<Subject 1>`, `<Subject 2>`, ... For every subject, the image number
|
||||
follows the subject number: Subject 2's reference is cited as `<Picture 2>` and, if
|
||||
generated, saved as `Image-2.json`.
|
||||
- A subject that does not appear in a segment must not be listed in that segment's
|
||||
`subject_definitions`.
|
||||
- No `<Video N>` labels: this skill never takes video input.
|
||||
- Output language: English.
|
||||
|
||||
## Pipeline (follow in order)
|
||||
|
||||
**Step 1 — Intake.** Parse the vague prompt. List every character that will be on
|
||||
screen. For each, decide: user-provided image reference (record filename) or needs a
|
||||
generated sheet. Detect audio file mentions and lyrics. Detect style hints.
|
||||
|
||||
**Step 2 — Segment count.** `n = max(1, round(total_seconds / 10))` with round-half-up:
|
||||
8s→1, 15s→2, 21s→2, 34s→3, 55s→6. Plan each segment as one beat of roughly
|
||||
`total_seconds / n`. Assume segments flow into each other as one longer scene unless
|
||||
the user says otherwise, so segment k's end state matches segment k+1's start state.
|
||||
|
||||
**Step 3 — Lock the story bible (before drafting).** Decide once, in a short working
|
||||
note, and never change it afterward: each subject's hair, eyes, build, wardrobe, props,
|
||||
and palette; the setting; time of day; lighting; color palette; camera character; style.
|
||||
Where the vague prompt is silent, invent specifics and lock them. Every segment and
|
||||
every sheet must use the identical locked values.
|
||||
|
||||
**Step 4 — Assign numbering.** Subject 1..M by first on-screen appearance across the
|
||||
whole video. Map references: user file (e.g. `mary.png`) or `Image-N.json`.
|
||||
|
||||
**Step 5 — Draft each segment** exactly per `references/ref2va-segment-format.md`:
|
||||
six sections in order, global labels, default one continuous `[Shot 1]` per segment,
|
||||
extra shots only for time-synced changes, timestamps relative to the segment start.
|
||||
When a subject sings to the provided audio, use the exact fixed audio template and the
|
||||
exact lip-sync phrase defined in that reference.
|
||||
|
||||
**Step 6 — Write the character sheets** per `references/t2i-character-sheet.md`, one
|
||||
`Image-N.json` per subject lacking a user reference. Captions must reuse the locked
|
||||
story-bible values verbatim.
|
||||
|
||||
**Step 7 — Write the manifest** `image-map.txt`, one line per subject:
|
||||
|
||||
```
|
||||
Subject 1 - mary.png
|
||||
Subject 2 - Image-2.json
|
||||
```
|
||||
|
||||
User-supplied files keep their filenames; generated sheets are always `Image-N.json`.
|
||||
|
||||
**Step 8 — Assemble `segments.txt`.** Strip each segment text, join with a single `|`
|
||||
(no spaces added around it). Exactly n segments, exactly n−1 `|` characters, no
|
||||
trailing separator, no extra headers or numbering. The `|` character must never appear
|
||||
inside a segment's own text.
|
||||
|
||||
**Step 9 — Validate** against the checklist below. When the environment can run Python,
|
||||
also run `python scripts/validate_outputs.py --segments segments.txt --expected-n <n>`.
|
||||
|
||||
## Output location
|
||||
|
||||
Write all outputs (`segments.txt`, `Image-N.json`, `image-map.txt`) into the current
|
||||
project folder of the project the skill is running on. If no project folder is
|
||||
obvious, use the current working directory. Never write outputs into the skill's own
|
||||
folder.
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. Lyrics NEVER appear in any output text — not in `detailed_description`, not in
|
||||
`<d>` tags, not in the audio sections. They only shape pacing and per-segment
|
||||
content. Singing is expressed solely by the lip-sync phrase and the fixed audio
|
||||
template.
|
||||
2. Song vocals come from the reused audio: do not invent `(Sx)` speaker IDs or `<d>`
|
||||
blocks for song lyrics. Ordinary spoken dialogue (non-song) may still use `(Sx)` +
|
||||
`<d>[Language] ...</d>` per the format reference.
|
||||
3. Global numbering is immutable across segments, sheets, and manifest.
|
||||
4. The audio template and lip-sync phrase are used verbatim with only `N` substituted.
|
||||
5. `[Shot 1]` never carries a timestamp; later shots use `At MM:SS.mmm` relative to the
|
||||
segment start.
|
||||
6. Every subject appearing anywhere in the video must have a manifest line.
|
||||
|
||||
## Validation checklist (all must pass before delivery)
|
||||
|
||||
1. `segments.txt` has exactly n segments and exactly n−1 `|` separators.
|
||||
2. Each segment contains all six sections in order: `subject_definitions`, `summary`,
|
||||
`retention_analysis`, `detailed_description`, `overall_soundscape`,
|
||||
`non_diegetic_music`.
|
||||
3. Subject numbering is global and gapless (1..M); `<Picture N>` cited inside
|
||||
`<Subject N>` always uses the same N.
|
||||
4. Every subject in the prompts has a manifest line; every `Image-N.json` in the
|
||||
manifest exists, parses, has exactly the two keys `expanded_caption` and
|
||||
`aspect_ratio`, and `aspect_ratio` is `"16:9"`. No orphan `Image-*.json` files.
|
||||
5. No `<Video` anywhere; no lyric text anywhere.
|
||||
6. Singing segments: summary prefix `[reference generation + audio reuse]`, the exact
|
||||
fixed audio template in the sound sections, and the exact lip-sync phrase inside
|
||||
`detailed_description`. Non-singing segments use `[reference generation]`.
|
||||
7. `[Shot 1]` has no timestamp; any `At MM:SS.mmm` appears only on `[Shot N]`, N≥2.
|
||||
8. Sheet captions and segment descriptions agree with the locked story bible.
|
||||
|
||||
## References
|
||||
|
||||
- `references/ref2va-segment-format.md` — authoritative per-segment format (sections,
|
||||
labels, shots, audio template, retention markers).
|
||||
- `references/t2i-character-sheet.md` — character-sheet caption rules and the two-key
|
||||
JSON output contract.
|
||||
- `references/worked-example.md` — full end-to-end example, including an audio variant.
|
||||
179
references/ref2va-segment-format.md
Normal file
179
references/ref2va-segment-format.md
Normal file
@ -0,0 +1,179 @@
|
||||
# Ref2VA Segment Format (generation from vague prompt)
|
||||
|
||||
This reference defines the exact format of ONE segment prompt produced by this skill.
|
||||
It adapts the full-reference mode output format (`segment-guide.md` in this repo) to
|
||||
the skill's use case: generating a ~10-second segment from scratch, where the only
|
||||
reference assets are character images (user-provided or generated `Image-N.json`
|
||||
sheets) and, optionally, one reused song audio file.
|
||||
|
||||
Write everything in English. Timestamps are relative to the segment start
|
||||
(`00:00.000` = first frame of this segment), because the video creator generates each
|
||||
segment independently and splits the total length evenly.
|
||||
|
||||
## 1. Segment skeleton
|
||||
|
||||
Each segment is one plain-text document with six sections in this exact order. Blank
|
||||
line between sections; one line per subject / retention entry:
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the <role/appearance summary> in <Picture 1>, with <locked traits>.
|
||||
<Subject 2> is the <role/appearance summary> in <Picture 2>, with <locked traits>.
|
||||
<Audio 1> is the user-supplied song file "<filename>", reused as the target segment's
|
||||
complete final audio track; <Subject N> performs its vocals.
|
||||
|
||||
summary:
|
||||
[reference generation] <one short paragraph naming subjects, shot flow, and roles of
|
||||
the reference assets>
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - <what exact traits are retained>.
|
||||
<Subject 2> (appears in [Shot 1]): fully_preserved - <what exact traits are retained>.
|
||||
<Audio 1>: fully_copy - <Audio 1> is reused 1:1 as the target video's complete final audio track.
|
||||
|
||||
detailed_description:
|
||||
<one or two style sentences>
|
||||
[Shot 1] <full description of the shot>
|
||||
|
||||
overall_soundscape:
|
||||
<ambience and physical sounds>
|
||||
|
||||
non_diegetic_music:
|
||||
<audience-only score, or N/A>
|
||||
```
|
||||
|
||||
Omit the `<Audio 1>` lines in all four places when no audio file is referenced.
|
||||
|
||||
## 2. `subject_definitions`
|
||||
|
||||
- One line per subject **present in this segment**, plus the audio definition when the
|
||||
segment uses the song. Never list subjects that do not appear in this segment.
|
||||
- Cite each character's reference image inside its definition: `<Subject 1> is the ...
|
||||
in <Picture 1>`. Do NOT create standalone `<Picture N>` entries: the images in this
|
||||
skill define characters, they are never frame anchors or storyboards.
|
||||
- Definition contents: identity, role, and the locked visible traits (hair, eyes,
|
||||
build, wardrobe, signature props) that the video must preserve. Keep the wording
|
||||
identical across segments — copy the trait phrases from the story bible.
|
||||
- Audio definition: name the file, state the reuse role. Example:
|
||||
`<Audio 1> is the user-supplied song file "midnight.mp3", reused as the target
|
||||
segment's complete final audio track; <Subject 1> performs its vocals.`
|
||||
- No `<Video N>` labels, ever.
|
||||
|
||||
## 3. `summary`
|
||||
|
||||
One short English paragraph. It MUST begin with the square-bracketed task-type prefix:
|
||||
|
||||
- Without audio: `[reference generation]`
|
||||
- With the song referenced: `[reference generation + audio reuse]`
|
||||
|
||||
After the prefix, name the subjects with their labels, the shot flow, and the role of
|
||||
each reference asset (`<Picture N>` as appearance/wardrobe source, `<Audio 1>` as the
|
||||
reused soundtrack the subject performs to). Do not introduce new labels.
|
||||
|
||||
## 4. `retention_analysis`
|
||||
|
||||
One line per subject present in the segment (plus the audio line when used). Markers
|
||||
are fixed English values: `fully_preserved`, `partially_preserved`, `attribute_transfer`,
|
||||
`weak_reference`. This skill's default is `fully_preserved` for every subject — segments
|
||||
flow into one continuous scene, so nothing about a character's locked look may drift:
|
||||
|
||||
```text
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - the matte-white EVA suit with
|
||||
orange stripes, short black hair, and the wrist scanner are retained.
|
||||
```
|
||||
|
||||
Audio line for song segments (exact marker and phrasing):
|
||||
|
||||
```text
|
||||
<Audio 1>: fully_copy - <Audio 1> is reused 1:1 as the target video's complete final audio track.
|
||||
```
|
||||
|
||||
## 5. `detailed_description`
|
||||
|
||||
The main body. Structure:
|
||||
|
||||
1. **Style opening** — one or two English sentences BEFORE `[Shot 1]` fixing style,
|
||||
lighting, and palette (from the story bible).
|
||||
2. **Shots** — `[Shot 1]` opens the segment and carries NO timestamp. Only split into
|
||||
`[Shot N] At MM:SS.mmm, ...` (N ≥ 2) when the segment needs a time-synced change
|
||||
(beat drop, lighting change, arrival event). Timestamps are relative to the segment
|
||||
start. Default is a single continuous `[Shot 1]`.
|
||||
|
||||
Inside the shot description:
|
||||
|
||||
- At the first appearance of each `<Subject N>`, weave in the locked traits, frame
|
||||
position, and current action. Reuse the same label later without redefining it.
|
||||
- Describe composition, environment and lighting, action and state changes, camera
|
||||
movement (type, amplitude, speed) as natural English.
|
||||
- Target roughly 350–500 words. A single shot does not justify a thin description;
|
||||
distribute detail across the full ~10 seconds. Never reduce it to a plot summary.
|
||||
- **Singing:** at the point(s) where the character is visibly singing, include the
|
||||
exact phrase `<Subject N> lips are synced to the audio in <Audio 1>` (substitute the
|
||||
real subject number; no possessive apostrophe). Example:
|
||||
`<Subject 1> lips are synced to the audio in <Audio 1> through the final chorus as she ...`
|
||||
- **Never quote lyrics** — no `<d>` blocks for the song, no lyric words. The vocal
|
||||
content lives in the reused audio only.
|
||||
- Ordinary spoken dialogue (non-song) is allowed when the scene implies it: give the
|
||||
speaker a stable `(S1)`, `(S2)` ID and write `<d>[English] ...</d>` per the source
|
||||
guide. This does not apply to the song.
|
||||
- No `<Video N>` labels.
|
||||
|
||||
## 6. `overall_soundscape` and `non_diegetic_music`
|
||||
|
||||
Both are written heading-on-its-own-line, content on the next line.
|
||||
|
||||
**Singing segments (audio file referenced) — use this EXACT template, verbatim, with
|
||||
only the subject number substituted. One line per singing subject:**
|
||||
|
||||
```text
|
||||
overall_soundscape:
|
||||
<Subject N> is Singing the words of <Audio 1>
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
```
|
||||
|
||||
**Non-singing segments** — describe ambience and physical sounds diegetically:
|
||||
|
||||
```text
|
||||
overall_soundscape:
|
||||
Dry desert wind with fine grit against the helmet shell, low boots pressing into
|
||||
cooling sand, and a faint sub-bass hum rising from the monolith.
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
```
|
||||
|
||||
`non_diegetic_music` is `N/A` when the scene lives on diegetic sound alone; when the
|
||||
vague prompt calls for a score (epic, tense, tender...), describe an original
|
||||
audience-only score with instrumentation, tempo, and dynamics. Never put the reused
|
||||
song here — the song is diegetic performance audio covered by the template above.
|
||||
Never repeat lyrics in either section.
|
||||
|
||||
## 7. Worked micro-example
|
||||
|
||||
One 10-second segment of a two-character desert scene (full end-to-end example in
|
||||
`references/worked-example.md`):
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the astronaut in <Picture 1>, a woman in her thirties with short black hair, wearing a matte-white EVA suit with orange stripe accents and a wrist-mounted scanner.
|
||||
<Subject 2> is the scout robot in <Picture 2>, a boxy machine on three wheels with a pale-grey shell and a single round blue lens eye.
|
||||
|
||||
summary:
|
||||
[reference generation] The target video shows <Subject 1> and <Subject 2> cresting a red dune at dusk and stopping before a monolith of black glass. <Subject 1>'s appearance and suit come from <Picture 1> and <Subject 2>'s shell and lens come from <Picture 2>.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - the matte-white EVA suit with orange stripe accents, short black hair, and the wrist-mounted scanner are retained.
|
||||
<Subject 2> (appears in [Shot 1]): fully_preserved - the boxy pale-grey shell, three wheels, and the single round blue lens eye are retained.
|
||||
|
||||
detailed_description:
|
||||
The target video uses a cinematic sci-fi realism style with low dusk light, long violet shadows, and a muted red-and-violet palette.
|
||||
[Shot 1] A wide establishing shot holds on a red desert at dusk, the sky a deep gradient of burnt orange fading into indigo. <Subject 1>, the astronaut in the matte-white EVA suit with orange stripe accents, short black hair under a clear dome, and a wrist-mounted scanner on her left forearm, crests the dune on the left of frame, boots sinking into rippled sand with each step. <Subject 2>, the boxy scout robot with a pale-grey shell and a single round blue lens eye, wheels up the slope on her right, treads leaving a neat triple track. The camera tracks laterally with their descent at walking pace, then slows as the pair reaches the flat basin. Ahead, a monolith of black glass stands three stories tall, its surface drinking the last light; a faint sub-bass hum pushes grit outward from its base in slow pulses. <Subject 1> stops two meters short, raises the wrist scanner, and the device's amber readout reflects in her dome. <Subject 2>'s blue lens dilates with a soft mechanical whir, and its head tilts toward the monolith. The camera pushes in slowly past her shoulder, ending on the monolith's mirrored face holding both their reflections as the hum deepens.
|
||||
|
||||
overall_soundscape:
|
||||
Dry desert wind with fine grit against the helmet shell, the crunch of boots in cooling sand, the soft whir of the robot's wheels, and the monolith's low pulsing hum.
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
```
|
||||
82
references/t2i-character-sheet.md
Normal file
82
references/t2i-character-sheet.md
Normal file
@ -0,0 +1,82 @@
|
||||
# T2I Character Sheet Prompts (Image-N.json)
|
||||
|
||||
This reference defines how the skill writes one character-sheet text-to-image prompt
|
||||
for a character that has no user-provided image reference. It adapts the caption-
|
||||
expansion and JSON contract rules in `t2i-prompt-rules/` of this repo.
|
||||
|
||||
## 1. Output contract (exact)
|
||||
|
||||
One file per character, named `Image-N.json` where N is the character's `<Subject N>`
|
||||
number. File content is exactly one JSON object with exactly two keys — no markdown
|
||||
fence, no commentary, no extra keys:
|
||||
|
||||
```json
|
||||
{"expanded_caption": "ONE_DETAILED_ENGLISH_CAPTION", "aspect_ratio": "16:9"}
|
||||
```
|
||||
|
||||
- `aspect_ratio` is ALWAYS the string `"16:9"` for these sheets. This overrides the
|
||||
general ratio-selection policy in the source rules.
|
||||
- `expanded_caption` is ONE fluent English paragraph (a string). Every ASCII double
|
||||
quote used inside the caption is serialized as the JSON escape `\"`; escape all
|
||||
other characters as valid JSON requires.
|
||||
- The file must parse with a standard JSON parser.
|
||||
|
||||
## 2. What the sheet is for
|
||||
|
||||
The rendered sheet becomes the character's reference image: it is cited as
|
||||
`<Picture N>` in the segment prompts and drives the character's identity in every
|
||||
segment. Therefore the caption must make the character's canonical look fully
|
||||
inspectable, and its every detail must match the locked story bible used by the
|
||||
segment prompts — same hair, eyes, build, wardrobe colors, materials, props. If the
|
||||
vague prompt left a trait unspecified, the skill invents it once (Step 3 of the
|
||||
pipeline) and uses the identical wording here and in the segments.
|
||||
|
||||
## 3. Caption design rules
|
||||
|
||||
Act as an expert visual designer. The requested image is a communication artifact —
|
||||
a designed character card / model sheet on a horizontal 16:9 canvas — not a plain
|
||||
portrait and not a scene. Build a finished information architecture:
|
||||
|
||||
Required elements (weave them into one flowing caption paragraph):
|
||||
|
||||
1. **Frame the artifact**: state that this is a 16:9 horizontal character design
|
||||
board / model sheet for the named character, clean designed layout.
|
||||
2. **Identity block**: title/name tag with the character's name (invent a fitting
|
||||
name if the prompt gives none), role line, optional short profile/about note.
|
||||
3. **One large full-body view**: the character standing in a neutral, readable
|
||||
stance (front or slight three-quarter), full figure with readable proportions,
|
||||
feet visible, no cropping.
|
||||
4. **Inspectable trait detail**: hair style and color, eye color, skin tone, build,
|
||||
each wardrobe piece with its color and material, footwear, and any signature
|
||||
props — exactly the locked story-bible values.
|
||||
5. **Attribute rows / callouts**: labeled swatch or annotation elements for key
|
||||
colors (palette strip) and materials, so the board reads as a designed sheet.
|
||||
6. **Props tied to the role** displayed beside or held by the figure when the role
|
||||
implies them.
|
||||
7. **Optional supporting elements** that add completeness without clutter: a short
|
||||
quote or badge, a small contextual backdrop hint, an instruction row. Keep these
|
||||
as short readable on-image labels, not prose blocks.
|
||||
|
||||
Hard rules carried over from the source rules:
|
||||
|
||||
- Preserve every hard fact from the user's prompt (names, stated traits, counts).
|
||||
- Required content must be visible, not implied; if a label is described, say where
|
||||
it sits on the board.
|
||||
- One character per sheet. No other characters; background figures never compete.
|
||||
- Replace abstract mood and generic adjectives ("cool", "epic") with specific
|
||||
visible cues (colors, materials, light).
|
||||
- The caption is a description of the image, not instructions to the viewer; write
|
||||
it as one descriptive paragraph in present tense.
|
||||
|
||||
## 4. Example
|
||||
|
||||
For an astronaut character locked as: woman in her thirties, short black hair, brown
|
||||
eyes, matte-white EVA suit with orange stripe accents, wrist-mounted scanner, clear
|
||||
dome helmet:
|
||||
|
||||
```json
|
||||
{"expanded_caption": "A 16:9 horizontal character design board titled \"VOSS\" in a clean technical sans-serif name tag, presenting a female astronaut in her thirties with short black hair and brown eyes, shown in one large full-body view standing in a neutral stance, feet fully visible. She wears a matte-white EVA suit with orange stripe accents along the arms and chest, a clear dome helmet, grey reinforced gloves, and a wrist-mounted scanner with a small amber readout on her left forearm. A role line under the name tag reads \"Deep-Field Survey Specialist\", and a short profile note describes a calm, methodical explorer. Along the bottom edge, a labeled palette strip shows matte white, safety orange, graphite grey, and amber swatches, with thin callout lines pointing to the suit fabric, helmet glass, and scanner housing. Two signature props, the wrist scanner and a compact sample canister, are displayed as small inset items beside the figure on a light grey drafting-paper background with subtle grid lines, so the board reads as a designed character sheet rather than a plain portrait.", "aspect_ratio": "16:9"}
|
||||
```
|
||||
|
||||
Write the file exactly in this compact single-line form: one JSON object, two keys,
|
||||
no surrounding text, no markdown fence inside the file.
|
||||
189
references/worked-example.md
Normal file
189
references/worked-example.md
Normal file
@ -0,0 +1,189 @@
|
||||
# Worked Example (end-to-end)
|
||||
|
||||
This example shows the complete deliverable for one run of the skill, followed by the
|
||||
audio variant. Copy its structure, not its content.
|
||||
|
||||
## Input
|
||||
|
||||
- Vague prompt: "An astronaut and her scout robot discover a glowing black monolith in
|
||||
a red desert at dusk"
|
||||
- Total length: 21 seconds
|
||||
- No image references, no audio, no lyrics
|
||||
|
||||
## Step 1–4 working notes (story bible)
|
||||
|
||||
- Segment count: `max(1, round(21 / 10))` = **2** segments (~10.5 s each), flowing
|
||||
continuously.
|
||||
- Subject 1 — Dr. Mara Voss, astronaut: woman in her thirties, short black hair, brown
|
||||
eyes, matte-white EVA suit with orange stripe accents, grey reinforced gloves,
|
||||
wrist-mounted scanner on her left forearm, clear dome helmet. No reference image →
|
||||
generate `Image-1.json`.
|
||||
- Subject 2 — scout robot "PIP": boxy machine on three wheels, pale-grey shell, single
|
||||
round blue lens eye, short antenna. No reference image → generate `Image-2.json`.
|
||||
- Setting: red desert basin at dusk; a three-story monolith of black glass emitting a
|
||||
slow pulsing sub-bass hum.
|
||||
- Style: cinematic sci-fi realism, low dusk light, long violet shadows, muted
|
||||
red-and-violet palette.
|
||||
- Sound: dry desert wind, grit, crunching sand, soft mechanical whirs, monolith hum.
|
||||
|
||||
## Segment 1 (~0–10.5 s)
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the astronaut in <Picture 1>, a woman in her thirties with short black hair and brown eyes, wearing a matte-white EVA suit with orange stripe accents, grey reinforced gloves, a clear dome helmet, and a wrist-mounted scanner on her left forearm.
|
||||
<Subject 2> is the scout robot in <Picture 2>, a boxy machine on three wheels with a pale-grey shell, a single round blue lens eye, and a short antenna.
|
||||
|
||||
summary:
|
||||
[reference generation] The target video shows <Subject 1> and <Subject 2> cresting a red dune at dusk and stopping before a monolith of black glass. <Subject 1>'s appearance and suit come from <Picture 1> and <Subject 2>'s shell and lens come from <Picture 2>.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair, clear dome helmet, and the wrist-mounted scanner on her left forearm are retained.
|
||||
<Subject 2> (appears in [Shot 1]): fully_preserved - the boxy pale-grey shell, three wheels, single round blue lens eye, and short antenna are retained.
|
||||
|
||||
detailed_description:
|
||||
The target video uses a cinematic sci-fi realism style with low dusk light, long violet shadows, and a muted red-and-violet palette.
|
||||
[Shot 1] A wide establishing shot holds on a red desert at dusk, the sky a deep gradient of burnt orange fading into indigo. <Subject 1>, the astronaut in the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair under a clear dome helmet, and the wrist-mounted scanner on her left forearm, crests the dune on the left of frame, boots sinking into rippled sand with each step. <Subject 2>, the boxy scout robot with a pale-grey shell, single round blue lens eye, and short antenna, wheels up the slope on her right, treads leaving a neat triple track. The camera tracks laterally with their descent at walking pace, then slows as the pair reaches the flat basin. Ahead, a monolith of black glass stands three stories tall, its surface drinking the last light; a faint sub-bass hum pushes grit outward from its base in slow pulses. <Subject 1> stops two meters short, raises the wrist scanner, and the device's amber readout reflects in her dome. <Subject 2>'s blue lens dilates with a soft mechanical whir and its head tilts toward the monolith. The camera pushes in slowly past her shoulder, ending on the monolith's mirrored face holding both their reflections as the hum deepens.
|
||||
|
||||
overall_soundscape:
|
||||
Dry desert wind with fine grit against the helmet shell, the crunch of boots in cooling sand, the soft whir of the robot's wheels, and the monolith's low pulsing hum.
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
```
|
||||
|
||||
## Segment 2 (~10.5–21 s)
|
||||
|
||||
The monolith ignition is a time-synced change, so this segment uses two shots. Note
|
||||
the relative timestamp on `[Shot 2]` and the original score in `non_diegetic_music`.
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the astronaut in <Picture 1>, a woman in her thirties with short black hair and brown eyes, wearing a matte-white EVA suit with orange stripe accents, grey reinforced gloves, a clear dome helmet, and a wrist-mounted scanner on her left forearm.
|
||||
<Subject 2> is the scout robot in <Picture 2>, a boxy machine on three wheels with a pale-grey shell, a single round blue lens eye, and a short antenna.
|
||||
|
||||
summary:
|
||||
[reference generation] The target video continues the desert encounter as the monolith ignites with amber circuitry light. <Subject 1> keeps her appearance from <Picture 1> and <Subject 2> keeps its shell and lens from <Picture 2> while the pair reacts in awe.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1], [Shot 2]): fully_preserved - the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair, clear dome helmet, and the wrist-mounted scanner on her left forearm are retained.
|
||||
<Subject 2> (appears in [Shot 1], [Shot 2]): fully_preserved - the boxy pale-grey shell, three wheels, single round blue lens eye, and short antenna are retained.
|
||||
|
||||
detailed_description:
|
||||
The target video continues the cinematic sci-fi realism style with low dusk light, long violet shadows, and a muted red-and-violet palette.
|
||||
[Shot 1] The shot resumes on the pair standing before the monolith in the red desert basin at dusk. <Subject 1>, the astronaut in the matte-white EVA suit with orange stripe accents and the wrist-mounted scanner on her left forearm, holds the device up, its amber readout flickering faster. <Subject 2>, the boxy scout robot with the pale-grey shell and single round blue lens eye, hovers its head between her and the monolith, antenna trembling. The camera holds at her shoulder height, breathing slowly with the wind.
|
||||
[Shot 2] At 00:05.000, the monolith's black surface ignites with slow rivers of amber circuitry light climbing from the base to its top edge, throwing hard orange reflections across her dome and the robot's shell. Fine red dust lifts from the basin floor in a widening ring. <Subject 1> takes one careful step closer, boots pressing half-moons into the sand, and lowers the scanner. <Subject 2>'s blue lens flares and it projects a thin fan of blue scan light across the glowing surface. The camera tilts up smoothly from their reflected faces to the monolith's crown as the amber light reaches full brightness, then settles back down to the two small figures against the towering glass.
|
||||
|
||||
overall_soundscape:
|
||||
Dry desert wind rising in gusts, the deepening pulse of the monolith's hum, the whir of the robot's scan projector, and fine grit ticking against the helmet shell.
|
||||
|
||||
non_diegetic_music:
|
||||
A low sustained analog-synth drone enters softly with the ignition and swells in volume and harmonic richness through the final frames, with no percussion.
|
||||
```
|
||||
|
||||
## `segments.txt`
|
||||
|
||||
The file contains the two segment texts above, each stripped of leading/trailing
|
||||
whitespace, joined by a single `|` character with nothing added around it — one
|
||||
segment flows directly into the separator, the next begins immediately after it:
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the astronaut in <Picture 1>, a woman in her thirties with short black hair and brown eyes, wearing a matte-white EVA suit with orange stripe accents, grey reinforced gloves, a clear dome helmet, and a wrist-mounted scanner on her left forearm.
|
||||
<Subject 2> is the scout robot in <Picture 2>, a boxy machine on three wheels with a pale-grey shell, a single round blue lens eye, and a short antenna.
|
||||
|
||||
summary:
|
||||
[reference generation] The target video shows <Subject 1> and <Subject 2> cresting a red dune at dusk and stopping before a monolith of black glass. <Subject 1>'s appearance and suit come from <Picture 1> and <Subject 2>'s shell and lens come from <Picture 2>.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair, clear dome helmet, and the wrist-mounted scanner on her left forearm are retained.
|
||||
<Subject 2> (appears in [Shot 1]): fully_preserved - the boxy pale-grey shell, three wheels, single round blue lens eye, and short antenna are retained.
|
||||
|
||||
detailed_description:
|
||||
The target video uses a cinematic sci-fi realism style with low dusk light, long violet shadows, and a muted red-and-violet palette.
|
||||
[Shot 1] A wide establishing shot holds on a red desert at dusk, the sky a deep gradient of burnt orange fading into indigo. <Subject 1>, the astronaut in the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair under a clear dome helmet, and the wrist-mounted scanner on her left forearm, crests the dune on the left of frame, boots sinking into rippled sand with each step. <Subject 2>, the boxy scout robot with a pale-grey shell, single round blue lens eye, and short antenna, wheels up the slope on her right, treads leaving a neat triple track. The camera tracks laterally with their descent at walking pace, then slows as the pair reaches the flat basin. Ahead, a monolith of black glass stands three stories tall, its surface drinking the last light; a faint sub-bass hum pushes grit outward from its base in slow pulses. <Subject 1> stops two meters short, raises the wrist scanner, and the device's amber readout reflects in her dome. <Subject 2>'s blue lens dilates with a soft mechanical whir and its head tilts toward the monolith. The camera pushes in slowly past her shoulder, ending on the monolith's mirrored face holding both their reflections as the hum deepens.
|
||||
|
||||
overall_soundscape:
|
||||
Dry desert wind with fine grit against the helmet shell, the crunch of boots in cooling sand, the soft whir of the robot's wheels, and the monolith's low pulsing hum.
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
|subject_definitions:
|
||||
<Subject 1> is the astronaut in <Picture 1>, a woman in her thirties with short black hair and brown eyes, wearing a matte-white EVA suit with orange stripe accents, grey reinforced gloves, a clear dome helmet, and a wrist-mounted scanner on her left forearm.
|
||||
<Subject 2> is the scout robot in <Picture 2>, a boxy machine on three wheels with a pale-grey shell, a single round blue lens eye, and a short antenna.
|
||||
|
||||
summary:
|
||||
[reference generation] The target video continues the desert encounter as the monolith ignites with amber circuitry light. <Subject 1> keeps her appearance from <Picture 1> and <Subject 2> keeps its shell and lens from <Picture 2> while the pair reacts in awe.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1], [Shot 2]): fully_preserved - the matte-white EVA suit with orange stripe accents, grey reinforced gloves, short black hair, clear dome helmet, and the wrist-mounted scanner on her left forearm are retained.
|
||||
<Subject 2> (appears in [Shot 1], [Shot 2]): fully_preserved - the boxy pale-grey shell, three wheels, single round blue lens eye, and short antenna are retained.
|
||||
|
||||
detailed_description:
|
||||
The target video continues the cinematic sci-fi realism style with low dusk light, long violet shadows, and a muted red-and-violet palette.
|
||||
[Shot 1] The shot resumes on the pair standing before the monolith in the red desert basin at dusk. <Subject 1>, the astronaut in the matte-white EVA suit with orange stripe accents and the wrist-mounted scanner on her left forearm, holds the device up, its amber readout flickering faster. <Subject 2>, the boxy scout robot with the pale-grey shell and single round blue lens eye, hovers its head between her and the monolith, antenna trembling. The camera holds at her shoulder height, breathing slowly with the wind.
|
||||
[Shot 2] At 00:05.000, the monolith's black surface ignites with slow rivers of amber circuitry light climbing from the base to its top edge, throwing hard orange reflections across her dome and the robot's shell. Fine red dust lifts from the basin floor in a widening ring. <Subject 1> takes one careful step closer, boots pressing half-moons into the sand, and lowers the scanner. <Subject 2>'s blue lens flares and it projects a thin fan of blue scan light across the glowing surface. The camera tilts up smoothly from their reflected faces to the monolith's crown as the amber light reaches full brightness, then settles back down to the two small figures against the towering glass.
|
||||
|
||||
overall_soundscape:
|
||||
Dry desert wind rising in gusts, the deepening pulse of the monolith's hum, the whir of the robot's scan projector, and fine grit ticking against the helmet shell.
|
||||
|
||||
non_diegetic_music:
|
||||
A low sustained analog-synth drone enters softly with the ignition and swells in volume and harmonic richness through the final frames, with no percussion.
|
||||
```
|
||||
|
||||
## `image-map.txt`
|
||||
|
||||
```
|
||||
Subject 1 - Image-1.json
|
||||
Subject 2 - Image-2.json
|
||||
```
|
||||
|
||||
If Subject 1 had a user-provided reference instead, the line would be
|
||||
`Subject 1 - voss.png` and no `Image-1.json` would be generated.
|
||||
|
||||
## `Image-1.json`
|
||||
|
||||
```json
|
||||
{"expanded_caption": "A 16:9 horizontal character design board titled \"VOSS\" in a clean technical sans-serif name tag, presenting a female astronaut in her thirties with short black hair and brown eyes, shown in one large full-body view standing in a neutral stance, feet fully visible. She wears a matte-white EVA suit with orange stripe accents along the arms and chest, a clear dome helmet, grey reinforced gloves, and a wrist-mounted scanner with a small amber readout on her left forearm. A role line under the name tag reads \"Deep-Field Survey Specialist\", and a short profile note describes a calm, methodical explorer. Along the bottom edge, a labeled palette strip shows matte white, safety orange, graphite grey, and amber swatches, with thin callout lines pointing to the suit fabric, helmet glass, and scanner housing. Two signature props, the wrist scanner and a compact sample canister, are displayed as small inset items beside the figure on a light grey drafting-paper background with subtle grid lines, so the board reads as a designed character sheet rather than a plain portrait.", "aspect_ratio": "16:9"}
|
||||
```
|
||||
|
||||
## `Image-2.json`
|
||||
|
||||
```json
|
||||
{"expanded_caption": "A 16:9 horizontal character design board titled \"PIP\" in a rounded technical name tag, presenting a small scout robot shown in one large full-body view in a neutral parked stance, all three wheels fully visible. The robot has a boxy pale-grey shell with soft rounded corners, a single large round blue lens eye centered on its front face, a short antenna on the roof panel, and a triple-wheel base with dark rubber treads. A role line under the name tag reads \"Terraform Scout Unit\", and a short profile note describes a curious, loyal field companion. Along the bottom edge, a labeled palette strip shows pale grey, gunmetal, signal blue, and dark rubber swatches, with thin callout lines pointing to the shell coating, lens glass, antenna joint, and wheel treads. One signature prop, a folded scan projector arm, is displayed as a small inset item beside the figure on a light grey drafting-paper background with subtle grid lines, so the board reads as a designed character sheet rather than a plain portrait.", "aspect_ratio": "16:9"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# Audio variant (one singing segment)
|
||||
|
||||
Input: "A cabaret singer performs her final song in a smoky bar, use midnight.mp3",
|
||||
10 seconds, lyrics provided (4 lines — they shape the pacing only and never appear in
|
||||
any output), no image reference. Subject 1 — the singer: woman in her late forties,
|
||||
auburn curls, emerald satin slip dress, black opera gloves. She has no reference
|
||||
image, so an `Image-1.json` sheet is generated exactly as shown earlier, reusing
|
||||
these same locked traits. Note the `[reference generation + audio reuse]` prefix, the
|
||||
`<Audio 1>` lines, the lip-sync phrase inside `detailed_description`, and the exact
|
||||
fixed audio template.
|
||||
|
||||
```text
|
||||
subject_definitions:
|
||||
<Subject 1> is the cabaret singer in <Picture 1>, a woman in her late forties with voluminous auburn curls, wearing an emerald satin slip dress and black opera gloves.
|
||||
<Audio 1> is the user-supplied song file "midnight.mp3", reused as the target segment's complete final audio track; <Subject 1> performs its vocals.
|
||||
|
||||
summary:
|
||||
[reference generation + audio reuse] The target video shows <Subject 1> delivering the final song on a smoky cabaret stage, her appearance drawn from <Picture 1>, while <Audio 1> is reused as the complete final audio track she performs to.
|
||||
|
||||
retention_analysis:
|
||||
<Subject 1> (appears in [Shot 1]): fully_preserved - the voluminous auburn curls, emerald satin slip dress, and black opera gloves are retained.
|
||||
<Audio 1>: fully_copy - <Audio 1> is reused 1:1 as the target video's complete final audio track.
|
||||
|
||||
detailed_description:
|
||||
The target video uses a warm film-noir cabaret style with tungsten spotlights, drifting cigarette smoke, and a deep amber-and-emerald palette.
|
||||
[Shot 1] A slow push-in starts wide on a smoky cabaret stage, a single tungsten spotlight carving a cone through the haze above a vintage chrome microphone. <Subject 1>, the woman in her late forties with voluminous auburn curls, wearing the emerald satin slip dress and black opera gloves, stands with one gloved hand resting on the microphone stand, fingers tightening on the final note's approach. As the song's last verse begins, <Subject 1> lips are synced to the audio in <Audio 1>, her chin lifting on the held high note while the spotlight rims her curls in gold. She draws the microphone closer, eyes closing, free hand pressing flat against her heart through the descending phrase. The camera continues its slow push past the microphone's chrome grille until her face fills the frame in profile, smoke drifting between the lens and the light, and she lowers her head as the song resolves.
|
||||
|
||||
overall_soundscape:
|
||||
<Subject 1> is Singing the words of <Audio 1>
|
||||
|
||||
non_diegetic_music:
|
||||
N/A
|
||||
```
|
||||
295
scripts/validate_outputs.py
Normal file
295
scripts/validate_outputs.py
Normal file
@ -0,0 +1,295 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validator for mm-prompter skill outputs.
|
||||
|
||||
Checks the output contract described in SKILL.md:
|
||||
- segments.txt: n segments, n-1 "|" separators, six sections per segment in order
|
||||
- global gapless Subject numbering, <Picture N> paired with <Subject N>
|
||||
- image-map.txt manifest covers every subject; Image-N.json valid (two keys, 16:9)
|
||||
- no <Video> labels; lyrics (optional file) never appear in the prompts
|
||||
- audio segments: exact summary prefix, exact audio template, lip-sync phrase,
|
||||
fully_copy retention line
|
||||
- [Shot 1] has no timestamp; shot numbers contiguous; timestamps only on N>=2
|
||||
|
||||
Usage:
|
||||
python3 scripts/validate_outputs.py --segments segments.txt [--expected-n 3] \
|
||||
[--dir .] [--manifest image-map.txt] [--lyrics-file lyrics.txt] [--expect-audio]
|
||||
|
||||
Exit code 0 = all checks passed, 1 = failures listed.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SECTION_ORDER = [
|
||||
"subject_definitions",
|
||||
"summary",
|
||||
"retention_analysis",
|
||||
"detailed_description",
|
||||
"overall_soundscape",
|
||||
"non_diegetic_music",
|
||||
]
|
||||
|
||||
AUDIO_TEMPLATE_RE = re.compile(
|
||||
r"overall_soundscape:\s*"
|
||||
r"(?:<Subject (\d+)> is Singing the words of <Audio 1>\s*)+"
|
||||
r"non_diegetic_music:\s*N/A\s*$"
|
||||
)
|
||||
LIPSYNC_RE = re.compile(r"<Subject (\d+)> lips are synced to the audio in <Audio 1>")
|
||||
AUDIO_RETENTION_RE = re.compile(
|
||||
r"<Audio 1>: fully_copy - <Audio 1> is reused 1:1 as the target video's "
|
||||
r"complete final audio track\."
|
||||
)
|
||||
SHOT_RE = re.compile(r"\[Shot (\d+)\]( At (\d{2}):(\d{2})\.(\d{3}))?")
|
||||
SUBJECT_RE = re.compile(r"<Subject (\d+)>")
|
||||
PICTURE_RE = re.compile(r"<Picture (\d+)>")
|
||||
|
||||
|
||||
def fail(errors, seg_no, msg):
|
||||
errors.append(f"[segment {seg_no}] {msg}" if seg_no else msg)
|
||||
|
||||
|
||||
def split_sections(segment_text, seg_no, errors):
|
||||
"""Return {name: content} or None if headings are missing/out of order."""
|
||||
positions = []
|
||||
for name in SECTION_ORDER:
|
||||
matches = list(re.finditer(rf"^{name}:\s*$", segment_text, re.MULTILINE))
|
||||
if len(matches) != 1:
|
||||
errors.append(f"[segment {seg_no}] section '{name}:' must appear exactly "
|
||||
f"once on its own line (found {len(matches)})")
|
||||
return None
|
||||
positions.append((name, matches[0].start(), matches[0].end()))
|
||||
for i in range(1, len(positions)):
|
||||
if positions[i][1] <= positions[i - 1][1]:
|
||||
errors.append(f"[segment {seg_no}] sections out of order at '{positions[i][0]}'")
|
||||
return None
|
||||
sections = {}
|
||||
for i, (name, start, end) in enumerate(positions):
|
||||
next_start = positions[i + 1][1] if i + 1 < len(positions) else len(segment_text)
|
||||
sections[name] = segment_text[end:next_start].strip()
|
||||
return sections
|
||||
|
||||
|
||||
def normalize(text):
|
||||
return re.sub(r"\s+", " ", text).strip().lower()
|
||||
|
||||
|
||||
def check_segment(seg_text, seg_no, errors):
|
||||
"""Per-segment checks. Returns (defined_subjects, has_audio)."""
|
||||
sections = split_sections(seg_text, seg_no, errors)
|
||||
if sections is None:
|
||||
return set(), False
|
||||
|
||||
defs = sections["subject_definitions"]
|
||||
body_after_defs = seg_text.split("detailed_description:", 1)[1] \
|
||||
if "detailed_description:" in seg_text else ""
|
||||
defined = set(SUBJECT_RE.findall(defs))
|
||||
used_after_defs = set(SUBJECT_RE.findall(body_after_defs))
|
||||
|
||||
if defined and not used_after_defs:
|
||||
fail(errors, seg_no, "no subject label is used after subject_definitions; "
|
||||
"defined subjects must appear in the body sections")
|
||||
|
||||
# Picture pairing: each definition line must cite <Picture N> with N == subject N
|
||||
for line in [ln for ln in defs.splitlines() if ln.strip()]:
|
||||
if line.lstrip().startswith("<Audio"):
|
||||
continue
|
||||
m = re.match(r"\s*<Subject (\d+)>", line)
|
||||
if not m:
|
||||
fail(errors, seg_no, f"subject_definitions line does not start with a "
|
||||
f"<Subject N> label: {line.strip()[:60]}...")
|
||||
continue
|
||||
n = m.group(1)
|
||||
pics = PICTURE_RE.findall(line)
|
||||
if pics != [n]:
|
||||
fail(errors, seg_no, f"<Subject {n}> definition must cite exactly "
|
||||
f"<Picture {n}> (found {pics})")
|
||||
|
||||
# Summary prefix
|
||||
summary = sections["summary"]
|
||||
has_audio = "<Audio" in seg_text
|
||||
if has_audio:
|
||||
if not summary.startswith("[reference generation + audio reuse]"):
|
||||
fail(errors, seg_no, "audio segment summary must start with "
|
||||
"'[reference generation + audio reuse]'")
|
||||
if not AUDIO_TEMPLATE_RE.search(seg_text):
|
||||
fail(errors, seg_no, "audio segment must end with the exact fixed audio "
|
||||
"template: 'overall_soundscape:' / '<Subject N> is "
|
||||
"Singing the words of <Audio 1>' / 'non_diegetic_music:' / 'N/A'")
|
||||
if not LIPSYNC_RE.search(sections["detailed_description"]):
|
||||
fail(errors, seg_no, "audio segment detailed_description must contain "
|
||||
"'<Subject N> lips are synced to the audio in <Audio 1>'")
|
||||
if not AUDIO_RETENTION_RE.search(sections["retention_analysis"]):
|
||||
fail(errors, seg_no, "audio segment retention_analysis must contain the "
|
||||
"exact fully_copy line for <Audio 1>")
|
||||
if "<d>" in sections["detailed_description"]:
|
||||
print(f"WARN: [segment {seg_no}] <d> block inside an audio segment; song "
|
||||
f"lyrics must never be written out", file=sys.stderr)
|
||||
else:
|
||||
if not summary.startswith("[reference generation]"):
|
||||
fail(errors, seg_no, "summary must start with '[reference generation]'")
|
||||
if "<Audio" in seg_text:
|
||||
fail(errors, seg_no, "segment mixes <Audio> usage with non-audio prefix")
|
||||
|
||||
# Shots
|
||||
shots = SHOT_RE.findall(sections["detailed_description"])
|
||||
shot_lines = re.findall(r"^\[Shot (\d+)\].*$", sections["detailed_description"],
|
||||
re.MULTILINE)
|
||||
if shot_lines:
|
||||
nums = [int(n) for n in shot_lines]
|
||||
if nums != list(range(1, len(nums) + 1)):
|
||||
fail(errors, seg_no, f"shot numbers must start at [Shot 1] and be "
|
||||
f"contiguous (found {nums})")
|
||||
prev_ts = 0.0
|
||||
for m in SHOT_RE.finditer(sections["detailed_description"]):
|
||||
n = int(m.group(1))
|
||||
if m.group(2):
|
||||
if n == 1:
|
||||
fail(errors, seg_no, "[Shot 1] must not carry a timestamp")
|
||||
ts = int(m.group(3)) * 60 + int(m.group(4)) + int(m.group(5)) / 1000.0
|
||||
if ts < prev_ts:
|
||||
fail(errors, seg_no, f"timestamp on [Shot {n}] goes backwards")
|
||||
prev_ts = ts
|
||||
elif n > 1:
|
||||
fail(errors, seg_no, f"[Shot {n}] must carry an 'At MM:SS.mmm' timestamp")
|
||||
if not shots:
|
||||
fail(errors, seg_no, "detailed_description contains no [Shot N] block")
|
||||
|
||||
return defined, has_audio
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser(description=__doc__,
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter)
|
||||
ap.add_argument("--segments", required=True)
|
||||
ap.add_argument("--expected-n", type=int, default=None)
|
||||
ap.add_argument("--dir", default=".", help="directory containing Image-N.json files")
|
||||
ap.add_argument("--manifest", default=None, help="default: <dir>/image-map.txt")
|
||||
ap.add_argument("--lyrics-file", default=None)
|
||||
ap.add_argument("--expect-audio", action="store_true",
|
||||
help="fail unless at least one segment references <Audio>")
|
||||
args = ap.parse_args()
|
||||
|
||||
errors = []
|
||||
seg_path = Path(args.segments)
|
||||
if not seg_path.exists():
|
||||
print(f"FAIL: {seg_path} not found")
|
||||
return 1
|
||||
raw = seg_path.read_text(encoding="utf-8")
|
||||
|
||||
parts = raw.split("|")
|
||||
n = len(parts)
|
||||
if args.expected_n is not None and n != args.expected_n:
|
||||
errors.append(f"segments.txt has {n} segments, expected {args.expected_n}")
|
||||
if raw.endswith("|") or raw.startswith("|"):
|
||||
errors.append("segments.txt must not start or end with a '|' separator")
|
||||
for i, part in enumerate(parts, 1):
|
||||
if not part.strip():
|
||||
errors.append(f"segment {i} is empty")
|
||||
|
||||
subjects, audio_flags = set(), []
|
||||
for i, part in enumerate(parts, 1):
|
||||
defined, has_audio = check_segment(part.strip(), i, errors)
|
||||
subjects |= defined
|
||||
audio_flags.append(has_audio)
|
||||
|
||||
if "<Video" in raw:
|
||||
errors.append("segments.txt contains a <Video> label; this skill never uses "
|
||||
"video references")
|
||||
|
||||
all_nums = set(int(x) for x in SUBJECT_RE.findall(raw))
|
||||
if all_nums and all_nums != set(range(1, max(all_nums) + 1)):
|
||||
errors.append(f"global Subject numbering must be gapless 1..{max(all_nums)} "
|
||||
f"(found {sorted(all_nums)})")
|
||||
|
||||
# Manifest
|
||||
manifest_path = Path(args.manifest) if args.manifest else Path(args.dir) / "image-map.txt"
|
||||
mapping = {}
|
||||
if not manifest_path.exists():
|
||||
errors.append(f"manifest not found: {manifest_path}")
|
||||
else:
|
||||
for ln_no, line in enumerate(manifest_path.read_text(encoding="utf-8")
|
||||
.splitlines(), 1):
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
m = re.match(r"^Subject (\d+) - (.+)$", line)
|
||||
if not m:
|
||||
errors.append(f"manifest line {ln_no} does not match "
|
||||
f"'Subject N - file': {line}")
|
||||
continue
|
||||
num, fname = int(m.group(1)), m.group(2).strip()
|
||||
if num in mapping:
|
||||
errors.append(f"manifest lists Subject {num} twice")
|
||||
mapping[num] = fname
|
||||
|
||||
for num in sorted(all_nums):
|
||||
if num not in mapping:
|
||||
errors.append(f"Subject {num} has no manifest line")
|
||||
|
||||
out_dir = Path(args.dir)
|
||||
if out_dir.exists():
|
||||
orphans = {p.name for p in out_dir.glob("Image-*.json")} - {
|
||||
f for f in mapping.values() if re.fullmatch(r"Image-\d+\.json", f)
|
||||
}
|
||||
if orphans:
|
||||
errors.append(f"orphan Image-*.json files not listed in the manifest: "
|
||||
f"{sorted(orphans)}")
|
||||
|
||||
for num, fname in sorted(mapping.items()):
|
||||
if re.fullmatch(r"Image-\d+\.json", fname):
|
||||
m = re.fullmatch(r"Image-(\d+)\.json", fname)
|
||||
if m and int(m.group(1)) != num:
|
||||
errors.append(f"manifest maps Subject {num} to {fname}; the sheet "
|
||||
f"number must follow the subject number")
|
||||
fpath = out_dir / fname
|
||||
if not fpath.exists():
|
||||
errors.append(f"generated sheet missing: {fpath}")
|
||||
continue
|
||||
try:
|
||||
obj = json.loads(fpath.read_text(encoding="utf-8"))
|
||||
except json.JSONDecodeError as e:
|
||||
errors.append(f"{fname} is not valid JSON: {e}")
|
||||
continue
|
||||
if set(obj.keys()) != {"expanded_caption", "aspect_ratio"}:
|
||||
errors.append(f"{fname} must have exactly the two keys "
|
||||
f"expanded_caption and aspect_ratio (found "
|
||||
f"{sorted(obj.keys())})")
|
||||
continue
|
||||
if obj["aspect_ratio"] != "16:9":
|
||||
errors.append(f"{fname} aspect_ratio must be \"16:9\" "
|
||||
f"(found {obj['aspect_ratio']!r})")
|
||||
if not isinstance(obj["expanded_caption"], str) or \
|
||||
len(obj["expanded_caption"].strip()) < 40:
|
||||
errors.append(f"{fname} expanded_caption is missing or too short")
|
||||
|
||||
# Lyrics must never appear
|
||||
if args.lyrics_file:
|
||||
lpath = Path(args.lyrics_file)
|
||||
if not lpath.exists():
|
||||
errors.append(f"lyrics file not found: {lpath}")
|
||||
else:
|
||||
norm_raw = normalize(raw)
|
||||
for line in lpath.read_text(encoding="utf-8").splitlines():
|
||||
words = normalize(line)
|
||||
if len(words.split()) >= 4 and words in norm_raw:
|
||||
errors.append(f"lyric line leaked into the prompts: "
|
||||
f"{words[:60]}...")
|
||||
|
||||
if args.expect_audio and not any(audio_flags):
|
||||
errors.append("no segment references <Audio>; --expect-audio was set")
|
||||
|
||||
if errors:
|
||||
print(f"FAIL: {len(errors)} problem(s)")
|
||||
for e in errors:
|
||||
print(f" - {e}")
|
||||
return 1
|
||||
print(f"PASS: {n} segment(s), subjects {sorted(subjects)}, "
|
||||
f"audio={'yes' if any(audio_flags) else 'no'}")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
Loading…
Reference in New Issue
Block a user