ffmpeg-skill 0.10.0 → 0.12.0

package/references/scripts.md

@@ -1,11 +1,17 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT`.
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Contents
 - probe.py — inspect
 - cut.py — cut / join segments
-- fit.py — target duration and/or aspect
+- fit.py — target duration and/or aspect, rotate/flip
+- crop.py — crop to an exact pixel rectangle
+- insert.py — still image to a timed silent clip, with Ken Burns zoom/pan
+- background.py — generate a solid-colour or gradient clip
+- reverse.py — reverse playback
+- stabilize.py — motion stabilisation (vidstab)
+- sequence.py — numbered/globbed image sequence to video
 - silence.py — remove dead air / jump cuts
 - join.py — concatenate with transitions
 - render.py — the whole edit in one project.json
@@ -21,12 +27,13 @@ Every script prints the same information with `--help`; this file exists so the
 - verify.py — real-footage verification kit
 - look.py — see the result
 - caption.py — subtitles (static, animated, karaoke)
-- overlay.py — logo, image, title
+- overlay.py — logo, image, title, video picture-in-picture, chroma key
 - sync.py — offset detection, alignment, drift correction
 - color.py — HDR to SDR, LUTs, colour tags, Dolby Vision
 - audio.py — clean-up, music, ducking, layout
 - loudness.py — EBU R128 normalisation
 - export.py — delivery presets
+- proxy.py — low-bitrate proxy for analysis/preview
 
 ## Scripts
 
@@ -48,18 +55,90 @@ keyframes, instant, lossless); if the snapped result deviates more than
 Multiple segments are concatenated in the order given. stderr reports whether
 the result was "lossless stream copy" or "re-encoded".
 
-### fit.py — target duration and/or aspect
+### fit.py — target duration and/or aspect, rotate/flip
 ```
 fit.py INPUT [--duration T --method speed|trim [--from-center] [--max-speed 4]]
-             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--pad-color black]]
-             [--fps N] [-o OUT]
+             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black]]
+             [--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT]
 ```
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
 refuses factors beyond `--max-speed`. For slow motion add `--smooth blend`
 (frame blending, fast) or `--smooth interpolate` (motion-compensated
 `minterpolate`, fluid but roughly 10-20x slower than realtime). `trim` keeps
-the head (or the middle with `--from-center`). `--fps` forces a constant frame
-rate; VFR sources are conformed automatically even without it.
+the head (or the middle with `--from-center`). `--width`/`--height` set the
+output size: give one and the other follows the aspect (source aspect if
+`--aspect` isn't also given); give both for an exact frame. `--rotate` applies
+a new clockwise rotation (90/180/270 swap width/height for 90 and 270 — this
+is separate from the rotation *metadata* fit.py already reads to size a
+source correctly); `--flip h|v` mirrors the picture; both can combine, rotate
+first. `--fps` forces a constant frame rate; VFR sources are conformed
+automatically even without it.
+
+### crop.py — crop to an exact pixel rectangle
+```
+crop.py INPUT --x X --y Y --width W --height H [-o OUT]
+```
+Crops to a literal `{x, y, width, height}` rectangle in source pixels —
+distinct from `fit.py --fit crop`, which crops to an *aspect ratio* and picks
+the rectangle for you. Use this when the rectangle is already known (a
+face-detection box, a saved crop, a hand-picked region). The rectangle must
+lie entirely inside the source frame (after accounting for display rotation);
+`--width`/`--height` must be even (4:2:0 chroma) and are refused, never
+rounded, if they aren't.
+
+### insert.py — still image to a timed silent clip
+```
+insert.py IMAGE --duration T [--width W] [--height H] [--fps N]
+                 [--zoom in|out [--zoom-amount 1.3]] [--pan left|right|up|down] [-o OUT]
+```
+Produces a silent, exact-duration clip from one image. `--width`/`--height`
+resolve like `fit.py`'s (one given -> the other follows the image's aspect;
+both given -> exact frame, scaled to fill and centre-cropped, never
+distorted). `--zoom in|out` is a Ken Burns effect: a slow linear zoom across
+the whole clip, ending (zoom in) or starting (zoom out) at `--zoom-amount`
+(default 1.3). `--pan` drifts the visible window across the image while
+zoomed — it needs `--zoom` (panning uses the extra image area a zoom exposes).
+
+### background.py — generate a solid-colour or gradient clip
+```
+background.py -o OUT --duration T --width W --height H
+              [--color C | --gradient C1:C2 [--angle DEG]]
+```
+No input file: ffmpeg's own `color`/`gradients` source filters generate the
+clip directly. For a title-card background, a placeholder layer, or a base
+for `overlay.py` to composite onto. `--width`/`--height` must be even.
+
+### reverse.py — reverse playback
+```
+reverse.py INPUT [--no-audio] [-o OUT]
+```
+Reverses video (and audio, unless `--no-audio`) with ffmpeg's `reverse`/
+`areverse` filters, which buffer the whole clip in memory — keep this to
+clips it makes sense to reverse (seconds to a couple of minutes), not
+something this tool limits for you.
+
+### stabilize.py — motion stabilisation
+```
+stabilize.py INPUT [--shakiness 1-10] [--smoothing N] [--zoom 0-100] [-o OUT]
+```
+Two-pass `vidstabdetect`/`vidstabtransform`: pass 1 analyses camera motion to
+a temporary transforms file (deleted after the run), pass 2 smooths and
+re-renders. `--shakiness` (default 5) trades analysis time for how much
+motion it looks for; `--smoothing` (default 15) is how many neighbouring
+frames the camera path is averaged over; `--zoom` crops in slightly to hide
+the black edges stabilizing can introduce. Needs an ffmpeg built with
+`--enable-libvidstab`; `doctor` reports this tool `usable: no` when that's
+missing (a plain Homebrew ffmpeg build, for example) rather than failing at
+run time.
+
+### sequence.py — numbered/globbed image sequence to video
+```
+sequence.py --dir DIR --pattern "frame_%04d.png"|"*.png" --fps N
+            [--start-number N] [--width W] [--height H] [-o OUT]
+```
+Turns a numbered or glob-matched set of still images into a video. The match
+is checked on disk before ffmpeg runs (an empty match or a missing first
+frame is refused here, not discovered from an opaque ffmpeg error).
 
 ### silence.py — remove dead air / jump cuts
 ```
@@ -204,25 +283,47 @@ frame like an editor would. Use `--compare` to show before/after to the user.
 ### caption.py — subtitles (static, animated, karaoke)
 ```
 caption.py INPUT --srt FILE | --ass FILE | --text CUES.txt [--write-srt OUT.srt]
+           [--mode burn|mux] [--audio-stream N] [--fps N]
            [--font NAME] [--fonts-dir DIR] [--size N] [--color RRGGBB] [--outline N] [--outline-color RRGGBB]
            [--bold] [--box] [--position bottom|top|center|top-left|...] [--margin N]
            [--animate none|fade|pop|slide] [--karaoke [--highlight-color RRGGBB]] [--write-ass OUT.ass] [-o OUT]
 caption.py --text CUES.txt --write-srt OUT.srt        # generate the SRT only
 ```
-Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`.
+Text cue format, one per line: `0:00-0:03 Hello`, `00:00:03.500 --> 00:00:06 Two | lines`,
+or `00:00:03:15 --> 00:00:06:00 SMPTE non-drop-frame timecode` (`hh:mm:ss:ff`, frame count
+converted with `--fps`, or the input video's own fps when `--input` is given and `--fps` is
+not — a timecode-shaped cue with no fps available is refused rather than misread as plain text).
 Lines without a time run for `--auto-seconds` (3 s) after the previous cue. `|` is a line break.
 `--animate`/`--karaoke` generate a styled ASS (PlayRes = video size) from the
 SRT/text cues: `pop` is the short-form "bouncy" entrance, `--karaoke` fills each
 word from `--color` to `--highlight-color` evenly across the cue (word timing
 is distributed, not transcribed). The ASS is kept next to the output so the
 user can hand-tune timings and re-run with `--ass`.
+`--mode burn` (default) renders subtitles into the picture and always
+re-encodes both streams. `--mode mux` copies video and audio untouched and
+adds the SRT as a separate, player-toggleable subtitle stream instead —
+takes only a plain SRT (`--srt`/`--text`/`--transcribe`, not `--ass`, since
+styling has no soft-subtitle equivalent) and no `--animate`/`--karaoke`. The
+subtitle codec follows the output container: `mov_text` for `.mp4`/`.m4v`/`.mov`,
+`srt` for `.mkv`, `webvtt` for `.webm`.
+`--audio-stream N` (default 0, the first track) picks which audio stream of a
+multi-track input (dubbed languages, M&E stems) is kept — applies to burn's
+re-encoded audio, mux's stream-copied audio, `--transcribe`'s speech-to-text
+source, and karaoke's energy-timing analysis alike, so all four agree on the
+same track instead of each silently defaulting to whichever one ffmpeg's own
+stream selection would have picked.
 
-### overlay.py — logo, image, title
+### overlay.py — logo, image, title, video picture-in-picture, chroma key
 ```
 overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--font-file F.ttf] [--font-size N] [--box]
+                  | --video CLIP [--chromakey COLOR [--chromakey-similarity 0-1] [--chromakey-blend 0-1]]
            [--position top-right|bottom-left|center|X,Y] [--margin N] [--start T] [--end T] [--fade S] [--opacity 0-1] [-o OUT]
 ```
-Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps playing.
+Alpha in PNGs is respected. Fades apply to the overlay only; the video keeps
+playing. `--video` composites a second video as a picture-in-picture layer
+(same position/scale/opacity/time-range knobs as `--image`); only the main
+input's audio is kept, the PiP layer's own audio is dropped. `--chromakey`
+(with `--video`) keys out that colour first for green-screen compositing.
 
 ### sync.py — offset detection, alignment, drift correction
 ```
@@ -292,3 +393,13 @@ export.py --list
 Scales into the preset frame (pad by default), tags BT.709, sets `+faststart`,
 trims to platform maximums (Reels 90 s, X 140 s) unless `--allow-long`.
 
+### proxy.py — low-bitrate proxy for analysis/preview
+```
+proxy.py INPUT [--width W | --scale F] [--crf N] [--fps N] [--no-audio] [-o OUT]
+```
+Not a delivery preset: resizes to `--width` (default 640) or by `--scale`
+factor, re-encodes at a proxy-grade `--crf` (default 30) with the fastest
+x264/x265 preset, keeps the source's own dynamic range (HDR stays HDR;
+run `color.py --to-sdr` first if SDR is wanted). Only executes the spec
+given — does not decide which asset to proxy or what for.
+

package/scripts/_common.py

@@ -41,12 +41,52 @@ INSTALL_HINTS = {
 }
 
 
+# `kind` (below) has been the only machine-readable failure axis since 0.1: a flat, 4-value
+# vocabulary (input / missing_tool / ffmpeg / output) set at the ~7 call sites that ever pass one
+# explicitly, defaulting to "input" everywhere else. `ERROR_CODE` is an additive, purely
+# informational refinement layered on top for agents that want a stable enum to switch on instead
+# of pattern-matching `kind` strings -- it is a static 1:1 relabelling of the exact same 4 buckets,
+# not a new taxonomy. It intentionally does NOT introduce categories this codebase cannot actually
+# distinguish today (e.g. a separate ffprobe-vs-ffmpeg code, or an environment-vs-content-cause
+# split of ffmpeg failures): every ffmpeg subprocess failure is currently one undifferentiated
+# bucket regardless of whether ffmpeg rejected a bad filter argument or died from a full disk,
+# and every "kind": "input" failure covers both a missing file and a bad flag value alike. Adding
+# codes for distinctions the code can't actually make would be guessing, not reporting -- if a
+# future call site can genuinely tell capability-missing apart from bad-argument (see doctor()'s
+# available/missing/unknown states, which already model this for detection but aren't wired into
+# any die() call), split ERROR_CODE then, with evidence, not speculatively now.
+ERROR_CODE = {
+    "input": "INPUT_INVALID",
+    "missing_tool": "DEPENDENCY_MISSING",
+    "ffmpeg": "FFMPEG_EXECUTION_FAILED",
+    "output": "OUTPUT_INVALID",
+}
+
+# None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
+# always deterministic (the same bad path or absent binary fails identically every time), and a
+# "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
+# condition (full disk, OOM) rather than a bad command -- is never distinguishable from a
+# deterministic content-cause failure without exit-code/stderr sniffing this codebase does not do.
+# Reporting retryable=True for a code we can't actually back up would invite an agent into a blind
+# retry loop against a command that will fail the same way every time; false-for-everything is the
+# honest answer until real sniffing exists to justify anything else.
+ERROR_RETRYABLE = False
+
+
 def die(msg: str, code: int = 1, kind: str = "input") -> "None":
     """Exit with a message. Under --json also print a machine-readable failure document
     (status: failed) on stdout so callers get the same shape as a success; exit codes are unchanged."""
     sys.stderr.write(f"error: {msg}\n")
     if STATE.json:
-        print_json({"status": "failed", "error": {"kind": kind, "message": msg}})
+        print_json({
+            "status": "failed", "exit_code": code,
+            "error": {
+                "kind": kind, "message": msg,
+                "code": ERROR_CODE.get(kind, "INTERNAL_ERROR"),
+                "retryable": ERROR_RETRYABLE,
+            },
+            "commands": list(STATE.commands),
+        })
     sys.exit(code)
 
 
@@ -135,10 +175,13 @@ def apply_common(args: "argparse.Namespace") -> None:
 
 def emit(output: Optional[str], **extra: Any) -> None:
     """Final stdout line: the output path, or a JSON document with --json."""
+    meta: Dict[str, Any] = {}
+    if output and not STATE.dry_run:
+        meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
     if STATE.json:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": STATE.dry_run, "commands": list(STATE.commands)}
-        if output and not STATE.dry_run and os.path.exists(output):
-            doc["probe"] = probe(output)
+        if meta:
+            doc["probe"] = meta
         doc.update(extra)
         print_json(doc)
     elif output:
@@ -153,11 +196,59 @@ def _is_ffmpeg(cmd: Sequence[str]) -> bool:
     return os.path.basename(cmd[0]).startswith("ffmpeg")
 
 
+def _cleanup_partial_output(cmd: Sequence[str]) -> None:
+    """A failed ffmpeg command can still have opened its output container (muxer header
+    written) before erroring out mid-stream -- unlike a failure that happens before ffmpeg ever
+    touches the output path (a bad filter argument, a missing input), which never creates the
+    file at all. Both are reported the same way (status: failed), but only the first case used
+    to leave a stray, usually-0-byte file behind: verify_output()'s cleanup only runs on the
+    success path, so a failed run() call never routed through it. Remove whatever ffmpeg managed
+    to write so a caller scanning the output directory after a failure never mistakes a partial
+    artifact for a real (if unverified) one."""
+    output = cmd[-1]
+    if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
+        return
+    try:
+        if os.path.exists(output):
+            os.remove(output)
+    except OSError:
+        pass
+
+
 def _fail(cmd: Sequence[str], returncode: int, stderr: str) -> None:
+    # Partial-output cleanup already ran in the caller (_run_captured/_run_with_progress) for
+    # every failed ffmpeg invocation, not just this check=True path -- see _cleanup_partial_output.
     tail = "\n".join(stderr.strip().splitlines()[-15:])
     die(f"command failed ({returncode}): {cmd[0]}\n{tail}", code=returncode or 1, kind="ffmpeg")
 
 
+def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
+    """Refuse an ffmpeg command whose output path resolves to the same file as one of its
+    inputs. ffmpeg's own "Output same as Input" guard only catches byte-identical path
+    strings; a relative/absolute pair, a leading "./", a redundant ".." segment, or a symlink
+    all resolve to the same file but pass that check, so "-o ./same.mp4" on an input opened as
+    "same.mp4" would otherwise silently let ffmpeg's -y clobber the source mid-encode. Every
+    write-side script routes through this one run() choke point rather than each computing its
+    own output path defensively, so the guard lives here once instead of at 25+ call sites."""
+    output = cmd[-1]
+    if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):
+        return
+    try:
+        out_real = os.path.realpath(output)
+    except OSError:
+        return
+    for i, a in enumerate(cmd):
+        if a == "-i" and i + 1 < len(cmd):
+            inp = cmd[i + 1]
+            try:
+                if os.path.realpath(inp) == out_real:
+                    die(f"refusing to run: output {output!r} is the same file as input {inp!r} "
+                        f"(would overwrite it while ffmpeg is still reading it) -- choose a different --output/-o path",
+                        kind="input")
+            except OSError:
+                continue
+
+
 def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:
     """Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.
 
@@ -167,6 +258,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     """
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
+        _check_no_overwrite_input(cmd)
         STATE.commands.append(_cmdline(cmd))
     if not quiet:
         info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
@@ -180,8 +272,17 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
 def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Plain run with stdout/stderr captured."""
     proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-    if check and proc.returncode != 0:
-        _fail(cmd, proc.returncode, proc.stderr)
+    if proc.returncode != 0:
+        # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
+        # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
+        # check=False so they can compose their own die() message from proc.stderr, but the
+        # partial-output risk is identical either way -- and for a script that retries into the
+        # same output path after a check=False failure (e.g. color.py's --retag copy-then-
+        # reencode fallback), removing the stale partial first is strictly safer than leaving it
+        # for -y to overwrite.
+        _cleanup_partial_output(cmd)
+        if check:
+            _fail(cmd, proc.returncode, proc.stderr)
     return proc
 
 
@@ -216,8 +317,10 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     _, err = proc.communicate()
     if last:
         sys.stderr.write("\r" + " " * len(last) + "\r")
-    if check and proc.returncode != 0:
-        _fail(cmd, proc.returncode, err)
+    if proc.returncode != 0:
+        _cleanup_partial_output(cmd)
+        if check:
+            _fail(cmd, proc.returncode, err)
     return subprocess.CompletedProcess(full, proc.returncode, "", err)
 
 
@@ -233,12 +336,56 @@ def ffmpeg_base(overwrite: bool = True) -> List[str]:
     return cmd
 
 
-def probe(path: str) -> Dict[str, Any]:
-    """Return a compact, script-friendly description of a media file."""
+MEDIA_EXT = {".mp4", ".mov", ".mkv", ".webm", ".m4v", ".avi", ".ts", ".mts", ".gif", ".wav", ".flac", ".mp3", ".m4a", ".aac", ".ogg", ".opus", ".png", ".jpg", ".jpeg"}
+
+
+def _output_failed(path: str, why: str) -> "None":
+    """An ffmpeg run reported success but the artifact is not usable: say so, and do not leave a
+    0-byte file behind that a later step could mistake for a result."""
+    try:
+        if os.path.exists(path) and os.path.getsize(path) == 0:
+            os.remove(path)
+            why += " (empty file removed)"
+    except OSError:
+        pass
+    die(f"output verification failed: {path}: {why}", kind="output")
+
+
+def verify_output(path: str) -> Dict[str, Any]:
+    """The success criterion for every writing tool: the file exists, is not empty and ffprobe
+    can read at least one stream from it. Non-media artifacts (srt, edl, html, md) only need to
+    exist and be non-empty. Returns the probe (empty dict for non-media)."""
+    if not os.path.exists(path):
+        _output_failed(path, "not written")
+    if os.path.getsize(path) == 0:
+        _output_failed(path, "0 bytes")
+    if os.path.splitext(path)[1].lower() not in MEDIA_EXT:
+        return {}
+    meta = probe(path, role="output")
+    if not meta.get("video") and not meta.get("audio"):
+        _output_failed(path, "no video or audio stream")
+    return meta
+
+
+def probe(path: str, role: str = "input") -> Dict[str, Any]:
+    """Return a compact, script-friendly description of a media file.
+
+    role="output" marks a file this tool just wrote: a read failure is then reported as an
+    output-verification failure (kind "output") instead of an input problem."""
     if not os.path.exists(path):
+        if role == "output" and not STATE["dry_run"]:
+            _output_failed(path, "not written")
         if STATE["dry_run"]:
+            # width/height/fps are honestly 0/0/0.0 -- "not measured", matching duration/size_bytes
+            # below -- because this is a dry run: the file doesn't exist yet, so there is nothing to
+            # probe. Earlier this stub used plausible-looking placeholders (1920x1080x30.0) instead,
+            # which some tools' dry-run summary line echoed verbatim as if it were a real computed
+            # preview (#77). That was reverted once, because a couple of call sites divided by these
+            # values for aspect-ratio math and crashed on a real 0 (join.py, fit.py); those call
+            # sites are now guarded to treat 0 as "unknown" and fall back sanely instead of dividing
+            # by it, so the stub can finally report the honest, unknown value.
             return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
-                    "video": {"codec": None, "width": 1920, "height": 1080, "fps": 30.0, "pix_fmt": None, "hdr": False,
+                    "video": {"codec": None, "width": 0, "height": 0, "fps": 0.0, "pix_fmt": None, "hdr": False,
                               "color_transfer": None, "color_primaries": None, "rotation": 0, "variable_frame_rate_suspected": False},
                     "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0}
         die(f"input not found: {path}")
@@ -249,6 +396,8 @@ def probe(path: str) -> Dict[str, Any]:
         check=False,
     )
     if proc.returncode != 0:
+        if role == "output":
+            _output_failed(path, f"ffprobe cannot read it:\n{proc.stderr.strip()}")
         die(f"ffprobe failed on {path}:\n{proc.stderr.strip()}")
     raw = json.loads(proc.stdout or "{}")
     fmt = raw.get("format", {})
@@ -274,6 +423,13 @@ def probe(path: str) -> Dict[str, Any]:
         "video": None,
         "audio": None,
         "subtitle_streams": len(subs),
+        # every subtitle stream in file order: index n here is `-map 0:s:n`
+        "subtitle_stream_details": [{
+            "index": n,
+            "codec": s.get("codec_name"),
+            "language": (s.get("tags") or {}).get("language"),
+            "title": (s.get("tags") or {}).get("title"),
+        } for n, s in enumerate(subs)],
     }
     if video:
         r_rate = _fraction(video.get("r_frame_rate"))
@@ -351,12 +507,30 @@ def default_output(input_path: str, suffix: str, ext: Optional[str] = None) -> s
     return str(p.with_name(f"{p.stem}_{suffix}.{new_ext}"))
 
 
-def parse_time(value: str) -> float:
-    """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250') or SRT '00:01:30,250'."""
+class MissingFpsError(ValueError):
+    """parse_time() saw an hh:mm:ss:ff SMPTE timecode but no fps was given to convert it -- distinct
+    from a plain ValueError so a caller that falls back to treating unparseable text as a literal
+    line (e.g. caption.py's free-text cue format) can still fail loudly on this one, instead of
+    silently swallowing a mistyped/missing --fps as an auto-timed line of digits."""
+
+
+def parse_time(value: str, fps: Optional[float] = None) -> float:
+    """Accept seconds ('12.5'), mm:ss ('1:30'), hh:mm:ss(.ms) ('00:01:30.250'), SRT '00:01:30,250',
+    or -- when `fps` is given -- SMPTE non-drop-frame timecode 'hh:mm:ss:ff' ('00:01:30:15')."""
     v = value.strip().replace(",", ".")
     if not v:
         raise ValueError("empty time")
     parts = v.split(":")
+    if len(parts) == 4:
+        if fps is None or fps <= 0:
+            raise MissingFpsError(f"'{value}' looks like an hh:mm:ss:ff SMPTE timecode, but no fps was given to convert its frame count to seconds")
+        h, m, s, f = parts
+        if "." in f:
+            raise ValueError(f"bad SMPTE timecode: {value}")
+        frame, whole_fps = int(f), int(round(fps))
+        if not (0 <= frame < whole_fps):
+            raise ValueError(f"bad SMPTE timecode '{value}': frame {frame} is out of range for {fps:g} fps (0-{whole_fps - 1})")
+        return int(h) * 3600 + int(m) * 60 + int(s) + frame / fps
     if len(parts) > 3:
         raise ValueError(f"bad time: {value}")
     total = 0.0
@@ -375,6 +549,20 @@ def fmt_srt_time(seconds: float) -> str:
     return f"{h:02d}:{m:02d}:{s:02d},{ms:03d}"
 
 
+def fmt_smpte_time(seconds: float, fps: float) -> str:
+    """SMPTE non-drop-frame timecode 'hh:mm:ss:ff' for a real fps (not the fractional NTSC rates
+    -- 29.97/59.94 need drop-frame counting to stay wall-clock accurate, which this does not do)."""
+    if seconds < 0:
+        seconds = 0.0
+    whole_fps = int(round(fps))
+    total_frames = int(round(seconds * fps))
+    frame = total_frames % whole_fps
+    secs_total = total_frames // whole_fps
+    h, rem = divmod(secs_total, 3600)
+    m, s = divmod(rem, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}:{frame:02d}"
+
+
 def escape_filter_path(path: str) -> str:
     """Escape a file path for use as a filter option value (subtitles=, ass=, lut3d=file=, fontfile=, fontsdir=).