ffmpeg-skill 3.6.4 → 3.6.5

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.6.4`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.5`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.6.4", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.5", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.4",
+  "version": "3.6.5",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [

package/scripts/_common/asr.py

@@ -9,7 +9,7 @@ why it is its own file.
 """
 from __future__ import annotations
 
-import json
+import math
 import os
 import re
 import unicodedata
@@ -18,7 +18,7 @@ from typing import Any, Dict, List, NamedTuple, Optional, Tuple
 
 from _common.decision import _unspaced_script, fmt_srt_time, parse_time
 from _common.emit import die, info, warn
-from _common.runner import read_text_or_die
+from _common.runner import parse_json, read_json, read_text_or_die
 
 # The engines this skill knows how to drive, and how to install each -- one string, so every
 # tool that needs a transcript refuses in the same words. The two Parakeet engines are
@@ -85,26 +85,60 @@ class Transcription:
                 f"facts={self.facts!r}, notes={self.notes!r})")
 
 
+# A line that starts a cue even with no blank line before it: a clock time, "-->", a clock time,
+# then nothing or whitespace (ffmpeg's position fields, X1:.. Y1:..). ffmpeg's SRT demuxer starts
+# an event at every such line; the first line of a block holding "-->" is a timing line whatever
+# its shape.
+_SRT_CUE_START = re.compile(r"^\s*\d+:\d+[\d:.,]*\s*-->\s*\d+:\d+[\d:.,]*(\s|$)")
+
+
+def srt_blocks(text: str) -> List[Tuple[str, List[str]]]:
+    """(timing line, text lines) of every cue in SRT text whose line ends are already `\\n`.
+
+    A blank (or whitespace-only) line ends a cue, and the first line holding "-->" in a run of
+    lines is its timing line; the lines before it (the index) are not text. Inside a run, a later
+    line shaped like a timing line (_SRT_CUE_START) starts the next cue, and a bare number just
+    before it is that cue's index, so an SRT written without blank lines between cues reads as
+    ffmpeg reads it rather than as one cue. A later line that merely contains "-->" is text."""
+    out: List[Tuple[str, List[str]]] = []
+    for run in re.split(r"\n\s*\n", text):
+        lines = [ln for ln in run.split("\n") if ln.strip()]
+        first = next((i for i, ln in enumerate(lines) if "-->" in ln), None)
+        if first is None:
+            continue
+        timing, body = lines[first], []
+        for ln in lines[first + 1:]:
+            if _SRT_CUE_START.match(ln):
+                if body and body[-1].strip().isdigit():
+                    body.pop()
+                out.append((timing, body))
+                timing, body = ln, []
+            else:
+                body.append(ln)
+        out.append((timing, body))
+    return out
+
+
+def srt_timing_times(line: str) -> Tuple[str, str]:
+    """The start and end tokens of an SRT timing line: what is before the first "-->", and the
+    first word after it. ffmpeg reads the two times and ignores the rest (position fields
+    `X1:.. X2:.. Y1:.. Y2:..`, or a stray second "-->")."""
+    a, _sep, b = line.partition("-->")
+    words = b.split()
+    return a.strip(), words[0] if words else ""
+
+
 def parse_srt(path: str) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
-    block: List[str] = []
-    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
-    for line in content.split("\n"):
-        if line.strip():
-            block.append(line)
-            continue
-        if block:
-            times = next((b for b in block if "-->" in b), None)
-            if times:
-                a, b = times.split("-->")
-                text = "\n".join(block[block.index(times) + 1:]).strip()
-                try:
-                    cues.append((parse_time(a), parse_time(b), text))
-                except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
-                    die(f"{path}: cannot read the timing line {times.strip()!r}: {e}")
-            block = []
+    for times, body in srt_blocks(read_text_or_die(path, "--srt")):
+        a, b = srt_timing_times(times)
+        text = "\n".join(body).strip()
+        try:
+            cues.append((parse_time(a), parse_time(b), text))
+        except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
+            die(f"{path}: cannot read the timing line {times.strip()!r}: {e}", kind="input")
     if not cues:
-        die(f"no cues found in {path}")
+        die(f"no cues found in {path}", kind="input")
     return cues
 
 
@@ -204,8 +238,9 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             # line with two adjacent pipes ("a||b") becomes "a\n\nb" -- and writing that blank line
             # raw would split one cue into two malformed half-blocks (the second missing its own
             # index/timecode). Collapse any run of blank lines within the cue text to a single
-            # newline so the cue's own text can never fake the format's block boundary.
-            t = re.sub(r"\n{2,}", "\n", t).strip("\n")
+            # newline so the cue's own text can never fake the format's block boundary. A line of
+            # only spaces or tabs is blank to every SRT reader too, so it goes the same way.
+            t = "\n".join(ln for ln in t.split("\n") if ln.strip())
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
     # under batch.py: this SRT as written is the run's own (an edit made after it is not)
     from _common.runner import report_committed
@@ -476,20 +511,24 @@ def whisper_word_timings(srt_path: Optional[str]) -> List[Tuple[float, float, st
         if not os.path.exists(cand):
             continue
         try:
-            data = json.loads(Path(cand).read_text(encoding="utf-8"))
+            data = read_json(cand)
         except (OSError, ValueError):
             continue
+        # the shape is not checked first: a segment that is a string or a list, or "segments" that
+        # is a number, is simply no words, as _dicts() reads every engine's JSON
         raw = []
         if isinstance(data, dict):
-            raw = list(data.get("words") or [])
-            for seg in data.get("segments") or []:
-                raw.extend((seg or {}).get("words") or [])
+            raw = _dicts(data.get("words"))
+            for seg in _dicts(data.get("segments")):
+                raw.extend(_dicts(seg.get("words")))
         words = []
         for w in raw:
             try:
                 text = str(w.get("word") or w.get("text") or "").strip()
-                if text:
-                    words.append((float(w["start"]), float(w["end"]), text))
+                start, end = float(w["start"]), float(w["end"])
+                # NaN / Infinity are valid to json.loads and place no word anywhere
+                if text and math.isfinite(start) and math.isfinite(end):
+                    words.append((start, end, text))
             except (AttributeError, KeyError, TypeError, ValueError):
                 continue
         if words:
@@ -519,12 +558,12 @@ def _words_from_whisper_cpp_json(path: str) -> "List[Dict[str, Any]]":
     boundaries). A token that is part of a character (U+FFFD) is still glued.
     """
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
-    for seg in (doc.get("transcription") or []):
-        for tok in (seg.get("tokens") or []):
+    for seg in _dicts(doc.get("transcription")) if isinstance(doc, dict) else []:
+        for tok in _dicts(seg.get("tokens")):
             text = str(tok.get("text") or "")
             if not text.strip() or text.strip().startswith("[_"):
                 continue
@@ -552,7 +591,7 @@ def _whisper_json_language(path: str) -> Optional[str]:
     """The language a Whisper engine's JSON says it decoded: whisper.cpp's `result.language`, or
     openai-whisper's top-level `language`. None when the file has neither."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8")) or {}
+        doc = read_json(path) or {}
         lang = str(((doc.get("result") or {}).get("language")) or doc.get("language") or "").strip().lower()
     except (OSError, ValueError, AttributeError):
         return None
@@ -568,12 +607,12 @@ def _heard_language(heard: list) -> Optional[str]:
 def _words_from_openai_whisper_json(path: str) -> "List[Dict[str, Any]]":
     """openai-whisper --word_timestamps True --output_format json: segments[].words[]."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
-    for seg in (doc.get("segments") or []):
-        for w in (seg.get("words") or []):
+    for seg in _dicts(doc.get("segments")) if isinstance(doc, dict) else []:
+        for w in _dicts(seg.get("words")):
             try:
                 out.append({"word": str(w.get("word") or w.get("text") or "").strip(),
                             "start": float(w["start"]), "end": float(w["end"])})
@@ -592,7 +631,7 @@ def _words_from_parakeet_mlx_json(path: str) -> "List[Dict[str, Any]]":
     after it starts a word too (" m" "is" "ter" " " "Q" "u" "il" "ter" -> "mister", "Quilter").
     """
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     out: "List[Dict[str, Any]]" = []
@@ -619,7 +658,7 @@ def _words_from_parakeet_mlx_json(path: str) -> "List[Dict[str, Any]]":
 def _cues_from_parakeet_mlx_json(path: str) -> List[Tuple[float, float, str]]:
     """parakeet-mlx's own sentence segmentation, as cues."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return []
     cues: List[Tuple[float, float, str]] = []
@@ -642,7 +681,7 @@ def _dicts(value: Any) -> "List[Dict[str, Any]]":
 def _words_from_parakeet_cpp_json(text: str) -> "List[Dict[str, Any]]":
     """parakeet-cli transcribe --json: {"words": [{"w", "start", "end", "conf"}]}, times in seconds."""
     try:
-        doc = json.loads(text)
+        doc = parse_json(text)
     except ValueError:
         return []
     out: "List[Dict[str, Any]]" = []
@@ -978,7 +1017,7 @@ def _heard_nothing(text: str, key: str) -> bool:
     Anything else that yields no words -- not JSON, the wrong shape, entries that do not parse --
     is output that could not be read, not a finding that nobody spoke."""
     try:
-        doc = json.loads(text)
+        doc = parse_json(text)
     except ValueError:
         return False
     return isinstance(doc, dict) and doc.get(key) == []
@@ -990,7 +1029,7 @@ def _whisper_heard_nothing(path: str, key: str) -> bool:
     no speech (#414). A document with text and no word timings is a build without them, not
     silence, and stays the "no word-level timings" refusal."""
     try:
-        doc = json.loads(Path(path).read_text(encoding="utf-8"))
+        doc = read_json(path)
     except (OSError, ValueError):
         return False
     if not isinstance(doc, dict) or not isinstance(doc.get(key), list):

package/scripts/_common/decision.py

@@ -6,7 +6,6 @@ and encoder-selection rules testable on their own.
 """
 from __future__ import annotations
 
-import json
 import math
 import os
 import re
@@ -17,6 +16,7 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import (as_limited, bt709_label_filter, bt709_matrix_args, bt709_matrix_filter, bt709_tag_args, drawn_stream_format,
                            is_neutral_color, limited_range_filter, rgb_island, rgb_to_bt709_filter, _sdr_bt709)
 from _common.emit import die, record_fallback, refuse, warn
+from _common.runner import read_json
 from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_list_error, ffmpeg_version, hw_platform_reason
 
 
@@ -1025,13 +1025,29 @@ def load_brand(path: Optional[str]) -> Dict[str, Any]:
     if not path:
         return brand
     if not os.path.exists(path):
-        die(f"brand file not found: {path}")
+        die(f"brand file not found: {path}", kind="input")
     try:
-        data = json.loads(Path(path).read_text(encoding="utf-8"))
-    except ValueError as exc:
-        die(f"brand file is not valid JSON: {exc}")
+        data = read_json(path)
+    except OSError as exc:
+        die(f"brand file {path} cannot be read: {exc.strerror or exc}", kind="input")
+    except ValueError as exc:  # malformed, not UTF-8, or nested too deep (read_json)
+        die(f"brand file is not valid JSON: {exc}", kind="input")
+    if not isinstance(data, dict):
+        die(f"brand file {path} must be a JSON object {{...}}, got {type(data).__name__}", kind="input")
+    # the shapes the readers below and brand_caption_style() walk: a block that is not an object,
+    # and a path that is not a string, were a traceback there
+    for key, value in (*data.items(), ("styles.caption", (data.get("styles") or {}).get("caption")
+                                       if isinstance(data.get("styles"), dict) else None)):
+        if value is None:
+            continue
+        if (isinstance(BRAND_DEFAULTS.get(key), dict) or key == "styles.caption") and not isinstance(value, dict):
+            die(f'brand file {path}: "{key}" must be an object {{...}}, got {type(value).__name__}', kind="input")
+        if key in ("logo", "font_file", "font") and not isinstance(value, str):
+            die(f'brand file {path}: "{key}" must be a string, got {type(value).__name__}', kind="input")
     base = Path(path).resolve().parent
     for k, v in data.items():
+        if v is None and isinstance(brand.get(k), dict):
+            continue  # a null block keeps its defaults: readers walk it as an object (#483 review)
         if isinstance(v, dict) and isinstance(brand.get(k), dict):
             brand[k].update(v)
         else:

package/scripts/_common/runner.py

@@ -2487,15 +2487,27 @@ def _read_ff_list(flag: str, pattern: str) -> set:
     return names
 
 
+_LINE_END = re.compile(r"\r*\n|\r")
+
+
+def normalize_text(text: str) -> str:
+    """A caller's text as every reader here takes it: a leading UTF-8 BOM dropped, and every line
+    ending `\\n`. `\\r\\r\\n` is one line end, as ffmpeg's text demuxers read it (a CRLF file passed
+    through a second CRLF conversion); a lone `\\r` (classic Mac) is one too. Only these: a line is
+    never split at U+2028, U+0085, \\v or \\f, which str.splitlines() also splits at."""
+    return _LINE_END.sub("\n", text.lstrip("\ufeff"))
+
+
 def read_text_or_die(path: str, flag: str) -> str:
     """Read a caller-supplied UTF-8 text file (a cue list, chapters, notes) or fail as kind input
-    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback."""
+    with the flag named, instead of a FileNotFoundError / UnicodeDecodeError traceback. The text
+    comes back through normalize_text(): no BOM, `\\n` line ends."""
     if os.path.isdir(path):
         # checked first: Windows raises PermissionError, not IsADirectoryError, for a directory
         die(f"{flag}: {path} is a directory, not a text file")
     try:
-        with open(path, "r", encoding="utf-8") as fh:
-            return fh.read()
+        with open(path, "r", encoding="utf-8", newline="") as fh:
+            return normalize_text(fh.read())
     except FileNotFoundError:
         die(f"{flag}: {path} does not exist")
     except IsADirectoryError:
@@ -2507,6 +2519,44 @@ def read_text_or_die(path: str, flag: str) -> str:
     return ""  # unreachable
 
 
+# Deeper than any project, recipe, brand, plan or transcript this skill reads (those are four or
+# five levels); a file nested past it is refused before code that walks it recursively
+# (copy.deepcopy, json.dumps) can raise RecursionError.
+JSON_MAX_DEPTH = 64
+
+
+class JsonTooDeep(ValueError):
+    """parse_json()'s refusal of a document nested past JSON_MAX_DEPTH: a ValueError, so callers
+    that catch ValueError refuse it as malformed JSON; one that falls back on a non-JSON file (a
+    media file) can tell this apart, since the file was JSON."""
+
+
+def parse_json(text: str) -> Any:
+    """json.loads for a caller's file: a BOM is dropped, and every way the text can fail to be a
+    document this skill can walk raises ValueError -- malformed JSON (json's own ValueError),
+    nesting too deep for the parser (RecursionError) or deeper than JSON_MAX_DEPTH. Callers that
+    already catch ValueError therefore refuse all three as they refuse malformed JSON."""
+    try:
+        data = json.loads(text.lstrip("\ufeff"))
+    except RecursionError:
+        raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep") from None
+    stack = [(data, 1)]
+    while stack:
+        value, depth = stack.pop()
+        if isinstance(value, (dict, list)):
+            if depth > JSON_MAX_DEPTH:
+                raise JsonTooDeep(f"nested more than {JSON_MAX_DEPTH} levels deep")
+            stack.extend((v, depth + 1) for v in (value.values() if isinstance(value, dict) else value))
+    return data
+
+
+def read_json(path: "os.PathLike[str] | str") -> Any:
+    """parse_json() of a UTF-8 file. Raises OSError for a file that cannot be read and ValueError
+    (UnicodeDecodeError is one) for anything else, so `except (OSError, ValueError)` covers it."""
+    with open(path, "r", encoding="utf-8") as fh:
+        return parse_json(fh.read())
+
+
 # Deferred to the foot of the module on purpose. runner is the first module the package loads and
 # emit needs runner's Context/STATE/ERROR_CODE, so the two form a cycle that has to be cut
 # somewhere: by the time this line runs every name emit reads from runner above is defined, and

package/scripts/_contract.py

@@ -443,6 +443,8 @@ ERROR_REASONS = {
     "plan_unknown_tool": "render.py PLAN: the plan names no tool render.py can run; details: {plan, plan_sha256, checked_at, tool, audit_log}",
     "plan_cwd_missing": "render.py PLAN: the directory the plan was made in is gone; details: {plan, plan_sha256, checked_at, cwd, audit_log}",
     "plan_argv_invalid": "render.py PLAN: argv is not a list; details: {plan, plan_sha256, checked_at, argv_type, audit_log}",
+    "plan_field_invalid": "render.py PLAN: inputs, unbound_inputs, verify (objects), commands (strings) or cwd has the wrong JSON type; "
+                          "details: {plan, plan_sha256, checked_at, field, field_type, audit_log}",
     "decoder_missing": "color.py / graphics.py / overlay.py: a VP9 source or --video layer stored with an alpha layer, on a build with no libvpx-vp9 decoder (FFmpeg's own VP9 decoder drops the alpha), kind missing_tool; details: {name}",
     "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
     "asr_engine_missing": "kind missing_tool: --transcribe (caption.py; silence.py with --filler or a sentence flag) found no local speech-to-text engine; the message lists the install lines; details: {}",

package/scripts/batch.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw,
+from _common.runner import (HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             owned_identity, stop_children)
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 from _common.decision import rebase_project_paths
@@ -235,6 +235,39 @@ def intermediate_ext(src: Path) -> str:
     return src.suffix.lstrip(".") if src.suffix.lower() in (".wav", ".mp3", ".m4a", ".flac") else "mp4"
 
 
+# the recipe keys the run reads as a string: a path, a glob, a file-name part
+RECIPE_STRINGS = ("glob", "project", "output_dir", "suffix", "ext")
+
+
+def check_recipe_types(recipe: Dict[str, Any]) -> None:
+    """Refuse a recipe value of the wrong JSON type before anything runs (A18): a number where a
+    path or glob goes, an absolute glob (pathlib refuses it), a step that is not a list. Each was
+    a traceback, or a failure of every item naming the step's first character."""
+    for key in RECIPE_STRINGS:
+        value = recipe.get(key)
+        if value is not None and not isinstance(value, str):
+            die(f'recipe "{key}" must be a string, got {type(value).__name__} {value!r:.60}', kind="input")
+    glob = recipe.get("glob")
+    if glob and (os.path.isabs(glob) or glob.startswith(("/", "\\"))):
+        die(f'recipe "glob" {glob!r} is an absolute path: it matches names inside the batch folder, e.g. "*.mp4" '
+            'or "sub/*.mov"', kind="input")
+    key = recipe.get("clip_key")
+    try:
+        index = int(key) if key is not None and not isinstance(key, (bool, float)) else (0 if key is None else -1)
+    except (TypeError, ValueError):
+        index = -1
+    if index < 0:
+        die(f'recipe "clip_key" must be a clip index (0, 1, ...), got {key!r:.60}', kind="input")
+    steps = recipe.get("steps")
+    if steps is not None and not isinstance(steps, list):
+        die(f'recipe "steps" must be a list of steps, each ["script.py", args...], got {type(steps).__name__}',
+            kind="input")
+    for i, st in enumerate(steps or []):
+        if not isinstance(st, list) or not st:
+            die(f'recipe step {i} must be a list ["script.py", args...], got {type(st).__name__} {st!r:.60}',
+                kind="input")
+
+
 def step_writes(step: Any) -> bool:
     """Whether a recipe step writes a file: it names {out} (check.py and probe.py do not)."""
     return isinstance(step, list) and any("{out}" in str(a) for a in step[1:])
@@ -382,14 +415,14 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         return max(1.0, deadline - time.monotonic())
     if recipe.get("project"):
         try:
-            proj = json.loads(Path(str(recipe["project"])).read_text(encoding="utf-8"))
+            proj = read_json(str(recipe["project"]))  # too deep is a ValueError too (A20)
         except (OSError, ValueError) as e:
             raise ItemError({"step": None, "tool": "render.py", "kind": "input", "reason": "recipe_project_unreadable",
                              "message": f"recipe.project: {recipe['project']} could not be read as JSON: {e}"})
         if not isinstance(proj, dict):
             raise ItemError({"step": None, "tool": "render.py", "kind": "input", "reason": "recipe_project_unreadable",
                              "message": f"recipe.project: {recipe['project']} is not a JSON object"})
-        idx = int(recipe.get("clip_key", 0))
+        idx = int(recipe.get("clip_key") or 0)  # null is clip 0, as check_recipe_types() reads it
         proj.setdefault("clips", [{}])
         while len(proj["clips"]) <= idx:
             proj["clips"].append({})
@@ -539,11 +572,12 @@ def main() -> int:
     if not folder.is_dir():
         die(f"not a folder: {folder}")
     try:
-        recipe = json.loads(Path(args.recipe).read_text(encoding="utf-8"))
+        recipe = read_json(args.recipe)  # too deep is a ValueError too (A20)
     except (OSError, ValueError) as exc:
-        die(f"cannot read recipe: {exc}")
+        die(f"cannot read recipe: {exc}", kind="input")
     if not isinstance(recipe, dict):
-        die("cannot read recipe: not a JSON object")
+        die("cannot read recipe: not a JSON object", kind="input")
+    check_recipe_types(recipe)
     if recipe.get("project") and not os.path.isabs(recipe["project"]):
         recipe["project"] = str((Path(args.recipe).resolve().parent / recipe["project"]))
     # a recipe error is the same for every item: refuse it once, before any item runs, rather than

package/scripts/caption.py

@@ -59,6 +59,8 @@ from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
+from _common.asr import srt_blocks
+from _common.runner import normalize_text
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
                      fit_size, line_em_for_size, MIN_CAPTION_FRACTION,
                      break_penalty, _is_weak_line, _atoms, _join, _break_spaced, _bare_word, _function_words,
@@ -83,10 +85,21 @@ ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3
 FORCE_STYLE_ALIGN = {"bottom": 2, "top": 6, "center": 10, "bottom-left": 1, "bottom-right": 3, "top-left": 5, "top-right": 7}
 
 TIME_RE = re.compile(
-    r"^\s*(?P<a>[\d:.,@]+)\s*(?:-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
+    r"^\s*(?P<a>[\d:.,@]+)\s*(?P<sep>-->|-|–|to)\s*(?P<b>[\d:.,@]+)\s+(?P<text>.+)$"  # @ = the 1.9 @fps suffix
 )
 
 
+def cue_times_match(line: str) -> "Optional[re.Match[str]]":
+    """TIME_RE's match of a --text line, or None when the line is caption text. The documented
+    separators are "-" and "-->", and with them bare seconds are times ("0-1.5 Hello"). "to" is
+    also an English word: "3 to 5 apples" is text, so with "to" both sides must be clock times
+    (a ':' in each, "0:03 to 0:05 Hello")."""
+    m = TIME_RE.match(line)
+    if m and m.group("sep") == "to" and not (":" in m.group("a") and ":" in m.group("b")):
+        return None
+    return m
+
+
 # an SRT timing line: the times alone, the cue text on the lines after it
 DROP_FRAME_RE = re.compile(r"^\s*\d+:\d{2}:\d{2};\d+")
 SRT_TIMING_RE = re.compile(r"^\s*\d+:\d{2}:\d{2}[,.]\d+\s*-->\s*\d+:\d{2}:\d{2}[,.]\d+\s*$")
@@ -95,9 +108,11 @@ SRT_TIMING_RE = re.compile(r"^\s*\d+:\d{2}:\d{2}[,.]\d+\s*-->\s*\d+:\d{2}:\d{2}[
 def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[float] = None) -> List[Tuple[float, float, str]]:
     cues: List[Tuple[float, float, str]] = []
     cursor = 0.0
-    lines = read_text_or_die(path, "--text").lstrip("\ufeff").splitlines(True)
+    # split at "\n" only: splitlines() also breaks a cue at U+2028, U+0085, \v and \f, which
+    # made the rest of the line an auto-timed cue of its own
+    lines = read_text_or_die(path, "--text").split("\n")
     for n, raw in enumerate(lines, 1):
-        if SRT_TIMING_RE.match(raw.rstrip("\r\n")):
+        if SRT_TIMING_RE.match(raw):
             # a cue file puts the text on the line with its times; this line has the times alone, so
             # the file is an SRT. Read as a cue file, its numbers and timing lines would be burned in
             # as captions, auto-timed 3 s apart (#396)
@@ -107,11 +122,10 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[fl
             # TIME_RE has no ';', so the line would be burned as caption text, auto-timed
             die(f"--text: line {n} has a drop-frame timecode (';'), which is not read: write it as "
                 "hh:mm:ss:ff@29.97 or in seconds", kind="input")
-    for raw in lines:
-        line = raw.rstrip("\n")
+    for line in lines:
         if not line.strip():
             continue
-        m = TIME_RE.match(line)
+        m = cue_times_match(line)
         if m:
             try:
                 start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
@@ -535,7 +549,7 @@ def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[
 def parse_ass_dialogue(path: str) -> str:
     """The spoken text of an ASS file, for script detection -- style/override blocks stripped."""
     text = []
-    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
+    for line in read_text_or_die(path, "--ass").split("\n"):
         if not line.startswith("Dialogue:"):
             continue
         fields = line.split(",", 9)
@@ -557,7 +571,7 @@ def parse_ass_cues(path: str, stats: Optional[dict] = None) -> List[Tuple[float,
     # the [Events] Format line names the columns; Text is always last (libass reads it the same
     # way), and a file without one gets the standard ten
     names = ["layer", "start", "end", "style", "name", "marginl", "marginr", "marginv", "effect", "text"]
-    for line in read_text_or_die(path, "--ass").lstrip("\ufeff").splitlines():
+    for line in read_text_or_die(path, "--ass").split("\n"):
         if line.startswith("Format:") and "text" in line.lower():
             names = [n.strip().lower() for n in line.partition(":")[2].split(",")]
             continue
@@ -601,7 +615,8 @@ def count_visible_cues(cues, duration) -> Tuple[int, int]:
 def shift_ass_file(src: str, dst: str, offset: float) -> Tuple[int, int]:
     """Copy an ASS file with every Dialogue start/end moved by `offset` seconds; (lines shifted,
     Dialogue lines copied unshifted because their timestamps could not be read)."""
-    text, n, unshifted = shift_ass_text(Path(src).read_text(encoding="utf-8-sig"), offset)
+    # read as the dry run reads it: a file that is not UTF-8 is refused as kind input on both
+    text, n, unshifted = shift_ass_text(read_text_or_die(src, "--ass"), offset)
     Path(dst).write_text(text, encoding="utf-8-sig")
     return n, unshifted
 
@@ -621,7 +636,9 @@ def shift_ass_text(source: str, offset: float) -> Tuple[str, int, int]:
 
     n = unshifted = 0
     out = []
-    for line in source.splitlines():
+    # lines end at "\n" only (libass reads them so); a U+2028 inside a Dialogue's text is text
+    body = normalize_text(source)
+    for line in (body[:-1] if body.endswith("\n") else body).split("\n"):
         if line.startswith("Dialogue:"):
             head, sep, rest = line.partition(":")
             fields = rest.split(",")
@@ -929,12 +946,9 @@ def srt_timings_shared_grammar(path: str) -> bool:
     """True when every timing line of the SRT at `path` reads the same to ffmpeg's SRT demuxer as
     to parse_srt(). ffmpeg refuses `00:01,000` (no hours) and reads `00:00:01,5` as 1.005 s, where
     parse_srt() reads 1.5 s (#414); such a file is handed to ffmpeg as a rewritten copy."""
-    text = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n")
-    # a cue's timing line is its first line with "-->", as parse_srt() reads it (and ffmpeg too);
-    # a later line holding "-->" is dialogue, not a timing this check should judge
-    blocks = [[ln for ln in b.split("\n") if ln.strip()] for b in re.split(r"\n\s*\n", text)]
-    timings = [next((ln for ln in b if "-->" in ln), None) for b in blocks]
-    return all(_SHARED_SRT_TIMING.match(line) for line in timings if line is not None)
+    # the timing lines parse_srt() reads, grouped as it groups them (srt_blocks()): a later line
+    # that only holds "-->" is dialogue, not a timing this check should judge
+    return all(_SHARED_SRT_TIMING.match(times) for times, _body in srt_blocks(read_text_or_die(path, "--srt")))
 
 
 def mux_subtitle_codec(output: str) -> str:
@@ -1461,7 +1475,7 @@ def main() -> int:
     if args.ass and args.offset and os.path.exists(args.ass):
         shifted = os.path.splitext(output)[0] + "_offset.ass"
         if STATE.dry_run:
-            _text, n, unshifted = shift_ass_text(read_text_or_die(args.ass, "--ass").lstrip("\ufeff"), args.offset)
+            _text, n, unshifted = shift_ass_text(read_text_or_die(args.ass, "--ass"), args.offset)
             info(f"[dry-run] would write {shifted} ({n} cues shifted by {args.offset:+g} s)")
         else:
             n, unshifted = shift_ass_file(args.ass, shifted, args.offset)

package/scripts/cut.py

@@ -58,7 +58,7 @@ import tempfile
 import zlib
 from typing import List, Tuple
 
-from _common.runner import fail_if_classified
+from _common.runner import JsonTooDeep, fail_if_classified, read_json
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
@@ -1199,11 +1199,15 @@ def _grid_from_source(path: str, min_confidence: float) -> "dict":
     """The beat grid of `path`: a scenes.py --json document if that is what it is, otherwise a
     media file to measure. Reading a document is how a caller avoids a second decode."""
     try:
-        with open(path, "r", encoding="utf-8") as fh:
-            doc = json.load(fh)
+        doc = read_json(path)   # a media file is not UTF-8 or not JSON: a ValueError, then measured
+    except JsonTooDeep as exc:
+        die(f"--snap-source {path}: {exc}", kind="input")
     except (OSError, ValueError):
         doc = None
     if isinstance(doc, dict) and doc.get("beat_grid"):
+        if not isinstance(doc["beat_grid"], dict) or not isinstance(doc.get("beats") or [], list):
+            die(f"--snap-source {path}: beat_grid must be an object and beats a list "
+                "(regenerate it with `scenes.py MUSIC --beats --json`)", kind="input")
         grid = dict(doc["beat_grid"])
         grid["beats"] = doc.get("beats") or []
         # A scenes.py document carries the supported subset since 1.17; one written by an older

package/scripts/join.py

@@ -44,6 +44,7 @@ from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
+from _common.runner import read_text_or_die
 from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, place_output, refuse, sibling_temp, as_limited, draws_chroma, drawn_chain, label_chain, matrix_chain, range_chain, video_args, aac_args, add_common, apply_common, audio_codec_for, default_output, die, dry_run_input_pending, emit, ffmpeg_base, info, measured_level_dbfs, is_audio_output, probe, require_tool, run, validate_color, X264_PRESETS, fmt_secs
 from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
@@ -280,13 +281,12 @@ def read_list(path: str) -> List[str]:
     """--list FILE: one segment per line, in order, relative to the list file's own folder.
     Blank lines and # comments are ignored, and ffmpeg's concat-demuxer spelling
     (`file 'part 01.wav'`) is accepted, so a list written for `ffmpeg -f concat` works as is."""
-    try:
-        text = open(path, encoding="utf-8").read()
-    except OSError as exc:
-        die(f"cannot read --list {path}: {exc}")
+    # the shared reader: a BOM, CRLF and a file that is not UTF-8 are read or refused as every
+    # other text input is, and a line ends at "\n" only
+    text = read_text_or_die(path, "--list")
     base = os.path.dirname(os.path.abspath(path))
     entries: List[str] = []
-    for line in text.splitlines():
+    for line in text.split("\n"):
         line = line.strip()
         if not line or line.startswith("#"):
             continue

package/scripts/metadata.py

@@ -43,7 +43,7 @@ def parse_chapters(path: str, duration: float) -> List[Dict[str, Any]]:
     start inside the file, the last chapter running to the file's end."""
     text = read_text_or_die(path, "--chapters")
     entries: List[Dict[str, Any]] = []
-    for n, raw in enumerate(text.splitlines(), start=1):
+    for n, raw in enumerate(text.split("\n"), start=1):  # not splitlines(): a title may hold U+2028
         line = raw.strip()
         if not line or line.startswith("#"):
             continue

package/scripts/render.py

@@ -75,7 +75,7 @@ from typing import Any, Dict, List, Optional, Sequence
 from export import PRESETS, PLATFORM_OF
 from _platforms import PLATFORMS, caption_defaults, resolve as resolve_platform
 from _common import guard_sidecar, STATE, add_common, aspect_ratio, brand_caption_style, load_brand, apply_common, child_args, die, emit, info, option_args, probe, require_tool, run, run_tool, place_output, refuse_output_is_input, _check_existing_output, _check_output_path, fingerprint, PLAN_VERSION, ffmpeg_version, X264_PRESETS
-from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, remember_written
+from _common.runner import HW_ENV, HW_FORCED_ENV, add_hw_orchestrator_args, child_exit_code, found_exe, kept_clause, kept_deliverables, mark_delivered, read_json, remember_written
 from _common.emit import absorb_stage, audit, record_fallback, record_skip, refuse, warn
 from _common.decision import rebase_project_paths
 import subprocess
@@ -182,7 +182,7 @@ def load_template(name: str) -> Dict[str, Any]:
     if not path.is_file():
         die(f"unknown template {name!r}", hint="templates: " + ", ".join(template_names()) + " (or 'all')")
     try:
-        return json.loads(path.read_text(encoding="utf-8"))
+        return read_json(path)
     except (OSError, ValueError) as exc:
         die(f"cannot read template {path}: {exc}")
     return {}
@@ -504,7 +504,7 @@ def project_input_files(proj: Dict[str, Any], rel: Any) -> List[str]:
         # the brand's own logo and font_file are read by the overlay and caption stages, resolved
         # against the brand file as load_brand() resolves them; an unreadable brand is left to them
         try:
-            data = json.loads(Path(rel(brand)).read_text(encoding="utf-8"))
+            data = read_json(rel(brand))
         except (OSError, ValueError):
             data = None
         if isinstance(data, dict):
@@ -565,6 +565,14 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
             require_object(proj.get(name), name)
         check_keys(proj.get(name), name, name)
     check_keys((proj.get("audio") or {}).get("stems"), "audio.stems", "audio.stems")
+    # the values the run reads with .get() or as a dict key: a list there was a traceback (A13)
+    audio = proj.get("audio")
+    if "audio" in read and isinstance(audio, dict):
+        require_object(audio.get("stems"), "audio.stems")
+    export = proj.get("export")
+    if "export" in read and isinstance(export, dict) and export.get("preset") and not isinstance(export["preset"], str):
+        die(f"export.preset: must be a preset name (a string), got {type(export['preset']).__name__} "
+            f"{export['preset']!r:.60}")
     if isinstance(proj.get("chapters"), list):
         # Every other project error is raised here, before the first ffmpeg call; a chapter typo
         # found inside the last stage costs a whole render and leaves an unchaptered file behind.
@@ -590,6 +598,14 @@ def validate_project(proj: Dict[str, Any], timeline: bool = False, stop_after: O
             # every clip stage starts from rel(c["src"]): without one it was a KeyError traceback
             if not item.get("src"):
                 die(f"clips[{i}]: no src")
+            if item.get("speed") and not timeline:
+                # the clips stage reads float(speed): "fast" or [2] was a traceback there (A13)
+                try:
+                    spd = float(item["speed"])
+                except (TypeError, ValueError):
+                    spd = float("nan")
+                if not (0 < spd < float("inf")):
+                    die(f"clips[{i}]: speed must be a positive number, got {item['speed']!r:.60}")
             if item.get("snap") is not None:
                 # the render reads a clip's snap only on a clip it cuts (in/out), the export never
                 if not timeline and (item.get("in") is not None or item.get("out") is not None):
@@ -984,6 +1000,19 @@ def execute_plan(plan: Dict[str, Any], path: str) -> int:
         _reject_plan(path, digest, "plan_version_unsupported",
                      f"{path}: plan_version {plan.get('plan_version')!r} is not {PLAN_VERSION}",
                      plan_version=plan.get("plan_version"), supported=[PLAN_VERSION])
+    # the fields below are walked as lists of objects or strings: a wrong type was a traceback
+    # with no audit record (A14), and is refused like every other plan error
+    for field, want, item in (("inputs", list, None), ("unbound_inputs", list, None), ("verify", list, dict),
+                              ("commands", list, str), ("cwd", str, None)):
+        value = plan.get(field)
+        if value is None:
+            continue
+        bad = not isinstance(value, want) or (item is not None and not all(isinstance(v, item) for v in value))
+        if bad:
+            shape = {"inputs": "a list", "unbound_inputs": "a list", "verify": "a list of objects",
+                     "commands": "a list of strings", "cwd": "a string"}[field]
+            _reject_plan(path, digest, "plan_field_invalid", f"{path}: {field} must be {shape}, got {type(value).__name__}",
+                         field=field, field_type=type(value).__name__)
     tool = str(plan.get("tool") or "")
     script = HERE / f"{tool}.py"
     if not re.fullmatch(r"[a-z][a-z0-9_]*", tool) or not script.exists() or tool == "render":
@@ -1238,9 +1267,10 @@ def main() -> int:
             if value:
                 die(f"{flag} belongs to --template NAME INPUT; a project.json states it in the project itself")
         try:
-            proj = json.loads(Path(args.project).read_text(encoding="utf-8"))
+            # read_json(): nesting too deep is a ValueError too, refused here, not a RecursionError
+            proj = read_json(args.project)
         except (OSError, ValueError) as exc:
-            die(f"cannot read project: {exc}")
+            die(f"cannot read project: {exc}", kind="input")
         if not isinstance(proj, dict):
             die(f"{args.project}: not a project or plan object (top level is {type(proj).__name__})")
         if "plan_version" in proj:

package/scripts/report.py

@@ -126,7 +126,7 @@ def pack_report(args) -> int:
     text = read_text_or_die(args.pack, "--pack")
     rows: List[List[str]] = []
     header: List[str] = []
-    for line in text.splitlines():
+    for line in text.split("\n"):
         line = line.strip()
         if not line.startswith("|"):
             continue
@@ -233,7 +233,9 @@ def main() -> int:
             if meta and meta.get("video"):
                 sheets[which], why = sheet_b64(path)
                 section("contact_sheet", which, why, f"{which} contact sheet")
-    commands = read_text_or_die(args.commands, "--commands").splitlines() if args.commands else []
+    # one per line, split at "\n" only (a command may hold U+2028 or \f; splitlines() split it)
+    command_text = read_text_or_die(args.commands, "--commands") if args.commands else ""
+    commands = command_text.removesuffix("\n").split("\n") if command_text else []
     notes = read_text_or_die(args.notes, "--notes") if args.notes else ""
     title = args.title or f"Delivery report — {Path(args.after).name}"
 

package/scripts/silence.py

@@ -28,7 +28,8 @@ from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOU
                      FILLER_PAD, read_text_or_die)
 from _common import asr as _asr
 from _common.emit import warn
-from _common.runner import replace_checked
+from _common.asr import _dicts
+from _common.runner import parse_json, replace_checked
 from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_input, _check_output_path
 from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
@@ -115,7 +116,7 @@ def sentence_words(args) -> "Tuple[list, str]":
         return usable(args._words, args._words_source)
     if args.words:
         try:
-            raw = json.loads(read_text_or_die(args.words, "--words"))
+            raw = parse_json(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         words, _had_segments, _untimed = _words_from_transcript(raw)
@@ -348,7 +349,7 @@ def resolve_filler(args, meta):
     untimed: list = []  # transcript words without a usable timing (a --words file can carry them)
     if args.words:
         try:
-            raw = json.loads(read_text_or_die(args.words, "--words"))
+            raw = parse_json(read_text_or_die(args.words, "--words"))
         except ValueError as exc:
             die(f"--words {args.words}: not readable JSON ({exc})", kind="input")
         source = f"whisper-json:{args.words}"
@@ -484,11 +485,13 @@ def _words_from_transcript(data):
     listed word it could not cut instead of dropping it unseen."""
     raw, had_segments = [], False
     if isinstance(data, dict):
-        raw = list(data.get("words") or [])
-        segments = data.get("segments") or []
+        # a "words" or "segments" that is not a list, and a segment that is not an object, carry no
+        # words: the file is then refused for having none, not by a traceback
+        raw = _dicts(data.get("words"))
+        segments = _dicts(data.get("segments"))
         had_segments = bool(segments)
         for seg in segments:
-            raw.extend((seg or {}).get("words") or [])
+            raw.extend(_dicts(seg.get("words")))
     elif isinstance(data, list):
         raw = list(data)
     out, untimed = [], []