Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

docs: answer the shared questions, and remove a fixed logo as a redact mode (#341)

Shogo Kajiyama5648043fc7e0
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9124bcb..bd190e4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,14 @@
## Unreleased
-(nothing yet)
+### Added
+
+- **README FAQ.** Answers the questions that followed the tool being shared: a caller cannot pass a filter graph or other raw ffmpeg arguments (schemas come from each script's argparse, and CI fails on drift; `doctor` checks the filters beforehand); Remotion and HyperFrames render a picture from code, and a file they write is an ordinary input here; a fixed logo or burned-in line can be interpolated with `redact.py --mode delogo`, while inpainting and anything that moves stay out of scope; nothing tracks a face or a subject; the GPU encode path is Apple VideoToolbox.
+- **`redact.py --mode delogo`.** ffmpeg's `delogo` filter, with the same typed rectangle as blur and pixelate (`--x`, `--y`, `--width`, `--height`). It fills that rectangle from the picture around it. The box has to sit at least 1 px inside the frame (the filter's band is fixed at 1, and the option is gone), and an HDR or 10-bit source is refused. A separate script was not added: this is the known-box operation `redact.py` already owns, and the tool count stays 42.
+
+### Fixed
+
+- **Windows 11 resolves Nirmala UI for Hindi, Bengali and Tamil (#339).** The font ships as `C:\Windows\Fonts\Nirmala.ttc`. `WINDOWS_FONTS` only named `Nirmala.ttf` and `NirmalaB.ttf`, so `doctor` reported no font for `hi`, `bn` and `ta`. The collection is now in those three lists, after the `.ttf` names, so a machine that still has Mangal or `Nirmala.ttf` keeps that file.
## 2.10.4
diff --git a/README.md b/README.md
index 4c5eb86..5022ddd 100644
--- a/README.md
+++ b/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:
diff --git a/SKILL.md b/SKILL.md
index a884650..db24de6 100644
--- a/SKILL.md
+++ b/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
diff --git a/demos/build.py b/demos/build.py
index 9867e76..8daa6cb 100644
--- a/demos/build.py
+++ b/demos/build.py
@@ -978,6 +978,19 @@ def demo_redact_blur(ctx):
return before, after
+def demo_delogo(ctx):
+ """A fixed white block stands in for a burned-in logo. redact.py --mode delogo fills that
+ rectangle from the picture around it. The box is given; nothing finds it."""
+ before = ctx.path("before.mp4")
+ ffmpeg("-i", str(FIX / "motion.mp4"), "-t", "4",
+ "-vf", "drawbox=x=48:y=36:w=240:h=96:color=white:t=fill",
+ "-c:v", "libx264", "-preset", "veryfast", "-crf", "18", "-c:a", "copy", str(before))
+ after = ctx.path("after.mp4")
+ ctx.script("redact.py", before, "--x", "48", "--y", "36", "--width", "240",
+ "--height", "96", "--mode", "delogo", "--preset", "veryfast", "-o", after)
+ return before, after
+
+
def demo_sphere_flat(ctx):
before = FIX / "equirect.mp4"
after = ctx.path("after.mp4")
@@ -1554,6 +1567,9 @@ _ROWS = [
("redact_blur", PICTURE, "Redact a rectangle",
"One region blurred for the whole clip and the rest of the frame untouched. The rectangle has to be given: this tool finds no faces and no plates.",
demo_redact_blur, "video", None),
+ ("delogo", PICTURE, "Remove a fixed logo",
+ "The white block is a stand-in for a burned-in logo. redact.py --mode delogo fills that rectangle from the picture around it. A logo that moves, or text that needs inpainting, is out of scope: the box is the caller's, and it has to sit 1 px inside the frame.",
+ demo_delogo, "video", None),
("sphere_flat", PICTURE, "360 panorama to a flat view",
"v360 maps the 2:1 equirectangular source onto a rectilinear camera pointed 40 degrees right and 10 degrees down -- the same viewport a headset would show, baked into a file.",
demo_sphere_flat, "video", "filter:v360"),
diff --git a/docs/contract.md b/docs/contract.md
index b0499c3..f346de7 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -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
diff --git a/docs/demos.md b/docs/demos.md
index 20a6cd0..dc4b116 100644
--- a/docs/demos.md
+++ b/docs/demos.md
@@ -417,6 +417,16 @@ python3 scripts/redact.py demos/out/fixtures/motion.mp4 --x 420 --y 180 --width
**Look for:** One region blurred for the whole clip and the rest of the frame untouched. The rectangle has to be given: this tool finds no faces and no plates.
+### Remove a fixed logo
+
+![Remove a fixed logo](demos/delogo.gif)
+
+```bash
+python3 scripts/redact.py demos/out/delogo_before.mp4 --x 48 --y 36 --width 240 --height 96 --mode delogo --preset veryfast -o demos/out/delogo_after.mp4
+```
+
+**Look for:** The white block is a stand-in for a burned-in logo. redact.py --mode delogo fills that rectangle from the picture around it. A logo that moves, or text that needs inpainting, is out of scope: the box is the caller's, and it has to sit 1 px inside the frame.
+
### 360 panorama to a flat view
![360 panorama to a flat view](demos/sphere_flat.gif)
diff --git a/docs/demos/delogo.gif b/docs/demos/delogo.gif
new file mode 100644
index 0000000..fab5fef
Binary files /dev/null and b/docs/demos/delogo.gif differ
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 3a0a86b..7c818c0 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -1570,6 +1570,24 @@ not a new file format this tool would have to maintain.
`start_snapped`'s meaning (the presented start moved) and `precision` takes
`least_exact_precision`'s (the least exact segment).
+## Unreleased — a fixed logo comes off with redact.py --mode delogo
+
+- **`--mode delogo` is a mode of `redact.py`, not a 43rd script.** The operation is the one
+ redact already has: a caller-supplied rectangle, applied to the whole clip, with no search
+ for the region. A new tool would restate that and move the count the 1.16 and 1.17 entries
+ above keep at 42. Blur and pixelate obscure the box; delogo fills it from the surrounding
+ pixels (ffmpeg's `delogo`). It is a border blend. Inpainting, a logo that moves, and
+ burned-in text whose position changes are out of scope, same as a face the caller did not
+ box. Code: `redact.main()`. Tests: `test_delogo_interpolates_a_fixed_rectangle_and_refuses_the_frame_edge`,
+ `test_delogo_refuses_a_10_bit_source`.
+- **The box must leave a 1 px ring, because `delogo` expands it by a band that is no longer a
+ flag.** On 5.1 through current the filter sets `band = 1`, grows the rectangle by that ring
+ and refuses the frame when the ring leaves it (`x < 1`, `y < 1`, or `x + width` / `y + height`
+ flush with the far edge). Passing `band` is an error on 6.1 ("Option not found"), so the tool
+ does not expose it. An HDR or 10-bit source is refused up front: the filter's pixel formats
+ are 8-bit YUV, and letting ffmpeg insert a scale would flatten the picture without saying so.
+ Code: `redact.main()`. Tests: the two named above.
+
## Unreleased — a video layer in a project
- **`overlays[]` refuses `video` beside another layer kind, and only that combination.** A video
diff --git a/references/scripts.md b/references/scripts.md
index eaa7b55..0657940 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -272,18 +272,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
```
diff --git a/scripts/_common/fonts.py b/scripts/_common/fonts.py
index 5420a81..bd00416 100644
--- a/scripts/_common/fonts.py
+++ b/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")],
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 25180c7..3b2dcb0 100644
--- a/scripts/_contract.py
+++ b/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"),
diff --git a/scripts/redact.py b/scripts/redact.py
index 4095556..9dfdd33 100644
--- a/scripts/redact.py
+++ b/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)
diff --git a/tests/test_picture.py b/tests/test_picture.py
index 04ead9d..35c6495 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -73,6 +73,37 @@ class PictureTests(MediaFixtures):
def test_redact_odd_dimensions_refused(self):
script("redact.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
+ def test_delogo_interpolates_a_fixed_rectangle_and_refuses_the_frame_edge(self):
+ """ffmpeg's delogo fills a known box from the pixels around it. A white block on grey
+ comes back grey; the same box with x=0 is refused, because the filter's 1 px band
+ (no longer an option) would leave the frame."""
+ src = OUT / "delogo_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", "color=c=gray:s=320x180:rate=10:d=0.4",
+ "-vf", "drawbox=x=40:y=30:w=80:h=40:color=white:t=fill",
+ "-c:v", "libx264", "-preset", "veryfast", "-pix_fmt", "yuv420p", str(src))
+ self.assertGreater(min(_pixel_at(src, 0.1, 80, 50)), 240, "the fixture's logo is white")
+ out = OUT / "delogo_out.mp4"
+ proc = script("redact.py", src, "--x", "40", "--y", "30", "--width", "80", "--height", "40",
+ "--mode", "delogo", "--fast", "--json", "-o", out)
+ doc = json.loads(proc.stdout)
+ self.assertIn("delogo=x=40:y=30:w=80:h=40", doc["commands"][0])
+ self.assertNotIn("boxblur", doc["commands"][0])
+ self.assertLess(max(_pixel_at(out, 0.1, 80, 50)), 180, "the white block was interpolated away")
+ self.assertGreater(min(_pixel_at(out, 0.1, 8, 8)), 90, "a corner outside the box stays grey")
+ edge = script("redact.py", src, "--x", "0", "--y", "30", "--width", "80", "--height", "40",
+ "--mode", "delogo", "--json", expect_fail=True)
+ err = json.loads(edge.stdout)
+ self.assertEqual(err["error"]["kind"], "input")
+ self.assertIn("1 px", err["error"]["message"])
+
+ def test_delogo_refuses_a_10_bit_source(self):
+ proc = script("redact.py", self.hdr, "--x", "40", "--y", "30", "--width", "80", "--height", "40",
+ "--mode", "delogo", "--json", expect_fail=True)
+ err = json.loads(proc.stdout)
+ self.assertEqual(err["error"]["kind"], "input")
+ self.assertIn("8-bit", err["error"]["message"])
+
# ---------------------------------------------------------------- grid
def test_grid_composites_cols_rows_with_labels(self):
out = OUT / "grid1.mp4"
@@ -2847,6 +2878,48 @@ class ScriptFontTests(unittest.TestCase):
self.assertEqual(font_for_script("ja"), font_for_script("ja"))
+class WindowsNirmalaTests(unittest.TestCase):
+ """#339: Windows 11 ships Nirmala UI as Nirmala.ttc. The lookup is by file name, so a
+ directory that contains only the collection must count as a font for hi, bn and ta."""
+
+ def tearDown(self):
+ import _common.fonts as fonts
+ fonts._SCRIPT_FONT_CACHE.clear()
+
+ def test_windows_11_nirmala_ttc_covers_hindi_bengali_and_tamil(self):
+ import _common.fonts as fonts
+ fonts._SCRIPT_FONT_CACHE.clear()
+ with tempfile.TemporaryDirectory() as tmp:
+ fonts_dir = Path(tmp) / "Fonts"
+ fonts_dir.mkdir()
+ (fonts_dir / "Nirmala.ttc").write_bytes(b"not a real font; existence is the check")
+ with unittest.mock.patch("platform.system", return_value="Windows"), \
+ unittest.mock.patch.dict(os.environ, {"WINDIR": tmp}):
+ for script_name in ("hi", "bn", "ta"):
+ path, family = fonts._script_font_uncached(script_name)
+ self.assertTrue(str(path).endswith("Nirmala.ttc"), path)
+ self.assertEqual(family, "Nirmala UI")
+ self.assertEqual(fonts.script_font_status(script_name), "available")
+ # A dedicated file still wins when both are installed: Mangal for Devanagari,
+ # Nirmala.ttf ahead of the collection for Bengali and Tamil.
+ (fonts_dir / "Nirmala.ttf").write_bytes(b"ttf")
+ (fonts_dir / "mangal.ttf").write_bytes(b"ttf")
+ fonts._SCRIPT_FONT_CACHE.clear()
+ hi, hi_family = fonts._script_font_uncached("hi")
+ bn, _bn_family = fonts._script_font_uncached("bn")
+ self.assertTrue(str(hi).endswith("mangal.ttf"), hi)
+ self.assertEqual(hi_family, "Mangal")
+ self.assertTrue(str(bn).endswith("Nirmala.ttf"), bn)
+ # No Nirmala and no Mangal: the script is missing, which is what doctor reported.
+ with tempfile.TemporaryDirectory() as empty:
+ (Path(empty) / "Fonts").mkdir()
+ fonts._SCRIPT_FONT_CACHE.clear()
+ with unittest.mock.patch("platform.system", return_value="Windows"), \
+ unittest.mock.patch.dict(os.environ, {"WINDIR": empty}):
+ self.assertIsNone(fonts._script_font_uncached("hi"))
+ self.assertEqual(fonts.script_font_status("hi"), "missing")
+
+
class EmojiTests(unittest.TestCase):
"""1.15: emoji are detected as clusters, measured at a full em, reserved in the ASS and
composited as PNGs -- and every degraded path says so instead of lying."""