ffmpeg-skill 0.9.0 → 0.12.0

package/scripts/audio.py

@@ -1,6 +1,8 @@
 #!/usr/bin/env python3
-"""Audio post: denoise, voice clean-up, background music with auto-ducking,
-fades and stereo/mono handling. Video is stream-copied.
+"""Audio post: denoise, voice clean-up, typed dynamics (compressor, limiter,
+gate), background music with auto-ducking, fades and stereo/mono handling.
+Video is stream-copied; an audio output extension (.wav/.flac/.mp3/.m4a/...)
+drops the picture, so `audio.py talk.mp4 -o talk.wav` is an extraction.
 
 Examples:
   python3 audio.py interview.mp4 --denoise                      # FFT noise reduction
@@ -10,15 +12,65 @@ Examples:
   python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
   python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
   python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
+  python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
+  python3 audio.py multi.mkv --audio-stream 1 --voice -o lav.m4a # pick the second audio track, clean it, write M4A
+  python3 audio.py talk.wav --compress --comp-threshold -20 --comp-ratio 4 --limit --limit-ceiling -1 -o talk_dyn.wav
 """
 import argparse
 import sys
 from typing import List
 
-from _common import add_common, apply_common, emit, audio_codec_for, default_output, die, ffmpeg_base, info, probe, run
+from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
+# Typed dynamics: every flag maps to one real option of one ffmpeg filter, validated against the
+# range that filter documents (ffmpeg -h filter=acompressor / alimiter / agate). dB flags are
+# converted to the linear value the filter takes, so no string reaches the graph unchecked.
+DYNAMICS = {
+    "acompressor": {
+        "comp_threshold": ("threshold", "dB", -60.0, 0.0),        # 0.000976563..1 linear
+        "comp_ratio": ("ratio", "x", 1.0, 20.0),
+        "comp_attack": ("attack", "ms", 0.01, 2000.0),
+        "comp_release": ("release", "ms", 0.01, 9000.0),
+        "comp_makeup": ("makeup", "dB", 0.0, 36.0),               # 1..64 linear
+        "comp_knee": ("knee", "dB", 1.0, 8.0),
+    },
+    "alimiter": {
+        "limit_ceiling": ("limit", "dB", -24.0, 0.0),             # 0.0625..1 linear
+        "limit_attack": ("attack", "ms", 0.1, 80.0),
+        "limit_release": ("release", "ms", 1.0, 8000.0),
+    },
+    "agate": {
+        "gate_threshold": ("threshold", "dB", -60.0, 0.0),        # 0..1 linear
+        "gate_ratio": ("ratio", "x", 1.0, 9000.0),
+        "gate_attack": ("attack", "ms", 0.01, 9000.0),
+        "gate_release": ("release", "ms", 0.01, 9000.0),
+        "gate_range": ("range", "dB", -90.0, 0.0),                # 0..1 linear: how far the gate closes
+        "gate_knee": ("knee", "dB", 1.0, 8.0),
+    },
+}
+
+
+def dynamics_filter(name: str, args: argparse.Namespace) -> str:
+    """One validated `acompressor=...` / `alimiter=...` / `agate=...` filter string from typed flags."""
+    opts = []
+    for flag, (opt, unit, lo, hi) in DYNAMICS[name].items():
+        value = getattr(args, flag)
+        if value is None:
+            continue
+        if not (lo <= value <= hi):
+            die(f"--{flag.replace('_', '-')} {value:g} is outside {lo:g}..{hi:g} {unit if unit != 'x' else ''}".rstrip()
+                + f" (the range ffmpeg's {name} accepts)")
+        if unit == "dB":
+            # the filters take linear amplitude (agate range: -90 dB -> 0.00003 closed, 0 dB -> 1 open)
+            opts.append(f"{opt}={db_to_linear(value):.6g}")
+        else:
+            opts.append(f"{opt}={value:g}")
+    if name == "alimiter":
+        opts.append("level=disabled")  # keep the level: a limiter must not normalise the whole track upwards
+    return name + ("=" + ":".join(opts) if opts else "")
+
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
@@ -43,10 +95,33 @@ def main() -> int:
     fades.add_argument("--mono", action="store_true", help="force 1-channel output")
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
+    dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
+    dyn.add_argument("--compress", action="store_true", help="compressor (acompressor); order: gate -> compressor -> limiter")
+    dyn.add_argument("--comp-threshold", type=float, help="dBFS above which gain is reduced, -60..0 (ffmpeg default -12.4)")
+    dyn.add_argument("--comp-ratio", type=float, help="ratio 1..20 (default 2)")
+    dyn.add_argument("--comp-attack", type=float, help="ms 0.01..2000 (default 20)")
+    dyn.add_argument("--comp-release", type=float, help="ms 0.01..9000 (default 250)")
+    dyn.add_argument("--comp-makeup", type=float, help="make-up gain dB 0..36 (default 0)")
+    dyn.add_argument("--comp-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    dyn.add_argument("--limit", action="store_true", help="look-ahead limiter (alimiter), level left as is")
+    dyn.add_argument("--limit-ceiling", type=float, help="ceiling dBFS -24..0 (default 0)")
+    dyn.add_argument("--limit-attack", type=float, help="ms 0.1..80 (default 5)")
+    dyn.add_argument("--limit-release", type=float, help="ms 1..8000 (default 50)")
+    dyn.add_argument("--gate", action="store_true", help="noise gate (agate)")
+    dyn.add_argument("--gate-threshold", type=float, help="dBFS below which the gate closes, -60..0 (default -18.1)")
+    dyn.add_argument("--gate-ratio", type=float, help="ratio 1..9000 (default 2)")
+    dyn.add_argument("--gate-attack", type=float, help="ms 0.01..9000 (default 20)")
+    dyn.add_argument("--gate-release", type=float, help="ms 0.01..9000 (default 250)")
+    dyn.add_argument("--gate-range", type=float, help="attenuation when closed, dB -90..0 (default -6.1)")
+    dyn.add_argument("--gate-knee", type=float, help="knee dB 1..8 (default 2.83)")
+    ap.add_argument("--audio-stream", type=int, default=0, help="which audio stream of the input to process, 0-based in file order (probe lists them under audio_streams)")
     ap.add_argument("--bitrate", default="192k")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
+    for flag_group, switch in (("acompressor", "compress"), ("alimiter", "limit"), ("agate", "gate")):
+        if not getattr(args, switch) and any(getattr(args, f) is not None for f in DYNAMICS[flag_group]):
+            die(f"--{switch} is off but one of its parameters was given; add --{switch}")
 
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
@@ -54,9 +129,15 @@ def main() -> int:
     if not meta.get("audio") and not args.replace:
         die("input has no audio stream (use --replace to add one)")
     output = args.output or default_output(args.input, "audio")
+    audio_out = is_audio_output(output)
+    streams = meta.get("audio_streams") or []
+    if streams and not (0 <= args.audio_stream < len(streams)) and not STATE["dry_run"]:
+        die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
+    if args.audio_stream and not streams and not STATE["dry_run"]:
+        die("--audio-stream needs an input with audio streams")
 
     inputs: List[str] = ["-i", args.input]
-    main_src = "0:a:0"
+    main_src = f"0:a:{args.audio_stream}"
     idx = 1
     if args.replace:
         probe(args.replace)
@@ -73,6 +154,12 @@ def main() -> int:
         fx.append(f"afftdn=nf=-{args.denoise_strength:g}:tn=1")
     if args.gain:
         fx.append(f"volume={args.gain:g}dB")
+    if args.gate:
+        fx.append(dynamics_filter("agate", args))
+    if args.compress:
+        fx.append(dynamics_filter("acompressor", args))
+    if args.limit:
+        fx.append(dynamics_filter("alimiter", args))
     if args.mono:
         fx.append("pan=mono|c0=0.5*c0+0.5*c1")
     elif args.stereo:
@@ -116,14 +203,20 @@ def main() -> int:
         last = "out"
 
     cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]
-    if has_video:
+    if has_video and not audio_out:
         cmd += ["-map", "0:v:0", "-c:v", "copy"]
+    elif has_video:
+        cmd += ["-vn"]  # audio extension: the picture is dropped, not copied into a container that cannot hold it
     cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
     run(cmd)
-    r = probe(output)
+    r = probe(output, role="output")
     a = r["audio"]
-    info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz)")
-    emit(output)
+    if r.get("video") and audio_out and not STATE["dry_run"]:
+        die(f"{output} unexpectedly contains a video stream")
+    info(f"wrote {output} ({r['duration']:.3f}s, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
+         + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
+    emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
+         dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f])
     return 0
 
 

package/scripts/background.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Generate a solid-colour or two-colour gradient background clip.
+
+No input file: a silent, fixed-duration, exact-size clip generated entirely
+by ffmpeg's own source filters (`color` for solid, `gradients` for a
+two-colour gradient) -- for a title card background, a placeholder behind a
+logo, or a base layer for overlay.py to composite onto.
+
+Examples:
+  python3 background.py --duration 3 --width 1920 --height 1080 --color 0x101010
+  python3 background.py --duration 5 --width 1080 --height 1920 --gradient 0xff6a00:0x0057ff --angle 45
+"""
+import argparse
+import math
+import sys
+
+from _common import add_common, apply_common, die, emit, ffmpeg_base, info, parse_time, probe, run, video_args
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("-o", "--output", required=True, help="output file")
+    ap.add_argument("--duration", required=True, help="clip duration (seconds or mm:ss)")
+    ap.add_argument("--width", type=int, required=True, help="output width in px (must be even)")
+    ap.add_argument("--height", type=int, required=True, help="output height in px (must be even)")
+    ap.add_argument("--fps", type=float, default=30.0, help="output frame rate (default 30)")
+    src = ap.add_mutually_exclusive_group()
+    src.add_argument("--color", default="black", help="solid background colour, e.g. black, 0x101010 (default black)")
+    src.add_argument("--gradient", help="two colours as C1:C2 for a linear gradient, e.g. 0xff6a00:0x0057ff")
+    ap.add_argument("--angle", type=float, default=0.0, help="gradient angle in degrees (with --gradient, default 0 = left to right)")
+    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)
+
+    target = parse_time(args.duration)
+    if target <= 0:
+        die("--duration must be > 0")
+    if args.fps <= 0:
+        die("--fps must be > 0")
+    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}")
+
+    if args.gradient:
+        try:
+            c0, c1 = args.gradient.split(":")
+        except ValueError:
+            die(f"--gradient needs two colours as C1:C2, got '{args.gradient}'")
+        rad = math.radians(args.angle)
+        x1 = round(args.width * math.cos(rad))
+        y1 = round(args.width * math.sin(rad))
+        src_filter = f"gradients=size={args.width}x{args.height}:rate={args.fps:g}:c0={c0}:c1={c1}:x0=0:y0=0:x1={x1}:y1={y1}"
+    else:
+        src_filter = f"color=c={args.color}:size={args.width}x{args.height}:rate={args.fps:g}"
+
+    output = args.output
+    cmd = ffmpeg_base() + ["-f", "lavfi", "-i", src_filter, "-t", f"{target:.3f}"]
+    cmd += video_args(None, args.crf, args.preset)
+    cmd += ["-an", output]
+    run(cmd)
+
+    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)")
+    emit(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/caption.py

@@ -1,12 +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.
+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:
@@ -23,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}
 
@@ -32,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:
@@ -43,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:
@@ -60,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."""
@@ -71,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")):
@@ -152,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,
@@ -167,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:
@@ -251,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)
@@ -266,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:
@@ -278,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)")
@@ -333,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:
@@ -354,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"
@@ -403,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/check.py

@@ -3,7 +3,12 @@
 
 Checks duration, frame size / aspect, fps, codec, pixel format, colour tags,
 file size, integrated loudness and true peak against the chosen platform
-and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs.
+and prints a PASS/WARN/FAIL table. Exit code 1 when anything FAILs. Each
+row's `fix` is the command that resolves it; a few of the less obvious FAILs
+(video codec, pixel format, HDR colour, loudness) also carry a plain-language
+`reason` -- "QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0",
+not a restatement of the spec value -- for a caller reporting this to someone
+who doesn't already know why the spec says what it says.
 
 Platforms: youtube, shorts, reels, tiktok, x, linkedin, broadcast (EBU R128), podcast, custom
 
@@ -88,10 +93,13 @@ def main() -> int:
 
     JUDGEMENT = {"duration", "aspect", "loudness", "fps", "resolution"}
 
-    def row(name: str, status: str, value: Any, expect: Any, fix: str = "") -> None:
+    def row(name: str, status: str, value: Any, expect: Any, fix: str = "", reason: str = "") -> None:
         # "format" rows are safe to fix mechanically; "judgement" rows change the content
-        # (what is cut, what is cropped, how loud ambience gets) and need a decision
+        # (what is cut, what is cropped, how loud ambience gets) and need a decision.
+        # "fix" is the command that resolves it; "reason" (only on the FAILs a non-technical
+        # person would ask "so what?" about) is why it matters in plain terms, not the spec clause.
         rows.append({"check": name, "status": status, "value": value, "expected": expect, "fix": fix,
+                     "reason": reason if status != "PASS" else "",
                      "kind": "judgement" if name in JUDGEMENT else "format"})
 
     dur = meta.get("duration") or 0.0
@@ -117,12 +125,15 @@ def main() -> int:
             row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")
         row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")
         if spec["codecs"]:
-            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"))
+            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube"),
+                reason="the platform's player may refuse to decode this codec at all, not just look worse")
         pf = v.get("pix_fmt") or ""
         if args.platform in ("reels", "tiktok", "x", "linkedin"):
-            row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p")
+            row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",
+                reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")
         if spec["sdr_only"] and v.get("hdr"):
-            row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr")
+            row("colour", "FAIL", v.get("hdr_format"), "SDR BT.709", "color.py --to-sdr",
+                reason="a platform or player without HDR support will show this washed-out, too dark, or with wrong colours -- not a rendering glitch, a colour space mismatch")
         else:
             tags = (v.get("color_primaries"), v.get("color_transfer"))
             untagged = not tags[0] and not tags[1]
@@ -148,7 +159,8 @@ def main() -> int:
             lm = measure_loudness(args.input)
             if lm:
                 diff = abs(lm["lufs"] - spec["lufs"])
-                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")
+                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}")
     elif args.platform in ("podcast",):
         row("audio", "FAIL", "none", "audio stream", "audio.py --replace")
@@ -164,6 +176,8 @@ def main() -> int:
             line = f"  {r['status']:4s} {r['check']:{width}s}  {r['value']}  (expected {r['expected']})"
             if r["status"] != "PASS" and r["kind"] == "judgement":
                 line += "  [judgement]"
+            if r["status"] != "PASS" and r["reason"]:
+                line += f"  ({r['reason']})"
             if r["status"] != "PASS" and r["fix"]:
                 line += f"  -> {r['fix']}"
             print(line)