ffmpeg-skill 1.4.0 → 1.4.2

package/README.md

@@ -13,9 +13,13 @@
 
 <p align="center">
   <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/ci.yml/badge.svg" alt="tests"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml"><img src="https://github.com/kajisho5/ffmpeg-skill/actions/workflows/codeql.yml/badge.svg" alt="CodeQL"></a>
   <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/v/ffmpeg-skill" alt="npm"></a>
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
-  <img src="https://img.shields.io/badge/ffmpeg-5.0%2B-orange" alt="FFmpeg 5.0+">
+  <a href="https://www.npmjs.com/package/ffmpeg-skill"><img src="https://img.shields.io/npm/dm/ffmpeg-skill" alt="npm downloads"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/stargazers"><img src="https://img.shields.io/github/stars/kajisho5/ffmpeg-skill" alt="GitHub stars"></a>
+  <a href="https://github.com/kajisho5/ffmpeg-skill/commits/main"><img src="https://img.shields.io/github/last-commit/kajisho5/ffmpeg-skill" alt="last commit"></a>
+  <img src="https://img.shields.io/badge/python-3.9%20%7C%203.13-blue" alt="Python 3.9 and 3.13 tested">
+  <a href="#ffmpeg-compatibility"><img src="https://img.shields.io/badge/ffmpeg-5.1%20%7C%206.1%20%7C%207.1%20%7C%208%20%7C%209%20tested-orange" alt="FFmpeg 5.1, 6.1, 7.1, 8 and 9 tested in CI"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT"></a>
   <a href="https://github.com/sponsors/kajisho5"><img src="https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=githubsponsors" alt="Sponsor"></a>
 </p>
@@ -139,7 +143,7 @@ These are the rules the skill file gives the agent and the code enforces. Togeth
 
 1. **Probe first.** No tool decides from the file name. `probe.py` measures duration, fps (with variable-frame-rate detection), resolution, rotation, bit depth, HDR format including Dolby Vision, colour tags and every audio stream before anything is cut.
 2. **Lossless when possible.** `cut.py`, `join.py` and `loudness.py` stream-copy what they do not need to touch. Re-encoding happens only when it must: frame-accurate cuts, filters, format changes, or a keyframe farther than the tolerance.
-3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress` (percent and ETA). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
+3. **Plan before render.** Every tool takes `--dry-run` (print the ffmpeg command lines, write nothing), `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress` (percent and ETA), `--timeout` (a hung ffmpeg is killed and reported, never waited on forever) and `--overwrite` (explicit consent before an existing output is replaced). A test runs every tool under `--dry-run` behind a fake ffmpeg and asserts that no ffmpeg call happened and no file appeared.
 4. **Machine-readable contract.** `contract --json` describes all 42 tools: input schema generated from the parser, output schema, role, required and conditional FFmpeg capabilities, dry-run support, the verification tools to run afterwards, whether a visual check is required, `mutates_input: false`. `provides` lists all 40 by a cross-repository Capability id (`ffmpeg-skill.cut`, `ffmpeg-skill.loudness`, ...) for [`kajisho5/AI-video-production-OS`](https://github.com/kajisho5/AI-video-production-OS)'s `CapabilityContract.provides` — see `docs/contract.md`.
 5. **Contract-derived MCP.** `mcp/server.py` builds its `tools/list` from the contract. Tool names, order and `inputSchema` cannot drift from the scripts; a test keeps the two byte-identical.
 6. **Capability detection.** `doctor` reads `ffmpeg -encoders / -filters / -bsfs` and reports which of the components the tools need are present on this build (libx264, libass, zscale, loudnorm, xfade, …), before a job fails inside ffmpeg.
@@ -336,6 +340,7 @@ FFmpeg 8 shortened the flag column of `ffmpeg -filters`. A parser anchored on th
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
+| **36 / 36** | 1.4.0 re-run (2026-09-11, one pass per prompt, Sonnet agent, regex grader + manual review): 24-prompt set routing 20/20, honest refusals 5/5, visual check 8/8, user's language 8/9; exec set real execution 6/6, honest failure on bad inputs 5/5 with 0 false successes, audio-as-audio 3/3; trigger set 22/22. Details and the six findings in `evals/results/iteration-5.json` |
 | **6 / 6** | 0.9.1 audio evals (audio join, extraction, track selection, sample-accurate trim, typed dynamics; 2 in Japanese): routing, report format and audio-as-audio handling 6/6 |
 
 ```bash

package/SKILL.md

@@ -5,7 +5,7 @@ description: 'Edit video and audio with local FFmpeg from natural-language reque
 
 # ffmpeg-skill
 
-Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality) and `--progress`. Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
+Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>/scripts/<name>.py`. Every script has `--help`, and all of them accept `--dry-run`, `--json` (structured result with a probe of the output), `--fast` (preview quality), `--progress`, `--timeout SECONDS` (a single ffmpeg run is killed past this and reported as `kind: timeout`; default 1800) and `--overwrite` (consent to replace an output that already exists; without it the tool warns today and refuses from 2.0). Writing tools run nothing under `--dry-run`; `probe`/`check`/`sync`/`multicam`/`scenes`/`cropdetect`/`report` may still run ffmpeg/ffprobe to measure or analyse — they just don't write their final artifact; `verify` accepts the flag but ignores it. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`). Details for every flag: `references/scripts.md`. Device-specific behaviour (iPhone HDR, GoPro, DJI, screen recordings, Zoom): `references/devices.md`.
 
 ## Workflow (always follow this order)
 
@@ -41,7 +41,9 @@ Scripts live in `scripts/` next to this file; run them with `python3 <skill-dir>
    be a placeholder, not a computed preview — see `docs/contract.md`). Use
    them to confirm a plan before long encodes and to report exact facts.
    `--fast` gives a quick preview-quality render (x264 veryfast), `--progress`
-   prints percent and ETA on stderr for long encodes.
+   prints percent and ETA on stderr for long encodes. Never point `-o` at a file
+   you did not create in this job unless the user asked for it to be replaced;
+   pass `--overwrite` only then.
 4. **Chain operations in a sensible order.** Colour (HDR→SDR / LUT) → cut →
    join → silence → fit → caption/overlay → sync → audio → loudness → export.
    Do frame changes (fit/crop) before captions and overlays so text is sized

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.4.0",
+  "version": "1.4.2",
   "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

@@ -158,3 +158,35 @@ inputs (or `Unexpected input(s)` in the first log) before trusting a parameter,
 any step whose output decides an irreversible action as something to unit-test with fixed
 inputs, not something to confirm by reading its YAML. And watch the first real run's
 *effect* (tags, npm), which is how both incidents were actually noticed.
+
+### The release bump step required the literal `(nothing yet)` line under `## Unreleased`
+
+Found on the first run after #163 (2026-09-11). `release.yml`'s auto-bump located the CHANGELOG
+insertion point with `assert "## Unreleased\n\n(nothing yet)\n\n" in changelog`. #163 did the
+natural thing and wrote its notes under Unreleased, so the bump step failed on the assert
+before the push, the tag or the publish -- a clean no-op, but a red run and no release. The
+script now takes whatever sits under Unreleased into the new version's section and puts the
+placeholder back, so hand-written notes are welcome there. Lesson: an anchor that is also
+prose will be edited; anchor on the heading, not on the placeholder text.
+
+### The built-in GITHUB_TOKEN cannot push the release bump through a ruleset
+
+Found on the first release after the main ruleset went active (2026-09-11, run for #166):
+`git push origin HEAD:main` from release.yml was declined with GH013 ("Changes must be made
+through a pull request", "8 of 8 required status checks are expected"). GitHub Actions cannot
+be added as a ruleset bypass actor (the import rejects the actor, the UI does not list it), so
+the bump push now uses the `RELEASE_PUSH_TOKEN` secret -- a fine-grained PAT of a repository
+admin with Contents: read/write on this repo -- whose "Repository admin" bypass applies. A PAT
+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.

package/references/scripts.md

@@ -1,6 +1,6 @@
 # Script reference
 
-Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
+Every script prints the same information with `--help`; this file exists so the agent can read several at once. All scripts accept `--dry-run`, `--json`, `--fast`, `--progress`, `--timeout SECONDS`, `--overwrite`, `-o OUT` -- but `--dry-run` only guarantees nothing is written for writing tools: `probe` (read-only, `--dry-run` changes nothing) and `check` (skips only the loudness-measurement pass) still run ffprobe/ffmpeg, `sync`/`multicam`/`scenes`/`cropdetect`/`report` still run ffmpeg/ffprobe to measure or analyse (they just don't write the final artifact), and `verify` accepts the flag but ignores it entirely. Exact per-tool semantics: `contract --json`'s `dry_run` field (or `docs/contract.md`).
 
 ## Contents
 - probe.py — inspect

package/scripts/_common.py

@@ -62,8 +62,25 @@ ERROR_CODE = {
     "missing_tool": "DEPENDENCY_MISSING",
     "ffmpeg": "FFMPEG_EXECUTION_FAILED",
     "output": "OUTPUT_INVALID",
+    "timeout": "TIMEOUT",
 }
 
+# Wall-clock ceiling for one ffmpeg/ffprobe invocation, in seconds. A hung ffmpeg (a build
+# that deadlocks on a filter combination, a stalled network mount, an input that never ends)
+# used to hang the calling agent with it, with no error document and no way out short of
+# killing the process by hand. The ceiling is generous on purpose: it exists to turn a hang
+# into a reported failure, not to police slow encodes. --timeout and FFMPEG_SKILL_TIMEOUT
+# override it; 0 disables it.
+DEFAULT_TIMEOUT = 1800.0
+PROBE_TIMEOUT = 120.0
+
+
+def _env_timeout() -> float:
+    try:
+        return max(0.0, float(os.environ.get("FFMPEG_SKILL_TIMEOUT", DEFAULT_TIMEOUT)))
+    except ValueError:
+        return DEFAULT_TIMEOUT
+
 # None of the four kinds above are retryable in practice: an "input"/"missing_tool" failure is
 # always deterministic (the same bad path or absent binary fails identically every time), and a
 # "ffmpeg"/"output" failure -- while it COULD in principle be caused by a transient environment
@@ -182,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")
-    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands")
+    __slots__ = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")
+    _KEYS = ("dry_run", "json", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written")
 
     def __init__(self) -> None:
         self.reset()
@@ -195,6 +212,9 @@ class Context:
         self.fast = False         # x264 preset forced to veryfast
         self.duration_hint: Optional[float] = None  # expected output length, for the progress percent
         self.commands: List[str] = []               # every ffmpeg command line, for --json and --dry-run
+        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
 
     # mapping-style access kept for backwards compatibility
     def __getitem__(self, key: str) -> Any:
@@ -221,6 +241,11 @@ def add_common(ap: "argparse.ArgumentParser") -> None:
     g.add_argument("--json", action="store_true", help="print a JSON result (output, probe, commands) on stdout instead of the path")
     g.add_argument("--progress", action="store_true", help="show percent / ETA on stderr while ffmpeg encodes")
     g.add_argument("--fast", action="store_true", help="preview quality: x264 preset veryfast (overrides --preset) for quick iterations")
+    if "--timeout" not in ap._option_string_actions:  # verify.py defines its own per-step --timeout; apply_common reads either
+        g.add_argument("--timeout", type=float, default=None, metavar="SECONDS",
+                       help=f"kill any single ffmpeg run that exceeds this many seconds and report kind=timeout (default {DEFAULT_TIMEOUT:.0f}, or FFMPEG_SKILL_TIMEOUT; 0 = no limit)")
+    g.add_argument("--overwrite", action="store_true",
+                   help="allow replacing an output file that already exists (without it a warning is printed today; from 2.0 an existing output is refused, and FFMPEG_SKILL_NO_OVERWRITE=1 opts into that now)")
 
 
 def apply_common(args: "argparse.Namespace") -> None:
@@ -228,6 +253,9 @@ def apply_common(args: "argparse.Namespace") -> None:
     STATE.json = bool(getattr(args, "json", False))
     STATE.progress = bool(getattr(args, "progress", False))
     STATE.fast = bool(getattr(args, "fast", False))
+    STATE.overwrite = bool(getattr(args, "overwrite", False))
+    if getattr(args, "timeout", None) is not None:
+        STATE.timeout = max(0.0, float(args.timeout))
     if STATE.fast and getattr(args, "preset", None) in X264_PRESETS:
         args.preset = "veryfast"
 
@@ -312,6 +340,46 @@ def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
                 continue
 
 
+def _check_existing_output(cmd: Sequence[str]) -> None:
+    """An output path that already exists is someone's file: a previous result, a source the
+    agent mis-named, a deliverable from another run. ffmpeg's -y (which every command carries so
+    a run never blocks on a y/N prompt) would replace it without a word. Until 2.0 this only
+    warns, per docs/contract.md's deprecation policy; FFMPEG_SKILL_NO_OVERWRITE=1 opts into the
+    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("-"):
+        return
+    try:
+        exists = os.path.isfile(output)
+        real = os.path.realpath(output)
+    except OSError:
+        return
+    if not exists or real in STATE.written:
+        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; "
+         f"from 2.0 an existing output is refused without it, FFMPEG_SKILL_NO_OVERWRITE=1 enables that now)")
+
+
+def _remember_output(cmd: Sequence[str]) -> None:
+    output = cmd[-1]
+    if output == "-" or output.startswith("pipe:") or output.startswith("-"):
+        return
+    try:
+        STATE.written.add(os.path.realpath(output))
+    except OSError:
+        pass
+
+
+def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
+    _cleanup_partial_output(cmd)
+    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
+        f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
+        code=124, kind="timeout")
+
+
 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.
 
@@ -322,6 +390,7 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True) -> subpr
     is_ffmpeg = _is_ffmpeg(cmd)
     if is_ffmpeg:
         _check_no_overwrite_input(cmd)
+        _check_existing_output(cmd)
         STATE.commands.append(_cmdline(cmd))
     if not quiet:
         info(("[dry-run] $ " if STATE.dry_run and is_ffmpeg else "$ ") + _cmdline(cmd))
@@ -346,9 +415,23 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     return True
 
 
+def _limit_for(cmd: Sequence[str]) -> Optional[float]:
+    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
+    short one, ffmpeg the configured one; None means unlimited."""
+    if not _is_ffmpeg(cmd):
+        return PROBE_TIMEOUT if STATE.timeout else None
+    return STATE.timeout or None
+
+
 def _run_captured(cmd: List[str], check: bool) -> subprocess.CompletedProcess:
     """Plain run with stdout/stderr captured."""
-    proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    limit = _limit_for(cmd)
+    try:
+        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
+    except subprocess.TimeoutExpired:
+        _timed_out(cmd, limit or 0)
+    if proc.returncode == 0 and _is_ffmpeg(cmd):
+        _remember_output(cmd)
     if proc.returncode != 0:
         # Cleanup happens for every failed ffmpeg invocation, not just the check=True/_fail()
         # path: a handful of scripts (cut.py, loudness.py, silence.py, sync.py) call run() with
@@ -377,10 +460,17 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
     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)
     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)
         if line.startswith("out_time_us=") or line.startswith("out_time_ms="):
             try:
                 done = int(line.split("=")[1]) / 1_000_000
@@ -391,9 +481,16 @@ def _run_with_progress(cmd: List[str], check: bool) -> subprocess.CompletedProce
                 sys.stderr.write(msg)
                 sys.stderr.flush()
                 last = msg
-    _, err = proc.communicate()
+    try:
+        _, err = proc.communicate(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")
+    if proc.returncode == 0:
+        _remember_output(cmd)
     if proc.returncode != 0:
         _cleanup_partial_output(cmd)
         if check:

package/scripts/_contract.py

@@ -329,7 +329,7 @@ def input_schema(parser: argparse.ArgumentParser) -> Dict[str, Any]:
     props: Dict[str, Any] = {}
     required: List[str] = []
     positional: List[str] = []
-    common = {"dry_run", "json", "progress", "fast"}
+    common = {"dry_run", "json", "progress", "fast", "timeout", "overwrite"}
     for action in parser._actions:
         if isinstance(action, argparse._HelpAction):
             continue
@@ -1037,7 +1037,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "json_output": {
             "success": {"status": "completed", "exit_code": 0, "stdout": "one JSON document (output_schema)"},
             "failure": {"status": "failed", "exit_code": "non-zero (127 when ffmpeg/ffprobe is missing)", "stdout": "{\"status\": \"failed\", \"exit_code\": N, \"error\": {\"kind\": ..., \"message\": ...}, \"commands\": [...]} when --json was given", "stderr": "human-readable message"},
-            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH"},
+            "error_kinds": {"input": "missing or unsuitable input, bad arguments", "ffmpeg": "ffmpeg/ffprobe returned an error (message carries the last stderr lines)", "output": "ffmpeg exited 0 but the artifact is missing, empty or unreadable (an empty file is removed)", "missing_tool": "ffmpeg or ffprobe not on PATH", "timeout": "one ffmpeg/ffprobe run exceeded --timeout (default 1800 s, FFMPEG_SKILL_TIMEOUT) and was killed; partial output removed; exit 124"},
             "success_criterion": "exit 0 AND the output exists AND is non-empty AND ffprobe reads a stream from it; only then is status completed printed and the output probe attached",
         },
         "capabilities": caps,

package/scripts/audio.py

@@ -196,18 +196,29 @@ def main() -> int:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
     if args.fade_out and dur:
         post.append(f"afade=t=out:st={max(0.0, dur - args.fade_out):.3f}:d={args.fade_out:g}")
-    if args.replace and dur:
+    # The audio track is conformed to the source duration whenever it is known: padded with
+    # silence if the graph came out short, trimmed if long. A mixed track can come out a few
+    # hundredths short (amix's dropout_transition, a looped bed's atrim boundary), and with
+    # -shortest below that used to shorten the *video* to match: 12.00 s in, 11.925 s out, four
+    # frames of a stream-copied picture gone (#164). Padding the audio, not cutting the picture,
+    # is the only correct answer for a tool whose contract says the video is never touched.
+    keep_video = has_video and not audio_out
+    if dur and (args.replace or args.music or keep_video):
         post.append(f"apad,atrim=0:{dur:.3f}")
     if post:
         graph.append(f"[{last}]{','.join(post)}[out]")
         last = "out"
 
     cmd = ffmpeg_base() + inputs + ["-filter_complex", ";".join(graph), "-map", f"[{last}]"]
-    if has_video and not audio_out:
+    if keep_video:
         cmd += ["-map", "0:v:0", "-c:v", "copy"]
     elif has_video:
         cmd += ["-vn"]  # audio extension: the picture is dropped, not copied into a container that cannot hold it
-    cmd += audio_codec_for(output, args.bitrate) + ["-shortest", output]
+    cmd += audio_codec_for(output, args.bitrate)
+    if not keep_video:
+        # audio-only outputs: a looped music bed is infinite, -shortest ends the run with the main track
+        cmd.append("-shortest")
+    cmd.append(output)
     run(cmd)
     r = probe(output, role="output")
     a = r["audio"]

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"