ffmpeg-skill 3.6.4 → 3.6.6

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.6`) | 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.6", "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.6",
   "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/color.py

@@ -74,7 +74,8 @@ def is_rgb(meta: Optional[Dict[str, Any]]) -> bool:
 _EVEN_PAD = "pad=ceil(iw/2)*2:ceil(ih/2)*2:0:0,"
 _MATRIX_FILTER_RE = re.compile(r"^(?:(?:%s)?colorspace=ispace=(?:%s):iprimaries=bt709:itrc=bt709:space=bt709:primaries=bt709:trc=bt709(?:,crop=iw-[01]:ih-[01]:0:0:exact=1)?|(?:format=rgb24,)?%s)$"
                                % (re.escape(_EVEN_PAD), "|".join(NON_BT709_MATRICES), re.escape(rgb_to_bt709_filter())))
-_INPUT_VIDEO_REF = re.compile(r"\[(\d+):v(?::0)?\]")
+# [N:v], [N:v:0] and [N:V:0] (PROBED_VIDEO: the motion picture, not an attached cover)
+_INPUT_VIDEO_REF = re.compile(r"\[(\d+):[vV](?::0)?\]")
 
 
 def bt709_matrix_filter(meta: Optional[Dict[str, Any]]) -> Optional[str]:
@@ -263,7 +264,7 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
 
     - no other filter: unchanged (the -vf is the graph);
     - a -vf: the conversion is prepended to that chain;
-    - a -filter_complex: every `[N:v]` / `[N:v:0]` reference to an input that reads the same file
+    - a -filter_complex: every `[N:v]` / `[N:v:0]` / `[N:V:0]` reference to an input that reads the same file
       as input 0 (the file the encoder line was built for; cut.py's segment join opens it once
       per segment) reads that input through the conversion instead. Other inputs are untouched.
 
@@ -298,7 +299,7 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
         graph = _INPUT_VIDEO_REF.sub(through, str(out[graph_at + 1]))
         if not refs:
             die("internal: a BT.709 matrix conversion was requested for a -filter_complex that never reads "
-                "input 0's video as [0:v]", kind="ffmpeg")
+                "input 0's video as [0:v] or [0:V:0]", kind="ffmpeg")
         # one conversion per input, split when the graph reads that input more than once
         # (speedramp.py trims [0:v] once per segment)
         chains = [f"{ref}{conv}" + (f",split={len(labels)}" if len(labels) > 1 else "") + "".join(labels)

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/probe.py

@@ -15,6 +15,14 @@ from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die, warn
 from _common.runner import STATE, dry_run_input_pending, require_tool, run, run_analysis, still_input_args
 
+# The streams probe() describes, as stream specifiers: its `video` is the first picture that is not
+# a cover (`V`), its `audio` the first sound stream. Without a -map, FFmpeg picks the largest
+# picture and the sound with the default disposition or the most channels, so on a file with two
+# of either a tool measured one stream and wrote another: loudness measured track 1 and applied the
+# gain to track 0, cut and crop wrote the larger picture they never probed (A110, A118, A128, A258).
+PROBED_VIDEO = "V:0"
+PROBED_AUDIO = "a:0"
+
 
 def fingerprint(path: str) -> Dict[str, Any]:
     """Size plus a sha256 over the first and last 8 MiB: enough to notice a re-export, a re-trim
@@ -50,7 +58,8 @@ def decode_pcm_mono(path: str, sample_rate: int, seconds: Optional[float] = None
     # first_pts=0 pads a sound that starts after the file's start (or after `start`) with silence,
     # so sample i is at start + i / sample_rate on the file's clock: sync.py measured a track that
     # starts 0.3 s late 0.279 s off, and --replace-audio placed it that far late (#409)
-    cmd += ["-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
+    # the first audio track, the one probe() describes (default selection takes the most channels)
+    cmd += ["-map", f"0:{PROBED_AUDIO}", "-vn", "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", str(sample_rate), "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
         if check:
@@ -99,7 +108,7 @@ def decode_gray_frames(path: str, fps: float, width: int, height: int, *, start:
     cmd += ["-i", path]
     if seconds is not None:
         cmd += ["-t", f"{max(0.0, seconds):.3f}"]
-    cmd += ["-vf", f"fps={fps:g},scale={width}:{height}:flags=area,format=gray",
+    cmd += ["-map", f"0:{PROBED_VIDEO}", "-vf", f"fps={fps:g},scale={width}:{height}:flags=area,format=gray",
             "-f", "rawvideo", "-"]
     proc = run_analysis(cmd, check=False, text=False)
     if proc.returncode != 0 or not proc.stdout:
@@ -422,6 +431,26 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
 _CARRY: Dict[str, Dict[str, Any]] = {}
 
 
+def probed_maps(meta: Optional[Dict[str, Any]], *, video: bool = True, audio: bool = True,
+                audio_stream: int = 0, input_index: int = 0) -> List[str]:
+    """`-map` arguments for the picture and sound probe() describes in `meta` (audio track
+    `audio_stream` where a tool takes --audio-stream). A kind the file does not have is left out,
+    so the same call serves a silent clip and an audio-only file."""
+    out: List[str] = []
+    if video and (meta or {}).get("video"):
+        out += ["-map", f"{input_index}:{PROBED_VIDEO}"]
+    if audio and (meta or {}).get("audio"):
+        out += ["-map", f"{input_index}:a:{audio_stream}"]
+    return out
+
+
+def several_av_streams(meta: Optional[Dict[str, Any]]) -> bool:
+    """True when FFmpeg's default stream selection could pick a picture or a sound other than the
+    one probe() describes: more than one playable video stream or more than one audio stream."""
+    counts = (meta or {}).get("stream_counts") or {}
+    return (counts.get("video") or 0) > 1 or (counts.get("audio") or 0) > 1
+
+
 def carry_inventory(path: str) -> "Optional[Dict[str, Any]]":
     """The carry-over items probe() last read off `path` (see emit()'s source_carry), or None."""
     return _CARRY.get(os.path.realpath(path)) if path else None
@@ -628,10 +657,11 @@ def measured_level_dbfs(path: str, seconds: Optional[float] = 120.0,
                         audio_stream: Optional[int] = None) -> Optional[Dict[str, float]]:
     """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.
     Cheap enough to run once as a hint when a threshold-based tool found nothing. seconds=None
-    measures the whole file; audio_stream picks the Nth audio stream (default: ffmpeg's choice)."""
+    measures the whole file; audio_stream picks the Nth audio stream (default: the first, the one
+    probe() describes; FFmpeg's own choice was the track with the most channels)."""
     ffmpeg = require_tool("ffmpeg")
     head = ["-t", f"{seconds:.0f}"] if seconds is not None else []
-    pick = ["-map", f"0:a:{audio_stream}"] if audio_stream is not None else []
+    pick = ["-map", f"0:a:{audio_stream or 0}"]
     proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", *head, "-i", path, *pick, "-vn",
                          "-af", "volumedetect", "-f", "null", "-"], check=False)
     m_mean = re.search(r"mean_volume:\s*(-?[0-9.]+) dB", proc.stderr)
@@ -751,7 +781,7 @@ def measure_signal_range(path: str, standard: str, window: float = 10.0,
         stats_file = os.path.join(tmp, "stats.txt")
         vf = (f"signalstats=stat=brng,metadata=print:file={escape_filter_path(stats_file)},"
               f"{mask},signalstats,metadata=print:file=-")
-        cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", "0:v:0", "-an", "-sn", "-dn", "-vf", vf, "-f", "null", "-"]
+        cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an", "-sn", "-dn", "-vf", vf, "-f", "null", "-"]
         proc = run_analysis(cmd, check=False, record=True)
         try:
             with open(stats_file, encoding="utf-8", errors="replace") as f:
@@ -804,7 +834,7 @@ def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     white below ~235 with low saturation: the image looks grey and flat but is tagged as plain SDR.
     """
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-an",
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-t", f"{seconds:.1f}", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an",
            "-vf", "fps=2,signalstats,metadata=print:file=-", "-f", "null", "-"]
     proc = run_analysis(cmd, check=False)
     vals: Dict[str, List[float]] = {}
@@ -976,7 +1006,7 @@ def detect_silences(path: str, threshold: float, min_silence: float) -> "List[Tu
     if dry_run_input_pending(path):
         return []
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af",
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn", "-af",
            f"silencedetect=noise={threshold}dB:d={min_silence}", "-f", "null", "-"]
     proc = run_analysis(cmd, check=False, record=True)
     if proc.returncode != 0:
@@ -1188,7 +1218,7 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
     a real cut is a one-frame spike. On real footage this roughly doubles precision at
     equal recall compared with the raw scdet threshold."""
     ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_VIDEO}", "-an", "-vf",
                          "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"])
     # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose
     # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title

package/scripts/_common/runner.py

@@ -2045,6 +2045,26 @@ def subtitle_container_holds(codec: str, out_ext: str) -> bool:
     return True
 
 
+def default_selection_maps(meta: Optional[Dict[str, Any]], dst: str) -> List[str]:
+    """The -map arguments for a re-encode that would otherwise rely on ffmpeg's default stream
+    selection: none for a file with one picture and one sound (the default picks those, and a
+    subtitle stream the container can hold, as it always did), and with several, the picture
+    and sound probe() describes plus the first subtitle stream when `dst`'s container can hold it
+    -- what the default would have carried, without its largest-picture / most-channels choice
+    (A258, #484 review)."""
+    from _common.probe import probed_maps, several_av_streams  # probe imports this module
+    if not several_av_streams(meta):
+        return []
+    maps = probed_maps(meta)
+    subs = (meta or {}).get("subtitle_stream_details") or []
+    codec, ext = (subs[0].get("codec") or "") if subs else "", os.path.splitext(dst)[1]
+    if subs and subtitle_container_holds(codec, ext):
+        # with its own -c:s: the default subtitle encoder does not exist for every container
+        # (none for MP4 in FFmpeg 6.1) and is a text encoder that cannot take a bitmap track
+        maps += ["-map", "0:s:0", "-c:s", subtitle_codec_for(codec, ext)]
+    return maps
+
+
 def run_keeping_subtitles(cmd: List[str], output: str, relabel_timecode: bool = False) -> bool:
     """Run an ffmpeg command that already maps its video/audio, trying first to also
     stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
@@ -2487,15 +2507,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 +2539,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/audio.py

@@ -157,6 +157,22 @@ def find_silent_tracks(args: argparse.Namespace, problems: List[Dict[str, Any]])
     return silent
 
 
+def main_track_channels(args: argparse.Namespace, meta: Dict[str, Any]) -> int:
+    """Channel count of the track audio.py processes: --replace's first audio track, else the
+    input's --audio-stream track; 0 when it is not known (a dry run's pending input)."""
+    if args.replace:
+        if dry_run_input_pending(args.replace) or not os.path.isfile(args.replace):
+            return 0
+        proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", "a:0", "-show_entries",
+                    "stream=channels", "-of", "csv=p=0", args.replace], quiet=True, check=False)
+        first = (proc.stdout or "").strip().splitlines()[:1]
+        return int(first[0]) if first and first[0].strip().isdigit() else 0
+    streams = meta.get("audio_streams") or []
+    if 0 <= args.audio_stream < len(streams):
+        return streams[args.audio_stream].get("channels") or 0
+    return (meta.get("audio") or {}).get("channels") or 0
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -279,7 +295,10 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
     if args.audio_stream and not streams and not STATE.dry_run:
         die("--audio-stream needs an input with audio streams")
-    in_channels = (meta.get("audio") or {}).get("channels") or 0
+    # the channels of the track the graph processes (main_src below): the --audio-stream track,
+    # or --replace's first track. meta["audio"] is the input's first track, so a mono a:0 left a
+    # stereo --audio-stream 1 unfolded by --mono, and a stereo a:0 halved a mono one (A128)
+    in_channels = main_track_channels(args, meta)
     if args.stereo_widen is not None:
         if args.mono:
             die("--stereo-widen and --mono contradict each other: there is no stereo image in a 1-channel output")
@@ -324,7 +343,8 @@ def main() -> int:
     if args.limit:
         fx.append(dynamics_filter("alimiter", args))
     if args.mono:
-        in_ch = (meta.get("audio") or {}).get("channels") or 2
+        # after --downmix the track is the stereo fold-down, whatever the source had
+        in_ch = 2 if args.downmix else (in_channels or 2)
         if in_ch == 2:
             fx.append("pan=mono|c0=0.5*c0+0.5*c1")
         elif in_ch > 2: