ffmpeg-skill 2.10.3 → 2.10.5

package/README.md

@@ -1,27 +1,34 @@
 <p align="center">
-  <img src="assets/logo.png" alt="FFmpeg Skill: media processing for AI agents" width="760">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/app-icon-dark.png">
+    <img src="brand/app-icon.png" width="128" alt="ffmpeg-skill app icon">
+  </picture>
 </p>
 
-<h1 align="center">ffmpeg-skill</h1>
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="brand/logo/ffmpeg-skill-wordmark-white.svg">
+    <img src="brand/logo/ffmpeg-skill-wordmark-black.svg" height="48" alt="ffmpeg-skill">
+  </picture>
+</p>
 
-<p align="center"><strong>Give your coding agent a video editor.</strong></p>
+<p align="center"><b>Give your coding agent a video editor.</b><br>
+Claude Code, Cursor, Codex or any MCP client edits your footage with local FFmpeg, then checks its own output.<br>
+No cloud · No API keys · Python standard library</p>
 
 <p align="center">
-  Local FFmpeg · No cloud · No API keys · Python standard library<br>
-  Claude Code · Cursor · Codex · MCP
+  <a href="#quick-start"><b>Quick start</b></a> ·
+  <a href="docs/demos.md">Demos</a> ·
+  <a href="#tools">Tools</a> ·
+  <a href="#mcp">MCP</a> ·
+  <a href="https://www.npmjs.com/package/ffmpeg-skill">npm</a>
 </p>
 
 <p align="center">
   <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
   <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a>
-  <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/dm/ffmpeg-skill" alt="npm downloads"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/stargazers"><img src="https://img.shields.io/github/stars/kajisho5/ffmpeg-skill" alt="GitHub stars"></a>
-  <a href="https://github.com/kajisho5/ffmpeg-skill/commits/main"><img src="https://img.shields.io/github/last-commit/kajisho5/ffmpeg-skill" alt="last commit"></a>
-  <img src="https://img.shields.io/badge/python-3.9%20%7C%203.13-blue" alt="Python 3.9 and 3.13 tested">
   <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-5.1%20%7C%206.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 5.1, 6.1, 7.1, 8 and 9 tested in CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
-  <a href="https://github.com/sponsors/kajisho5"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors" alt="Sponsor"></a>
 </p>
 
 ```bash
@@ -39,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.
 
@@ -70,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)
 
 ---
 
@@ -210,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 |
@@ -382,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/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.3`) | any release |
+| `skill.version` | the npm / package.json version (`2.10.5`) | 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.3", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "2.10.5", "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "2.10.3",
+  "version": "2.10.5",
   "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
 ```

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/join.py

@@ -509,7 +509,7 @@ def main() -> int:
     if len(set(chans)) > 1:
         info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
     for i in range(n):
-        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
+        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
         parts.append(f"[{audio_src[i]}]aformat=sample_rates=48000:channel_layouts={layout},asetpts=PTS-STARTPTS[a{i}]")
 
     # pad the shorter stream to the clip's length: the audio with silence, the picture by holding

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)