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: 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.md
index 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.2
diff --git a/references/process-pitfalls.md b/references/process-pitfalls.md
index 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 los
run and a confusing timeline. release.yml now checks out `ref: main` and rebases the bump on
main right before pushing. Lesson: a workflow that pushes to the branch that triggered it must
start 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.py
index 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 = none
self.overwrite = False # --overwrite: an existing output may be replaced
self.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 compatibility
def __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("-"):
return
try:
- 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 this
process 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("-"):
return
try:
exists = os.path.isfile(output)
@@ -357,6 +369,13 @@ def _check_existing_output(cmd: Sequence[str]) -> None:
return
if 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:
+ return
if 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) -> subpr
info(("[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 proc
def 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 threading
import time
total = STATE.duration_hint or 0.0
full = 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:
+ break
if 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.CompletedProce
sys.stderr.flush()
last = msg
try:
- _, 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.py
index 5e367ca..2b805a1 100644
--- a/tests/test_contract.py
+++ b/tests/test_contract.py
@@ -13,6 +13,7 @@ import shutil
import subprocess
import sys
import tempfile
+import time
import unittest
from 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 an
output path that already existed -- a previous deliverable, a mis-named source -- was