#!/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 \\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:]))