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: a failed run never costs the caller an existing output; --timeout is enforced under --progress (#173)
Shogo Kajiyama0890903d400a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 01cdc1c..df8b9b7 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,7 +4,8 @@## Unreleased-(nothing yet)+- A failed ffmpeg run no longer costs the caller an output file that existed before the run. Such a file is now written through a hidden sibling temp file and replaced only on success; on failure the original is untouched and the temp removed. Previously the partial-output cleanup deleted it (any FFmpeg), and on FFmpeg 5.x ffmpeg itself truncated it to 0 bytes before a filter error, with or without `--overwrite`.+- `--timeout` is enforced under `--progress`: the deadline is checked on a clock, so a deadlocked ffmpeg that prints no progress lines is killed and reported as `kind: timeout` instead of being waited on forever.## 1.4.2diff --git a/references/process-pitfalls.md b/references/process-pitfalls.mdindex 2aa2f00..6ae3735 100644--- a/references/process-pitfalls.md+++ b/references/process-pitfalls.md@@ -201,3 +201,29 @@ then found both PRs unreleased and published 1.4.2 correctly, so nothing was losrun and a confusing timeline. release.yml now checks out `ref: main` and rebases the bump onmain right before pushing. Lesson: a workflow that pushes to the branch that triggered it muststart from the branch tip, not from the triggering commit.++### "Clean up the partial output on failure" deleted the user's file++Found by the 1.4.2 review (2026-09-12), present since #78 (2026-09-07). The cleanup that removes a+0-byte stray after a failed encode keyed on "output path exists after failure", which is also+true of a deliverable that was there before the run and that ffmpeg never opened (a bad filter+argument fails at graph init, before the muxer touches the output -- on 6.1+). The --overwrite+consent added in #163 guards the success path only; the failure path had its own delete. The+first fix (snapshot size/mtime, leave an unchanged file alone) passed on 6.1 and failed in the+5.1.1 CI job: FFmpeg 5.x opens (truncates) the output during option parsing, before any filter+initialises, so ffmpeg itself had already destroyed the file. The fix that holds on every+version is to never let ffmpeg write to an existing path: run against a hidden sibling temp+file and os.replace() it over the original on success only. Lessons: a destructive step must+know whether it created the thing it is about to destroy, "exists" is not that knowledge; and+"the tool fails before touching the file" is a version-specific fact, never a guarantee. And the second review found what the first one -- which had+just written the overwrite guard next to this code -- did not: a reviewer who wrote the fix+reads the file they fixed, not the one beside it.++### --timeout only worked when ffmpeg was talking++Same review. The --progress runner iterated the progress pipe and compared the clock per+line, so the one case the timeout exists for (a deadlocked ffmpeg, which prints nothing)+never reached the comparison. The non-progress path used subprocess.run(timeout=) and was+fine, and the test only exercised that path. Lesson: a deadline belongs on a clock the loop+wakes up to check, never on the arrival of the thing you are waiting for; and a test for+"hang" must use a shim that actually hangs silently, not one that fails fast.diff --git a/scripts/_common.py b/scripts/_common.pyindex 6c64b09..434593d 100755--- a/scripts/_common.py+++ b/scripts/_common.py@@ -199,8 +199,8 @@ class Context:it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``."""- __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")- _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")+ __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting")+ _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting")def __init__(self) -> None:self.reset()@@ -215,6 +215,7 @@ class Context:self.timeout: float = _env_timeout() # seconds per ffmpeg invocation, 0 = noneself.overwrite = False # --overwrite: an existing output may be replacedself.written: set = set() # output paths this process has written itself+ self.preexisting: dict = {} # output path -> (size, mtime_ns) of a file that was there before we ran# mapping-style access kept for backwards compatibilitydef __getitem__(self, key: str) -> Any:@@ -300,8 +301,19 @@ def _cleanup_partial_output(cmd: Sequence[str]) -> None:if output in ("-", "pipe:0", "pipe:1") or output.startswith("pipe:") or output.startswith("-"):returntry:- if os.path.exists(output):- os.remove(output)+ if not os.path.exists(output):+ return+ # A file that was already there before this command ran is someone's deliverable, not+ # our partial. If ffmpeg died before opening it (bad filter argument, unreadable input:+ # the common case) it is byte-for-byte what it was, so leave it alone. Only when ffmpeg+ # did open and truncate it (size or mtime changed) is what remains a partial of ours,+ # and the original is already gone either way; then removing it is still right.+ before = STATE.preexisting.get(os.path.realpath(output))+ if before is not None:+ st = os.stat(output)+ if (st.st_size, st.st_mtime_ns) == before:+ return+ os.remove(output)except OSError:pass@@ -348,7 +360,7 @@ def _check_existing_output(cmd: Sequence[str]) -> None:2.0 behaviour (refuse) today, and --overwrite is the explicit consent either way. Paths thisprocess wrote itself (a two-pass tool, a copy-then-re-encode fallback) are never in question."""output = cmd[-1]- if STATE.overwrite or output in ("-",) or output.startswith("pipe:") or output.startswith("-"):+ if output in ("-",) or output.startswith("pipe:") or output.startswith("-"):returntry:exists = os.path.isfile(output)@@ -357,6 +369,13 @@ def _check_existing_output(cmd: Sequence[str]) -> None:returnif not exists or real in STATE.written:return+ try:+ st = os.stat(output)+ STATE.preexisting[real] = (st.st_size, st.st_mtime_ns)+ except OSError:+ pass+ if STATE.overwrite:+ returnif os.environ.get("FFMPEG_SKILL_NO_OVERWRITE", "") not in ("", "0"):die(f"refusing to overwrite existing output {output!r}: pass --overwrite to replace it, or choose another -o path", kind="input")info(f"warning: {output} already exists and will be overwritten (pass --overwrite to confirm; "@@ -380,12 +399,40 @@ def _timed_out(cmd: Sequence[str], seconds: float) -> "None":code=124, kind="timeout")+def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:+ """When the output path already holds someone's file, run ffmpeg against a hidden sibling+ temp path and move it over the original only on success.++ ffmpeg's -y truncates the output the moment it opens it, and *when* it opens it depends on+ the version: 6.1+ initialises the filter graph first (a bad LUT fails before the file is+ touched), 5.x opens the output during option parsing, before any filter runs, so the same+ bad LUT leaves a 0-byte file where the deliverable was. No amount of post-failure cleanup+ can undo that; the only way to keep an existing file safe across a failed run is for ffmpeg+ never to write to it. Same directory, same extension (the muxer is chosen by it), hidden+ name, so nothing else changes for the encoder. Returns (command to execute, final path,+ temp path); (cmd, None, None) when no staging is needed."""+ output = cmd[-1]+ if output == "-" or output.startswith("pipe:") or output.startswith("-"):+ return list(cmd), None, None+ try:+ if not os.path.isfile(output) or os.path.realpath(output) in STATE.written:+ return list(cmd), None, None+ except OSError:+ return list(cmd), None, None+ d, base = os.path.split(output)+ stem, ext = os.path.splitext(base)+ tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")+ return list(cmd[:-1]) + [tmp], output, tmp++def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprocess.CompletedProcess:"""Run a command, echoing it to stderr unless quiet. Exits on failure when check=True.ffmpeg invocations are recorded in STATE.commands (for --json), skipped under --dry-run(a fake successful CompletedProcess is returned so scripts can keep planning), and run- with a progress readout under --progress. ffprobe and other tools always run.+ with a progress readout under --progress. ffprobe and other tools always run. An output+ path that already exists is written through a temp file and replaced only on success+ (see _stage_existing_output), so a failed run never costs the caller the file that was there."""is_ffmpeg = _is_ffmpeg(cmd)if is_ffmpeg:@@ -396,9 +443,22 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subprinfo(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))if STATE.dry_run and is_ffmpeg:return subprocess.CompletedProcess(list(cmd), 0, "", "")- if STATE.progress and is_ffmpeg and cmd[-1] != "-":- return _run_with_progress(list(cmd), check)- return _run_captured(list(cmd), check)+ exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)+ if STATE.progress and is_ffmpeg and exec_cmd[-1] != "-":+ proc = _run_with_progress(exec_cmd, check)+ else:+ proc = _run_captured(exec_cmd, check)+ if final and tmp:+ if proc.returncode == 0:+ try:+ os.replace(tmp, final)+ except OSError as e:+ _cleanup_partial_output(exec_cmd)+ die(f"could not replace {final} with the new output: {e}", kind="output")+ _remember_output(cmd)+ else:+ _cleanup_partial_output(exec_cmd)+ return procdef run_keeping_subtitles(cmd: List[str], output: str) -> bool:@@ -455,22 +515,57 @@ def _progress_line(done: float, total: float, elapsed: float) -> str:def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcess:- """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr."""+ """Run ffmpeg with -progress on a pipe and print percent/ETA to stderr.++ The time limit is checked on a clock, not per progress line: a deadlocked ffmpeg (the very+ case --timeout exists for) prints nothing, so a loop that only looked at the deadline when a+ line arrived waited on it forever. Reader threads drain both pipes; the main loop wakes at+ least twice a second to compare the clock against the limit."""+ import queue+ import threadingimport timetotal = STATE.duration_hint or 0.0full = cmd[:1] + ["-progress", "pipe:1", "-nostats"] + cmd[1:]t0 = time.time()limit = _limit_for(cmd)proc = subprocess.Popen(full, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)+ assert proc.stdout is not None and proc.stderr is not None+ lines: "queue.Queue[Optional[str]]" = queue.Queue()+ err_chunks: List[str] = []++ def pump_out() -> None:+ for line in proc.stdout: # type: ignore[union-attr]+ lines.put(line)+ lines.put(None)++ def pump_err() -> None:+ err_chunks.append(proc.stderr.read()) # type: ignore[union-attr]++ threading.Thread(target=pump_out, daemon=True).start()+ err_thread = threading.Thread(target=pump_err, daemon=True)+ err_thread.start()last = ""- assert proc.stdout is not None- for line in proc.stdout:- if limit and time.time() - t0 > limit:- proc.kill()- proc.communicate()- if last:- sys.stderr.write("\r" + " " * len(last) + "\r")- _timed_out(cmd, limit)++ def clear_line() -> None:+ if last:+ sys.stderr.write("\r" + " " * len(last) + "\r")++ def timed_out() -> None:+ proc.kill()+ proc.wait()+ clear_line()+ _timed_out(cmd, limit or 0)++ while True:+ remaining = (limit - (time.time() - t0)) if limit else None+ if remaining is not None and remaining <= 0:+ timed_out()+ try:+ line = lines.get(timeout=min(0.5, remaining) if remaining is not None else 0.5)+ except queue.Empty:+ continue+ if line is None:+ breakif line.startswith("out_time_us=") or line.startswith("out_time_ms="):try:done = int(line.split("=")[1]) / 1_000_000@@ -482,13 +577,12 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProcesys.stderr.flush()last = msgtry:- _, err = proc.communicate(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))+ proc.wait(timeout=(max(5.0, limit - (time.time() - t0)) if limit else None))except subprocess.TimeoutExpired:- proc.kill()- proc.communicate()- _timed_out(cmd, limit or 0)- if last:- sys.stderr.write("\r" + " " * len(last) + "\r")+ timed_out()+ err_thread.join()+ err = "".join(err_chunks)+ clear_line()if proc.returncode == 0:_remember_output(cmd)if proc.returncode != 0:diff --git a/tests/test_contract.py b/tests/test_contract.pyindex 5e367ca..2b805a1 100644--- a/tests/test_contract.py+++ b/tests/test_contract.py@@ -13,6 +13,7 @@ import shutilimport subprocessimport sysimport tempfile+import timeimport unittestfrom pathlib import Path@@ -1206,6 +1207,59 @@ class ContractTests(unittest.TestCase):self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "timeout", "the env default applies without the flag")self.assertIn("timeout", self.contract["json_output"]["error_kinds"])+ def test_failed_run_never_deletes_an_output_that_predates_it(self):+ """The partial-output cleanup (#78) removed the output path after every failed ffmpeg run+ without asking whether the file had been there before: a bad filter argument aimed at an+ existing deliverable deleted the deliverable. And on FFmpeg 5.x the cleanup was not even+ needed for that: -y truncates the output during option parsing, before the filter graph+ is initialised, so the same bad LUT left a 0-byte file by itself (6.1+ initialises+ filters first). An existing output is therefore written through a hidden sibling temp+ file and replaced only on success -- with or without --overwrite (consent to replace is+ not consent to lose the file on failure); no temp file survives a failure; a fresh path+ the failed run created is still cleaned up."""+ keep = self.out("deliverable.mp4")+ self.assertEqual(tool("cut", self.src, "--start", "0", "--end", "1", "-o", keep).returncode, 0)+ before = (keep.stat().st_size, keep.stat().st_mtime_ns)+ bad = self.out("bad.cube")+ bad.write_text('TITLE "x"\nLUT_3D_SIZE 2\ngarbage\n')+ for extra in ((), ("--overwrite",)):+ proc = tool("color", self.src, "--lut", bad, "--json", "-o", keep, *extra, check=False)+ self.assertNotEqual(proc.returncode, 0)+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "ffmpeg")+ self.assertTrue(keep.exists(), f"failed run deleted a pre-existing output ({extra})")+ self.assertEqual((keep.stat().st_size, keep.stat().st_mtime_ns), before, "pre-existing output was modified")+ self.assertEqual([p.name for p in keep.parent.glob(".*ffskill*")], [], "temp file left behind after a failure")+ # success replaces the file, through the same temp path, and leaves no temp behind+ self.assertEqual(tool("cut", self.src, "--start", "0", "--end", "2", "--overwrite", "-o", keep).returncode, 0)+ self.assertNotEqual(keep.stat().st_size, before[0])+ self.assertEqual([p.name for p in keep.parent.glob(".*ffskill*")], [])+ # a fresh path that the failed run created is still cleaned up+ fresh = self.out("fresh.mp4")+ proc = tool("color", self.src, "--lut", bad, "--json", "-o", fresh, check=False)+ self.assertNotEqual(proc.returncode, 0)+ self.assertFalse(fresh.exists())++ @unittest.skipIf(platform.system() == "Windows", "the hung ffmpeg is a #!/bin/sh shim on a POSIX-only PATH; the deadline logic itself is platform-neutral")+ def test_timeout_is_enforced_under_progress_when_ffmpeg_prints_nothing(self):+ """--progress read ffmpeg's progress pipe line by line and only compared the clock when a+ line arrived, so the exact case --timeout exists for -- a deadlocked ffmpeg that prints+ nothing -- waited forever. A shell shim standing in for ffmpeg that sleeps silently and+ then fails reproduces it in seconds: with the limit at 1 s the run must end as kind+ timeout well before the shim's own sleep would have returned."""+ shim = self.out("hang_shim")+ shim.mkdir()+ (shim / "ffmpeg").write_text("#!/bin/sh\nsleep 8\nexit 1\n")+ (shim / "ffmpeg").chmod(0o755)+ (shim / "ffprobe").symlink_to(shutil.which("ffprobe"))+ env = dict(os.environ, PATH=str(shim) + os.pathsep + os.environ["PATH"])+ t0 = time.time()+ proc = tool("fit", self.src, "--aspect", "9:16", "--progress", "--timeout", "1", "--json",+ "-o", self.out("hang.mp4"), env=env, check=False)+ elapsed = time.time() - t0+ self.assertEqual(proc.returncode, 124, proc.stderr[-300:])+ self.assertEqual(json.loads(proc.stdout)["error"]["kind"], "timeout")+ self.assertLess(elapsed, 6, f"--progress waited {elapsed:.1f}s on a silent ffmpeg; the limit was 1 s")+def test_existing_output_warns_today_refuses_on_request_and_never_for_its_own_files(self):"""Every ffmpeg command carries -y (so a run never blocks on a y/N prompt), which meant anoutput path that already existed -- a previous deliverable, a mis-named source -- was