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.

look.py: contact-sheet timecodes add back the mid-slice seek (#352)

Shogo Kajiyama4915bf5055c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 63aab9d..f545375 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,10 @@
## Unreleased
+### Fixed
+
+- **`look.py` contact-sheet timecodes match the frames shown.** The sheet starts reading half a slice in (`-ss` before `-i`, so the first tile is not a black lead-in), which resets timestamps to 0 at that point: every burned-in label was half a slice early (an 8 s clip as 3x2 labelled a frame at 0.667 s `00:00:00.000`). The timecode now adds the seek back (`%{pts:hms:<seek>}`); a sheet that starts at 0 is unchanged.
+
### Changed
- **`docs/design-decisions.md` opens with a contents list** (by topic, then by release), built from its headings by `.github/scripts/design_decisions_index.py`; a test fails when it is stale. Eleven sections that still said "Unreleased" long after they shipped (2.3.0 to 2.12.0) carry their version, and the release workflow now renames such a heading to the version that ships it, as it does for CHANGELOG.md.
diff --git a/scripts/look.py b/scripts/look.py
index 17a6738..7916b3e 100755
--- a/scripts/look.py
+++ b/scripts/look.py
@@ -28,7 +28,12 @@ def fmt_hms(sec: float) -> str:
return f"{int(h):02d}:{int(m):02d}:{s_:06.3f}"
-def timecode_filter(font_prefix: str) -> str:
+def timecode_filter(font_prefix: str, offset: float = 0.0) -> str:
+ """Burned-in timecode. `offset` is added to each frame's pts: an input-side -ss resets
+ timestamps to 0 at the seek point, so a sheet that starts reading mid-slice must add the seek
+ back or every tile is labelled `offset` seconds early (the contact sheet below seeks step/2)."""
+ if offset > 0:
+ return f"drawtext=text='%{{pts\\:hms\\:{offset:.6f}}}':{font_prefix}{FONT}"
return f"drawtext=text='%{{pts\\:hms}}':{font_prefix}{FONT}"
@@ -256,10 +261,12 @@ def main() -> int:
tile_w = max(2, (args.width // cols) // 2 * 2)
out = args.output or os.path.join(outdir, f"{stem}_sheet.png")
# sample at the middle of each slice so the first/last tiles are not black lead-in/out frames
- vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc},"
- f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
# with only a handful of frames a mid-slice seek skips past them all: start at 0 instead
seek = 0.0 if frames_avail < 4 else step / 2
+ # the seek resets pts to 0, so the burned-in timecode gets the seek added back
+ tc_sheet = tc.replace(timecode_filter(font_prefix), timecode_filter(font_prefix, seek)) if seek else tc
+ vf = (f"select='isnan(prev_selected_t)+gte(t-prev_selected_t\\,{step * 0.98:.6f})',scale={tile_w}:-2{tc_sheet},"
+ f"tile={cols}x{rows}:padding=2:margin=2:color=0x202020")
cmd = ffmpeg_base() + ["-ss", f"{seek:.6f}", "-i", args.input, "-vf", vf, "-frames:v", "1", out]
run(cmd)
outputs.append(out)
diff --git a/tests/test_contract.py b/tests/test_contract.py
index f2a8e5c..e9aea2f 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -3201,6 +3201,25 @@ class ContractTests(unittest.TestCase):
doc = json.loads(tool("speedramp", self.src, "--segment", "0-6:2", "-o", self.out("policy_ramp_plain.mp4"), "--json", "--fast").stdout)
self.assertFalse(doc["dropped_non_av_streams"])
+ def test_look_sheet_timecode_counts_from_the_seek(self):
+ """A contact sheet starts reading at half a slice (-ss before -i), which resets pts to 0 at
+ the seek point: the burned-in labels were half a slice early (8 s, 3x2: a tile showing
+ 0.667 s labelled 0.000). The timecode now adds the seek back; a sheet that starts at 0
+ (a clip with only a handful of frames) keeps the plain pts."""
+ doc = json.loads(tool("look", self.src, "--tiles", "3x2", "--dry-run", "--json",
+ "-o", self.out("tc_sheet.png")).stdout)
+ cmd = doc["commands"][0]
+ seek = re.search(r"-ss (\d+\.\d+) ", cmd).group(1)
+ self.assertGreater(float(seek), 0)
+ self.assertIn(f"pts\\:hms\\:{seek}", cmd)
+ one = self.out("tc_one_frame.mp4")
+ ffmpeg("-f", "lavfi", "-i", "testsrc2=size=64x64:rate=30", "-frames:v", "1", "-c:v", "libx264",
+ "-preset", "veryfast", "-pix_fmt", "yuv420p", one)
+ cmd = json.loads(tool("look", one, "--tiles", "2x2", "--dry-run", "--json",
+ "-o", self.out("tc_one.png")).stdout)["commands"][0]
+ self.assertIn("-ss 0.000000 ", cmd)
+ self.assertIn("pts\\:hms}", cmd)
+
def test_boundary_sweep_p3_regressions(self):
"""Sweep P3s: export's HDR warning reaches --json (F11); graphics refuses a frame too small
for its templates (F16); insert refuses a video where it wants a still (F17); look builds