ffmpeg-skill 0.10.0 → 0.12.5

package/scripts/caption.py

@@ -1,18 +1,25 @@
 #!/usr/bin/env python3
-"""Burn SRT/ASS subtitles into a video, or generate an SRT from plain text.
+"""Burn SRT/ASS subtitles into a video, or mux one in as a soft (toggleable)
+subtitle stream, or generate an SRT from plain text.
 
 Styling (font, size, colour, outline, position) applies to SRT input via
 libass force_style. ASS files carry their own styles and are rendered as-is.
-
-This only burns subtitles into the picture. There is no soft-subtitle (mux a
-subtitle stream, toggleable by the player) path -- every call re-encodes the
-whole video and its audio (see contract --json: reencodes_video/reencodes_audio
-are both "always" for this tool), even for a source that only needed the
-subtitle track added.
+Styling and animation only apply to --mode burn (the default): they render
+pixels, so they have no meaning for a soft subtitle stream.
+
+--mode mux copies the video and audio streams untouched (see contract --json:
+reencodes_video/reencodes_audio are "never" for this mode) and adds the SRT
+as a separate subtitle stream a player can toggle -- the source is never
+touched. It takes only a plain SRT (from --srt, --text or --transcribe), not
+--ass: ASS styling has no equivalent soft-subtitle representation across
+containers, so --mode mux --ass is refused with a pointer to --mode burn.
+The subtitle codec is picked from the output container: mov_text for
+.mp4/.m4v/.mov, srt for .mkv, webvtt for .webm.
 
 Text-to-SRT input format (one cue per line, blank lines ignored):
   0:00-0:03 Hello and welcome
   00:00:03.500 --> 00:00:06 Second line | with a manual line break
+  00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode (hh:mm:ss:ff, needs --fps)
   Text without a time is auto-timed after the previous cue (--auto-seconds)
 
 Examples:
@@ -29,7 +36,7 @@ import sys
 from pathlib import Path
 from typing import List, Optional, Tuple
 
-from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, info, parse_time, probe, run, x264_args
+from _common import STATE, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
 
@@ -38,7 +45,7 @@ TIME_RE = re.compile(
 )
 
 
-def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[float, float, str]]:
+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
     with open(path, encoding="utf-8") as fh:
@@ -49,7 +56,9 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[fl
             m = TIME_RE.match(line)
             if m:
                 try:
-                    start, end = parse_time(m.group("a")), parse_time(m.group("b"))
+                    start, end = parse_time(m.group("a"), fps), parse_time(m.group("b"), fps)
+                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()
                 else:
@@ -66,7 +75,7 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float) -> List[Tuple[fl
     return cues
 
 
-def transcribe(video: str, out_srt: str, language: Optional[str], model: str) -> List[Tuple[float, float, str]]:
+def transcribe(video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int = 0) -> List[Tuple[float, float, str]]:
     """Optional local ASR bridge. Tries, in order: whisper-cli / main (whisper.cpp), faster-whisper (python),
     whisper (openai-whisper CLI). Produces an SRT with word timings where the engine supports it.
     No engine installed -> clear error with install hints; the skill never depends on one."""
@@ -77,7 +86,8 @@ def transcribe(video: str, out_srt: str, language: Optional[str], model: str) ->
     ffmpeg = require_tool("ffmpeg")
     tmpdir = tempfile.mkdtemp(prefix="ffskill_asr_")
     wav = os.path.join(tmpdir, "audio.wav")
-    subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video, "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav], check=True)
+    subprocess.run([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
+                     "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav], check=True)
     # 1. whisper.cpp
     cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp") or shutil.which("main")
     if cli and (shutil.which("whisper-cli") or shutil.which("whisper-cpp")):
@@ -158,7 +168,7 @@ def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
             fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
 
 
-def word_durations_from_audio(video: str, start: float, end: float, n_words: int) -> List[int]:
+def word_durations_from_audio(video: str, start: float, end: float, n_words: int, audio_stream: int = 0) -> List[int]:
     """Split a cue's time across n_words in proportion to speech energy (centiseconds each).
 
     Decodes the cue window to 8 kHz mono, builds a 10 ms RMS envelope, removes the noise floor,
@@ -173,7 +183,7 @@ def word_durations_from_audio(video: str, start: float, end: float, n_words: int
         return [total_cs]
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
-           "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
+           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
     proc = sp.run(cmd, stdout=sp.PIPE, stderr=sp.PIPE)
     n = len(proc.stdout) // 2
     if proc.returncode != 0 or n < 800:
@@ -257,7 +267,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
             segments = body.split("\\N")
             words = [w for seg in segments for w in seg.split(" ") if w]
             if getattr(args, "karaoke_timing", "even") == "energy" and video:
-                durs = word_durations_from_audio(video, start, end, len(words))
+                durs = word_durations_from_audio(video, start, end, len(words), getattr(args, "audio_stream", 0))
             else:
                 per = max(1, dur_cs // max(1, len(words)))
                 durs = [per] * len(words)
@@ -272,6 +282,18 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         fh.write("\n".join(header + lines) + "\n")
 
 
+def mux_subtitle_codec(output: str) -> str:
+    ext = Path(output).suffix.lower()
+    if ext in (".mp4", ".m4v", ".mov"):
+        return "mov_text"
+    if ext == ".mkv":
+        return "srt"
+    if ext == ".webm":
+        return "webvtt"
+    die(f"--mode mux: don't know a soft-subtitle codec for '{ext}' output "
+        "(know .mp4/.m4v/.mov, .mkv, .webm) -- use --mode burn, or pick one of those containers with -o")
+
+
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = hex_rgb.lstrip("#")
     if len(h) != 6:
@@ -284,16 +306,26 @@ 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)")
     ap.add_argument("-o", "--output", help="output video (default: <name>_captioned.<ext>)")
+    ap.add_argument("--mode", choices=["burn", "mux"], default="burn",
+                     help="'burn' renders subtitles into the picture (default); "
+                          "'mux' copies video/audio untouched and adds the SRT as a soft, toggleable subtitle stream")
+    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, "
+                          "the first track, same as leaving it unset always did")
     src = ap.add_argument_group("subtitle source")
     src.add_argument("--srt", help="SRT file to burn")
     src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
     src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
     src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (whisper-cli / whisper / faster-whisper); never required")
-    src.add_argument("--language", help="language code for --transcribe (e.g. en, ja); default auto")
+    src.add_argument("--language", help="language code for --transcribe (e.g. en, ja; default auto), also tagged on the subtitle stream with --mode mux")
     src.add_argument("--model", default="base", help="whisper model name/path for --transcribe (default base)")
     src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
     src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
     src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
+    src.add_argument("--fps", type=float, default=None,
+                      help="frame rate for interpreting hh:mm:ss:ff SMPTE timecode cues in --text (non-drop-frame); "
+                           "defaults to the input video's own fps when --input is given, required otherwise")
     sty = ap.add_argument_group("style (SRT only)")
     sty.add_argument("--brand", help="brand.json: font, colours, caption size/position/animation defaults")
     sty.add_argument("--font", default=None, help="font family, e.g. 'Noto Sans CJK JP' for Japanese (default DejaVu Sans or brand font)")
@@ -339,17 +371,37 @@ def main() -> int:
         args.fonts_dir = str(Path(brand["font_file"]).parent)
     if not (args.srt or args.ass or args.text or args.transcribe):
         die("give one of --srt, --ass, --text or --transcribe")
+    if args.mode == "mux":
+        if args.ass:
+            die("--mode mux takes --srt (or --text/--transcribe), not --ass -- "
+                "ASS carries burn-only styling with no soft-subtitle equivalent; use --mode burn for an ASS file")
+        if args.animate != "none" or args.karaoke:
+            die("--animate/--karaoke render pixels into the picture and require --mode burn")
+
+    meta = None
+    if args.input:
+        meta = probe(args.input)
+        if not meta.get("video"):
+            die("input has no video stream")
+        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")
+    fps_for_tc = args.fps
+    if fps_for_tc is None and meta is not None:
+        fps_for_tc = meta.get("video", {}).get("fps")
 
     srt_path = args.srt
     if args.transcribe:
         if not args.input:
             die("--transcribe needs the input video")
         srt_path = args.write_srt or os.path.splitext(args.input)[0] + ".srt"
-        cues = transcribe(args.input, srt_path, args.language, args.model)
+        cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
         info(f"wrote {srt_path} ({len(cues)} cues)")
         args.text = None
     if args.text:
-        cues = parse_text_cues(args.text, args.auto_seconds, args.gap)
+        cues = parse_text_cues(args.text, args.auto_seconds, args.gap, fps_for_tc)
         if args.write_srt:
             srt_path = args.write_srt
         elif args.input:
@@ -360,18 +412,45 @@ def main() -> int:
             srt_path = os.path.splitext(args.text)[0] + ".srt"
         if not STATE.dry_run:
             write_srt(cues, srt_path)
-        info(f"wrote {srt_path} ({len(cues)} cues)")
+        tc_range = f", {fmt_smpte_time(cues[0][0], fps_for_tc)}-{fmt_smpte_time(cues[-1][1], fps_for_tc)} @ {fps_for_tc:g}fps" if fps_for_tc else ""
+        info(f"wrote {srt_path} ({len(cues)} cues{tc_range})")
         if not args.input:
             print(srt_path)
             return 0
 
     if not args.input:
         die("input video is required unless you only use --text/--write-srt")
-    meta = probe(args.input)
-    if not meta.get("video"):
-        die("input has no video stream")
 
     output = args.output or default_output(args.input, "captioned")
+
+    if args.mode == "mux":
+        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 [])
+        for i in range(existing_subs):
+            cmd += [f"-c:s:{i}", "copy"]
+        cmd += [f"-c:s:{existing_subs}", codec]
+        if args.language:
+            cmd += [f"-metadata:s:s:{existing_subs}", f"language={args.language}"]
+        cmd += [output]
+        run(cmd)
+        result = probe(output, role="output")
+        info(f"wrote {output} ({result.get('duration'):.3f}s, mux, subtitle codec {codec})")
+        emit(output)
+        return 0
+
     if (args.animate != "none" or args.karaoke) and not args.ass:
         cues_for_ass = cues if args.text else parse_srt(srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
@@ -409,10 +488,13 @@ def main() -> int:
         if args.fonts_dir:
             vf += f":fontsdir={escape_filter_path(args.fonts_dir)}"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
+    cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0"]
+    if meta.get("audio"):
+        cmd += ["-map", f"0:a:{args.audio_stream}"]
+    cmd += ["-vf", vf] + video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += (aac_args() if meta.get("audio") else ["-an"]) + [output]
     run(cmd)
-    result = probe(output)
+    result = probe(output, role="output")
     info(f"wrote {output} ({result.get('duration'):.3f}s)")
     emit(output)
     return 0

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,20 @@ 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, "
+                          "the first track, same as leaving it unset always did. Only affects modes that re-encode "
+                          "audio (--to-sdr, --lut, --correct, and --retag's re-encode fallback) -- --strip-dovi and "
+                          "a successful --retag stream-copy all streams untouched, so the flag has nothing to select there.")
     ap.add_argument("--crf", type=int, default=18)
     ap.add_argument("--preset", default="medium")
     add_common(ap)
@@ -116,6 +194,11 @@ def main() -> int:
         die("input has no video stream")
     v = meta["video"]
     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")
 
     if args.strip_dovi:
         output = args.output or default_output(args.input, "nodv")
@@ -128,7 +211,7 @@ def main() -> int:
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)
         run(cmd)
-        r = probe(output)
+        r = probe(output, role="output")
         info(f"wrote {output} (dolby_vision={r['video'].get('dolby_vision')})")
         emit(output)
         return 0
@@ -148,14 +231,30 @@ def main() -> int:
             cmd += ["-movflags", "+faststart"]
         cmd.append(output)
         proc = run(cmd, check=False)
+        dropped_streams = False
         if proc.returncode != 0:
-            # some codecs cannot carry retagged colour info without a bitstream filter; fall back to re-encode
-            info("stream copy could not rewrite tags, re-encoding")
-            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", "0:a:0?"] + x264_args(args.crf, args.preset, keep_bt709=False)
-            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
-            run(cmd)
+            # Some codecs cannot carry retagged colour info without a bitstream filter, so the
+            # stream copy above fails and we fall back to re-encoding video+audio. The copy path
+            # (-map 0 -c copy) keeps every stream -- extra audio tracks, subtitles, chapters,
+            # attached pictures -- byte-for-byte; -c:s/-c:d copy here keeps that same guarantee
+            # for subtitle/data streams even though video/audio must be re-encoded. Only if THAT
+            # also fails (e.g. a subtitle codec genuinely incompatible with the target container)
+            # do we drop to video+selected-audio-only, and even then we say so explicitly rather
+            # than silently reporting "completed" with streams missing.
+            info("stream copy could not rewrite tags, re-encoding video/audio (subtitles/data streams kept)")
+            cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
+                                    "-map", "0:s?", "-map", "0:d?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+            cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]]
+            cmd += (aac_args() if has_audio else []) + ["-c:s", "copy", "-c:d", "copy"] + [output]
+            proc2 = run(cmd, check=False)
+            if proc2.returncode != 0:
+                info("re-encode with subtitles/data streams kept also failed; dropping them")
+                dropped_streams = True
+                cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"] + x264_args(args.crf, args.preset, keep_bt709=False)
+                cmd += ["-colorspace", tags[0], "-color_primaries", tags[1], "-color_trc", tags[2]] + (aac_args() if has_audio else []) + [output]
+                run(cmd)
         info(f"wrote {output} (tags -> {args.retag})")
-        emit(output)
+        emit(output, reencoded=proc.returncode != 0, dropped_non_av_streams=dropped_streams)
         return 0
 
     measurements = None
@@ -184,17 +283,17 @@ def main() -> int:
         output = args.output or default_output(args.input, "lut")
         tag = "lut"
 
-    cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0", "-map", "0:a:0?"]
-    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else []) + [output]
-    run(cmd)
-    r = probe(output)
+    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 [])
+    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

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Crop a video to an exact pixel rectangle.
+
+{x, y, width, height} are literal pixel offsets and dimensions in the SOURCE
+frame, not aspect-ratio-relative -- for cropping to a target aspect ratio
+(e.g. 16:9 -> 9:16) use fit.py --fit crop instead, which computes the
+rectangle for you and lets you steer it with --crop-x/--crop-y. This tool is
+for when the caller already knows the exact rectangle (a face-detection box,
+a saved crop from a previous edit, a hand-picked region).
+
+The rectangle must lie entirely inside the source frame after accounting for
+any display rotation, and --width/--height must be even (required for 4:2:0
+chroma subsampling, the pixel format every encoder here uses) -- given values
+are validated and refused, never silently rounded, since a caller-specified
+rectangle should do exactly what was asked or fail loudly.
+
+Examples:
+  python3 crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920
+  python3 crop.py input.mp4 --x 0 --y 140 --width 1920 --height 800 -o cropped.mp4
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+
+
+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>_crop.<ext>)")
+    ap.add_argument("--x", type=int, required=True, help="left edge of the crop rectangle, in source pixels")
+    ap.add_argument("--y", type=int, required=True, help="top edge of the crop rectangle, in source pixels")
+    ap.add_argument("--width", type=int, required=True, help="crop width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="crop height in px (must be even)")
+    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.x < 0 or args.y < 0:
+        die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")
+    if args.width <= 0 or args.height <= 0:
+        die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+    if args.width % 2 or args.height % 2:
+        die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+
+    meta = probe(args.input)
+    if not meta.get("video"):
+        die("input has no video stream")
+    sw, sh = meta["video"]["width"], meta["video"]["height"]
+    if meta["video"].get("rotation") in (90, -90, 270, -270):
+        sw, sh = sh, sw
+    if args.x + args.width > sw or args.y + args.height > sh:
+        die(f"crop rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
+    has_audio = bool(meta.get("audio"))
+
+    output = args.output or default_output(args.input, "crop")
+    vf = [f"crop={args.width}:{args.height}:{args.x}:{args.y}", "setsar=1"]
+    cmd = ffmpeg_base() + ["-i", args.input, "-vf", ",".join(vf)]
+    cmd += video_args(meta, args.crf, args.preset)
+    cmd += cfr_args(meta, args.fps)
+    if has_audio:
+        cmd += aac_args()
+    else:
+        cmd += ["-an"]
+    cmd.append(output)
+    run(cmd)
+
+    result = probe(output, role="output")
+    v = result["video"]
+    info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']})")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/cut.py

@@ -112,7 +112,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         if not reencode:
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta)
-        die(f"ffmpeg failed:\n{proc.stderr.strip()}")
+        die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
     if not reencode and tolerance >= 0 and not STATE["dry_run"]:
         got = probe(dst).get("duration") or 0.0
         if abs(got - dur) > tolerance:
@@ -190,7 +190,7 @@ def main() -> int:
                 cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile] + encode_args(meta, output, args.crf, args.preset) + [output]
                 run(cmd)
 
-    result = probe(output)
+    result = probe(output, role="output")
     expected = sum(e - s for s, e in segments)
     precision = precision_of(meta, output, reencoded)
     got = result.get("duration")

package/scripts/export.py

@@ -118,7 +118,7 @@ def main() -> int:
         cmd += ["-t", f"{p['max']:.3f}"]
     cmd.append(output)
     run(cmd)
-    result = probe(output)
+    result = probe(output, role="output")
     v = result["video"]
     info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['codec']})")
     emit(output)