mmprompt/easy-media-track-gate/verify_track_rules.py

1910 lines
96 KiB
Python

#!/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]
override PROMPT_OVERRIDE.json --outline OUTLINE.json
validate the minimax_prompt_override paste
payload for the multitrack editor node
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_]*$")
# The multitrack editor's prompt_override input (format MiniMax) accepts exactly one JSON
# payload type. Anything else falls back to the '|'-separated text parser and renders ONE
# clip over the whole timeline — the classic single-clip failure.
OVERRIDE_TYPE = "minimax_prompt_override"
OVERRIDE_VERSION = 1
OVERRIDE_GEN_TYPES = {"r2v", "t2v", "i2v", "v2v", "l2v"}
OVERRIDE_DURATION_MIN = 2.0
OVERRIDE_DURATION_MAX = 15.0
OVERRIDE_FIELDS = {"type", "version", "prompts", "duration", "generation_type",
"continuity_mode", "system_prompt", "video_track_lock", "audio_track_lock"}
_TASK_MODE_TO_GEN = {"ref": "r2v", "l2v": "l2v", "default": "t2v"}
_PICTURE_RE = re.compile(r"<Picture\s*(\d+)\s*>", re.IGNORECASE)
_AUDIO_RE = re.compile(r"<Audio\s*(\d+)\s*>", re.IGNORECASE)
_VIDEO_RE = re.compile(r"<Video\s*(\d+)\s*>", re.IGNORECASE)
_ATREF_RE = re.compile(r"@(?:image|img|audio|video|\u56fe\u7247|\u56fe|\u97f3\u9891|\u89c6\u9891)\s*\d+", re.IGNORECASE)
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):
raise Fail(
"outline.media_inventory must be an array of media rows — use [] for a pure "
"t2v story with no media at all (no picture tokens may then appear in prompts)")
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
# ------------------------------------------------- minimax prompt_override paste
def _override_media_positions(outline: dict[str, Any]) -> dict[str, int]:
"""1-based slot position per inventory key.
The editor's prompt_override attaches media ONLY through tokens in the prompt text
(`<Picture N>` / `<Audio N>` / `<Video N>`). N is the 1-based position of the media
item in the editor's image / audio / video input list, so this gate's convention is:
wire the inventory's rows into the editor's matching input in inventory order, then
N is the row's 1-based position among the rows of its own kind.
"""
positions: dict[str, int] = {}
counters = {"image": 0, "audio": 0, "video": 0}
for key, entry in outline["inventory"].items():
counters[entry["kind"]] += 1
positions[key] = counters[entry["kind"]]
return positions
def _override_tail_values(raw: Any, count: int, *, default: str, allowed: set[str],
field: str) -> list[str]:
"""Mirror the runtime's comma-list parsing: per-segment values, tail reused."""
text = default if raw is None else str(raw).strip()
if not text:
text = default
parts = [p.strip() for p in text.split(",") if p.strip()]
if not parts:
raise Fail(f"prompt_override.{field} must contain at least one value")
values: list[str] = []
for part in parts:
norm = part.lower()
if norm not in allowed:
raise Fail(f"prompt_override.{field} value {part!r} is not one of {sorted(allowed)}")
values.append(norm)
return [values[min(i, len(values) - 1)] for i in range(count)]
def _override_durations(raw: Any, count: int) -> list[float]:
text = "10" if raw is None else str(raw).strip()
if not text:
text = "10"
parts = [p.strip() for p in text.split(",") if p.strip()]
if not parts:
raise Fail("prompt_override.duration must contain at least one value")
out: list[float] = []
for part in parts:
try:
sec = float(part)
except ValueError:
raise Fail(f"prompt_override.duration has a non-numeric value: {part!r}")
if not OVERRIDE_DURATION_MIN <= sec <= OVERRIDE_DURATION_MAX:
raise Fail(
f"prompt_override.duration value {part!r} is outside the runtime's "
f"{OVERRIDE_DURATION_MIN:g}-{OVERRIDE_DURATION_MAX:g}s window; the editor "
"rejects the paste outright at that range")
out.append(sec)
return [out[min(i, len(out) - 1)] for i in range(count)]
def build_prompt_override(outline: dict[str, Any], fragments: list[dict[str, Any]]) -> dict[str, Any]:
"""Assemble the multitrack editor's paste payload from validated fragments.
One prompt per outline row (variant b honored), media reference tokens prepended.
Minimal by construction: the node's parser (utils/prompt_override.py,
parse_minimax_prompt_override) checks ONLY `type` and `prompts`; every other key has
a code default (duration "10" seconds, generation_type "r2v", continuity_mode
"shot", both track locks 0, no system_prompt) and `version` is written by the pack's
builder node but read by nothing. A key is emitted only when the story needs a
non-default value.
"""
rows = outline["rows"]
if len(fragments) != len(rows):
raise Fail(f"expected {len(rows)} fragments (one per approved outline row), got {len(fragments)}")
positions = _override_media_positions(outline)
roles = outline["_roles"]
audio_pos = positions.get(roles["master_audio"]["key"]) if roles["master_audio"] else None
video_pos = positions.get(roles["reference_video"]["key"]) if roles["reference_video"] else None
prompts: list[str] = []
durations: list[str] = []
gen_types: list[str] = []
cont_modes: list[str] = []
for row, frag in zip(rows, fragments):
content = frag.get("content", {})
variant = content.get("user_prompt_variant", "a")
text = content.get("user_prompt_b") if variant == "b" else content.get("user_prompt")
if not isinstance(text, str) or not text.strip():
raise Fail(f"fragment {frag.get('id', '?')}: no prompt text for the override payload")
# Idempotent prepending: a fragment prompt that already carries its approved
# <Picture N>/<Audio N>/<Video N> tokens must not get them duplicated — the
# duplicated text still resolves to one slot, but it reads wrong to the model.
present_pics = {int(m.group(1)) for m in _PICTURE_RE.finditer(text)}
present_audio = {int(m.group(1)) for m in _AUDIO_RE.finditer(text)}
present_video = {int(m.group(1)) for m in _VIDEO_RE.finditer(text)}
refs = ""
for img in row.get("images", []):
pos = positions[img["key"]]
if pos not in present_pics:
refs += f"<Picture {pos}> "
if audio_pos is not None and audio_pos not in present_audio:
refs += f"<Audio {audio_pos}> "
if video_pos is not None and video_pos not in present_video:
refs += f"<Video {video_pos}> "
prompts.append(" ".join((refs + text).split()))
durations.append(f"{float(row['duration_seconds']):g}")
gen_types.append(_TASK_MODE_TO_GEN[row["task_mode"]])
cont_modes.append(row["continuity_mode"])
def _compact(values: list[str]) -> str:
return ",".join(values) if len(set(values)) > 1 else values[0]
override: dict[str, Any] = {"type": OVERRIDE_TYPE, "prompts": prompts}
duration = _compact(durations)
if duration != "10":
override["duration"] = duration
generation_type = _compact(gen_types)
if generation_type != "r2v":
override["generation_type"] = generation_type
continuity_mode = _compact(cont_modes)
if continuity_mode != "shot":
override["continuity_mode"] = continuity_mode
if video_pos is not None:
override["video_track_lock"] = 1
if audio_pos is not None:
override["audio_track_lock"] = 1
return override
def _check_override_refs(prompt: str, row: dict[str, Any], outline: dict[str, Any], where: str) -> None:
positions = _override_media_positions(outline)
inventory = outline["inventory"]
expected_pics = sorted({positions[img["key"]] for img in row.get("images", [])})
found_pics = sorted({int(m.group(1)) for m in _PICTURE_RE.finditer(prompt)})
unexpected = [n for n in found_pics if n not in expected_pics]
if unexpected:
raise Fail(
f"{where} references <Picture {unexpected[0]}> which is not one of this segment's "
f"approved images (expected {expected_pics}); a stray token attaches the wrong "
"slot image from the editor's image input")
missing = [n for n in expected_pics if n not in found_pics]
if missing:
raise Fail(
f"{where} is missing <Picture {missing[0]}>. In a prompt_override paste the images "
"are attached ONLY through these tokens — a prompt without them renders with no "
"reference images at all")
roles = outline["_roles"]
expected_audio = [positions[roles["master_audio"]["key"]]] if roles["master_audio"] else []
expected_video = [positions[roles["reference_video"]["key"]]] if roles["reference_video"] else []
found_audio = sorted({int(m.group(1)) for m in _AUDIO_RE.finditer(prompt)})
found_video = sorted({int(m.group(1)) for m in _VIDEO_RE.finditer(prompt)})
if found_audio != expected_audio:
raise Fail(
f"{where} <Audio N> refs {found_audio} != expected {expected_audio}: with a locked "
"master audio every prompt must reference the song exactly once "
"(and audio_track_lock 1); with none, no audio token may appear")
if found_video != expected_video:
raise Fail(
f"{where} <Video N> refs {found_video} != expected {expected_video}: with a locked "
"reference video every prompt must reference it exactly once "
"(and video_track_lock 1); with none, no video token may appear")
def validate_prompt_override(payload: Any, outline: dict[str, Any]) -> dict[str, Any]:
"""Validate a minimax_prompt_override payload against the approved outline."""
if not isinstance(payload, dict):
raise Fail("prompt_override must be a JSON object")
if payload.get("type") != OVERRIDE_TYPE:
raise Fail(
f"prompt_override.type must be {OVERRIDE_TYPE!r}; got {payload.get('type')!r}. "
"Any other JSON pasted into the multitrack editor's prompt_override falls back to "
"the '|'-separated text parser and renders ONE clip over the whole timeline")
# `version` is NOT required and NOT checked: parse_minimax_prompt_override never
# reads it. It stays in OVERRIDE_FIELDS so payloads from the pack's own builder
# node (which writes it) still validate here.
unknown = sorted(set(payload) - OVERRIDE_FIELDS)
if unknown:
raise Fail(f"prompt_override has unsupported fields {unknown}")
prompts = payload.get("prompts")
rows = outline["rows"]
if not isinstance(prompts, list) or not prompts:
raise Fail("prompt_override.prompts must be a non-empty list")
if len(prompts) != len(rows):
raise Fail(
f"prompt_override.prompts has {len(prompts)} entries but the approved outline has "
f"{len(rows)} segments — one prompt per segment, in order")
durations = _override_durations(payload.get("duration"), len(prompts))
gen_types = _override_tail_values(payload.get("generation_type"), len(prompts),
default="r2v", allowed=OVERRIDE_GEN_TYPES,
field="generation_type")
cont_modes = _override_tail_values(payload.get("continuity_mode"), len(prompts),
default="shot",
allowed=CONTINUITY_MODES | {"context_swap"},
field="continuity_mode")
cont_modes = ["context_drift" if m == "context_swap" else m for m in cont_modes]
for i, (row, prompt, dur, gen, cont) in enumerate(
zip(rows, prompts, durations, gen_types, cont_modes)):
where = f"prompts[{i}]"
if not isinstance(prompt, str) or not prompt.strip():
raise Fail(f"{where} must be a non-empty string")
if "|" in prompt:
raise Fail(f"{where} contains '|'; the fallback parser splits prompts on it — keep prompts pipe-free")
if _ATREF_RE.search(prompt):
raise Fail(f"{where} uses @media references; this gate's canonical form is "
"<Picture N> / <Audio N> / <Video N>")
expected_gen = _TASK_MODE_TO_GEN[row["task_mode"]]
if gen != expected_gen:
raise Fail(f"{where} generation_type {gen!r} != {expected_gen!r} for task_mode {row['task_mode']!r}")
if cont != row["continuity_mode"]:
raise Fail(f"{where} continuity_mode {cont!r} != approved {row['continuity_mode']!r}")
if abs(dur - float(row["duration_seconds"])) > 1e-6:
raise Fail(f"{where} duration {dur:g}s != approved {float(row['duration_seconds']):g}s")
prompt_rules(prompt, row["continuity_mode"], row["followed_by_join"], where)
_check_override_refs(prompt, row, outline, where)
system_prompt = payload.get("system_prompt", "")
if not isinstance(system_prompt, str):
raise Fail("prompt_override.system_prompt must be a string")
roles = outline["_roles"]
expected_audio_lock = 1 if roles["master_audio"] else 0
expected_video_lock = 1 if roles["reference_video"] else 0
for field, expected in (("audio_track_lock", expected_audio_lock),
("video_track_lock", expected_video_lock)):
value = payload.get(field, 0)
if not is_int(value) or not 0 <= int(value) <= 3:
raise Fail(f"prompt_override.{field} must be an integer 0-3")
if int(value) != expected:
label = "master audio" if field == "audio_track_lock" else "reference video"
raise Fail(
f"prompt_override.{field} must be {expected}: the outline "
+ ("locks a " + label + " track (reference it in every prompt and lock slot 1)"
if expected else "has no " + label + ", so there is nothing to lock"))
return payload
# --------------------------------------------- plain-text prompt_override paste
# The editor's fallback path (nodes/basic.py -> build_multitrack_data_from_prompt_override
# -> parse_override_segments in utils/prompt_override.py) splits a non-JSON prompt_override
# on '|': one task segment per part, a trailing '|' a no-op. Per-part extras the pack's
# parser lifts OUT of the text: a trailing [s-e] / [s-e,type] frame-range marker (ANY
# [number-number] pattern anywhere in a scene is eaten as a marker — prose must avoid it),
# and @imageN/@audioN/@videoN media references. The <Picture N> bracket tokens are
# JSON-only and stay literal text in this path. Proven against the pack's code
# (parse_override_segments + build_multitrack_data_from_prompt_override).
_TASK_MODE_TO_TEXT_TYPE = {"ref": "r2v", "l2v": "l2v", "default": "flf"}
_TEXT_TYPES = {"flf", "fmlf", "ref", "l2v", "v2v", "i2v", "rv2v", "vi2v", "r2v"}
_TEXT_MARKER_RE = re.compile(
r"\[\s*(\d+(?:\.\d+)?)\s*(s?)\s*-\s*(\d+(?:\.\d+)?)\s*(s?)\s*(?:,\s*(\w+)\s*)?\]")
_AT_IMAGE_RE = re.compile(r"@(?:image|img|图片|图)\s*(\d+)", re.IGNORECASE)
_AT_AUDIO_RE = re.compile(r"@(?:audio|音频)\s*(\d+)", re.IGNORECASE)
_AT_VIDEO_RE = re.compile(r"@(?:video|视频)\s*(\d+)", re.IGNORECASE)
def _text_marker_values(match: "re.Match[str]", fps: int) -> tuple[int, int, str | None]:
"""[s-e(,type)] -> (start_frame, end_frame, type). Seconds forms ([1.5s-3s]) convert
at the outline's frame rate with the pack's 4-frame quanta."""
s_val, s_suf, e_val, e_suf, typ = match.groups()
start = float(s_val)
end = float(e_val)
if s_suf:
start = int(round(start * fps / 4.0)) * 4
if e_suf:
end = int(round(end * fps / 4.0)) * 4
norm_type = typ.lower() if typ else None
if norm_type is not None and norm_type not in _TEXT_TYPES:
raise Fail(f"[s-e] marker type {typ!r} is not a pack task type "
f"(one of {sorted(_TEXT_TYPES)})")
return int(start), int(end), norm_type
def _check_text_refs(scene: str, row: dict[str, Any], outline: dict[str, Any],
where: str) -> None:
"""@-media contract of the plain-text path (mirror of _check_override_refs)."""
positions = _override_media_positions(outline)
expected_pics = sorted({positions[img["key"]] for img in row.get("images", [])})
found_pics = sorted({int(m.group(1)) for m in _AT_IMAGE_RE.finditer(scene)})
unexpected = [n for n in found_pics if n not in expected_pics]
if unexpected:
raise Fail(
f"{where} references @image{unexpected[0]} which is not one of this segment's "
f"approved images (expected {expected_pics}); a stray @ref attaches the wrong "
"slot image from the editor's image input")
missing = [n for n in expected_pics if n not in found_pics]
if missing:
raise Fail(
f"{where} is missing @image{missing[0]}. In the plain-text paste the images are "
"attached ONLY through @imageN/@audioN/@videoN tokens — a scene without them "
"renders with no reference images at all")
roles = outline["_roles"]
expected_audio = [positions[roles["master_audio"]["key"]]] if roles["master_audio"] else []
expected_video = [positions[roles["reference_video"]["key"]]] if roles["reference_video"] else []
found_audio = sorted({int(m.group(1)) for m in _AT_AUDIO_RE.finditer(scene)})
found_video = sorted({int(m.group(1)) for m in _AT_VIDEO_RE.finditer(scene)})
if found_audio != expected_audio:
raise Fail(
f"{where} @audio refs {found_audio} != expected {expected_audio}: with a locked "
"master audio every scene must reference the song exactly once; with none, no "
"audio @ref may appear")
if found_video != expected_video:
raise Fail(
f"{where} @video refs {found_video} != expected {expected_video}: with a locked "
"reference video every scene must reference it exactly once; with none, no "
"video @ref may appear")
def validate_prompt_override_text(text: str, outline: dict[str, Any]) -> list[str]:
"""Validate a PLAIN-TEXT prompt_override paste ('scene1|scene2|...', spaces around
the pipes are stripped by the parser) against the approved outline — the editor's
fallback-parser contract plus this gate's outline pins. Returns the marker-stripped
scene texts."""
rows = outline["rows"]
fps = outline["defaults"]["frame_rate"]
raw = text.strip()
if raw.startswith("{"):
raise Fail("this paste is JSON: validate it as the JSON payload (it must carry "
f"\"type\": {OVERRIDE_TYPE!r}) — pasted as plain text it would parse as "
"ONE scene over the whole timeline")
parts = [p.strip() for p in raw.split("|")]
parts = [p for p in parts if p]
if not parts:
raise Fail("plain-text prompt_override is empty — paste 'scene1 | scene2 | ...'")
if len(parts) != len(rows):
raise Fail(
f"plain-text paste splits into {len(parts)} scenes but the approved outline has "
f"{len(rows)} segments — one scene per '|'-chunk, in order (a missing '|' "
"renders the whole story as ONE clip)")
equal_rows = len({float(r["duration_seconds"]) for r in rows}) == 1
scenes: list[str] = []
marker_flags: list[bool] = []
for i, (part, row) in enumerate(zip(parts, rows)):
where = f"scene {i + 1}"
matches = list(_TEXT_MARKER_RE.finditer(part))
if len(matches) > 1:
raise Fail(
f"{where}: {len(matches)} [number-number] patterns found — the pack's parser "
"eats every one as a frame-range marker. Keep exactly one [s-e(,type)] marker "
"at the scene end and no [number-number] prose anywhere in the scene")
body = part
marker = None
if matches:
match = matches[0]
if match.end() != len(part):
raise Fail(
f"{where}: the [s-e(,type)] marker must sit at the very END of the scene "
"(the parser strips only a trailing marker; text after it reaches the "
"model, text before it gets eaten as a frame range)")
start_f, end_f, typ = _text_marker_values(match, fps)
expected_start, expected_end = row["start_frame"], row["end_frame"]
if (start_f, end_f) != (expected_start, expected_end):
raise Fail(
f"{where}: marker [{start_f}-{end_f}] != approved row frames "
f"[{expected_start}-{expected_end}] (start_seconds "
f"{row['start_seconds']:g} + duration_seconds "
f"{float(row['duration_seconds']):g} at {fps} fps)")
expected_type = _TASK_MODE_TO_TEXT_TYPE[row["task_mode"]]
if expected_type != "flf" and typ is None:
raise Fail(
f"{where}: task_mode {row['task_mode']!r} renders as TYPE "
f"{expected_type} only with an explicit suffix — end the scene with "
f"[{start_f}-{end_f},{expected_type}]")
if typ is not None and typ != expected_type:
raise Fail(
f"{where}: marker type {typ!r} != {expected_type!r} for task_mode "
f"{row['task_mode']!r}")
body = part[:match.start()].rstrip()
marker = True
if not body:
raise Fail(f"{where} is only a marker — a scene still needs its prompt text")
if _PICTURE_RE.search(body) or _AUDIO_RE.search(body) or _VIDEO_RE.search(body):
raise Fail(
f"{where}: <Picture N>/<Audio N>/<Video N> tokens are JSON-only — the "
"plain-text parser leaves them as literal text in the prompt. Use "
"@imageN/@audioN/@videoN here, or deliver the JSON payload for this story")
residual = _ATREF_RE.sub("", body)
if "@" in residual:
raise Fail(
f"{where} contains a stray '@': the parser strips it (and eats @imageN/"
"@audioN/@videoN as media references) — keep '@' out of scene prose")
prompt_rules(body, row["continuity_mode"], row["followed_by_join"], where)
_check_text_refs(body, row, outline, where)
scenes.append(body)
marker_flags.append(marker is not None)
if any(marker_flags) and not all(marker_flags):
raise Fail(
"markers must be all-or-nothing: scenes with explicit [s-e] ranges and scenes "
"without them mix two unproven split behaviors — give every scene a marker")
if not any(marker_flags) and not equal_rows:
raise Fail(
"the outline's rows have unequal durations but no scene carries a [start-end] "
"marker: without markers the editor splits its total_length EVENLY across "
"scenes — add [s-e(,type)] markers or equalize the rows")
return scenes
def build_plain_text_override(outline: dict[str, Any], fragments: list[dict[str, Any]]) -> str:
"""Assemble the plain-text paste: raw scene prompts joined with '|' (no padding —
byte-identical to the proven paste form), one per outline row.
Unlike build_prompt_override this keeps the fragment text VERBATIM: the text path
preserves newlines INSIDE a scene (only '|' splits), so the multi-section prompt
structure survives — do not feed it the JSON payload's whitespace-collapsed prompts.
Markers ([start-end] / [start-end,type], the form the pack's parser lifts) are added
when the rows have unequal durations (the markerless form splits the editor's
total_length evenly) or any scene's task type differs from the text default
(flf -> t2v). Zero-media stories only: <Picture N> tokens are JSON-only.
"""
rows = outline["rows"]
if len(fragments) != len(rows):
raise Fail(f"expected {len(rows)} fragments (one per approved outline row), got {len(fragments)}")
texts: list[str] = []
for frag in fragments:
content = frag.get("content", {})
variant = content.get("user_prompt_variant", "a")
text = content.get("user_prompt_b") if variant == "b" else content.get("user_prompt")
if not isinstance(text, str) or not text.strip():
raise Fail(f"fragment {frag.get('id', '?')}: no prompt text for the plain-text paste")
texts.append(text.strip())
equal_rows = len({float(r["duration_seconds"]) for r in rows}) == 1
needs_types = any(_TASK_MODE_TO_TEXT_TYPE[r["task_mode"]] != "flf" for r in rows)
if equal_rows and not needs_types:
return "|".join(texts)
parts = []
for row, text in zip(rows, texts):
typ = _TASK_MODE_TO_TEXT_TYPE[row["task_mode"]]
suffix = f",{typ}" if typ != "flf" else ""
parts.append(f"{text} [{row['start_frame']}-{row['end_frame']}{suffix}]")
return "|".join(parts)
# ------------------------------------------------------------------- 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 _suite_text_outline() -> dict[str, Any]:
"""Zero-media two-scene outline: the shape the plain-text paste covers."""
return {
"title": "plain_text_two_shot",
"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": [],
"tracks": {"master_audio": None, "reference_video": None},
"project": {"project_save": "new", "segment_start_number": 1,
"segment_count": -1, "sampling_plan": "medium", "sampling_mode": "single"},
"segments": [
{"index": 1, "id": "text_harbor_open", "start_seconds": 0, "duration_seconds": 10,
"task_mode": "default", "continuity_mode": "shot", "images": [],
"beat": "Mia strides the wet pier as gulls lift; ends with the boat sliding out.",
"prompt_brief": "Self-contained dawn harbor shot; keep her stride; end mid-motion."},
{"index": 2, "id": "text_lighthouse_run", "start_seconds": 10, "duration_seconds": 10,
"task_mode": "default", "continuity_mode": "shot", "images": [],
"beat": "Mia climbs to the lighthouse walk and breaks into a run; ends running.",
"prompt_brief": "Self-contained midday shot; wind presses; end mid-run."},
],
}
TEXT_PROMPT_1 = (
"Dawn light spills over a quiet harbor as Mia steps onto the wet stone pier, her yellow "
"raincoat swinging with each stride; gulls lift off the pilings while she steadies a "
"coiled rope against her hip, the tide swelling green beneath the planks, and the camera "
"tracks slowly beside her as the first fishing boat slides out toward the open water.")
TEXT_PROMPT_2 = (
"Midday sun hardens over the quiet harbor as Mia climbs the wooden stairs to the "
"lighthouse walk, her boots drumming the planks while wind presses the raincoat flat "
"against her back; she raises one hand against the glare, watches a ferry cut a white "
"line across the bay, and breaks into a run along the railing as the horn sounds below.")
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)
override = build_prompt_override(outline, [frag1, frag2, frag3])
check("override build+validate", True, validate_prompt_override,
copy.deepcopy(override), outline)
bad = copy.deepcopy(override)
bad["type"] = "plan"
check("override wrong type caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["duration"] = "30"
check("override duration over 15s caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["duration"] = "5"
check("override duration off outline caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["continuity_mode"] = "shot"
check("override mode off outline caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["prompts"][1] = bad["prompts"][1].replace("<Picture 1>", "", 1)
check("override missing picture ref caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["prompts"][0] = bad["prompts"][0] + " She watches <Picture 2> drift closer."
check("override stray picture ref caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["prompts"][0] = bad["prompts"][0].replace("<Audio 1>", "@audio1", 1)
check("override @ref caught", False, validate_prompt_override, bad, outline)
bad = copy.deepcopy(override)
bad["audio_track_lock"] = 0
check("override audio lock zeroed caught", False, validate_prompt_override, bad, outline)
# ---- plain-text paste path (the editor's fallback parser + outline pins) ----
text_outline = _suite_text_outline()
check("text outline example", True, validate_outline, text_outline)
plain = f"{TEXT_PROMPT_1} | {TEXT_PROMPT_2}"
check("text override even split", True, validate_prompt_override_text, plain, text_outline)
marked = f"{TEXT_PROMPT_1} [0-240] | {TEXT_PROMPT_2} [240-480]"
check("text override frame markers", True, validate_prompt_override_text, marked, text_outline)
built = build_plain_text_override(
text_outline,
[{"content": {"user_prompt": TEXT_PROMPT_1}}, {"content": {"user_prompt": TEXT_PROMPT_2}}])
check("text override builder roundtrip", True, validate_prompt_override_text, built, text_outline)
bad = f"{TEXT_PROMPT_1} | {TEXT_PROMPT_2} | {TEXT_PROMPT_1}"
check("text override scene count caught", False, validate_prompt_override_text, bad, text_outline)
bad = f"{TEXT_PROMPT_1} [0-240] | {TEXT_PROMPT_2}"
check("text override mixed markers caught", False, validate_prompt_override_text, bad, text_outline)
bad = f"{TEXT_PROMPT_1} [0-300] | {TEXT_PROMPT_2} [240-480]"
check("text override marker frames caught", False, validate_prompt_override_text, bad, text_outline)
bad = f"{TEXT_PROMPT_1} [0-240,r2v] | {TEXT_PROMPT_2} [240-480,r2v]"
check("text override marker type caught", False, validate_prompt_override_text, bad, text_outline)
uneven = copy.deepcopy(text_outline)
uneven["rows"][1]["duration_seconds"] = 15
check("text override uneven no markers caught", False,
validate_prompt_override_text, plain, uneven)
bad = f"{TEXT_PROMPT_1} <Picture 1> | {TEXT_PROMPT_2}"
check("text override bracket token caught", False, validate_prompt_override_text, bad, text_outline)
bad = f"{TEXT_PROMPT_1} @image1 | {TEXT_PROMPT_2}"
check("text override @media without inventory caught", False,
validate_prompt_override_text, bad, text_outline)
bad = f"{TEXT_PROMPT_1} meet @ the pier | {TEXT_PROMPT_2}"
check("text override stray @ caught", False, validate_prompt_override_text, bad, text_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
if cmd == "override":
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
if not positional or not outline_path:
raise Fail("usage: override PROMPT_OVERRIDE.(txt|json) --outline outline.json")
outline = load_json(outline_path, "outline")
validate_outline(outline)
raw_text = Path(positional[0]).read_text(encoding="utf-8")
total_s = sum(float(r["duration_seconds"]) for r in outline["rows"])
fmt = outline["editor"]["format"]
if raw_text.lstrip().startswith("{"):
payload = load_json(positional[0], "prompt_override payload")
validate_prompt_override(payload, outline)
print(f"OVERRIDE OK (JSON payload): {len(payload['prompts'])} prompts, "
f"duration {payload.get('duration', '10 (default)')}, "
f"total {total_s:.2f}s at {outline['defaults']['frame_rate']} fps — paste into "
f"the multitrack editor's prompt_override input (format {fmt!r})")
else:
scenes = validate_prompt_override_text(raw_text, outline)
marked = " with [start-end,type] markers" if "[" in raw_text else ""
print(f"OVERRIDE OK (plain text): {len(scenes)} scenes split on '|'{marked}, "
f"total {total_s:.2f}s at {outline['defaults']['frame_rate']} fps — paste into "
f"the multitrack editor's prompt_override input (format {fmt!r})")
return 0
raise Fail(f"unknown sub-command {cmd!r} (use outline/segment/trackdata/plan/override/suite)")
except Fail as exc:
print(f"FAIL: {exc}")
return 1
if __name__ == "__main__":
sys.exit(_main(sys.argv[1:]))