Skip to content

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

fit.py: add --crop-x/--crop-y anchor for aspect-ratio cropping (#25)

Shogo Kajiyama28559976423b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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. Togeth
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.
-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.md
index 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 conta
noise, 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.py
index 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-preserving
via atempo chaining) or --method trim (keep the first N seconds, or a centred
window 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 60s
python3 fit.py input.mp4 --duration 30 --method trim
python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
python3 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 argparse
import 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.py
index 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)
+
# ---------------------------------------------------------------- caption
def test_caption_text_to_srt_and_burn(self):
srt = OUT / "cues.srt"