Skip to content

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

Add copy preset to export.py for zero-change deliveries (#27)

Shogo Kajiyamac8acb76f8423
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.py
index 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 compatibility
gif 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 youtube
python3 export.py final.mp4 --preset reels --fit crop
python3 export.py final.mp4 --preset prores -o master.mov
+ python3 export.py final.mp4 --preset copy -o delivered.mp4
python3 export.py --list
"""
import argparse
import sys
+from pathlib import Path
from typing import Dict, List
from _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.py
index 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 material
def test_probe_detects_vfr_rotation_surround_hdr(self):
self.assertTrue(probe(str(self.vfr))["video"]["variable_frame_rate_suspected"])