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 -movflags +faststart to remaining mp4 stream-copy paths (#279)

Shogo Kajiyama70d471d3a3ef
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 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 not
start the "1.19.0: observability, portability" theme further down this document, which remains
planned. 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.py
index e4505d6..8b6d9f4 100755
--- a/scripts/audio.py
+++ b/scripts/audio.py
@@ -21,6 +21,7 @@ Examples:
"""
import argparse
import sys
+from pathlib import Path
from typing import Any, Dict, List
from _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 it
cmd += audio_codec_for(output, args.bitrate)
diff --git a/scripts/caption.py b/scripts/caption.py
index 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.py
index 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 args
LOSSLESS_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.py
index 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.py
index 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.py
index b0bd0ab..6d06511 100644
--- a/tests/test_analysis.py
+++ b/tests/test_analysis.py
@@ -13,7 +13,7 @@ import unittest
from pathlib import Path
sys.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: E402
from _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.py
index 03ab660..185f135 100644
--- a/tests/test_audio.py
+++ b/tests/test_audio.py
@@ -12,20 +12,10 @@ import unittest
from pathlib import Path
sys.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: E402
from _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.py
index 1d7ed90..8f0936b 100644
--- a/tests/test_editing.py
+++ b/tests/test_editing.py
@@ -15,7 +15,7 @@ import unittest
from pathlib import Path
sys.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: E402
from _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.py
index 83d99d6..ddb7dea 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -18,7 +18,7 @@ import unittest.mock
from pathlib import Path
sys.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: E402
from _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 new
one (its map list never included 0:s?), so chaining it once per language -- the natural