ffmpeg-skill 1.4.1 → 1.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.1",
+  "version": "1.4.3",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 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",

package/references/process-pitfalls.md

@@ -180,3 +180,50 @@ admin with Contents: read/write on this repo -- whose "Repository admin" bypass
 push triggers workflows (GITHUB_TOKEN's do not), so the bump commit carries `[skip ci]`; the
 tag, Release and npm publish all happen in the originating run. Rotate the PAT before it
 expires or the next release fails at the same step, cleanly, before anything is published.
+
+### A literal `[skip ci]` anywhere in a PR body skips every workflow on the squash merge
+
+Found on the merge of #170 (2026-09-11). The PR body quoted the new bump-commit message
+verbatim, including `[skip ci]`; a squash merge copies the PR body into the merge commit, and
+GitHub honours the marker wherever it appears in the commit message. Nothing ran on `main` for
+that merge -- no tests, no CodeQL, no release -- and the release only happened when the next PR
+merged. Describe the marker in words in PR bodies and commit messages ("the skip-CI marker"),
+or wrap it so it does not match, and after any merge that touches CI check that the push
+actually triggered the expected runs.
+
+### Two merges minutes apart: the first release run bumps on a stale main and its push is rejected
+
+Found on 1.4.2 (2026-09-11). #167 (fix) merged, then #171 (docs) a minute later while the
+release run for #167 was still bumping. The concurrency group serialises the runs, but a run
+checks out the SHA that triggered it, so the first run's bump commit sat behind #171's merge
+and `git push origin HEAD:main` was rejected as non-fast-forward. The second run (for #171)
+then found both PRs unreleased and published 1.4.2 correctly, so nothing was lost -- one red
+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.

package/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:

package/scripts/color.py

@@ -112,26 +112,46 @@ def correction_chain(args: argparse.Namespace) -> str:
         die(f"--levels-out-black {out_black} must be less than --levels-out-white {out_white}")
 
     gm, rm, bm = -tint, tint / 2.0, tint / 2.0
-    terms = [
+    rgb = [
         f"exposure=exposure={exposure:g}",
         f"colortemperature=temperature={temperature:g}",
         f"colorbalance=rs={lift:g}:gs={lift:g}:bs={lift:g}:rm={rm:g}:gm={gm:g}:bm={bm:g}:rh={gain:g}:gh={gain:g}:bh={gain:g}",
-        f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}",
     ]
+    terms = [_rgb_stage(rgb), f"eq=contrast={contrast:g}:saturation={saturation:g}:gamma={gamma:g}"]
+    rgb2 = []
     if (in_black, in_white, out_black, out_white) != (0, 255, 0, 255):
         rimin, rimax = in_black / 255.0, in_white / 255.0
         romin, romax = out_black / 255.0, out_white / 255.0
-        terms.append(
+        rgb2.append(
             f"colorlevels=rimin={rimin:g}:gimin={rimin:g}:bimin={rimin:g}:"
             f"rimax={rimax:g}:gimax={rimax:g}:bimax={rimax:g}:"
             f"romin={romin:g}:gomin={romin:g}:bomin={romin:g}:"
             f"romax={romax:g}:gomax={romax:g}:bomax={romax:g}"
         )
     if args.curves:
-        terms.append(f"curves=preset={args.curves}")
+        rgb2.append(f"curves=preset={args.curves}")
+    if rgb2:
+        terms.append(_rgb_stage(rgb2))
     return ",".join(terms)
 
 
+def _rgb_stage(filters: list) -> str:
+    """Wrap a run of RGB-only filters in explicit, matching YUV<->RGB conversions.
+
+    exposure/colortemperature/colorbalance/colorlevels/curves take RGB, so libavfilter inserts a
+    swscale conversion on each side. Left to itself, the way in honours the frame's colour tag
+    (bt709 on any camera or export.py file) while the way back uses swscale's default matrix
+    (bt601): on a bt709-tagged source an all-defaults --correct came out 26 dB PSNR from its
+    input and ~8 % less saturated (#159). Untagged sources never showed it because both legs
+    then fall back to bt601 and cancel. Pinning both legs to the same matrix restores the
+    identity on every source (39 dB, the same as an untagged one always got); bt601 on both
+    sides measured better than bt709 on both (34 dB) because swscale's 601 path round-trips
+    8-bit 4:2:0 more exactly. The matrix here is only the working space of the conversion pair,
+    never a tag: the output carries the encoder's BT.709 tags as before."""
+    return ("scale=in_color_matrix=bt601,format=gbrpf32le," + ",".join(filters)
+            + ",scale=out_color_matrix=bt601,format=yuv420p")
+
+
 def hdr_to_sdr_chain(meta: dict, tonemap: str, peak: float, desat: float) -> str:
     v = meta["video"]
     trc = v.get("color_transfer") or "smpte2084"