ffmpeg-skill 0.10.0 → 0.12.0

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,36 @@ 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)
+        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}"]
+        maps += ["-map", "1:0"]
+        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else []) + ["-c:s", codec]
+        if args.language:
+            cmd += ["-metadata:s:s:0", 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 +479,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

@@ -105,6 +105,12 @@ 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("--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 +122,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 +139,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 +159,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,10 +211,10 @@ 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 = 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)
-    r = probe(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})")
     if measurements is not None:

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)

package/scripts/fit.py

@@ -5,7 +5,13 @@ Duration: --duration N with --method speed (retime video+audio, pitch-preserving
 via atempo chaining) or --method trim (keep the first N seconds, or a centred
 window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
 --fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.
---width sets the output width; height follows the aspect.
+--width and/or --height set the output size: give one and the other follows
+the aspect (source aspect if --aspect is not also given); give both for an
+exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
+rotation/mirror to the picture -- distinct from the rotation metadata a
+source already carries (read automatically to compute the displayed size,
+never altered by these flags unless asked). Both can be combined; rotate is
+applied before flip.
 
 Crop keeps the centre of the frame by default, which is a guess: going from
 16:9 to 9:16 throws away most of the width, and whatever isn't in the middle
@@ -20,6 +26,10 @@ Examples:
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
   python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
+  python3 fit.py input.mp4 --height 1080                         # width follows the source aspect
+  python3 fit.py input.mp4 --width 1920 --height 1080            # exact frame, no aspect needed
+  python3 fit.py input.mp4 --rotate 90                           # rotate 90 degrees clockwise
+  python3 fit.py input.mp4 --flip h                              # mirror horizontally
 """
 import argparse
 import math
@@ -66,6 +76,10 @@ 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>_fit.<ext>)")
+    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")
     d = ap.add_argument_group("duration")
     d.add_argument("--duration", help="target duration (seconds or mm:ss)")
     d.add_argument("--method", choices=["speed", "trim"], default="speed", help="how to reach the duration (default speed)")
@@ -76,10 +90,14 @@ def main() -> int:
     a = ap.add_argument_group("aspect")
     a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
     a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
-    a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")
+    a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
+    a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
     a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
     a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
+    r = ap.add_argument_group("rotate / flip")
+    r.add_argument("--rotate", type=int, choices=[90, 180, 270], help="rotate the picture clockwise by this many degrees")
+    r.add_argument("--flip", choices=["h", "v"], help="mirror the picture horizontally (h) or vertically (v)")
     e = ap.add_argument_group("encoding")
     e.add_argument("--crf", type=int, default=18)
     e.add_argument("--preset", default="medium")
@@ -88,8 +106,10 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
-    if not args.duration and not args.aspect and not args.width and not args.fps:
-        die("nothing to do: give --duration, --aspect, --width and/or --fps")
+    if args.fps is not None and args.fps <= 0:
+        die(f"--fps must be positive, got {args.fps:g}")
+    if not args.duration and not args.aspect and not args.width and not args.height and not args.fps and not args.rotate and not args.flip:
+        die("nothing to do: give --duration, --aspect, --width/--height, --rotate/--flip and/or --fps")
     if not 0.0 <= args.crop_x <= 1.0:
         die(f"--crop-x must be 0..1, got {args.crop_x}")
     if not 0.0 <= args.crop_y <= 1.0:
@@ -98,10 +118,17 @@ def main() -> int:
     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")
     src_dur = meta["duration"] or 0.0
     sw, sh = meta["video"]["width"], meta["video"]["height"]
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         sw, sh = sh, sw
+    if args.rotate in (90, 270):
+        sw, sh = sh, sw
     has_audio = bool(meta.get("audio"))
 
     vf: List[str] = []
@@ -110,6 +137,18 @@ def main() -> int:
     post: List[str] = []
     factor = 1.0
 
+    # ---- rotate / flip
+    if args.rotate == 90:
+        vf.append("transpose=1")
+    elif args.rotate == 270:
+        vf.append("transpose=2")
+    elif args.rotate == 180:
+        vf.append("transpose=2,transpose=2")
+    if args.flip == "h":
+        vf.append("hflip")
+    elif args.flip == "v":
+        vf.append("vflip")
+
     # ---- duration
     if args.duration:
         target = parse_time(args.duration)
@@ -142,14 +181,22 @@ def main() -> int:
                 info(f"source ({src_dur:.2f}s) is already shorter than {target:.2f}s; trim does nothing")
 
     # ---- aspect / size
-    if args.aspect or args.width:
-        src_ratio = Fraction(sw, sh)
+    if args.aspect or args.width or args.height:
+        src_ratio = Fraction(sw, sh) if sh else None
         ratio = parse_aspect(args.aspect) if args.aspect else src_ratio
-        if args.width:
+        if args.width and args.height:
+            out_w, out_h = even(args.width), even(args.height)
+        elif args.width:
             out_w = even(args.width)
-        else:
+            out_h = even(out_w / ratio) if ratio else args.width
+        elif args.height:
+            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)
+            out_h = even(out_w / ratio)
+        else:
+            out_w, out_h = even(sw), even(sh)
         if args.fit == "crop":
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
             vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
@@ -169,6 +216,9 @@ def main() -> int:
         cmd += ["-vf", ",".join(vf)]
     if af:
         cmd += ["-af", ",".join(af)]
+    cmd += ["-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 not args.fps else []
     if has_audio:
@@ -178,7 +228,7 @@ def main() -> int:
     cmd += post + [output]
     run(cmd)
 
-    result = probe(output)
+    result = probe(output, role="output")
     msg = f"wrote {output} ({result['duration']:.3f}s, {result['video']['width']}x{result['video']['height']})"
     if abs(factor - 1.0) > 1e-4:
         msg += f", speed {factor:.3f}x"

package/scripts/graphics.py

@@ -40,6 +40,10 @@ 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>_gfx.<ext>)")
+    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")
     ap.add_argument("--template", choices=TEMPLATES, required=True)
     ap.add_argument("--brand", help="brand.json for colours, font, safe margin")
     ap.add_argument("--name", help="lower-third: name line")
@@ -70,6 +74,11 @@ def main() -> int:
     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")
     W, H = meta["video"]["width"], meta["video"]["height"]
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         W, H = H, W
@@ -149,14 +158,14 @@ def main() -> int:
     output = args.output or default_output(args.input, "gfx")
     cmd = ffmpeg_base() + ["-i", args.input]
     if fc:
-        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", "0:a:0?"]
+        cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", f"0:a:{args.audio_stream}?"]
     else:
-        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-map", "0:a:0?"]
+        cmd += ["-vf", ",".join(filters), "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
     cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
     cmd.append(output)
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {args.template})")
     emit(output, template=args.template)
     return 0