ffmpeg-skill 0.12.0 → 0.16.12

package/scripts/caption.py

@@ -60,7 +60,12 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[fl
                 except MissingFpsError as e:
                     die(f"cue '{line}': {e} -- pass --fps, or --input's own fps is used automatically when given")
                 except ValueError:
-                    start, end, text = cursor, cursor + auto_seconds, line.strip()
+                    # TIME_RE matched (so m.group("text") is the real cue text, not the broken
+                    # timestamp), but one of the two timestamps itself failed to parse (e.g. a
+                    # malformed "00:00:03.15.999") -- falling back to `line.strip()` here used to
+                    # burn the whole raw line, broken timestamp included, into the caption instead
+                    # of just the text after it.
+                    start, end, text = cursor, cursor + auto_seconds, m.group("text").strip()
                 else:
                     text = m.group("text").strip()
             else:
@@ -165,6 +170,13 @@ def parse_srt(path: str) -> List[Tuple[float, float, str]]:
 def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
     with open(path, "w", encoding="utf-8") as fh:
         for i, (s, e, t) in enumerate(cues, 1):
+            # A blank line is SRT's own block separator (index/timecode/text, blank, next block).
+            # Cue text can contain one -- parse_text_cues() turns a bare "|" into "\n", so a source
+            # 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")
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
 
 
@@ -247,12 +259,20 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         "[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}", "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
         "[V4+ Styles]",
         "Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
-        f"Style: Default,{args.font},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
+        f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
         "", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
     ]
     lines = []
     for start, end, text in cues:
         text = text.replace("\n", "\\N")
+        # ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
+        # commands, not literal characters. Cue text (from --text, an SRT, or ASR transcription --
+        # all effectively user-controlled) that happens to contain braces would otherwise be
+        # interpreted as those commands (\pos, \t, \fscx, ...), letting caption content reposition,
+        # rescale, or recolor itself or later text instead of just being read out. No caption needs
+        # a literal curly brace, so they're dropped outright, matching the "unneeded delimiter
+        # character -> drop it" call already made for font names (see ass_font_name()).
+        text = text.replace("{", "").replace("}", "")
         fx = ""
         if args.animate == "fade":
             fx = "{\\fad(200,200)}"
@@ -302,6 +322,20 @@ def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     return f"&H{alpha:02X}{b}{g}{r}".upper()
 
 
+def ass_font_name(name: str) -> str:
+    """Sanitise a font name for embedding in an ASS [V4+ Styles] Style line (comma-delimited
+    fields, no quoting mechanism) and in a `force_style='...'` option list (comma-separated
+    Key=Value pairs, colon-separated from the rest of the -vf filter). No real font name uses
+    `, : \\ '`, so rather than chase a per-context escape (a Style line and a force_style list
+    have different delimiter rules), those characters -- and control characters, which are never
+    meaningful in a font name either -- are dropped outright, the same "no escape proven safe
+    everywhere it's used" call this codebase already makes for escape_drawtext()'s `'`/`%`."""
+    name = re.sub(r"[\x00-\x1f\x7f]", "", name)
+    for ch in ",:\\'":
+        name = name.replace(ch, "")
+    return name
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input", nargs="?", help="video to burn captions into (omit with --write-srt to only generate)")
@@ -427,14 +461,23 @@ def main() -> int:
         if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
             die(f"SRT file not found: {srt_path}")
         codec = mux_subtitle_codec(output)
+        # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
+        # language to build a multi-language set) -- copied byte-identical, distinct from the
+        # newly-added SRT's own codec below.
+        existing_subs = meta.get("subtitle_streams") or 0
         maps = ["-map", "0:v:0"]
         cmd = ffmpeg_base() + ["-i", args.input, "-i", srt_path]
         if meta.get("audio"):
             maps += ["-map", f"0:a:{args.audio_stream}"]
+        if existing_subs:
+            maps += ["-map", "0:s?"]
         maps += ["-map", "1:0"]
-        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else []) + ["-c:s", codec]
+        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])
+        for i in range(existing_subs):
+            cmd += [f"-c:s:{i}", "copy"]
+        cmd += [f"-c:s:{existing_subs}", codec]
         if args.language:
-            cmd += ["-metadata:s:s:0", f"language={args.language}"]
+            cmd += [f"-metadata:s:s:{existing_subs}", f"language={args.language}"]
         cmd += [output]
         run(cmd)
         result = probe(output, role="output")
@@ -462,7 +505,7 @@ def main() -> int:
         if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
             die(f"SRT file not found: {srt_path}")
         style = [
-            f"FontName={args.font}",
+            f"FontName={ass_font_name(args.font)}",
             f"FontSize={args.size}",
             f"PrimaryColour={ass_color(args.color)}",
             f"OutlineColour={ass_color(args.outline_color)}",

package/scripts/check.py

@@ -162,6 +162,14 @@ def main() -> int:
                 row("loudness", "PASS" if diff <= spec["lufs_tol"] else "FAIL", f"{lm['lufs']:.1f} LUFS", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", f"loudness.py -I {spec['lufs']:g} for speech or music; leave ambience/near-silence (<= -40 LUFS) alone and say so",
                     reason="the platform will auto-normalise it to its own target anyway, which can pump or duck the mix in ways you did not choose")
                 row("true peak", "PASS" if lm["tp"] <= spec["tp"] + 0.05 else "FAIL", f"{lm['tp']:.1f} dBTP", f"<= {spec['tp']:g} dBTP", f"loudness.py --tp {spec['tp']:g}")
+            else:
+                # ffmpeg's loudnorm JSON didn't parse out of stderr (unexpected/garbled output).
+                # Dropping the loudness/true-peak rows silently here would report an overall PASS
+                # for a platform that has a loudness requirement, without ever having checked it --
+                # a false PASS is worse than noise. WARN so the gap is visible in the report.
+                row("loudness", "WARN", "could not measure", f"{spec['lufs']:g} ± {spec['lufs_tol']:g} LUFS", "re-run check.py, or verify loudness manually",
+                    reason="ffmpeg's loudness measurement didn't produce a readable result -- this was not actually checked")
+                row("true peak", "WARN", "could not measure", f"<= {spec['tp']:g} dBTP", "re-run check.py, or verify true peak manually")
     elif args.platform in ("podcast",):
         row("audio", "FAIL", "none", "audio stream", "audio.py --replace")
     else:

package/scripts/color.py

@@ -2,7 +2,8 @@
 """Colour management: convert HDR (HDR10/PQ, HLG, BT.2020) to SDR BT.709 with
 real tone mapping, apply a .cube LUT (Log footage, creative grades), fix wrong
 colour tags without re-encoding, or apply typed primary colour correction
-(exposure, contrast, saturation, white balance).
+(exposure, contrast, saturation, gamma, white balance, three-way
+lift/gain, levels, curves).
 
 Examples:
   python3 color.py iphone_hdr.mov --to-sdr                       # PQ/HLG -> BT.709 SDR, hable tonemap
@@ -13,21 +14,26 @@ Examples:
   python3 color.py iphone_dv.mov --strip-dovi                       # drop Dolby Vision RPU, keep HLG base layer
   python3 color.py iphone_dv.mov --to-sdr                           # DV 8.4 = HLG base layer -> tone-mapped SDR
   python3 color.py flat.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05
+  python3 color.py flat.mp4 --correct --gamma 1.2 --lift 0.04 --gain -0.03   # three-way shadows/gamma/highlights
+  python3 color.py flat.mp4 --correct --levels-in-black 16 --levels-in-white 235 --curves medium_contrast
 """
 import argparse
 import os
 import sys
 from typing import List
 
-from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
 # Typed primary correction: each flag is one option of one real, always-available libavfilter filter
 # (never a caller-supplied filter string). Range is this script's own safe subset of what the filter
 # documents (`ffmpeg -h filter=<name>`), not the filter's full technical range. default is each filter's
-# own documented no-op value, so every stage below is always emitted and the chain never depends on
-# which flags were actually given.
+# own documented no-op value, so every stage in this dict is always emitted and the chain never depends
+# on which flags were actually given (exposure/temperature/tint/gamma/lift/gain). `colorlevels` and
+# `curves` (see LEVELS and CURVES_PRESETS below) are the exception: they only add a term to the chain
+# when the caller actually asks for them, because "levels 0..255 in, 0..255 out" and "no curve" are
+# already the identity operation without emitting a no-op filter term for it.
 CORRECTION = {
     #      flag           default  lo      hi       unit
     "exposure":    (0.0,   -3.0,    3.0,   "stops"),   # exposure filter's own full range (linear-domain stops)
@@ -35,8 +41,27 @@ CORRECTION = {
     "saturation":  (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
     "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (its own default)
     "tint":        (0.0,   -1.0,    1.0,   "x"),       # mapped to colorbalance midtones, see correction_chain()
+    "gamma":       (1.0,    0.1,   10.0,   "x"),       # eq filter's own gamma option; 1=unchanged (its own default)
+    "lift":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance shadows (rs=gs=bs); 0=unchanged
+    "gain":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance highlights (rh=gh=bh); 0=unchanged
 }
 
+# colorlevels takes fractional 0.0..1.0 input/output black/white points; this tool exposes the
+# familiar 8-bit 0..255 unit instead and divides by 255.0 when building the filter (same convention
+# as the rest of CORRECTION: a human-friendly CLI unit formatted into the filter's own native unit).
+LEVELS = {
+    #             flag             default  lo   hi
+    "levels_in_black":  (0,     0, 255),
+    "levels_in_white":  (255,   0, 255),
+    "levels_out_black": (0,     0, 255),
+    "levels_out_white": (255,   0, 255),
+}
+
+# curves filter's real built-in presets (`ffmpeg -h filter=curves`), excluding its own "none" (0):
+# omitting --curves already gets that identity result without adding a filter term for it.
+CURVES_PRESETS = ["color_negative", "cross_process", "darker", "increase_contrast", "lighter",
+                   "linear_contrast", "medium_contrast", "negative", "strong_contrast", "vintage"]
+
 
 def _checked(args: argparse.Namespace, flag: str) -> float:
     _, lo, hi, unit = CORRECTION[flag]
@@ -46,26 +71,65 @@ def _checked(args: argparse.Namespace, flag: str) -> float:
     return value
 
 
+def _checked_levels(args: argparse.Namespace, flag: str) -> int:
+    _, lo, hi = LEVELS[flag]
+    value = getattr(args, flag)
+    if not (lo <= value <= hi):
+        die(f"--{flag.replace('_', '-')} {value} is outside {lo}..{hi} (8-bit units, scaled to colorlevels' own 0..1 range)")
+    return value
+
+
 def correction_chain(args: argparse.Namespace) -> str:
-    """Four always-present filter stages, in a fixed order chosen so each stage sees a picture already
-    corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint, so
-    contrast/saturation act on colour-balanced footage) -> contrast -> saturation (the most creative-
-    adjacent stage, applied last). `tint` (-1 green .. +1 magenta) is not a single ffmpeg option: it is
-    expressed as colorbalance's three midtone channels (gm=-tint, rm=bm=tint/2) so a positive tint shifts
-    midtones toward magenta and a negative one toward green without changing overall midtone lightness,
-    the same balanced-axis convention colour tools use for a one-dial tint control."""
+    """Always-present filter stages, in a fixed order chosen so each stage sees a picture already
+    corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint/
+    lift/gain, so contrast/saturation act on colour-balanced footage) -> contrast/saturation/gamma
+    (the most creative-adjacent stage of the always-on chain). `tint` (-1 green .. +1 magenta) is not
+    a single ffmpeg option: it is expressed as colorbalance's three midtone channels (gm=-tint,
+    rm=bm=tint/2) so a positive tint shifts midtones toward magenta and a negative one toward green
+    without changing overall midtone lightness, the same balanced-axis convention colour tools use
+    for a one-dial tint control. `lift` and `gain` extend the same colorbalance call to the shadow
+    (rs=gs=bs=lift) and highlight (rh=gh=bh=gain) channels, giving a classic three-way shadows/
+    midtones/highlights correction in one filter invocation. `gamma` is folded into the same `eq`
+    term contrast/saturation already use, as `eq`'s own `gamma` option. Two further stages are
+    appended only when asked for, since their own identity value would otherwise add a no-op filter
+    term to the chain: `colorlevels` (--levels-*, 8-bit units scaled to the filter's 0..1 range) and
+    `curves` (--curves, one of the filter's own named presets)."""
     exposure = _checked(args, "exposure")
     contrast = _checked(args, "contrast")
     saturation = _checked(args, "saturation")
     temperature = _checked(args, "temperature")
     tint = _checked(args, "tint")
+    gamma = _checked(args, "gamma")
+    lift = _checked(args, "lift")
+    gain = _checked(args, "gain")
+    in_black = _checked_levels(args, "levels_in_black")
+    in_white = _checked_levels(args, "levels_in_white")
+    out_black = _checked_levels(args, "levels_out_black")
+    out_white = _checked_levels(args, "levels_out_white")
+    if in_black >= in_white:
+        die(f"--levels-in-black {in_black} must be less than --levels-in-white {in_white}")
+    if out_black >= out_white:
+        die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
+
     gm, rm, bm = -tint, tint / 2.0, tint / 2.0
-    return ",".join([
+    terms = [
         f"exposure=exposure={exposure:g}",
         f"colortemperature=temperature={temperature:g}",
-        f"colorbalance=rm={rm:g}:gm={gm:g}:bm={bm:g}",
-        f"eq=contrast={contrast:g}:saturation={saturation:g}",
-    ])
+        f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}",
+        f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}",
+    ]
+    if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
+        rimin, rimax = in_black / 255.0, in_white / 255.0
+        romin, romax = out_black / 255.0, out_white / 255.0
+        terms.append(
+            f"colorlevels=rimin={rimin:g}:gimin={rimin:g}:bimin={rimin:g}:"
+            f"rimax={rimax:g}:gimax={rimax:g}:bimax={rimax:g}:"
+            f"romin={romin:g}:gomin={romin:g}:bomin={romin:g}:"
+            f"romax={romax:g}:gomax={romax:g}:bomax={romax:g}"
+        )
+    if args.curves:
+        terms.append(f"curves=preset={args.curves}")
+    return ",".join(terms)
 
 
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
@@ -94,7 +158,7 @@ def main() -> int:
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
-    mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint")
+    mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint/--gamma/--lift/--gain/--levels-*/--curves")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
@@ -105,6 +169,14 @@ def main() -> int:
     ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
     ap.add_argument("--temperature", type=float, default=CORRECTION["temperature"][0], help="--correct: white-balance temperature in Kelvin, 2000..12000, 6500=unchanged (default 6500)")
     ap.add_argument("--tint", type=float, default=CORRECTION["tint"][0], help="--correct: green(-1)/magenta(+1) tint, 0=unchanged (default 0)")
+    ap.add_argument("--gamma", type=float, default=CORRECTION["gamma"][0], help="--correct: master gamma (eq filter's own gamma), 0.1..10, 1=unchanged (default 1)")
+    ap.add_argument("--lift", type=float, default=CORRECTION["lift"][0], help="--correct: shadows lift (colorbalance rs/gs/bs), -1..1, 0=unchanged (default 0)")
+    ap.add_argument("--gain", type=float, default=CORRECTION["gain"][0], help="--correct: highlights gain (colorbalance rh/gh/bh), -1..1, 0=unchanged (default 0)")
+    ap.add_argument("--levels-in-black", type=int, default=LEVELS["levels_in_black"][0], help="--correct: colorlevels input black point, 0..255 (default 0, unchanged)")
+    ap.add_argument("--levels-in-white", type=int, default=LEVELS["levels_in_white"][0], help="--correct: colorlevels input white point, 0..255 (default 255, unchanged)")
+    ap.add_argument("--levels-out-black", type=int, default=LEVELS["levels_out_black"][0], help="--correct: colorlevels output black point, 0..255 (default 0, unchanged)")
+    ap.add_argument("--levels-out-white", type=int, default=LEVELS["levels_out_white"][0], help="--correct: colorlevels output white point, 0..255 (default 255, unchanged)")
+    ap.add_argument("--curves", choices=CURVES_PRESETS, default=None, help="--correct: curves filter built-in preset (default: none, no curves term added)")
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
                           "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
@@ -202,8 +274,16 @@ def main() -> int:
     else:
         if not os.path.exists(args.lut):
             die(f"LUT not found: {args.lut}")
+        if not (0.0 <= args.lut_strength <= 1.0):
+            die(f"--lut-strength {args.lut_strength:g} is outside 0..1")
         lut = f"lut3d=file={escape_filter_path(args.lut)}:interp=tetrahedral"
-        if 0 < args.lut_strength < 1:
+        if args.lut_strength == 0.0:
+            # 0 means "no LUT at all" -- without this branch, 0 (falling outside the open interval
+            # below) landed in the same "apply the LUT at full strength" fallback as an out-of-range
+            # value did before the guard above existed: the one strength value documented to mean
+            # "don't grade it" instead silently graded it at 100%, the opposite of what was asked.
+            vf = "format=yuv420p"
+        elif args.lut_strength < 1.0:
             # blend graded and original
             vf = f"split[o][g];[g]{lut}[g2];[o][g2]blend=all_mode=normal:all_opacity={args.lut_strength:g},format=yuv420p"
         else:
@@ -212,16 +292,16 @@ def main() -> int:
         tag = "lut"
 
     cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
-    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
-    run(cmd)
+    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else [])
+    dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
+    extra = {"dropped_non_av_streams": dropped_streams}
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
-        emit(output, measurements=measurements)
-    else:
-        emit(output)
+        extra["measurements"] = measurements
+    emit(output, **extra)
     return 0
 
 

package/scripts/crop.py

@@ -38,6 +38,8 @@ def main() -> int:
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
 
     if args.x < 0 or args.y < 0:
         die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")

package/scripts/cropdetect.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Measure black letterbox/pillarbox bars and report the crop rectangle that removes them.
+
+Wraps FFmpeg's cropdetect filter: it samples frames, finds the largest
+non-black rectangle common to (recent) frames, and reports it. This is a
+measurement only -- it writes no file. Feed the reported {x, y, width,
+height} to crop.py to actually remove the bars:
+
+  python3 cropdetect.py input.mp4
+  python3 crop.py input.mp4 --x 0 --y 140 --width 1920 --height 800
+
+Distinct from fit.py --fit crop, which crops to a *target aspect ratio* it
+computes itself (no black-bar detection involved) -- this tool instead
+measures bars that are already baked into the source picture and tells you
+where they are; it does not decide whether removing them is wanted (a
+source with genuine letterboxed content, e.g. a scope-ratio film in a 16:9
+frame, will "detect" that letterboxing as bars to strip, which is correct
+for restoring the original frame but wrong if the letterboxing is part of
+the intended presentation -- look at the frame before cropping it away).
+
+--seconds controls how much of the file is sampled (default 10s, spread
+across the file by --samples windows so a single black scene near the start
+doesn't skew the result). Detected values fluctuate slightly frame to frame
+even on a static border; the reported rectangle is the most common one seen.
+
+Examples:
+  python3 cropdetect.py input.mp4
+  python3 cropdetect.py input.mp4 --seconds 30 --limit 0.15
+"""
+import argparse
+import re
+import subprocess
+import sys
+from collections import Counter
+from typing import Dict, List, Tuple
+
+from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool
+
+CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
+
+
+def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float) -> List[Tuple[int, int, int, int]]:
+    ffmpeg = require_tool("ffmpeg")
+    per_window = max(0.5, seconds / max(1, samples))
+    rects: List[Tuple[int, int, int, int]] = []
+    for i in range(samples):
+        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", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+        for m in CROP_RE.finditer(proc.stderr):
+            rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+    return rects
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("--seconds", type=float, default=10.0, help="total seconds of footage to sample across the file (default 10)")
+    ap.add_argument("--samples", type=int, default=5, help="number of windows spread across the file (default 5)")
+    ap.add_argument("--limit", type=float, default=0.0941176, help="black-pixel threshold, 0..1 (default ~0.094, cropdetect's own default)")
+    ap.add_argument("--round", type=int, default=16, dest="round_to", help="the reported width/height are rounded to a multiple of this (default 16)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    if args.seconds <= 0:
+        die(f"--seconds must be > 0, got {args.seconds:g}")
+    if args.samples <= 0:
+        die(f"--samples must be > 0, got {args.samples}")
+    if not 0 <= args.limit <= 1:
+        die(f"--limit must be 0..1, got {args.limit:g}")
+    if args.round_to <= 0:
+        die(f"--round must be > 0, got {args.round_to}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    duration = meta.get("duration") or 0.0
+
+    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration)
+    result: Dict = {"file": args.input, "source_width": sw, "source_height": sh}
+    if not rects:
+        result["crop"] = None
+        info("no crop bars detected (cropdetect produced no readings -- try --limit higher, or the source may already be full-frame)")
+    else:
+        w, h, x, y = Counter(rects).most_common(1)[0][0]
+        result["crop"] = {"width": w, "height": h, "x": x, "y": y}
+        result["confidence"] = round(Counter(rects).most_common(1)[0][1] / len(rects), 3)
+        if (w, h) == (sw, sh):
+            info(f"no bars detected: full {sw}x{sh} frame is already content")
+        else:
+            info(f"detected crop={w}:{h}:{x}:{y} (source {sw}x{sh}, confidence {result['confidence']:.0%}) -- "
+                 f"crop.py {args.input} --x {x} --y {y} --width {w} --height {h}")
+
+    if args.json:
+        emit(None, **result)
+    else:
+        print_json(result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cut.py

@@ -149,10 +149,14 @@ def main() -> int:
         segments = parse_segments(args.segments)
     else:
         start = parse_time(args.start)
+        if start < 0:
+            die(f"--start must not be negative, got {args.start!r}")
         if args.end and args.duration:
             die("use --end or --duration, not both")
         if args.end:
             end = parse_time(args.end)
+            if end < 0:
+                die(f"--end must not be negative, got {args.end!r}")
         elif args.duration:
             end = start + parse_time(args.duration)
         else:

package/scripts/deinterlace.py

@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Deinterlace interlaced source footage (old broadcast masters, DV, some camcorders).
+
+Wraps FFmpeg's yadif filter. --mode frame (default) keeps the original frame
+rate, blending each pair of fields back into one frame; --mode field instead
+emits one frame per field, doubling the frame rate (smoother motion, the
+usual choice for footage that will be watched at full quality). --parity
+tells yadif which field came first when the container doesn't say so
+correctly; --only-interlaced skips frames the source itself doesn't mark as
+interlaced, leaving already-progressive frames untouched.
+
+This tool does not detect whether the source needs deinterlacing at all --
+that's a probe.py/look.py judgement (visible combing on motion in a contact
+sheet). Running yadif on already-progressive footage is a harmless no-op in
+practice but still re-encodes the whole file, so don't run this by default.
+
+Examples:
+  python3 deinterlace.py old_tape.mov
+  python3 deinterlace.py broadcast.mxf --mode field --parity tff
+  python3 deinterlace.py mixed.mov --only-interlaced
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+MODES = {"frame": 0, "field": 1}
+PARITIES = {"auto": -1, "tff": 0, "bff": 1}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_deint.<ext>)")
+    ap.add_argument("--mode", choices=list(MODES), default="frame",
+                     help="frame (default): one output frame per input frame; field: one output frame per field, doubling fps")
+    ap.add_argument("--parity", choices=list(PARITIES), default="auto",
+                     help="which field came first (default auto-detect from the stream)")
+    ap.add_argument("--only-interlaced", action="store_true",
+                     help="only deinterlace frames the source marks as interlaced; leave the rest untouched")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to keep, 0-based in file order (default 0)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
+    output = args.output or default_output(args.input, "deint")
+
+    vf = f"yadif=mode={MODES[args.mode]}:parity={PARITIES[args.parity]}:deint={1 if args.only_interlaced else 0}"
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    if args.mode == "field":
+        v = meta["video"]
+        src_fps = v.get("fps") or 30.0
+        cmd += ["-fps_mode", "cfr", "-r", f"{src_fps * 2:g}"]
+    else:
+        cmd += cfr_args(meta)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['fps']:g}fps, mode={args.mode})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/denoise.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Reduce video noise/grain with FFmpeg's hqdn3d filter.
+
+For audio noise reduction use audio.py --denoise instead -- this tool only
+touches the picture. --strength picks a tested preset (low/medium/high,
+scaling hqdn3d's four spatial/temporal luma/chroma parameters together);
+--luma-spatial/--chroma-spatial/--luma-temporal/--chroma-temporal override
+any of the four individually when a preset isn't precise enough. Heavier
+denoising trades away fine detail (skin texture, foliage, film grain) for a
+cleaner-looking but softer image -- there is no setting that removes noise
+"for free"; --strength high is a real quality trade-off, not just "better".
+
+Examples:
+  python3 denoise.py noisy_lowlight.mp4
+  python3 denoise.py grainy_scan.mov --strength high
+  python3 denoise.py source.mp4 --luma-spatial 6 --chroma-spatial 4 --luma-temporal 8 --chroma-temporal 6
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+# hqdn3d's own AVOptions default to 0 (off); these tested presets are the light/medium/heavy
+# starting points its own documentation and common usage recommend (spatial then temporal,
+# luma then chroma -- chroma tends to tolerate more smoothing before looking soft).
+STRENGTH_PRESETS = {
+    "low": (2.0, 1.5, 3.0, 2.25),
+    "medium": (4.0, 3.0, 6.0, 4.5),
+    "high": (8.0, 6.0, 10.0, 7.5),
+}
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("input")
+    ap.add_argument("-o", "--output", help="output file (default: <name>_denoise.<ext>)")
+    ap.add_argument("--strength", choices=list(STRENGTH_PRESETS), default="medium",
+                     help="preset denoising amount (default medium); overridden per-parameter by the flags below")
+    ap.add_argument("--luma-spatial", type=float, help="spatial luma denoising strength (default from --strength)")
+    ap.add_argument("--chroma-spatial", type=float, help="spatial chroma denoising strength (default from --strength)")
+    ap.add_argument("--luma-temporal", type=float, help="temporal luma denoising strength (default from --strength)")
+    ap.add_argument("--chroma-temporal", type=float, help="temporal chroma denoising strength (default from --strength)")
+    ap.add_argument("--audio-stream", type=int, default=0,
+                     help="which audio stream of the input to keep, 0-based in file order (default 0)")
+    ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+    ap.add_argument("--preset", default="medium", help="x264 preset")
+    ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+    add_common(ap)
+    args = ap.parse_args()
+    apply_common(args)
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
+
+    ls, cs, lt, ct = STRENGTH_PRESETS[args.strength]
+    ls = args.luma_spatial if args.luma_spatial is not None else ls
+    cs = args.chroma_spatial if args.chroma_spatial is not None else cs
+    lt = args.luma_temporal if args.luma_temporal is not None else lt
+    ct = args.chroma_temporal if args.chroma_temporal is not None else ct
+    for name, val in (("--luma-spatial", ls), ("--chroma-spatial", cs), ("--luma-temporal", lt), ("--chroma-temporal", ct)):
+        if val < 0:
+            die(f"{name} must be >= 0, got {val:g}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    has_audio = bool(meta.get("audio"))
+    audio_streams = meta.get("audio_streams") or []
+    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+    if args.audio_stream and not audio_streams:
+        die("--audio-stream needs an input with audio streams")
+    output = args.output or default_output(args.input, "denoise")
+
+    vf = f"hqdn3d={ls:g}:{cs:g}:{lt:g}:{ct:g}"
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+    if has_audio:
+        cmd += ["-map", f"0:a:{args.audio_stream}?"]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    dropped_streams = run_keeping_subtitles(cmd, output)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, strength={args.strength})")
+    emit(output, dropped_non_av_streams=dropped_streams)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())