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
fit.py: add --crop-x/--crop-y anchor for aspect-ratio cropping (#25)
Shogo Kajiyama28559976423b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 69e0b19..c9fd107 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,7 @@## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color+- **`fit.py --crop-x` / `--crop-y`.** `--fit crop` always cropped from the centre, so reframing a wide shot to 9:16 could cut off a subject held to one side (a product, a person off-centre). `--crop-x`/`--crop-y` (0=left/top, 0.5=centre default, 1=right/bottom) pick which edge to keep instead; range-checked before ffmpeg runs. No change to the default (centre) behaviour.- **Filter file paths on Windows.** `subtitles=`, `ass=`, `lut3d=file=`, `fontfile=` and `fontsdir=` values are parsed twice by ffmpeg (graph, then filter options), so a drive letter needs two levels of colon escaping (`D\\\\:/x.srt`). 0.9.1 escaped once and every caption / LUT job on Windows failed with `Unable to parse "original_size" option value` or `Error parsing a filter description`. `escape_filter_path` now escapes for both passes; `;` is escaped too. Reproduced and tested on Linux with a directory literally named `D:` plus spaces and non-ASCII in the path.- **`overlay.py --image` length on FFmpeg 7+.** `-shortest` alone left up to 2 s of the looped still after the video ended (8.1 / 9.0); the command now also passes `-t <video duration>`.- **`--help` on a legacy Windows console.** stdout / stderr are reconfigured to UTF-8 (with replacement) by `_common`, so non-ASCII help text (Japanese example, arrows) no longer raises `UnicodeEncodeError`; the test harness decodes script output as UTF-8.diff --git a/README.md b/README.mdindex 9ea31a1..27af8d2 100644--- a/README.md+++ b/README.md@@ -115,7 +115,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth5. **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.-8. **Verify the result.** The output is probed, and when the picture changed (captions, overlays, crops, colour, transitions) the agent runs `look.py` and inspects the PNG. The report is not finished until its `Look:` line names that image; audio-only jobs say `Look: not needed`.+8. **Verify the result.** The output is probed, and when the picture changed (captions, overlays, crops, colour, transitions) the agent runs `look.py` and inspects the PNG. The report is not finished until its `Look:` line names that image; audio-only jobs say `Look: not needed`. **"Inspects" means the calling agent's own vision, not a feature of this skill:** `look.py` only renders a PNG; nothing in this repository detects faces, products or any other subject. When a crop or reframe needs to keep a specific part of the frame (`fit.py --fit crop --crop-x/-y`, see [Tools](#tools)), it is the multimodal agent looking at that PNG and choosing the anchor — a non-visual caller (a script, a CLI user without eyes on the sheet) has to supply that decision itself; the default is a plain centre crop.9. **Keep originals.** No tool overwrites its input. Outputs are new files named `<input>_<operation>.<ext>` unless told otherwise, and a test hashes every input after the run.## Tools@@ -137,7 +137,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth| `cut.py` | In/out or multi-segment cuts, lossless `-c copy` first, re-encode fallback, `--accurate` for frame-exact video and sample-exact audio; reports `precision` || `join.py` | Concatenate clips with xfade transitions, normalising size, fps and audio; audio-only inputs are joined as audio || `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); force constant fps |+| `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); force constant fps |**Audio**diff --git a/SKILL.md b/SKILL.mdindex b346cd3..8755df0 100644--- a/SKILL.md+++ b/SKILL.md@@ -62,7 +62,8 @@ Ask one short question only when the answer changes the output materially and th- **Captions** without a text source: use `--transcribe` if a local whisper exists, otherwise ask for the text or a timed file; never invent dialogue.- **Fonts and brand**: if the user mentions a brand, colours or "our font", ask for or create `brand.json` once and reuse it.- **CJK / non-Latin text**: check that a font exists before rendering (`fc-list :lang=ja file` / `:lang=ko` / `:lang=zh`); pass it with `--font "Name"` or `--font-file /path.ttf`. Tofu boxes are a failed job, not a style.-- Anything else (crop position, transition type, caption style): pick the conventional default, say what you picked, and offer the alternative in one line.+- **Crop position** for `--fit crop`: default to centre, but if the request or the source names an off-centre subject ("keep the product on the right", "don't cut off my hands", a logo/person visibly off-centre in `look.py`'s sheet) use `--crop-x`/`--crop-y` (0=left/top, 1=right/bottom) instead of the silent centre guess. Ask which edge to keep when the sheet shows the subject near an edge and the request doesn't say.+- Anything else (transition type, caption style): pick the conventional default, say what you picked, and offer the alternative in one line.Do not ask for things `probe.py` can tell you.@@ -182,7 +183,7 @@ Keep it to those five lines plus anything the user must decide. Attach the contanoise, not the content. Leave the level, say so, and offer music or narration.- Captions burned before a crop/resize: text lands off-frame. Frame changes first, then text.- Anything chained by hand through three re-encodes: use `render.py` so the plan is one file and the user can change one number.-- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars) or a reframe is often the honest answer.+- `--fit crop` to reach 9:16 from 16:9 throws away 70 % of the width: a wide shot loses people at the edges. Check the sheet; pad (bars), `--crop-x`/`--crop-y` toward the subject, or a reframe is often the honest answer — a silent centre crop is a guess, not a decision.- Conforming 60 fps to 30 halves the motion samples: fine for a talking head, visibly choppy for sports, gaming, drone pans. Keep 60 when the platform allows it.- "Make it 60 seconds" on a 3-minute talk by speed change is unwatchable (3×); by trim it drops two thirds of the words. Ask which, or propose a highlight cut with `scenes.py`.diff --git a/scripts/fit.py b/scripts/fit.pyindex 66a8a79..8a1d8e7 100755--- a/scripts/fit.py+++ b/scripts/fit.py@@ -4,14 +4,22 @@Duration: --duration N with --method speed (retime video+audio, pitch-preservingvia atempo chaining) or --method trim (keep the first N seconds, or a centredwindow with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with---fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop-(centre crop). --width sets the output width; height follows the aspect.+--fit pad (letterbox/pillarbox with --pad-color, default black) or --fit crop.+--width sets the output width; height follows the aspect.++Crop keeps the centre of the frame by default, which is a guess: going from+16:9 to 9:16 throws away most of the width, and whatever isn't in the middle+third (a person at the edge, a product held to one side) is cut off. Say what+to keep with --crop-x / --crop-y (0=left/top, 0.5=centre, 1=right/bottom, or+a decimal in between) rather than accepting the default silently when the+subject isn't centred; --fit pad never loses anything if you don't know yet.Examples:python3 fit.py input.mp4 --duration 60 # speed up/down to exactly 60spython3 fit.py input.mp4 --duration 30 --method trimpython3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15+ python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1 # keep the right edge (e.g. product held stage-right)"""import argparseimport math@@ -70,6 +78,8 @@ def main() -> int:a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect)")a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")+ a.add_argument("--crop-x", type=float, default=0.5, help="with --fit crop, horizontal anchor 0=left, 0.5=centre (default), 1=right")+ a.add_argument("--crop-y", type=float, default=0.5, help="with --fit crop, vertical anchor 0=top, 0.5=centre (default), 1=bottom")e = ap.add_argument_group("encoding")e.add_argument("--crf", type=int, default=18)e.add_argument("--preset", default="medium")@@ -80,6 +90,10 @@ def main() -> int:if not args.duration and not args.aspect and not args.width and not args.fps:die("nothing to do: give --duration, --aspect, --width and/or --fps")+ if not 0.0 <= args.crop_x <= 1.0:+ die(f"--crop-x must be 0..1, got {args.crop_x}")+ if not 0.0 <= args.crop_y <= 1.0:+ die(f"--crop-y must be 0..1, got {args.crop_y}")meta = probe(args.input)if not meta.get("video"):@@ -138,7 +152,7 @@ def main() -> int:out_h = even(out_w / ratio)if args.fit == "crop":vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")- vf.append(f"crop={out_w}:{out_h}")+ vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")else:vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=decrease")vf.append(f"pad={out_w}:{out_h}:(ow-iw)/2:(oh-ih)/2:color={args.pad_color}")diff --git a/tests/test_all.py b/tests/test_all.pyindex 780a0e9..f0c10e9 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -151,6 +151,24 @@ class FFmpegSkillTests(unittest.TestCase):def test_fit_refuses_extreme_speed(self):script("fit.py", self.src, "--duration", "1", expect_fail=True)+ def test_fit_crop_anchor_keeps_a_chosen_edge_not_just_the_centre(self):+ """A centre crop can cut a subject held to one side; --crop-x/-y say what to keep."""+ left = OUT / "fit_crop_left.mp4"+ right = OUT / "fit_crop_right.mp4"+ center = OUT / "fit_crop_center.mp4"+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "0", "-o", left)+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "--crop-x", "1", "-o", right)+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--width", "360", "-o", center)+ for out in (left, right, center):+ m = probe(str(out))+ self.assertEqual((m["video"]["width"], m["video"]["height"]), (360, 640))+ # different horizontal anchors must crop different content, not just resize the same crop+ self.assertLess(self._psnr(left, right), 40, "crop-x=0 vs crop-x=1 kept the same picture")++ def test_fit_crop_anchor_out_of_range_is_refused(self):+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-x", "1.5", expect_fail=True)+ script("fit.py", self.src, "--aspect", "9:16", "--fit", "crop", "--crop-y", "-0.1", expect_fail=True)+# ---------------------------------------------------------------- captiondef test_caption_text_to_srt_and_burn(self):srt = OUT / "cues.srt"