ffmpeg-skill 3.6.4 → 3.6.6

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

@@ -47,6 +47,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, TP_TOLERANCE_DB, spec_of, re
 from _common.probe import (CHANGE_FLOOR, CHANGE_GRID, change_mask_tiles, change_tiles, LEGAL_RANGE_CHOICES, measure_signal_range, COMPARE_SSIM_WARN, CONTENT_FLAT_STD, SILENT_PEAK_DBFS, compare_pictures, detect_content,
                            detect_flashes, first_frame_stats, presentation_times, measured_level_dbfs)
 from _common.emit import file_identity
+from _common.probe import PROBED_AUDIO
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
 # The one delivery table (scripts/_platforms.py): check.py's rows, export.py's presets and the
@@ -61,7 +62,10 @@ def measure_loudness(path: str) -> Dict[str, float]:
     if dry_run_input_pending(path):
         return {}
     ffmpeg = require_tool("ffmpeg")
-    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
+    # the first audio track, the one the audio row's probe facts describe (and the one export and
+    # loudness write): default selection measured the track with the most channels
+    proc = run_analysis([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn",
+                         "-af", "loudnorm=I=-14:TP=-1:LRA=11:print_format=json", "-f", "null", "-"], check=False, record=True)
     m = re.search(r"\{[^{}]*\"input_i\"[^{}]*\}", proc.stderr, re.S)
     if not m:
         return {}

package/scripts/crop.py

@@ -23,6 +23,7 @@ import sys
 
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, fmt_secs
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.runner import default_selection_maps
 from _common.emit import note
 
 
@@ -65,7 +66,8 @@ def main() -> int:
     if square_pixels(meta["video"]):
         vf.insert(0, square_pixels(meta["video"]))
         note(square_pixels_note(meta["video"]))
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", ",".join(vf)]
+    # the picture the rectangle was checked against, not the largest one default selection takes
+    cmd = ffmpeg_base() + ["-i", args.input] + default_selection_maps(meta, output) + ["-vf", ",".join(vf)]
     cmd += video_args(meta, args.crf, args.preset)
     cmd += cfr_args(meta, args.fps)
     if has_audio:

package/scripts/cropdetect.py

@@ -35,7 +35,7 @@ from typing import Dict, List, Optional, Tuple
 
 from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
 from _common.emit import note, warn
-from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note
 
 MOTION_CENTRE_FPS = 2.0
 MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
@@ -57,7 +57,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
-               "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+               "-map", f"0:{PROBED_VIDEO}", "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
         proc = run_analysis(cmd, check=False)
         if proc.returncode != 0:
             # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows

package/scripts/cut.py

@@ -58,10 +58,11 @@ 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
+from _common.probe import PROBED_AUDIO, PROBED_VIDEO, TS_EXTS, probed_maps, several_av_streams, signatures_match, stream_signature
+from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.decision import SEEK_MARGIN, delivered_rate, frame_rate, grid_at_or_after, stream_starts
 from _common.timeline import output_timecode_args
 from _common import warn, record_fallback, refuse_existing_outputs, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
@@ -147,6 +148,29 @@ def copy_args(meta: dict, dst: str) -> List[str]:
     return args
 
 
+def stream_maps(meta: dict, dst: str, copy: bool) -> List[str]:
+    """The -map arguments of a cut: the picture and the sound probe() describes, which every
+    measurement here (keyframes, start skew, timecode, length) is taken from. ffmpeg's default
+    selection wrote the largest picture and the track with the default disposition or the most
+    channels instead (A258). A stream copy of a file with one picture and one sound keeps the
+    default selection, command for command (it also carries a subtitle stream into a container
+    whose muxer names a subtitle codec, such as Matroska). With several, the first subtitle stream
+    is mapped when the container holds it as it is, and is otherwise left out and reported
+    (DROPPED_STREAMS)."""
+    audio_only = is_audio_output(dst) or not meta.get("video")
+    if copy and not several_av_streams(meta):
+        return []
+    maps = probed_maps(meta, video=not audio_only)
+    subs = meta.get("subtitle_stream_details") or []
+    if copy and not audio_only and subs:
+        codec, ext = subs[0].get("codec") or "", os.path.splitext(dst)[1].lstrip(".").lower()
+        if subtitle_container_holds(codec, ext) and subtitle_codec_for(codec, ext) == "copy":
+            maps += ["-map", "0:s:0"]
+        else:
+            DROPPED_STREAMS.append(dst)
+    return maps
+
+
 LOSSLESS_AUDIO = {"pcm_s16le", "pcm_s24le", "pcm_s32le", "pcm_f32le", "flac"}
 
 
@@ -870,7 +894,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             # -ss before -i seeks, then decoding discards samples up to the exact start
             # (accurate_seek); atrim bounds the decoded stream to the requested length at sample
             # resolution.
-            cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"]
+            cmd = ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur:.6f}"] + stream_maps(meta, dst, copy=False)
             cmd += ["-af", f"atrim=end={dur:.6f},asetpts=PTS-STARTPTS"]
         else:
             # Seek SEEK_MARGIN early, then drop the margin on the output side, which decodes and
@@ -879,6 +903,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
             # `start` and lose the frames before it (-ss 9.9 on a B-frame HEVC file began at 10.0).
             m = min(SEEK_MARGIN, start)
             cmd = ffmpeg_base() + ["-ss", f"{start - m:.6f}", "-i", src, "-ss", f"{m:.6f}", "-t", f"{dur:.6f}"]
+            cmd += stream_maps(meta, dst, copy=False)
         # ffmpeg's default stream selection also picks one subtitle stream; a re-encode cannot
         # trim it (the cues kept their timestamps and the container grew to 2 s for a 1 s cut,
         # sweep F2), so the re-encode carries video/audio only and the result says so
@@ -901,7 +926,8 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     elif audio_only:
         # output-side seek: an input seek on a video file lands on the previous video keyframe and on
         # FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packet
-        cmd = ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst]
+        cmd = (ffmpeg_base() + ["-i", src, "-ss", f"{start:.6f}", "-t", f"{dur:.6f}"] + stream_maps(meta, dst, copy=True)
+               + copy_args(meta, dst) + ["-avoid_negative_ts", "make_zero", dst])
     else:
         # With --edit-list a single MP4/MOV output keeps the edit list the plain copy writes: the
         # keyframe's pre-roll is stored but hidden, so the picture and the sound start at `start`.
@@ -913,7 +939,8 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         # Other concat parts (Matroska, MPEG-TS) keep make_zero.
         edit_list = (edit_list_ok or copy_t is not None) and os.path.splitext(dst)[1].lower() in EDIT_LIST_EXTS
         cmd = (ffmpeg_base() + ["-ss", f"{start:.6f}", "-i", src, "-t", f"{dur if copy_t is None else copy_t:.6f}"]
-               + copy_args(meta, dst) + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])
+               + stream_maps(meta, dst, copy=True) + copy_args(meta, dst)
+               + ([] if edit_list else ["-avoid_negative_ts", "make_zero"]) + [dst])
     if not audio_only and (meta.get("timecode") or {}).get("value"):
         cmd[-1:-1] = output_timecode_args(meta, first_frame_from(src, meta, start, reencode, edit_list and copy_t is None),
                                           delivered_rate(meta) if reencode else None)
@@ -1098,7 +1125,7 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
             # concat filter starts the next segment after the longer stream, so a short picture
             # would leave a hole in the video there
             pad = f"tpad=stop_mode=clone:stop_duration={e - vend + 1.0:.6f}," if first + i in hold else ""
-            graph.append(f"[{i}:v:0]{pad}trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB[v{i}]")
+            graph.append(f"[{i}:{PROBED_VIDEO}]{pad}trim=start={a - half:.6f}:end={b - half:.6f},setpts=PTS-{a:.6f}/TB[v{i}]")
             pads += f"[v{i}]"
         if has_a:
             # fade only the sides that meet another segment: the file's own start and end stay as cut
@@ -1109,7 +1136,7 @@ def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: d
                 fades += f",afade=t=in:st=0:d={fade:.6f}"
             if fade > 0 and n < (len(segments) if total is None else total) - 1:
                 fades += f",afade=t=out:st={b - a - fade:.6f}:d={fade:.6f}"
-            graph.append(f"[{i}:a:0]atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB,"
+            graph.append(f"[{i}:{PROBED_AUDIO}]atrim=start={a:.6f}:end={b:.6f},asetpts=PTS-{a:.6f}/TB,"
                          f"aresample=async=1:first_pts=0{fades}[a{i}]")
             pads += f"[a{i}]"
     outs = ("[v]" if has_v else "") + ("[a]" if has_a else "")
@@ -1199,11 +1226,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/export.py

@@ -50,7 +50,7 @@ from _common.runner import child_exit_code, fail_if_classified, kept_clause, mar
 from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
-from _common.probe import square_pixels, square_pixels_note
+from _common.probe import PROBED_AUDIO, PROBED_VIDEO, probed_maps, square_pixels, square_pixels_note
 from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
 from _common.emit import file_identity
 from check import SPECS as PLATFORMS, measure_loudness
@@ -204,8 +204,8 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     key_chain = ",".join(vf + ["alphaextract", "format=yuv422p10le"])
     tc = ((meta.get("timecode") or {}).get("value"))
     tc_args = ["-timecode", tc] if tc else []
-    cmd = cmd + ["-filter_complex", f"[0:v:0]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
-    cmd += ["-map", "[fill]"] + (["-map", "0:a:0"] if has_audio else []) + p["video"] + tc_args + cfr_args(meta)
+    cmd = cmd + ["-filter_complex", f"[0:{PROBED_VIDEO}]split[f][k];[f]{fill_chain}[fill];[k]{key_chain}[key]"]
+    cmd += ["-map", "[fill]"] + probed_maps(meta, video=False, audio=has_audio) + p["video"] + tc_args + cfr_args(meta)
     # the fill is always written to a hidden sibling and moved into place only after the encode
     # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
     # left a partial new fill (the retry was refused as output_exists) or truncated an existing one
@@ -410,7 +410,9 @@ def media_damage(path: str) -> Dict[str, int]:
     PTS) and every other error line, counted. What --repair is measured by, before and after."""
     # repeat+: every occurrence on its own line, not "Last message repeated N times", which hid
     # N timestamp warnings and was itself counted as a decode error
-    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path, "-f", "null", "-"],
+    # the streams a copy export writes (probed_maps), not the ones default selection would decode
+    proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-nostdin", "-v", "repeat+warning", "-i", path,
+                         "-map", f"0:{PROBED_VIDEO}?", "-map", f"0:{PROBED_AUDIO}?", "-f", "null", "-"],
                         check=False, record=True)
     lines = [ln for ln in (proc.stderr or "").splitlines() if ln.strip()]
     # "Packet corrupt (stream = 0, dts = ...)" names a dts but is damage, not a timestamp problem
@@ -585,16 +587,19 @@ def main() -> int:
     # Subtitle and data streams (a soft-subtitle track muxed upstream, a camera's timecode) are
     # kept where the container can hold them: ffmpeg's default stream selection takes one video
     # and one audio stream only, and through 2.22.1 every preset dropped the rest without a word.
-    # Mapping them means mapping the picture and the sound too, the same streams probe() describes.
+    # The picture and the sound are mapped on every export, the same streams probe() describes:
+    # until A118 they were mapped only beside a subtitle or data stream, and without one ffmpeg's
+    # default selection took the larger picture and the track with the default disposition or the
+    # most channels, so which audio track an export kept depended on whether it had subtitles.
     subs = meta.get("subtitle_stream_details") or []
     data = _data_streams(args.input) if meta.get("data_streams") else []
     sub_codecs = [_subtitle_codec(s.get("codec") or "", out_ext) for s in subs]
-    if args.preset != "gif" and not p.get("keyfill") and (subs or data):
-        cmd += ["-map", "0:V:0"] + (["-map", "0:a:0"] if has_audio else [])
+    if args.preset != "gif" and not p.get("keyfill"):
+        cmd += probed_maps(meta, audio=has_audio)
 
     if args.preset == "gif":
         chain = ",".join(([gif_label] if gif_label else []) + ["fps=12"] + vf)
-        fc = f"[0:v]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
+        fc = f"[0:{PROBED_VIDEO}]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)
         info(f"wrote {output}")

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

@@ -24,7 +24,7 @@ from _common import drawtext_fontfile  # noqa: E402
 from _common import ffmpeg_filters, filter_missing_hint  # noqa: E402
 from _common.emit import note, record_fallback  # noqa: E402
 from _common.color import bt709_label_filter, bt2020_sdr_to_bt709_chain, hdr_to_sdr_chain, is_bt2020_sdr  # noqa: E402
-from _common.probe import display_size, square_pixels, square_pixels_note  # noqa: E402
+from _common.probe import PROBED_VIDEO, display_size, square_pixels, square_pixels_note  # noqa: E402
 
 # --guides: broadcast safe areas as outlines, in fractions of the frame (a tile as much as a frame).
 # Action and title safe are SMPTE ST 2046-1's 93 % and 90 % of a 16:9 picture; the 4:3 centre cut
@@ -337,7 +337,7 @@ def main() -> int:
                 conv = "," + conv if conv else ""
                 return (f"scale={half}:{box_h}:force_original_aspect_ratio=decrease{conv}{pre},"
                         f"pad={half}:{box_h}:(ow-iw)/2:(oh-ih)/2:color=0x202020,setsar=1{stamp}")
-            fc = (f"[0:v]{lab}{sq}{fit(tm)}[a];[1:v]{lab2}{csq}{fit(tm2)}[b];"
+            fc = (f"[0:{PROBED_VIDEO}]{lab}{sq}{fit(tm)}[a];[1:{PROBED_VIDEO}]{lab2}{csq}{fit(tm2)}[b];"
                   f"[a][b]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-ss", f"{sec:.3f}", *still_input_args(args.compare), "-i", args.compare,
                                    "-filter_complex", fc, "-map", "[out]", "-frames:v", "1", "-update", "1", out]
@@ -354,7 +354,7 @@ def main() -> int:
                 # several frames, or -o given as a stem/prefix without an image extension
                 out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
             stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-vf", f"{lab}{sq}scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", "-update", "1", out]
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", *still_input_args(args.input), "-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-vf", f"{lab}{sq}scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", "-update", "1", out]
             run(cmd)
             outputs.append(out)
     else:
@@ -384,7 +384,7 @@ def main() -> int:
         tc_sheet = tc
         vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',{lab}{sq}scale={tile_w}:-2{tc_sheet},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
-        cmd = ffmpeg_base() + ["-copyts", "-start_at_zero", "-ss", f"{seek:.6f}", *still_input_args(args.input), "-i", args.input, "-vf", vf, "-frames:v", "1", "-update", "1", out]
+        cmd = ffmpeg_base() + ["-copyts", "-start_at_zero", "-ss", f"{seek:.6f}", *still_input_args(args.input), "-i", args.input, "-map", f"0:{PROBED_VIDEO}", "-vf", vf, "-frames:v", "1", "-update", "1", out]
         run(cmd)
         outputs.append(out)
         info(f"contact sheet: {n} frames every {step:.2f}s")

package/scripts/loudness.py

@@ -23,6 +23,7 @@ from _platforms import TP_TOLERANCE_DB
 
 AUDIO_LENGTH_TOLERANCE = 0.03  # seconds: one AAC frame at 48 kHz is 0.021 s
 LUFS_TOLERANCE = 1.0  # LU: a normalised file within this of the requested -I is on target
+from _common.probe import PROBED_AUDIO, probed_maps
 from _common import STATE, add_common, apply_common, emit, AUDIO_CODECS, audio_codec_for, default_output, die, ffmpeg_base, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, dry_run_input_pending
 
 
@@ -65,7 +66,11 @@ def measure(path: str, I: float, tp: float, lra: float) -> dict:
     if dry_run_input_pending(path):
         return {"input_i": "-20.0", "input_tp": "-3.0", "input_lra": "8.0", "input_thresh": "-30.0", "target_offset": "0.0", "silent": False, "placeholder": True}
     ffmpeg = require_tool("ffmpeg")
-    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-vn", "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
+    # the first audio track, the one pass 2 normalises and probe() describes: without a -map,
+    # FFmpeg measured the track with the default disposition or the most channels, and the gain
+    # for that track was applied to a:0 (A110)
+    cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", f"0:{PROBED_AUDIO}", "-vn",
+           "-af", f"loudnorm=I={I}:TP={tp}:LRA={lra}:print_format=json", "-f", "null", "-"]
     # Pass 1 is a measurement: it runs under --dry-run too, so the planned pass-2 command and
     # the reported input_i are real (before 1.4.6 a dry run returned a made-up -20 LUFS).
     proc = run_analysis(cmd, check=False, record=True)
@@ -112,9 +117,9 @@ def _normalize(args, meta: dict, stats: dict, lufs: float, tp_max: float, output
             af += f",atrim=duration={float(in_audio):.6f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-af", af, "-ar", str(sr)]
         if ext in AUDIO_CODECS or not meta.get("video"):
-            cmd += ["-vn"] + audio_codec_for(output, bitrate)
+            cmd += ["-map", f"0:{PROBED_AUDIO}", "-vn"] + audio_codec_for(output, bitrate)
         else:
-            cmd += ["-map", "0:v:0", "-map", "0:a:0", "-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
+            cmd += probed_maps(meta) + ["-c:v", "copy", "-c:a", "aac", "-b:a", bitrate]
             if ext in (".mp4", ".mov", ".m4v"):
                 cmd += ["-movflags", "+faststart"]
             dropped_streams = run_keeping_subtitles(cmd, output)

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