ffmpeg-skill 2.10.4 → 2.10.6

package/README.md

@@ -46,7 +46,7 @@ npx ffmpeg-skill
   </tr>
 </table>
 
-Left half is the input, right half is what the command produced. **[All 53 before/after demos, with the exact command under each one →](docs/demos.md)** — all of it generated from synthetic footage by `python3 demos/build.py`, so you can rebuild every frame of it yourself.
+Left half is the input, right half is what the command produced. **[All 66 before/after demos, with the exact command under each one →](docs/demos.md)** — all of it generated from synthetic footage by `python3 demos/build.py`, so you can rebuild every frame of it yourself.
 
 `ffmpeg-skill` is an [Agent Skill](https://docs.anthropic.com/en/docs/agents-and-tools/agent-skills) for Claude Code, Cursor, Codex and any agent that reads `SKILL.md`. It teaches the agent a fixed workflow (probe → edit losslessly where possible → check → verify) and ships **42 tools** that do the actual work with `ffmpeg` / `ffprobe`: cut, join, silence removal, fit to duration and aspect, captions and karaoke, overlays and motion graphics, HDR → SDR and LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, whole-edit project rendering, batch folders. Every tool is also callable as an MCP tool (`tools/list` advertises a core 12 by default to keep client context small, with `FFMPEG_SKILL_MCP_FULL=1` listing all 42; every tool is reachable by name through `tools/call` either way), and the whole set is described by a machine-readable contract.
 
@@ -77,7 +77,7 @@ Other repos in the ecosystem — [`media-analysis-skill`](https://github.com/kaj
 ---
 
 **Contents**
-[Standalone, and in an ecosystem](#standalone-and-in-an-ecosystem) · [Why](#why) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Design principles](#design-principles) · [Tools](#tools) · [Audio](#audio-is-a-first-class-input) · [Built for agents](#built-for-agents) · [FFmpeg compatibility](#ffmpeg-compatibility) · [Tested on real footage](#tested-on-real-footage) · [Install](#install) · [Requirements](#requirements) · [Development](#development) · [Docs](#docs)
+[Standalone, and in an ecosystem](#standalone-and-in-an-ecosystem) · [Why](#why) · [Quick start](#quick-start) · [How it works](#how-it-works) · [Design principles](#design-principles) · [Tools](#tools) · [Audio](#audio-is-a-first-class-input) · [Built for agents](#built-for-agents) · [FAQ](#faq) · [FFmpeg compatibility](#ffmpeg-compatibility) · [Tested on real footage](#tested-on-real-footage) · [Install](#install) · [Requirements](#requirements) · [Development](#development) · [Docs](#docs)
 
 ---
 
@@ -217,7 +217,7 @@ These are the rules the skill file gives the agent and the code enforces.
 | `cropdetect.py` | Measure existing black letterbox/pillarbox bars and report the `crop.py`-ready rectangle that removes them — analysis only, writes no file; `--motion-centre` reports the per-second motion centroid instead, for a 9:16 reframe — report only, the calling agent picks the crop, no auto-reframing |
 | `deinterlace.py` | Deinterlace interlaced source footage (`yadif`), `--mode frame`/`field`, `--parity` |
 | `denoise.py` | Reduce video noise/grain (`hqdn3d`), `--strength low/medium/high` or individual spatial/temporal overrides |
-| `redact.py` | Blur or pixelate an exact pixel rectangle for the whole clip (privacy/compliance redaction) |
+| `redact.py` | Blur, pixelate, or (`--mode delogo`) interpolate away an exact pixel rectangle for the whole clip. The box is given: nothing here finds a face, a plate or a logo, and `delogo` is a border blend, not inpainting |
 | `sphere.py` | Extract a flat rectilinear viewport from a 360/spherical video (`--yaw --pitch --roll --h-fov --v-fov`); no subject tracking, only the aim you give it |
 | `straighten.py` | Rotate by an arbitrary angle for horizon correction (`--degrees`, `--fit crop/pad`) — distinct from `fit.py --rotate`'s exact 90-degree turns |
 | `insert.py` | Turn a still image into a silent, fixed-duration video clip (title card, end slate) at an exact frame size / fps, with an optional Ken Burns zoom/pan |
@@ -389,6 +389,28 @@ The short list for humans. The agent-facing version, with the reasoning, is the
 - **Outputs are never overwritten silently.** An existing output path is refused (`kind: input`, before anything runs); pass `--overwrite` where a replacement is intended.
 - **Long chains belong in a plan.** Three hand-chained re-encodes lose quality and are hard to change; `render.py` runs the whole edit from one JSON file, and `--dry-run` shows every ffmpeg command before anything is written.
 
+## FAQ
+
+### Can I pass raw ffmpeg arguments, or a filter_complex?
+
+Each operation is a script whose flags are its argparse parser, and that parser is what `contract --json` and the MCP `inputSchema` are built from. CI fails the build when those drift from the scripts. A caller-supplied filter graph, `-vf` string, or other ffmpeg option is not an argument any script accepts. `doctor` reads `ffmpeg -filters` (and `-encoders`, `-bsfs`) and reports a filter a tool needs before a job runs into it. MCP does accept an `argv` array, and that array is the named script's own CLI flags, still bound to that script: the script's flags, never an ffmpeg command line and never a shell.
+
+### How does this differ from Remotion or HyperFrames? Can they be used together?
+
+Remotion renders a video from React components. HyperFrames renders one from HTML. This repository does neither, and it does not call either of them. It edits a media file you already have, on the machine, with ffmpeg and ffprobe, then probes the file it wrote. A render from either tool is an ordinary input: `probe.py`, `cut.py`, `fit.py`, `export.py` and `check.py` take the file the same way they take any other clip.
+
+### Can it remove burned-in subtitles or logos?
+
+A rectangle you already know, sitting still for the whole clip, can be filled from the picture around it with `redact.py --mode delogo` (ffmpeg's `delogo` filter). That is a 1 px border blend. It is not inpainting: a logo that moves, or burned-in subtitles whose position changes, is out of scope. The same known box can be obscured instead, with `--mode blur` or `--mode pixelate`. None of the three finds the box. `delogo` also needs the box at least 1 px inside the frame, and it only interpolates 8-bit YUV, so an HDR or 10-bit source is refused until `color.py --to-sdr`.
+
+### Does it auto-track faces or subjects for reframing?
+
+`fit.py --fit crop` centres the crop unless you pass `--crop-x` and `--crop-y`. `crop.py` cuts the rectangle you pass. `cropdetect.py` measures letterbox bars, and `--motion-centre` reports where motion sat each second; it writes no file and picks no crop. `sphere.py` points a 360 view where you aim it. `look.py` writes a contact sheet. Nothing in this repository detects a face, a product or a subject. Choosing what to keep in frame is the caller's.
+
+### Does it encode on the GPU?
+
+The encode path a tool will actually take is Apple VideoToolbox, for h264, hevc and prores, and only on Apple Silicon. `--hw` asks for it on that call. `FFMPEG_SKILL_HW=1` makes it the default for every re-encoding tool except `export.py`'s delivery presets, which take `--hw` on their own (or `render.py --hw` for a whole project). AV1 stays on SVT-AV1. nvenc, QSV, VAAPI and AMF are reported by `doctor --json`'s `gpu_encoders` when the ffmpeg build was compiled with them, and no tool encodes with them. One build is the exception to opt-in: with no `libx264` and no `libx265`, and with `h264_videotoolbox` or `hevc_videotoolbox`, those encodes use VideoToolbox without `--hw` and the result says `hw.source` is `"auto"`. `--no-hw` still asks for the CPU encoder. A VideoToolbox job the hardware refuses is re-encoded on the CPU and the result says so (`hw.fallback`).
+
 ## 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 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:

package/SKILL.md

@@ -86,6 +86,7 @@ Timestamp flags (`--start`, `--end`, `--at`, `--from`, `--duration`, `--offset`,
 | "this old footage is interlaced" | `deinterlace.py input.mp4` |
 | "it's grainy/noisy, clean it up" | `denoise.py input.mp4 --strength medium` |
 | "blur/pixelate this face/plate" (known box) | `redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate` |
+| "remove this fixed logo" (known box) | `redact.py input.mp4 --x 40 --y 20 --width 180 --height 60 --mode delogo` |
 | "stabilize this shaky footage" | `stabilize.py input.mp4` |
 | "are there black bars on this?" | `cropdetect.py input.mp4` |
 | "iPhone Dolby Vision clip looks wrong" | `color.py clip.mov --to-sdr` or `--strip-dovi` (keep HDR, drop the DV layer) |
@@ -196,9 +197,9 @@ Notes: send a valid .cube, or say if you want the clip left as is
 Those filler lines are sentences, not labels: the same report for a Japanese request ends
 `Check: 検証するものなし` / `Look: 不要`.
 
-A refusal uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. The shortest failure gets all five labels, never headings. A partial result is `Done:` with the shortfall in `Notes:`; a refusal that still delivers something is `Failed:` — never a third label like `Done (partially):`. Quote a failure's `error.hint` in `Notes:` — the flag change a retry needs.
+A refusal uses the same shape: `Failed:` names what was refused and why, `Steps:` lists what did run, `Look: not needed`. A partial result is `Done:` with the shortfall in `Notes:`; a refusal that still delivers something is `Failed:` — never a third label like `Done (partially):`. Quote a failure's `error.hint` in `Notes:`.
 
-Every script prints `{"status": "failed", "error": {"kind": input | ffmpeg | output | missing_tool | timeout | verification | interrupted, "message": ...}}` with `--json` and exits non-zero; quote the message, never paraphrase it.
+A failure's `--json` is `status: failed` plus `error.kind` and `error.message`; quote the message, never paraphrase it.
 
 ## Things that look right but are wrong
 

package/bin/install.js

@@ -41,21 +41,39 @@ if (has('--help') || has('-h')) {
   process.exit(0);
 }
 
-// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
-if (args[0] === 'contract' || args[0] === 'doctor') {
-  // Windows Python installers commonly expose `python`/`py`, not `python3` (only the
-  // Microsoft Store package does); try python3 first (macOS/Linux convention), then fall
-  // back so `npx ffmpeg-skill doctor` doesn't silently fail with ENOENT on Windows.
-  const candidates = process.platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
-  let py;
+// Windows Python installers commonly expose `python`/`py`, not `python3`. The Microsoft Store
+// app-execution alias is a real python3.exe that spawns (no ENOENT) and exits non-zero, so a
+// missing `error` is not proof an interpreter ran. Probe with a version check, then fall through.
+const PYTHON_PROBE = ['-c', 'import sys; raise SystemExit(0 if sys.version_info >= (3, 9) else 1)'];
+
+function pythonCandidates(platform) {
+  return platform === 'win32' ? ['python3', 'python', 'py'] : ['python3'];
+}
+
+function runWithPython(scriptArgs, platform, spawn) {
+  const candidates = pythonCandidates(platform);
+  const run = spawn || spawnSync;
+  let last = null;
   for (const cmd of candidates) {
-    py = spawnSync(cmd, [path.join(ROOT, 'scripts', '_contract.py'), ...args], { stdio: 'inherit' });
-    if (!py.error) break;
+    const probe = run(cmd, PYTHON_PROBE, { stdio: 'ignore', timeout: 15000 });
+    if (probe.error || probe.status !== 0) {
+      last = probe;
+      continue;
+    }
+    return run(cmd, scriptArgs, { stdio: 'inherit' });
   }
-  if (py.error) {
-    console.error(`error: could not find a Python interpreter (tried: ${candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+  return { missing: true, error: last && last.error, status: last && last.status, candidates };
+}
+
+function main() {
+// `contract` / `doctor` are answered by scripts/_contract.py; everything else installs.
+if (args[0] === 'contract' || args[0] === 'doctor') {
+  const py = runWithPython([path.join(ROOT, 'scripts', '_contract.py'), ...args], process.platform, spawnSync);
+  if (py.missing) {
+    console.error(`error: could not find a Python 3.9+ interpreter (tried: ${py.candidates.join(', ')}). Install Python 3.9+ and ensure it is on PATH.`);
+    process.exit(127);
   }
-  process.exit(py.error ? 127 : py.status);
+  process.exit(py.error ? 127 : (py.status == null ? 1 : py.status));
 }
 
 const home = os.homedir();
@@ -159,3 +177,10 @@ if (!has('--uninstall')) {
   console.log('\nDone. Ask your agent things like "make this video 60 seconds and add captions".');
 }
 process.exit(failed ? 1 : 0);
+}
+
+if (require.main === module) {
+  main();
+}
+
+module.exports = { pythonCandidates, runWithPython };

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`2.10.4`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.6`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -119,7 +119,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "contract_version": "1.0",
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "2.10.4", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.6", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -384,6 +384,12 @@ environment variables (`doctor`'s `hw.default_on` is a boolean derived from `FFM
 never its value). The two binary paths can sit under a home directory, so read a pasted `doctor`
 before posting it.
 
+`filter:delogo` is optional on `redact` (`--mode delogo`). The filter fills a fixed
+rectangle from a 1 px ring of the surrounding picture. It is a border blend,
+not inpainting, and its pixel formats are 8-bit YUV, so an HDR or 10-bit
+source is refused (`color.py --to-sdr` first). `filter:boxblur` stays required
+on `redact`, because `--mode blur` is the default.
+
 `external:whisper` is **optional** for two tools since 1.17: `caption.py`
 (`--transcribe`) and `silence.py` (`--filler --transcribe`). Neither requires
 it — both take a transcript the caller already has (`--srt`/`--words`), and

package/mcp/server.py

@@ -21,7 +21,7 @@ import os
 import subprocess
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 HERE = Path(__file__).resolve().parent
 SCRIPTS = HERE.parent / "scripts"
@@ -90,18 +90,66 @@ def build_argv(name: str, args: Dict[str, Any]) -> List[str]:
     return argv
 
 
+def _timeout_in_argv(argv: List[str]) -> Optional[float]:
+    """The last `--timeout` / `--timeout=N` value in a raw argv list.
+
+    None when the flag is absent or its value is not a number (the child argparse then fails,
+    and the outer ceiling stays the environment default)."""
+    found: Optional[float] = None
+    seen = False
+    i = 0
+    n = len(argv)
+    while i < n:
+        token = argv[i]
+        if token == "--":
+            break
+        if token == "--timeout":
+            if i + 1 >= n:
+                return None
+            raw = argv[i + 1]
+            i += 2
+        elif token.startswith("--timeout="):
+            raw = token.split("=", 1)[1]
+            i += 1
+        else:
+            i += 1
+            continue
+        seen = True
+        try:
+            found = float(raw)
+        except ValueError:
+            return None
+    return found if seen else None
+
+
+def timeout_from_call(args: Dict[str, Any]) -> float:
+    """Per-call seconds for the MCP outer ceiling.
+
+    Structured `timeout` is the canonical key. A raw `argv` list ignores every other key, so
+    `--timeout` has to be read from that list: `--timeout 0` otherwise left the ceiling at 4x
+    the 1800 s default while the child itself ran with no limit. A negative value is 0, matching
+    apply_common (0 means no limit)."""
+    if isinstance(args.get("argv"), list):
+        parsed = _timeout_in_argv([str(a) for a in args["argv"]])
+        if parsed is None:
+            return _common._env_timeout()
+        return max(0.0, parsed)
+    try:
+        return max(0.0, float(args.get("timeout", _common._env_timeout())))
+    except (TypeError, ValueError):
+        return _common._env_timeout()
+
+
 def call_tool(name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     script = SCRIPTS / f"{name}.py"
     if name not in specs() or not script.exists():
         return {"isError": True, "content": [{"type": "text", "text": f"unknown tool {name}"}]}
     argv = build_argv(name, args or {})
     # The child enforces --timeout on each ffmpeg call; this outer ceiling (4x that plus 60 s)
-    # is the only thing that ends a child hung for any other reason. The caller's own `timeout`
-    # argument sets both; otherwise FFMPEG_SKILL_TIMEOUT / the 1800 s default.
-    try:
-        per_call = float((args or {}).get("timeout", _common._env_timeout()))
-    except (TypeError, ValueError):
-        per_call = _common._env_timeout()
+    # is the only thing that ends a child hung for any other reason. Structured `timeout` or
+    # `--timeout` inside a raw argv list sets both (0 = no limit); otherwise
+    # FFMPEG_SKILL_TIMEOUT / the 1800 s default.
+    per_call = timeout_from_call(args or {})
     proc = _common.run_tool([str(script)] + argv, per_call=per_call)
     stdout = proc.stdout.strip()
     text = stdout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.4",
+  "version": "2.10.6",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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

@@ -91,7 +91,16 @@ max(2 frames, 0.1 s) away from the source's own offset where the picture starts
 (the keyframe the copy began from; `--start` under `--edit-list`). It is
 reported, not repaired. `-ss`/`-t` are passed to the microsecond; `--accurate`
 seeks a second early and trims on the output side, so frames just before a
-keyframe are kept. `keyframe_snapped` is true for every stream copy (`precision`
+keyframe are kept. An `--accurate` re-encode of a video does not pass
+`-avoid_negative_ts make_zero`, which shifted the picture by the AAC priming
+(about 21 ms, more when a B-frame decode time is negative) while the sound
+stayed at 0, and `fit.py --fps` then changed the frame count. A start that
+lands on a frame leaves that frame at time 0. A start between frames begins on
+the next source frame and may keep up to one frame of timestamp. A `.mp4`/`.mov`
+edit list hides the priming. A source whose audio starts after its picture keeps
+that offset. An audio-only `--accurate` cut
+still uses `make_zero`; that priming is what `precision: codec_frame` counts
+in the length. `keyframe_snapped` is true for every stream copy (`precision`
 `packet`); `start_snapped` is measured: true when a copied picture starts more
 than a frame from `--start`, or when its start could not be measured (an unknown start is
 never claimed exact); `null` under `--dry-run`.
@@ -272,18 +281,25 @@ Heavier denoising trades fine detail for a cleaner but softer image -- for
 audio noise reduction use `audio.py --denoise` instead, this tool only
 touches the picture.
 
-### redact.py — blur or pixelate an exact rectangle
+### redact.py — blur, pixelate, or interpolate away an exact rectangle
 ```
-redact.py INPUT --x X --y Y --width W --height H [--mode blur|pixelate]
+redact.py INPUT --x X --y Y --width W --height H [--mode blur|pixelate|delogo]
                  [--blur-strength N] [--block-size N] [-o OUT]
 ```
 Same rectangle convention as `crop.py` -- the rectangle must already be
 known (a saved detection box, a hand-picked region); this tool does not
-locate faces or plates itself. `--mode blur` (default) box-blurs the
-rectangle; `--mode pixelate` mosaics it into `--block-size`-px blocks, the
-more unmistakably-redacted look often wanted for compliance footage. The
-rest of the frame, and the whole clip's timeline, are untouched -- to
-redact only part of the timeline, `cut.py` the clip into segments first.
+locate faces, plates, logos or burned-in text itself. `--mode blur`
+(default) box-blurs the rectangle; `--mode pixelate` mosaics it into
+`--block-size`-px blocks, the more unmistakably-redacted look often wanted
+for compliance footage. `--mode delogo` runs ffmpeg's `delogo` filter,
+which fills the rectangle from the picture around it: a fixed logo or a
+burned-in line that does not move. That is a border blend, not inpainting,
+and a logo that travels or subtitles that change position are out of
+scope. The filter reads a 1 px ring outside the box, so the box cannot
+touch the frame edge, and it only interpolates 8-bit YUV (an HDR or 10-bit
+source is refused; `color.py --to-sdr` first). The rest of the frame, and
+the whole clip's timeline, are untouched -- to cover only part of the
+timeline, `cut.py` the clip into segments first.
 
 ### sphere.py — flat viewport extraction from 360/spherical video
 ```
@@ -739,10 +755,13 @@ An `overlays[]` entry draws one of `"logo": true`, `"image"`, `"text"` or
 `"video"` (#326: a picture-in-picture or green-screen layer, `overlay.py
 --video`), with `position`, `scale`, `opacity`, `start`, `end`, `margin`,
 `platform` (and `fade`, `box`, `font*` for the still/text kinds) mapping to
-overlay.py's flags. `"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
-`"chromakey_blend"` key a colour out of the video layer. The stage runs after
-`fit`, so `"scale": 480` is 480 px of the delivered frame, and a template's
-safe margins apply as they do to a logo. Refused (`kind: input`) before the
+overlay.py's flags. `scale` is the layer width in px for a logo, image or
+video (`"scale": 480` is 480 px of the delivered frame, because the stage
+runs after `fit`). A text entry's size is `font_size`; `scale` on a text-only
+entry is refused (`kind: input`) rather than drawn at the default font size.
+`"chromakey": "0x00ff00"`, `"chromakey_similarity"` and
+`"chromakey_blend"` key a colour out of the video layer. A template's
+safe margins apply as they do to a logo. Also refused before the
 first stage: `video` together with `logo`/`image`/`text` in one entry (a
 logo, image and text together still draw the first of them, as before), a
 `chromakey*` key without `video`, `chromakey_similarity`/`_blend` without
@@ -1448,7 +1467,9 @@ overlay.py INPUT --image PNG [--scale W | --scale-percent P] | --text "..." [--f
 (`scripts/_platforms.py`), so a template's top-left logo clears TikTok's status bar instead of
 sitting 24 px into it; an explicit `--margin` (or a brand `safe_margin`) wins.
 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
+playing. `--scale` / `--scale-percent` set the width of an image, logo or
+`--video` layer. They are refused with `--text`: text size is `--font-size`.
+`--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.

package/scripts/_common/fonts.py

@@ -119,10 +119,13 @@ WINDOWS_FONTS = {
     "ja": [("meiryo.ttc", "Meiryo"), ("YuGothM.ttc", "Yu Gothic Medium"), ("YuGothR.ttc", "Yu Gothic"), ("msgothic.ttc", "MS Gothic")],
     "ar": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
     "he": [("tahoma.ttf", "Tahoma"), ("arial.ttf", "Arial")],
-    "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
+    # Windows 11 ships Nirmala UI as the collection Nirmala.ttc; there is no Nirmala.ttf (#339).
+    # The .ttf names stay first so a machine that still has them (older Windows, a copied font)
+    # keeps that file. Mangal, when present, stays the Devanagari face it always was.
+    "hi": [("mangal.ttf", "Mangal"), ("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("NirmalaB.ttf", "Nirmala UI")],
     "th": [("leelawui.ttf", "Leelawadee UI"), ("leelawad.ttf", "Leelawadee"), ("tahoma.ttf", "Tahoma")],
-    "bn": [("Nirmala.ttf", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
-    "ta": [("Nirmala.ttf", "Nirmala UI"), ("latha.ttf", "Latha")],
+    "bn": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("vrinda.ttf", "Vrinda")],
+    "ta": [("Nirmala.ttf", "Nirmala UI"), ("Nirmala.ttc", "Nirmala UI"), ("latha.ttf", "Latha")],
     "lo": [("leelawui.ttf", "Leelawadee UI"), ("DokChamp.ttf", "DokChampa")],
     "ru": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],
     "el": [("arial.ttf", "Arial"), ("segoeui.ttf", "Segoe UI")],

package/scripts/_contract.py

@@ -98,8 +98,9 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "cropdetect": dict(role="analysis", inputs=["video asset"], outputs=["detected crop rectangle JSON on stdout (no file)"],
                        required=FF + ["filter:cropdetect"], optional=[],
                        video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=False, idempotency="environment_dependent", deterministic=False),
-    "redact": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the given pixel rectangle blurred or pixelated"],
-                   required=FF + [X264, AAC, "filter:boxblur"], optional=[HDR_X265],
+    "redact": dict(role="execution", inputs=["video asset"], outputs=["video artifact with the given pixel rectangle blurred, pixelated, or interpolated away (--mode delogo)"],
+                   required=FF + [X264, AAC, "filter:boxblur"],
+                   optional=[HDR_X265, {"capability": "filter:delogo", "when": "--mode delogo"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "waveform": dict(role="execution", inputs=["audio or video asset (audio track only)"], outputs=["generated waveform or spectrum visualization video artifact"],
                      required=FF + [X264, AAC, "filter:showwaves"], optional=[{"capability": "filter:showspectrum", "when": "--style spectrum"}],
@@ -261,7 +262,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "deinterlace": dict(video="always", audio="always", note="the yadif filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "denoise":   dict(video="always", audio="always", note="the hqdn3d filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "cropdetect": dict(video="never", audio="never", note="analysis only, no artifact"),
-    "redact":    dict(video="always", audio="always", note="the boxblur/pixelate filter_complex always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+    "redact":    dict(video="always", audio="always", note="the boxblur, pixelate or delogo graph always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
     "waveform":  dict(video="always", audio="always", note="always encodes a fresh generated visualization clip; the source audio is always re-encoded to AAC"),
     "sphere":   dict(video="always", audio="always", note="the v360 filter always forces a re-encode of the video stream; audio is passed through to AAC unchanged"),
     "straighten": dict(video="always", audio="always", note="the rotate filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),

package/scripts/cut.py

@@ -22,6 +22,12 @@ caller never has to trust "it probably cut where I asked" on faith.
 A single-segment .mp4/.mov copy shifts its timestamps to zero (-avoid_negative_ts
 make_zero), so the picture starts at the keyframe; --edit-list keeps the MP4 edit
 list instead, which hides the keyframe's pre-roll so the picture starts at --start.
+An --accurate re-encode of a video does not: make_zero moved the picture by the
+AAC priming (about 21 ms, and further when a B-frame's decode time is negative)
+while the sound stayed at 0. A start that lands on a frame keeps that frame at 0.
+A start between frames begins on the next frame and may keep up to one frame of
+timestamp. The MP4 edit list hides the encoder priming, and a source whose audio
+starts late keeps that offset.
 
 A re-encode uses x264 for an SDR source and x265 Main10 for an HDR or BT.2020 one, as every
 editing tool does; --keep-hevc re-encodes an SDR HEVC source as HEVC (x265 8-bit BT.709, or
@@ -823,7 +829,19 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
         cmd += ["-sn", "-dn"]
         if meta.get("subtitle_streams") or meta.get("data_streams"):
             DROPPED_STREAMS.append(dst)
-        cmd += encode_args(meta, dst, crf, preset) + ["-avoid_negative_ts", "make_zero", dst]
+        cmd += encode_args(meta, dst, crf, preset)
+        if audio_only:
+            # asetpts already starts the samples at 0. make_zero is what folds the encoder's
+            # priming into the container length, which is the delay precision codec_frame reports.
+            # A video re-encode must not take it (#336): the earliest timestamp is that priming,
+            # or a negative B-frame decode time, so make_zero starts the picture after 0 and
+            # leaves the sound at 0. fit --fps then drops or repeats a frame. Without the shift
+            # a start on a frame has that frame at 0. A start between frames begins on the next
+            # frame and may keep up to one frame of timestamp; moving the picture alone would
+            # leave the sound that far ahead. An MP4/MOV edit list hides the priming, and a
+            # source whose audio starts late keeps that offset.
+            cmd += ["-avoid_negative_ts", "make_zero"]
+        cmd += [dst]
     elif audio_only:
         # output-side seek: an input seek on a video file lands on the previous video keyframe and on
         # FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packet

package/scripts/fit.py

@@ -198,7 +198,7 @@ def main() -> int:
             darken = 0.0 if meta["video"].get("bt2020_or_hdr") else BLUR_DARKEN
             if not darken:
                 info("--fit blur: HDR source, so the blurred background is not dimmed "
-                     "(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "
+                     "(an eq on PQ/HLG code values is not the -15% dim it is on SDR); "
                      "run color.py --to-sdr first for the SDR look")
             vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
         else:

package/scripts/overlay.py

@@ -116,8 +116,8 @@ def main() -> int:
     ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
     ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
     img = ap.add_argument_group("image options")
-    img.add_argument("--scale", type=int, help="scale the image to this width in px (keeps aspect)")
-    img.add_argument("--scale-percent", type=float, help="scale the image to this %% of the video width")
+    img.add_argument("--scale", type=int, help="width in px for an image, logo or video layer (keeps aspect); text size is --font-size")
+    img.add_argument("--scale-percent", type=float, help="width as a %% of the video for an image, logo or video layer (keeps aspect); text size is --font-size")
     txt = ap.add_argument_group("text options")
     txt.add_argument("--font", default="DejaVu Sans", help="fontconfig font name")
     txt.add_argument("--font-file", help="explicit .ttf/.otf/.ttc path (use this for CJK fonts)")
@@ -158,6 +158,10 @@ def main() -> int:
         die("--text is blank -- give the words to draw", kind="input")
     if not (args.image or args.text or args.video):
         die("give --image, --text, --logo or --video")
+    # --scale is a layer width. On a text draw it used to be accepted and ignored (fontsize stayed
+    # at --font-size), so a project that asked for 200 px text completed with the 42 px default.
+    if args.text and not (args.image or args.video) and (args.scale is not None or args.scale_percent is not None):
+        die("--scale and --scale-percent size an image, logo or video layer; text size is --font-size", kind="input")
     if args.brand:
         if args.margin == ap.get_default("margin"):
             args.margin = int(brand.get("safe_margin", args.margin))

package/scripts/redact.py

@@ -1,21 +1,28 @@
 #!/usr/bin/env python3
-"""Blur or pixelate an exact pixel rectangle for the whole clip (privacy redaction, license plates, faces).
+"""Blur, pixelate, or interpolate away an exact pixel rectangle for the whole clip.
 
 {x, y, width, height} are literal pixel offsets and dimensions in the SOURCE
 frame, the same convention as crop.py -- this tool needs the rectangle
 already known (a saved detection box, a hand-picked region); it does not
-locate faces or plates itself. The rest of the frame is untouched.
+locate faces, plates, logos or burned-in text itself. The rest of the frame
+is untouched.
 
 --mode blur (default) applies a strong box blur inside the rectangle;
 --mode pixelate mosaics it into large blocks -- the more recognisable,
 unmistakably-redacted look often wanted for compliance/legal footage.
-The region stays --mode blur/pixelate for the whole clip; for a region that
-only needs covering part of the timeline, cut the clip into segments first
-(cut.py) and redact only the relevant one.
+--mode delogo fills the rectangle from the picture around it (ffmpeg's
+delogo filter): a fixed logo or burned-in line, not inpainting, and not a
+region that moves. delogo reads a 1 px ring outside the box, so the box
+cannot touch the frame edge, and it only interpolates 8-bit YUV (an HDR or
+10-bit source is refused; color.py --to-sdr first).
+The region stays one mode for the whole clip; for a region that only needs
+covering part of the timeline, cut the clip into segments first (cut.py)
+and redact only the relevant one.
 
 Examples:
   python3 redact.py interview.mp4 --x 820 --y 140 --width 240 --height 240
   python3 redact.py dashcam.mp4 --x 0 --y 900 --width 400 --height 120 --mode pixelate --block-size 16
+  python3 redact.py branded.mp4 --x 40 --y 20 --width 180 --height 60 --mode delogo
 """
 import argparse
 import sys
@@ -31,7 +38,8 @@ def main() -> int:
     ap.add_argument("--y", type=int, required=True, help="top edge of the rectangle, in source pixels")
     ap.add_argument("--width", type=int, required=True, help="rectangle width in px (must be even)")
     ap.add_argument("--height", type=int, required=True, help="rectangle height in px (must be even)")
-    ap.add_argument("--mode", choices=["blur", "pixelate"], default="blur", help="blur (default) or pixelate the rectangle")
+    ap.add_argument("--mode", choices=["blur", "pixelate", "delogo"], default="blur",
+                     help="blur (default), pixelate, or delogo (interpolate a fixed rectangle away; not inpainting, and not a moving region)")
     ap.add_argument("--blur-strength", type=int, default=20, help="box-blur radius in px, --mode blur only (default 20)")
     ap.add_argument("--block-size", type=int, default=12, help="mosaic block size in px, --mode pixelate only (default 12)")
     ap.add_argument("--audio-stream", type=int, default=0,
@@ -64,6 +72,17 @@ def main() -> int:
         sw, sh = sh, sw
     if args.x + args.width > sw or args.y + args.height > sh:
         die(f"redaction rectangle ({args.x},{args.y},{args.width}x{args.height}) exceeds the source frame ({sw}x{sh})")
+    if args.mode == "delogo":
+        # delogo's band is fixed at 1 px (the option was removed; 5.1 through current all
+        # expand the box by that ring and refuse it when the ring leaves the frame).
+        vinfo = meta["video"]
+        if vinfo.get("bt2020_or_hdr") or (vinfo.get("bit_depth") or 8) > 8:
+            die(f"--mode delogo interpolates 8-bit YUV only (this source is {vinfo.get('pix_fmt') or 'not 8-bit'}); "
+                "color.py --to-sdr first")
+        if args.x < 1 or args.y < 1 or args.x + args.width >= sw or args.y + args.height >= sh:
+            die(f"--mode delogo needs a 1 px ring of picture around the rectangle "
+                f"({args.x},{args.y},{args.width}x{args.height} in {sw}x{sh}); "
+                "a logo on the frame edge is out of range")
     has_audio = bool(meta.get("audio"))
     audio_streams = meta.get("audio_streams") or []
     if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
@@ -72,17 +91,22 @@ def main() -> int:
         die("--audio-stream needs an input with audio streams")
 
     output = args.output or default_output(args.input, "redact")
-    crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
-    if args.mode == "blur":
-        # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
-        # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
-        radius = max(1, min(args.blur_strength, min(args.width, args.height) // 2 - 1))
-        chroma = max(1, min(radius // 2, min(args.width, args.height) // 4 - 1))
-        region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
+    if args.mode == "delogo":
+        cmd = ffmpeg_base() + ["-i", args.input, "-vf",
+                               f"delogo=x={args.x}:y={args.y}:w={args.width}:h={args.height}",
+                               "-map", "0:v:0"]
     else:
-        region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
-    fc = f"[0:v]split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"
-    cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
+        crop = f"crop={args.width}:{args.height}:{args.x}:{args.y}"
+        if args.mode == "blur":
+            # boxblur refuses a radius above half the plane: the chroma planes of 4:2:0 are half-size,
+            # so they get their own (halved) radius; a 30 px region with the default 20 used to fail
+            radius = max(1, min(args.blur_strength, min(args.width, args.height) // 2 - 1))
+            chroma = max(1, min(radius // 2, min(args.width, args.height) // 4 - 1))
+            region = f"{crop},boxblur={radius}:{radius}:{chroma}:{radius}"
+        else:
+            region = f"{crop},scale={max(1, args.width // args.block_size)}:{max(1, args.height // args.block_size)}:flags=neighbor,scale={args.width}:{args.height}:flags=neighbor"
+        fc = f"[0:v]split=2[base][region];[region]{region}[patched];[base][patched]overlay={args.x}:{args.y}[out]"
+        cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc, "-map", "[out]"]
     if has_audio:
         cmd += ["-map", f"0:a:{args.audio_stream}?"]
     cmd += video_args(meta, args.crf, args.preset)

package/scripts/render.py

@@ -40,7 +40,9 @@ skipped. "brand" points caption/graphics/overlay at a brand.json (fonts,
 colours, logo, safe margin); {"logo": true} in overlays places the brand logo.
 An overlay entry draws one of logo, image, text or video (a picture-in-picture
 layer, overlay.py --video; "chromakey", "chromakey_similarity" and
-"chromakey_blend" key a colour out of that video and need "video").
+"chromakey_blend" key a colour out of that video and need "video"). "scale"
+is that layer's width in px for a logo, image or video; a text entry's size
+is "font_size", and "scale" on a text entry is refused.
 
 "check" mirrors check.py's own exit code: a delivery-spec FAIL (or check.py
 itself failing to run) exits 1, same as running check.py directly would --
@@ -436,6 +438,10 @@ def check_overlay(ov: Any, label: str) -> None:
         tuned = [k for k in ("chromakey_similarity", "chromakey_blend") if ov.get(k) is not None]
         if tuned:
             die(f"{label}: {tuned[0]} tunes \"chromakey\", which this entry does not set")
+    # scale is a layer width (overlay.py --scale). A text entry that carries it used to complete
+    # with the default font size, because the text branch never reads the flag.
+    if ov.get("text") and not any(ov.get(k) for k in ("logo", "image", "video")) and ov.get("scale") is not None:
+        die(f"{label}: scale sizes an image, logo or video layer; text size is font_size", kind="input")
 
 
 def require_object(obj: Any, label: str) -> None:

package/scripts/speedramp.py

@@ -84,9 +84,14 @@ def main() -> int:
     output = args.output or default_output(args.input, "ramp")
 
     vparts, aparts, labels = [], [], []
+    # The coverage check above allows the last end to sit up to 0.5 s off the probed duration.
+    # That slack is for a caller who rounded the duration, not a reason to redraw the tail at
+    # the last factor. The end bound is omitted only when the stated end is the file's end
+    # (within 50 ms): a trim a few milliseconds short of the last packet drops that packet.
+    last_runs_to_eof = abs(segments[-1][1] - dur) <= 0.05
     for i, (start, end, factor) in enumerate(segments):
         vlabel, alabel = f"v{i}", f"a{i}"
-        end_expr = f"{end:.3f}" if i < len(segments) - 1 else None
+        end_expr = f"{end:.3f}" if not (i == len(segments) - 1 and last_runs_to_eof) else None
         trim = f"trim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
         vparts.append(f"[0:v]{trim},setpts=(PTS-STARTPTS)/{factor:.6f}[{vlabel}]")
         labels.append(f"[{vlabel}]")

package/scripts/sync.py

@@ -36,6 +36,17 @@ from _common import video_args, add_common, apply_common, emit, aac_args, audio_
 
 SR = 8000  # decode sample rate
 
+
+def sync_meaning(offset: float) -> str:
+    """The sentence a caller reads next to offset_seconds.
+
+    A zero offset used to take the else branch of `later if offset > 0` and say the second
+    file starts earlier. Values that print as 0.000 s (under half a millisecond) say the two
+    recordings start together; anything larger keeps later/earlier."""
+    if abs(offset) < 5e-4:
+        return "second starts together with the reference"
+    return "second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")
+
 # Scoring constants for coarse alignment. Both come from tests/bench_sync.py on real dialogue and
 # music with +/-30 s offsets, gain, noise and EQ (see evals/results and CHANGELOG 0.8.0):
 #
@@ -307,7 +318,7 @@ def main() -> int:
             "second": args.second,
             "offset_seconds": offset,
             "confidence": score,
-            "meaning": ("second starts %.3fs %s than reference" % (abs(offset), "later" if offset > 0 else "earlier")),
+            "meaning": sync_meaning(offset),
             "sources": sources_block,
         }
         if drift_info: