#!/usr/bin/env python3 """Gate for ComfyUI-Easy-Media MultiTrack plans: outline, task segments, TRACK_DATA, patch plan. The validator mirrors every check that the node pack's own `skills/easy-media-multitrack-workflow/scripts/patch_workflow.py` performs at apply time (ids, ordering, overlap, frame ranges, media sources, image counts, audio locks, shared references, resolution combos, project fields), so a plan that passes here cannot be rejected there for schema reasons. On top it enforces the gates that upstream leaves to discipline: * outline pins — each segment's id, start/end frames, task_mode, continuity_mode and reference-image set must match the approved outline row; media `file_path` strings must be character-for-character copies of the outline's media_inventory entries (the same verbatim contract the h3-plan-gate enforces for refmods); * context prompt rules — self-contained prompts (no "same as before" references), keep-then-change openers for context/context_drift joins, end-in-motion tails when more context segments follow; * drift uniformity — when any task segment is context_drift, all are, with the contiguous 10-second split unless the user pinned lengths. Sub-commands: (no args) embedded self-test suite outline OUTLINE.json validate the timeline guide segment SEGMENT_NN.json --index N --total T --outline OUTLINE.json [--prev PREV.json] trackdata TRACK_DATA.json [--outline OUTLINE.json] plan PLAN.json [--outline OUTLINE.json] suite embedded self-test suite Exit code 0 = pass, 1 = fail. Standard library only. """ from __future__ import annotations import json import re import sys from pathlib import Path from typing import Any TRACK_TYPES = {"task", "video", "audio", "subtitle"} TASK_MODES = {"default", "l2v", "ref", "edit"} CONTINUITY_MODES = {"shot", "context", "context_drift"} CONTINUITY_JOIN_MODES = {"context", "context_drift"} REF_IMAGE_SIZES = {"match", "max"} PROMPT_VARIANTS = {"a", "b"} SOURCE_TYPES = {"input", "output", "local", "url", "slot"} SOURCE_FIELD = { "input": "file_path", "output": "file_path", "local": "local_path", "url": "url", "slot": "slot_name", } MEDIA_KINDS = {"image", "audio", "video"} RESIZE_METHODS = { "stretch", "resize", "pad", "pad (white)", "pad_edge", "pad_edge_pixel", "crop", "pillarbox_blur", } ASPECT_RATIOS = { "1:1 (Square)", "2:3 (Portrait Photo)", "3:2 (Photo)", "3:4 (Portrait Standard)", "4:3 (Standard)", "9:16 (Portrait Widescreen)", "16:9 (Widescreen)", "21:9 (Ultrawide)", } PROJECT_FIELDS = { "project_name", "project_save", "segment_start_number", "segment_count", "seed", "control_after_generate", "sampling_plan", "sampling_mode", "1st_pass_only", "disable_2nd_noise", "upscale_by", "upscale_model", } EDITOR_PLAN_FIELDS = {"node_id", "track_data", "format", "resolution", "recalculate_total_length"} SNAKE_RE = re.compile(r"^[a-z][a-z0-9_]*$") MAX_IMAGES = 9 PROMPT_MIN_WORDS = 60 END_STATE_MIN_WORDS = 15 OPEN_WINDOW = 240 # chars inspected for keep/cut rules at the prompt start TAIL_WINDOW = 240 # chars inspected for the end-in-motion rule at the prompt end # A task segment renders standalone: the model never sees any other segment's prompt. BANNED_SELFREF = [ "same as before", "the same as before", "as before", "as mentioned", "as above", "same as above", "previous shot", "previous segment", "previous scene", "previous clip", "previous frame", "previous prompt", "the last shot", "the last segment", "the last scene", "the last clip", "the last frame", "same as the previous", "like the previous", "identical to the previous", "same character as", "同上", "和之前一样", "上一段", "上一镜头", ] # Context/drift joins must open by keeping the delivered tail, not by restating a plan. KEEP_TOKENS = [ "hold", "keep", "continu", "maintain", "carry", "resume", "unchanged", "same direction", "same framing", "same pose", "same speed", "same light", "steady", "incoming", "arrives with", "already in", ] # New compositions belong in `shot` segments, not in the opening of a context join. CUT_TOKENS_OPEN = [ "cut to", "cuts to", "hard cut", "smash cut", "jump cut", "new angle", "new shot", "new scene", "new composition", "new setup", ] # A context join that is followed by another context join must not end its motion. REST_TOKENS_TAIL = [ "comes to rest", "comes to a stop", "comes to a complete stop", "comes to a halt", "freezes in place", "holds still", "stops moving", "motionless", "stands still", "lies still", "sits still", "slows to a stop", "slows to a halt", "grinds to a halt", "ends on a held frame", "freezes the frame", "falls asleep", "settles into stillness", ] class Fail(Exception): """A validation failure with an actionable message.""" def load_json(path: str | Path, label: str) -> dict[str, Any]: try: value = json.loads(Path(path).read_text(encoding="utf-8")) except OSError as exc: raise Fail(f"cannot read {label} {path}: {exc}") from exc except json.JSONDecodeError as exc: raise Fail(f"{label} {path} is not valid JSON: {exc}") from exc if not isinstance(value, dict): raise Fail(f"{label} must be a JSON object: {path}") return value def is_int(value: Any) -> bool: return isinstance(value, int) and not isinstance(value, bool) def require_snake(value: Any, where: str) -> str: if not isinstance(value, str) or not SNAKE_RE.fullmatch(value): raise Fail(f"{where} must be lowercase snake_case (letters, digits, underscores): {value!r}") return value def word_count(text: str) -> int: return len(text.split()) # ---------------------------------------------------------------- resolution def validate_resolution(value: Any, where: str) -> dict[str, Any]: if isinstance(value, str): patch: dict[str, Any] = {"resolution": value} elif isinstance(value, dict): patch = dict(value) else: raise Fail(f"{where} must be a string or an object") allowed = {"resolution", "resize_method", "resize_to_pixel", "width", "height", "aspect_ratio", "megapixels"} unknown = sorted(set(patch) - allowed) if unknown: raise Fail(f"{where} has unsupported fields {unknown}; allowed: {sorted(allowed)}") label = patch.get("resolution") if not isinstance(label, str) or not label: raise Fail(f"{where}.resolution must be a non-empty string label") def reject_unused(expected: set[str]) -> None: unused = sorted(set(patch) - {"resolution"} - expected) if unused: raise Fail(f"resolution option {label!r} does not use fields {unused}") def check_method() -> str: method = patch.get("resize_method", "stretch") if method not in RESIZE_METHODS: raise Fail(f"{where}.resize_method {method!r} not in {sorted(RESIZE_METHODS)}") return method if label == "width x height (custom)": reject_unused({"width", "height", "resize_method"}) for field in ("width", "height"): dim = patch.get(field) if not is_int(dim) or dim < 64 or dim > 8096: raise Fail(f"{where}.{field} must be an integer from 64 to 8096") check_method() elif label in {"width x height (shortest)", "width x height (longest)"}: reject_unused({"resize_to_pixel", "resize_method"}) pixels = patch.get("resize_to_pixel") if not is_int(pixels) or pixels < 64 or pixels > 8096: raise Fail(f"{where}.resize_to_pixel must be an integer from 64 to 8096") check_method() elif label == "width x height (megapixels)": reject_unused({"aspect_ratio", "megapixels"}) aspect = patch.get("aspect_ratio") mp = patch.get("megapixels") if aspect not in ASPECT_RATIOS: raise Fail( f"{where}.aspect_ratio must be the exact full token, one of " f"{sorted(ASPECT_RATIOS)}; got {aspect!r} (plain '16:9' is a rewrite — " "copy the token verbatim from the outline)" ) if not isinstance(mp, (int, float)) or isinstance(mp, bool) or not 0.1 <= float(mp) <= 16.0: raise Fail(f"{where}.megapixels must be a number from 0.1 to 16.0") else: reject_unused({"resize_method"}) is_auto = label == "width x height (auto)" is_fixed = re.fullmatch(r"\s*\d+\s*x\s*\d+\s*\([^()]+\)\s*", label) is not None if not is_auto and not is_fixed: raise Fail(f"{where}.resolution label {label!r} is not a supported option") check_method() return patch # ------------------------------------------------------------ media sources def validate_media_source(content: dict[str, Any], where: str, kinds: set[str]) -> str: media_type = content.get("media_type") if media_type not in kinds: raise Fail(f"{where}.content.media_type must be one of {sorted(kinds)}; got {media_type!r}") source_type = content.get("source_type") if source_type not in SOURCE_TYPES: raise Fail(f"{where}.content.source_type must be one of {sorted(SOURCE_TYPES)}; got {source_type!r}") field = SOURCE_FIELD[source_type] value = content.get(field) if not isinstance(value, str) or not value.strip(): raise Fail( f"{where}.content.source_type {source_type!r} requires a non-empty " f"`{field}` field (the path field must match the source type)" ) if source_type in {"input", "output", "local"} and value.startswith(("/", "~")): raise Fail( f"{where}.content.{field} must be the relative path returned by the upload " f"API (like codex/session/file.mp4), not a machine-absolute path: {value!r}" ) return str(value) # ------------------------------------------------------------ prompt rules def prompt_rules(user_prompt: str, continuity_mode: str, followed_by_join: bool, where: str) -> None: if not isinstance(user_prompt, str) or not user_prompt.strip(): raise Fail(f"{where}.content.user_prompt must be a non-empty string") text = " ".join(user_prompt.split()) lowered = text.lower() words = word_count(text) if words < PROMPT_MIN_WORDS: raise Fail( f"{where}.content.user_prompt is too thin ({words} words; floor {PROMPT_MIN_WORDS}). " "Compose the segment, do not summarize: subject anchor with its look, blocking, " "one camera idea, ordered body-mechanics motion, physical texture, exit state." ) for token in BANNED_SELFREF: if token in lowered: raise Fail( f"{where}.content.user_prompt references another segment ({token!r}). Each task " "segment renders standalone — the model never sees any other prompt. Fully " "restate scene, light and subject identity inside this prompt." ) if continuity_mode in CONTINUITY_JOIN_MODES: opener = lowered[:OPEN_WINDOW] if not any(token in opener for token in KEEP_TOKENS): raise Fail( f"{where}.content.user_prompt must open by keeping the delivered tail " f"(one of {KEEP_TOKENS[:8]} ... in the first ~{OPEN_WINDOW} characters). " "Context joins start from the previous segment's real last frames: keep " "camera direction, pose and light first; put every change later." ) for token in CUT_TOKENS_OPEN: if token in opener: raise Fail( f"{where}.content.user_prompt opens with a new composition ({token!r}). " "A context join keeps first and changes later (changes from ~00:02, " "written as an explicit cut); for a genuinely new composition use a " "`shot` segment." ) if followed_by_join: tail = lowered[-TAIL_WINDOW:] for token in REST_TOKENS_TAIL: if token in tail: raise Fail( f"{where}.content.user_prompt ends in rest ({token!r}) but another " "context segment follows. End in motion — the next join opens inside " "this segment's real last frames." ) # ----------------------------------------------------------------- outline def _validate_media_inventory(outline: dict[str, Any]) -> dict[str, dict[str, Any]]: rows = outline.get("media_inventory") if not isinstance(rows, list) or not rows: raise Fail("outline.media_inventory must be a non-empty array of media rows") inventory: dict[str, dict[str, Any]] = {} for i, row in enumerate(rows): where = f"media_inventory[{i}]" if not isinstance(row, dict): raise Fail(f"{where} must be an object") key = row.get("key") if not isinstance(key, str) or not re.fullmatch(r"^[A-Z][A-Z0-9_]*$", key): raise Fail(f"{where}.key must be an UPPERCASE key (like POSE_REF): {key!r}") if key in inventory: raise Fail(f"duplicate media_inventory key: {key}") kind = row.get("kind") if kind not in MEDIA_KINDS: raise Fail(f"{where}.kind must be one of {sorted(MEDIA_KINDS)}; got {kind!r}") path = validate_media_source( {"media_type": kind, "source_type": row.get("source_type", "input"), **{k: v for k, v in row.items() if k in {"file_path", "local_path", "url", "slot_name"}}}, where, {kind}, ) entry = {"kind": kind, "source_type": row.get("source_type", "input"), "path": path} name = row.get("file_name") if name is not None: if not isinstance(name, str) or not name.strip(): raise Fail(f"{where}.file_name must be a non-empty string when present") entry["file_name"] = name inventory[key] = entry return inventory def _validate_track_roles(outline: dict[str, Any], inventory: dict[str, dict[str, Any]]) -> dict[str, Any]: tracks = outline.get("tracks") if not isinstance(tracks, dict): raise Fail("outline.tracks must be an object with master_audio / reference_video / extra_tracks") roles: dict[str, Any] = {"master_audio": None, "reference_video": None, "extra_tracks": []} for role, kind in (("master_audio", "audio"), ("reference_video", "video")): spec = tracks.get(role) if spec is None: continue if not isinstance(spec, dict): raise Fail(f"outline.tracks.{role} must be an object or null") key = spec.get("key") if key not in inventory: raise Fail(f"outline.tracks.{role}.key {key!r} is not a media_inventory key") if inventory[key]["kind"] != kind: raise Fail( f"outline.tracks.{role}.key {key!r} is a {inventory[key]['kind']} row; " f"the {role} role needs a {kind} row" ) if spec.get("lock") is not True: raise Fail( f"outline.tracks.{role}.lock must be true: this gate only builds tracks that " "drive generation; ordinary background media does not belong in the plan" ) name = spec.get("name", "Master Audio" if role == "master_audio" else "Reference Video") roles[role] = {"key": key, "name": name} extra = tracks.get("extra_tracks", []) if extra != []: raise Fail("outline.tracks.extra_tracks must be [] in this gate version") return roles def _validate_project(project: Any) -> dict[str, Any]: if not isinstance(project, dict): raise Fail("outline.project must be an object") unknown = sorted(set(project) - ({"node_id"} | PROJECT_FIELDS)) if unknown: raise Fail(f"outline.project has unsupported fields {unknown}") if project.get("project_save") not in {"new", "override"}: raise Fail("outline.project.project_save must be 'new' or 'override'") start = project.get("segment_start_number", 1) if not is_int(start) or start < 1: raise Fail("outline.project.segment_start_number must be a positive integer (1-based)") count = project.get("segment_count", -1) if not is_int(count) or count < -1: raise Fail("outline.project.segment_count must be -1 or a non-negative integer") mode = project.get("sampling_mode", "single") if mode not in {"single", "dual"}: raise Fail("outline.project.sampling_mode must be 'single' or 'dual'") plan = project.get("sampling_plan") if not isinstance(plan, str) or not plan.strip(): raise Fail("outline.project.sampling_plan must be a non-empty preset name (e.g. 'medium')") if "upscale_by" in project: up = project["upscale_by"] if not isinstance(up, (int, float)) or isinstance(up, bool) or up <= 0: raise Fail("outline.project.upscale_by must be a positive number") if round(float(up), 3) != float(up): raise Fail("outline.project.upscale_by keeps three decimals (step 0.001)") for flag in ("1st_pass_only", "disable_2nd_noise"): if flag in project and not isinstance(project[flag], bool): raise Fail(f"outline.project.{flag} must be a boolean") if "seed" in project and not is_int(project["seed"]): raise Fail("outline.project.seed must be an integer") return project def outline_frames(outline: dict[str, Any]) -> list[dict[str, Any]]: """Return the outline rows with computed start_frame/end_frame and joined flags.""" fps = outline.get("defaults", {}).get("frame_rate") rows = outline.get("segments", []) out: list[dict[str, Any]] = [] for i, row in enumerate(rows): start_s = float(row["start_seconds"]) dur_s = float(row["duration_seconds"]) start_f = round(start_s * fps) end_f = start_f + round(dur_s * fps) joined_after = any( r["continuity_mode"] in CONTINUITY_JOIN_MODES for r in rows[i + 1:] ) out.append({**row, "start_frame": start_f, "end_frame": end_f, "followed_by_join": joined_after}) return out def validate_outline(obj: dict[str, Any]) -> dict[str, Any]: if obj.get("title") is None or not SNAKE_RE.fullmatch(str(obj.get("title"))): raise Fail("outline.title must be lowercase snake_case") editor = obj.get("editor") if not isinstance(editor, dict): raise Fail("outline.editor must be an object") fmt = editor.get("format") if not isinstance(fmt, str) or not fmt.strip(): raise Fail("outline.editor.format must be a non-empty string (the editor's format pack, e.g. 'MiniMax')") if "resolution" not in editor: raise Fail("outline.editor.resolution is required (the DynamicCombo setting)") validate_resolution(editor["resolution"], "outline.editor.resolution") defaults = obj.get("defaults") if not isinstance(defaults, dict): raise Fail("outline.defaults must be an object") fps = defaults.get("frame_rate") if not is_int(fps) or fps < 1: raise Fail("outline.defaults.frame_rate must be a positive integer") seg_s = defaults.get("segment_seconds", 10) if not isinstance(seg_s, (int, float)) or isinstance(seg_s, bool) or seg_s <= 0: raise Fail("outline.defaults.segment_seconds must be a positive number") inventory = _validate_media_inventory(obj) _validate_track_roles(obj, inventory) _validate_project(obj.get("project")) rows = obj.get("segments") if not isinstance(rows, list) or not rows: raise Fail("outline.segments must be a non-empty array of segment rows") ids: set[str] = set() pinned = obj.get("lengths_user_pinned") is True drift_rows = 0 cursor = 0.0 for i, row in enumerate(rows): where = f"segments[{i}]" if not isinstance(row, dict): raise Fail(f"{where} must be an object") if row.get("index") != i + 1: raise Fail(f"{where}.index must be {i + 1} (contiguous, 1-based)") seg_id = require_snake(row.get("id"), f"{where}.id") if seg_id in ids: raise Fail(f"duplicate segment id: {seg_id}") ids.add(seg_id) start_s = row.get("start_seconds") dur_s = row.get("duration_seconds") if not isinstance(start_s, (int, float)) or isinstance(start_s, bool) or start_s < 0: raise Fail(f"{where}.start_seconds must be a non-negative number") if not isinstance(dur_s, (int, float)) or isinstance(dur_s, bool) or dur_s < 1: raise Fail(f"{where}.duration_seconds must be a number >= 1") if abs(float(start_s) - cursor) > 1e-6: raise Fail( f"{where}.start_seconds is {start_s} but the timeline cursor is {cursor} " "(previous start + duration + gap_after_seconds). Keep the rows cumulative." ) cursor = float(start_s) + float(dur_s) if row.get("task_mode") not in TASK_MODES: raise Fail(f"{where}.task_mode must be one of {sorted(TASK_MODES)}") cm = row.get("continuity_mode") if cm not in CONTINUITY_MODES: raise Fail(f"{where}.continuity_mode must be one of {sorted(CONTINUITY_MODES)}; " "write 'context_drift' (the legacy 'context_swap' is not accepted in new plans)") if cm == "context_drift": drift_rows += 1 beat = row.get("beat") if not isinstance(beat, str) or word_count(beat) < 6: raise Fail(f"{where}.beat must say in one sentence what happens AND where the segment ends") brief = row.get("prompt_brief") if not isinstance(brief, str) or word_count(brief) < 6: raise Fail(f"{where}.prompt_brief must sketch the prompt's keep/change plan in 1-2 sentences") images = row.get("images", []) if not isinstance(images, list): raise Fail(f"{where}.images must be an array") if len(images) > MAX_IMAGES: raise Fail(f"{where}.images holds {len(images)} items; the schema allows at most {MAX_IMAGES} per task") seen_keys: set[str] = set() for j, img in enumerate(images): img_where = f"{where}.images[{j}]" if not isinstance(img, dict) or img.get("key") not in inventory: raise Fail(f"{img_where}.key must be a media_inventory key") key = img["key"] if key in seen_keys: raise Fail(f"{img_where} repeats media key {key}") seen_keys.add(key) if inventory[key]["kind"] != "image": raise Fail(f"{img_where}.key {key} is a {inventory[key]['kind']} row; task images need image rows") if "shared_reference" in img and not isinstance(img["shared_reference"], bool): raise Fail(f"{img_where}.shared_reference must be a boolean") gap = row.get("gap_after_seconds", 0) if not isinstance(gap, (int, float)) or isinstance(gap, bool) or gap < 0: raise Fail(f"{where}.gap_after_seconds must be a non-negative number") cursor += float(gap) if drift_rows and drift_rows != len(rows): offenders = [r["id"] for r in rows if r.get("continuity_mode") != "context_drift"] raise Fail( "context_drift is all-or-nothing: every task segment in scope carries " f"context_drift (the first one included), but {offenders} do not. Set all rows " "to context_drift — or none of them." ) if drift_rows and not pinned: expected = float(defaults.get("segment_seconds", 10)) off = [f"{r['id']}={r['duration_seconds']}" for r in rows if abs(float(r["duration_seconds"]) - expected) > 1e-6] if off: raise Fail( "context_drift without user-pinned lengths splits the task range into " f"consecutive {expected:g}s pieces (the last takes the remainder, no padding). " f"These rows deviate: {off}. Set lengths_user_pinned=true only if the user " "actually specified the lengths." ) if drift_rows: for i in range(1, len(rows)): prev, cur = rows[i - 1], rows[i] expected_start = float(prev["start_seconds"]) + float(prev["duration_seconds"]) \ + float(prev.get("gap_after_seconds", 0)) if abs(float(cur["start_seconds"]) - expected_start) > 1e-6: raise Fail( f"context_drift splits are consecutive: segments[{i}].start_seconds must be " f"{expected_start:g} (previous start + duration + gap), got {cur['start_seconds']}" ) obj["inventory"] = inventory obj["_roles"] = _validate_track_roles(obj, inventory) obj["rows"] = outline_frames(obj) return obj # ---------------------------------------------------------------- fragment def _validate_task_images(images: Any, where: str, outline: dict[str, Any] | None) -> list[str]: if not isinstance(images, list): raise Fail(f"{where}.content.images must be an array") if len(images) > MAX_IMAGES: raise Fail(f"{where}.content.images holds {len(images)} items; at most {MAX_IMAGES} is allowed") paths: list[str] = [] for j, img in enumerate(images): img_where = f"{where}.content.images[{j}]" if not isinstance(img, dict): raise Fail(f"{img_where} must be an object") if "shared_reference" in img and not isinstance(img["shared_reference"], bool): raise Fail(f"{img_where}.shared_reference must be a boolean") if "key" in img: raise Fail(f"{img_where} must not carry the outline's `key` field — copy the real " "file_path from the media_inventory row instead") path = validate_media_source( {"media_type": "image", "source_type": img.get("source_type", "input"), **{k: v for k, v in img.items() if k in {"file_path", "local_path", "url", "slot_name"}}}, img_where, {"image"}, ) if outline is not None: inv = outline["inventory"] matches = [k for k, v in inv.items() if v["kind"] == "image" and v["path"] == path] if not matches: nearest = min( (v["path"] for v in inv.values() if v["kind"] == "image"), default="", key=lambda p: _distance(p, path), ) raise Fail( f"{img_where}.file_path {path!r} is not a verbatim copy of any outline " f"media_inventory image path (closest: {nearest!r}). Open outline.json, " "select the exact file_path text, copy, paste — never retype it." ) paths.append(path) return paths def _distance(a: str, b: str) -> int: """Cheap similarity proxy for the error hint (absolute difference in shared prefix).""" i = 0 for ca, cb in zip(a, b): if ca != cb: break i += 1 return len(a) + len(b) - 2 * i def _validate_task_content(content: dict[str, Any], where: str, outline: dict[str, Any] | None, followed_by_join: bool) -> None: if not isinstance(content, dict): raise Fail(f"{where}.content must be an object") if "media_type" in content and content["media_type"] != "none": raise Fail(f"{where}.content.media_type must be 'none' on a task segment") if content.get("task_mode") not in TASK_MODES: raise Fail(f"{where}.content.task_mode must be one of {sorted(TASK_MODES)}") cm = content.get("continuity_mode") if cm not in CONTINUITY_MODES: raise Fail( f"{where}.content.continuity_mode must be one of {sorted(CONTINUITY_MODES)}; " "write 'context_drift' (the legacy 'context_swap' is not accepted in new plans)" ) if "ref_image_size" in content and content["ref_image_size"] not in REF_IMAGE_SIZES: raise Fail(f"{where}.content.ref_image_size must be 'match' or 'max'") if "user_prompt_variant" in content and content["user_prompt_variant"] not in PROMPT_VARIANTS: raise Fail(f"{where}.content.user_prompt_variant must be 'a' or 'b'") for field in ("user_prompt", "system_prompt", "user_prompt_b"): if field in content and not isinstance(content[field], str): raise Fail(f"{where}.content.{field} must be a string") if not isinstance(content.get("muted", False), bool) or not isinstance(content.get("volume_db", 0), (int, float)): raise Fail(f"{where}.content.muted must be a boolean and volume_db a number") _validate_task_images(content.get("images", []), where, outline) prompt_field = "user_prompt_b" if content.get("user_prompt_variant") == "b" else "user_prompt" prompt_rules(content.get(prompt_field, ""), cm, followed_by_join, where) def validate_fragment(obj: dict[str, Any], index: int = 1, total: int | None = None, prev: dict[str, Any] | None = None, outline: dict[str, Any] | None = None) -> dict[str, Any]: if not isinstance(obj, dict): raise Fail("segment fragment must be a JSON object") if total is not None and outline is not None and total != len(outline["rows"]): raise Fail(f"--total {total} does not match the outline's {len(outline['rows'])} segment rows") if outline is not None and not 1 <= index <= len(outline["rows"]): raise Fail(f"--index {index} is outside the outline's 1..{len(outline['rows'])} rows") seg_id = require_snake(obj.get("id"), "fragment.id") start = obj.get("start_frame") end = obj.get("end_frame") if not is_int(start) or start < 0: raise Fail("fragment.start_frame must be a non-negative integer") if not is_int(end) or end <= start: raise Fail("fragment.end_frame must be an integer greater than start_frame " "(start_frame inclusive, end_frame exclusive)") row: dict[str, Any] | None = None if outline is not None: row = outline["rows"][index - 1] if seg_id != row["id"]: raise Fail(f"fragment.id {seg_id!r} does not match the approved outline row " f"{index} id {row['id']!r} — ids are never silently altered") if start != row["start_frame"] or end != row["end_frame"]: raise Fail( f"fragment frames [{start}, {end}) do not match the approved outline row " f"[{row['start_frame']}, {row['end_frame']}) " f"(row start_seconds {row['start_seconds']} + duration_seconds " f"{row['duration_seconds']} at {outline['defaults']['frame_rate']} fps). " "The approved guide is the contract; fix the fragment, or revise the outline first." ) if obj.get("content", {}).get("task_mode") not in (None, row["task_mode"]): raise Fail(f"outline pins segment {seg_id} as task_mode {row['task_mode']!r}; " f"the fragment says {obj['content']['task_mode']!r}") if obj.get("content", {}).get("continuity_mode") not in (None, row["continuity_mode"]): raise Fail(f"outline pins segment {seg_id} as continuity_mode {row['continuity_mode']!r}; " f"the fragment says {obj['content']['continuity_mode']!r}") _validate_task_content(obj.get("content", {}), "fragment", outline, bool(row and row["followed_by_join"])) if outline is not None and row is not None: content = obj["content"] frag_paths = _validate_task_images(content.get("images", []), "fragment", outline) row_keys = [img["key"] for img in row.get("images", [])] row_paths = [outline["inventory"][k]["path"] for k in row_keys] if frag_paths != row_paths: raise Fail( f"fragment image order/set {frag_paths} does not match the approved outline " f"row {row_paths} — carry exactly the pinned references in the pinned order " "(image order defines the picture-reference order)" ) handoff = obj.get("_handoff") if not isinstance(handoff, dict): raise Fail("fragment._handoff must be an object with an end_state") end_state = handoff.get("end_state") if not isinstance(end_state, str) or word_count(end_state) < END_STATE_MIN_WORDS: raise Fail( f"fragment._handoff.end_state must describe the real final frame in at least " f"{END_STATE_MIN_WORDS} words (pose, motion in progress, camera state) — the next " "context join opens inside these frames" ) if prev is not None: prev_end = prev.get("end_frame") if is_int(prev_end) and start != prev_end and (outline is None or _row_gap(outline, index) == 0): raise Fail( f"fragment starts at frame {start} but the previous segment ends at {prev_end}. " "Task segments of one chain are consecutive: [0,N), [N,2N), ... — never an " "extra frame at the boundary, no overlap." ) return obj def _row_gap(outline: dict[str, Any], index: int) -> float: if index < 2 or index > len(outline["rows"]): return 0.0 return float(outline["rows"][index - 2].get("gap_after_seconds", 0)) # --------------------------------------------------------------- track data def validate_track_data(data: dict[str, Any], *, outline: dict[str, Any] | None = None, recalculate: bool = True, segment_start_index: int = 0, segment_count: int = -1) -> dict[str, Any]: tracks = data.get("tracks") fps = data.get("frame_rate") if not isinstance(tracks, list): raise Fail("track_data.tracks must be an array") if not is_int(fps) or fps < 1: raise Fail("track_data.frame_rate must be a positive integer") if not is_int(segment_start_index) or segment_start_index < 0: raise Fail("segment_start_index must be a non-negative integer") if not is_int(segment_count) or segment_count < -1: raise Fail("segment_count must be -1 or a non-negative integer") track_ids: set[str] = set() segment_ids: set[str] = set() locked: list[tuple[str, int, str]] = [] shared_refs: list[tuple[str, str, str]] = [] task_ranges: list[tuple[int, int]] = [] task_segments: list[dict[str, Any]] = [] max_end = 0 for ti, track in enumerate(tracks): where = f"tracks[{ti}]" if not isinstance(track, dict): raise Fail(f"{where} must be an object") track_id = track.get("id") if not isinstance(track_id, str) or not track_id: raise Fail(f"{where}.id must be a non-empty string") if track_id in track_ids: raise Fail(f"duplicate track id: {track_id}") track_ids.add(track_id) ttype = track.get("type") if ttype not in TRACK_TYPES: raise Fail(f"{where}.type must be one of {sorted(TRACK_TYPES)}; got {ttype!r}") if "audio_locked" in track and not isinstance(track["audio_locked"], bool): raise Fail(f"track {track_id} audio_locked must be a boolean") if track.get("audio_locked") is True: if ttype not in {"audio", "video"}: raise Fail(f"only audio/video tracks may set audio_locked: true (track {track_id})") locked.append((track_id, ti, str(ttype))) segments = track.get("segments") if not isinstance(segments, list): raise Fail(f"{where}.segments must be an array") previous_end = -1 for si, segment in enumerate(segments): seg_where = f"{where}.segments[{si}]" if not isinstance(segment, dict): raise Fail(f"{seg_where} must be an object") segment_id = segment.get("id") if not isinstance(segment_id, str) or not segment_id: raise Fail(f"{seg_where}.id must be a non-empty string") if segment_id in segment_ids: raise Fail(f"duplicate segment id: {segment_id}") segment_ids.add(segment_id) start = segment.get("start_frame") end = segment.get("end_frame") if not is_int(start) or start < 0: raise Fail(f"{seg_where}.start_frame must be a non-negative integer") if not is_int(end) or end <= start: raise Fail(f"{seg_where}.end_frame must be greater than start_frame") if start < previous_end: raise Fail(f"segments overlap or are unsorted in track {track_id}") previous_end = end max_end = max(max_end, end) if ttype == "task": task_ranges.append((start, end)) task_segments.append(segment) content = segment.get("content") if not isinstance(content, dict): raise Fail(f"{seg_where}.content must be an object") if ttype in {"video", "audio"}: path = validate_media_source(content, seg_where, {ttype}) if outline is not None: roles = outline.get("_roles", {}) role = roles.get("master_audio") if ttype == "audio" else roles.get("reference_video") if role and path != outline["inventory"][role["key"]]["path"]: raise Fail( f"{seg_where}.content path {path!r} is not the verbatim outline path " f"for the {ttype} role ({outline['inventory'][role['key']]['path']!r})" ) if "shared_reference" in content: if not isinstance(content["shared_reference"], bool): raise Fail(f"{seg_where}.content.shared_reference must be a boolean") if content.get("shared_reference") is True: shared_refs.append((track_id, segment_id, str(ttype))) if "speaker_reference" in content: if not isinstance(content["speaker_reference"], bool): raise Fail(f"{seg_where}.content.speaker_reference must be a boolean") if ttype != "audio" or content.get("media_type") != "audio": raise Fail(f"only audio segments may contain speaker_reference ({seg_where})") if content.get("speaker_reference") is True: raise Fail( f"{seg_where} writes the legacy speaker_reference: true — new plans " "always use shared_reference" ) if ttype == "task": followed_by_join = _segment_followed_by_join(task_segments, segment, tracks, ti, si) _validate_task_content(content, seg_where, outline, followed_by_join) for ltype in ("audio", "video"): locked_ids = [tid for tid, _, tt in locked if tt == ltype] if len(locked_ids) > 1: raise Fail(f"only one {ltype} track may be audio_locked; found {locked_ids}") dup_tracks = sorted({tid for tid, _, _ in shared_refs if [t for t, _, _ in shared_refs].count(tid) > 1}) if dup_tracks: raise Fail(f"each audio/video track may contain only one shared reference; found multiple in {dup_tracks}") selected = task_ranges[segment_start_index:] if segment_count >= 0: selected = selected[:segment_count] master_audio_ranges: list[tuple[int, int]] = [] for _, ti, kind in locked: if kind != "audio": continue for segment in tracks[ti]["segments"]: s, e = segment["start_frame"], segment["end_frame"] if master_audio_ranges and master_audio_ranges[-1][1] == s: master_audio_ranges[-1] = (master_audio_ranges[-1][0], e) else: master_audio_ranges.append((s, e)) complete_master = bool(selected) and all( any(a_s <= s and a_e >= e for a_s, a_e in master_audio_ranges) for s, e in selected ) for locked_id, ti, ltype in locked: locked_segments = tracks[ti].get("segments", []) if not any(isinstance(seg, dict) and isinstance(seg.get("content"), dict) and seg["content"].get("media_type") == ltype for seg in locked_segments): raise Fail(f"locked {ltype} track {locked_id} contains no {ltype} segments") if ltype == "video" and complete_master: continue uncovered = [ (s, e) for s, e in selected if not any(int(seg.get("start_frame", 0)) < e and int(seg.get("end_frame", 0)) > s for seg in locked_segments if isinstance(seg, dict)) ] if uncovered: raise Fail( f"locked {ltype} track {locked_id} does not overlap task segments: {uncovered}. " "The locked media must intersect every task range it drives." ) if recalculate and max_end > 0: data["total_length"] = max_end total = data.get("total_length") if not is_int(total) or total < 0: raise Fail("track_data.total_length must be a non-negative integer") if outline is not None: _check_outline_pins(data, task_segments, outline) return data def _segment_followed_by_join(task_segments: list[dict[str, Any]], segment: dict[str, Any], tracks: list[dict[str, Any]], ti: int, si: int) -> bool: """True when a later task segment (any task track) uses a join continuity mode.""" for track in tracks[ti:]: if not isinstance(track, dict) or track.get("type") != "task": continue segments = track.get("segments", []) start_from = si + 1 if track is tracks[ti] else 0 for later in segments[start_from:]: if isinstance(later, dict) and isinstance(later.get("content"), dict): if later["content"].get("continuity_mode") in CONTINUITY_JOIN_MODES: return True return False def _check_outline_pins(data: dict[str, Any], task_segments: list[dict[str, Any]], outline: dict[str, Any]) -> None: rows = outline["rows"] if len(task_segments) != len(rows): raise Fail( f"track_data carries {len(task_segments)} task segments but the approved outline " f"has {len(rows)} — rebuild with build_track_plan.py, never hand-edit the merge" ) fps = data["frame_rate"] for segment, row in zip(task_segments, rows): seg_id = segment.get("content", {}) where = f"task segment {row['id']!r}" if segment.get("start_frame") != row["start_frame"] or segment.get("end_frame") != row["end_frame"]: raise Fail( f"{where} frames [{segment.get('start_frame')}, {segment.get('end_frame')}) do not " f"match the approved outline [{row['start_frame']}, {row['end_frame']}) at {fps} fps" ) if seg_id.get("task_mode") != row["task_mode"]: raise Fail(f"{where} task_mode {seg_id.get('task_mode')!r} != outline {row['task_mode']!r}") if seg_id.get("continuity_mode") != row["continuity_mode"]: raise Fail(f"{where} continuity_mode {seg_id.get('continuity_mode')!r} != outline {row['continuity_mode']!r}") for track in data["tracks"]: if track.get("audio_locked") is not True or track.get("type") not in {"audio", "video"}: continue role = "master_audio" if track["type"] == "audio" else "reference_video" spec = outline.get("_roles", {}).get(role) if spec: expected = outline["inventory"][spec["key"]]["path"] found = [seg.get("content", {}).get("file_path") for seg in track.get("segments", []) if isinstance(seg, dict)] if expected not in found: raise Fail( f"locked {track['type']} track path {found} does not carry the verbatim " f"outline media path {expected!r}" ) # -------------------------------------------------------------------- plan def validate_plan(plan: dict[str, Any], *, outline: dict[str, Any] | None = None) -> dict[str, Any]: if not isinstance(plan, dict): raise Fail("plan must be a JSON object") unknown_top = sorted(set(plan) - {"editor", "project"}) if unknown_top: raise Fail(f"plan has unsupported top-level fields {unknown_top}; only editor/project") editor = plan.get("editor") project = plan.get("project") if not isinstance(editor, dict) or not isinstance(project, dict): raise Fail("plan.editor and plan.project must be objects") unknown_editor = sorted(set(editor) - EDITOR_PLAN_FIELDS) if unknown_editor: raise Fail(f"plan.editor has unsupported fields {unknown_editor}") _validate_project(project) if "track_data" not in editor: raise Fail("plan.editor.track_data is required (the complete TRACK_DATA object)") track_data = editor["track_data"] if not isinstance(track_data, dict): raise Fail("plan.editor.track_data must be an object") if "resolution" in editor: validate_resolution(editor["resolution"], "plan.editor.resolution") if "format" in editor and (not isinstance(editor["format"], str) or not editor["format"]): raise Fail("plan.editor.format must be a non-empty string") validate_track_data(track_data, outline=outline, recalculate=editor.get("recalculate_total_length", True) is not False, segment_start_index=int(project.get("segment_start_number", 1)) - 1, segment_count=int(project.get("segment_count", -1))) if outline is not None: if editor.get("format") != outline["editor"]["format"]: raise Fail(f"plan.editor.format {editor.get('format')!r} != outline {outline['editor']['format']!r}") if editor.get("resolution") != outline["editor"]["resolution"]: raise Fail("plan.editor.resolution does not match the approved outline — the merge " "copies it from the outline; never retype resolution tokens") return track_data # ------------------------------------------------------------------- suite def _suite_outline() -> dict[str, Any]: return { "title": "sunrise_rooftop_coffee", "lengths_user_pinned": True, "editor": { "format": "MiniMax", "resolution": {"resolution": "width x height (megapixels)", "aspect_ratio": "16:9 (Widescreen)", "megapixels": 0.8}, }, "defaults": {"frame_rate": 24, "segment_seconds": 10}, "media_inventory": [ {"key": "SONG", "kind": "audio", "source_type": "input", "file_path": "codex/rooftop/song.wav", "file_name": "song.wav"}, {"key": "POSE_REF", "kind": "image", "source_type": "input", "file_path": "codex/rooftop/pose_ref.png", "file_name": "pose_ref.png"}, ], "tracks": { "master_audio": {"key": "SONG", "lock": True, "name": "Master Song"}, "reference_video": None, }, "project": {"project_save": "override", "segment_start_number": 1, "segment_count": -1, "sampling_plan": "medium", "sampling_mode": "single"}, "segments": [ {"index": 1, "id": "seg_one_open", "start_seconds": 0, "duration_seconds": 10, "task_mode": "ref", "continuity_mode": "shot", "images": [{"key": "POSE_REF", "shared_reference": False}], "beat": "She pours coffee at the rooftop rail as the sun clears the skyline; ends mid-sip, city brightening.", "prompt_brief": "Establish rooftop, rail, skyline; pour coffee; end mid-sip with motion alive."}, {"index": 2, "id": "seg_two_sip_wind", "start_seconds": 10, "duration_seconds": 10, "task_mode": "ref", "continuity_mode": "context", "images": [{"key": "POSE_REF", "shared_reference": False}], "beat": "Wind tugs her cardigan mid-sip; she turns her face into the light; ends still turning.", "prompt_brief": "Keep framing and pose from the delivered tail; wind arrives at 00:02; end turning."}, {"index": 3, "id": "seg_three_city_wakes", "start_seconds": 20, "duration_seconds": 10, "task_mode": "ref", "continuity_mode": "context", "images": [{"key": "POSE_REF", "shared_reference": False}], "beat": "She lowers the cup as windows light up below; ends mid-exhale, steam curling.", "prompt_brief": "Keep the turn; lower the cup slowly; city windows light up; end mid-exhale."}, ], } PROMPT_1 = ( "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." ) PROMPT_2 = ( "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." ) PROMPT_3 = ( "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." ) def _suite_fragment(outline_rows: list[dict[str, Any]], index: int, prompt: str) -> dict[str, Any]: row = outline_rows[index - 1] return { "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-{index}", "source_type": "input", "file_path": "codex/rooftop/pose_ref.png", "file_name": "pose_ref.png", "shared_reference": False}], "user_prompt": prompt, "system_prompt": "", "user_prompt_variant": "a", "user_prompt_b": "", "muted": False, "volume_db": 0, }, "_handoff": {"end_state": "She stands mid-motion at the rail, cup halfway through its arc, ponytail " "and cardigan lifted by the wind, camera still drifting left.", "beat_used": row["beat"]}, } def _merged_track_data(outline: dict[str, Any], fragments: list[dict[str, Any]]) -> dict[str, Any]: rows = outline["rows"] task_segments = [] for frag in fragments: seg = {"id": f"seg-{frag['id']}", "start_frame": frag["start_frame"], "end_frame": frag["end_frame"], "color": "var(--multitrack-task-bg)", "content": dict(frag["content"])} seg["content"].pop("media_type", None) seg["content"]["media_type"] = "none" task_segments.append(seg) tracks: list[dict[str, Any]] = [{ "id": "track-tasks", "name": "Tasks", "type": "task", "color": "var(--multitrack-task-bg)", "muted": False, "solo": False, "volume_db": 0, "locked": False, "segments": task_segments, }] total = max(s["end_frame"] for s in task_segments) roles = outline["_roles"] if roles["master_audio"]: inv = outline["inventory"][roles["master_audio"]["key"]] tracks.append({ "id": "track-master-audio", "name": roles["master_audio"]["name"], "type": "audio", "color": "var(--primary)", "muted": False, "solo": False, "volume_db": 0, "locked": False, "audio_locked": True, "segments": [{"id": "seg-master-audio", "start_frame": 0, "end_frame": total, "content": {"media_type": "audio", "source_type": inv["source_type"], "file_path": inv["path"], "file_name": inv.get("file_name", "")}}], }) data = {"muted": False, "volume_db": 0, "task_markers": [], "task_overview": False, "tracks": tracks, "total_length": total, "frame_rate": outline["defaults"]["frame_rate"]} return data def run_embedded_suite() -> int: cases: list[tuple[str, bool, Any, Any]] = [] def check(name: str, should_pass: bool, fn: Any, *args: Any, **kwargs: Any) -> None: try: fn(*args, **kwargs) ok = should_pass detail = "" if should_pass else "passed but should have failed" except Fail as exc: ok = not should_pass detail = str(exc) if not should_pass else f"failed: {exc}" cases.append((name, ok, str(detail)[:110])) outline = _suite_outline() check("outline example", True, validate_outline, outline) rows = outline["rows"] frag1 = _suite_fragment(rows, 1, PROMPT_1) frag2 = _suite_fragment(rows, 2, PROMPT_2) frag3 = _suite_fragment(rows, 3, PROMPT_3) check("fragment 1 verbatim", True, validate_fragment, frag1, 1, 3, None, outline) check("fragment 2 chain", True, validate_fragment, frag2, 2, 3, frag1, outline) check("fragment 3 chain", True, validate_fragment, frag3, 3, 3, frag2, outline) import copy bad = copy.deepcopy(frag2) bad["start_frame"], bad["end_frame"] = 250, 490 check("frames rewrite caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag2) bad["content"]["continuity_mode"] = "shot" check("mode swap caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag2) bad["content"]["images"][0]["file_path"] = "codex/rooftop/pose_reference.png" check("path paraphrase caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag2) bad["content"]["user_prompt"] = PROMPT_2.replace("keeps the pose, motion and light it arrived with", "keeps the pose from the previous segment") check("selfref caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag2) bad["content"]["user_prompt"] = ( "A new composition opens on the skyline. She stands at the rail with coffee, wind " "moving her cardigan while the city brightens below her elbows and the cup warms " "her hands; steam lifts and bends away from the white ceramic lip in brightening " "dawn light as traffic swells beneath the rooftop terrace and pigeons scatter." ) check("no keep-opener caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag2) bad["content"]["user_prompt"] = PROMPT_2.replace( "as the turn continues.", "She comes to a stop, still as a photograph.") check("rest tail caught", False, validate_fragment, bad, 2, 3, frag1, outline) bad = copy.deepcopy(frag1) bad["content"]["user_prompt"] = "short" check("thin prompt caught", False, validate_fragment, bad, 1, 3, None, outline) bad = copy.deepcopy(frag1) bad["content"]["images"] = [{"id": f"i{n}", "source_type": "input", "file_path": "codex/rooftop/pose_ref.png"} for n in range(10)] check("ten images caught", False, validate_fragment, bad, 1, 3, None, outline) bad = copy.deepcopy(frag1) bad["content"]["continuity_mode"] = "context_swap" check("legacy context_swap caught", False, validate_fragment, bad, 1, 3, None, outline) data = _merged_track_data(outline, [frag1, frag2, frag3]) check("track_data merge", True, validate_track_data, copy.deepcopy(data), outline=outline) bad = copy.deepcopy(data) bad["tracks"][0]["segments"][1]["start_frame"] = 239 check("overlap caught", False, validate_track_data, bad, outline=outline) bad = copy.deepcopy(data) bad["tracks"][1]["audio_locked"] = False check("missing audio lock ok", True, validate_track_data, bad, outline=outline) bad = copy.deepcopy(data) bad["tracks"].append({"id": "track-song-2", "name": "Song 2", "type": "audio", "audio_locked": True, "segments": [ {"id": "s2", "start_frame": 0, "end_frame": 720, "content": {"media_type": "audio", "source_type": "input", "file_path": "codex/rooftop/song.wav"}}]}) check("two audio locks caught", False, validate_track_data, bad, outline=outline) bad = copy.deepcopy(data) bad["tracks"][1]["segments"] = [] check("locked empty track caught", False, validate_track_data, bad, outline=outline) bad = copy.deepcopy(data) bad["tracks"][0]["segments"][0]["content"]["images"] = [ {"id": "u", "source_type": "url", "file_path": "codex/rooftop/pose_ref.png"}] check("source field mismatch caught", False, validate_track_data, bad, outline=outline) drift = copy.deepcopy(outline) drift["segments"] = [ {"index": 1, "id": "drift_one", "start_seconds": 0, "duration_seconds": 10, "task_mode": "ref", "continuity_mode": "context_drift", "images": [], "beat": "The dancer replaces the silhouette through the whole phrase.", "prompt_brief": "x y z w a b"}, {"index": 2, "id": "drift_two", "start_seconds": 10, "duration_seconds": 10, "task_mode": "ref", "continuity_mode": "shot", "images": [], "beat": "The second phrase continues the replacement.", "prompt_brief": "x y z w a b"}, ] check("drift uniformity caught", False, validate_outline, drift) badres = copy.deepcopy(outline) badres["editor"]["resolution"]["aspect_ratio"] = "16:9" check("bare ratio token caught", False, validate_outline, badres) badproj = copy.deepcopy(outline) badproj["project"]["sampling_mode"] = "triple" check("bad sampling_mode caught", False, validate_outline, badproj) plan = {"editor": {"resolution": outline["editor"]["resolution"], "track_data": copy.deepcopy(data), "format": "MiniMax"}, "project": dict(outline["project"])} check("plan merge", True, validate_plan, copy.deepcopy(plan), outline=outline) bad = copy.deepcopy(plan) del bad["project"]["sampling_plan"] check("plan missing sampling_plan caught", False, validate_plan, bad, outline=outline) bad = copy.deepcopy(plan) bad["editor"]["track_data"]["total_length"] = 12 check("plan total_length recalc", True, validate_plan, bad, outline=outline) failed = [c for c in cases if not c[1]] for name, ok, detail in cases: if ok: print(f"ok {name}") else: print(f"FAIL {name}: {detail}") total_cases = len(cases) print(f"SUITE {'PASS' if not failed else 'FAIL'} ({total_cases - len(failed)}/{total_cases} cases)") return 0 if not failed else 1 # --------------------------------------------------------------------- CLI def _main(argv: list[str]) -> int: if not argv or argv[0] in {"suite", "--suite"}: return run_embedded_suite() cmd = argv[0] try: if cmd == "outline": outline = load_json(argv[1], "outline") validate_outline(outline) fps = outline["defaults"]["frame_rate"] total = outline["rows"][-1]["end_frame"] print(f"OUTLINE OK: {len(outline['rows'])} task segments, {total} frames " f"= {total / fps:.2f}s at {fps} fps, format {outline['editor']['format']!r}") return 0 if cmd == "segment": args = argv[1:] index = total = None outline_path = prev_path = None positional: list[str] = [] i = 0 while i < len(args): if args[i] == "--index": index = int(args[i + 1]); i += 2 elif args[i] == "--total": total = int(args[i + 1]); i += 2 elif args[i] == "--outline": outline_path = args[i + 1]; i += 2 elif args[i] == "--prev": prev_path = args[i + 1]; i += 2 else: positional.append(args[i]); i += 1 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]") frag = load_json(positional[0], "segment fragment") outline = None if outline_path: outline = load_json(outline_path, "outline") validate_outline(outline) if total is None and outline is not None: total = len(outline["rows"]) prev = load_json(prev_path, "previous fragment") if prev_path else None validate_fragment(frag, index, total, prev, outline) total_label = total if total is not None else "?" print(f"SEGMENT {index}/{total_label} OK: {frag['id']} frames " f"[{frag['start_frame']}, {frag['end_frame']})") return 0 if cmd == "trackdata": args = argv[1:] outline_path = None positional: list[str] = [] i = 0 while i < len(args): if args[i] == "--outline": outline_path = args[i + 1]; i += 2 else: positional.append(args[i]); i += 1 data = load_json(positional[0], "TRACK_DATA") outline = None if outline_path: outline = load_json(outline_path, "outline") validate_outline(outline) validate_track_data(data, outline=outline) task_count = sum(1 for t in data["tracks"] if t.get("type") == "task" for _ in t.get("segments", [])) print(f"TRACK_DATA OK: {task_count} task segments, total_length {data['total_length']} " f"frames = {data['total_length'] / data['frame_rate']:.2f}s at {data['frame_rate']} fps, " f"{len(data['tracks'])} tracks") return 0 if cmd == "plan": args = argv[1:] outline_path = None positional: list[str] = [] i = 0 while i < len(args): if args[i] == "--outline": outline_path = args[i + 1]; i += 2 else: positional.append(args[i]); i += 1 plan = load_json(positional[0], "patch plan") outline = None if outline_path: outline = load_json(outline_path, "outline") validate_outline(outline) data = validate_plan(plan, outline=outline) task_count = sum(1 for t in data["tracks"] if t.get("type") == "task" for _ in t.get("segments", [])) print(f"PLAN OK: {task_count} task segments, total_length {data['total_length']} " f"frames = {data['total_length'] / data['frame_rate']:.2f}s, " f"format {plan['editor'].get('format')!r}") return 0 raise Fail(f"unknown sub-command {cmd!r} (use outline/segment/trackdata/plan/suite)") except Fail as exc: print(f"FAIL: {exc}") return 1 if __name__ == "__main__": sys.exit(_main(sys.argv[1:]))