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), [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 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 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 ### 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_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_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 | | `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 | | `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`) | | `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` | | `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 ```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 .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 shot 3 id='greenhouse_delivery' raw=362 delivered=340 steps=20
total delivered: 1042 frames = 43.42s total delivered: 1042 frames = 43.42s
wrote plan.json - paste its full contents into plan_json_input 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 Two deliverables: **`clips/clip_01.json`, `clip_02.json`, `clip_03.json`** — one
with their three-line prompts and durations (full file: 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`). `h3_agent_workflow_examples/plan.json`).
**6. Render.** Paste the full contents of `plan.json` into the Production Plan node's **6. Render the multi-clip video (the main use).** For each clip in order: paste the full
`plan_json_input` (a non-empty connected value overrides the visual editor's plan for that contents of `clips/clip_NN.json` into the Production Plan node's `plan_json_input`, queue
run), set the Plan node's width/height widgets, and wire the width/height outputs into the one render, save the output — then stitch the clips in order in any editor. Every clip
conditioning node and sampler latent. You get three 15-second scenes — the first plays in renders at its FULL duration (three 15-second scenes = 45 seconds of footage; the chain
full, each later scene loses ~1 second to overlap trimming — 1042 delivered frames ≈ 43.4 s overlap trim does not apply to independent clips), and because every description opens
at 24 fps. Want scene 2 different? Just tell the agent "rewrite scene 2, keep everything mid-motion and ends mid-action, the cuts read as one continuous take.
else": it rewrites only `scene_02.json`, re-validates, and re-merges.
*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 ### 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 # 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/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 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: Smoke test with the shipped examples:
@ -188,12 +211,14 @@ Smoke test with the shipped examples:
### Wiring the result ### Wiring the result
Paste the full contents of `plan.json` into the Plan node's forced STRING input For a **multi-clip video**, render one clip at a time: paste the full contents of
**`plan_json_input`** — a non-empty connected value overrides the visual editor's plan and `clips/clip_NN.json` into the Plan node's forced STRING input **`plan_json_input`** (a
receives identical normalization/validation. Resolution, context length, audio mode, and non-empty connected value overrides the visual editor's plan for that run), queue, save,
`base_seed` stay on the node's own widgets (the JSON cannot set them; default canvas is next clip — then stitch in order. For a **single continuous take**, paste `plan.json`
960×544 — set width/height widgets and wire the width/height outputs into the conditioning instead and render once. Resolution, context length, audio mode, and `base_seed` stay on
node and sampler latent to avoid square output). 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 ### 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: Never write the plan JSON by hand and never edit fragment prose during the merge. Run:
```sh ```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 .venv\Scripts\python.exe h3-plan-gate/build_plan.py --check plan.json
``` ```
The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, and validates The merger strips `_handoff`, injects `"prompt_prefix": [""]` and `defaults`, validates
everything. Report the delivered frames/seconds it prints. 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 Report the delivered frames/seconds it prints.
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 ## Step 4 — Deliver (multi-clip is the default goal)
the conditioning node and sampler latent or the video can come out square.
**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) ## 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 ## Revising one scene
Rewrite that `scene_NN.json` (keep its id and duration from the outline), re-validate it 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) ## 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. (replicated in verify_plan_rules.py) before anything is written.
Usage: 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 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 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 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 its "scenes" key. When present, fragment ids, durations, and dialogue are checked
against it in order. Fenced markdown JSON (```json ... ```) also parses. against it in order. Fenced markdown JSON (```json ... ```) also parses.
@ -66,6 +72,9 @@ def main():
help="defaults.steps when no outline is given") help="defaults.steps when no outline is given")
ap.add_argument("--check", metavar="PLAN", default=None, ap.add_argument("--check", metavar="PLAN", default=None,
help="validate an existing plan JSON and exit") 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() args = ap.parse_args()
if args.check: if args.check:
@ -136,6 +145,21 @@ def main():
else: else:
print("\n" + out_text) 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__": if __name__ == "__main__":
main() main()