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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
Add 10 tools: cropdetect, deinterlace, denoise, redact, waveform, straighten, freeze, pad, speedramp, loop (#104)
Shogo Kajiyama6774ed04afda
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 videoNew tool wrapping FFmpeg's `v360` filter for the most common 360-video job: pointing a fixed,diff --git a/README.md b/README.mdindex 0513380..b90c782 100644--- a/README.md+++ b/README.md@@ -25,7 +25,7 @@ npx ffmpeg-skill-`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. Togeth1. **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. ForOn 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 detectiondiff --git a/SKILL.md b/SKILL.mdindex 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.mdindex 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 theToolSpec 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 inthat project's own `docs/CAPABILITY_MATRIX.md` section 9 ("ffmpeg-skill'sdiff --git a/package.json b/package.jsonindex 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.mdindex 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, neverrounded, 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 amoving subject, call this once per keyframe viewpoint from outside thistool. `--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 matchis checked on disk before ffmpeg runs (an empty match or a missing firstframe 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.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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)+# ---------------------------------------------------------------- spheredef 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)+# ---------------------------------------------------------------- insertdef 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)+# ---------------------------------------------------------------- captiondef test_caption_text_to_srt_and_burn(self):srt = OUT / "cues.srt"diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 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"]: