ffmpeg-skill 0.12.5 → 0.16.13

package/scripts/batch.py

@@ -36,6 +36,13 @@ from _common import STATE, add_common, apply_common, die, emit, info
 
 HERE = Path(__file__).resolve().parent
 MEDIA_EXT = {".mp4", ".mov", ".m4v", ".mkv", ".webm", ".avi", ".mts", ".m2ts", ".mxf", ".wav", ".m4a", ".mp3", ".flac"}
+# recipe steps name the script to run as plain, untrusted JSON -- run_step() joins it onto HERE
+# with the `/` operator, which silently ignores the left side when the right side is itself an
+# absolute path (Path("/scripts") / "/tmp/evil.py" == Path("/tmp/evil.py")), and does nothing to
+# stop a "../" traversal either. Without this allowlist, a batch.json a caller didn't author
+# themselves (from a template, a shared config, anywhere) could name any Python file on disk and
+# have it executed with the caller's own privileges on every matching media file.
+ALLOWED_STEP_SCRIPTS = {p.name for p in HERE.glob("*.py") if not p.name.startswith("_")}
 
 
 def file_key(path: Path) -> str:
@@ -51,11 +58,27 @@ def file_key(path: Path) -> str:
 
 
 def recipe_key(recipe: Dict[str, Any]) -> str:
-    return hashlib.sha1(json.dumps(recipe, sort_keys=True).encode()).hexdigest()[:12]
+    # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
+    # (export preset, captions, everything) live in the file at that path, not in this dict.
+    # Hashing only `recipe` meant editing project.json's content (without touching batch.json
+    # itself) left the key, and so every cache hit, unchanged: a preset swapped from "copy" to
+    # "x" (a real re-encode) still served the old cached output. Fold the referenced file's own
+    # content into the key so a content change invalidates the cache like any other edit would.
+    project_content = ""
+    if recipe.get("project"):
+        try:
+            project_content = Path(recipe["project"]).read_text(encoding="utf-8")
+        except OSError:
+            pass
+    return hashlib.sha1((json.dumps(recipe, sort_keys=True) + "\0" + project_content).encode()).hexdigest()[:12]
 
 
 def run_step(argv: List[str]) -> bool:
-    cmd = [sys.executable, str(HERE / argv[0])] + argv[1:]
+    script = argv[0]
+    if script not in ALLOWED_STEP_SCRIPTS:
+        die(f"recipe step names a script that isn't one of this skill's own tools: {script!r} "
+            f"(must be a bare filename like 'silence.py', found in scripts/)")
+    cmd = [sys.executable, str(HERE / script)] + argv[1:]
     if STATE["fast"]:
         cmd.append("--fast")
     if STATE["dry_run"]:
@@ -68,10 +91,20 @@ def run_step(argv: List[str]) -> bool:
     return True
 
 
-def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict[str, Any]:
+def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     suffix = recipe.get("suffix", "_out")
+    # By default final_ext falls back to each source's OWN extension, so files that only differ
+    # by extension don't collide -- but a recipe that fixes "ext" (e.g. converting a folder of
+    # mixed .mp4/.mov masters to one format) makes every source with the same stem land on the
+    # same final path, e.g. clip.mp4 and clip.mov both -> clip_out.mp4. process() has no collision
+    # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
+    # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
-    final = outdir / f"{src.stem}{suffix}.{final_ext}"
+    return outdir / f"{src.stem}{suffix}.{final_ext}"
+
+
+def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path) -> Dict[str, Any]:
+    final = final_path(src, recipe, outdir)
     t0 = time.time()
     if recipe.get("project"):
         proj = json.loads(Path(recipe["project"]).read_text(encoding="utf-8"))
@@ -140,6 +173,18 @@ def main() -> int:
     def one_pass() -> List[Dict[str, Any]]:
         results = []
         files = sorted(p for p in folder.glob(glob) if p.is_file() and p.suffix.lower() in MEDIA_EXT and outdir not in p.parents)
+        # Two different sources can compute the same final path (most often a fixed recipe "ext"
+        # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
+        # processing anything, rather than letting the later one silently overwrite the earlier
+        # one's finished output with the cache still recording both as "ok".
+        by_final: Dict[Path, List[Path]] = {}
+        for src in files:
+            by_final.setdefault(final_path(src, recipe, outdir), []).append(src)
+        collisions = {dst: srcs for dst, srcs in by_final.items() if len(srcs) > 1}
+        if collisions:
+            detail = "; ".join(f"{dst.name} <- {', '.join(s.name for s in srcs)}" for dst, srcs in collisions.items())
+            die(f"{len(collisions)} output filename collision(s) in this batch -- rename the sources, "
+                f"or add a distinguishing \"suffix\"/\"ext\" per run, or split into separate globs: {detail}")
         for src in files:
             key = f"{file_key(src)}:{rkey}"
             hit = cache.get(key)
@@ -152,7 +197,15 @@ def main() -> int:
             results.append(r)
             if r["ok"] and not STATE["dry_run"]:
                 cache[key] = r
-                cache_path.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+                # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
+                # a concurrent manual run) could leave a truncated file that json.loads() above
+                # then silently treats as "no cache" (a ValueError -> {}), discarding every prior
+                # entry. Write to a sibling temp file and rename into place: same-directory
+                # renames are atomic on POSIX and os.replace() is atomic on Windows too, so a
+                # reader only ever sees the old complete file or the new complete file.
+                tmp = cache_path.parent / f"{cache_path.name}.tmp{os.getpid()}"
+                tmp.write_text(json.dumps(cache, indent=2), encoding="utf-8")
+                os.replace(tmp, cache_path)
         return results
 
     results = one_pass()

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)")
@@ -471,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

@@ -274,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:

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())

package/scripts/export.py

@@ -26,7 +26,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color
 
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
@@ -63,6 +63,7 @@ def main() -> int:
         return 0
     if not args.input or not args.preset:
         die("input and --preset are required (or use --list)")
+    validate_color(args.pad_color, "--pad-color")
 
     p = PRESETS[args.preset]
     meta = probe(args.input)

package/scripts/fit.py

@@ -37,7 +37,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, x264_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args
 
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
@@ -114,6 +114,7 @@ def main() -> int:
         die(f"--crop-x must be 0..1, got {args.crop_x}")
     if not 0.0 <= args.crop_y <= 1.0:
         die(f"--crop-y must be 0..1, got {args.crop_y}")
+    validate_color(args.pad_color, "--pad-color")
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -193,8 +194,18 @@ def main() -> int:
             out_h = even(args.height)
             out_w = even(out_h * ratio) if ratio else args.height
         elif ratio and src_ratio:
-            out_w = even(sw if ratio <= src_ratio else sh * ratio)
-            out_h = even(out_w / ratio)
+            # No explicit --width/--height: size the canvas to the new aspect without exceeding
+            # the source's own resolution in either dimension. A narrower/taller target than the
+            # source (e.g. 9:16 from a 16:9 source) must be bounded by the source's HEIGHT, not
+            # its width -- bounding by width there multiplies the height by src_ratio/ratio (a
+            # 1920x1080 source asked for 9:16 used to come out 1920x3414, a ~3.16x upscale in
+            # both fit=pad and fit=crop, entirely unrequested).
+            if ratio <= src_ratio:
+                out_h = even(sh)
+                out_w = even(out_h * ratio)
+            else:
+                out_w = even(sw)
+                out_h = even(out_w / ratio)
         else:
             out_w, out_h = even(sw), even(sh)
         if args.fit == "crop":