mmprompt/easy-media-track-gate/build_track_plan.py
Z User ea5c5a71b4 easy-media-track-gate: the h3-plan-gate methodology adapted to ComfyUI-Easy-Media multitrack nodes
Portable self-contained skill (%USERPROFILE%\.agent\skills\easy-media-track-gate\):
- references/track-schema.md: full English translation of the node pack's Chinese
  multitrack-schema.md (resolution DynamicCombo rules, time semantics, task segment
  content, context/context_drift joins, audio locks, shared media, project params,
  patch plan shape); field names cross-checked against patch_workflow.py source.
- verify_track_rules.py (66 KB, stdlib only): mirrors every check the node pack's
  patch_workflow.py performs at apply time (ids, sorting, overlap, frames, source_type
  field matching, <=9 images, continuity enums, one locked audio + one locked video,
  locked-media task coverage, shared_reference rules, resolution tokens, project
  fields) and adds the gates upstream leaves to discipline: outline pins (id/frames/
  modes/image set diffed per fragment AND at the merge), verbatim media contract
  (file_path character-for-character vs media_inventory, closest-match hint on
  rewrite), context prompt rules (self-contained in all modes, keep-then-change
  opener for joins, end-in-motion tail when another join follows), drift all-or-
  nothing + consecutive 10s split unless lengths_user_pinned. Subcommands: outline/
  segment/trackdata/plan/suite; no-outline runs stay schema-only. Embedded suite
  25 cases, prints ~0.7 KB (far under Cline's 8k cap).
- build_track_plan.py: merge re-walks every fragment against the guide, assembles
  TRACK_DATA (task track from fragments; locked master-audio/reference-video tracks
  built from the outline, never retyped), writes plan.json + track_data.json with
  stable UUIDv5 ids; --check mode re-validates.
- examples/: worked 3-segment rooftop example (outline, 3 fragments, plan.json,
  track_data.json) - merge is byte-deterministic and the generated plan dry-run-
  applies to the bundled v1.3.0 blank template with graph_preserved: true.
- SKILL.md: five-move procedure with Cline cap workarounds (never read the 66 KB
  validator, @@CONTINUE@@ split, never read back generated plans), Step 0 media
  paths (upload only on explicit request; never invent a path), approval pause,
  prompt craft rules, delivery through the node pack's own patch_workflow.py
  (dry-run -> --write to a NEW file -> inspect); queueing stays the node pack's
  own flow on explicit user request.
2026-11-01 01:09:26 +00:00

224 lines
9.0 KiB
Python

#!/usr/bin/env python3
"""Merge approved outline + task-segment fragments into the Easy-Media MultiTrack patch plan.
py -3 build_track_plan.py outline.json segment_01.json segment_02.json -o plan.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
outline (ids, frames, modes, verbatim media paths, context-prompt rules, handoff chain),
then assembles the TRACK_DATA (task track + locked master-audio / reference-video tracks
built straight from the outline, never retyped) and the patch plan the node pack's
`patch_workflow.py apply` consumes:
{"editor": {"resolution": ..., "track_data": {...}, "format": ...},
"project": {...}}
It writes `plan.json` (the deliverable) and `track_data.json` (pretty, for inspection).
Segment/track/image ids are deterministic UUIDv5 values derived from the project title, so
re-running the merge keeps ids stable. Never edit fragment prose here and never write the
plan by hand — fix the fragment, re-validate, re-merge.
Standard library only.
"""
from __future__ import annotations
import argparse
import copy
import json
import sys
import uuid
from pathlib import Path
from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
import verify_track_rules as vtr # noqa: E402
def stable_id(*parts: str) -> str:
seed = "easy-media-track-gate/" + "/".join(parts)
return str(uuid.uuid5(uuid.NAMESPACE_URL, seed))
def _finalize_image(img: dict[str, Any], inv_entry: dict[str, Any], seg_id: str, pos: int,
shared_default: bool) -> dict[str, Any]:
out = {
"id": img.get("id") or stable_id(seg_id, f"image-{pos}"),
"source_type": img.get("source_type", inv_entry["source_type"]),
"file_path": inv_entry["path"],
"file_name": img.get("file_name") or inv_entry.get("file_name")
or inv_entry["path"].rsplit("/", 1)[-1],
"shared_reference": img.get("shared_reference", shared_default),
}
if out["source_type"] == "url":
out["url"] = img.get("url") or inv_entry["path"]
out.pop("file_path", None)
out.pop("file_name", None)
return out
def build(outline: dict[str, Any], fragments: list[dict[str, Any]]) -> dict[str, Any]:
rows = outline["rows"]
if len(fragments) != len(rows):
raise vtr.Fail(f"expected {len(rows)} fragments (one per approved outline row), got {len(fragments)}")
prev: dict[str, Any] | None = None
for i, frag in enumerate(fragments):
vtr.validate_fragment(frag, i + 1, len(rows), prev, outline)
prev = frag
task_segments: list[dict[str, Any]] = []
for i, (frag, row) in enumerate(zip(fragments, rows)):
seg_id = stable_id(outline["title"], "segment", row["id"])
content = copy.deepcopy(frag["content"])
content.setdefault("media_type", "none")
content["media_type"] = "none"
content.setdefault("user_prompt_variant", "a")
if content.get("user_prompt_variant") == "a":
content.setdefault("user_prompt_b", "")
content.setdefault("system_prompt", "")
content.setdefault("muted", False)
content.setdefault("volume_db", 0)
if "ref_image_size" not in content:
content["ref_image_size"] = "match"
row_imgs = row.get("images", [])
final_imgs = []
for pos, (img, row_img) in enumerate(zip(content.get("images", []), row_imgs)):
inv_entry = outline["inventory"][row_img["key"]]
final_imgs.append(_finalize_image(img, inv_entry, seg_id, pos,
bool(row_img.get("shared_reference", False))))
content["images"] = final_imgs
task_segments.append({
"id": seg_id,
"start_frame": frag["start_frame"],
"end_frame": frag["end_frame"],
"color": "var(--multitrack-task-bg)",
"content": content,
})
total = max((s["end_frame"] for s in task_segments), default=0)
tracks: list[dict[str, Any]] = [{
"id": stable_id(outline["title"], "track", "tasks"),
"name": "Tasks",
"type": "task",
"color": "var(--multitrack-task-bg)",
"muted": False,
"solo": False,
"volume_db": 0,
"locked": False,
"segments": task_segments,
}]
roles = outline["_roles"]
for role, track_type in (("master_audio", "audio"), ("reference_video", "video")):
spec = roles.get(role)
if not spec:
continue
inv = outline["inventory"][spec["key"]]
media_content: dict[str, Any] = {
"media_type": track_type,
"source_type": inv["source_type"],
}
if inv["source_type"] == "url":
media_content["url"] = inv["path"]
else:
media_content["file_path"] = inv["path"]
media_content["file_name"] = inv.get("file_name") or inv["path"].rsplit("/", 1)[-1]
tracks.append({
"id": stable_id(outline["title"], "track", role),
"name": spec["name"],
"type": track_type,
"color": "var(--primary)",
"muted": False,
"solo": False,
"volume_db": 0,
"locked": False,
"audio_locked": True,
"segments": [{
"id": stable_id(outline["title"], "media", role),
"start_frame": 0,
"end_frame": max(total, 1),
"color": "var(--primary)",
"content": media_content,
}],
})
track_data: dict[str, Any] = {
"muted": False,
"volume_db": 0,
"task_markers": [],
"task_overview": False,
"tracks": tracks,
"total_length": total,
"frame_rate": outline["defaults"]["frame_rate"],
}
plan: dict[str, Any] = {
"editor": {
"resolution": copy.deepcopy(outline["editor"]["resolution"]),
"track_data": track_data,
"format": outline["editor"]["format"],
},
"project": copy.deepcopy(outline["project"]),
}
project = plan["project"]
vtr.validate_plan(plan, outline=outline)
return plan
def _summary(plan: dict[str, Any]) -> str:
data = plan["editor"]["track_data"]
task_count = sum(len(t.get("segments", [])) for t in data["tracks"] if t.get("type") == "task")
locked = [f"{t['type']}:{t.get('name', t['id'])}" for t in data["tracks"]
if t.get("audio_locked") is True]
fps = data["frame_rate"]
return (f"{task_count} task segments, total_length {data['total_length']} frames "
f"= {data['total_length'] / fps:.2f}s at {fps} fps; "
f"tracks: {', '.join(t['type'] + ' ' + t.get('name', '') for t in data['tracks'])}; "
f"audio_locked: {', '.join(locked) if locked else 'none'}")
def _write_json(path: Path, value: dict[str, Any]) -> None:
path.write_text(json.dumps(value, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
def _main(argv: list[str]) -> int:
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("-o", "--output", default="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")
args = parser.parse_args(argv)
try:
if args.check:
if not args.inputs:
raise vtr.Fail("--check needs the plan file path")
plan = vtr.load_json(args.inputs[0], "patch plan")
outline = None
if args.outline:
outline = vtr.load_json(args.outline, "outline")
vtr.validate_outline(outline)
vtr.validate_plan(plan, outline=outline)
print(f"PLAN OK: {_summary(plan)}")
return 0
if len(args.inputs) < 2:
raise vtr.Fail("usage: build_track_plan.py outline.json segment_01.json [segment_02.json ...] -o plan.json")
outline = vtr.load_json(args.inputs[0], "outline")
vtr.validate_outline(outline)
fragments = [vtr.load_json(p, "segment fragment") for p in args.inputs[1:]]
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"])
print(f"PLAN OK: {_summary(plan)}")
print(f"wrote {out_path} and {out_path.parent / 'track_data.json'}")
print("next: dry-run the node pack's patch script before writing:")
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
except vtr.Fail as exc:
print(f"FAIL: {exc}")
return 1
if __name__ == "__main__":
sys.exit(_main(sys.argv[1:]))