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 render.py silently dropping fit.height and multicam.py's drift-trim ordering (#122)

Shogo Kajiyama54924f8efe61
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2f9acde..866fd11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,28 @@
(nothing yet)
+## 0.16.7 — fix a silently-dropped render.py fit height and a multicam.py drift-trim ordering bug
+
+- `render.py`'s single-clip fit path only ever inherited `width`/`fps` from
+ `project.frame` (never `height`), and the flag-forwarding list that turns
+ `project.fit`'s own keys into `fit.py` argv had no entry for `height` at
+ all. A `project.json` specifying `"fit": {"height": N}` alone built an
+ empty `fit.py` argv and crashed with "nothing to do"; combined with
+ another `fit` key (e.g. `duration`), `height` silently never reached
+ `fit.py` and the output's height was left unchanged with no error. Fixed
+ by adding the missing `frame.get("height")` inheritance and the
+ `("height", "--height")` forwarding entry, matching the multi-clip `join`
+ path, which already handled `height` correctly.
+- `multicam.py --fix-drift` computed its audio trim start (`a_start`) in
+ the source's own pre-correction time axis, but applied it via `atrim=
+ start=` *after* the `asetrate`/`aresample` drift-correction filters had
+ already rescaled that axis in the same filter chain -- so the trim
+ landed on the wrong point once the timeline had been stretched or
+ compressed by the drift ratio. `sync.py` already avoids this by seeking
+ with `-ss` (an input-level operation) before its own drift filters;
+ `multicam.py` now applies `atrim=start=`/`asetpts` before `asetrate`/
+ `aresample` in the filter chain to match.
+
## 0.16.5 — fix silence.py breaking on audio-only WAV, unvalidated --fps, and a LUT-strength inversion in color.py
A deep line-by-line pass over the most-used editing tools:
diff --git a/docs/contract.md b/docs/contract.md
index 7fbead6..fe19621 100644
--- a/docs/contract.md
+++ b/docs/contract.md
@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
| Field | Meaning | Changes when |
|---|---|---|
| `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`0.16.5`) | any release |
+| `skill.version` | the npm / package.json version (`0.16.7`) | any release |
A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -39,7 +39,7 @@ drifting silently.
```json
{
"contract_version": "1.0",
- "skill": {"id": "ffmpeg-skill", "version": "0.16.5", "execution_mode": "local", "kind": "execution",
+ "skill": {"id": "ffmpeg-skill", "version": "0.16.7", "execution_mode": "local", "kind": "execution",
"entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
"not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
"requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
diff --git a/package.json b/package.json
index ec7b0c6..18df5d8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "ffmpeg-skill",
- "version": "0.16.5",
+ "version": "0.16.7",
"description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 40 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
"keywords": [
"ffmpeg",
diff --git a/scripts/multicam.py b/scripts/multicam.py
index ad28c96..e8de298 100755
--- a/scripts/multicam.py
+++ b/scripts/multicam.py
@@ -188,13 +188,17 @@ def main() -> int:
parts.append("".join(labels) + f"concat=n={len(filled)}:v=1:a=0[vout]")
a = args.audio
a_start = -offsets[a] if offsets[a] < 0 else 0.0
- afx = []
+ # a_start is a trim point in the source's own, pre-drift-correction time axis, so it must be
+ # applied before asetrate/aresample rescale that axis -- otherwise the trim lands at the wrong
+ # point once the stream's timebase has already been stretched/compressed by the drift ratio
+ # (mirrors sync.py, which seeks with -ss, an input-level operation, before its drift_af filters).
+ afx = [f"atrim=start={a_start:.4f}", "asetpts=PTS-STARTPTS"]
if abs(ratios[a] - 1.0) > 1e-7:
sr = metas[a]["audio"].get("sample_rate") or 48000
afx += [f"asetrate={sr * ratios[a]:.6f}", f"aresample={sr}"]
if offsets[a] > 0:
afx.append(f"adelay={int(round(offsets[a] * 1000))}:all=1")
- afx += [f"atrim=start={a_start:.4f}", "asetpts=PTS-STARTPTS", f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
+ afx += [f"atrim=0:{ref_dur:.3f}", "aformat=sample_rates=48000:channel_layouts=stereo"]
parts.append(f"[{a}:a]{','.join(afx)}[aout]")
output = args.output or default_output(args.inputs[0], "multicam", "mp4")
diff --git a/scripts/render.py b/scripts/render.py
index 07fc5ce..ceacbf7 100755
--- a/scripts/render.py
+++ b/scripts/render.py
@@ -204,12 +204,14 @@ def main() -> int:
fit.setdefault("aspect", frame["aspect"])
if frame.get("width") and len(parts) == 1:
fit.setdefault("width", frame["width"])
+ if frame.get("height") and len(parts) == 1:
+ fit.setdefault("height", frame["height"])
if frame.get("fps") and len(parts) == 1:
fit.setdefault("fps", frame["fps"])
if fit:
nxt = str(work / "fit.mp4")
argv = [current, "-o", nxt]
- for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("fps", "--fps"), ("smooth", "--smooth")):
+ for k, flag in (("duration", "--duration"), ("method", "--method"), ("aspect", "--aspect"), ("fit", "--fit"), ("width", "--width"), ("height", "--height"), ("fps", "--fps"), ("smooth", "--smooth")):
if fit.get(k) is not None:
argv += [flag, str(fit[k])]
sh("fit.py", *argv)
diff --git a/tests/test_all.py b/tests/test_all.py
index 0d94176..0dbc862 100644
--- a/tests/test_all.py
+++ b/tests/test_all.py
@@ -1635,6 +1635,31 @@ class FFmpegSkillTests(unittest.TestCase):
self.assertClose(probe(str(auto))["duration"], 12.0, 0.2)
script("multicam.py", self.src, camB, "--switch", "0-3:5", expect_fail=True)
+ def test_multicam_fix_drift_trims_before_resample_not_after(self):
+ """--fix-drift's audio path computes a_start (an atrim start point) in the source's own
+ pre-correction time axis, but the filter chain used to apply asetrate/aresample (the drift
+ correction) *before* atrim -- so the trim landed on the already-rescaled timeline instead
+ of the raw one it was computed for, same bug class as sync.py already avoids by seeking
+ with -ss (an input-level, pre-filter operation) before its own drift_af. Build a camera
+ whose audio started before the reference (offsets[a] < 0, so a_start > 0) and also drifts
+ (ratios[a] != 1), then check the constructed [<audio input>:a] filter chain: atrim=start=
+ must appear before asetrate, mirroring sync.py's ordering."""
+ base = OUT / "mc_drift_base.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", f"aevalsrc='{TONES}':s=48000", "-t", "200", "-c:a", "pcm_s16le", base)
+ ref_audio = OUT / "mc_drift_ref.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-ss", "1.2", "-i", base, "-c:a", "pcm_s16le", ref_audio)
+ camB = OUT / "mc_drift_camB.wav"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-i", base, "-af", "asetrate=48000*0.9995,aresample=48000", "-c:a", "pcm_s16le", camB)
+ cam0 = OUT / "mc_drift_cam0.mp4"
+ sh("ffmpeg", "-y", "-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=size=160x120:rate=15", "-i", ref_audio, "-c:v", "libx264", "-preset", "ultrafast", "-c:a", "aac", "-shortest", cam0)
+
+ data = json.loads(script("multicam.py", cam0, camB, "--audio", "1", "--switch", "0-198:0", "--fix-drift", "--max-offset", "5", "--fast", "-o", OUT / "mc_drift_out.mp4", "--json").stdout)
+ self.assertLess(data["offsets_seconds"][1], 0, "camera 1 must have started before the reference for a_start > 0 to be exercised")
+ self.assertNotEqual(data["drift_ppm"][1], 0.0, "drift must actually be detected for asetrate/aresample to be in the chain")
+ audio_chain = data["commands"][0].split("[1:a]", 1)[1]
+ self.assertLess(audio_chain.index("atrim=start="), audio_chain.index("asetrate="),
+ "atrim=start= (in the pre-correction time axis) must run before asetrate/aresample rescale that axis")
+
def test_multicam_negative_auto_interval_refused_not_infinite_loop(self):
"""--auto builds cuts with `while t < ref_dur: ... t += args.auto` -- `elif args.auto:` is
only false for exactly 0, so a negative value used to pass that check and enter the loop
@@ -2031,6 +2056,24 @@ class FFmpegSkillTests(unittest.TestCase):
self.assertEqual(out["stages"], ["clips", "join"])
self.assertTrue(Path(out["output"]).exists())
+ def test_render_single_clip_fit_height_is_not_silently_dropped(self):
+ """The single-clip fit path only ever inherited width/fps from project.frame, and the
+ flag-forwarding list that turns project.fit's own keys into fit.py argv omitted height
+ entirely -- so a project.json specifying "fit": {"height": N} (with no other fit key)
+ used to build fit.py argv with nothing in it at all ("nothing to do" crash), and combined
+ with another fit key (e.g. duration) the height silently never reached fit.py -- the
+ output's height was left unchanged with no error. Verify height alone now actually
+ resizes a single-clip render."""
+ proj = OUT / "project_height.json"
+ proj.write_text(json.dumps({
+ "output": "render_height.mp4",
+ "clips": [{"src": "source.mp4", "in": "0:01", "out": "0:04"}],
+ "fit": {"height": 480},
+ }), encoding="utf-8")
+ script("render.py", proj, "--fast", "--json")
+ m = probe(str(OUT / "render_height.mp4"))
+ self.assertEqual(m["video"]["height"], 480)
+
def test_render_exits_nonzero_when_the_check_stage_fails(self):
"""A render whose deliverable fails its own check stage must not report success."""
proj = OUT / "project_bad_check.json"