MM-prompter/references/segmented-output-format.md

95 lines
5.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Segmented Output Format (one segment.txt per segment, optional)
An adaptation of the ref2va format (`references/ref2va-segment-format.md`) for tools
that consume one prompt file per segment instead of one joined file. Opt in only when
the user asks for it (phrases like "each segment gets its own segment.txt", "one file
per segment", "@Picture1", "@Audio1"). Everything not changed below is exactly the
ref2va format — same six sections, same summary prefixes, same audio template and
lip-sync phrase, same shot rules, same sheets, frame prompts, and manifest. Never mix
formats in one run.
## 1. What changes vs ref2va
| | ref2va (default) | segmented (opt-in) |
| --- | --- | --- |
| Output files | one `segments.txt`, n segments joined by bare `\|` | n files: `segment-1/segment.txt`, `segment-2/segment.txt`, ... |
| `\|` separators | exactly n−1, bare | none — the `\|` character never appears in any segment file |
| Reference tokens | `<Picture 1>`, `<Audio 1>` | `@Picture1`, `@Audio1` |
| Subject tokens | `<Subject N>` | `<Subject N>` — unchanged |
| Segment content | ref2va single-segment format | identical, one document per file |
## 2. File layout
One folder per segment, each containing a file named exactly `segment.txt`:
```
segment-1/segment.txt
segment-2/segment.txt
...
segment-n/segment.txt
```
`segment-N/segment.txt` holds segment N's ref2va document, stripped of leading and
trailing whitespace. Folder numbers start at 1 with no gaps and no extra
`segment-*` folders. No combined `segments.txt` is written in this mode.
## 3. Reference token syntax
Convert every reference token to its @-form — same number, no space, no angle
brackets:
- `<Picture N>` → `@PictureN` (example: `<Picture 1>` → `@Picture1`)
- `<Audio N>` → `@AudioN` (example: `<Audio 1>` → `@Audio1`)
The conversion applies everywhere the token appears: the `subject_definitions`
citations and audio definition line, `summary`, `retention_analysis` (including the
`fully_copy` line), and the lip-sync phrase inside `detailed_description`. Examples:
- `<Audio 1> is the user-supplied song file "midnight.mp3", ...` →
`@Audio1 is the user-supplied song file "midnight.mp3", ...`
- `<Subject 1> lips are synced to the audio in <Audio 1>` →
`<Subject 1> lips are synced to the audio in @Audio1`
- `<Audio 1>: fully_copy - <Audio 1> is reused 1:1 as the target video's complete
final audio track.` → `@Audio1: fully_copy - @Audio1 is reused 1:1 as the target
video's complete final audio track.`
`<Subject N>` is NOT converted: never write `@SubjectN`. The angle-bracket forms
`<Picture ...>` and `<Audio ...>` must not appear anywhere in a segmented file.
## 4. Numbering
Subject and Picture numbering stays global across the whole video (1..M, gapless when
all segment files are taken together), exactly as in ref2va; each file defines only
the subjects that appear in it, using their global numbers. `Image-N.json` sheets and
`image-map.txt` are unchanged, and `@PictureN` still corresponds to the sheet mapped
to Subject N.
## 5. Worked micro-example
Segment 1 of the desert project (full end-to-end example in
`references/worked-example.md`) as `segment-1/segment.txt` — identical ref2va text,
tokens converted:
```text
subject_definitions:
<Subject 1> is the astronaut in @Picture1, 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 @Picture2, 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 @Picture1 and <Subject 2>'s shell and lens come from @Picture2.
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
```