5.6 KiB
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:
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