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
fix(cut): start an accurate re-encode's picture at 0 (#342)
Shogo Kajiyama722a816df2e3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.4diff --git a/docs/design-decisions.md b/docs/design-decisions.mdindex 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 onediff --git a/references/scripts.md b/references/scripts.mdindex 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 isreported, 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 morethan a frame from `--start`, or when its start could not be measured (an unknown start isnever claimed exact); `null` under `--dry-run`.diff --git a/scripts/cut.py b/scripts/cut.pyindex 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_tsmake_zero), so the picture starts at the keyframe; --edit-list keeps the MP4 editlist 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 everyediting 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: icmd += ["-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 packetdiff --git a/tests/test_cut_copy.py b/tests/test_cut_copy.pyindex 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 thekeyframe at 10.0; the three frames before it were lost."""