ffmpeg-skill 0.10.0 → 0.12.5

package/references/process-pitfalls.md

@@ -0,0 +1,85 @@
+# Process pitfalls
+
+Mistakes made (or nearly made) while developing this repo that were not about FFmpeg
+or a platform's behaviour — about the *process* of making a change safely. Written down
+for the same reason `references/ci-platform-pitfalls.md` exists: a mistake that isn't
+recorded gets repeated the next time a session starts fresh with no memory of it.
+
+**This file is a living record.** Whenever a change here is made (or nearly made, then
+caught before landing) because an existing guardrail — a pinned test, an environment
+constraint, a platform's real behaviour under repeated attempts — wasn't checked first,
+add an entry below. Don't wait to be asked.
+
+## Before narrowing a `required`/`optional` capability list, grep for the pinned test that checks it
+
+`scripts/_contract.py`'s `TOOL_META[...]["required"]` drives `doctor`'s per-tool `usable`
+answer (`_tool_usability()` in `_contract.py` only reads `required`, never `optional`).
+Moving a capability from `required` to `optional` — even when it's honestly true that a
+new flag makes it conditional — silently changes what `doctor` reports as `usable: no`
+on a machine missing that capability, for the tool's *default* invocation too.
+
+`tests/test_contract.py`'s `DoctorDetectionTests` pins specific `usable` outcomes against
+real captured `ffmpeg -filters`/`-encoders` fixtures (e.g. a plain Homebrew macOS build
+correctly reporting `caption.usable: "no"` because it lacks `filter:subtitles`). A change
+to `required` that isn't checked against these first can pass a quick unit test and still
+break this fixture-based guarantee.
+
+Caught twice while adding capability metadata for new flags (`caption.py --mode mux` in
+#51, `doctor`'s `gpu_encoders` in #52) — in both cases the fix was to grep
+`tests/test_contract.py` for `usable` and `_doctor(` *before* editing `TOOL_META`, not
+after a test failure revealed it. Do that grep first, every time `required`/`optional`
+changes.
+
+## Git tag push and GitHub Release creation are not reachable from this environment
+
+The git credentials available here can push to `refs/heads/*` (branches) but not
+`refs/tags/*` — confirmed by a 403 straight from the git-receive-pack endpoint, not an
+auth failure, meaning it's a deliberate scope restriction, not a bug to route around.
+The GitHub MCP tool surface has no `create_release`/`create_tag` equivalent either
+(`create_branch`, `create_pull_request`, `create_or_update_file` exist; nothing for
+releases). A direct call to the GitHub REST API's `/releases` endpoint with a raw token
+is also blocked by the outbound proxy itself (its own 403, pointing at Anthropic's docs,
+not GitHub's).
+
+Confirmed once (retried the tag push a second time "just in case" before accepting it).
+Don't retry either path a second time — if `git push origin <tag>` 403s, or no
+release-creation tool is found in one `ToolSearch` pass, say so once and hand the user
+the two-minute browser-only path instead (open the repo's `/releases/new`, type the new
+tag name in the tag field — GitHub creates it from the target branch on publish, no git
+command needed).
+
+## A quantitative test failing three different ways across fixture redesigns means the platform, not the fixture, is the problem
+
+`test_stabilize_reduces_frame_to_frame_motion` (macOS CI, `stabilize.py`) failed with
+three independently redesigned shake fixtures in a row — each time the instinct was "the
+fixture's frequencies must be wrong," each time the retuned fixture failed a *different*
+way on the next CI run. The actual cause (libvidstab behaving differently across the
+Linux and macOS ffmpeg builds) was diagnosable from the first failure: a synthetic
+fixture that reliably improves under one implementation and reliably gets worse under
+another is evidence the implementations disagree, not that the fixture is miscalibrated.
+
+If a quantitative assertion fails on one platform, survives a redesign, and fails again
+on the *same* platform in a different way: stop redesigning the fixture. Either restrict
+the strict assertion to the platform where it's provably correct (keeping a weaker,
+platform-general check — output exists, has the right duration — everywhere), or escalate
+before spending a third CI cycle on it.
+
+## A fix merged after CHANGELOG.md's current-version section was drafted can silently miss it
+
+`CHANGELOG.md`'s `## 0.12.0` section was written once, covering everything merged up to
+that point. Two fixes that closed real issues after that point (#62's `--audio-stream`
+extension via PR #72, #77's dry-run-dims fix via PR #88) landed with no further nudge to
+go back and add a bullet — #62's fix actually got a bullet (its content is genuinely
+described) but the `Closes #62` link was left off, and #77 was missed outright until a
+direct question ("shouldn't this bump the version?") prompted a manual check. Neither was
+caught by CI, because nothing checked CHANGELOG.md against what had actually been closed.
+
+Caught by hand both times, then closed properly with `tests/test_contract.py`'s
+`test_changelog_mentions_every_closed_issue_since_last_tag`, which walks `git log` back to
+the latest release tag, extracts every `Closes #N.` from a commit body, and fails if that
+issue number doesn't appear anywhere in `CHANGELOG.md`. This needs real history (`ci.yml`'s
+`actions/checkout` step now passes `fetch-depth: 0` for exactly this reason — the default
+shallow clone leaves no tag reachable to diff against, which would make the test silently
+skip itself in CI, not fail). If this test ever needs to skip a genuinely changelog-less
+closed issue (a pure process note, a duplicate, a revert of an unreleased change), name the
+exemption in the test itself with a reason — don't just widen the regex or drop the check.

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
 ```
@@ -251,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
@@ -292,3 +409,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.
+