ffmpeg-skill 1.1.0 → 1.2.0

package/README.md

@@ -312,12 +312,13 @@ npx ffmpeg-skill doctor --json   # available / missing / missing_optional / unkn
 
 ## FFmpeg compatibility
 
-The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 6.1 (Ubuntu), 8.x (macOS) and 9.x (Windows), all on Python 3.9, plus Ubuntu on Python 3.13 (the two ends of the supported range); 5.x and 7.x are expected to work from the filter/encoder names used but are not run ([#146](https://github.com/kajisho5/ffmpeg-skill/issues/146) tracks widening the matrix). The capability parser has been run against the listings of these builds:
+The tools need FFmpeg 5.0 or later and Python 3.9 or later (standard library only). What CI actually exercises on every pull request is FFmpeg 5.1.1 (static build), 6.1 (Ubuntu apt), 7.1 (Debian trixie apt), 8.x (macOS Homebrew) and 9.x (Windows gyan.dev), on Python 3.9 and 3.13 (the two ends of the supported range). The capability parser has been run against the listings of these builds:
 
 | FFmpeg | `-filters` row layout | Source |
 |---|---|---|
+| 5.1.1 | three flag characters, same as 6.x | johnvansickle.com static build on the Linux CI runner |
 | 6.1.1 | three flag characters: `..C acompressor A->A` | Ubuntu 24.04 apt, captured |
-| 7.x | same as 6.x | constructed fixture (no capture at hand) |
+| 7.1.x | same as 6.x | Debian trixie apt in a CI container (plus a constructed fixture in tests/) |
 | 8.1.2 | two flag characters: `TS aap AA->A`, three-character legend, `------` separator | Homebrew on the macOS CI runner, captured |
 | 9.0.1 | same as 8.x, CRLF | gyan.dev build on the Windows CI runner, captured |
 
@@ -403,7 +404,7 @@ python3 evals/run.py --list   # agent eval prompts (see evals/)
 node bin/install.js --dir /tmp/skills   # try the installer without touching ~/.claude
 ```
 
-CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), and uploads each runner's FFmpeg listings as an artifact.
+CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `main`, on Ubuntu (FFmpeg 6.1, Python 3.9 and 3.13), macOS (Homebrew FFmpeg 8.x) and Windows (gyan.dev FFmpeg 9.x), plus two Linux jobs on FFmpeg 5.1.1 (static build) and 7.1 (Debian trixie container), and uploads each runner's FFmpeg listings as an artifact.
 
 `tests/test_contract.py` runs on all three OSes, but a handful of its tests build a fake `ffmpeg` as a `#!/bin/sh` script on a PATH shim to force specific FFmpeg 6/7/8/9 fixture layouts through `doctor`'s parser — that technique isn't portable to Windows, so `test_dry_run_never_runs_ffmpeg_and_writes_nothing` and the whole `DoctorDetectionTests` class (fixture-driven layout parsing) are individually `skipIf`'d there and show as `skipped`, not silently absent, in the Windows job's log. Everything else — contract schema, `reencodes_*`, `doctor.tools`, MCP derivation, and every tool exercised through the contract, including `cut.py`'s provenance fields — runs against the real Windows `ffmpeg` on every PR. See [references/ci-platform-pitfalls.md](references/ci-platform-pitfalls.md) for this and other per-OS behaviour differences already diagnosed, before spending a CI cycle re-diagnosing a platform-only failure.
 

package/SKILL.md

@@ -128,7 +128,7 @@ If a request needs an FFmpeg feature none of the 40 scripts expose, say so and n
 | "cut from 1:20 to 2:05", "trim the first 10 seconds" | `cut.py input.mp4 --start 1:20 --end 2:05` |
 | "keep only these parts", "remove the middle" | `cut.py input.mp4 --segments 0-1:00,1:30-2:00` |
 | "make it exactly 60 seconds", "fit it in 30s" | `fit.py input.mp4 --duration 60` (speed) or `--method trim` |
-| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) |
+| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`); add `--pad-fill blur` for the blurred-background bars phone editors produce |
 | "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) |
 | "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |
 | "are there black bars on this?", "what's the crop rectangle to remove the letterboxing" | `cropdetect.py input.mp4` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 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/ci-platform-pitfalls.md

@@ -109,3 +109,59 @@ When a test needs to special-case a platform, prefer gating with
 mechanism, and write the skip/relaxation reason as a full sentence
 explaining the underlying platform behaviour — not just "flaky on
 Windows" — so a future reader doesn't have to re-derive it from the CI log.
+
+## FFmpeg 5.x (the 5.1.1 static-build CI job)
+
+Found the day the job was added (#146); 6.1+ behaves the same on all three OSes, so none of
+these had ever shown up before.
+
+- **`scdet=...:sc_pass=1` passes only frames whose score exceeds the threshold.** On 5.x every
+  truly static frame (score exactly 0: a title card, colour bars) is dropped before the next
+  filter and the frame numbers are re-counted without them. `scenes.py` used it with
+  `threshold=0` expecting every frame through, so a 4 s smptebars scene made the cuts on both
+  sides of it disappear from its neighbourhood test. 6.1+ passes every frame regardless.
+  Dropped the option; scores are also indexed by frame number now, missing frames counting as 0.
+- **`drawtext` `boxborderw=v|h` (and the four-value form) is 6.1+.** 5.x and 6.0 fail the whole
+  filter with "Error setting option boxborderw to value 9|16". `_common.drawtext_boxborderw()`
+  emits the larger single value on older builds (`_common.ffmpeg_version()` parses
+  `ffmpeg -version` once; it is the only place the tools branch on a version string).
+- **`showwaves` keeps emitting frames after the audio ends, `-shortest` notwithstanding.** A
+  12 s source came out 14.08 s on 5.1.1. `waveform.py` now also passes `-t <source duration>`.
+- **`-display_rotation` is 6.0+.** Only the test fixture builder used it (to make a rotated
+  phone-style clip); on 5.x it writes the stream's `rotate` tag instead, which every probe here
+  reads identically.
+- **John Van Sickle's 7.0.2 static build has no `drawtext`** (built with freetype, yet the
+  filter is absent), and BtbN no longer publishes 7.x; the 7.1 job therefore runs in a Debian
+  trixie container (apt ffmpeg 7.1.5 with libass, freetype and zimg).
+
+## FFmpeg 7.1+ (the debian-trixie container CI job)
+
+- **Output `-colorspace bt709` is no longer just a tag: on an untagged source it converts.**
+  7.1 added colourspace negotiation to libavfilter, and the CLI feeds the encoder's
+  `-colorspace/-color_primaries/-color_trc` into the graph's output constraints. A source
+  whose bitstream carries no colour tags (`color_space=unknown` -- test sources, screen
+  recordings, many cameras) then *differs* from the requested BT.709, so ffmpeg auto-inserts
+  a real matrix conversion (swscale guesses bt601 for "unknown"): every SDR re-encode through
+  `x264_args()` shifted the picture, and a `--lut-strength 0` no-op grade came back ~24 dB
+  PSNR from its source. 5.x/6.x wrote the same options as tags only (47 dB, no conversion).
+  The 7.0.2 static build does *not* show it; 7.1.1 (conda-forge) reproduces it locally, so
+  that is the build to use when the trixie job goes red on a colour test.
+  Fix: `_common.bt709_tag_args()` writes the tags through the encoder's own VUI parameters
+  (`-x264-params colorprim=...:transfer=...:colormatrix=...`, x265 likewise) from 7.1 on,
+  which libavfilter never sees; older builds keep the output options, since those were the
+  only way to get an mp4 `colr` atom there. A decoder-side `-colorspace bt709 ... -i` override
+  was tried first and rejected: it also tags a `-c copy` output of an untagged source (export
+  copy must stay a real copy), and it exposed a separate, pre-existing `--correct` bug (below).
+  Verified on 5.1.1, 6.1.1, 7.1.1 and 8.1.2. 8.x has the same encode-time conversion; it
+  went unnoticed there because 8.x's `psnr` filter *also* negotiates colourspace and undid it
+  before measuring (40 dB for re-matrixed pixels), and it then flagged the fixed, byte-clean
+  output as 26 dB instead. The tests' `_psnr` helper now pins identical colour tags on both
+  inputs so every build reports the same number for the same two files.
+- **The conda-forge 7.1.1 build deadlocks on `tpad` + `adelay`/`apad` (pad.py) and ignores
+  SIGTERM.** Debian's 7.1.5 in CI does not. Run pad tests against CI, not that build, and note
+  that the tools have no subprocess timeout to get an agent out of such a hang.
+- **Not a 7.1 issue, found while chasing it: `color --correct` desaturates a bt709-*tagged*
+  source by ~8 % at identity settings on 6.1 and 7.1 alike** (113.6 → 103.9 saturation_avg):
+  the RGB stages (exposure/colortemperature/colorbalance) make swscale go yuv→rgb with the
+  frame's bt709 matrix and back with its bt601 default. The identity test only ever used an
+  untagged source, where both legs pick bt601 and cancel out. Tracked separately.

package/references/scripts.md

@@ -58,7 +58,7 @@ the result was "lossless stream copy" or "re-encoded".
 ### 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] [--height H] [--pad-color black]]
+             [--aspect 16:9|9:16|1:1|4:5|W:H --fit pad|crop [--width W] [--height H] [--pad-color black] [--pad-fill color|blur [--pad-blur 20]]]
              [--rotate 90|180|270] [--flip h|v] [--fps N] [-o OUT]
 ```
 `speed` retimes video and audio together (pitch-preserving `atempo`); it
@@ -73,6 +73,10 @@ 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.
+`--pad-fill blur` fills the letterbox/pillarbox bars with a blurred, scaled-to-cover copy
+of the frame (the look every phone editor gives landscape footage posted as a Short/Reel)
+instead of the solid `--pad-color`; `--pad-blur` is the blur radius. `export.py --fit pad`
+takes the same two flags.
 
 ### crop.py — crop to an exact pixel rectangle
 ```

package/scripts/_common.py

@@ -9,13 +9,14 @@ from __future__ import annotations
 import json
 import os
 import platform
+import argparse
 import re
 import shutil
 import subprocess
 import sys
 from fractions import Fraction
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence, Tuple
 
 # Every script prints paths, help text and reports that may contain non-ASCII (Japanese examples,
 # arrows). On Windows the console streams default to a legacy code page and raise
@@ -74,6 +75,63 @@ ERROR_CODE = {
 ERROR_RETRYABLE = False
 
 
+_FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
+
+
+def ffmpeg_version() -> "Tuple[int, int]":
+    """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
+    when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
+    ffmpeg (docs/contract.md: ffmpeg_execution "none") while ffprobe always may, and the two
+    ship from the same build. Used only to pick between two spellings of an option where FFmpeg
+    changed behaviour between releases (the tools otherwise never branch on the version: doctor's
+    capability listing is the source of truth for what a build can do)."""
+    global _FFMPEG_VERSION
+    if _FFMPEG_VERSION is None:
+        _FFMPEG_VERSION = (0, 0)
+        try:
+            out = subprocess.run(["ffprobe", "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True).stdout
+            m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
+            if m:
+                _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
+        except OSError:
+            pass
+    return _FFMPEG_VERSION
+
+
+def drawtext_boxborderw(vertical: int, horizontal: int) -> str:
+    """drawtext's per-side `boxborderw=top|right|bottom|left` (and the two-value `v|h` form)
+    arrived in FFmpeg 6.1; 5.x and 6.0 reject the `|` with "Error setting option boxborderw"
+    (found by the FFmpeg 5.1.1 CI job, #146). Older builds get the larger single value."""
+    if ffmpeg_version() >= (6, 1):
+        return f"{vertical}|{horizontal}"
+    return str(max(vertical, horizontal))
+
+
+def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int) -> str:
+    """The letterbox/pillarbox step shared by fit.py and export.py, as one -vf segment.
+
+    fill="color": scale to fit, then pad with a solid colour (the historical behaviour).
+    fill="blur": the bars are a blurred, scaled-to-cover copy of the same frame -- what every
+    phone editor's "make it vertical" does with landscape footage (#139). Built as a small
+    graph inside the -vf chain: split, one branch scaled to cover and cropped to the frame
+    then boxblur'ed, the other scaled to fit, overlaid centred. Only `filter:boxblur` is
+    needed beyond the usual scale/pad set, and that is already required by redact.py."""
+    if fill == "blur":
+        radius = max(1, int(blur))
+        return (f"split[__fitfg][__fitbg];"
+                f"[__fitbg]scale={out_w}:{out_h}:force_original_aspect_ratio=increase,crop={out_w}:{out_h},"
+                f"boxblur={radius}:2[__fitbgb];"
+                f"[__fitfg]scale={out_w}:{out_h}:force_original_aspect_ratio=decrease[__fitfgs];"
+                f"[__fitbgb][__fitfgs]overlay=(W-w)/2:(H-h)/2:format=auto")
+    return f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease,pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={color}"
+
+
+def add_pad_fill_args(parser: "argparse.ArgumentParser") -> None:
+    parser.add_argument("--pad-fill", choices=["color", "blur"], default="color",
+                        help="what fills the letterbox/pillarbox bars under --fit pad: a solid --pad-color (default) or a blurred, scaled-up copy of the frame")
+    parser.add_argument("--pad-blur", type=int, default=20, help="blur radius in pixels for --pad-fill blur (default 20)")
+
+
 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."""
@@ -698,10 +756,30 @@ def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Lis
     return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
 
 
+def bt709_tag_args(encoder: str = "libx264") -> List[str]:
+    """Tag an SDR output as BT.709 without touching its pixels.
+
+    Up to FFmpeg 7.0 the output options -colorspace/-color_primaries/-color_trc were tags only.
+    7.1 added colourspace negotiation to libavfilter and feeds those options into the graph's
+    output constraints, so on a source whose bitstream carries no colour tags (test sources,
+    screen recordings, many cameras) the CLI now auto-inserts a *real* matrix conversion (its
+    guess for "unknown" is bt601) into every SDR re-encode: a --lut-strength 0 no-op grade
+    came back ~24 dB PSNR from its source on 7.1. From 7.1 on, the tags therefore go through
+    the encoder's own VUI parameters instead, which libavfilter never sees; a source that is
+    genuinely tagged bt601/bt2020 is left alone either way (it keeps its own tags on the old
+    path, and the encoder VUI is a label, not a conversion, on the new one).
+    """
+    if ffmpeg_version() < (7, 1):
+        return ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+    if encoder == "libx265":
+        return ["-x265-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
+    return ["-x264-params", "colorprim=bt709:transfer=bt709:colormatrix=bt709"]
+
+
 def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) -> List[str]:
     args = ["-c:v", "libx264", "-preset", preset, "-crf", str(crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
     if keep_bt709:
-        args += ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
+        args += bt709_tag_args("libx264")
     return args
 
 

package/scripts/_contract.py

@@ -74,7 +74,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                 required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
-                required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"}],
+                required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},
+                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
                  required=FF + [X264, AAC], optional=[HDR_X265],
@@ -174,7 +175,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
                                           {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
-                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}],
+                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],

package/scripts/export.py

@@ -26,8 +26,7 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color
-
+from _common import STATE, add_common, apply_common, bt709_tag_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, validate_color, pad_filters, add_pad_fill_args
 PRESETS: Dict[str, Dict] = {
     "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
     "youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},
@@ -39,7 +38,6 @@ PRESETS: Dict[str, Dict] = {
     "copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},
 }
 
-BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]
 
 
 def main() -> int:
@@ -49,6 +47,7 @@ def main() -> int:
     ap.add_argument("--preset", choices=sorted(PRESETS), help="delivery preset")
     ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how to reach the preset frame when aspect differs (default pad)")
     ap.add_argument("--pad-color", default="black")
+    add_pad_fill_args(ap)
     ap.add_argument("--no-scale", action="store_true", help="keep source resolution even for platform presets")
     ap.add_argument("--allow-long", action="store_true", help="do not trim to the platform's max duration")
     ap.add_argument("--crf", type=int, help="override CRF")
@@ -81,7 +80,7 @@ def main() -> int:
             if args.fit == "crop":
                 vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=increase", f"crop={p['w']}:{p['h']}"]
             else:
-                vf += [f"scale={p['w']}:{p['h']}:force_original_aspect_ratio=decrease", f"pad={p['w']}:{p['h']}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}"]
+                vf.append(pad_filters(p["w"], p["h"], args.pad_fill, args.pad_color, args.pad_blur))
             vf.append("setsar=1")
         else:
             vf.append(f"scale={p['w']}:-2")
@@ -110,7 +109,7 @@ def main() -> int:
         if "-r" not in video:
             cmd += cfr_args(meta)
         if args.preset not in ("prores",):
-            cmd += BT709
+            cmd += bt709_tag_args(video[video.index("-c:v") + 1])
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]
     cmd += (p["audio"] if has_audio else ["-an"])

package/scripts/fit.py

@@ -4,7 +4,7 @@
 Duration: --duration N with --method speed (retime video+audio, pitch-preserving
 via atempo chaining) or --method trim (keep the first N seconds, or a centred
 window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
---fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.
+--fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture) or --fit crop.
 --width and/or --height set the output size: give one and the other follows
 the aspect (source aspect if --aspect is not also given); give both for an
 exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
@@ -24,6 +24,7 @@ Examples:
   python3 fit.py input.mp4 --duration 60                    # speed up/down to exactly 60s
   python3 fit.py input.mp4 --duration 30 --method trim
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
+  python3 fit.py input.mp4 --aspect 9:16 --fit pad --pad-fill blur   # the phone-editor look: blurred frame behind the bars
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
   python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
   python3 fit.py input.mp4 --height 1080                         # width follows the source aspect
@@ -37,8 +38,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, run_keeping_subtitles, validate_color, 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, validate_color, x264_args, pad_filters, add_pad_fill_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)}
 
 
@@ -93,6 +93,7 @@ def main() -> int:
     a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
     a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
+    add_pad_fill_args(a)
     a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")
     a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")
     r = ap.add_argument_group("rotate / flip")
@@ -115,6 +116,8 @@ def main() -> int:
     if not 0.0 <= args.crop_y <= 1.0:
         die(f"--crop-y must be 0..1, got {args.crop_y}")
     validate_color(args.pad_color, "--pad-color")
+    if args.pad_blur <= 0:
+        die(f"--pad-blur must be > 0, got {args.pad_blur}")
 
     meta = probe(args.input)
     if not meta.get("video"):
@@ -212,8 +215,7 @@ def main() -> int:
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
             vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
         else:
-            vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")
-            vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")
+            vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur))
         vf.append("setsar=1")
 
     if args.fps:

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_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
+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, drawtext_boxborderw
 
 TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
 
@@ -139,7 +139,7 @@ def main() -> int:
         ye = f"{margin}" if "top" in pos else f"h-text_h-{margin}"
         box_color = ff_color(primary if args.template == "chapter" else bg, 0.9 if args.template == "chapter" else 0.7)
         txt_color = ff_color(bg if args.template == "chapter" else text_c)
-        filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={pady}|{padx}:alpha='{fade_a}':{en}")
+        filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={drawtext_boxborderw(pady, padx)}:alpha='{fade_a}':{en}")
 
     elif args.template == "progress":
         h = max(3, int(base * 0.008))

package/scripts/scenes.py

@@ -39,25 +39,35 @@ def detect_scenes(path: str, threshold: float, min_len: float, duration: float,
     equal recall compared with the raw scdet threshold."""
     ffmpeg = require_tool("ffmpeg")
     proc = subprocess.run([ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-an", "-vf",
-                           "scale=320:-2,scdet=threshold=0:sc_pass=1,metadata=print:file=-", "-f", "null", "-"],
+                           "scale=320:-2,scdet=threshold=0,metadata=print:file=-", "-f", "null", "-"],
                           stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
-    times: List[float] = []
-    scores: List[float] = []
-    cur_t = None
+    # No `sc_pass=1` on scdet: on FFmpeg 5.x that option means "pass only the frames whose
+    # score exceeds the threshold", so every truly static frame (score exactly 0 -- a title
+    # card, colour bars) is dropped before metadata=print and the frame numbers are re-counted
+    # without them. The +-12-frame neighbourhood around a real cut then fills with the moving
+    # segment's scores instead of the still one's zeros, the cut fails the ratio test, and a
+    # 4 s smptebars scene made the cuts on both sides of it disappear (found by the 5.1.1 CI
+    # job, #146). 6.1+ passes every frame either way. Scores are still indexed by frame number
+    # and any frame the filter did not report counts as 0, so a build that drops frames again
+    # cannot shift the neighbourhood.
+    by_frame: Dict[int, Tuple[float, float]] = {}
+    cur = None
     for line in proc.stdout.splitlines():
         m = SCORE_RE.match(line)
         if m:
-            cur_t = float(m.group(2))
+            cur = (int(m.group(1)), float(m.group(2)))
             continue
-        if line.startswith("lavfi.scd.score=") and cur_t is not None:
+        if line.startswith("lavfi.scd.score=") and cur is not None:
             try:
-                times.append(cur_t)
-                scores.append(float(line.split("=", 1)[1]))
+                by_frame[cur[0]] = (cur[1], float(line.split("=", 1)[1]))
             except ValueError:
                 pass
     cuts = [0.0]
-    if not scores:
+    if not by_frame:
         return cuts
+    n_frames = max(by_frame) + 1
+    times: List[float] = [by_frame[i][0] if i in by_frame else -1.0 for i in range(n_frames)]
+    scores: List[float] = [by_frame[i][1] if i in by_frame else 0.0 for i in range(n_frames)]
     w = 12
     for i, sc in enumerate(scores):
         if sc < threshold:

package/scripts/waveform.py

@@ -78,6 +78,11 @@ def main() -> int:
     cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]
     cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
     cmd += aac_args()
+    # -shortest alone is not enough on FFmpeg 5.x: showwaves keeps emitting frames after the
+    # audio ends (a 12 s source came out 14.08 s on 5.1.1, #146), so the output is also capped
+    # at the source's own duration when probe knows it.
+    if meta.get("duration"):
+        cmd += ["-t", f"{float(meta['duration']):.3f}"]
     cmd += ["-shortest", output]
     run(cmd)