Multi-clip videos as the primary deliverable: per-scene clip export

build_plan.py --clips [DIR] (default clips/) now exports one validated
single-shot plan JSON per scene (clip_01.json, ...) alongside the merged
plan. Each clip renders through plan_json_input as its own video at FULL
duration (no chain overlap trim), then the clips are stitched in order;
the mid-motion open/close craft rules make the cuts read as one take.
plan.json stays as the optional single continuous-take render.

SKILL.md Step 3/4 rewritten (merge exports clips + plan; deliver =
render-per-clip then stitch), README intro/example/wiring/validating
updated to multi-clip-first with real clip output shown. Verified from a
simulated project root: export green, every clip re-checks PLAN OK.
This commit is contained in:
Z User 2026-10-29 18:40:18 +00:00
parent a804088d72
commit 54a8271072
3 changed files with 95 additions and 30 deletions

View File

@ -7,7 +7,10 @@ Prompt set and tooling that turn a story idea into the `plan_json_input` JSON fo
[ComfyUI-MiniMaxH3-Context-Loop](https://github.com/ethanfel/ComfyUI-MiniMaxH3-Context-Loop),
verified against commit `43afeff`. The workflow is agent-shaped: one outline turn, one turn
per scene, then a validated merge — so long stories are written scene by scene and single
scenes can be regenerated without touching the rest.
scenes can be regenerated without touching the rest. The merge exports **one render-ready
JSON per scene** (`clips/clip_NN.json`) for making **multi-clip videos** — each scene is
rendered as its own clip and stitched in an editor — plus an optional merged `plan.json`
for a single continuous chain take.
### Files
@ -17,7 +20,7 @@ scenes can be regenerated without touching the rest.
| `h3_scene_agent_system_prompt.md` | Stage 1 + 2 system prompts: **PROMPT A** (outline planner) and **PROMPT B** (one-scene-per-turn writer with a `_handoff` chain) |
| `h3_plan_assembler_system_prompt.md` | Stage 3 LLM merge prompt — only when you cannot run scripts |
| `h3_plan_json_system_prompt.md` | Single-pass variant (whole plan in one turn) — fastest for 2–4 scene stories |
| `build_plan.py` | Deterministic Stage 3 merger: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing |
| `build_plan.py` | Deterministic Stage 3 merger: strips `_handoff`, injects `"prompt_prefix": [""]` + defaults, validates everything before writing; `--clips` exports one single-scene plan JSON per scene for multi-clip rendering |
| `verify_plan_rules.py` | Node-replica validator (final plans *and* per-turn fragments) with an embedded test suite |
| `count_prompt_tokens.py` | o200k token counter for the prompt fences (needs `pip install tiktoken`) |
| `h3_agent_workflow_examples/` | Worked 3-scene greenhouse-courier run: `outline.json` → `scene_01..03.json` → `plan.json` |
@ -139,10 +142,10 @@ lighting detail):
}
```
**5. The agent merges and checks** — never writing the plan JSON by hand:
**5. The agent merges, exports the clips, and checks** — never writing plan JSON by hand:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
```
@ -157,19 +160,38 @@ Merged plan:
shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s
wrote plan.json - paste its full contents into plan_json_input
clip 1/3 -> clips/clip_01.json (id=greenhouse_arrival)
shot 1 id='greenhouse_arrival' raw=362 delivered=362 steps=20
total delivered: 362 frames = 15.08s
…
clip 3/3 -> clips/clip_03.json (id=greenhouse_delivery)
shot 1 id='greenhouse_delivery' raw=362 delivered=362 steps=20
total delivered: 362 frames = 15.08s
…
wrote 3 single-scene clip plans -> clips/ - render each clip_NN.json through
plan_json_input as its own video, then stitch the clips in order
```
`plan.json` is the final artifact — `"prompt_prefix": [""]`, `"defaults"`, and three shots
with their three-line prompts and durations (full file:
Two deliverables: **`clips/clip_01.json`, `clip_02.json`, `clip_03.json`** — one
single-scene plan per clip, the input for a multi-clip video — and the merged
`plan.json` for an optional single continuous take (full file:
`h3_agent_workflow_examples/plan.json`).
**6. Render.** Paste the full contents of `plan.json` into the Production Plan node's
`plan_json_input` (a non-empty connected value overrides the visual editor's plan for that
run), set the Plan node's width/height widgets, and wire the width/height outputs into the
conditioning node and sampler latent. You get three 15-second scenes — the first plays in
full, each later scene loses ~1 second to overlap trimming — 1042 delivered frames ≈ 43.4 s
at 24 fps. Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything
else": it rewrites only `scene_02.json`, re-validates, and re-merges.
**6. Render the multi-clip video (the main use).** For each clip in order: paste the full
contents of `clips/clip_NN.json` into the Production Plan node's `plan_json_input`, queue
one render, save the output — then stitch the clips in order in any editor. Every clip
renders at its FULL duration (three 15-second scenes = 45 seconds of footage; the chain
overlap trim does not apply to independent clips), and because every description opens
mid-motion and ends mid-action, the cuts read as one continuous take.
*Alternative — one continuous take:* paste `plan.json` instead and the node renders the
whole story as a single chain video (1042 delivered frames ≈ 43.4 s at 24 fps — every
scene after the first loses ~1 second to overlap trimming).
Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything else": it
rewrites only `scene_02.json`, re-validates, and re-merges — refreshing both the clip and
the merged plan.
### Validating
@ -177,6 +199,7 @@ else": it rewrites only `scene_02.json`, re-validates, and re-merges.
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py # embedded pass/fail suite
.venv\Scripts\python.exe h3-plan-gate/verify_plan_rules.py plan plan.json # node-rule replica on a final plan
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json # same checks + frame/duration report
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check clips/clip_01.json # clips validate the same way
```
Smoke test with the shipped examples:
@ -188,12 +211,14 @@ Smoke test with the shipped examples:
### Wiring the result
Paste the full contents of `plan.json` into the Plan node's forced STRING input
**`plan_json_input`** — a non-empty connected value overrides the visual editor's plan and
receives identical normalization/validation. Resolution, context length, audio mode, and
`base_seed` stay on the node's own widgets (the JSON cannot set them; default canvas is
960×544 — set width/height widgets and wire the width/height outputs into the conditioning
node and sampler latent to avoid square output).
For a **multi-clip video**, render one clip at a time: paste the full contents of
`clips/clip_NN.json` into the Plan node's forced STRING input **`plan_json_input`** (a
non-empty connected value overrides the visual editor's plan for that run), queue, save,
next clip — then stitch in order. For a **single continuous take**, paste `plan.json`
instead and render once. Resolution, context length, audio mode, and `base_seed` stay on
the node's own widgets (the JSON cannot set them; default canvas is 960×544 — set
width/height widgets and wire the width/height outputs into the conditioning node and
sampler latent to avoid square output).
### Requirements

View File

@ -92,24 +92,39 @@ Each fragment is exactly this shape:
}
```
## Step 3 — Merge and check
## Step 3 — Merge, export clips, check
Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
```sh
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
.venv\Scripts\python.exe h3-plan-gate/build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
.venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and validates
everything. Report the delivered frames/seconds it prints.
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates
everything, and writes two deliverables:
## Step 4 — Deliver
- `clips/clip_01.json`, `clip_02.json`, … — one single-scene plan per clip. **This is the
main output: the goal is a multi-clip video**, one rendered clip per scene.
- `plan.json` — all shots in one chain plan (optional: a single continuous take instead).
Tell the user to paste the full contents of `plan.json` into the Plan node's forced STRING
input `plan_json_input`. Resolution, context length, audio mode, and `base_seed` stay on
the node's widgets — the JSON cannot set them; the width/height outputs must be wired into
the conditioning node and sampler latent or the video can come out square.
Report the delivered frames/seconds it prints.
## Step 4 — Deliver (multi-clip is the default goal)
**Multi-clip video (main use):** the user renders each scene as its own video — paste the
full contents of `clips/clip_01.json` into the Plan node's `plan_json_input`, queue one
render, save the output, then repeat with `clip_02.json`, `clip_03.json`, … — and stitches
the clips in order in any editor. Each clip renders at its FULL duration (no chain overlap
trimming), and because every description opens mid-motion and ends mid-action, the cuts
read as one continuous take.
**Continuous take (optional):** pasting `plan.json` instead renders the whole story in one
chain run; every scene after the first then loses about 1 second to overlap trimming.
Either way: resolution, context length, audio mode, and `base_seed` stay on the node's
widgets — the JSON cannot set them; the width/height outputs must be wired into the
conditioning node and sampler latent or the video can come out square.
## Craft rules for every fragment (violations fail the validator)
@ -149,7 +164,8 @@ the conditioning node and sampler latent or the video can come out square.
## Revising one scene
Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it
with the fragment command, then re-run the Step 3 merge. Never patch `plan.json` directly.
with the fragment command, then re-run the Step 3 merge so `clips/clip_NN.json` and
`plan.json` refresh together. Never patch `plan.json` or a clip file directly.
## Short stories (2–4 scenes)

26
h3-plan-gate/build_plan.py Normal file → Executable file
View File

@ -7,10 +7,16 @@ Every fragment and the merged plan are validated with the same rules the node us
(replicated in verify_plan_rules.py) before anything is written.
Usage:
python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json
python build_plan.py outline.json scene_01.json scene_02.json scene_03.json -o plan.json --clips
python build_plan.py scene_01.json scene_02.json -o plan.json [--duration 10] [--steps 20]
python build_plan.py --check plan.json # validate an existing plan file
--clips [DIR] (default dir: clips) additionally writes one single-shot plan JSON per
scene (clip_01.json, clip_02.json, ...) for MULTI-CLIP rendering: render each clip
through plan_json_input as its own video, then stitch the clips in an editor. Each
clip plays at its full duration (no chain overlap trimming). The merged plan (-o /
stdout) remains the single continuous-take render.
The outline file (from the scene agent's PROMPT A) is optional; it is auto-detected by
its "scenes" key. When present, fragment ids, durations, and dialogue are checked
against it in order. Fenced markdown JSON (```json ... ```) also parses.
@ -66,6 +72,9 @@ def main():
help="defaults.steps when no outline is given")
ap.add_argument("--check", metavar="PLAN", default=None,
help="validate an existing plan JSON and exit")
ap.add_argument("--clips", nargs="?", const="clips", default=None, metavar="DIR",
help="also write one single-shot plan JSON per scene here "
"(multi-clip rendering; default dir: clips)")
args = ap.parse_args()
if args.check:
@ -136,6 +145,21 @@ def main():
else:
print("\n" + out_text)
if args.clips:
os.makedirs(args.clips, exist_ok=True)
for i, shot in enumerate(final_shots, 1):
clip = {"prompt_prefix": [""], "defaults": dict(defaults), "shots": [shot]}
print(f"\nclip {i}/{n} -> {args.clips}/clip_{i:02d}.json "
f"(id={shot.get('id')})")
vpr.validate_plan(clip)
vpr.check_h3_sections(clip)
with open(os.path.join(args.clips, f"clip_{i:02d}.json"), "w",
encoding="utf-8") as fh:
fh.write(json.dumps(clip, indent=2, ensure_ascii=False) + "\n")
print(f"\nwrote {n} single-scene clip plans -> {args.clips}/ - render each "
f"clip_NN.json through plan_json_input as its own video, then stitch "
f"the clips in order (each clip plays at its full duration)")
if __name__ == "__main__":
main()