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.

fix(cut): start an accurate re-encode's picture at 0 (#342)

Shogo Kajiyama722a816df2e3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index bd190e4..8f2dfa8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@
### Fixed
+- **`cut.py --accurate` starts the picture at 0 (#336).** The re-encode passed `-avoid_negative_ts make_zero`, which shifts every stream so the earliest timestamp is 0. That timestamp is the AAC encoder's priming (21.3 ms at 48 kHz) or a negative B-frame decode time, so the picture started after 0 and the sound at 0. `fit.py --fps` then changed the frame count. The video re-encode no longer passes the flag. When `--start` lands on a frame, that frame is at 0. A start between frames begins on the next source frame and may keep up to one frame of its timestamp. An MP4/MOV edit list hides the priming, and a source whose audio starts late keeps that offset. A stream copy still uses `make_zero` (or `--edit-list`). An audio-only `--accurate` cut still uses it, which is the priming `precision: codec_frame` counts in the length.
- **Windows 11 resolves Nirmala UI for Hindi, Bengali and Tamil (#339).** The font ships as `C:\Windows\Fonts\Nirmala.ttc`. `WINDOWS_FONTS` only named `Nirmala.ttf` and `NirmalaB.ttf`, so `doctor` reported no font for `hi`, `bn` and `ta`. The collection is now in those three lists, after the `.ttf` names, so a machine that still has Mangal or `Nirmala.ttf` keeps that file.
## 2.10.4
diff --git a/docs/design-decisions.md b/docs/design-decisions.md
index 7c818c0..0fbc0bd 100644
--- a/docs/design-decisions.md
+++ b/docs/design-decisions.md
@@ -1570,6 +1570,26 @@ not a new file format this tool would have to maintain.
`start_snapped`'s meaning (the presented start moved) and `precision` takes
`least_exact_precision`'s (the least exact segment).
+## Unreleased — an accurate cut starts its picture at 0
+
+- **`cut.py --accurate` on a video does not pass `-avoid_negative_ts make_zero`.** The
+ flag shifts every stream so the earliest timestamp is 0. On a re-encode that timestamp
+ is the AAC encoder's priming (1024 samples, 21.3 ms at 48 kHz) or, with B-frames, a
+ negative video decode time further back, so the picture started after 0 and the sound
+ at 0 (#336). `fit.py --fps` then snapped the gap and changed the frame count. Dropping
+ the flag leaves the first frame at 0 when `--start` lands on a frame. A start between
+ frames begins on the next source frame. On FFmpeg 6.1 that frame's timestamp is 0; on
+ 7.1, the Homebrew build and the Windows build it keeps about one frame (0.033 s), the
+ grid the decoder already had. Moving the picture alone to erase that frame would leave
+ the sound a frame ahead. An MP4/MOV edit list still hides the priming, so the sound
+ presents with the picture; a Matroska file keeps the priming packet at a negative time
+ and the picture at 0. A source whose audio starts late keeps that offset. Audio-only
+ `--accurate` still uses `make_zero`: `asetpts` already starts the samples at 0, and the
+ flag is what folds the priming into the length `precision: codec_frame` reports. A stream
+ copy is unchanged
+ (`make_zero` by default, `--edit-list` to hide the keyframe's pre-roll). Code:
+ `cut.cut_one()`. Test: `test_an_accurate_reencode_starts_the_picture_at_zero`.
+
## Unreleased — a fixed logo comes off with redact.py --mode delogo
- **`--mode delogo` is a mode of `redact.py`, not a 43rd script.** The operation is the one
diff --git a/references/scripts.md b/references/scripts.md
index 0657940..77b1ac1 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -91,7 +91,16 @@ max(2 frames, 0.1 s) away from the source's own offset where the picture starts
(the keyframe the copy began from; `--start` under `--edit-list`). It is
reported, not repaired. `-ss`/`-t` are passed to the microsecond; `--accurate`
seeks a second early and trims on the output side, so frames just before a
-keyframe are kept. `keyframe_snapped` is true for every stream copy (`precision`
+keyframe are kept. An `--accurate` re-encode of a video does not pass
+`-avoid_negative_ts make_zero`, which shifted the picture by the AAC priming
+(about 21 ms, more when a B-frame decode time is negative) while the sound
+stayed at 0, and `fit.py --fps` then changed the frame count. A start that
+lands on a frame leaves that frame at time 0. A start between frames begins on
+the next source frame and may keep up to one frame of timestamp. A `.mp4`/`.mov`
+edit list hides the priming. A source whose audio starts after its picture keeps
+that offset. An audio-only `--accurate` cut
+still uses `make_zero`; that priming is what `precision: codec_frame` counts
+in the length. `keyframe_snapped` is true for every stream copy (`precision`
`packet`); `start_snapped` is measured: true when a copied picture starts more
than a frame from `--start`, or when its start could not be measured (an unknown start is
never claimed exact); `null` under `--dry-run`.
diff --git a/scripts/cut.py b/scripts/cut.py
index 9017ee3..55cda87 100755
--- a/scripts/cut.py
+++ b/scripts/cut.py
@@ -22,6 +22,12 @@ caller never has to trust "it probably cut where I asked" on faith.
A single-segment .mp4/.mov copy shifts its timestamps to zero (-avoid_negative_ts
make_zero), so the picture starts at the keyframe; --edit-list keeps the MP4 edit
list instead, which hides the keyframe's pre-roll so the picture starts at --start.
+An --accurate re-encode of a video does not: make_zero moved the picture by the
+AAC priming (about 21 ms, and further when a B-frame's decode time is negative)
+while the sound stayed at 0. A start that lands on a frame keeps that frame at 0.
+A start between frames begins on the next frame and may keep up to one frame of
+timestamp. The MP4 edit list hides the encoder priming, and a source whose audio
+starts late keeps that offset.
A re-encode uses x264 for an SDR source and x265 Main10 for an HDR or BT.2020 one, as every
editing tool does; --keep-hevc re-encodes an SDR HEVC source as HEVC (x265 8-bit BT.709, or
@@ -823,7 +829,19 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
cmd += ["-sn", "-dn"]
if meta.get("subtitle_streams") or meta.get("data_streams"):
DROPPED_STREAMS.append(dst)
- cmd += encode_args(meta, dst, crf, preset) + ["-avoid_negative_ts", "make_zero", dst]
+ cmd += encode_args(meta, dst, crf, preset)
+ if audio_only:
+ # asetpts already starts the samples at 0. make_zero is what folds the encoder's
+ # priming into the container length, which is the delay precision codec_frame reports.
+ # A video re-encode must not take it (#336): the earliest timestamp is that priming,
+ # or a negative B-frame decode time, so make_zero starts the picture after 0 and
+ # leaves the sound at 0. fit --fps then drops or repeats a frame. Without the shift
+ # a start on a frame has that frame at 0. A start between frames begins on the next
+ # frame and may keep up to one frame of timestamp; moving the picture alone would
+ # leave the sound that far ahead. An MP4/MOV edit list hides the priming, and a
+ # source whose audio starts late keeps that offset.
+ cmd += ["-avoid_negative_ts", "make_zero"]
+ cmd += [dst]
elif audio_only:
# output-side seek: an input seek on a video file lands on the previous video keyframe and on
# FLAC/MP3 on a coarse index; reading from the start and dropping packets is exact to the packet
diff --git a/tests/test_cut_copy.py b/tests/test_cut_copy.py
index d0400d4..a141579 100644
--- a/tests/test_cut_copy.py
+++ b/tests/test_cut_copy.py
@@ -447,6 +447,53 @@ class CutJoinTests(unittest.TestCase):
self.assertEqual(cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}, "audio": {"start_time": 0.02}}), (0.02, None))
self.assertEqual(cut.av_skew({"video": {"start_time": 0.0, "fps": 30.0}}), (None, None))
+ def test_an_accurate_reencode_starts_the_picture_at_zero(self):
+ """#336: make_zero on the re-encode shifted the picture by the AAC priming (21 ms,
+ or the negative B-frame decode time, about 66 ms) and left the sound at 0. fit --fps
+ then changed the frame count. A start on a frame presents that frame at 0. A start
+ between frames begins on the next source frame and may keep up to one frame of
+ timestamp (FFmpeg 6.1 presents it at 0; 7.1, Homebrew and the Windows build keep
+ about 0.033 s). Audio-only --accurate keeps make_zero, which is the priming
+ codec_frame reports."""
+ plan = cut_json(self.hevc, "--start", "1", "--end", "3", "--accurate", "--dry-run",
+ "-o", DIR / "accurate_zero_plan.mp4")
+ self.assertNotIn("-avoid_negative_ts", plan["commands"][0])
+ audio_plan = cut_json(self.hevc, "--start", "1", "--end", "3", "--accurate", "--dry-run",
+ "-o", DIR / "accurate_zero_plan.m4a")
+ self.assertIn("-avoid_negative_ts make_zero", audio_plan["commands"][0])
+ out = DIR / "accurate_zero.mp4"
+ data = cut_json(self.hevc, "--start", "1", "--end", "3", "--accurate", "--preset", "ultrafast", "-o", out)
+ meta = probe(str(out))
+ vstart = meta["video"]["start_time"] or 0.0
+ astart = meta["audio"]["start_time"] or 0.0
+ self.assertLess(abs(vstart), 0.5 / FPS, vstart)
+ # one AAC frame of audio leading the picture is the priming packet a container
+ # stores at a negative time; the picture starting after the sound is the bug
+ self.assertLess(abs(astart - vstart), 1024 / 48000 + 0.005, (vstart, astart))
+ pts = frame_pts(out)
+ self.assertAlmostEqual(pts[0], 0.0, delta=0.5 / FPS)
+ self.assertEqual(len(pts), 60, "2 s at 30 fps, starting on a frame")
+ self.assertFrameIs(gray_frames(out)[0], 30, "the frame at 1.0 s, presented at 0")
+ self.assertLess(abs(data["duration_delta_seconds"]), 0.5 / FPS, data["duration_delta_seconds"])
+ mid = DIR / "accurate_midframe.mp4"
+ cut_json(self.hevc, "--start", "1.016", "--duration", "2", "--accurate", "--preset", "ultrafast", "-o", mid)
+ # 1.5 frames still excludes the priming shift (about 21 ms, or a B-frame decode
+ # time near 66 ms) while allowing the one-frame grid newer ffmpeg keeps.
+ self.assertGreaterEqual(frame_pts(mid)[0], -0.001)
+ self.assertLess(frame_pts(mid)[0], 1.5 / FPS,
+ "a between-frames start may keep up to one frame of grid offset")
+ self.assertFrameIs(gray_frames(mid)[0], 31, "1.016 s falls between frames; the next one starts the file")
+ fitted = DIR / "accurate_zero_fit.mp4"
+ script("fit.py", out, "--fps", "30", "--preset", "ultrafast", "-o", fitted)
+ self.assertEqual(len(frame_pts(fitted)), 60, "fit --fps keeps the frame the cut started at 0")
+ if "prores_ks" in ffmpeg_encoders():
+ mov = DIR / "accurate_zero.mov"
+ cut_json(self.hevc, "--start", "1", "--duration", "2", "--accurate", "--codec", "prores", "-o", mov)
+ got = probe(str(mov))
+ self.assertLess(abs(got["video"]["start_time"] or 0.0), 0.5 / FPS)
+ self.assertLess(abs((got["audio"]["start_time"] or 0.0) - (got["video"]["start_time"] or 0.0)),
+ 1024 / 48000 + 0.005)
+
def test_accurate_keeps_the_frames_before_a_keyframe(self):
"""--accurate seeked straight to the start, and by decode time -ss 9.9 lands on the
keyframe at 10.0; the three frames before it were lost."""