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 copy preset to export.py for zero-change deliveries (#27)
Shogo Kajiyamac8acb76f8423
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1ebfd98..f5c2e2c 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -2,6 +2,20 @@## Unreleased — FFmpeg 8+ / Windows compatibility for caption and color+- **`export.py --preset copy`.** Every existing preset re-encodes (even `prores`/`h265`, which+ keep the source resolution). A caller with nothing to change — the deliverable already matches+ the source, no platform target — had no way to get a real, delivered file out of `export.py`+ without paying for and risking a needless re-encode. `copy` is a genuine stream copy (`-c:v+ copy -c:a copy`, no `-an` unless the source truly has no audio track): same codecs, same+ container (keeps the source's own extension unless `-o` names one), same colour tags — it+ skips the CFR-conforming (`-r`/`-fps_mode cfr`) and BT.709-retagging steps every re-encoding+ preset applies, since neither is meaningful (or safe) without decoding the picture, and it+ never issues the HDR "outputs SDR BT.709 tags" warning other presets do, because it doesn't+ touch colour at all. `-movflags +faststart` still applies when the resolved output is `.mp4`+ (a real optimisation a copy can do for free). Verified codec/resolution/frame-count/HDR-tags+ stay byte-for-byte the source's, not just nominally unchanged (frame count via `ffprobe+ -count_frames`, which a re-encode could silently drop or duplicate).+- **`scenes.py --rank-by`.** `--highlights` ranked candidate scenes by audio energy only, and the docstring falsely claimed motion was also used (it never was — dead documentation). `--rank-by {audio,duration}` (default audio, unchanged) makes the criterion explicit and adds a real second option (longest scene first); the result JSON now reports `highlights_rank_by`.- **`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.diff --git a/scripts/export.py b/scripts/export.pyindex 2587e0a..1f8c20c 100755--- a/scripts/export.py+++ b/scripts/export.py@@ -11,15 +11,19 @@ Presets:prores ProRes 422 HQ .mov, PCM 16-bit audio (editing master)h265 HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibilitygif 480px wide palette-optimised GIF at 12 fps (short previews)+ copy stream copy, no re-encode: same codecs, container and colour+ tags as the source (a delivery target with nothing to change)Examples:python3 export.py final.mp4 --preset youtubepython3 export.py final.mp4 --preset reels --fit croppython3 export.py final.mp4 --preset prores -o master.mov+ python3 export.py final.mp4 --preset copy -o delivered.mp4python3 export.py --list"""import argparseimport sys+from pathlib import Pathfrom typing import Dict, Listfrom _common import STATE, add_common, apply_common, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run@@ -32,6 +36,7 @@ PRESETS: Dict[str, Dict] = {"prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},"h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},"gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},+ "copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},}BT709 = ["-colorspace", "bt709", "-color_primaries", "bt709", "-color_trc", "bt709"]@@ -63,10 +68,11 @@ def main() -> int:meta = probe(args.input)if not meta.get("video"):die("input has no video stream")- if meta["video"].get("hdr") and args.preset != "prores":+ if meta["video"].get("hdr") and args.preset not in ("prores", "copy"):info("warning: source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))has_audio = bool(meta.get("audio"))output = args.output or default_output(args.input, args.preset, p["ext"])+ out_ext = Path(output).suffix.lstrip(".").lower()vf: List[str] = []if p["w"] and not args.no_scale:@@ -97,11 +103,14 @@ def main() -> int:if STATE["fast"] and "-preset" in video:video[video.index("-preset") + 1] = "veryfast"cmd += video- if "-r" not in video:- cmd += cfr_args(meta)- if args.preset not in ("prores",):- cmd += BT709- if p["ext"] == "mp4":+ if args.preset != "copy":+ # a stream copy can't be frame-rate-conformed or retagged without decoding it — that would+ # no longer be a copy, and would silently mislabel colour the agent never actually looked at+ if "-r" not in video:+ cmd += cfr_args(meta)+ if args.preset not in ("prores",):+ cmd += BT709+ if out_ext == "mp4":cmd += ["-movflags", "+faststart"]cmd += (p["audio"] if has_audio else ["-an"])if p["max"] and not args.allow_long and (meta.get("duration") or 0) > p["max"]:diff --git a/tests/test_all.py b/tests/test_all.pyindex e47141b..b8cd59a 100644--- a/tests/test_all.py+++ b/tests/test_all.py@@ -263,6 +263,39 @@ class FFmpegSkillTests(unittest.TestCase):def test_export_list(self):self.assertIn("youtube", script("export.py", "--list").stdout)+ def test_export_copy_is_a_real_stream_copy(self):+ """`--preset copy`: same bytes as a source→same-container remux would produce, not a re-encode — verified by+ codec/resolution/bitrate/frame-count staying exactly the source's, not by trusting the preset name."""+ out = OUT / "export_copy.mp4"+ script("export.py", self.src, "--preset", "copy", "-o", out)+ src_m, out_m = probe(str(self.src)), probe(str(out))+ self.assertEqual(out_m["video"]["codec"], src_m["video"]["codec"])+ self.assertEqual((out_m["video"]["width"], out_m["video"]["height"]), (src_m["video"]["width"], src_m["video"]["height"]))+ self.assertEqual(out_m["audio"]["codec"], src_m["audio"]["codec"])+ self.assertClose(out_m["duration"], src_m["duration"], 0.05)+ src_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", self.src).stdout.strip()+ out_frames = sh("ffprobe", "-v", "error", "-count_frames", "-select_streams", "v:0", "-show_entries", "stream=nb_read_frames", "-of", "csv=p=0", out).stdout.strip()+ self.assertEqual(out_frames, src_frames, "a re-encode could drop/duplicate frames; a copy cannot")+ # a genuinely untouched source has no colour tags to begin with (never asserts a re-encoder's own default)+ self.assertEqual(out_m["video"]["color_space"], src_m["video"]["color_space"])+ # no audio in the source: copy must not invent a silent track, and must not error demanding one+ noaudio = OUT / "noaudio_source.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", self.src, "-t", "2", "-an", "-c:v", "copy", noaudio)+ out_na = OUT / "export_copy_noaudio.mp4"+ script("export.py", noaudio, "--preset", "copy", "-o", out_na)+ self.assertIsNone(probe(str(out_na)).get("audio"))++ def test_export_copy_preserves_hdr_tags_untouched(self):+ """The HDR-warning branch that every re-encoding preset trips (`export.py` docstring: "outputs SDR BT.709+ tags without tone mapping") must not apply to `copy` — it doesn't touch colour at all, so the source's own+ HDR tags must survive exactly, not get silently flattened to BT.709 like every other preset does."""+ out = OUT / "export_copy_hdr.mov"+ proc = script("export.py", self.hdr, "--preset", "copy", "-o", out)+ self.assertNotIn("BT.709", proc.stdout + proc.stderr, "copy re-encodes nothing, so it never issues the SDR-flattening warning")+ m = probe(str(out))+ self.assertTrue(m["video"]["hdr"], "the source's real HDR tags must survive a stream copy")+ self.assertNotEqual(m["video"]["color_space"], "bt709", "copy must never relabel HDR content as bt709")+# ---------------------------------------------------------------- real-world materialdef test_probe_detects_vfr_rotation_surround_hdr(self):self.assertTrue(probe(str(self.vfr))["video"]["variable_frame_rate_suspected"])