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 -movflags +faststart to remaining mp4 stream-copy paths (#279)
Shogo Kajiyama70d471d3a3ef
diff --git a/docs/roadmap.md b/docs/roadmap.mdindex d138014..602c49e 100644--- a/docs/roadmap.md+++ b/docs/roadmap.md@@ -17,11 +17,11 @@ minor and `fix` PRs into a patch, so each block below is one or two `feat` PRs p- **planned** — not released. Nothing below a *planned* heading exists in any published version;the feature lines are the intent, not a description of the code.-The released version today is **1.24.0** — `multicam.py --write-project FILE` writes a-`render.py` project that reproduces the tool's own cut decision (eval 21's `mc2` gap, no more-hand-translating cuts/offsets into `clips[]`), and `--filler` alone no longer jump-cuts unrelated-dead-air silence (eval 19's `fw1`/`fw3`: "remove the ums" silently removed ~5s of unasked-for-pauses too; fixed by skipping generic silence detection unless `--speech-aware` is also given).+The released version today is **1.24.1** — `caption.py --karaoke-style word` emits one ASS+Dialogue event per word (active word scaled/emboldened, past/upcoming colours) instead of the+`\kf` colour-only sweep (#276), and `loudness.py`'s video-stream-copy branch now writes+`-movflags +faststart` like every other mp4-writing path, fixing a `render.py --template`+delivery that lost faststart on its `--normalize` pass (#275).1.19.0 (the `--write-project` feature) is a `feat:` release, hence the minor bump; it does notstart the "1.19.0: observability, portability" theme further down this document, which remainsplanned. 1.19.2 is docs-only (SKILL.md's overlong-word and MCP core-12 rows, this same truth-up).diff --git a/scripts/audio.py b/scripts/audio.pyindex e4505d6..8b6d9f4 100755--- a/scripts/audio.py+++ b/scripts/audio.py@@ -21,6 +21,7 @@ Examples:"""import argparseimport sys+from pathlib import Pathfrom typing import Any, Dict, Listfrom _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs@@ -305,6 +306,8 @@ def main() -> int:cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]if keep_video:cmd += ["-map", "0:v:0", "-c:v", "copy"]+ if Path(output).suffix.lower() in (".mp4", ".mov", ".m4v"):+ cmd += ["-movflags", "+faststart"]elif has_video:cmd += ["-vn"] # audio extension: the picture is dropped, not copied into a container that cannot hold itcmd += audio_codec_for(output, args.bitrate)diff --git a/scripts/caption.py b/scripts/caption.pyindex 546bed2..9e3d5f4 100755--- a/scripts/caption.py+++ b/scripts/caption.py@@ -1260,6 +1260,8 @@ def main() -> int:for n in range(len(added)):maps += ["-map", f"{n + 1}:0"]cmd += maps + ["-c:v", "copy"] + (["-c:a", "copy"] if meta.get("audio") else [])+ if mp4_family:+ cmd += ["-movflags", "+faststart"]for i in range(existing_subs):cmd += [f"-c:s:{i}", "copy"]tracks: List[Dict[str, Any]] = []diff --git a/scripts/cut.py b/scripts/cut.pyindex e360b4f..43f6822 100755--- a/scripts/cut.py+++ b/scripts/cut.py@@ -78,7 +78,10 @@ def copy_args(meta: dict, dst: str) -> List[str]:"""Stream-copy arguments: everything into a video container, audio only into an audio extension."""if is_audio_output(dst) and meta.get("video"):return ["-vn", "-c:a", "copy"]- return ["-c", "copy"]+ args = ["-c", "copy"]+ if os.path.splitext(dst)[1].lower() in (".mp4", ".mov", ".m4v"):+ args += ["-movflags", "+faststart"]+ return argsLOSSLESS_AUDIO = {"pcm_s16le", "pcm_s24le", "pcm_s32le", "pcm_f32le", "flac"}@@ -353,7 +356,10 @@ def main() -> int:with open(listfile, "w", encoding="utf-8") as fh:for p in parts:fh.write(concat_list_line(p) + "\n")- cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy", output]+ cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", listfile, "-c", "copy"]+ if ext in (".mp4", ".mov", ".m4v"):+ cmd += ["-movflags", "+faststart"]+ cmd += [output]proc = run(cmd, check=False)if proc.returncode != 0:info("concat with stream copy failed, re-encoding the join")diff --git a/scripts/sync.py b/scripts/sync.pyindex 5057109..7fff8b8 100755--- a/scripts/sync.py+++ b/scripts/sync.py@@ -335,6 +335,8 @@ def main() -> int:if head_trim > 0:cmd += ["-ss", f"{head_trim:.4f}"]cmd += ["-i", args.second, "-map", "0:v:0", "-map", "1:a:0", "-c:v", "copy"]+ if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):+ cmd += ["-movflags", "+faststart"]# the reference picture is the deliverable: pad the (possibly trimmed) second audio to# its length instead of -shortest, which cut the reference's tail whenever the second# file started earlier (head_trim > 0) or was simply shorter@@ -350,7 +352,10 @@ def main() -> int:run(cmd)else:if head_trim > 0 and not drift_af:- cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy", "-avoid_negative_ts", "make_zero", output]+ cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second, "-c", "copy"]+ if os.path.splitext(output)[1].lower() in (".mp4", ".mov", ".m4v"):+ cmd += ["-movflags", "+faststart"]+ cmd += ["-avoid_negative_ts", "make_zero", output]proc = run(cmd, check=False)if proc.returncode != 0:cmd = ffmpeg_base() + ["-ss", f"{head_trim:.4f}", "-i", args.second] + (video_args(probe(args.reference) if args.replace_audio else probe(args.second), args.crf) if has_video else []) + audio_codec_for(output) + [output]diff --git a/tests/_fixtures.py b/tests/_fixtures.pyindex 377e6ad..ef12212 100644--- a/tests/_fixtures.py+++ b/tests/_fixtures.py@@ -43,6 +43,17 @@ def png_size(path) -> tuple:return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")+def _is_faststart(path) -> bool:+ """moov before mdat. Reads the whole file rather than a leading slice: bytes.find() on a+ short read returns -1 for an atom that is actually further in, which compares as "before"+ every other offset and reports a false faststart -- issue #275 called this out explicitly+ after hitting it while confirming the bug. Shared by every test module that writes an mp4+ through a stream-copy path (#277's faststart regression tests)."""+ data = Path(path).read_bytes()+ moov, mdat = data.find(b"moov"), data.find(b"mdat")+ return moov != -1 and mdat != -1 and moov < mdat++def script(name, *args, **kw):return sh(sys.executable, SCRIPTS / name, *args, **kw)diff --git a/tests/test_analysis.py b/tests/test_analysis.pyindex b0bd0ab..6d06511 100644--- a/tests/test_analysis.py+++ b/tests/test_analysis.py@@ -13,7 +13,7 @@ import unittestfrom pathlib import Pathsys.path.insert(0, str(Path(__file__).resolve().parent))-from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _no_fontconfig, png_size, script, sh # noqa: E402+from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _is_faststart, _no_fontconfig, png_size, script, sh # noqa: E402from _common import default_font_file, font_for_script, probe # noqa: E402@@ -131,6 +131,31 @@ class AnalysisTests(MediaFixtures):again = json.loads(script("sync.py", self.src, out, "--json").stdout)self.assertClose(again["offset_seconds"], 0.0, 0.05, "aligned output has no residual offset")+ def test_sync_replace_audio_stream_copy_writes_faststart_mp4(self):+ """Same shape as #275/#277: --replace-audio stream-copies the reference's video with+ -c:v copy while only the audio is rebuilt, and must write -movflags +faststart on the+ mp4 output the same way every other mp4-writing path does."""+ out = OUT / "sync_replace_faststart.mp4"+ script("sync.py", self.src, self.mic, "--replace-audio", "-o", out)+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")+ self.assertTrue(_is_faststart(out), "sync.py --replace-audio must write +faststart")++ def test_sync_trim_second_stream_copy_writes_faststart_mp4(self):+ """Same shape as #275/#277, the other stream-copy spot in sync.py: --trim-second's+ head-trim path (`-c copy`) when the second file has video and started earlier."""+ early_video = OUT / "early_video.mp4"+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error",+ "-f", "lavfi", "-i", "color=c=black:s=1280x720:r=30:d=1.5",+ "-f", "lavfi", "-i", "aevalsrc=0:s=48000:d=1.5",+ "-i", self.src, "-filter_complex",+ "[0:v][2:v]concat=n=2:v=1:a=0[v];[1:a][2:a]concat=n=2:v=0:a=1[a]",+ "-map", "[v]", "-map", "[a]", "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac",+ str(early_video))+ out = OUT / "sync_trim_second_faststart.mp4"+ script("sync.py", self.src, early_video, "--trim-second", "-o", out)+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")+ self.assertTrue(_is_faststart(out), "sync.py --trim-second's stream-copy branch must write +faststart")+def test_sync_negative_offset_trim_second(self):early = OUT / "early.wav"sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "aevalsrc=0:s=48000:d=1.5",diff --git a/tests/test_audio.py b/tests/test_audio.pyindex 03ab660..185f135 100644--- a/tests/test_audio.py+++ b/tests/test_audio.py@@ -12,20 +12,10 @@ import unittestfrom pathlib import Pathsys.path.insert(0, str(Path(__file__).resolve().parent))-from _fixtures import MediaFixtures, OUT, SCRIPTS, script, sh # noqa: E402+from _fixtures import MediaFixtures, OUT, SCRIPTS, _is_faststart, script, sh # noqa: E402from _common import probe # noqa: E402-def _is_faststart(path) -> bool:- """moov before mdat. Reads the whole file rather than a leading slice: bytes.find() on a- short read returns -1 for an atom that is actually further in, which compares as "before"- every other offset and reports a false faststart -- issue #275 called this out explicitly- after hitting it while confirming the bug."""- data = Path(path).read_bytes()- moov, mdat = data.find(b"moov"), data.find(b"mdat")- return moov != -1 and mdat != -1 and moov < mdat--class AudioTests(MediaFixtures):"""Audio, loudness and waveform."""@@ -117,6 +107,15 @@ class AudioTests(MediaFixtures):self.assertEqual(self._frame_count(out), src_frames, f"{tag}: the picture lost or gained frames")self.assertAlmostEqual(m["audio"].get("duration") or m["duration"], src_dur, msg=tag, delta=0.05)+ def test_audio_keep_video_branch_writes_faststart_mp4(self):+ """Same shape as #275/#277 (loudness.py): --replace's keep_video branch stream-copies the+ video with -c:v copy while only the audio is touched, and must add -movflags +faststart+ on an mp4 output the same way every other mp4-writing path does."""+ out = OUT / "audio_keepvideo_faststart.mp4"+ script("audio.py", self.src, "--replace", self.mic, "-o", out)+ self.assertEqual(probe(str(out))["video"]["codec"], "h264", "video stream copied")+ self.assertTrue(_is_faststart(out), "audio.py's keep_video branch must write +faststart")+def test_audio_downmix_voice_and_ducking(self):out = OUT / "downmix.mp4"script("audio.py", self.surround, "--downmix", "--voice", "-o", out)diff --git a/tests/test_editing.py b/tests/test_editing.pyindex 1d7ed90..8f0936b 100644--- a/tests/test_editing.py+++ b/tests/test_editing.py@@ -15,7 +15,7 @@ import unittestfrom pathlib import Pathsys.path.insert(0, str(Path(__file__).resolve().parent))-from _fixtures import MediaFixtures, OUT, SCRIPTS, script, sh # noqa: E402+from _fixtures import MediaFixtures, OUT, SCRIPTS, _is_faststart, script, sh # noqa: E402from _common import probe # noqa: E402@@ -34,6 +34,15 @@ class EditingTests(MediaFixtures):out = OUT / "cut3.mp4"proc = script("cut.py", self.src, "--start", "2", "--end", "6", "--tolerance", "-1", "-o", out)self.assertIn("lossless stream copy", proc.stderr)+ # same shape as #275/#277: a stream-copy mp4-writing path must add -movflags +faststart+ self.assertTrue(_is_faststart(out), "cut.py's lossless single-segment stream copy must write +faststart")++ def test_cut_multi_segment_concat_copy_writes_faststart_mp4(self):+ """Same shape as #275/#277: the multi-segment concat join (`-f concat ... -c copy`) is a+ second, separate mp4-writing stream-copy path from the single-segment one above."""+ out = OUT / "cut_concat_faststart.mp4"+ script("cut.py", self.src, "--segments", "1-3,6-9", "-o", out)+ self.assertTrue(_is_faststart(out), "cut.py's multi-segment concat join must write +faststart")def test_cut_segments_accurate(self):out = OUT / "cut2.mp4"diff --git a/tests/test_picture.py b/tests/test_picture.pyindex 83d99d6..ddb7dea 100644--- a/tests/test_picture.py+++ b/tests/test_picture.py@@ -18,7 +18,7 @@ import unittest.mockfrom pathlib import Pathsys.path.insert(0, str(Path(__file__).resolve().parent))-from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _ass_advance, _ass_ink_columns, _ass_ink_rows, _emoji_assets, _families_for, _family_installed, _frame_ink, _no_fontconfig, _pixel_at, script, sh # noqa: E402+from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _ass_advance, _ass_ink_columns, _ass_ink_rows, _emoji_assets, _families_for, _family_installed, _frame_ink, _is_faststart, _no_fontconfig, _pixel_at, script, sh # noqa: E402from _common import default_font_file, detect_script, escape_filter_path, font_family_for_script, font_for_script, probe # noqa: E402@@ -741,6 +741,15 @@ class PictureTests(MediaFixtures):self.assertEqual(m["audio"]["codec"], "aac", "audio must be copied untouched")self.assertClose(m["duration"], 12.0, 0.15)+ def test_caption_mux_writes_faststart_mp4(self):+ """Same shape as #275/#277: --mode mux stream-copies video/audio with -c:v copy / -c:a+ copy while only adding a subtitle track, and must write -movflags +faststart on an mp4+ output the same way every other mp4-writing path does."""+ srt = OUT / "mux_faststart_cues.srt"+ out = OUT / "cap_mux_faststart.mp4"+ script("caption.py", self.src, "--text", self.cues, "--write-srt", srt, "--mode", "mux", "-o", out)+ self.assertTrue(_is_faststart(out), "caption.py --mode mux must write +faststart")+def test_caption_mux_chained_keeps_every_language_track(self):"""--mode mux used to drop any subtitle track the input already had when adding a newone (its map list never included 0:s?), so chaining it once per language -- the natural