ffmpeg-skill 0.12.0 → 0.12.5

package/README.md

@@ -29,6 +29,12 @@ npx ffmpeg-skill
 
 If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.
 
+> **SPEC** (Self-Producing Execution Contract), coined by this project's author
+> [kajisho5](https://github.com/kajisho5): each tool's `input_schema` — the part of its contract
+> and MCP tool definition that has to track the CLI flag-for-flag — is never hand-authored beside
+> the code. It's derived, at run time, from the same `argparse` parser that already defines the
+> CLI, and CI fails the build if any of it drifts. → [full explanation](#what-is-spec)
+
 ---
 
 ## Standalone, and in an ecosystem
@@ -94,6 +100,8 @@ python3 $S/fit.py input.mp4 --duration 60 --aspect 9:16 --dry-run    # print the
 python3 $S/export.py input.mp4 --preset reels --json                 # structured result with a probe of the output
 ```
 
+On Windows in Git Bash, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — replace `python3` with `python` above if you see a "command not found". `bin/install.js` and `doctor`/`contract` already handle this for you; only the raw script examples above need it spelled out manually.
+
 More requests and the commands behind them: [examples/README.md](examples/README.md). To see everything run end-to-end on generated footage: `npm run demo`.
 
 ## How it works
@@ -180,7 +188,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 | `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; animated and word-by-word karaoke timed to the speech energy; optional local transcription |
 | `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--video` for picture-in-picture, `--chromakey` for green-screen compositing |
 | `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs drawn by FFmpeg from a brand kit |
-| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/white balance) |
+| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |
 
 **Delivery**
 
@@ -216,6 +224,34 @@ Picture tools (`fit`, `caption`, `overlay`, `graphics`, `color`, `export`, `scen
 
 ## Built for agents
 
+### What is SPEC?
+
+This project's author, [kajisho5](https://github.com/kajisho5), coined **SPEC** (Self-Producing
+Execution Contract) for the pattern this skill's tool layer is built on: each tool's `input_schema`
+— the part of its contract that has to track the CLI exactly, flag for flag — is never
+hand-authored side by side with the code. It is derived, at run time, from the one thing that
+actually has to be correct for the CLI to work at all: the script's own `argparse` parser.
+
+Concretely, `scripts/_contract.py`'s `_capture_parser()` imports every tool script and
+intercepts its `parse_args()` call to get the live, fully-built parser object — flags, types,
+choices, defaults, required/positional, mutually exclusive groups, all of it. `input_schema` is
+built straight from that object. (The rest of a `ToolSpec` — `role`, `capabilities`, `inputs`,
+`outputs`, `output_schema` — comes from a hand-authored table, `TOOL_META`, since those facts
+aren't things a parser can express; only `input_schema` is parser-derived.)
+
+- **The contract**'s `input_schema` for every tool is generated from the live parser directly.
+- **The MCP server** (`mcp/server.py`) carries no schema of its own; `tools/list` is translated
+  straight from the contract, `input_schema` included.
+- **The docs** (`docs/contract.md`'s field reference, this README's tool table) describe the same
+  shape. `tests/test_contract.py` runs on every CI run and fails the build if any of them drift
+  out of sync with what the code actually does — it catches drift, it doesn't fix it for you.
+
+The result: add a flag to a script's `argparse` block, and `input_schema` and the MCP tool
+definition follow with no second edit; if a docs page or a `TOOL_META` entry falls behind, CI
+catches it rather than letting it drift silently. There is no separate `input_schema` file to
+forget to update, and no version of "what CLI flags does this tool accept" that can quietly go
+stale.
+
 ### Machine-readable contract
 
 ```bash

package/SKILL.md

@@ -299,6 +299,18 @@ Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | out
   `caption.py --fonts-dir ./fonts --font "Noto Sans CJK JP"`). Without a
   matching font you get boxes, not an error. Install: `apt install fonts-noto-cjk`,
   `brew install --cask font-noto-sans-cjk`.
+- **Windows drawtext crashes on some real builds.** On certain Windows ffmpeg
+  builds (e.g. winget's gyan.dev), `drawtext` crashes with an access violation
+  whenever it resolves a font by family name through fontconfig, even with a
+  valid `fonts.conf` (#100). `look.py`, `scenes.py --sheet`, `overlay.py --text`
+  and `graphics.py` all resolve a concrete `--font-file` by default when one is
+  available (`fontfile=` skips fontconfig entirely and is the form confirmed
+  not to crash), so this should already be handled automatically. If a
+  drawtext tool still crashes, pass `--font-file` explicitly rather than
+  relying on `--font`/`font=` resolution; `doctor` also runs a real one-frame
+  drawtext probe and reports `filter:drawtext` missing (with the crash detail
+  in `errors[]`) rather than a false "available" from the `-filters` listing
+  alone.
 - **Keyframe cuts.** A lossless `cut.py` result may start up to one GOP (often
   1–10 s) earlier than requested; the script re-encodes automatically when the
   deviation exceeds 0.5 s. If the user insists on lossless output, pass

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "0.12.0",
+  "version": "0.12.5",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 28 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/references/scripts.md

@@ -352,7 +352,23 @@ color.py INPUT --to-sdr [--tonemap hable|mobius|reinhard|bt2390] [--peak 1000] [
 color.py INPUT --lut grade.cube [--lut-strength 0..1] [-o OUT]
 color.py INPUT --retag bt709|bt2020-pq|bt2020-hlg|bt601 [-o OUT]      # metadata only, stream copy
 color.py INPUT --strip-dovi [-o OUT]                                 # drop the Dolby Vision RPU, keep the HLG/HDR10 base layer (stream copy)
-```
+color.py INPUT --correct [--exposure -3..3] [--contrast 0..2] [--saturation 0..2] [--gamma 0.1..10]
+         [--temperature 2000..12000] [--tint -1..1] [--lift -1..1] [--gain -1..1]
+         [--levels-in-black 0..255] [--levels-in-white 0..255] [--levels-out-black 0..255] [--levels-out-white 0..255]
+         [--curves color_negative|cross_process|darker|increase_contrast|lighter|linear_contrast|medium_contrast|negative|strong_contrast|vintage] [-o OUT]
+```
+`--correct` is typed primary colour correction, no filter string ever accepted:
+`--exposure`/`--contrast`/`--saturation`/`--gamma` (`exposure`/`eq` filters),
+`--temperature`/`--tint`/`--lift`/`--gain` (`colortemperature`/`colorbalance`
+filters — `--tint` sets midtones, `--lift` shadows, `--gain` highlights, a
+classic three-way correction), `--levels-*` (`colorlevels`, 8-bit units
+converted to the filter's own 0..1 range, only added to the chain when at
+least one is given) and `--curves` (the `curves` filter's own built-in
+presets, only added when given). Every flag is range-checked against this
+script's own safe subset of what `ffmpeg -h filter=<name>` documents before
+ffmpeg runs. `--json`'s `measurements` reports `analyze_levels()` (signalstats
+luma/saturation) for input and output side by side.
+
 iPhone "HDR" video is Dolby Vision profile 8.4 on an HLG base layer:
 `probe.py` reports `hdr_format: Dolby Vision profile 8` and `--to-sdr`
 tone-maps it from the HLG base layer. When the user wants to keep HDR but

package/scripts/_common.py

@@ -269,6 +269,20 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     return _run_captured(list(cmd), check)
 
 
+def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
+    """Run an ffmpeg command that already maps its video/audio, trying first to also
+    stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
+    there are none). A source whose subtitle codec cannot be copied into the target container
+    (e.g. a container change) makes that first attempt fail; retry the same command without the
+    extra maps rather than let a tool that never touched subtitles start hard-failing because of
+    them. `cmd` is the full argv *without* the output path. Returns True only when the
+    retry-without-subtitles path was actually needed (i.e. subtitle/data streams were dropped)."""
+    if run(cmd + ["-map", "0:s?", "-map", "0:d?", "-c:s", "copy", "-c:d", "copy", output], check=False).returncode == 0:
+        return False
+    run(cmd + [output])
+    return True
+
+
 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)
@@ -325,7 +339,7 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
 
 
 def shell_quote(s: str) -> str:
-    if not s or any(ch in s for ch in " \t\"'\;|&<>()[]{}$*?"):
+    if not s or any(ch in s for ch in " \t\\\"';|&<>()[]{}$*?"):
         return "'" + s.replace("'", "'\\''") + "'"
     return s
 
@@ -387,7 +401,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             return {"file": path, "dry_run": True, "format": None, "duration": 0.0, "size_bytes": 0, "bitrate": None,
                     "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}
+                    "audio": {"codec": None, "channels": 0, "sample_rate": 0}, "subtitle_streams": 0, "data_streams": 0}
         die(f"input not found: {path}")
     ffprobe = require_tool("ffprobe")
     proc = run(
@@ -405,6 +419,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
     video = next((s for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0) == 0), None)
     audio = next((s for s in streams if s.get("codec_type") == "audio"), None)
     subs = [s for s in streams if s.get("codec_type") == "subtitle"]
+    data_stream_count = sum(1 for s in streams if s.get("codec_type") in ("data", "attachment"))
 
     duration = _to_float(fmt.get("duration"))
     if duration is None and video:
@@ -423,6 +438,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
         "video": None,
         "audio": None,
         "subtitle_streams": len(subs),
+        "data_streams": data_stream_count,
         # every subtitle stream in file order: index n here is `-map 0:s:n`
         "subtitle_stream_details": [{
             "index": n,
@@ -582,6 +598,43 @@ def escape_filter_path(path: str) -> str:
     return p
 
 
+def default_font_file(font_name: str) -> Optional[str]:
+    """Resolve `font_name` to a concrete on-disk font file, so a caller can tell drawtext
+    `fontfile=<path>` instead of `font=<name>`, when possible.
+
+    On some real Windows ffmpeg builds (winget's gyan.dev 9.x), drawtext's own fontconfig
+    resolution crashes with an access violation whenever it has to resolve a font by family name
+    -- with or without a valid fonts.conf on FONTCONFIG_FILE. `fontfile=` is the only form
+    confirmed not to crash (#100), since it never touches fontconfig at all. `font_name` itself is
+    ignored on Windows for that reason: a fixed, near-universally-present system font is used
+    instead of trying to resolve the requested family (which would crash the same way).
+
+    On Linux/macOS this is best-effort and uses the real requested family: `fc-match` reports the
+    same file fontconfig would resolve `font_name` to anyway, so a caller gets the identical font,
+    just already resolved to a path -- fontfile= skips a redundant fontconfig lookup and equally
+    sidesteps the same class of crash if it exists on some build there too, but the fallback below
+    (returning None) is exercised routinely there, not just on failure.
+
+    Returns None when nothing could be resolved (fc-match missing/unavailable, or no well-known
+    Windows font file present); the caller falls back to font=<font_name>, the prior behaviour.
+    """
+    if platform.system() == "Windows":
+        windir = os.environ.get("WINDIR", "C:\\Windows")
+        candidate = Path(windir) / "Fonts" / "arial.ttf"
+        return str(candidate) if candidate.exists() else None
+    exe = shutil.which("fc-match")
+    if not exe:
+        return None
+    try:
+        proc = subprocess.run([exe, "--format=%{file}\n", font_name], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=5)
+    except (subprocess.TimeoutExpired, OSError):
+        return None
+    if proc.returncode != 0:
+        return None
+    path = proc.stdout.splitlines()[0].strip() if proc.stdout.strip() else ""
+    return path if path and os.path.exists(path) else None
+
+
 def escape_drawtext(text: str) -> str:
     return (
         text.replace("\\", "\\\\")

package/scripts/_contract.py

@@ -127,7 +127,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   required=FF, optional=[{"capability": X264, "when": "--to-sdr / --lut / --correct"}, {"capability": "filter:zscale", "when": "--to-sdr"}, {"capability": "filter:tonemap", "when": "--to-sdr"},
                                          {"capability": "filter:lut3d", "when": "--lut"}, {"capability": "bsf:filter_units", "when": "--strip-dovi"}, {"capability": X265, "when": "--lut on an HDR source"}, {"capability": AAC, "when": "re-encode"},
                                          {"capability": "filter:exposure", "when": "--correct"}, {"capability": "filter:eq", "when": "--correct"},
-                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"}],
+                                         {"capability": "filter:colorbalance", "when": "--correct"}, {"capability": "filter:colortemperature", "when": "--correct"},
+                                         {"capability": "filter:colorlevels", "when": "--correct with any --levels-*"}, {"capability": "filter:curves", "when": "--correct --curves"}],
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "proxy": dict(role="execution", inputs=["video asset"], outputs=["low-resolution, low-bitrate proxy artifact for downstream analysis, preview or editing decisions"],
                   required=FF + [X264, AAC], optional=[HDR_X265],
@@ -482,6 +483,50 @@ def _default_font() -> str:
     return str(BRAND_DEFAULTS["font"])
 
 
+def _drawtext_probe() -> Dict[str, Any]:
+    """Actually render one frame through drawtext, rather than trusting `-filters` alone.
+
+    `-filters` only reports whether this ffmpeg build was compiled with the filter; it never
+    proves drawtext can actually execute. On some real Windows ffmpeg builds (winget's gyan.dev
+    9.x), drawtext crashes with an access violation whenever it has to resolve a font through
+    fontconfig -- with or without a valid fonts.conf -- so `-filters` correctly reports drawtext
+    present and doctor used to report the capability `available` anyway; every tool that actually
+    used it (look, scenes --sheet, overlay --text, graphics) then crashed on first real use (#100).
+
+    This runs the cheapest real drawtext render there is: a one-frame synthetic clip, no font=
+    given at all (ffmpeg's own default resolution -- the same path that crashed). A clean exit
+    means drawtext genuinely works here. Anything that could not prove either way (no ffmpeg,
+    timeout, an ordinary nonzero exit with a real ffmpeg error) is `unknown`, same "unknown is not
+    missing" principle as every other capability here. A crash specifically -- killed by signal on
+    POSIX, or an unhandled access violation surfacing as a huge unsigned exit code on Windows -- is
+    the one case this function exists to catch, and folds into `missing`: the filter is present in
+    the build but cannot actually be used as ffmpeg's own default would use it.
+    """
+    exe = shutil.which("ffmpeg")
+    if not exe:
+        return {"status": "unknown", "detail": "ffmpeg not on PATH"}
+    try:
+        proc = subprocess.run(
+            [exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "color=c=black:s=64x64:d=1",
+             "-vf", "drawtext=text=x", "-frames:v", "1", "-f", "null", "-"],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=_DETECT_TIMEOUT,
+        )
+    except subprocess.TimeoutExpired:
+        return {"status": "unknown", "detail": f"drawtext probe did not exit within {_DETECT_TIMEOUT}s"}
+    except OSError as e:
+        return {"status": "unknown", "detail": f"drawtext probe: {e}"}
+    if proc.returncode == 0:
+        return {"status": "available", "detail": "one-frame drawtext render succeeded"}
+    if proc.returncode < 0 or proc.returncode >= 0x80000000:
+        return {"status": "missing",
+                "detail": f"drawtext render crashed (exit {proc.returncode}) instead of failing cleanly -- "
+                           "the filter is present in this build but cannot be used as-is, likely a fontconfig "
+                           "resolution crash (see https://github.com/kajisho5/ffmpeg-skill/issues/100); "
+                           "pass an explicit --font-file to every drawtext tool as a workaround"}
+    tail = " ".join(proc.stderr.strip().splitlines()[-2:])
+    return {"status": "unknown", "detail": f"drawtext probe exited {proc.returncode}: {tail}"}
+
+
 def _font_available(font_name: str) -> Dict[str, Any]:
     """Whether `font_name` (a fontconfig family name, as passed to drawtext's `font=`) is actually
     installed, distinct from silently resolving to a substitute.
@@ -561,6 +606,7 @@ def doctor() -> Dict[str, Any]:
     sets = {k: set(v["names"]) for k, v in listings.items()}
     state: Dict[str, str] = {}  # capability -> available | missing | unknown
     wanted = required_capabilities()
+    drawtext_probe: Optional[Dict[str, Any]] = None
 
     def _from(kind: str, name: str) -> str:
         lst = listings[kind]
@@ -577,6 +623,23 @@ def doctor() -> Dict[str, Any]:
             state[cap] = "available" if shutil.which("ffprobe") else "missing"
         elif cap.startswith("encoder:"):
             state[cap] = _from("encoders", cap[8:])
+        elif cap == "filter:drawtext":
+            listing_state = _from("filters", "drawtext")
+            if listing_state == "available":
+                # Only escalate an "available" listing to "missing" on an unambiguous crash --
+                # an ordinary nonzero exit (a real ffmpeg's own -h/-filters-only build variance, or
+                # in tests a fake ffmpeg shim that only implements -filters/-encoders/-bsfs/-version)
+                # proves nothing either way, so it leaves the listing-based result standing rather
+                # than downgrading it; see _drawtext_probe()'s own docstring for why a crash alone
+                # is the one case this exists to catch.
+                probe = _drawtext_probe()
+                if probe["status"] == "missing":
+                    drawtext_probe = probe
+                    state[cap] = "missing"
+                else:
+                    state[cap] = "available"
+            else:
+                state[cap] = listing_state
         elif cap.startswith("filter:"):
             state[cap] = _from("filters", cap[7:])
         elif cap.startswith("bsf:"):
@@ -591,6 +654,8 @@ def doctor() -> Dict[str, Any]:
     unknown = sorted(c for c, st in state.items() if st == "unknown")
     unknown_required = [c for c in unknown if c in wanted["required"]]
     errors = [f"{k}: {v['detail']}" for k, v in listings.items() if v["status"] in ("unparsed", "failed")]
+    if drawtext_probe is not None and drawtext_probe["status"] != "available":
+        errors.append(f"filter:drawtext: {drawtext_probe['detail']}")
     return {
         "version": skill_version(),
         "python": ".".join(str(x) for x in sys.version_info[:3]),
@@ -630,6 +695,12 @@ def _capability_fix_hint(cap: str) -> str:
         full_hint = "install/build ffmpeg with it enabled"
     if cap.startswith("encoder:"):
         return f"this ffmpeg build has no {cap[8:]} encoder; {full_hint}"
+    if cap == "filter:drawtext":
+        return ("drawtext crashed instead of rendering a frame (see errors[] for the exit detail) -- "
+                 "every drawtext tool already resolves a concrete font file automatically when one can "
+                 "be found (#100); if it still crashes, use --no-timecode with look.py or scenes.py "
+                 "--sheet to skip drawtext entirely, or pass --font-file explicitly to overlay.py/"
+                 "graphics.py (the two that accept it) rather than relying on font= resolution")
     if cap.startswith("filter:"):
         return f"this ffmpeg build has no {cap[7:]} filter; {full_hint}"
     if cap.startswith("bsf:"):

package/scripts/caption.py

@@ -427,14 +427,23 @@ def main() -> int:
         if not srt_path or (not os.path.exists(srt_path) and not (STATE.dry_run and args.text)):
             die(f"SRT file not found: {srt_path}")
         codec = mux_subtitle_codec(output)
+        # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
+        # language to build a multi-language set) -- copied byte-identical, distinct from the
+        # newly-added SRT's own codec below.
+        existing_subs = meta.get("subtitle_streams") or 0
         maps = ["-map", "0:v:0"]
         cmd = ffmpeg_base() + ["-i", args.input, "-i", srt_path]
         if meta.get("audio"):
             maps += ["-map", f"0:a:{args.audio_stream}"]
+        if existing_subs:
+            maps += ["-map", "0:s?"]
         maps += ["-map", "1:0"]
-        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else []) + ["-c:s", codec]
+        cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])
+        for i in range(existing_subs):
+            cmd += [f"-c:s:{i}", "copy"]
+        cmd += [f"-c:s:{existing_subs}", codec]
         if args.language:
-            cmd += ["-metadata:s:s:0", f"language={args.language}"]
+            cmd += [f"-metadata:s:s:{existing_subs}", f"language={args.language}"]
         cmd += [output]
         run(cmd)
         result = probe(output, role="output")

package/scripts/color.py

@@ -2,7 +2,8 @@
 """Colour management: convert HDR (HDR10/PQ, HLG, BT.2020) to SDR BT.709 with
 real tone mapping, apply a .cube LUT (Log footage, creative grades), fix wrong
 colour tags without re-encoding, or apply typed primary colour correction
-(exposure, contrast, saturation, white balance).
+(exposure, contrast, saturation, gamma, white balance, three-way
+lift/gain, levels, curves).
 
 Examples:
   python3 color.py iphone_hdr.mov --to-sdr                       # PQ/HLG -> BT.709 SDR, hable tonemap
@@ -13,21 +14,26 @@ Examples:
   python3 color.py iphone_dv.mov --strip-dovi                       # drop Dolby Vision RPU, keep HLG base layer
   python3 color.py iphone_dv.mov --to-sdr                           # DV 8.4 = HLG base layer -> tone-mapped SDR
   python3 color.py flat.mp4 --correct --exposure 0.3 --contrast 1.1 --saturation 1.05 --temperature 5600 --tint -0.05
+  python3 color.py flat.mp4 --correct --gamma 1.2 --lift 0.04 --gain -0.03   # three-way shadows/gamma/highlights
+  python3 color.py flat.mp4 --correct --levels-in-black 16 --levels-in-white 235 --curves medium_contrast
 """
 import argparse
 import os
 import sys
 from typing import List
 
-from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, x264_args
+from _common import add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, info, probe, run, run_keeping_subtitles, x264_args
 
 TONEMAPS = ["hable", "mobius", "reinhard", "bt2390", "clip", "linear", "gamma"]
 
 # Typed primary correction: each flag is one option of one real, always-available libavfilter filter
 # (never a caller-supplied filter string). Range is this script's own safe subset of what the filter
 # documents (`ffmpeg -h filter=<name>`), not the filter's full technical range. default is each filter's
-# own documented no-op value, so every stage below is always emitted and the chain never depends on
-# which flags were actually given.
+# own documented no-op value, so every stage in this dict is always emitted and the chain never depends
+# on which flags were actually given (exposure/temperature/tint/gamma/lift/gain). `colorlevels` and
+# `curves` (see LEVELS and CURVES_PRESETS below) are the exception: they only add a term to the chain
+# when the caller actually asks for them, because "levels 0..255 in, 0..255 out" and "no curve" are
+# already the identity operation without emitting a no-op filter term for it.
 CORRECTION = {
     #      flag           default  lo      hi       unit
     "exposure":    (0.0,   -3.0,    3.0,   "stops"),   # exposure filter's own full range (linear-domain stops)
@@ -35,8 +41,27 @@ CORRECTION = {
     "saturation":  (1.0,    0.0,    2.0,   "x"),       # eq filter; 0=grayscale, 1=unchanged, 2=double saturation
     "temperature": (6500.0, 2000.0, 12000.0, "K"),     # colortemperature filter; 6500=unchanged (its own default)
     "tint":        (0.0,   -1.0,    1.0,   "x"),       # mapped to colorbalance midtones, see correction_chain()
+    "gamma":       (1.0,    0.1,   10.0,   "x"),       # eq filter's own gamma option; 1=unchanged (its own default)
+    "lift":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance shadows (rs=gs=bs); 0=unchanged
+    "gain":        (0.0,   -1.0,    1.0,   "x"),       # colorbalance highlights (rh=gh=bh); 0=unchanged
 }
 
+# colorlevels takes fractional 0.0..1.0 input/output black/white points; this tool exposes the
+# familiar 8-bit 0..255 unit instead and divides by 255.0 when building the filter (same convention
+# as the rest of CORRECTION: a human-friendly CLI unit formatted into the filter's own native unit).
+LEVELS = {
+    #             flag             default  lo   hi
+    "levels_in_black":  (0,     0, 255),
+    "levels_in_white":  (255,   0, 255),
+    "levels_out_black": (0,     0, 255),
+    "levels_out_white": (255,   0, 255),
+}
+
+# curves filter's real built-in presets (`ffmpeg -h filter=curves`), excluding its own "none" (0):
+# omitting --curves already gets that identity result without adding a filter term for it.
+CURVES_PRESETS = ["color_negative", "cross_process", "darker", "increase_contrast", "lighter",
+                   "linear_contrast", "medium_contrast", "negative", "strong_contrast", "vintage"]
+
 
 def _checked(args: argparse.Namespace, flag: str) -> float:
     _, lo, hi, unit = CORRECTION[flag]
@@ -46,26 +71,65 @@ def _checked(args: argparse.Namespace, flag: str) -> float:
     return value
 
 
+def _checked_levels(args: argparse.Namespace, flag: str) -> int:
+    _, lo, hi = LEVELS[flag]
+    value = getattr(args, flag)
+    if not (lo <= value <= hi):
+        die(f"--{flag.replace('_', '-')} {value} is outside {lo}..{hi} (8-bit units, scaled to colorlevels' own 0..1 range)")
+    return value
+
+
 def correction_chain(args: argparse.Namespace) -> str:
-    """Four always-present filter stages, in a fixed order chosen so each stage sees a picture already
-    corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint, so
-    contrast/saturation act on colour-balanced footage) -> contrast -> saturation (the most creative-
-    adjacent stage, applied last). `tint` (-1 green .. +1 magenta) is not a single ffmpeg option: it is
-    expressed as colorbalance's three midtone channels (gm=-tint, rm=bm=tint/2) so a positive tint shifts
-    midtones toward magenta and a negative one toward green without changing overall midtone lightness,
-    the same balanced-axis convention colour tools use for a one-dial tint control."""
+    """Always-present filter stages, in a fixed order chosen so each stage sees a picture already
+    corrected by the previous one: exposure (linear light level) -> white balance (temperature/tint/
+    lift/gain, so contrast/saturation act on colour-balanced footage) -> contrast/saturation/gamma
+    (the most creative-adjacent stage of the always-on chain). `tint` (-1 green .. +1 magenta) is not
+    a single ffmpeg option: it is expressed as colorbalance's three midtone channels (gm=-tint,
+    rm=bm=tint/2) so a positive tint shifts midtones toward magenta and a negative one toward green
+    without changing overall midtone lightness, the same balanced-axis convention colour tools use
+    for a one-dial tint control. `lift` and `gain` extend the same colorbalance call to the shadow
+    (rs=gs=bs=lift) and highlight (rh=gh=bh=gain) channels, giving a classic three-way shadows/
+    midtones/highlights correction in one filter invocation. `gamma` is folded into the same `eq`
+    term contrast/saturation already use, as `eq`'s own `gamma` option. Two further stages are
+    appended only when asked for, since their own identity value would otherwise add a no-op filter
+    term to the chain: `colorlevels` (--levels-*, 8-bit units scaled to the filter's 0..1 range) and
+    `curves` (--curves, one of the filter's own named presets)."""
     exposure = _checked(args, "exposure")
     contrast = _checked(args, "contrast")
     saturation = _checked(args, "saturation")
     temperature = _checked(args, "temperature")
     tint = _checked(args, "tint")
+    gamma = _checked(args, "gamma")
+    lift = _checked(args, "lift")
+    gain = _checked(args, "gain")
+    in_black = _checked_levels(args, "levels_in_black")
+    in_white = _checked_levels(args, "levels_in_white")
+    out_black = _checked_levels(args, "levels_out_black")
+    out_white = _checked_levels(args, "levels_out_white")
+    if in_black >= in_white:
+        die(f"--levels-in-black {in_black} must be less than --levels-in-white {in_white}")
+    if out_black >= out_white:
+        die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
+
     gm, rm, bm = -tint, tint / 2.0, tint / 2.0
-    return ",".join([
+    terms = [
         f"exposure=exposure={exposure:g}",
         f"colortemperature=temperature={temperature:g}",
-        f"colorbalance=rm={rm:g}:gm={gm:g}:bm={bm:g}",
-        f"eq=contrast={contrast:g}:saturation={saturation:g}",
-    ])
+        f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}",
+        f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}",
+    ]
+    if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
+        rimin, rimax = in_black / 255.0, in_white / 255.0
+        romin, romax = out_black / 255.0, out_white / 255.0
+        terms.append(
+            f"colorlevels=rimin={rimin:g}:gimin={rimin:g}:bimin={rimin:g}:"
+            f"rimax={rimax:g}:gimax={rimax:g}:bimax={rimax:g}:"
+            f"romin={romin:g}:gomin={romin:g}:bomin={romin:g}:"
+            f"romax={romax:g}:gomax={romax:g}:bomax={romax:g}"
+        )
+    if args.curves:
+        terms.append(f"curves=preset={args.curves}")
+    return ",".join(terms)
 
 
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
@@ -94,7 +158,7 @@ def main() -> int:
     mode.add_argument("--lut", help=".cube LUT to apply (3D)")
     mode.add_argument("--retag", choices=["bt709", "bt2020-pq", "bt2020-hlg", "bt601"], help="rewrite colour tags only (no re-encode)")
     mode.add_argument("--strip-dovi", action="store_true", help="remove the Dolby Vision RPU (profile 8.4 iPhone clips) so players use the plain HLG/HDR10 base layer; stream copy")
-    mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint")
+    mode.add_argument("--correct", action="store_true", help="typed primary colour correction: --exposure/--contrast/--saturation/--temperature/--tint/--gamma/--lift/--gain/--levels-*/--curves")
     ap.add_argument("--tonemap", choices=TONEMAPS, default="hable", help="tone-mapping curve (default hable)")
     ap.add_argument("--peak", type=float, default=1000.0, help="source peak brightness in nits used for PQ (default 1000)")
     ap.add_argument("--desat", type=float, default=0.0, help="tonemap desaturation strength (default 0)")
@@ -105,6 +169,14 @@ def main() -> int:
     ap.add_argument("--saturation", type=float, default=CORRECTION["saturation"][0], help="--correct: saturation, 0..2, 1=unchanged (default 1)")
     ap.add_argument("--temperature", type=float, default=CORRECTION["temperature"][0], help="--correct: white-balance temperature in Kelvin, 2000..12000, 6500=unchanged (default 6500)")
     ap.add_argument("--tint", type=float, default=CORRECTION["tint"][0], help="--correct: green(-1)/magenta(+1) tint, 0=unchanged (default 0)")
+    ap.add_argument("--gamma", type=float, default=CORRECTION["gamma"][0], help="--correct: master gamma (eq filter's own gamma), 0.1..10, 1=unchanged (default 1)")
+    ap.add_argument("--lift", type=float, default=CORRECTION["lift"][0], help="--correct: shadows lift (colorbalance rs/gs/bs), -1..1, 0=unchanged (default 0)")
+    ap.add_argument("--gain", type=float, default=CORRECTION["gain"][0], help="--correct: highlights gain (colorbalance rh/gh/bh), -1..1, 0=unchanged (default 0)")
+    ap.add_argument("--levels-in-black", type=int, default=LEVELS["levels_in_black"][0], help="--correct: colorlevels input black point, 0..255 (default 0, unchanged)")
+    ap.add_argument("--levels-in-white", type=int, default=LEVELS["levels_in_white"][0], help="--correct: colorlevels input white point, 0..255 (default 255, unchanged)")
+    ap.add_argument("--levels-out-black", type=int, default=LEVELS["levels_out_black"][0], help="--correct: colorlevels output black point, 0..255 (default 0, unchanged)")
+    ap.add_argument("--levels-out-white", type=int, default=LEVELS["levels_out_white"][0], help="--correct: colorlevels output white point, 0..255 (default 255, unchanged)")
+    ap.add_argument("--curves", choices=CURVES_PRESETS, default=None, help="--correct: curves filter built-in preset (default: none, no curves term added)")
     ap.add_argument("--audio-stream", type=int, default=0,
                      help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
                           "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
@@ -212,16 +284,16 @@ def main() -> int:
         tag = "lut"
 
     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)
+    cmd += x264_args(args.crf, args.preset) + cfr_args(meta) + (aac_args() if has_audio else [])
+    dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {r['video']['width']}x{r['video']['height']}, "
          f"{r['video']['color_transfer']}/{r['video']['color_primaries']}, {tag})")
+    extra = {"dropped_non_av_streams": dropped_streams}
     if measurements is not None:
         measurements["output"] = analyze_levels(output)
-        emit(output, measurements=measurements)
-    else:
-        emit(output)
+        extra["measurements"] = measurements
+    emit(output, **extra)
     return 0
 
 

package/scripts/fit.py

@@ -37,7 +37,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, x264_args
 
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
@@ -225,15 +225,24 @@ def main() -> int:
         cmd += aac_args()
     else:
         cmd += ["-an"]
-    cmd += post + [output]
-    run(cmd)
+    cmd += post
+    if abs(factor - 1.0) > 1e-4:
+        # A subtitle/data stream stream-copied by run_keeping_subtitles keeps the source's
+        # original timestamps; --method speed retimes video (setpts) and audio (atempo) but has
+        # no equivalent way to retime a copied subtitle track, so it would desync from the
+        # now-faster/slower picture. Drop them here rather than ship a captions track that lies
+        # about when a line is spoken.
+        run(cmd + [output])
+        dropped_streams = bool(meta.get("subtitle_streams") or meta.get("data_streams"))
+    else:
+        dropped_streams = run_keeping_subtitles(cmd, 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"
     info(msg)
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/graphics.py

@@ -21,7 +21,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, video_args
+from _common import aac_args, add_common, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -33,6 +33,9 @@ def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
 def font_opts(brand: dict, font: Optional[str], font_file: Optional[str]) -> str:
     if font_file or brand.get("font_file"):
         return f"fontfile={escape_filter_path(font_file or brand['font_file'])}"
+    resolved = default_font_file(font or brand.get("font", "DejaVu Sans"))
+    if resolved:
+        return f"fontfile={escape_filter_path(resolved)}"
     return f"font='{font or brand.get('font', 'DejaVu Sans')}'"
 
 
@@ -163,11 +166,10 @@ def main() -> int:
         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)
+    dropped_streams = run_keeping_subtitles(cmd, output)
     r = probe(output, role="output")
     info(f"wrote {output} ({r['duration']:.3f}s, {args.template})")
-    emit(output, template=args.template)
+    emit(output, template=args.template, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/look.py

@@ -15,7 +15,7 @@ import sys
 from pathlib import Path
 from typing import List
 
-from _common import add_common, apply_common, die, emit, escape_drawtext, ffmpeg_base, info, parse_time, probe, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
 
@@ -26,8 +26,8 @@ def fmt_hms(sec: float) -> str:
     return f"{int(h):02d}:{int(m):02d}:{s_:06.3f}"
 
 
-def timecode_filter() -> str:
-    return f"drawtext=text='%{{pts\\:hms}}':{FONT}"
+def timecode_filter(font_prefix: str) -> str:
+    return f"drawtext=text='%{{pts\\:hms}}':{font_prefix}{FONT}"
 
 
 def main() -> int:
@@ -49,7 +49,12 @@ def main() -> int:
     dur = meta.get("duration") or 0.0
     stem = Path(args.input).stem
     outdir = str(Path(args.output).parent) if args.output else str(Path(args.input).parent)
-    tc = "" if args.no_timecode else "," + timecode_filter()
+    # a resolvable font file, given as fontfile=, is the only form confirmed not to crash drawtext's
+    # own fontconfig resolution on some real Windows ffmpeg builds (#100); font= is the fallback when
+    # nothing can be resolved, unchanged from before this existed.
+    default_font = default_font_file("DejaVu Sans")
+    font_prefix = f"fontfile={escape_filter_path(default_font)}:" if default_font else ""
+    tc = "" if args.no_timecode else "," + timecode_filter(font_prefix)
     # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
     if meta["video"].get("hdr"):
         v = meta["video"]
@@ -67,8 +72,8 @@ def main() -> int:
             sec = parse_time(t)
             out = args.output or os.path.join(outdir, f"{stem}_vs_{Path(args.compare).stem}_{sec:.3f}s.png")
             half = args.width // 2
-            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
-            tcs = tc.replace("," + timecode_filter(), "") + stamp
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
+            tcs = tc.replace("," + timecode_filter(font_prefix), "") + stamp
             fc = (f"[0:v]scale={half}:-2{tcs}[a];[1:v]scale={half}:-2{tcs}[b];"
                   f"[a][b]scale2ref=w=iw:h=ih[a2][b2];[a2][b2]hstack=inputs=2[out]")
             cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-ss", f"{sec:.3f}", "-i", args.compare,
@@ -81,8 +86,8 @@ def main() -> int:
             if dur and sec > dur:
                 die(f"--at {t} is beyond the duration ({dur:.2f}s)")
             out = os.path.join(outdir, f"{args.output and Path(args.output).stem or stem}_{sec:.3f}s.png")
-            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{FONT}"
-            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(), '')}{stamp}", "-frames:v", "1", out]
+            stamp = "" if args.no_timecode else f",drawtext=text='{escape_drawtext(fmt_hms(sec))}':{font_prefix}{FONT}"
+            cmd = ffmpeg_base() + ["-ss", f"{sec:.3f}", "-i", args.input, "-vf", f"scale={args.width}:-2{tc.replace(',' + timecode_filter(font_prefix), '')}{stamp}", "-frames:v", "1", out]
             run(cmd)
             outputs.append(out)
     else:

package/scripts/overlay.py

@@ -24,7 +24,7 @@ import argparse
 import sys
 from typing import List, Optional
 
-from _common import STATE, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, x264_args
+from _common import STATE, load_brand, video_args, add_common, apply_common, default_font_file, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, x264_args
 
 POS = {
     "top-left": ("{m}", "{m}"),
@@ -144,6 +144,8 @@ def main() -> int:
             args.font = brand.get("font", args.font)
         if not args.font_file and brand.get("font_file"):
             args.font_file = brand["font_file"]
+    if not args.font_file:
+        args.font_file = default_font_file(args.font)
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
@@ -193,12 +195,19 @@ def main() -> int:
         # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
         cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
         fc = f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS[ov];[0:v][ov]{ov}[out]"
-        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?", "-shortest"]
-        # -shortest alone is not exact on FFmpeg 7+: the muxer keeps up to shortest_buf_duration (10 s)
-        # of the looped still after the video ended, and the file came out 2 s long on 8.1 / 9.0.
-        # The output must be as long as the main input, so say so explicitly.
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
+            # An explicit -t is exact and, unlike -shortest, only bounds the *main* input's
+            # streams -- a preserved subtitle/data stream that ends earlier (run_keeping_subtitles)
+            # must not be allowed to cut the whole output short via -shortest's "stop at whichever
+            # mapped stream finishes first" semantics.
             cmd += ["-t", f"{meta['duration']:.3f}"]
+        else:
+            # No known duration to bound by -t (e.g. probe found no video duration): -shortest is
+            # the only thing stopping the looped still from running forever. FFmpeg 7+'s
+            # shortest_buf_duration slack (up to 10s) is an accepted imprecision here since there is
+            # no better bound available.
+            cmd += ["-shortest"]
     elif args.video:
         pip_meta = probe(args.video)
         if not pip_meta.get("video"):
@@ -219,9 +228,13 @@ def main() -> int:
             ov += f":enable='{enable}'"
         cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
         fc = f"[1:v]{','.join(chain)}[ov];[0:v][ov]{ov}[out]"
-        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?", "-shortest"]
+        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
         if meta.get("duration"):
+            # See the --image branch above: -t (exact, bounds only the main input) instead of
+            # -shortest (would also stop at a preserved subtitle/data stream that ends earlier).
             cmd += ["-t", f"{meta['duration']:.3f}"]
+        else:
+            cmd += ["-shortest"]
     else:
         x, y = position_exprs(args.position, args.margin, text_mode=True)
         opts = [f"text='{escape_drawtext(args.text)}'", f"fontsize={args.font_size}", f"x={x}", f"y={y}",
@@ -245,12 +258,11 @@ def main() -> int:
 
     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)
+    dropped_streams = run_keeping_subtitles(cmd, output)
     if not STATE.dry_run:
         result = probe(output, role="output")
         info(f"wrote {output} ({result['duration']:.3f}s)")
-    emit(output)
+    emit(output, dropped_non_av_streams=dropped_streams)
     return 0
 
 

package/scripts/scenes.py

@@ -26,7 +26,7 @@ import subprocess
 import sys
 from typing import Dict, List, Tuple
 
-from _common import add_common, apply_common, die, emit, ffmpeg_base, info, print_json, probe, require_tool, run
+from _common import add_common, apply_common, default_font_file, die, emit, escape_filter_path, ffmpeg_base, info, print_json, probe, require_tool, run
 
 SCORE_RE = re.compile(r"frame:(\d+)\s+pts:\d+\s+pts_time:([0-9.]+)")
 
@@ -107,6 +107,7 @@ def main() -> int:
     ap.add_argument("--max-scene", type=float, default=15.0, help="cap a highlight range at this many seconds (default 15)")
     ap.add_argument("--edl", help="write highlight ranges as START-END lines (cut.py --segments format)")
     ap.add_argument("--sheet", help="write a contact sheet PNG with the first frame of every scene")
+    ap.add_argument("--no-timecode", action="store_true", help="--sheet without the burnt-in timecode stamp (a way out if drawtext itself is unusable, see doctor)")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -183,7 +184,12 @@ def main() -> int:
         # exactly one frame per scene: the frame index at the scene start
         fps = meta["video"].get("fps") or 30.0
         expr = "+".join(f"eq(n\\,{int(round(sc['start'] * fps))})" for sc in scenes)
-        vf = (f"select='{expr}',scale={tile_w}:-2,drawtext=text='%{{pts\\:hms}}':fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6,"
+        stamp = ""
+        if not args.no_timecode:
+            default_font = default_font_file("DejaVu Sans")
+            font_prefix = f"fontfile={escape_filter_path(default_font)}:" if default_font else ""
+            stamp = f",drawtext=text='%{{pts\\:hms}}':{font_prefix}fontcolor=white:fontsize=h/14:box=1:boxcolor=black@0.55:boxborderw=4:x=6:y=6"
+        vf = (f"select='{expr}',scale={tile_w}:-2{stamp},"
               f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
         run(ffmpeg_base() + ["-i", args.input, "-vf", vf, "-frames:v", "1", "-fps_mode", "vfr", args.sheet])
         info(f"wrote {args.sheet}")

package/scripts/stabilize.py

@@ -9,12 +9,18 @@ this run only -- it is not a caller-facing artifact.
 --shakiness (1 = barely shaky, fast; 10 = very shaky, slow analysis) and
 --smoothing (how many neighbouring frames to average the camera path over)
 are the two knobs that matter most; --zoom crops in slightly to hide the
-black edges stabilizing can introduce (0 = keep the original framing and let
-edges show; ffmpeg's own --crop-mode is not exposed as a raw flag here).
+edges stabilizing can introduce (0 = keep the original framing and let edges
+show). --crop chooses what happens to any edge vidstab reveals that --zoom
+doesn't crop away: "keep" (default) stretches the border pixels, "black"
+fills it in solid black instead. --tripod locks the frame fully still
+against a single reference frame (e.g. a camera meant to be static but
+nudged, or a shot you want dead-locked rather than merely smoothed) instead
+of following the camera's intended motion.
 
 Examples:
   python3 stabilize.py shaky.mp4
   python3 stabilize.py shaky.mp4 --shakiness 8 --smoothing 20 --zoom 5
+  python3 stabilize.py locked-off.mp4 --tripod --crop black
 """
 import argparse
 import sys
@@ -31,6 +37,8 @@ def main() -> int:
     ap.add_argument("--shakiness", type=int, default=5, help="1 (barely shaky) .. 10 (very shaky), default 5")
     ap.add_argument("--smoothing", type=int, default=15, help="frames of camera-path smoothing on each side, default 15")
     ap.add_argument("--zoom", type=float, default=0.0, help="percent to zoom in to hide stabilization edges, 0..100 (default 0)")
+    ap.add_argument("--crop", choices=["keep", "black"], default="keep", help="edges --zoom doesn't crop away: keep (stretch border pixels, default) or black (fill solid black)")
+    ap.add_argument("--tripod", action="store_true", help="lock the frame fully still against a single reference frame instead of smoothing the camera's motion")
     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)
@@ -56,13 +64,23 @@ def main() -> int:
 
         if not STATE["dry_run"]:
             ffmpeg = require_tool("ffmpeg")
+            detect_vf = f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}"
+            if args.tripod:
+                # A frame number, not a boolean: frame 1 is the standard reference for "lock to
+                # this fixed frame" (mirrors vidstabtransform's own tripod=1 below).
+                detect_vf += ":tripod=1"
             detect_cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", args.input,
-                          "-vf", f"vidstabdetect=shakiness={args.shakiness}:result={trf_arg}", "-f", "null", "-"]
+                          "-vf", detect_vf, "-f", "null", "-"]
             proc = run(detect_cmd, check=False)
             if proc.returncode != 0:
                 die(f"stabilization analysis (pass 1) failed:\n{proc.stderr.strip()[-1500:]}")
 
-        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:zoom={args.zoom:g}:optzoom=1"
+        crop_mode = {"keep": 0, "black": 1}[args.crop]
+        transform_vf = f"vidstabtransform=input={trf_arg}:smoothing={args.smoothing}:crop={crop_mode}:zoom={args.zoom:g}:optzoom=1"
+        if args.tripod:
+            # Equivalent to relative=0:smoothing=0 -- overrides --smoothing, since averaging a
+            # camera path makes no sense once every frame is locked to one fixed reference.
+            transform_vf += ":tripod=1"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", transform_vf]
         cmd += video_args(meta, args.crf, args.preset)
         cmd += cfr_args(meta)