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.

Add 10 tools: cropdetect, deinterlace, denoise, redact, waveform, straighten, freeze, pad, speedramp, loop (#104)

Shogo Kajiyama6774ed04afda
diff --git a/CHANGELOG.md b/CHANGELOG.md
index d511751..3b30e3e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,66 @@
(nothing yet)
+## 0.15.0 — 5 more tools: straighten, freeze, pad, speedramp, loop
+
+Five more mechanical, typed-flag FFmpeg capabilities:
+
+- `straighten.py` — rotates by an arbitrary angle for horizon correction
+ (`rotate` filter), `--fit crop` (scale to fill, no visible gap) or `--fit
+ pad` (keep the full picture, fill the corners). Distinct from `fit.py
+ --rotate`'s exact 90-degree turns.
+- `freeze.py` — holds a frame for N seconds (`tpad`/`concat`), `--mode
+ insert` (pushes the rest of the clip later) or `--mode extend` (only at
+ the clip's end, no push).
+- `pad.py` — adds black/silent padding at the start and/or end of the
+ timeline (`tpad`/`apad`). Distinct from `fit.py --fit pad`'s per-frame
+ letterbox bars.
+- `speedramp.py` — steps through different constant speeds across a clip
+ via repeatable `--segment START-END:FACTOR` pieces (setpts/atempo per
+ segment, concatenated). Distinct from `fit.py`'s single whole-clip speed
+ factor.
+- `loop.py` — repeats a clip `--times` N or to a target `--duration`
+ (`-stream_loop`).
+
+Same conventions as every other tool here: every numeric flag range-checked
+before ffmpeg runs, no subject detection or judgement (straighten doesn't
+measure the tilt, loop doesn't smooth the seam, freeze doesn't pick where
+to hold -- the calling agent supplies all of that).
+
+Registered in `_contract.py`'s `TOOL_META`/`REENCODE_META` (39 tools total,
+up from 34); 19 new regression tests in `tests/test_all.py`, including a
+pixel-level check that `straighten.py --fit crop` leaves no black corner.
+
+## 0.14.0 — 5 new tools: cropdetect, deinterlace, denoise, redact, waveform
+
+Five mechanical, typed-flag FFmpeg capabilities that had no wrapper yet:
+
+- `cropdetect.py` — measures existing black letterbox/pillarbox bars (FFmpeg's
+ `cropdetect` filter) and reports the `crop.py`-ready rectangle. Analysis only,
+ writes no file. Distinct from `fit.py --fit crop`, which crops to a target
+ aspect ratio it computes itself with no black-bar measurement involved.
+- `deinterlace.py` — deinterlaces old interlaced source footage (`yadif`),
+ `--mode frame` (keeps fps) or `--mode field` (doubles fps), `--parity`.
+- `denoise.py` — video noise/grain reduction (`hqdn3d`), `--strength low/
+ medium/high` or individual spatial/temporal luma/chroma overrides. Distinct
+ from `audio.py --denoise`, which only touches audio.
+- `redact.py` — blurs or pixelates an exact caller-given pixel rectangle for
+ the whole clip (privacy/compliance redaction: faces, plates). Same
+ rectangle convention as `crop.py`; does not locate anything itself.
+- `waveform.py` — renders an audio track as a waveform or spectrum
+ visualization video (`showwaves`/`showspectrum`), for audio-only inputs
+ with no picture worth showing.
+
+All five follow this skill's typed-flags-only convention: every numeric flag
+is range-checked against FFmpeg's own real documented AVOptions before
+ffmpeg runs, and none introduces any subject detection or judgement --
+cropdetect measures existing bars, redact blurs the exact rectangle it's
+given, neither decides what belongs in frame.
+
+Registered in `_contract.py`'s `TOOL_META`/`REENCODE_META` (34 tools total,
+up from 29); 22 new regression tests in `tests/test_all.py` cover the
+functional path and validated ranges for each tool.
+
## 0.13.0 — add `sphere.py`: flat-viewport extraction from 360/spherical video
New tool wrapping FFmpeg's `v360` filter for the most common 360-video job: pointing a fixed,
diff --git a/README.md b/README.md
index 0513380..b90c782 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ npx ffmpeg-skill
![before / after demo](assets/demo.gif)
-`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 **29 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 an MCP tool, and the whole set is described by a machine-readable contract.
+`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 **39 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 an MCP tool, and the whole set is described by a machine-readable contract.
If `ffmpeg` and `python3` are on your PATH, it works: offline, on footage you would rather not upload.
@@ -139,7 +139,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
-4. **Machine-readable contract.** `contract --json` describes all 29 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 29 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
+4. **Machine-readable contract.** `contract --json` describes all 39 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 39 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
7. **Unknown is not missing.** When a listing cannot be read (a layout the parser does not know, ffmpeg exiting non-zero) the affected capabilities are `unknown`: never `missing`, never silently `available`. An installed filter is not reported absent; a failed detection is not a pass.
@@ -148,7 +148,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
## Tools
-29 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
+39 public tools, all Python 3.9 standard library, all with `--help`, `--dry-run`, `--json`, non-zero exit and a reason on stderr on failure.
**Analysis and inspection**
@@ -167,12 +167,22 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
| `silence.py` | Detect and remove dead air (jump cuts) with a margin around speech; list or export the cut list |
| `fit.py` | Fit to a duration (pitch-preserving speed change or trim, smooth slow-mo) and/or aspect ratio (pad or crop, with `--crop-x`/`--crop-y` to keep an off-centre subject) and/or exact `--width`/`--height`; rotate 90/180/270, flip h/v; force constant fps |
| `crop.py` | Crop to an exact pixel rectangle (`--x --y --width --height`) — distinct from `fit.py --fit crop`, which crops to an aspect ratio it computes itself |
+| `cropdetect.py` | Measure existing black letterbox/pillarbox bars and report the `crop.py`-ready rectangle that removes them — analysis only, writes no file |
+| `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) |
| `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 |
| `background.py` | Generate a solid-colour or two-colour gradient clip at an exact size/duration — no input file |
| `reverse.py` | Reverse playback (video and, unless `--no-audio`, audio) |
| `stabilize.py` | Two-pass motion stabilisation (`vidstabdetect`/`vidstabtransform`) |
| `sequence.py` | Numbered (`frame_%04d.png`) or glob-matched still images into a video |
+| `waveform.py` | Render an audio track as a waveform or spectrum visualization video (`showwaves`/`showspectrum`) — for audio-only inputs with no picture worth showing |
+| `freeze.py` | Hold a frame for N seconds (`--at`, `--hold`, `--mode insert/extend`) — an end-card hold or a comedic beat |
+| `pad.py` | Add black/silent padding at the start and/or end of the timeline (`--start`, `--end`) — distinct from `fit.py --fit pad`'s per-frame letterbox bars |
+| `speedramp.py` | Step through different constant speeds across a clip via `--segment START-END:FACTOR` (repeatable) — distinct from `fit.py`'s single whole-clip speed factor |
+| `loop.py` | Repeat a clip `--times` N or to a target `--duration` — for background loops and filling a fixed slot length |
**Audio**
@@ -260,7 +270,7 @@ npx ffmpeg-skill contract --json # or: python3 scripts/_contract.py -
npx ffmpeg-skill contract --json --static # without environment detection
```
-The contract is generated from the code that runs, not maintained beside it. For each of the 29 tools (`ffmpeg-skill/<name>`) it states:
+The contract is generated from the code that runs, not maintained beside it. For each of the 39 tools (`ffmpeg-skill/<name>`) it states:
| Field | Meaning |
|---|---|
@@ -285,7 +295,7 @@ The contract is generated from the code that runs, not maintained beside it. For
On Windows, `python3` is only on PATH if Python was installed from the Microsoft Store; a python.org install exposes `python` (or the `py` launcher) instead — if your MCP client reports the server failed to start, change `"command"` above to `"python"` (or the full path from `where python`).
-`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 29 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
+`mcp/server.py` is a stdio JSON-RPC transport with no tool table of its own. `tools/list` is derived from the contract at start-up: the same 39 names, the same order, and `inputSchema` translated from each tool's `input_schema`. `tools/call` maps structured arguments to argv and runs the named script; a raw `argv` form is accepted for compatibility and marked non-canonical. `python3 mcp/server.py --list` prints the tools; `--call probe '{"inputs": ["a.mp4"]}'` runs one from the shell.
### Capability detection
diff --git a/SKILL.md b/SKILL.md
index 38db366..72958bd 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -131,7 +131,12 @@ If a request needs an FFmpeg feature none of the 28 scripts expose, say so and n
| "make it vertical / for TikTok / 9:16", "square for Instagram" | `fit.py input.mp4 --aspect 9:16 --fit pad` (or `--fit crop`) |
| "resize to a specific height, width follows" | `fit.py input.mp4 --height 1080` (or `--width`, or both for an exact frame) |
| "crop to this exact box/rectangle" (known x/y/width/height, not an aspect ratio) | `crop.py input.mp4 --x 100 --y 0 --width 1080 --height 1920` |
+| "are there black bars on this?", "what's the crop rectangle to remove the letterboxing" | `cropdetect.py input.mp4` |
+| "this old footage is interlaced / combed on motion" | `deinterlace.py input.mp4` |
+| "this footage is grainy/noisy, clean it up" | `denoise.py input.mp4 --strength medium` |
+| "blur/pixelate this face/plate/region" (known x/y/width/height) | `redact.py input.mp4 --x 820 --y 140 --width 240 --height 240 --mode pixelate` |
| "pull a flat clip out of this 360/spherical video, looking this way" (known yaw/pitch/fov, not "find the interesting part") | `sphere.py insta360.mp4 --yaw 90 --pitch 0 --h-fov 100 --v-fov 70` |
+| "the horizon is tilted, straighten this out" (known degrees, not "auto-level") | `straighten.py tilted.mp4 --degrees -2.5` |
| "turn this image into a N-second clip", "title card / end slate" | `insert.py title.png --duration 3` |
| "slow zoom on a photo", "Ken Burns effect" | `insert.py photo.jpg --duration 6 --zoom in --pan right --width 1920 --height 1080` |
| "rotate this 90 degrees", "mirror it horizontally" | `fit.py input.mp4 --rotate 90` / `fit.py input.mp4 --flip h` |
@@ -139,6 +144,11 @@ If a request needs an FFmpeg feature none of the 28 scripts expose, say so and n
| "stabilize this shaky footage" | `stabilize.py input.mp4` |
| "make a blank/colour background clip" | `background.py -o bg.mp4 --duration 3 --width 1920 --height 1080 --color 0x101010` |
| "turn these numbered frames into a video" | `sequence.py --dir frames --pattern "frame_%04d.png" --fps 24` |
+| "make a waveform/spectrum video for this podcast/track" | `waveform.py podcast.wav -o waveform.mp4` |
+| "hold on this frame for a couple seconds", "freeze the last frame" | `freeze.py clip.mp4 --hold 2` |
+| "add some black at the start before the title card" | `pad.py clip.mp4 --start 1.5` |
+| "speed up here, slam into slow-mo there, then speed back up" (known segments) | `speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0` |
+| "loop this background clip to fill 30 seconds" | `loop.py bg_loop.mp4 --duration 30` |
| "add subtitles from this SRT", "burn in captions" | `caption.py input.mp4 --srt subs.srt` |
| "caption it with these lines" (plain text with times) | `caption.py input.mp4 --text cues.txt` |
| "add subtitles but keep them toggleable / editable", "mux in an SRT, don't burn it" | `caption.py input.mp4 --srt subs.srt --mode mux` |
diff --git a/docs/contract.md b/docs/contract.md
index b12df42..05d28b3 100644
--- a/docs/contract.md
+++ b/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 (`0.13.0`) | any release |
+| `skill.version` | the npm / package.json version (`0.15.0`) | 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`
@@ -39,7 +39,7 @@ drifting silently.
```json
{
"contract_version": "1.0",
- "skill": {"id": "ffmpeg-skill", "version": "0.13.0", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.15.0", "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"},
@@ -129,7 +129,7 @@ gives you:
## `provides`
-`provides` lists these 29 tools by a cross-repository Capability id, for
+`provides` lists these 39 tools by a cross-repository Capability id, for
`kajisho5/AI-video-production-OS`'s `CapabilityContract.provides`
(`docs/SPEC.md` there), matching the ids already assigned to this Skill in
that project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill's
diff --git a/package.json b/package.json
index a62f633..91d0bb3 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
{
"name": "ffmpeg-skill",
- "version": "0.13.0",
- "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 29 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.",
+ "version": "0.15.0",
+ "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 39 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",
"video",
diff --git a/references/scripts.md b/references/scripts.md
index c8cc14c..9dd6a3e 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -86,6 +86,57 @@ lie entirely inside the source frame (after accounting for display rotation);
`--width`/`--height` must be even (4:2:0 chroma) and are refused, never
rounded, if they aren't.
+### cropdetect.py — measure black bars, report the crop rectangle
+```
+cropdetect.py INPUT [--seconds N] [--samples N] [--limit F] [--round N]
+```
+Measurement only -- writes no file. Samples `--samples` windows spread
+across the file (default 5, totalling `--seconds` 10s of footage) and
+reports the crop rectangle FFmpeg's `cropdetect` filter found most often, as
+`{x, y, width, height}` ready to hand to `crop.py`. Distinct from
+`fit.py --fit crop`, which crops to a target aspect ratio it computes
+itself with no black-bar measurement involved. A rectangle that matches the
+full source frame means no bars were found. Does not decide whether
+removing detected bars is wanted -- genuine letterboxed content (a
+scope-ratio film in a 16:9 frame) "detects" the same way as accidental
+bars; look at the frame before cropping it away.
+
+### deinterlace.py — deinterlace interlaced footage
+```
+deinterlace.py INPUT [--mode frame|field] [--parity auto|tff|bff] [--only-interlaced] [-o OUT]
+```
+Wraps FFmpeg's `yadif` filter. `--mode frame` (default) keeps the source
+frame rate; `--mode field` emits one frame per field, doubling the output
+frame rate. `--parity` overrides field order when the container gets it
+wrong; `--only-interlaced` skips frames the source doesn't itself mark
+interlaced. Does not detect whether the source needs deinterlacing --
+that's a `look.py` judgement call (visible combing on motion).
+
+### denoise.py — reduce video noise/grain
+```
+denoise.py INPUT [--strength low|medium|high] [--luma-spatial F] [--chroma-spatial F]
+ [--luma-temporal F] [--chroma-temporal F] [-o OUT]
+```
+Wraps FFmpeg's `hqdn3d` filter. `--strength` picks a tested preset scaling
+all four of hqdn3d's spatial/temporal luma/chroma parameters together; the
+four `--luma-*`/`--chroma-*` flags override any of them individually.
+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 INPUT --x X --y Y --width W --height H [--mode blur|pixelate]
+ [--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.
+
### sphere.py — flat viewport extraction from 360/spherical video
```
sphere.py INPUT [--input-projection equirect|fisheye|dfisheye|c3x2|c6x1|barrel|cylindrical|hequirect]
@@ -105,6 +156,19 @@ tracking here: only the typed aim you give it. For a shot that follows a
moving subject, call this once per keyframe viewpoint from outside this
tool. `--width`/`--height` must be even (4:2:0 chroma); default 1920x1080.
+### straighten.py — rotate by an arbitrary angle (horizon correction)
+```
+straighten.py INPUT --degrees D [--fit crop|pad] [--fill-color C] [-o OUT]
+```
+Distinct from `fit.py --rotate`, which only turns the picture in exact
+90-degree steps -- this wraps FFmpeg's `rotate` filter for a small
+corrective tilt (`--degrees`, -45..45). Rotating by a non-90-degree angle
+leaves triangular gaps at the corners: `--fit crop` (default) scales up
+just enough to fill the frame with no visible gap, losing a thin border of
+the original picture; `--fit pad` keeps the full original picture and fills
+the gaps with `--fill-color`. Does not measure the tilt itself -- give the
+degrees once you can see how far off it is (a `look.py` judgement call).
+
### insert.py — still image to a timed silent clip
```
insert.py IMAGE --duration T [--width W] [--height H] [--fps N]
@@ -159,6 +223,66 @@ Turns a numbered or glob-matched set of still images into a video. The match
is checked on disk before ffmpeg runs (an empty match or a missing first
frame is refused here, not discovered from an opaque ffmpeg error).
+### waveform.py — audio waveform/spectrum visualization video
+```
+waveform.py INPUT [--style waveform|spectrum] [--width W] [--height H] [--fps N]
+ [--color C] [--background C] [--waveform-mode M] [--split-channels] [-o OUT]
+```
+Renders the input's audio as a video: `--style waveform` (default, FFmpeg's
+`showwaves`) draws amplitude over time; `--style spectrum` (`showspectrum`)
+draws a frequency-over-time heatmap instead, reading more out of dense
+mixes at the cost of being less immediately readable. The output always
+carries the audio it visualizes. For an audio-only input (no video stream
+needed) or any file with an audio track worth visualizing.
+
+### freeze.py — hold a frame for N seconds
+```
+freeze.py INPUT --hold T [--at T] [--mode insert|extend] [-o OUT]
+```
+`--at` (default: the last frame) is the timestamp to freeze; `--hold` is
+how long the freeze lasts. `--mode insert` (default) inserts the hold at
+`--at`, pushing everything after it later by `--hold` seconds. `--mode
+extend` only works with `--at` at (or past) the clip's end and just makes
+the last frame last `--hold` seconds longer, with nothing pushed. Audio is
+silent during the held frame in `--mode insert` (there is no source audio
+for a frozen moment that didn't exist before).
+
+### pad.py — add black/silent padding at the start/end
+```
+pad.py INPUT [--start T] [--end T] [--color C] [-o OUT]
+```
+Distinct from `fit.py --fit pad`, which pads the *frame* (letterbox/
+pillarbox bars around each existing frame) -- this pads the *timeline*:
+extra seconds of solid colour and silence before and/or after the clip's
+existing content. At least one of `--start`/`--end` must be > 0.
+
+### speedramp.py — step through different speeds across a clip
+```
+speedramp.py INPUT --segment START-END:FACTOR [--segment ...] [-o OUT]
+```
+Distinct from `fit.py --duration --method speed`, which applies one
+constant factor to the whole clip -- this takes a list of `--segment`
+pieces (repeatable) covering the clip start to end with no gaps or
+overlaps, each played at its own constant speed (pitch-preserving audio,
+matching `fit.py`), then concatenates them: "speed up, then slow way down
+for the punch, then speed back up," built from a few constant segments
+rather than a continuous curve. `FACTOR` is 0.05..20 (2.0 = twice as fast,
+0.5 = half speed). Picking exactly where a ramp should ease in or out is a
+judgement call for the calling agent, made concrete here as the segment
+boundaries it supplies.
+
+### loop.py — repeat a clip
+```
+loop.py INPUT --times N | --duration T [-o OUT]
+```
+`--times` repeats the whole clip that many times back to back (2 =
+original + 1 repeat). `--duration` instead loops (and trims the last
+repeat) to hit an exact target length. For a background loop, an ambient
+bed, or filling a fixed slot length with a short clip. Does not smooth the
+loop point (no crossfade at the seam) -- a clip that doesn't already loop
+cleanly will show a visible cut/pop at each repeat, which is a property of
+the source material this tool cannot fix.
+
### silence.py — remove dead air / jump cuts
```
silence.py INPUT [--threshold -35] [--min-silence 0.6] [--margin 0.15] [--min-keep 0.2] [--list] [--edl keep.txt] [-o OUT]
diff --git a/scripts/_contract.py b/scripts/_contract.py
index 1fce2a0..39a4e57 100644
--- a/scripts/_contract.py
+++ b/scripts/_contract.py
@@ -79,9 +79,39 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
"crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
required=FF + [X264, AAC], optional=[HDR_X265],
video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "deinterlace": dict(role="execution", inputs=["video asset"], outputs=["deinterlaced (progressive) video artifact"],
+ required=FF + [X264, AAC, "filter:yadif"], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "denoise": dict(role="execution", inputs=["video asset"], outputs=["denoised video artifact"],
+ required=FF + [X264, AAC, "filter:hqdn3d"], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "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],
+ 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"}],
+ video_required=False, audio_only=True, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
"sphere": dict(role="execution", inputs=["360/spherical video asset"], outputs=["flat rectilinear video artifact of the chosen viewport"],
required=FF + [X264, AAC, "filter:v360"], optional=[HDR_X265],
video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "straighten": dict(role="execution", inputs=["video asset"], outputs=["video artifact rotated by the given angle (horizon correction)"],
+ required=FF + [X264, AAC, "filter:rotate"], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "freeze": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a frame held for the given duration"],
+ required=FF + [X264, AAC, "filter:tpad"], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "pad": dict(role="execution", inputs=["video asset"], outputs=["video artifact with black/silent padding added at the start/end"],
+ required=FF + [X264, AAC, "filter:tpad"], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "speedramp": dict(role="execution", inputs=["video asset"], outputs=["video artifact with a stepped speed ramp applied across segments"],
+ required=FF + [X264, AAC], optional=[HDR_X265],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
+ "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration"],
+ required=FF + [X264, AAC], optional=[],
+ video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
"insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
@@ -192,7 +222,17 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
"cut": dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),
"fit": dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),
"crop": dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),
+ "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"),
+ "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"),
+ "freeze": dict(video="always", audio="always", note="the tpad/concat filter graph always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+ "pad": dict(video="always", audio="always", note="the tpad filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
+ "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
+ "loop": dict(video="always", audio="always", note="-stream_loop always re-encodes both streams; the audio codec is always AAC when present"),
"insert": dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
"background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
"reverse": dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
diff --git a/scripts/cropdetect.py b/scripts/cropdetect.py
new file mode 100644
index 0000000..3d9c566
--- /dev/null
+++ b/scripts/cropdetect.py
@@ -0,0 +1,106 @@
+#!/usr/bin/env python3
+"""Measure black letterbox/pillarbox bars and report the crop rectangle that removes them.
+
+Wraps FFmpeg's cropdetect filter: it samples frames, finds the largest
+non-black rectangle common to (recent) frames, and reports it. This is a
+measurement only -- it writes no file. Feed the reported {x, y, width,
+height} to crop.py to actually remove the bars:
+
+ python3 cropdetect.py input.mp4
+ python3 crop.py input.mp4 --x 0 --y 140 --width 1920 --height 800
+
+Distinct from fit.py --fit crop, which crops to a *target aspect ratio* it
+computes itself (no black-bar detection involved) -- this tool instead
+measures bars that are already baked into the source picture and tells you
+where they are; it does not decide whether removing them is wanted (a
+source with genuine letterboxed content, e.g. a scope-ratio film in a 16:9
+frame, will "detect" that letterboxing as bars to strip, which is correct
+for restoring the original frame but wrong if the letterboxing is part of
+the intended presentation -- look at the frame before cropping it away).
+
+--seconds controls how much of the file is sampled (default 10s, spread
+across the file by --samples windows so a single black scene near the start
+doesn't skew the result). Detected values fluctuate slightly frame to frame
+even on a static border; the reported rectangle is the most common one seen.
+
+Examples:
+ python3 cropdetect.py input.mp4
+ python3 cropdetect.py input.mp4 --seconds 30 --limit 0.15
+"""
+import argparse
+import re
+import subprocess
+import sys
+from collections import Counter
+from typing import Dict, List, Tuple
+
+from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool
+
+CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
+
+
+def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float) -> List[Tuple[int, int, int, int]]:
+ ffmpeg = require_tool("ffmpeg")
+ per_window = max(0.5, seconds / max(1, samples))
+ rects: List[Tuple[int, int, int, int]] = []
+ for i in range(samples):
+ start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
+ start = max(0.0, start)
+ cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
+ "-vf", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+ proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+ for m in CROP_RE.finditer(proc.stderr):
+ rects.append((int(m.group(1)), int(m.group(2)), int(m.group(3)), int(m.group(4))))
+ return rects
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("--seconds", type=float, default=10.0, help="total seconds of footage to sample across the file (default 10)")
+ ap.add_argument("--samples", type=int, default=5, help="number of windows spread across the file (default 5)")
+ ap.add_argument("--limit", type=float, default=0.0941176, help="black-pixel threshold, 0..1 (default ~0.094, cropdetect's own default)")
+ ap.add_argument("--round", type=int, default=16, dest="round_to", help="the reported width/height are rounded to a multiple of this (default 16)")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if args.seconds <= 0:
+ die(f"--seconds must be > 0, got {args.seconds:g}")
+ if args.samples <= 0:
+ die(f"--samples must be > 0, got {args.samples}")
+ if not 0 <= args.limit <= 1:
+ die(f"--limit must be 0..1, got {args.limit:g}")
+ if args.round_to <= 0:
+ die(f"--round must be > 0, got {args.round_to}")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ sw, sh = meta["video"]["width"], meta["video"]["height"]
+ duration = meta.get("duration") or 0.0
+
+ rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration)
+ result: Dict = {"file": args.input, "source_width": sw, "source_height": sh}
+ if not rects:
+ result["crop"] = None
+ info("no crop bars detected (cropdetect produced no readings -- try --limit higher, or the source may already be full-frame)")
+ else:
+ w, h, x, y = Counter(rects).most_common(1)[0][0]
+ result["crop"] = {"width": w, "height": h, "x": x, "y": y}
+ result["confidence"] = round(Counter(rects).most_common(1)[0][1] / len(rects), 3)
+ if (w, h) == (sw, sh):
+ info(f"no bars detected: full {sw}x{sh} frame is already content")
+ else:
+ info(f"detected crop={w}:{h}:{x}:{y} (source {sw}x{sh}, confidence {result['confidence']:.0%}) -- "
+ f"crop.py {args.input} --x {x} --y {y} --width {w} --height {h}")
+
+ if args.json:
+ emit(None, **result)
+ else:
+ print_json(result)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/deinterlace.py b/scripts/deinterlace.py
new file mode 100644
index 0000000..812547b
--- /dev/null
+++ b/scripts/deinterlace.py
@@ -0,0 +1,85 @@
+#!/usr/bin/env python3
+"""Deinterlace interlaced source footage (old broadcast masters, DV, some camcorders).
+
+Wraps FFmpeg's yadif filter. --mode frame (default) keeps the original frame
+rate, blending each pair of fields back into one frame; --mode field instead
+emits one frame per field, doubling the frame rate (smoother motion, the
+usual choice for footage that will be watched at full quality). --parity
+tells yadif which field came first when the container doesn't say so
+correctly; --only-interlaced skips frames the source itself doesn't mark as
+interlaced, leaving already-progressive frames untouched.
+
+This tool does not detect whether the source needs deinterlacing at all --
+that's a probe.py/look.py judgement (visible combing on motion in a contact
+sheet). Running yadif on already-progressive footage is a harmless no-op in
+practice but still re-encodes the whole file, so don't run this by default.
+
+Examples:
+ python3 deinterlace.py old_tape.mov
+ python3 deinterlace.py broadcast.mxf --mode field --parity tff
+ python3 deinterlace.py mixed.mov --only-interlaced
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+MODES = {"frame": 0, "field": 1}
+PARITIES = {"auto": -1, "tff": 0, "bff": 1}
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_deint.<ext>)")
+ ap.add_argument("--mode", choices=list(MODES), default="frame",
+ help="frame (default): one output frame per input frame; field: one output frame per field, doubling fps")
+ ap.add_argument("--parity", choices=list(PARITIES), default="auto",
+ help="which field came first (default auto-detect from the stream)")
+ ap.add_argument("--only-interlaced", action="store_true",
+ help="only deinterlace frames the source marks as interlaced; leave the rest untouched")
+ ap.add_argument("--audio-stream", type=int, default=0,
+ help="which audio stream of the input to keep, 0-based in file order (default 0)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ 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)):
+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+ if args.audio_stream and not audio_streams:
+ die("--audio-stream needs an input with audio streams")
+ output = args.output or default_output(args.input, "deint")
+
+ vf = f"yadif=mode={MODES[args.mode]}:parity={PARITIES[args.parity]}:deint={1 if args.only_interlaced else 0}"
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+ if has_audio:
+ cmd += ["-map", f"0:a:{args.audio_stream}?"]
+ cmd += video_args(meta, args.crf, args.preset)
+ if args.mode == "field":
+ v = meta["video"]
+ src_fps = v.get("fps") or 30.0
+ cmd += ["-fps_mode", "cfr", "-r", f"{src_fps * 2:g}"]
+ else:
+ cmd += cfr_args(meta)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {v['fps']:g}fps, mode={args.mode})")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/denoise.py b/scripts/denoise.py
new file mode 100644
index 0000000..5e0537b
--- /dev/null
+++ b/scripts/denoise.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+"""Reduce video noise/grain with FFmpeg's hqdn3d filter.
+
+For audio noise reduction use audio.py --denoise instead -- this tool only
+touches the picture. --strength picks a tested preset (low/medium/high,
+scaling hqdn3d's four spatial/temporal luma/chroma parameters together);
+--luma-spatial/--chroma-spatial/--luma-temporal/--chroma-temporal override
+any of the four individually when a preset isn't precise enough. Heavier
+denoising trades away fine detail (skin texture, foliage, film grain) for a
+cleaner-looking but softer image -- there is no setting that removes noise
+"for free"; --strength high is a real quality trade-off, not just "better".
+
+Examples:
+ python3 denoise.py noisy_lowlight.mp4
+ python3 denoise.py grainy_scan.mov --strength high
+ python3 denoise.py source.mp4 --luma-spatial 6 --chroma-spatial 4 --luma-temporal 8 --chroma-temporal 6
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+# hqdn3d's own AVOptions default to 0 (off); these tested presets are the light/medium/heavy
+# starting points its own documentation and common usage recommend (spatial then temporal,
+# luma then chroma -- chroma tends to tolerate more smoothing before looking soft).
+STRENGTH_PRESETS = {
+ "low": (2.0, 1.5, 3.0, 2.25),
+ "medium": (4.0, 3.0, 6.0, 4.5),
+ "high": (8.0, 6.0, 10.0, 7.5),
+}
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_denoise.<ext>)")
+ ap.add_argument("--strength", choices=list(STRENGTH_PRESETS), default="medium",
+ help="preset denoising amount (default medium); overridden per-parameter by the flags below")
+ ap.add_argument("--luma-spatial", type=float, help="spatial luma denoising strength (default from --strength)")
+ ap.add_argument("--chroma-spatial", type=float, help="spatial chroma denoising strength (default from --strength)")
+ ap.add_argument("--luma-temporal", type=float, help="temporal luma denoising strength (default from --strength)")
+ ap.add_argument("--chroma-temporal", type=float, help="temporal chroma denoising strength (default from --strength)")
+ ap.add_argument("--audio-stream", type=int, default=0,
+ help="which audio stream of the input to keep, 0-based in file order (default 0)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ ls, cs, lt, ct = STRENGTH_PRESETS[args.strength]
+ ls = args.luma_spatial if args.luma_spatial is not None else ls
+ cs = args.chroma_spatial if args.chroma_spatial is not None else cs
+ lt = args.luma_temporal if args.luma_temporal is not None else lt
+ ct = args.chroma_temporal if args.chroma_temporal is not None else ct
+ for name, val in (("--luma-spatial", ls), ("--chroma-spatial", cs), ("--luma-temporal", lt), ("--chroma-temporal", ct)):
+ if val < 0:
+ die(f"{name} must be >= 0, got {val:g}")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ 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)):
+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+ if args.audio_stream and not audio_streams:
+ die("--audio-stream needs an input with audio streams")
+ output = args.output or default_output(args.input, "denoise")
+
+ vf = f"hqdn3d={ls:g}:{cs:g}:{lt:g}:{ct:g}"
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+ if has_audio:
+ cmd += ["-map", f"0:a:{args.audio_stream}?"]
+ cmd += video_args(meta, args.crf, args.preset)
+ cmd += cfr_args(meta, args.fps)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, strength={args.strength})")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/freeze.py b/scripts/freeze.py
new file mode 100644
index 0000000..1f1b26c
--- /dev/null
+++ b/scripts/freeze.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Freeze on one frame for a number of seconds -- an end-card hold, a comedic beat, a pause.
+
+--at is the timestamp to freeze (default: the last frame). --hold is how
+long the freeze lasts. --mode insert (default) inserts the hold into the
+clip at --at, pushing everything after it later by --hold seconds; --mode
+extend only works with --at at (or past) the end of the clip and simply
+makes the last frame last --hold seconds longer, without touching anything
+earlier. Audio is silent during the held frame in --mode insert (there is
+no source audio for a frozen moment that didn't exist before); --mode
+extend has no audio to extend either, since it only makes sense at the
+clip's end.
+
+Examples:
+ python3 freeze.py interview.mp4 --hold 2 # hold the last frame 2s longer
+ python3 freeze.py sketch.mp4 --at 12.5 --hold 1.5 # 1.5s freeze inserted at 12.5s
+ python3 freeze.py outro.mp4 --hold 3 --mode extend # extend only the very end by 3s
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_freeze.<ext>)")
+ ap.add_argument("--at", type=float, help="timestamp to freeze, in seconds (default: the last frame)")
+ ap.add_argument("--hold", type=float, required=True, help="how long the freeze lasts, in seconds")
+ ap.add_argument("--mode", choices=["insert", "extend"], default="insert",
+ help="insert (default): hold pushes the rest of the clip later; extend: only valid at/after the clip's end, makes the last frame last longer with nothing pushed")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if args.hold <= 0:
+ die(f"--hold must be > 0, got {args.hold:g}")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ dur = meta.get("duration") or 0.0
+ fps = meta["video"].get("fps") or 30.0
+ at = args.at if args.at is not None else dur
+ if at < 0 or at > dur:
+ die(f"--at {at:g} is outside the clip (0..{dur:.3f})")
+ if args.mode == "extend" and at < dur - 0.01:
+ die(f"--mode extend needs --at at or after the clip's end ({dur:.3f}), got {at:g}")
+ has_audio = bool(meta.get("audio"))
+ output = args.output or default_output(args.input, "freeze")
+
+ if args.mode == "extend":
+ # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
+ # needed since it only ever appends past the real end.
+ vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+ if has_audio:
+ cmd += ["-map", "0:a:0?", "-af", f"apad=pad_dur={args.hold:.3f}"]
+ else:
+ # freeze N frames at `at` by holding on that one source frame for --hold seconds, then
+ # resuming the rest of the clip: split the timeline at `at`, freeze-frame the first
+ # part's last frame for --hold seconds via tpad, concat with the remainder.
+ n = max(1, round(args.hold * fps))
+ vf = (f"[0:v]split[a][b];[a]trim=end={at:.3f},setpts=PTS-STARTPTS[head];"
+ f"[b]trim=start={at:.3f},setpts=PTS-STARTPTS[tail];"
+ f"[head]tpad=stop_mode=clone:stop={n}[frozen];"
+ f"[frozen][tail]concat=n=2:v=1:a=0[outv]")
+ cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
+ if has_audio:
+ af = (f"[0:a]asplit[aa][ab];[aa]atrim=end={at:.3f},asetpts=PTS-STARTPTS[ahead];"
+ f"[ab]atrim=start={at:.3f},asetpts=PTS-STARTPTS[atail];"
+ f"[ahead]apad=pad_dur={args.hold:.3f}[afrozen];"
+ f"[afrozen][atail]concat=n=2:v=0:a=1[outa]")
+ cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", f"{vf};{af}", "-map", "[outv]", "-map", "[outa]"]
+ cmd += video_args(meta, args.crf, args.preset)
+ cmd += cfr_args(meta)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, froze {args.hold:g}s at {at:g}s, mode={args.mode})")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/loop.py b/scripts/loop.py
new file mode 100644
index 0000000..0d7127e
--- /dev/null
+++ b/scripts/loop.py
@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""Loop a clip a number of times, or to a target duration.
+
+For a background loop, an ambient bed, or filling a fixed slot length with
+a short clip. --times repeats the whole clip that many times back to back;
+--duration instead loops (and, on the last repeat, trims) to hit an exact
+target length. Audio loops along with the video when present. This tool
+does not smooth the loop point (no crossfade at the seam) -- a clip that
+doesn't already loop cleanly will show a visible cut/pop at each repeat;
+that's a judgement call about the source material, not something a --times
+or --duration flag can fix.
+
+Examples:
+ python3 loop.py bg_loop.mp4 --times 3
+ python3 loop.py texture.mp4 --duration 30
+"""
+import argparse
+import math
+import sys
+
+from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, parse_time, probe, run
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_loop.<ext>)")
+ group = ap.add_mutually_exclusive_group(required=True)
+ group.add_argument("--times", type=int, help="repeat the whole clip this many times (2 = original + 1 repeat)")
+ group.add_argument("--duration", help="loop (and trim the last repeat) to hit exactly this target duration (seconds or mm:ss)")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ src_dur = meta.get("duration") or 0.0
+ if src_dur <= 0:
+ die("input has no measurable duration to loop")
+ has_audio = bool(meta.get("audio"))
+ output = args.output or default_output(args.input, "loop")
+
+ if args.times is not None:
+ if args.times < 2:
+ die(f"--times must be >= 2 (1 is just the original clip), got {args.times}")
+ target = None
+ stream_loop = args.times - 1
+ else:
+ target = parse_time(args.duration)
+ if target <= src_dur:
+ die(f"--duration ({target:g}s) must be longer than the source ({src_dur:.3f}s) -- use cut.py to trim instead")
+ stream_loop = math.ceil(target / src_dur) - 1
+
+ # -stream_loop repeats the whole input read (video and audio together) at the demuxer level
+ # -- exact and lossless-in-intent for a re-encode target, unlike a filter-graph loop that
+ # would need separate video/audio filters kept in lockstep by hand.
+ cmd = ffmpeg_base() + ["-stream_loop", str(stream_loop), "-i", args.input]
+ if target is not None:
+ cmd += ["-t", f"{target:.3f}"]
+ cmd += ["-c:v", "libx264", "-preset", "medium", "-crf", "18", "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+ if has_audio:
+ cmd += ["-c:a", "aac", "-b:a", "192k"]
+ else:
+ cmd += ["-an"]
+ cmd.append(output)
+ run(cmd)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, source {src_dur:.3f}s looped)")
+ emit(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/pad.py b/scripts/pad.py
new file mode 100644
index 0000000..2d4e536
--- /dev/null
+++ b/scripts/pad.py
@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Add black video / silent audio at the start and/or end of a clip.
+
+Distinct from fit.py --fit pad, which pads the FRAME (letterbox/pillarbox
+bars around each existing frame to reach a target aspect ratio) -- this
+tool pads the TIMELINE (extra seconds of solid colour and silence before
+and/or after the clip's existing content). Common uses: a beat of black
+before a title card starts, room for a fade-in, aligning a clip to a fixed
+slot length.
+
+Examples:
+ python3 pad.py clip.mp4 --start 1.5 # 1.5s of black+silence before the clip
+ python3 pad.py clip.mp4 --end 2 # 2s of black+silence after the clip
+ python3 pad.py clip.mp4 --start 1 --end 1 --color 0x101010
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_pad.<ext>)")
+ ap.add_argument("--start", type=float, default=0.0, help="seconds of padding to add before the clip (default 0)")
+ ap.add_argument("--end", type=float, default=0.0, help="seconds of padding to add after the clip (default 0)")
+ ap.add_argument("--color", default="black", help="padding colour (default black)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if args.start < 0 or args.end < 0:
+ die(f"--start/--end must be >= 0, got start={args.start:g} end={args.end:g}")
+ if args.start == 0 and args.end == 0:
+ die("--start and/or --end must be > 0 (nothing to pad)")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ has_audio = bool(meta.get("audio"))
+ output = args.output or default_output(args.input, "pad")
+
+ vf = f"tpad=start_duration={args.start:.3f}:stop_duration={args.end:.3f}:color={args.color}"
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
+ if has_audio:
+ af = f"adelay={int(args.start * 1000)}:all=1,apad=pad_dur={args.end:.3f}"
+ cmd += ["-map", "0:a:0?", "-af", af]
+ cmd += video_args(meta, args.crf, args.preset)
+ cmd += cfr_args(meta)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, +{args.start:g}s start / +{args.end:g}s end)")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/redact.py b/scripts/redact.py
new file mode 100644
index 0000000..9e1b8c6
--- /dev/null
+++ b/scripts/redact.py
@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""Blur or pixelate an exact pixel rectangle for the whole clip (privacy redaction, license plates, faces).
+
+{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.
+
+--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.
+
+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
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_redact.<ext>)")
+ ap.add_argument("--x", type=int, required=True, help="left edge of the rectangle, in source pixels")
+ 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("--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,
+ help="which audio stream of the input to keep, 0-based in file order (default 0)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if args.x < 0 or args.y < 0:
+ die(f"--x/--y must be >= 0, got x={args.x} y={args.y}")
+ if args.width <= 0 or args.height <= 0:
+ die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+ if args.width % 2 or args.height % 2:
+ die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+ if args.blur_strength <= 0:
+ die(f"--blur-strength must be > 0, got {args.blur_strength}")
+ if args.block_size <= 1:
+ die(f"--block-size must be > 1, got {args.block_size}")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ sw, sh = meta["video"]["width"], meta["video"]["height"]
+ if meta["video"].get("rotation") in (90, -90, 270, -270):
+ 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})")
+ 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)):
+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+ if args.audio_stream and not audio_streams:
+ 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":
+ region = f"{crop},boxblur={args.blur_strength}:{args.blur_strength}"
+ 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)
+ cmd += cfr_args(meta, args.fps)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {args.mode} at x={args.x} y={args.y} {args.width}x{args.height})")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/speedramp.py b/scripts/speedramp.py
new file mode 100644
index 0000000..63367a4
--- /dev/null
+++ b/scripts/speedramp.py
@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""Step through different constant speeds across a clip's timeline (a speed ramp).
+
+Distinct from fit.py --duration --method speed, which applies one constant
+factor to the whole clip. This tool takes a list of --segment START-END:FACTOR
+pieces covering the clip start to end with no gaps or overlaps, each played
+at its own constant speed (pitch-preserving audio, matching fit.py), then
+concatenates them back together -- the classic "speed up, then slow way
+down for the punch, then speed back up" edit, built from a few constant
+segments rather than a continuous curve (which this tool does not attempt:
+picking exactly where a ramp should ease in or out is a judgement call for
+the calling agent, made concrete here as segment boundaries it supplies).
+
+Examples:
+ python3 speedramp.py action.mp4 --segment 0-3:1.0 --segment 3-4:0.25 --segment 4-8:2.0
+ python3 speedramp.py clip.mp4 --segment 0-2:2.0 --segment 2-6:1.0
+"""
+import argparse
+import sys
+from typing import List, Tuple
+
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run, video_args
+
+MAX_SPEED = 20.0
+MIN_SPEED = 0.05
+
+
+def atempo_chain(factor: float) -> str:
+ """atempo accepts 0.5..100 per instance; chain for factors outside that range."""
+ parts: List[str] = []
+ remaining = factor
+ while remaining < 0.5:
+ parts.append("atempo=0.5")
+ remaining /= 0.5
+ while remaining > 100.0:
+ parts.append("atempo=100.0")
+ remaining /= 100.0
+ parts.append(f"atempo={remaining:.6f}")
+ return ",".join(parts)
+
+
+def parse_segment(raw: str) -> Tuple[float, float, float]:
+ try:
+ span, factor_s = raw.split(":")
+ start_s, end_s = span.split("-")
+ start, end, factor = float(start_s), float(end_s), float(factor_s)
+ except ValueError:
+ die(f"--segment must look like START-END:FACTOR, got '{raw}'")
+ if end <= start:
+ die(f"--segment {raw}: END must be after START")
+ if not MIN_SPEED <= factor <= MAX_SPEED:
+ die(f"--segment {raw}: FACTOR must be {MIN_SPEED}..{MAX_SPEED}")
+ return start, end, factor
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_ramp.<ext>)")
+ ap.add_argument("--segment", action="append", required=True, dest="segments",
+ help=f"START-END:FACTOR, repeatable; segments must cover 0..duration with no gaps or overlaps, in order. FACTOR is {MIN_SPEED}..{MAX_SPEED} (2.0 = twice as fast, 0.5 = half speed)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ segments = [parse_segment(s) for s in args.segments]
+ segments.sort(key=lambda s: s[0])
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ dur = meta.get("duration") or 0.0
+ if abs(segments[0][0] - 0.0) > 0.01:
+ die(f"segments must start at 0, first segment starts at {segments[0][0]:g}")
+ if abs(segments[-1][1] - dur) > 0.5:
+ die(f"segments must cover the whole clip (0..{dur:.3f}), last segment ends at {segments[-1][1]:g}")
+ for i in range(len(segments) - 1):
+ if abs(segments[i][1] - segments[i + 1][0]) > 0.01:
+ die(f"segments must be contiguous with no gap/overlap: segment {i} ends at {segments[i][1]:g}, "
+ f"segment {i + 1} starts at {segments[i + 1][0]:g}")
+ has_audio = bool(meta.get("audio"))
+ output = args.output or default_output(args.input, "ramp")
+
+ vparts, aparts, labels = [], [], []
+ 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
+ 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}]")
+ if has_audio:
+ atrim = f"atrim=start={start:.3f}" + (f":end={end_expr}" if end_expr else "")
+ aparts.append(f"[0:a]{atrim},asetpts=PTS-STARTPTS,{atempo_chain(factor)}[{alabel}]")
+
+ if has_audio:
+ concat_inputs = "".join(f"[v{i}][a{i}]" for i in range(len(segments)))
+ fc = ";".join(vparts + aparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=1[outv][outa]"
+ maps = ["-map", "[outv]", "-map", "[outa]"]
+ else:
+ concat_inputs = "".join(f"[v{i}]" for i in range(len(segments)))
+ fc = ";".join(vparts) + f";{concat_inputs}concat=n={len(segments)}:v=1:a=0[outv]"
+ maps = ["-map", "[outv]"]
+
+ cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", fc] + maps
+ cmd += video_args(meta, args.crf, args.preset)
+ cmd += ["-fps_mode", "cfr", "-r", f"{meta['video'].get('fps') or 30.0:g}"]
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ cmd.append(output)
+ run(cmd)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {len(segments)} speed segments)")
+ emit(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/straighten.py b/scripts/straighten.py
new file mode 100644
index 0000000..6eb5835
--- /dev/null
+++ b/scripts/straighten.py
@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Rotate a video by an arbitrary angle (horizon correction, not a 90/180/270 turn).
+
+Distinct from fit.py --rotate, which only turns the picture in exact 90-degree
+steps (swapping width/height, lossless in intent). This tool wraps FFmpeg's
+rotate filter for a small corrective tilt -- "the horizon is 2 degrees off" --
+which necessarily crops or pads the corners: rotating a rectangle by a
+non-90-degree angle leaves triangular gaps at the corners. --fit crop scales
+up just enough to fill the frame with no visible gap (losing a thin border
+of the original picture); --fit pad keeps the full original picture inside
+the rotated frame and fills the gaps with --fill-color.
+
+This tool does not measure the tilt itself -- it has no way to find a
+horizon line in a frame; that is a look.py/vision judgement call. Give the
+degrees once you can see how far off it is.
+
+Examples:
+ python3 straighten.py tilted.mp4 --degrees -2.5
+ python3 straighten.py handheld.mp4 --degrees 1.2 --fit pad --fill-color 0x101010
+"""
+import argparse
+import math
+import sys
+
+from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_straighten.<ext>)")
+ ap.add_argument("--degrees", type=float, required=True, help="rotation angle in degrees, -45..45, positive = clockwise")
+ ap.add_argument("--fit", choices=["crop", "pad"], default="crop",
+ help="crop (default): scale up to fill the frame, no visible corner gap; pad: keep the full picture, fill the corner gaps with --fill-color")
+ ap.add_argument("--fill-color", default="black", help="corner fill colour with --fit pad (default black)")
+ ap.add_argument("--audio-stream", type=int, default=0,
+ help="which audio stream of the input to keep, 0-based in file order (default 0)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ ap.add_argument("--fps", type=float, help="force a constant output frame rate (recommended for VFR sources)")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if not -45 <= args.degrees <= 45:
+ die(f"--degrees must be -45..45, got {args.degrees:g}")
+ if args.degrees == 0:
+ die("--degrees must be nonzero (nothing to straighten)")
+
+ meta = probe(args.input)
+ if not meta.get("video"):
+ die("input has no video stream")
+ 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)):
+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+ if args.audio_stream and not audio_streams:
+ die("--audio-stream needs an input with audio streams")
+ output = args.output or default_output(args.input, "straighten")
+
+ radians = math.radians(args.degrees)
+ if args.fit == "pad":
+ rotate = (f"rotate={radians:.8f}:fillcolor={args.fill_color}:"
+ f"ow=trunc(rotw({radians:.8f})/2)*2:oh=trunc(roth({radians:.8f})/2)*2")
+ else:
+ # Pre-scale the frame up by a safe, conservative factor (|cos|+|sin|, the exact growth
+ # factor for a square, over-generous for a rectangle) so the rotated content fully
+ # covers the original W:H window with no black corner, then rotate in place (canvas
+ # stays at the scaled size) and crop back down to the original W:H, centred.
+ s = abs(math.cos(radians)) + abs(math.sin(radians))
+ # crop dimensions must round down to even (4:2:0 chroma); trunc(.../2)*2 floors to the
+ # nearest even value instead of leaving an odd width/height that the encoder would refuse.
+ rotate = f"scale=iw*{s:.8f}:ih*{s:.8f},rotate={radians:.8f},crop=trunc(iw/{s:.8f}/2)*2:trunc(ih/{s:.8f}/2)*2"
+
+ cmd = ffmpeg_base() + ["-i", args.input, "-vf", rotate, "-map", "0:v:0"]
+ if has_audio:
+ cmd += ["-map", f"0:a:{args.audio_stream}?"]
+ cmd += video_args(meta, args.crf, args.preset)
+ cmd += cfr_args(meta, args.fps)
+ if has_audio:
+ cmd += aac_args()
+ else:
+ cmd += ["-an"]
+ dropped_streams = run_keeping_subtitles(cmd, output)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, degrees={args.degrees:g}, fit={args.fit})")
+ emit(output, dropped_non_av_streams=dropped_streams)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/waveform.py b/scripts/waveform.py
new file mode 100644
index 0000000..3ba6640
--- /dev/null
+++ b/scripts/waveform.py
@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Render an audio track as a waveform or spectrum visualization video.
+
+Wraps FFmpeg's showwaves (--style waveform, the default) or showspectrum
+(--style spectrum) source filter over the input's audio -- for a podcast
+episode, a music release, or any clip that has no picture worth showing.
+The rendered clip always carries the same audio it visualizes; the video is
+generated fresh, there is no source picture involved.
+
+--style waveform draws the amplitude over time; --style spectrum draws a
+frequency-over-time heatmap instead, which reads more information out of
+dense mixes at the cost of being less immediately readable to a general
+audience. Both accept --width/--height and --color; waveform additionally
+takes --waveform-mode (how each sample is drawn) and --split-channels
+(stereo drawn as two separate lanes instead of summed to one).
+
+Examples:
+ python3 waveform.py podcast.wav -o waveform.mp4
+ python3 waveform.py track.wav --style spectrum --width 1920 --height 1080 -o spectrum.mp4
+ python3 waveform.py interview.mp4 --split-channels --color cyan|magenta
+"""
+import argparse
+import sys
+
+from _common import add_common, apply_common, aac_args, default_output, die, emit, ffmpeg_base, info, probe, run
+
+WAVEFORM_MODES = ["point", "line", "p2p", "cline"]
+
+
+def main() -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("input")
+ ap.add_argument("-o", "--output", help="output file (default: <name>_waveform.<ext>)")
+ ap.add_argument("--style", choices=["waveform", "spectrum"], default="waveform", help="waveform (default) or spectrum visualization")
+ ap.add_argument("--width", type=int, default=1920, help="output width in px, must be even (default 1920)")
+ ap.add_argument("--height", type=int, default=1080, help="output height in px, must be even (default 1080)")
+ ap.add_argument("--fps", type=float, default=25.0, help="output frame rate (default 25)")
+ ap.add_argument("--color", default="lime", help="channel colour(s), pipe-separated per channel, e.g. 'lime' or 'cyan|magenta' (default lime)")
+ ap.add_argument("--background", default="black", help="background colour (default black)")
+ ap.add_argument("--waveform-mode", choices=WAVEFORM_MODES, default="line", help="--style waveform only: how each sample is drawn (default line)")
+ ap.add_argument("--split-channels", action="store_true", help="draw each channel in its own lane instead of summing to one")
+ ap.add_argument("--audio-stream", type=int, default=0,
+ help="which audio stream of the input to render, 0-based in file order (default 0)")
+ ap.add_argument("--crf", type=int, default=18, help="x264 CRF (default 18)")
+ ap.add_argument("--preset", default="medium", help="x264 preset")
+ add_common(ap)
+ args = ap.parse_args()
+ apply_common(args)
+
+ if args.width <= 0 or args.height <= 0:
+ die(f"--width/--height must be > 0, got width={args.width} height={args.height}")
+ if args.width % 2 or args.height % 2:
+ die(f"--width/--height must be even (4:2:0 chroma), got width={args.width} height={args.height}")
+ if args.fps <= 0:
+ die(f"--fps must be > 0, got {args.fps:g}")
+
+ meta = probe(args.input)
+ if not meta.get("audio"):
+ die("input has no audio stream")
+ audio_streams = meta.get("audio_streams") or []
+ if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
+ die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
+ output = args.output or default_output(args.input, "waveform")
+
+ if args.style == "waveform":
+ vf = (f"showwaves=s={args.width}x{args.height}:mode={args.waveform_mode}:rate={args.fps:g}:"
+ f"split_channels={1 if args.split_channels else 0}:colors={args.color}")
+ else:
+ vf = f"showspectrum=s={args.width}x{args.height}:mode={'separate' if args.split_channels else 'combined'}:fps={args.fps:g}"
+ # showwaves/showspectrum paint the visualization on a transparent-black canvas; composite
+ # it over an explicit solid background instead of assuming that canvas already matches
+ # --background.
+ vf = f"color=c={args.background}:s={args.width}x{args.height}:r={args.fps:g}[bg];[0:a]{vf}[vis];[bg][vis]overlay=format=auto"
+
+ cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", f"0:a:{args.audio_stream}"]
+ cmd += ["-c:v", "libx264", "-preset", args.preset, "-crf", str(args.crf), "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+ cmd += aac_args()
+ cmd += ["-shortest", output]
+ run(cmd)
+
+ result = probe(output, role="output")
+ v = result["video"]
+ info(f"wrote {output} ({result['duration']:.3f}s, {v['width']}x{v['height']}, {args.style})")
+ emit(output)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/tests/test_all.py b/tests/test_all.py
index e040293..1aa0f55 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -301,6 +301,73 @@ class FFmpegSkillTests(unittest.TestCase):
def test_crop_negative_offset_refused(self):
script("crop.py", self.src, "--x", "-5", "--y", "0", "--width", "100", "--height", "100", expect_fail=True)
+ # ---------------------------------------------------------------- cropdetect
+ def test_cropdetect_reports_a_black_bar_rectangle(self):
+ bars = OUT / "cropdetect_bars.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi",
+ "-i", "color=black:size=640x480:duration=2,drawbox=y=100:h=280:color=white@1:t=fill",
+ "-r", "10", "-pix_fmt", "yuv420p", bars)
+ proc = script("cropdetect.py", bars, "--seconds", "2", "--samples", "2", "--json")
+ result = json.loads(proc.stdout)
+ self.assertIsNotNone(result["crop"])
+ self.assertEqual(result["crop"]["width"], 640)
+ self.assertLess(result["crop"]["height"], 480)
+ self.assertGreater(result["crop"]["y"], 0)
+
+ def test_cropdetect_writes_no_file(self):
+ before = set(OUT.iterdir())
+ script("cropdetect.py", self.src, "--seconds", "1", "--samples", "1")
+ self.assertEqual(before, set(OUT.iterdir()))
+
+ def test_cropdetect_bad_seconds_refused(self):
+ script("cropdetect.py", self.src, "--seconds", "0", expect_fail=True)
+
+ # ---------------------------------------------------------------- deinterlace
+ def test_deinterlace_frame_mode_keeps_fps(self):
+ out = OUT / "deint1.mp4"
+ script("deinterlace.py", self.src, "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["video"]["fps"], 30.0, 0.5)
+ self.assertClose(m["duration"], 12.0, 0.3)
+ self.assertIsNotNone(m["audio"])
+
+ def test_deinterlace_field_mode_doubles_fps(self):
+ out = OUT / "deint2.mp4"
+ script("deinterlace.py", self.src, "--mode", "field", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["video"]["fps"], 60.0, 0.5)
+
+ # ---------------------------------------------------------------- denoise
+ def test_denoise_produces_valid_output(self):
+ out = OUT / "denoise1.mp4"
+ script("denoise.py", self.src, "--strength", "high", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+ self.assertClose(m["duration"], 12.0, 0.3)
+
+ def test_denoise_negative_override_refused(self):
+ script("denoise.py", self.src, "--luma-spatial", "-1", expect_fail=True)
+
+ # ---------------------------------------------------------------- redact
+ def test_redact_blur_keeps_frame_size(self):
+ out = OUT / "redact1.mp4"
+ script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+
+ def test_redact_pixelate_mode(self):
+ out = OUT / "redact2.mp4"
+ script("redact.py", self.src, "--x", "100", "--y", "50", "--width", "200", "--height", "100",
+ "--mode", "pixelate", "--block-size", "16", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (1280, 720))
+
+ def test_redact_out_of_bounds_refused(self):
+ script("redact.py", self.src, "--x", "1200", "--y", "0", "--width", "200", "--height", "200", expect_fail=True)
+
+ def test_redact_odd_dimensions_refused(self):
+ script("redact.py", self.src, "--x", "0", "--y", "0", "--width", "101", "--height", "100", expect_fail=True)
+
# ---------------------------------------------------------------- sphere
def test_sphere_extracts_a_flat_viewport(self):
out = OUT / "sphere1.mp4"
@@ -333,6 +400,102 @@ class FFmpegSkillTests(unittest.TestCase):
def test_sphere_audio_stream_out_of_range_refused(self):
script("sphere.py", self.src, "--audio-stream", "5", expect_fail=True)
+ # ---------------------------------------------------------------- straighten
+ def test_straighten_crop_fit_has_no_black_corner(self):
+ out = OUT / "straighten1.mp4"
+ script("straighten.py", self.src, "--degrees", "10", "--fit", "crop", "-o", out)
+ m = probe(str(out))
+ self.assertLess(m["video"]["width"], 1280)
+ self.assertLess(m["video"]["height"], 720)
+ self.assertEqual(m["video"]["width"] % 2, 0)
+ self.assertEqual(m["video"]["height"] % 2, 0)
+ frame = OUT / "straighten1_corner.raw"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", out, "-vf", "crop=8:8:0:0",
+ "-frames:v", "1", "-f", "rawvideo", "-pix_fmt", "rgb24", frame)
+ data = frame.read_bytes()
+ self.assertFalse(all(b == 0 for b in data), "top-left corner is pure black -- straighten left a visible gap")
+
+ def test_straighten_pad_fit_grows_the_frame(self):
+ out = OUT / "straighten2.mp4"
+ script("straighten.py", self.src, "--degrees", "-8", "--fit", "pad", "-o", out)
+ m = probe(str(out))
+ self.assertGreater(m["video"]["width"], 1280)
+ self.assertGreater(m["video"]["height"], 720)
+
+ def test_straighten_zero_degrees_refused(self):
+ script("straighten.py", self.src, "--degrees", "0", expect_fail=True)
+
+ def test_straighten_out_of_range_refused(self):
+ script("straighten.py", self.src, "--degrees", "60", expect_fail=True)
+
+ # ---------------------------------------------------------------- freeze
+ def test_freeze_insert_extends_duration(self):
+ out = OUT / "freeze1.mp4"
+ script("freeze.py", self.src, "--at", "5", "--hold", "1", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 13.0, 0.3)
+
+ def test_freeze_extend_mode_at_end(self):
+ out = OUT / "freeze2.mp4"
+ script("freeze.py", self.src, "--hold", "1.5", "--mode", "extend", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 13.5, 0.3)
+
+ def test_freeze_extend_mode_before_end_refused(self):
+ script("freeze.py", self.src, "--at", "2", "--hold", "1", "--mode", "extend", expect_fail=True)
+
+ def test_freeze_zero_hold_refused(self):
+ script("freeze.py", self.src, "--hold", "0", expect_fail=True)
+
+ # ---------------------------------------------------------------- pad
+ def test_pad_start_and_end_extend_duration(self):
+ out = OUT / "pad1.mp4"
+ script("pad.py", self.src, "--start", "1", "--end", "2", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 15.0, 0.3)
+
+ def test_pad_nothing_refused(self):
+ script("pad.py", self.src, expect_fail=True)
+
+ def test_pad_negative_refused(self):
+ script("pad.py", self.src, "--start", "-1", expect_fail=True)
+
+ # ---------------------------------------------------------------- speedramp
+ def test_speedramp_segments_change_overall_duration(self):
+ out = OUT / "ramp1.mp4"
+ script("speedramp.py", self.src, "--segment", "0-6:1.0", "--segment", "6-9:0.5", "--segment", "9-12:2.0", "-o", out)
+ m = probe(str(out))
+ # 6/1.0 + 3/0.5 + 3/2.0 = 6 + 6 + 1.5 = 13.5s
+ self.assertClose(m["duration"], 13.5, 0.5)
+
+ def test_speedramp_bad_segment_format_refused(self):
+ script("speedramp.py", self.src, "--segment", "not-a-segment", expect_fail=True)
+
+ def test_speedramp_gap_refused(self):
+ script("speedramp.py", self.src, "--segment", "0-5:1.0", "--segment", "6-12:1.0", expect_fail=True)
+
+ def test_speedramp_must_start_at_zero_refused(self):
+ script("speedramp.py", self.src, "--segment", "1-12:1.0", expect_fail=True)
+
+ # ---------------------------------------------------------------- loop
+ def test_loop_times_multiplies_duration(self):
+ out = OUT / "loop1.mp4"
+ script("loop.py", self.src, "--times", "3", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 36.0, 1.0)
+
+ def test_loop_duration_hits_exact_target(self):
+ out = OUT / "loop2.mp4"
+ script("loop.py", self.src, "--duration", "20", "-o", out)
+ m = probe(str(out))
+ self.assertClose(m["duration"], 20.0, 0.1)
+
+ def test_loop_times_too_small_refused(self):
+ script("loop.py", self.src, "--times", "1", expect_fail=True)
+
+ def test_loop_duration_shorter_than_source_refused(self):
+ script("loop.py", self.src, "--duration", "3", expect_fail=True)
+
# ---------------------------------------------------------------- insert
def test_insert_native_size_and_duration(self):
out = OUT / "insert1.mp4"
@@ -561,6 +724,36 @@ class FFmpegSkillTests(unittest.TestCase):
def test_sequence_missing_dir_refused(self):
script("sequence.py", "--dir", str(OUT / "does_not_exist"), "--pattern", "*.png", "--fps", "5", expect_fail=True)
+ # ---------------------------------------------------------------- waveform
+ def test_waveform_style_default(self):
+ out = OUT / "waveform1.mp4"
+ script("waveform.py", self.src, "--width", "640", "--height", "360", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+ self.assertIsNotNone(m["audio"])
+ self.assertClose(m["duration"], 12.0, 0.3)
+
+ def test_waveform_spectrum_style(self):
+ out = OUT / "waveform2.mp4"
+ script("waveform.py", self.src, "--style", "spectrum", "--width", "640", "--height", "360", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (640, 360))
+
+ def test_waveform_audio_only_input(self):
+ out = OUT / "waveform3.mp4"
+ script("waveform.py", self.mic, "--width", "480", "--height", "270", "-o", out)
+ m = probe(str(out))
+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (480, 270))
+
+ def test_waveform_no_audio_refused(self):
+ silent = OUT / "waveform_silent_src.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=size=320x240:rate=25",
+ "-t", "1", "-c:v", "libx264", "-preset", "veryfast", "-crf", "20", "-pix_fmt", "yuv420p", silent)
+ script("waveform.py", silent, expect_fail=True)
+
+ def test_waveform_odd_dimensions_refused(self):
+ script("waveform.py", self.src, "--width", "641", "--height", "360", expect_fail=True)
+
# ---------------------------------------------------------------- caption
def test_caption_text_to_srt_and_burn(self):
srt = OUT / "cues.srt"
diff --git a/tests/test_contract.py b/tests/test_contract.py
index 794d68e..f710629 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -484,10 +484,12 @@ class ContractTests(unittest.TestCase):
self.assertEqual(self.tools["cut"]["verification"]["tools"], ["ffmpeg-skill/probe"])
def test_visual_verification_metadata(self):
- picture = {"fit", "crop", "sphere", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy"}
- # join is the one picture tool that also accepts audio-only inputs (audio concat); look applies
- # to its video output only, which SKILL.md states next to "Look: not needed"
- both = {"join"}
+ picture = {"fit", "crop", "sphere", "insert", "background", "reverse", "stabilize", "sequence", "caption", "overlay", "graphics", "color", "join", "multicam", "render", "proxy",
+ "deinterlace", "denoise", "redact", "waveform", "straighten", "freeze", "pad", "speedramp", "loop"}
+ # join and waveform are the picture tools that also accept audio-only inputs (audio
+ # concat; audio-track visualization); look applies to their video output only, which
+ # SKILL.md states next to "Look: not needed"
+ both = {"join", "waveform"}
for t in self.contract["tools"]:
self.assertEqual(t["requires_visual_verification"], t["name"] in picture, t["name"])
if t["requires_visual_verification"]: