track-gate: the txt IS the pipeline - segment fragments are now plain text (segment_NN.txt = the scene prompt verbatim + one '# handoff:' line; the approved outline row supplies id, frames, modes and images, so nothing is retyped and the old verbatim-copy failures cannot happen by construction) and the merge writes ONE file by default: prompt_override.txt for zero-media stories, prompt_override.json for stories with media (tokens are JSON-only); plan.json + track_data.json only behind --plan (the 5B patch path), prompt_override.json behind --json for zero-media continuity modes/locks. verify_track_rules gains fragment_from_text/load_text_fragment/load_fragment_any (reusing validate_fragment + prompt_rules + _check_override_refs stray-token logic on the synthesized fragment; rejects |, hand-written [start-end] markers, @, and zero-media <Picture N>) and the segment command takes .txt or .json in every position incl. --prev; 11 new suite cases, 57/57. SKILL.md/README flipped: outline.json is the only JSON the default flow ever writes; the full JSON fragment is demoted to the variant-b / custom-system-prompt escape hatch; examples/ swaps the three JSON segments + track_data.json for the Sam story's segment_01-03.txt. Proven end to end: outline_sam_park.json + the three txt fragments merge to ONE file byte-identical to the proven prompt_override_r2v_refmod.txt paste

This commit is contained in:
Z User 2026-11-03 01:58:03 +00:00
parent 3587e676fa
commit 55e4b27385
11 changed files with 506 additions and 438 deletions

View File

@ -1,30 +1,33 @@
# Easy-Media Track Gate # Easy-Media Track Gate
A portable, self-contained agent skill that turns a video idea into a **validated MultiTrack A portable, self-contained agent skill that turns a video idea into a **validated
patch plan** for the ComfyUI-Easy-Media nodes (`easy multiTrackEditor` + `prompt_override` paste** for the ComfyUI-Easy-Media nodes (`easy multiTrackEditor`),
`easy multitrackProject`), built with the same outline → approval → one-segment-per-turn → built with the same outline → approval → one-segment-per-turn → merge → gate flow as
merge → gate flow as `h3-plan-gate`, adapted to the Easy-Media multitrack schema. `h3-plan-gate`, adapted to the Easy-Media multitrack schema.
The PRIMARY deliverable is a **plain-text `prompt_override` paste** (`prompt_override.txt`: The deliverable is a **plain-text `prompt_override` paste** (`prompt_override.txt`: the
the scene prompts joined with `|` on one line, `[start-end(,type)]` markers where scene scene prompts joined with `|` on one line, `[start-end(,type)]` markers where scene
lengths differ or a scene is not t2v) for the `easy multiTrackEditor` node's lengths differ or a scene is not t2v) for the `easy multiTrackEditor` node's
`prompt_override` input (format `MiniMax`) — the editor splits on pipes and renders one `prompt_override` input (format `MiniMax`) — the editor splits on pipes and renders one
clip per scene, no JSON needed. `prompt_override.json` (a `minimax_prompt_override` clip per scene, no JSON needed. The segment files the agent writes on the way there are
payload) is the option for what plain text cannot carry (`<Picture N>` media tokens, plain text too (`segment_NN.txt`: the scene prompt verbatim + one `# handoff:` line; the
continuity modes, track locks), and `plan.json` is the whole-workflow alternative applied approved outline row supplies id, frames, modes and images). JSON appears only where plain
by the node pack's own `skills/easy-media-multitrack-workflow/scripts/patch_workflow.py text cannot reach: `prompt_override.json` (a `minimax_prompt_override` payload — written
apply`. automatically for stories with media, or with `--json` for continuity modes / track
locks) and `plan.json` (`--plan`, the whole-workflow alternative applied by the node
pack's own `skills/easy-media-multitrack-workflow/scripts/patch_workflow.py apply`).
## What the gate enforces ## What the gate enforces
| Layer | Check | | Layer | Check |
| --- | --- | | --- | --- |
| Schema | Mirrors every check of the node pack's `patch_workflow.py` at apply time: track/segment ids, sorting, overlap, frame ranges, media `source_type`↔field matching, ≤ 9 images per task, continuity enum, one locked audio + one locked video max, locked-media coverage of task ranges, shared-reference rules, DynamicCombo resolution tokens, project fields — so a plan that passes here cannot be rejected there for schema reasons | | Schema | Mirrors every check of the node pack's `patch_workflow.py` at apply time: track/segment ids, sorting, overlap, frame ranges, media `source_type`↔field matching, ≤ 9 images per task, continuity enum, one locked audio + one locked video max, locked-media coverage of task ranges, shared-reference rules, DynamicCombo resolution tokens, project fields — so a plan that passes here cannot be rejected there for schema reasons |
| Outline pins | Each segment's id, start/end frames (`round(seconds × fps)`), `task_mode`, `continuity_mode` and reference-image set are diffed against the approved guide at the segment turn AND again at the merge | | Outline pins | Each segment's id, start/end frames (`round(seconds × fps)`), `task_mode`, `continuity_mode` and reference-image set come FROM the approved guide row when a plain-text fragment is loaded — nothing is retyped, so they cannot drift; JSON fragments are diffed against the row at the segment turn AND again at the merge |
| Verbatim media contract | Every `file_path` in fragments and locked tracks must be a character-for-character copy of the outline's `media_inventory` entry (the same discipline `h3-plan-gate` applies to refmods; a retyped path fails with a closest-match hint) | | Verbatim media contract | Media paths are typed only in the outline's `media_inventory`: plain-text fragments cannot carry paths at all, and locked tracks are built straight from the outline (a retyped JSON-fragment path fails with a closest-match hint) |
| Context prompt rules | Self-contained prompts in every mode (no "same as before"); context/context_drift joins must open by keeping the delivered tail and must not open with a new composition; a join followed by another join must not end at rest | | Context prompt rules | Self-contained prompts in every mode (no "same as before"); context/context_drift joins must open by keeping the delivered tail and must not open with a new composition; a join followed by another join must not end at rest |
| Drift discipline | `context_drift` is all-or-nothing across the task range (first segment included), with the consecutive 10-second split unless the user pinned lengths | | Drift discipline | `context_drift` is all-or-nothing across the task range (first segment included), with the consecutive 10-second split unless the user pinned lengths |
| Paste payload | `prompt_override` re-checked against the guide in BOTH forms: plain text (scene count/order, `[s-e,type]` markers vs the approved row frames and task types, `@imageN/@audioN/@videoN` refs vs the inventory, `<Picture N>` and stray `@` rejected) and JSON payload (durations, generation/continuity modes, exact `<Picture N>` sets, track locks) | | Paste payload | `prompt_override` re-checked against the guide in BOTH forms: plain text (scene count/order, `[s-e,type]` markers vs the approved row frames and task types, `@imageN/@audioN/@videoN` refs vs the inventory, `<Picture N>` and stray `@` rejected) and JSON payload (durations, generation/continuity modes, exact `<Picture N>` sets, track locks) |
| Fragment hygiene | Plain-text segment files reject `|` (would split the paste), hand-written `[start-end]` markers (the merge appends them), `@` (the editor strips it) and, on zero-media stories, `<Picture N>` tokens (JSON-only); the `# handoff:` line must describe the real final frame (15+ words) |
## Folder ## Folder
@ -33,13 +36,16 @@ easy-media-track-gate/
├── SKILL.md agent procedure (the entry point) ├── SKILL.md agent procedure (the entry point)
├── README.md this file ├── README.md this file
├── verify_track_rules.py the gate: outline / segment / trackdata / plan / override / suite ├── verify_track_rules.py the gate: outline / segment / trackdata / plan / override / suite
├── build_track_plan.py merge fragments → prompt_override.txt/.json + TRACK_DATA + patch plan.json ├── build_track_plan.py merge fragments → the paste (prompt_override.txt, or .json for
│ media stories); --plan adds plan.json + track_data.json
├── references/ ├── references/
│ └── track-schema.md English translation of the node pack's Chinese │ └── track-schema.md English translation of the node pack's Chinese
│ multitrack-schema.md (all field names preserved) │ multitrack-schema.md (all field names preserved)
└── examples/ worked 3-segment example: outline, segments, plan, track_data, └── examples/ worked 3-segment r2v example: outline_sam_park.json, the
paste payloads (prompt_override.json + the plain-text plain-text segment_01–03.txt fragments, and the paste they
prompt_override_r2v_refmod.txt with its outline_sam_park.json) merge into (prompt_override_r2v_refmod.txt); plus a media-story
guide (outline.json), its JSON payload (prompt_override.json)
and the patch-plan shape (plan.json)
``` ```
Standard library only; Windows-first (`py -3`), runs anywhere Python 3.8+ lives. Standard library only; Windows-first (`py -3`), runs anywhere Python 3.8+ lives.
@ -63,20 +69,20 @@ its plan input and defers execution to it.
:: smoke test :: smoke test
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py"
:: validate a guide / one segment / the merged plan :: validate a guide / one plain-text segment
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_01.json --index 1 --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_01.txt --index 1 --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.json --index 2 --prev segment_01.json --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.txt --index 2 --prev segment_01.txt --outline outline.json
:: merge everything (writes prompt_override.txt + prompt_override.json + plan.json + track_data.json) :: merge to the deliverable (writes ONLY the paste: prompt_override.txt for zero-media
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.json segment_02.json segment_03.json -o plan.json :: stories, prompt_override.json when the story has media; --json / --plan add the rest)
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt
:: validate the paste payloads (plain text is the default form; JSON the option) :: validate the paste
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.json --outline outline.json
:: apply with the node pack's own script (dry-run, then write) :: optional: patch plan for the node pack's own script (dry-run, then write)
py -3 <ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt --plan plan.json
py -3 <ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json --output RESULT.json --write py -3 <ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py apply WORKFLOW.json --plan plan.json --output RESULT.json --write
``` ```

View File

@ -13,23 +13,26 @@ description: Turn a video idea into a validated MultiTrack plan for ComfyUI-Easy
# Easy-Media Track Gate — agent procedure # Easy-Media Track Gate — agent procedure
Goal: produce a validated plan for the `easy multiTrackEditor` node in five moves: the user Goal: produce the `prompt_override` paste for the `easy multiTrackEditor` node in five
gives a video idea and a segment count (or an existing workflow to edit) → you build a moves: the user gives a video idea and a segment count (or an existing workflow to edit) →
timeline guide (`outline.json`) and show it for **approval** → with the approved guide you you build a timeline guide (`outline.json` — the ONLY JSON the default flow ever writes)
compose the task segments one at a time (about 10 seconds each), each turn existing so that and show it for **approval** → with the approved guide you compose the task segments one
ONE segment gets a complete prompt, the right references and the right continuity mode → at a time (about 10 seconds each) as PLAIN TEXT files (`segment_01.txt`, …): each file is
the scripts verify schema, timing and continuity across the whole chain → ONE scene's complete prompt plus a one-line `# handoff:` note — no ids, no frames, no
`build_track_plan.py` assembles the deliverables at the end. The PRIMARY deliverable is media paths, no JSON, because the approved outline row supplies all of that → the scripts
verify timing, continuity and prompt craft across the whole chain →
`build_track_plan.py` merges the fragments and writes the deliverable. The deliverable is
`prompt_override.txt` — PLAIN TEXT, the scene prompts joined with `|` on one line (the `prompt_override.txt` — PLAIN TEXT, the scene prompts joined with `|` on one line (the
editor splits on pipes; no JSON), which the user pastes into the multitrack editor node's editor splits on pipes; no JSON), which the user pastes into the multitrack editor node's
`prompt_override` input (format `MiniMax`) — the editor then renders one clip per scene, `prompt_override` input (format `MiniMax`) — the editor then renders one clip per scene,
chained back-to-back. The merge adds `[start-end]` / `[start-end,type]` markers per scene chained back-to-back. The merge adds `[start-end]` / `[start-end,type]` markers per scene
when the story needs them (unequal lengths, or a scene that is not the plain-text default when the story needs them (unequal lengths, or a scene that is not the plain-text default
t2v — e.g. r2v). `prompt_override.json` (a `minimax_prompt_override` payload) is the t2v — e.g. r2v). `prompt_override.json` (a `minimax_prompt_override` payload) exists only
OPTION for what plain text cannot carry: `<Picture N>`/`<Audio N>`/`<Video N>` media for what plain text cannot carry: `<Picture N>`/`<Audio N>`/`<Video N>` media tokens
tokens, per-segment continuity modes, track locks. The patch plan (`plan.json` for the (stories with media — the merge writes it automatically then), per-segment continuity
node pack's `patch_workflow.py`) is the optional whole-workflow alternative. Never deliver modes or track locks (`--json`). The patch plan (`plan.json` via `--plan` for the node
a plan that did not pass validation, and never compose a segment from a guide the user has pack's `patch_workflow.py`) is the optional whole-workflow alternative. Never deliver a
paste that did not pass validation, and never compose a segment from a guide the user has
not approved. Never hand the user any other JSON as the paste: a non- not approved. Never hand the user any other JSON as the paste: a non-
`minimax_prompt_override` value in `prompt_override` falls back to the editor's `minimax_prompt_override` value in `prompt_override` falls back to the editor's
`|`-separated text parser and renders the whole story as ONE clip over the entire `|`-separated text parser and renders the whole story as ONE clip over the entire
@ -43,9 +46,10 @@ timeline — and never put `|` inside a scene prompt for the same reason.
example all live in SKILL_DIR, not in the working folder. Every command below uses the example all live in SKILL_DIR, not in the working folder. Every command below uses the
Windows default install path; substitute your real SKILL_DIR if it differs. Windows default install path; substitute your real SKILL_DIR if it differs.
- Work in the user's **working folder** (the folder open in the editor). Write generated - Work in the user's **working folder** (the folder open in the editor). Write generated
files there: `outline.json`, `segment_01.json`, `segment_02.json`, …, `plan.json`, files there: `outline.json`, `segment_01.txt`, `segment_02.txt`, …, and the merge's
`track_data.json`, `prompt_override.txt`, `prompt_override.json`. Never write generated `prompt_override.txt` — that is the whole default set. `prompt_override.json` appears
files into SKILL_DIR. for stories with media (or with `--json`), `plan.json`/`track_data.json` only with
`--plan`. Never write generated files into SKILL_DIR.
- Python command: Windows `py -3` (or `python`); macOS/Linux `python3`. If the working - Python command: Windows `py -3` (or `python`); macOS/Linux `python3`. If the working
folder has a `.venv`, its interpreter works too (`.venv\Scripts\python.exe`). The scripts folder has a `.venv`, its interpreter works too (`.venv\Scripts\python.exe`). The scripts
need only the Python standard library — nothing to install. need only the Python standard library — nothing to install.
@ -53,16 +57,17 @@ timeline — and never put `|` inside a scene prompt for the same reason.
SKILL_DIR is missing files, stop and tell the user the skill folder is incomplete. SKILL_DIR is missing files, stop and tell the user the skill folder is incomplete.
- **Never read `verify_track_rules.py`** — run it and work from its printed output. Cline's - **Never read `verify_track_rules.py`** — run it and work from its printed output. Cline's
read_file is capped by hard-coded budgets that do NOT grow with the model's context read_file is capped by hard-coded budgets that do NOT grow with the model's context
window: about 48,000 characters per read, 2,000 lines per read. The 81 KB validator window: about 48,000 characters per read, 2,000 lines per read. The ~110 KB validator
arrives cut no matter how large the context window is. A truncation notice is Cline's arrives cut no matter how large the context window is. A truncation notice is Cline's
read cap, not repo corruption — do not "fix" truncated files. `build_track_plan.py` read cap, not repo corruption — do not "fix" truncated files. `build_track_plan.py`
(~10 KB) and `references/track-schema.md` (~26 KB) are safe to read whole. (~15 KB) and `references/track-schema.md` (~26 KB) are safe to read whole.
- **Never read back `plan.json`, `track_data.json`, `prompt_override.txt` or - **Never read back `prompt_override.txt`, `prompt_override.json`, `plan.json` or
`prompt_override.json` once real segments exist** — a 10-segment plan passes the read `track_data.json` once real segments exist** — a 10-segment plan passes the read caps
caps today and exceeds them tomorrow. Validate with `--check` / the `override` command today and exceeds them tomorrow. Validate with the `segment` / `override` commands (the
(it takes BOTH the `.txt` paste and the `.json` payload) and trust the one-line OK `override` command takes BOTH the `.txt` paste and the `.json` payload) and trust the
summary; the shipped `examples/prompt_override_r2v_refmod.txt` (7 KB, the worked one-line OK summary; the shipped `examples/segment_01.txt`–`segment_03.txt` (the worked
plain-text paste), `examples/outline_sam_park.json` (its guide), plain-text fragments), `examples/outline_sam_park.json` (their guide),
`examples/prompt_override_r2v_refmod.txt` (the paste those fragments merge into),
`examples/prompt_override.json` (2.5 KB) and `examples/plan.json` (6.8 KB) are safe to `examples/prompt_override.json` (2.5 KB) and `examples/plan.json` (6.8 KB) are safe to
read if you need to see a shape. read if you need to see a shape.
- Cline's editor rejects writes over 6,000 characters ("Editor input too large"). A segment - Cline's editor rejects writes over 6,000 characters ("Editor input too large"). A segment
@ -80,15 +85,17 @@ timeline — and never put `|` inside a scene prompt for the same reason.
```sh ```sh
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" --check "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\plan.json" py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" --check "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\plan.json"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\segment_02.txt" --index 2 --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline_sam_park.json" --prev "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\segment_01.txt"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override_r2v_refmod.txt" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline_sam_park.json" py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override_r2v_refmod.txt" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline_sam_park.json"
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override.json" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline.json" py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\prompt_override.json" --outline "%USERPROFILE%\.agent\skills\easy-media-track-gate\examples\outline.json"
``` ```
Expect the suite to print `SUITE PASS (46/46 cases)`, the `--check` to print `PLAN OK` Expect the suite to print `SUITE PASS (57/57 cases)`, the `--check` to print `PLAN OK`
with `total_length 720 frames = 30.00s`, the first `override` to print `OVERRIDE OK with `total_length 720 frames = 30.00s`, the `segment` check to print `SEGMENT 2/3 OK
(plain text): 3 scenes split on '|' with [start-end,type] markers, total 30.00s at 24 fps` (plain-text fragment): butterfly_chase_miss frames [240, 480)`, the first `override` to
and the second `OVERRIDE OK (JSON payload): 3 prompts, duration 10 (default), total print `OVERRIDE OK (plain text): 3 scenes split on '|' with [start-end,type] markers,
30.00s`. total 30.00s at 24 fps` and the second `OVERRIDE OK (JSON payload): 3 prompts, duration
10 (default), total 30.00s`.
## Step 0 — Media paths come first (never invent one) ## Step 0 — Media paths come first (never invent one)
@ -112,8 +119,11 @@ asked (Step 5).
Read SKILL_DIR's `references/track-schema.md` once (safe whole-file read; it is the English Read SKILL_DIR's `references/track-schema.md` once (safe whole-file read; it is the English
translation of the node pack's Chinese schema doc). Then write `outline.json` — the guide translation of the node pack's Chinese schema doc). Then write `outline.json` — the guide
for the whole timeline — in exactly this shape (the shipped `examples/outline.json` is the for the whole timeline, and the only JSON the default flow ever writes — in exactly this
worked model): shape (the shipped `examples/outline.json` is the worked model). Everything downstream is
derived from it: frames, task types, continuity modes, images and ids all come from the
approved rows, so the outline is also the single place media paths and resolution tokens
are ever typed.
```json ```json
{ {
@ -197,63 +207,62 @@ approval. The approved guide is the contract: segments are composed from it, ids
and modes are never silently altered, and new story ideas from the user go through the and modes are never silently altered, and new story ideas from the user go through the
guide first — never straight into a segment file. guide first — never straight into a segment file.
## Step 3 — Compose the segments one at a time ## Step 3 — Compose the segments one at a time (plain text)
Work only from the approved guide. In story order: compose ONE segment file, validate it, Work only from the approved guide. In story order: compose ONE segment file, validate it,
fix it until it passes, and only then move to the next. Since you wrote the previous file fix it until it passes, and only then move to the next. Since you wrote the previous file
yourself, open it and reuse its `_handoff.end_state` as the opening state of the next yourself, open it and reuse its `# handoff:` line as the opening state of the next context
context join. Rewrite a segment as many times as it takes. If Cline rejects a write with join. Rewrite a segment as many times as it takes. If Cline rejects a write with
'Editor input too large', split it with the marker pattern from the rules above. 'Editor input too large', split it with the marker pattern from the rules above.
**Media copy rule (the one writers keep breaking):** every `file_path` in a segment's **A segment file is plain text** (`segment_01.txt`, `segment_02.txt`, …): the scene's
`images` is a character-for-character COPY of the outline's `media_inventory` path for that complete prompt, written exactly as it will sit inside the paste — multi-line section
key. Select the text in `outline.json`, copy, paste — never retype it from memory, never structure (`subject_definitions:`, `[Shot 1]`, sound cues) survives into the clip — and
fix a typo in it, never reword a folder name. The commands below pass `--outline`, so the ONE trailing `# handoff:` line naming the real final frame. No id, no frame numbers, no
validator diffs the paths against the guide and a rewrite fails the segment on the spot. task mode, no media paths, no JSON: the approved outline row supplies all of that when
The same discipline covers the resolution tokens and file names: the merge copies the scripts load the file, so none of it can be mistyped. The `# handoff:` line is the
`editor.resolution` and the locked media tracks straight from the outline, so the outline contract the next segment's join opens inside — pose, motion in progress, camera state
is the only place they are ever typed. (15+ words); it is stripped before anything reaches the model.
Each fragment is exactly this shape: ```text
subject_definitions:
```json <Subject 1> identity: Sam is a 9 year old boy with his blonde hair in pigtails …
{ summary:
"id": "from the outline row", [reference generation]
"start_frame": 0, detailed_description:
"end_frame": 240, [Shot 1] …the full scene prompt, multi-line, ending in motion…
"content": { overall_soundscape:
"media_type": "none", …
"task_mode": "ref", # handoff: Sam stands tipped onto his toes at the path's edge, both hands still reaching,
"continuity_mode": "shot", # fingers an inch short of the hovering butterfly's orange wings, the camera holding low…
"ref_image_size": "match",
"images": [
{ "id": "img-seg-one-open-1", "source_type": "input",
"file_path": "copied verbatim from the inventory", "file_name": "pose_ref.png",
"shared_reference": false }
],
"user_prompt": "the full segment prompt",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
},
"_handoff": { "end_state": "the real final frame in 2-3 sentences: pose, motion in progress, camera state" }
}
``` ```
`start_frame`/`end_frame` are computed, not guessed: `round(seconds * frame_rate)`, (The shipped `examples/segment_01.txt`–`segment_03.txt` are the worked model — the same
start inclusive, end exclusive, and they must match the approved row exactly. If the story the example paste merges from, byte-identical.)
variant is `b`, write `user_prompt_b` and leave `user_prompt` alone — never switch the
variant on your own. **What the plain-text form forbids** (the validator fails the file on the spot): no `|`
(it would split the scene in the paste), no `[start-end]` markers (the merge appends
them itself), no `@` (the editor strips it), and no `<Picture N>`/`<Audio N>`/`<Video N>`
tokens on a zero-media story (JSON-only). On a story with media the tokens are allowed
and diff-checked against the row's approved images. **Media copy rule, reduced to one
sentence:** media paths are typed ONLY in `outline.json`'s `media_inventory` — segment
files cannot carry them at all.
**JSON fragment escape hatch:** only when a segment needs `user_prompt_variant: "b"` or a
custom `system_prompt` (both rare, both user-requested) write that ONE segment as JSON —
`{"id": row id, "start_frame": row start, "end_frame": row end, "content": {"task_mode":
…, "continuity_mode": …, "images": […], "user_prompt": …}, "_handoff": {"end_state":
…}}` (full shape in `references/track-schema.md`). Frames and ids still come from the
row, and the merge takes `.txt` and `.json` fragments in any mix.
```sh ```sh
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_01.json --index 1 --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_01.txt --index 1 --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.json --index 2 --prev segment_01.json --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" segment segment_02.txt --index 2 --prev segment_01.txt --outline outline.json
``` ```
(`--total` is optional with `--outline`; `--prev` chains the previous file and enforces (`--total` is optional with `--outline`; `--prev` chains the previous file and enforces
consecutive frames `[0,240), [240,480), …` — never an extra frame at a boundary.) consecutive frames `[0,240), [240,480), …` — never an extra frame at a boundary. `.txt`
and `.json` fragments both work in every position.)
### Prompt craft rules (violations fail the validator) ### Prompt craft rules (violations fail the validator)
@ -282,48 +291,45 @@ consecutive frames `[0,240), [240,480), …` — never an extra frame at a bound
hand in a one-liner. hand in a one-liner.
- `system_prompt` stays `""` unless the user asked for one: an empty system prompt lets the - `system_prompt` stays `""` unless the user asked for one: an empty system prompt lets the
node auto-append the MiniMax reference rules for context joins; a custom one disables node auto-append the MiniMax reference rules for context joins; a custom one disables
that. that (and needs the one-segment JSON escape hatch above).
- `_handoff.end_state` must be truthful — it is the contract the next join opens inside. - The `# handoff:` line must be truthful — it is the contract the next join opens inside.
## Step 4 — Verify the chain, put it all together at the end ## Step 4 — Verify the chain, merge to the paste
Once every segment file passes, the merge is the continuity check: `build_track_plan.py` Once every segment file passes, the merge is the continuity check: `build_track_plan.py`
re-walks every fragment against the guide (ids, frames, modes, verbatim media paths, prompt re-walks every fragment against the guide (ids, frames, modes, verbatim media paths, prompt
rules, handoff chain), assembles the TRACK_DATA (task track from the fragments; the locked rules, handoff chain — all pinned by the outline rows), builds the paste from the same
master-audio / reference-video tracks built straight from the outline), computes validated fragments, and writes ONE file by default. Never write the paste by hand and
`total_length`, builds the paste payload from the same validated fragments in BOTH forms, never edit fragment prose during the merge.
and only then writes the deliverables. Never write the plan by hand and never edit
fragment prose during the merge.
```sh ```sh
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.json segment_02.json segment_03.json -o plan.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" outline.json segment_01.txt segment_02.txt segment_03.txt
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\build_track_plan.py" --check plan.json --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.txt --outline outline.json
py -3 "%USERPROFILE%\.agent\skills\easy-media-track-gate\verify_track_rules.py" override prompt_override.json --outline outline.json
``` ```
The merge writes `prompt_override.txt` (the plain-text paste — the DEFAULT deliverable for Zero-media stories get `prompt_override.txt` (the plain-text paste — THE deliverable);
zero-media stories), `prompt_override.json` (the optional per-segment payload, and the stories with media get `prompt_override.json` instead (the only form that carries
only form that carries `<Picture N>`/`<Audio N>`/`<Video N>` tokens for stories with `<Picture N>`/`<Audio N>`/`<Video N>` tokens). Two opt-ins: `--json` also writes the
media), `plan.json` (the patch plan) and `track_data.json` (pretty, for inspection), and payload for a zero-media story that needs per-segment continuity modes or track locks,
prints the delivered durations/seconds, the track list and the locked tracks. Segment, and `--plan plan.json` also writes the patch plan (plus `track_data.json` for inspection)
track and image ids are stable UUIDv5 values derived from the project title, so a re-merge for the whole-workflow patch path (Step 5B). Segment, track and image ids are stable
keeps ids consistent. Both `override` commands re-check the paste against the guide: one UUIDv5 values derived from the project title, so a re-merge keeps ids consistent. The
scene per segment in order; plain text — `[start-end]`/`[start-end,type]` markers equal `override` command re-checks the paste against the guide: one scene per segment in order;
to the approved row frames and task types (or, without markers, equal row lengths), plain text — `[start-end]`/`[start-end,type]` markers equal to the approved row frames and
@imageN/@audioN/@videoN refs matching the inventory, no `<Picture N>` (JSON-only), no task types (or, without markers, equal row lengths), @imageN/@audioN/@videoN refs matching
stray `@`, no `[number-number]` prose (the parser eats it as a frame range); JSON — the inventory, no `<Picture N>` (JSON-only), no stray `@`, no `[number-number]` prose (the
durations inside the runtime's 2–15s window and equal to the approved rows, parser eats it as a frame range); JSON — durations inside the runtime's 2–15s window and
per-segment generation/continuity modes, the exact `<Picture N>` / `<Audio N>` / equal to the approved rows, per-segment generation/continuity modes, the exact
`<Video N>` reference set per prompt (a missing token renders with no reference media; a `<Picture N>` / `<Audio N>` / `<Video N>` reference set per prompt (a missing token
stray one attaches the wrong image), and the track locks. renders with no reference media; a stray one attaches the wrong image), and the track
locks.
## Step 5 — Deliver (plain-text paste first, patch script as the alternative) ## Step 5 — Deliver (plain-text paste first, patch script as the alternative)
### 5A — Default: the plain-text `prompt_override` paste ### 5A — Default: the plain-text `prompt_override` paste
**The paste is plain text — `scene1|scene2|...` — unless the story needs the JSON option **The paste is plain text — `scene1|scene2|...` — unless the story needs the JSON option
below.** Deliver `prompt_override.txt` (the merge writes it next to the JSON): the scene below.** Deliver `prompt_override.txt` (the merge's default output): the scene
prompts joined with `|` on ONE line, one scene per pipe-chunk. The editor splits on pipes prompts joined with `|` on ONE line, one scene per pipe-chunk. The editor splits on pipes
with no JSON at all: one clip per scene, back-to-back; a trailing `|` is a no-op. Newlines with no JSON at all: one clip per scene, back-to-back; a trailing `|` is a no-op. Newlines
INSIDE a scene survive — multi-section prompt structure is fine — but `|` inside a scene INSIDE a scene survive — multi-section prompt structure is fine — but `|` inside a scene
@ -370,15 +376,17 @@ Deliver `prompt_override.txt` with these instructions:
**JSON option (`prompt_override.json`) — only for what plain text cannot carry:** **JSON option (`prompt_override.json`) — only for what plain text cannot carry:**
`<Picture N>`/`<Audio N>`/`<Video N>` media tokens (stories with images/song/reference `<Picture N>`/`<Audio N>`/`<Video N>` media tokens (stories with images/song/reference
video), per-segment continuity modes or track locks. The payload is minimal by design — video — the merge writes this payload automatically for them), per-segment continuity
the parser requires only `type` and `prompts`; optional keys appear only when non-default modes or track locks on a zero-media story (re-run the merge with `--json`). The payload
(duration is SECONDS, `generation_type` defaults to `r2v` in the pack's code) — and is is minimal by design — the parser requires only `type` and `prompts`; optional keys
self-contained: one prompt per clip, media reference tokens inside the prompts, no frame appear only when non-default (duration is SECONDS, `generation_type` defaults to `r2v` in
fields anywhere. The paste steps are the same three as above (format MiniMax; wire the the pack's code) — and is self-contained: one prompt per clip, media reference tokens
inventory's image rows into the editor's `image` input in inventory order, the master song inside the prompts, no frame fields anywhere. The paste steps are the same three as above
into `audio`, the reference video into `video` — the `<Picture N>`/`<Audio N>`/`<Video N>` (format MiniMax; wire the inventory's image rows into the editor's `image` input in
tokens resolve against those input lists positionally; clear the widget and paste the inventory order, the master song into `audio`, the reference video into `video` — the
one-line JSON), and the same `task_index`/loop wiring applies afterwards. `<Picture N>`/`<Audio N>`/`<Video N>` tokens resolve against those input lists
positionally; clear the widget and paste the one-line JSON), and the same
`task_index`/loop wiring applies afterwards.
**The paste target is the `prompt_override` input and only these two forms.** Never give **The paste target is the `prompt_override` input and only these two forms.** Never give
the user a `plan.json`, an outline, an H3 plan or any other JSON to paste there: without the user a `plan.json`, an outline, an H3 plan or any other JSON to paste there: without
@ -389,8 +397,10 @@ Never add `|` inside a scene for the same reason.
### 5B — Alternative: the node pack's patch script (whole-workflow patch) ### 5B — Alternative: the node pack's patch script (whole-workflow patch)
When the user wants the timeline written into a workflow file directly (or needs `edit` When the user wants the timeline written into a workflow file directly (or needs `edit`
task modes / extra tracks the paste payload cannot express), the deliverable is applied by task modes / extra tracks the paste payload cannot express), first produce the patch plan
the Easy-Media node pack's script — find it under the node pack folder (typically by re-running the merge with `--plan plan.json` (it also writes `track_data.json` for
inspection), then apply it with the Easy-Media node pack's script — find it under the
node pack folder (typically
`<ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py`; `<ComfyUI>\custom_nodes\ComfyUI-Easy-Media\skills\easy-media-multitrack-workflow\scripts\patch_workflow.py`;
ask the user for the path and the workflow JSON if they are not at hand): ask the user for the path and the workflow JSON if they are not at hand):
@ -415,23 +425,23 @@ the node pack's own flow (see its `references/execution-api.md`). "Queued" never
## Revising after approval ## Revising after approval
- Guide-level change (timings, beats, modes, segment count, media): update `outline.json` - Guide-level change (timings, beats, modes, segment count, media): update `outline.json`
first, show the changed rows, then rewrite only the affected segments against it and first, show the changed rows, then rewrite only the affected segment files against it
re-run the Step 4 merge so `prompt_override.txt`, `prompt_override.json` and `plan.json` and re-run the Step 4 merge so the paste refreshes (plus the `--json`/`--plan` outputs
refresh. when they were requested).
- One segment reads badly: rewrite that `segment_NN.json` (keep its id and frames from the - One segment reads badly: rewrite that `segment_NN.txt` (the outline row still pins its
guide), re-validate it with the `segment` command, then re-merge. Never patch id and frames), re-validate it with the `segment` command, then re-merge. Never patch
`prompt_override.txt`, `prompt_override.json` or `plan.json` directly — the merge `prompt_override.txt`, `prompt_override.json` or `plan.json` directly — the merge
rebuilds all three from the fragments every time. rebuilds the paste from the fragments every time.
## If you cannot run Python ## If you cannot run Python
Say plainly that the result skipped script validation. Follow the rules manually: copy the Say plainly that the result skipped script validation. Follow the rules manually: copy the
`examples/` shapes exactly, compute frames as `round(seconds * frame_rate)`, copy every `examples/` shapes exactly, compute frames as `round(seconds * frame_rate)`, copy every
`file_path` and resolution token by selection (never retyping), and hand-assemble the `file_path` and resolution token by selection (never retyping), and hand-assemble the
TRACK_DATA the way Step 4 describes. Hand-write the paste as plain text — scene prompts paste the way Step 4 describes. Hand-write the paste as plain text — scene prompts
joined with `|` on one line, one `[start-end(,type)]` marker at each scene end when joined with `|` on one line, one `[start-end(,type)]` marker at each scene end when
lengths differ or the scene is not t2v, exactly like lengths differ or the scene is not t2v, exactly like
`examples/prompt_override_r2v_refmod.txt` — and use the JSON payload only when the story `examples/prompt_override_r2v_refmod.txt` — and use the JSON payload only when the story
needs `<Picture N>` tokens, continuity modes or locks. Manual assembly is error-prone — needs `<Picture N>` tokens, continuity modes or locks. Manual assembly is error-prone —
prefer getting Python running (any of `py -3`, `python`, a `.venv`) over hand-building prefer getting Python running (any of `py -3`, `python`, a `.venv`) over hand-building
the plan. the paste.

View File

@ -1,33 +1,35 @@
#!/usr/bin/env python3 #!/usr/bin/env python3
"""Merge approved outline + task-segment fragments into the Easy-Media MultiTrack deliverables. """Merge the approved outline + segment fragments into the prompt_override paste.
py -3 build_track_plan.py outline.json segment_01.json segment_02.json -o plan.json py -3 build_track_plan.py outline.json segment_01.txt segment_02.txt [segment_03.txt ...]
py -3 build_track_plan.py outline.json segment_01.json ... --plan plan.json
py -3 build_track_plan.py --check plan.json [--outline outline.json] py -3 build_track_plan.py --check plan.json [--outline outline.json]
The merge is the continuity check: it re-validates every fragment against the approved The deliverable is ONE paste file, plain text by default — everything else is opt-in:
outline (ids, frames, modes, verbatim media paths, context-prompt rules, handoff chain),
then assembles the deliverables from it:
1. `prompt_override.txt` — the PRIMARY paste for the `easy multiTrackEditor` node's 1. `prompt_override.txt` (default output, zero-media stories) — plain text for the
`prompt_override` input (format MiniMax): plain text, the scene prompts joined with `easy multiTrackEditor` node's `prompt_override` input (format MiniMax): the scene
' | ' on one line, plus [start-end(,type)] markers when the rows have unequal durations prompts joined with '|' on one line, plus [start-end(,type)] markers when the rows
or a scene is not the text default (flf -> t2v). The editor splits a non-JSON have unequal durations or a scene is not the text default (flf -> t2v). The editor
prompt_override on '|' — one clip per scene, no JSON needed. Zero-media stories only: splits a non-JSON prompt_override on '|' — one clip per scene, no JSON needed.
<Picture N>/<Audio N>/<Video N> tokens are NOT parsed in this path. <Picture N>/<Audio N>/<Video N> tokens are NOT parsed in this path.
2. `prompt_override.json` — the OPTION for what plain text cannot carry: the minimal 2. `prompt_override.json` — written INSTEAD of the txt when the story has media (the
{"type": "minimax_prompt_override", "prompts": [...]} payload (parser requires ONLY minimal {"type": "minimax_prompt_override", "prompts": [...]} payload with media
those two keys; duration in SECONDS, generation_type, continuity_mode and track locks tokens; parser requires ONLY type+prompts, duration in SECONDS, other keys only when
emitted only when non-default) with <Picture N>/<Audio N>/<Video N> media tokens for non-default), or alongside it with --json when a zero-media story needs per-segment
stories that have media. Paste it into the widget and queue; wire the inventory's continuity modes or track locks the text form cannot carry.
media into the editor's image/audio/video inputs in inventory order so the tokens 3. `--plan plan.json` — the optional patch plan for the node pack's
resolve. `patch_workflow.py apply` ({"editor": {..., "track_data": {...}}, "project": {...}}),
3. `plan.json` — the patch plan the node pack's `patch_workflow.py apply` consumes plus `track_data.json` (pretty, for inspection) next to it. Written only when asked.
({"editor": {..., "track_data": {...}}, "project": {...}}) for patching a whole
workflow file, plus `track_data.json` (pretty, for inspection).
Segment/track/image ids are deterministic UUIDv5 values derived from the project title, so Segment fragments are plain text (segment_NN.txt: the scene prompt verbatim + a
re-running the merge keeps ids stable. Never edit fragment prose here and never write the '# handoff:' line); the approved outline row supplies id, frames, modes and images.
plan by hand — fix the fragment, re-validate, re-merge. JSON fragments are still accepted for the rare variant-b / custom-system-prompt cases.
The merge is the continuity check: it re-validates every fragment against the outline
(ids, frames, modes, verbatim media paths, context-prompt rules, handoff chain) before
anything is written. Never edit fragment prose here and never patch the paste by hand —
fix the fragment, re-validate, re-merge. Segment/track/image ids are deterministic
UUIDv5 values derived from the project title, so re-runs keep ids stable.
Standard library only. Standard library only.
""" """
@ -192,8 +194,17 @@ def _write_json(path: Path, value: dict[str, Any]) -> None:
def _main(argv: list[str]) -> int: def _main(argv: list[str]) -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0]) parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
parser.add_argument("inputs", nargs="*", help="outline.json then segment_01.json ... (merge) or plan.json (--check)") parser.add_argument("inputs", nargs="*",
parser.add_argument("-o", "--output", default="plan.json") help="outline.json then segment_01.(txt|json) ... (merge) or plan.json (--check)")
parser.add_argument("-o", "--output", default=None,
help="the paste file (default: prompt_override.txt for zero-media "
"stories, prompt_override.json when the story has media)")
parser.add_argument("--plan", default=None, metavar="PLAN_JSON",
help="also write the patch plan (plan.json) for the node pack's "
"patch_workflow.py apply, plus track_data.json next to it")
parser.add_argument("--json", action="store_true",
help="also write prompt_override.json (the payload for continuity "
"modes / track locks the plain text cannot carry)")
parser.add_argument("--check", action="store_true", help="re-validate an existing plan.json") parser.add_argument("--check", action="store_true", help="re-validate an existing plan.json")
parser.add_argument("--outline", help="outline to re-check the plan against") parser.add_argument("--outline", help="outline to re-check the plan against")
args = parser.parse_args(argv) args = parser.parse_args(argv)
@ -211,63 +222,85 @@ def _main(argv: list[str]) -> int:
print(f"PLAN OK: {_summary(plan)}") print(f"PLAN OK: {_summary(plan)}")
return 0 return 0
if len(args.inputs) < 2: if len(args.inputs) < 2:
raise vtr.Fail("usage: build_track_plan.py outline.json segment_01.json [segment_02.json ...] -o plan.json") raise vtr.Fail("usage: build_track_plan.py outline.json segment_01.txt "
"[segment_02.txt ...] [--plan plan.json] [--json]")
outline = vtr.load_json(args.inputs[0], "outline") outline = vtr.load_json(args.inputs[0], "outline")
vtr.validate_outline(outline) vtr.validate_outline(outline)
fragments = [vtr.load_json(p, "segment fragment") for p in args.inputs[1:]] fragments = [vtr.load_fragment_any(p, outline, i)
for i, p in enumerate(args.inputs[1:], 1)]
# The merge is the continuity check: build() re-walks every fragment against
# the outline (ids, frames, modes, verbatim media paths, prompt rules, handoff
# chain) and validates the assembled TRACK_DATA — the plan object itself is
# only written when --plan asks for it.
plan = build(outline, fragments) plan = build(outline, fragments)
out_path = Path(args.output)
_write_json(out_path, plan)
_write_json(out_path.parent / "track_data.json", plan["editor"]["track_data"])
override = vtr.build_prompt_override(outline, fragments)
vtr.validate_prompt_override(copy.deepcopy(override), outline)
override_path = out_path.parent / "prompt_override.json"
override_path.write_text(
json.dumps(override, ensure_ascii=True, separators=(",", ":")) + "\n",
encoding="utf-8")
# Plain-text form — the DEFAULT paste: the prompt_override input splits on '|'
# with no JSON at all (parse_override_segments -> one segment per part). Only
# valid with zero media — <Picture N>/<Audio N>/<Video N> tokens are JSON-only;
# the text path attaches media via @imageN/@audioN/@videoN. Unequal row durations
# or non-default task types are carried by [start-end(,type)] markers, which the
# builder emits per scene (proven: [0-240,r2v] renders TYPE r2v, task-duration
# sum drives the MiniMax total).
uses_media = bool( uses_media = bool(
outline["_roles"].get("master_audio") outline["_roles"].get("master_audio")
or outline["_roles"].get("reference_video") or outline["_roles"].get("reference_video")
or any(row.get("images") for row in outline["rows"]) or any(row.get("images") for row in outline["rows"])
) )
text_path = None # Plain-text form — the DEFAULT paste: the prompt_override input splits on '|'
if not uses_media: # with no JSON at all (parse_override_segments -> one segment per part). Only
# valid with zero media — <Picture N>/<Audio N>/<Video N> tokens are JSON-only.
# Unequal row durations or non-default task types are carried by
# [start-end(,type)] markers, which the builder emits per scene (proven:
# [0-240,r2v] renders TYPE r2v, task-duration sum drives the MiniMax total).
prompts_count = len(outline["rows"])
total_s = sum(float(row["duration_seconds"]) for row in outline["rows"])
paste_path = Path(args.output) if args.output else None
json_path = None
if uses_media:
override = vtr.build_prompt_override(outline, fragments)
vtr.validate_prompt_override(copy.deepcopy(override), outline)
if paste_path is None:
paste_path = Path("prompt_override.json")
if paste_path.suffix.lower() != ".json":
raise vtr.Fail("this story has media — the paste must be the JSON payload "
"(<Picture N>/<Audio N>/<Video N> tokens are JSON-only); "
"give -o a .json path")
json_path = paste_path
json_path.write_text(
json.dumps(override, ensure_ascii=True, separators=(",", ":")) + "\n",
encoding="utf-8")
print(f"OVERRIDE OK (JSON payload): {prompts_count} prompts, "
f"duration {override.get('duration', '10 (default)')}, "
f"total {total_s:.2f}s; wrote {json_path} "
f"({json_path.stat().st_size} chars, one line)")
print("PASTE NOTE: this story has media — <Picture N>/<Audio N>/<Video N> tokens are "
"JSON-only, so the paste is prompt_override.json (the text path would leave "
"those tokens as literal prompt text)")
else:
paste_text = vtr.build_plain_text_override(outline, fragments) paste_text = vtr.build_plain_text_override(outline, fragments)
vtr.validate_prompt_override_text(paste_text, copy.deepcopy(outline)) vtr.validate_prompt_override_text(paste_text, copy.deepcopy(outline))
text_path = out_path.parent / "prompt_override.txt" if paste_path is None:
text_path.write_text(paste_text + "\n", encoding="utf-8") paste_path = Path("prompt_override.txt")
prompts = len(override["prompts"]) paste_path.write_text(paste_text + "\n", encoding="utf-8")
total_s = sum(float(row["duration_seconds"]) for row in outline["rows"]) print(f"PLAIN TEXT OK (the paste): {prompts_count} scenes split on '|', "
print(f"OVERRIDE OK: {prompts} prompts, duration {override.get('duration', '10 (default)')}, " f"total {total_s:.2f}s; wrote {paste_path} "
f"total {total_s:.2f}s; wrote {override_path} " f"({paste_path.stat().st_size} chars) — [start-end,type] markers where "
f"({override_path.stat().st_size} chars, one line)") "lengths differ or a scene is not t2v")
if args.json:
override = vtr.build_prompt_override(outline, fragments)
vtr.validate_prompt_override(copy.deepcopy(override), outline)
json_path = paste_path.parent / "prompt_override.json"
json_path.write_text(
json.dumps(override, ensure_ascii=True, separators=(",", ":")) + "\n",
encoding="utf-8")
print(f"OVERRIDE OK (JSON payload): wrote {json_path} — for per-segment "
"continuity modes / track locks the plain text cannot carry")
if args.plan:
plan_path = Path(args.plan)
_write_json(plan_path, plan)
_write_json(plan_path.parent / "track_data.json", plan["editor"]["track_data"])
print(f"PLAN OK: {_summary(plan)}") print(f"PLAN OK: {_summary(plan)}")
print(f"wrote {out_path} and {out_path.parent / 'track_data.json'}") print(f"wrote {plan_path} and {plan_path.parent / 'track_data.json'} — for the "
if text_path: "node pack's patch_workflow.py apply (dry-run first)")
print(f"PLAIN TEXT OK (the DEFAULT paste): wrote {text_path} — scenes split on '|', " print(f"deliver: paste {paste_path} into the multitrack editor's prompt_override "
f"[start-end,type] markers where lengths differ or a scene is not t2v") f"input (format {outline['editor']['format']!r})")
else:
print("PASTE NOTE: this story has media — <Picture N>/<Audio N>/<Video N> tokens are "
"JSON-only, so deliver prompt_override.json (the text path would leave those "
"tokens as literal prompt text)")
print("deliver: paste prompt_override.txt (plain text — the default for zero-media "
"stories) or prompt_override.json (media tokens / continuity modes / locks) "
"into the multitrack editor's prompt_override input (format MiniMax)")
print("NOTE: easy multiTrackTaskOutput renders ONE task segment per pass " print("NOTE: easy multiTrackTaskOutput renders ONE task segment per pass "
"(task_index, default 0 = first clip only).") "(task_index, default 0 = first clip only).")
print(" - all clips: use the pack's example_workflows/MinimaxH3_ForLoop_MultiShot.json " print(" - all clips: use the pack's example_workflows/MinimaxH3_ForLoop_MultiShot.json "
"(loop index -> task_index, PrimitiveInt -1 = all, auto-merge)") "(loop index -> task_index, PrimitiveInt -1 = all, auto-merge)")
print(f" - or queue manually with task_index 0..{prompts - 1} and join the clips") print(f" - or queue manually with task_index 0..{prompts_count - 1} and join the clips")
print("optional whole-workflow patch (dry-run first):")
print(' py -3 <ComfyUI-Easy-Media>\\skills\\easy-media-multitrack-workflow\\scripts\\patch_workflow.py apply WORKFLOW.json --plan plan.json')
print(' ... then add --output RESULT.json --write and inspect RESULT.json')
return 0 return 0
except vtr.Fail as exc: except vtr.Fail as exc:
print(f"FAIL: {exc}") print(f"FAIL: {exc}")

View File

@ -1,30 +0,0 @@
{
"id": "seg_one_open",
"start_frame": 0,
"end_frame": 240,
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "shot",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-one-open-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "Dawn light spills across an empty rooftop terrace above a hushed city. A young woman with a brown ponytail, cream cardigan over a white tee and blue jeans stands at the steel rail, matching the pose reference image for her identity only. She cradles a matte-black kettle in her right hand and tips it in one slow arc; a thread of steam rises as coffee fills the white cup in her left hand, her wrist rotating smoothly, elbow dropping as the kettle empties. She sets the kettle on the rail with a soft clink, lifts the cup, and brings it halfway to her lips as the sun's first rim crests the skyline and warms her cheek. The camera holds one slow push-in toward her profile, never cutting, while pigeon wings clap once somewhere below and the kettle's metal ticks as it cools.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
},
"_handoff": {
"end_state": "She stands at the rail with the cup halfway to her lips, wrist still rotating it inward, ponytail and cardigan hem lifted by a first light breeze, the camera mid push-in on her profile as the sun rim crests the skyline.",
"beat_used": "She pours coffee at the rooftop rail as the sun clears the skyline; ends mid-sip, city brightening."
}
}

View File

@ -0,0 +1,17 @@
subject_definitions:
<Subject 1> identity: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl; voice: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl
<Subject 2> is a small monarch butterfly with bright orange wings, black veins, black-spotted wing edges and a thin dark body
summary:
[reference generation]
retention_analysis:
<Subject 1>: fully_preserved
<Subject 2>: fully_preserved
detailed_description:
Bright photoreal park realism on a warm late morning, sunlit green lawn and pale gravel path under fresh leaf shadows, the butterfly's orange the one saturated accent in a soft natural palette.
Gentle camera kept low at the child's eye height, gliding smoothly alongside the walk.
[Shot 1] <Subject 1> strolls along the pale gravel path through the sunlit park, his arms swinging loosely at his sides, sun warm on his face, his weight rolling heel to toe over the crunching gravel with every step. The camera glides low at his eye height, one slow step behind his shoulder, then another, holding him centered as sunlit lawn and fresh leaf shadows slide past behind him, then settles as he stops. At the path's edge a small monarch butterfly with bright orange wings, black veins and black-spotted wing edges darts up out of the flower bed, crosses in front of him in two quick darts, and settles into a hover at his chest height. <Subject 1>'s right foot plants mid-stride, his arms slow and rise, and his eyes lock onto the hovering butterfly as his mouth falls open; he rises onto his toes and both small hands reach toward it, fingers spreading wide, his whole body tipping forward with the reach. The butterfly hangs in the air just out of reach, its wings opening and closing slowly while his fingertips strain closer. End mid-action: both hands still reaching, fingers an inch short of the orange wings, his weight tipped onto his toes, the camera holding the butterfly and his hands in the same frame.
overall_soundscape:
songbirds calling in the trees, a light breeze moving through the leaves, distant playground chatter, small footsteps crunching on the gravel path.
non_diegetic_music:
N/A
# handoff: Sam stands tipped onto his toes at the path's edge, both hands still reaching, fingers an inch short of the hovering butterfly's orange wings, the camera holding low at his eye height with the butterfly and his hands in the same frame.

View File

@ -1,30 +0,0 @@
{
"id": "seg_two_sip_wind",
"start_frame": 240,
"end_frame": 480,
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "context",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-two-sip-wind-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "The camera holds the same framing it arrived with, and she keeps the pose, motion and light it arrived with: the cup still traveling toward her lips, steam bending in the same breeze. Her chest rises with one slow breath, weight easing onto her left hip as the cardigan's hem starts to lift. Around the two-second mark the wind strengthens into a gust that ruffles her ponytail and snaps the cardigan open a finger's width; her fingers reclose it while she turns her face slowly into the light, eyelids narrowing. Steam tears off the cup in ribbons. The camera keeps its single slow drift leftward with no cut, the city below sharpening frame by frame, traffic swelling from hum to roar, a rooftop antenna creaking softly, her cardigan snapping in steady wind as the turn continues.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
},
"_handoff": {
"end_state": "Her face is mid-turn toward the morning light, chin still traveling, cardigan snapping in the sustained gust, cup lowered to chest height with steam tearing off it, the camera still drifting left without a cut.",
"beat_used": "Wind tugs her cardigan mid-sip; she turns her face into the light; ends still turning."
}
}

View File

@ -0,0 +1,17 @@
subject_definitions:
<Subject 1> identity: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl; voice: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl
<Subject 2> is a small monarch butterfly with bright orange wings, black veins, black-spotted wing edges and a thin dark body
summary:
[reference generation]
retention_analysis:
<Subject 1>: fully_preserved
<Subject 2>: fully_preserved
detailed_description:
Bright photoreal park realism on a warm late morning, sunlit green lawn and pale gravel path under fresh leaf shadows, the butterfly's orange the one saturated accent in a soft natural palette.
Gentle camera kept low at the child's eye height, gliding smoothly alongside the walk.
[Shot 1] Continue the same reach without resetting the motion: <Subject 1>'s fingertips close on empty air as the small monarch butterfly with bright orange wings, black veins and black-spotted wing edges snaps its wings shut, drops a hand-width, and darts away over the lawn. His planted right foot pushes off the gravel, his left foot lands on the short springy grass beyond the path's edge, grass bending flat under each landing step, and he is running, three quick strides, then four, his arms pumping at his sides. The camera picks up its low glide again and tracks after him one step, then another, keeping his back and the fluttering butterfly in the same frame. He swings his right hand in a high arc at the butterfly and misses by a hand-width; it lifts, he lunges forward, and his left hand crosses over his right to clap shut on empty air. The butterfly banks around him in a tight orange loop and rises to a hover just above his reach. He staggers to a stop, both hands still fisted around nothing, his chest heaving with quick breaths, sun warm on his upturned face; his eyebrows knot, his chin dips, and his mouth begins to pull down at the corners as his hands lower slowly to his sides. End mid-action: the butterfly hanging in a steady hover above his head, his lower lip starting to tremble, his shoulders beginning to sink.
overall_soundscape:
the same songbirds and light leaf-breeze continue as the gravel crunch gives way to a soft grass swish under running steps, quick panting breaths rise, each swipe of his hands whiffs through the air, distant playground chatter still drifting.
non_diegetic_music:
N/A
# handoff: Sam stands empty-handed on the lawn with both fists undone at his sides, the butterfly hanging in a steady hover just above his head, his lower lip starting to tremble and his shoulders beginning to sink while the camera holds at his eye height.

View File

@ -1,30 +0,0 @@
{
"id": "seg_three_city_wakes",
"start_frame": 480,
"end_frame": 720,
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "context",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-three-city-wakes-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "The join keeps everything it is handed: same framing, same breeze, the tail of her turn still in motion as her face comes level with the camera. She continues the turn until her eyes find the skyline, then lowers the cup in one unhurried arc to the rail, her shoulder rolling with the descent. Below, windows begin to light up floor by floor, a slow tide of warm rectangles climbing the tower across the street while a bus door hisses open. She exhales a long breath, steam curling off the cup in the same wind, ponytail still lifting, cardigan snapping softly. The camera keeps its slow lateral drift and never cuts; the city's morning roar builds under the song as her chest keeps rising and falling mid-breath.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
},
"_handoff": {
"end_state": "She rests the cup on the rail mid-exhale, chest still rising, ponytail lifted by the wind, the camera drifting left as windows keep lighting up across the city below.",
"beat_used": "She lowers the cup as windows light up below; ends mid-exhale, steam curling."
}
}

View File

@ -0,0 +1,17 @@
subject_definitions:
<Subject 1> identity: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl; voice: Sam is a 9 year old boy with his blonde hair in pigtails that dresses like a baby girl
<Subject 2> is a small monarch butterfly with bright orange wings, black veins, black-spotted wing edges and a thin dark body
summary:
[reference generation]
retention_analysis:
<Subject 1>: fully_preserved
<Subject 2>: fully_preserved
detailed_description:
Bright photoreal park realism on a warm late morning, sunlit green lawn and pale gravel path under fresh leaf shadows, the butterfly's orange the one saturated accent in a soft natural palette.
Gentle camera kept low at the child's eye height, gliding smoothly alongside the walk.
[Shot 1] Continue the same sinking without resetting the motion: <Subject 1>'s fists come undone at his sides, his shoulders drop the last of their fight, and his knees fold under him; he drops his weight straight down, his bottom landing on the short grass with a soft thump, both hands slapping the lawn beside him to steady himself. The camera glides one slow arc from behind his shoulder around to his front, settles at his seated eye height, and holds still. In front of him the small monarch butterfly with bright orange wings, black veins and black-spotted wing edges rises in two slow wingbeats, drifts back over the flower bed, and shrinks to a fleck of orange among the blossoms. <Subject 1> watches it go with his mouth crumpling; then his eyes squeeze shut, his mouth opens wide in the first wail, and he cries like an infant, tears spilling over his lower lashes and rolling down both cheeks, sun warm on his tear-streaked face. His right fist rubs hard across his left eye, then his left fist across his right eye, his shoulders hitching with each sob, his head tipping back on the big wails and dropping forward between them, his heels digging into the grass and pulling close to his bottom. He stays seated in the grass, crying, tears streaking to his chin, the flower bed across the lawn holding only the spot where the butterfly vanished.
overall_soundscape:
the same songbirds and light leaf-breeze continue, the grass swishing once as he sinks down, then the first wail rising over the ambience with hitching sobs carrying on, distant playground chatter still drifting.
non_diegetic_music:
N/A
# handoff: Final frame: Sam stays seated in the grass crying, tears streaking to his chin, heels pulled close to his bottom, the flower bed across the lawn holding only the spot where the butterfly vanished.

View File

@ -1,128 +0,0 @@
{
"muted": false,
"volume_db": 0,
"task_markers": [],
"task_overview": false,
"tracks": [
{
"id": "3b53d88d-07b5-5f0e-9fc0-aa87503aae80",
"name": "Tasks",
"type": "task",
"color": "var(--multitrack-task-bg)",
"muted": false,
"solo": false,
"volume_db": 0,
"locked": false,
"segments": [
{
"id": "d2c2d695-f725-56ae-9024-bf9126443256",
"start_frame": 0,
"end_frame": 240,
"color": "var(--multitrack-task-bg)",
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "shot",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-one-open-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "Dawn light spills across an empty rooftop terrace above a hushed city. A young woman with a brown ponytail, cream cardigan over a white tee and blue jeans stands at the steel rail, matching the pose reference image for her identity only. She cradles a matte-black kettle in her right hand and tips it in one slow arc; a thread of steam rises as coffee fills the white cup in her left hand, her wrist rotating smoothly, elbow dropping as the kettle empties. She sets the kettle on the rail with a soft clink, lifts the cup, and brings it halfway to her lips as the sun's first rim crests the skyline and warms her cheek. The camera holds one slow push-in toward her profile, never cutting, while pigeon wings clap once somewhere below and the kettle's metal ticks as it cools.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
}
},
{
"id": "69749e2e-3bd5-5e50-ae29-61bf607cba20",
"start_frame": 240,
"end_frame": 480,
"color": "var(--multitrack-task-bg)",
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "context",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-two-sip-wind-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "The camera holds the same framing it arrived with, and she keeps the pose, motion and light it arrived with: the cup still traveling toward her lips, steam bending in the same breeze. Her chest rises with one slow breath, weight easing onto her left hip as the cardigan's hem starts to lift. Around the two-second mark the wind strengthens into a gust that ruffles her ponytail and snaps the cardigan open a finger's width; her fingers reclose it while she turns her face slowly into the light, eyelids narrowing. Steam tears off the cup in ribbons. The camera keeps its single slow drift leftward with no cut, the city below sharpening frame by frame, traffic swelling from hum to roar, a rooftop antenna creaking softly, her cardigan snapping in steady wind as the turn continues.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
}
},
{
"id": "6d0f444e-c6b1-5d14-a3c6-a29cd594beb7",
"start_frame": 480,
"end_frame": 720,
"color": "var(--multitrack-task-bg)",
"content": {
"media_type": "none",
"task_mode": "ref",
"continuity_mode": "context",
"ref_image_size": "match",
"images": [
{
"id": "img-seg-three-city-wakes-1",
"source_type": "input",
"file_path": "codex/rooftop/pose_ref.png",
"file_name": "pose_ref.png",
"shared_reference": false
}
],
"user_prompt": "The join keeps everything it is handed: same framing, same breeze, the tail of her turn still in motion as her face comes level with the camera. She continues the turn until her eyes find the skyline, then lowers the cup in one unhurried arc to the rail, her shoulder rolling with the descent. Below, windows begin to light up floor by floor, a slow tide of warm rectangles climbing the tower across the street while a bus door hisses open. She exhales a long breath, steam curling off the cup in the same wind, ponytail still lifting, cardigan snapping softly. The camera keeps its slow lateral drift and never cuts; the city's morning roar builds under the song as her chest keeps rising and falling mid-breath.",
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": false,
"volume_db": 0
}
}
]
},
{
"id": "51945496-eaa4-5ba0-bb78-201bbfee5819",
"name": "Master Song",
"type": "audio",
"color": "var(--primary)",
"muted": false,
"solo": false,
"volume_db": 0,
"locked": false,
"audio_locked": true,
"segments": [
{
"id": "ee335ed8-75cd-5278-969f-144cba015861",
"start_frame": 0,
"end_frame": 720,
"color": "var(--primary)",
"content": {
"media_type": "audio",
"source_type": "input",
"file_path": "codex/rooftop/song.wav",
"file_name": "song.wav"
}
}
]
}
],
"total_length": 720,
"frame_rate": 24
}

View File

@ -700,7 +700,148 @@ def _row_gap(outline: dict[str, Any], index: int) -> float:
return float(outline["rows"][index - 2].get("gap_after_seconds", 0)) return float(outline["rows"][index - 2].get("gap_after_seconds", 0))
# --------------------------------------------------------------- track data # ------------------------------------------------- plain-text segment fragments
_HANDOFF_LINE_RE = re.compile(r"^#\s*handoff\s*:\s*(.*)$", re.IGNORECASE)
def fragment_from_text(outline: dict[str, Any], index: int, prompt_text: str,
handoff: str | None) -> dict[str, Any]:
"""Synthesize the minimal segment fragment from an approved outline row plus the
scene prompt text (the body of a plain-text segment_NN.txt fragment).
The row is the single source of truth: id, frames, task/continuity modes and the
image set come straight from the outline — nothing is retyped, so the classic
fragment failures (paraphrased media paths, drifting frames, swapped modes) cannot
happen by construction. Only two things are genuinely new per segment: the prompt
text and the handoff end_state. Both are prose — which is why the fragment file is
plain text, not JSON.
"""
rows = outline["rows"]
if not 1 <= index <= len(rows):
raise Fail(f"fragment index {index} is outside the outline's 1..{len(rows)} rows")
row = rows[index - 1]
where = f"txt fragment {row['id']}"
if not isinstance(prompt_text, str) or not prompt_text.strip():
raise Fail(f"{where}: the fragment file has no scene prompt text")
if "|" in prompt_text:
raise Fail(
f"{where}: the scene prompt contains '|' — it would split the scene in the "
"plain-text paste. One scene per fragment file; move the pipe out."
)
if _TEXT_MARKER_RE.search(prompt_text):
raise Fail(
f"{where}: the scene prompt contains a [start-end] marker. The merge appends "
"the markers itself; a hand-written one doubles up, and bare [number-number] "
"prose is eaten by the editor's parser as a frame range."
)
if "@" in prompt_text:
raise Fail(
f"{where}: '@' never survives to the model (the editor strips it) — media "
"rides in the JSON payload's <Picture N>/<Audio N>/<Video N> tokens, which "
"the merge builds for stories with media. Keep '@' out of scene text."
)
found_tokens = (list(_PICTURE_RE.finditer(prompt_text))
+ list(_AUDIO_RE.finditer(prompt_text))
+ list(_VIDEO_RE.finditer(prompt_text)))
if found_tokens and not outline["inventory"]:
raise Fail(
f"{where}: <Picture N>/<Audio N>/<Video N> tokens are JSON-only and this story "
"has no media inventory — the plain-text paste would leave them as literal "
"prompt text"
)
if found_tokens and outline["inventory"]:
# Stray tokens only: a MISSING token is fine here — build_prompt_override
# prepends the approved tokens idempotently when it builds the JSON payload.
positions = _override_media_positions(outline)
roles = outline["_roles"]
expected_pics = {positions[img["key"]] for img in row.get("images", [])}
allowed_audio = ({positions[roles["master_audio"]["key"]]}
if roles["master_audio"] else set())
allowed_video = ({positions[roles["reference_video"]["key"]]}
if roles["reference_video"] else set())
for m in found_tokens:
n = int(m.group(1))
if m.re is _PICTURE_RE and n not in expected_pics:
raise Fail(
f"{where}: <Picture {n}> is not one of this segment's approved images "
f"(expected {sorted(expected_pics)}); a stray token attaches the wrong "
"slot image from the editor's image input")
if m.re is _AUDIO_RE and n not in allowed_audio:
raise Fail(
f"{where}: <Audio {n}> has no locked master audio to resolve against "
f"(allowed {sorted(allowed_audio)})")
if m.re is _VIDEO_RE and n not in allowed_video:
raise Fail(
f"{where}: <Video {n}> has no locked reference video to resolve against "
f"(allowed {sorted(allowed_video)})")
if handoff is None or not str(handoff).strip():
raise Fail(
f"{where}: the fragment file must end with a '# handoff: ...' line — the real "
f"final frame in at least {END_STATE_MIN_WORDS} words (pose, motion in progress, "
"camera state). It is the contract the next segment's join opens inside."
)
frag: dict[str, Any] = {
"id": row["id"],
"start_frame": row["start_frame"],
"end_frame": row["end_frame"],
"content": {
"media_type": "none",
"task_mode": row["task_mode"],
"continuity_mode": row["continuity_mode"],
"ref_image_size": "match",
"images": [
{"id": f"img-{row['id']}-{pos}",
"source_type": outline["inventory"][img["key"]]["source_type"],
"file_path": outline["inventory"][img["key"]]["path"],
"file_name": (outline["inventory"][img["key"]].get("file_name")
or outline["inventory"][img["key"]]["path"].rsplit("/", 1)[-1]),
"shared_reference": bool(img.get("shared_reference", False))}
for pos, img in enumerate(row.get("images", []))
],
"user_prompt": prompt_text,
"system_prompt": "",
"user_prompt_variant": "a",
"user_prompt_b": "",
"muted": False,
"volume_db": 0,
},
"_handoff": {"end_state": str(handoff).strip()},
}
return frag
def load_text_fragment(path: str | Path, outline: dict[str, Any], index: int) -> dict[str, Any]:
"""Read a plain-text segment fragment file (segment_NN.txt): the scene prompt
verbatim — multi-line section structure survives — ending with ONE
'# handoff: ...' line that names the real final frame."""
raw = Path(path).read_text(encoding="utf-8")
lines = raw.rstrip().splitlines()
handoff = None
if lines:
m = _HANDOFF_LINE_RE.match(lines[-1].strip())
if m:
handoff = m.group(1).strip()
lines = lines[:-1]
prompt_text = "\n".join(lines).strip()
return fragment_from_text(outline, index, prompt_text, handoff)
def load_fragment_any(path: str | Path, outline: dict[str, Any] | None,
index: int) -> dict[str, Any]:
"""Load a segment fragment from .txt (the plain-text default; needs the outline —
the approved row supplies id, frames, modes and images) or .json (the full
fragment object, for the rare variant-b / custom-system-prompt escape hatch)."""
if str(path).lower().endswith(".txt"):
if outline is None:
raise Fail("a .txt fragment needs --outline outline.json — the approved row "
"supplies the id, frames, modes and images; the file carries only "
"the prompt text and the handoff line")
return load_text_fragment(path, outline, index)
return load_json(path, "segment fragment")
# ------------------------------------------------------------------- track data
def validate_track_data(data: dict[str, Any], *, outline: dict[str, Any] | None = None, def validate_track_data(data: dict[str, Any], *, outline: dict[str, Any] | None = None,
recalculate: bool = True, segment_start_index: int = 0, recalculate: bool = True, segment_start_index: int = 0,
@ -1766,6 +1907,48 @@ def run_embedded_suite() -> int:
bad = f"{TEXT_PROMPT_1} meet @ the pier | {TEXT_PROMPT_2}" bad = f"{TEXT_PROMPT_1} meet @ the pier | {TEXT_PROMPT_2}"
check("text override stray @ caught", False, validate_prompt_override_text, bad, text_outline) check("text override stray @ caught", False, validate_prompt_override_text, bad, text_outline)
# ---- plain-text segment fragments (segment_NN.txt: prompt body + # handoff line) ----
hand_1 = ("She is mid-stride on the wet stone pier with the rope against her hip, "
"gulls still lifting off the pilings, the first boat sliding out while "
"the camera keeps tracking beside her.")
hand_2 = ("She is running hard along the lighthouse railing, raincoat pressed flat "
"by the wind, one hand raised against the glare as the horn sounds below.")
tfrag1 = fragment_from_text(text_outline, 1, TEXT_PROMPT_1, hand_1)
tfrag2 = fragment_from_text(text_outline, 2, TEXT_PROMPT_2, hand_2)
check("txt fragment 1 example", True, validate_fragment, tfrag1, 1, 2, None, text_outline)
check("txt fragment 2 chain", True, validate_fragment, tfrag2, 2, 2, tfrag1, text_outline)
check("txt fragment pipe caught", False, fragment_from_text,
text_outline, 1, TEXT_PROMPT_1 + " | extra", hand_1)
check("txt fragment marker caught", False, fragment_from_text,
text_outline, 1, TEXT_PROMPT_1 + " [0-240]", hand_1)
check("txt fragment picture token caught", False, fragment_from_text,
text_outline, 1, TEXT_PROMPT_1 + " <Picture 1>", hand_1)
check("txt fragment stray @ caught", False, fragment_from_text,
text_outline, 1, TEXT_PROMPT_1 + " meet @ the pier", hand_1)
check("txt fragment handoff missing caught", False, fragment_from_text,
text_outline, 1, TEXT_PROMPT_1, None)
built_from_txt = build_plain_text_override(text_outline, [tfrag1, tfrag2])
check("txt fragments build the paste", True,
validate_prompt_override_text, built_from_txt, text_outline)
r2v_outline = copy.deepcopy(text_outline)
r2v_outline["rows"][0]["task_mode"] = "ref"
r2v_outline["rows"][1]["task_mode"] = "ref"
rfrag1 = fragment_from_text(r2v_outline, 1, TEXT_PROMPT_1, hand_1)
rfrag2 = fragment_from_text(r2v_outline, 2, TEXT_PROMPT_2, hand_2)
built_r2v = build_plain_text_override(r2v_outline, [rfrag1, rfrag2])
check("txt fragments r2v markers", True,
validate_prompt_override_text, built_r2v, r2v_outline)
hand_r = ("She stands mid-motion at the rail, cup halfway through its arc, "
"ponytail and cardigan lifted by the wind, camera still drifting left.")
mfrag = fragment_from_text(outline, 1, PROMPT_1 + " <Picture 1>", hand_r)
check("txt fragment media tokens ok", True, validate_fragment, mfrag, 1, 3, None, outline)
check("txt fragment stray picture caught", False, fragment_from_text,
outline, 1, PROMPT_1 + " <Picture 2>", hand_r)
failed = [c for c in cases if not c[1]] failed = [c for c in cases if not c[1]]
for name, ok, detail in cases: for name, ok, detail in cases:
if ok: if ok:
@ -1810,18 +1993,21 @@ def _main(argv: list[str]) -> int:
else: else:
positional.append(args[i]); i += 1 positional.append(args[i]); i += 1
if not positional or index is None: if not positional or index is None:
raise Fail("usage: segment SEGMENT_NN.json --index N --total T --outline outline.json [--prev segment_XX.json]") raise Fail("usage: segment SEGMENT_NN.(txt|json) --index N --outline outline.json "
frag = load_json(positional[0], "segment fragment") "[--prev segment_XX.(txt|json)] [--total T]")
outline = None
if outline_path: if outline_path:
outline = load_json(outline_path, "outline") outline = load_json(outline_path, "outline")
validate_outline(outline) validate_outline(outline)
frag = load_fragment_any(positional[0], outline, index)
if total is None and outline is not None: if total is None and outline is not None:
total = len(outline["rows"]) total = len(outline["rows"])
prev = load_json(prev_path, "previous fragment") if prev_path else None prev = (load_fragment_any(prev_path, outline, index - 1)
if prev_path else None)
validate_fragment(frag, index, total, prev, outline) validate_fragment(frag, index, total, prev, outline)
total_label = total if total is not None else "?" total_label = total if total is not None else "?"
print(f"SEGMENT {index}/{total_label} OK: {frag['id']} frames " kind = ("plain-text fragment"
if str(positional[0]).lower().endswith(".txt") else "fragment")
print(f"SEGMENT {index}/{total_label} OK ({kind}): {frag['id']} frames "
f"[{frag['start_frame']}, {frag['end_frame']})") f"[{frag['start_frame']}, {frag['end_frame']})")
return 0 return 0
if cmd == "trackdata": if cmd == "trackdata":