ffmpeg-skill 3.6.2 → 3.6.4

package/README.md

@@ -676,6 +676,8 @@ CI (`.github/workflows/ci.yml`) runs on every pull request and on pushes to `mai
 
 **Releasing** is fully automated end to end, including the version number itself — a PR doesn't need to touch `package.json`, `docs/contract.md`, or `CHANGELOG.md` at all. Once a PR merges to `main`, `.github/workflows/release.yml` takes it from there: if nobody bumped the version by hand, it resolves the next version ([.github/scripts/resolve_version.py](.github/scripts/resolve_version.py)) from the labels on every PR merged since the last tag (`minor`/`feature`/`enhancement` → minor, `fix`/`bug`/`patch` → patch, an unlabeled PR defaults to `patch`; a PR whose only labels are `chore`, `ci`, `docs` or `dependencies` is not releasable, so a merge that changes no shipped file releases nothing). Most PRs don't need a label added by hand: `release-drafter.yml`'s `autolabel` job applies one automatically from the PR's title/changed files (`Fix ...` → `fix`, `Add ...`/`feat ...` → `feature`, `docs`/`.md`/`.github/`/`build(deps)` changes → `chore`) as soon as it's opened — add a label yourself only to override that. **A major version is never chosen automatically**: no label rule produces `major`, and the workflow refuses to auto-bump across a major boundary even if someone applies that label — a real major release is a deliberate `package.json` bump in a PR, which the manual path below already handles. It bumps `package.json`, `.claude-plugin/plugin.json`, `docs/contract.md` and `docs/roadmap.md`'s released-version sentence, writes a `CHANGELOG.md` section listing those PRs (and any issues they closed), and pushes that commit to `main` itself. Either way — auto-bumped or hand-bumped in the PR — it then creates the `vX.Y.Z` tag, publishes a GitHub Release with notes extracted from `CHANGELOG.md`'s matching section, and publishes the package to npm. A PR that still wants to write its own version bump and `CHANGELOG.md` prose (e.g. to explain the "why" of a release by hand) can — the automation only fills in when nobody made that call already. A push to `main` with nothing new to release is a no-op. npm publishing needs an `NPM_TOKEN` repo secret (an npm access token with publish rights on this package) — without it the tag and GitHub Release still happen, only the npm step is skipped. A repo that depends on this one (an editing skill, an agent) should pin an `ffmpeg-skill` version by tag or npm version, not by tracking `main` — a merged-but-not-yet-released commit on `main` can be ahead of the last published npm version for the few minutes between merge and this workflow completing.
 
+**A version that was tagged but never reached npm** (the npm step failed; a re-run of that release sees the tag and skips the publish) is finished by dispatching the same workflow on its tag: `gh workflow run release.yml --ref vX.Y.Z -f version=X.Y.Z`. That runs only the workflow's `recover` job. It refuses a version that is not `X.Y.Z`, has no tag, or that npm already has, and a run whose commit is not the tagged one: the npm provenance attestation names the run's commit, so it must be the commit the package is built from. It publishes with `--provenance` under the `latest` dist-tag when the version is above every stable (non-prerelease) version npm has, and under `backport` otherwise, so `latest` never moves back. Then it publishes the `plugin` branch when no commit there is for this version and the branch's tip is older, and the MCP Registry entry when the registry does not list the version (never for a `backport`). The GitHub Release is left as it is. A tag cut before the job was added (#448; every tag up to v3.6.3) has no `recover` job at its commit and cannot be recovered this way.
+
 Contributing a change: see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Docs

package/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 (`2.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`3.6.2`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.4`) | 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`
@@ -149,7 +149,7 @@ JSON would have been rewritten for that. The flat keys, typed per tool in `outpu
   "deprecated": [],
   "removed": [{"what": "...", "since": "1.10.0", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"},
               {"what": "running on FFmpeg 5.x (the requirements.ffmpeg floor)", "since": "2.14.0", "replacement": "FFmpeg 6.1 or later; ...", "removed_in": "3.0.0", "where": "behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "3.6.2", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.4", "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.10 (standard library only)", "ffmpeg": ">=6.1", "ffprobe": ">=6.1"},
@@ -760,6 +760,7 @@ silence a tool reported as fine while another measurement disagreed):
 | `verification[]` step `duration` | `export.py` (a preset with a platform maximum, without `--allow-long`) | the written file's length against the maximum, measured as `check.py` measures it (the container's duration, `tolerance` 0). A length that cannot be read fails the step with `reason: not_measured` |
 | `verification[]` step `duration` (`property: audio_duration`) | `loudness.py` | the output's sound against the input's, to one AAC frame (at least 0.03 s): a levels pass changes no timing. A length that cannot be read fails the step with `reason: not_measured` |
 | `inputs_duration`, `transition_shortening`; step `duration`'s `inputs_total` | `join.py` | the clips' own total and how much the transitions took out of it. `expected_duration` is derived from the transition the join applied, so it cannot show that on its own |
+| `frame_rate`, `clip_frames`, `transition_frames` | `join.py` (video join; added after 3.6.2) | the join's rate as an exact fraction (`"30000/1001"`), the whole frames of it each clip holds (its sound is cut to the samples those frames last), and the frames each transition overlaps (`--duration` rounded to whole frames, at least 1; `0` for `--transition none`). Lengths and xfade offsets are counted in these frames, never in rounded seconds (#455, #468); `inputs_duration` and `expected_duration` are derived from them. A pending `--dry-run` input counts 0 frames |
 | `margins` | `silence.py` | `{lead, tail}`: the seconds of each silence kept before speech starts (`--margin-lead`) and after it ends (`--margin-tail`); both equal `--margin` unless one is named. Absent under `--filler` with neither `--speech-aware` nor a sentence flag, which removes no silences |
 | `silence_positions`, `sentence` | `silence.py --sentence-min-silence` / `--sentence-margin-tail` | per entry of `silences`, `sentence_end` when the transcript word before it ends in sentence-final punctuation, else `inside`; and `{min_silence, margin_tail, source, word_timings, sentence_end_words, silences}`. `sentence_end_words: 0` means the transcript had no such punctuation, so every silence used `--min-silence` and `--margin-tail` (warning `sentence_ends_not_found`) |
 | `silence_kinds`, `silence_breakdown` | `silence.py` | per detected silence, `digital` (at or below -90 dBFS) or `below_threshold` (quiet sound under `--threshold`), and the count and seconds of each with the level that defines it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.2",
+  "version": "3.6.4",
   "mcpName": "io.github.kajisho5/ffmpeg-skill",
   "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": [

package/scripts/_common/runner.py

@@ -10,6 +10,7 @@ import json
 import os
 import platform
 import argparse
+import contextlib
 import re
 import shutil
 import subprocess
@@ -329,7 +330,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
+    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "checked", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
                  "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs",
                  "source_timecode", "smpte_hint", "delivered", "expected_timecode")
@@ -356,6 +357,7 @@ class Context:
         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
+        self.checked: dict = {}                      # real output path -> owned_identity() at its output check (None: absent), or as this run left it; refuse_changed_output() compares it at the replace
         self.plan: Optional[str] = None              # --plan FILE: write the dry-run as a plan document (implies --dry-run)
         self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
         self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
@@ -1226,6 +1228,9 @@ def refuse_existing_outputs(paths: Sequence[str]) -> None:
             real = os.path.realpath(output)
         except OSError:
             continue
+        # what the decision below is about: compared again where the file is replaced
+        # (refuse_changed_output), so one put there during the run is not replaced unasked
+        _record_checked(output, _checked_state(output) if exists else None)
         if not exists or real in STATE.written:
             continue
         size = mtime_ns = None
@@ -1259,11 +1264,163 @@ def _remember_output(cmd: Sequence[str]) -> None:
     output = cmd[-1]
     if output == "-" or output.startswith("pipe:") or output.startswith("-"):
         return
+    _remember_identity(output)
+    report_committed(output)
+
+
+def _checked_key(path: str) -> str:
+    """The place a check is about: `path`'s directory resolved, its last component as named, so a
+    symlink created at an absent target since the check is still that target (#480 review)."""
+    full = os.path.abspath(path)
+    return os.path.join(os.path.realpath(os.path.dirname(full)), os.path.basename(full))
+
+
+def _parent(path: str) -> str:
+    return os.path.realpath(os.path.dirname(os.path.abspath(path)))
+
+
+def _checked_state(path: str) -> "Optional[Tuple[Optional[Dict[str, int]], bool]]":
+    """What is at `path` now: (owned_identity, is a symlink), or None when nothing is there."""
+    if not os.path.lexists(path):
+        return None
+    return (owned_identity(path), os.path.islink(path))
+
+
+def _record_checked(path: str, state: Any) -> None:
+    """Record what a check (or this run's own write) found at `path`, with the directory the path
+    resolved to then, under the resolved place and under the path as named: a directory symlink
+    switched since is then found by the name and refused, not looked up as a place never checked."""
+    entry = (_parent(path), state)
+    key = _checked_key(path)
+    STATE.checked[key] = entry
+    STATE.checked[os.path.abspath(path)] = entry
+    # the same file reached by another spelling of its path (a write through the resolved name
+    # after a check through a link) is the same record: a later replace through either matches
+    # -- only a record made in the same directory: one whose link has been switched since keeps
+    # what it saw, so the replace through it is still refused
+    for named in [k for k in STATE.checked if k != key]:
+        try:
+            if _checked_key(named) == key and STATE.checked[named][0] == entry[0]:
+                STATE.checked[named] = entry
+        except OSError:
+            pass
+
+
+def _remember_identity(path: str) -> None:
+    """Count `path` as this run's own and record the identity this run left it with, which a
+    later replace of it compares (refuse_changed_output)."""
     try:
-        STATE.written.add(os.path.realpath(output))
+        real = os.path.realpath(path)
+        STATE.written.add(real)
     except OSError:
-        pass
-    report_committed(output)
+        return
+    _record_checked(path, _checked_state(path))
+
+
+def refuse_changed_output(path: str, cleanup: "Optional[Callable[[], None]]" = None) -> None:
+    """Refuse to replace `path` when it is no longer the file its output check decided about.
+
+    refuse_existing_outputs() decides before the encode whether an existing target may be
+    replaced (--overwrite, this run's own file, batch.py's own delivery) and records the
+    target's identity (owned_identity(), None when absent); _remember_identity() records it again
+    when this run writes it. Called under the output's lock just before the replace: a file
+    another process put there meanwhile -- a different file at an existing target, or one at a
+    target that was absent -- is refused (`kind: input`, `reason: output_exists`) and `cleanup`
+    removes the new output's temp, unless --overwrite gave consent to replace whatever is at the
+    path (as batch.py's deliver() does). A path with no recorded check is left alone."""
+    if STATE.overwrite or not path or path == "-" or path.startswith("pipe:") or path.startswith("-"):
+        return
+    try:
+        key, named, real = _checked_key(path), os.path.abspath(path), os.path.realpath(path)
+        # the name first: a resolved place another path also reached says nothing about this one
+        recorded = STATE.checked.get(named) or STATE.checked.get(key)
+        if recorded is None:
+            return
+        (parent_then, expected), parent_now, now = recorded, _parent(path), _checked_state(path)
+    except OSError:
+        return
+    if now == expected and parent_now == parent_then:
+        return
+    if cleanup:
+        cleanup()
+    if parent_now != parent_then:
+        why = (f"is now in another directory ({parent_now!r}, checked in {parent_then!r}): a directory "
+               "link on its path was changed during the run")
+    elif expected is None:
+        why = "did not exist when the run checked it and another process created it during the run"
+    elif now is None:
+        why = "was removed or replaced by something that is not a regular file during the run"
+    else:
+        why = "changed during the run (another process wrote or replaced it after the output check)"
+    refuse("input", "output_exists",
+           f"refusing to replace {path!r}: it {why}; the new output was not put there. Pass --overwrite to "
+           "replace it anyway, or choose another -o path",
+           hint="pass --overwrite, or choose another -o path",
+           outputs=[{"path": path, "resolved": real, "changed_during_run": True,
+                     "expected": expected, "found": now}])
+
+
+def _remove_quietly(path: Optional[str]) -> None:
+    if path:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+
+
+def replace_checked(tmp: str, final: str) -> None:
+    """os.replace(tmp, final) for a file a tool writes itself (a time map, a normalised export):
+    under `final`'s output lock, after refuse_changed_output(), which removes `tmp` when it
+    refuses."""
+    replace_checked_together([(tmp, final)])
+
+
+def replace_checked_together(pairs: "Sequence[Tuple[str, str]]") -> None:
+    """Replace each (tmp, final) only once every final has passed refuse_changed_output(), all
+    under their output locks: files that belong together (a fill and its key). A file already at a
+    final is moved aside first and put back if a later replace fails, so a failed pair leaves
+    what was there. Every tmp is removed on a refusal, a refused lock or a failed replace (#480
+    review)."""
+    def cleanup() -> None:
+        for tmp, _final in pairs:
+            _remove_quietly(tmp)
+    aside: List[Tuple[str, Optional[str]]] = []  # (final, where its earlier file went, or None)
+    try:
+        with contextlib.ExitStack() as stack:
+            for final in sorted({final for _tmp, final in pairs}):
+                stack.enter_context(_OutputLock(final))
+            for _tmp, final in pairs:
+                refuse_changed_output(final, cleanup)
+            try:
+                for tmp, final in pairs:
+                    kept = None
+                    if len(pairs) > 1 and os.path.lexists(final):
+                        d, base = os.path.split(final)
+                        stem, ext = os.path.splitext(base)
+                        kept = reserve_sibling(d, stem, ext, "keep")
+                        os.replace(final, kept)
+                    try:
+                        os.replace(tmp, final)
+                    except BaseException:
+                        if kept:
+                            os.replace(kept, final)
+                        raise
+                    aside.append((final, kept))  # replaced: undone below if a later one fails
+            except BaseException:
+                for final, kept in reversed(aside):
+                    if kept:
+                        try:
+                            os.replace(kept, final)
+                        except OSError:
+                            pass
+                    elif os.path.exists(final):
+                        _remove_quietly(final)
+                raise
+            for _final, kept in aside:
+                _remove_quietly(kept)
+    except BaseException:
+        cleanup()
+        raise
 
 
 # set only by batch.py for the steps it runs: the path of a JSON file {"replaceable": {real path:
@@ -1376,10 +1533,7 @@ def remember_written(*paths: Optional[str]) -> None:
     as replacing someone else's file (#415)."""
     for path in paths:
         if path and os.path.isfile(path):
-            try:
-                STATE.written.add(os.path.realpath(path))
-            except OSError:
-                pass
+            _remember_identity(path)
             report_committed(path)
 
 
@@ -1638,6 +1792,9 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
     if is_ffmpeg:
         flush_drawtext_textfiles(cmd)
     with _OutputLock(cmd[-1] if is_ffmpeg else "-"):
+        if is_ffmpeg:
+            # a file put at the output since the check above is not ours to stage over
+            refuse_changed_output(cmd[-1])
         exec_cmd, final, tmp = _stage_existing_output(cmd) if is_ffmpeg else (list(cmd), None, None)
         def even_retry(proc: subprocess.CompletedProcess, ran: List[str]) -> "Tuple[subprocess.CompletedProcess, List[str]]":
             """An attempt that failed on odd dimensions, run again with an even scale: after the
@@ -1694,6 +1851,9 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
             _fail(tried, proc.returncode, proc.stderr or "", ctx=ctx, retried=retried)
         if final and tmp:
             if proc.returncode == 0:
+                # still under the lock: the target the check let this run replace, not a file
+                # another process put there during the encode
+                refuse_changed_output(final, lambda: _cleanup_partial_output(exec_cmd))
                 try:
                     os.replace(tmp, final)
                 except OSError as e:
@@ -2104,6 +2264,9 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
     with _OutputLock(dst):
+        # under the lock: the target the check above decided about, not one put there since
+        # (`src` is the caller's to remove, as on every other refusal)
+        refuse_changed_output(dst)
         if move:
             try:
                 os.replace(src, dst)
@@ -2114,6 +2277,7 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
         tmp = None
         try:
             tmp = copy_to_sibling(src, dst)
+            refuse_changed_output(dst, lambda: _remove_quietly(tmp))
             os.replace(tmp, dst)
         except OSError as e:
             if tmp:

package/scripts/_contract.py

@@ -770,6 +770,9 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "join":
         extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},
                  "expected_duration": {"type": ["number", "null"], "description": "clip lengths minus the transitions; null under --dry-run while an input is pending (its length is unknown)"},
+                 "frame_rate": {"type": "string", "description": "video mode only: the join's frame rate as an exact fraction (\"30000/1001\"), the rate every clip length and xfade offset is counted in"},
+                 "clip_frames": {"type": "array", "items": {"type": "integer"}, "description": "video mode only: per clip, the whole frames of frame_rate it holds in the join (its picture's, or the frames that cover a sound running more than a frame past it); its sound is cut to the samples those frames last. A pending --dry-run input counts 0"},
+                 "transition_frames": {"type": "integer", "description": "video mode only: the frames each xfade/acrossfade overlaps (--duration rounded to whole frames, at least 1; 0 for --transition none)"},
                  "sample_rate": {"type": "integer", "description": "audio mode only"}, "channels": {"type": "integer", "description": "audio mode only"},
                  "video": {"type": "boolean", "description": "false in audio mode: the output has no video stream"},
                  "skipped": {"type": "array", "description": "inputs --on-missing skip left out: [{index, path, reason}] ([] when none were)"},

package/scripts/export.py

@@ -51,7 +51,7 @@ from _common import STATE, run_analysis, add_common, apply_common, bt709_label_f
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
 from _common.probe import square_pixels, square_pixels_note
-from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, replace_checked, replace_checked_together, reserve_sibling, run_analysis as _run_analysis, subtitle_codec_for
 from _common.emit import file_identity
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
@@ -209,23 +209,32 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     # the fill is always written to a hidden sibling and moved into place only after the encode
     # succeeds: run() stages and cleans up only ffmpeg's last output (the key), so a failed encode
     # left a partial new fill (the retry was refused as output_exists) or truncated an existing one
-    fill_tmp = None
+    # the key is staged the same way, and both are committed together: a fill refused at its
+    # replace never leaves a new key beside it (which a retry would then refuse as existing)
+    fill_tmp = key_tmp = None
     if not STATE.dry_run:
         d, base = os.path.split(output)
         stem, ext = os.path.splitext(base)
         fill_tmp = reserve_sibling(d, stem, ext, "fill")  # created exclusively: never through a planted link
+        kd, kbase = os.path.split(key)
+        kstem, kext = os.path.splitext(kbase)
+        key_tmp = reserve_sibling(kd, kstem, kext, "key")
+        # this run's own placeholder: run()'s output check must not refuse it as someone's file
+        STATE.written.add(os.path.realpath(key_tmp))
     cmd += (p["audio"] if has_audio else ["-an"]) + [fill_tmp or output]
-    cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key]
+    cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key_tmp or key]
     try:
         run(cmd)
-        if fill_tmp:
-            os.replace(fill_tmp, output)
+        if fill_tmp and key_tmp:
+            # under both locks, and only while each is the file guard_sidecar() decided about
+            replace_checked_together([(fill_tmp, output), (key_tmp, key)])
     finally:
-        if fill_tmp:
-            # the command is recorded with the path the caller asked for, not the temp name
-            STATE.commands[:] = [c.replace(fill_tmp, output) for c in STATE.commands]
-            if os.path.exists(fill_tmp):
-                os.remove(fill_tmp)
+        for tmp, final in ((fill_tmp, output), (key_tmp, key)):
+            if tmp:
+                # the command is recorded with the path the caller asked for, not the temp name
+                STATE.commands[:] = [c.replace(tmp, final) for c in STATE.commands]
+                if os.path.exists(tmp):
+                    os.remove(tmp)
     remember_written(output, key)
     extra: Dict[str, object] = {"alpha_mode": args.alpha_mode or "straight", "key": {"output": key}}
     # a fill and a key for a switcher carry the picture and the sound; the source's subtitle and
@@ -746,7 +755,8 @@ def main() -> int:
                     die(f"--normalize: loudness.py failed: {why} ({kept_clause()})",
                         code=child_exit_code(child, proc.returncode) if proc.returncode else 1,
                         kind=err.get("kind") or "ffmpeg", output=output, hint=err.get("hint"))
-                os.replace(tmp, output)
+                # the export this run wrote, unless another process replaced it during the pass
+                replace_checked(tmp, output)
                 m = measure_loudness(output)
                 if not m:
                     # the file changed: the measurement before --normalize no longer describes it

package/scripts/join.py

@@ -36,9 +36,11 @@ audio stream is never silent.
 """
 import argparse
 import json
+import math
 import os
 import tempfile
 import sys
+from fractions import Fraction
 from typing import Any, Dict, List, Optional, Tuple
 
 from _common.probe import SILENT_PEAK_DBFS, signatures_match, stream_signature
@@ -46,6 +48,7 @@ from _common import STATE, AUDIO_MEDIA_EXT, concat_list_line, guard_sidecar, pla
 from _common.emit import note, warn
 from _common.decision import av_clip_length, av_trim, stream_starts
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.timeline import exact_rate
 
 TRANSITIONS = ["fade", "dissolve", "wipeleft", "wiperight", "wipeup", "wipedown", "slideleft", "slideright",
                "circleopen", "circleclose", "fadeblack", "fadewhite", "smoothleft", "smoothright", "radial", "none"]
@@ -112,6 +115,81 @@ def clip_length(meta: Dict[str, Any], fps: float) -> float:
     return av_clip_length(meta, fps)
 
 
+# the video join's sound rate (every clip is resampled to it before the trims)
+JOIN_AUDIO_RATE = 48000
+
+
+def output_rate(fps: float, first: Dict[str, Any], asked: bool) -> Fraction:
+    """The join's frame rate as an exact fraction: the first clip's own r_frame_rate/avg_frame_rate
+    when `fps` is that clip's (30000/1001, not 29.97), else the NTSC fraction or the plain one
+    `fps` names (timeline.exact_rate). Every clip length, offset and sound length is counted in
+    frames of this rate, so the graph's fps filter runs at the same fraction."""
+    if not asked:
+        for key in ("r_frame_rate", "avg_frame_rate"):
+            try:
+                q = Fraction(str(first.get(key) or ""))
+            except (ValueError, ZeroDivisionError):
+                continue
+            # the declared rate also wins when the average was taken over a length that leaves out
+            # the last frame's duration (#475: 5 frames in 0.1333 s read 37.5 fps, and the whole
+            # join ran at 75/2)
+            if 0 < q <= 240 and (abs(float(q) - fps) < 1e-3 or short_last_frame(first, q)):
+                return q
+    return exact_rate(fps)
+
+
+def short_last_frame(video: Optional[Dict[str, Any]], q: Fraction) -> bool:
+    """Whether a picture's duration is its frame count less one frame at rate `q`: a container
+    that stores no duration for the last frame (MOV written with -fps_mode passthrough, seen on
+    FFmpeg 7.1) reads 5 frames as 0.1333 s at 30 fps (#475)."""
+    v = video or {}
+    nb, dur = v.get("nb_frames"), v.get("duration")
+    if not nb or nb < 2 or not dur or q <= 0:
+        return False
+    step = float(1 / q)
+    return abs(dur - (nb - 1) * step) < 0.25 * step and abs(dur - nb * step) > 0.25 * step
+
+
+def with_whole_picture(meta: Dict[str, Any], q: Fraction) -> Dict[str, Any]:
+    """`meta` with its picture counted as every frame it holds when its duration leaves out the
+    last one (short_last_frame), so the clip-length rule does not read the sound as running a
+    frame past the picture and hold the clip longer (#475). Other clips are returned as they are."""
+    v = meta.get("video") or {}
+    # each clip at its OWN declared rate: at the join's rate a complete 30 fps clip of 5 frames
+    # (5/30 s) also equals 4 frames at --fps 24 and would be stretched to 5/24 s
+    try:
+        own = Fraction(str(v.get("r_frame_rate") or ""))
+    except (ValueError, ZeroDivisionError):
+        own = q
+    if not 0 < own <= 240:
+        own = q
+    if not short_last_frame(v, own):
+        return meta
+    return dict(meta, video=dict(v, duration=float(v["nb_frames"] / own)))
+
+
+def clip_frames(meta: Dict[str, Any], length: float, q: Fraction) -> int:
+    """How many frames of rate `q` a clip of `length` seconds (clip_length) holds in the join: its
+    picture's frames, or, when the clip lasts as long as its sound, enough frames to cover that
+    sound (narration is never cut; a hundredth of a frame is rounding, not sound). A pending
+    dry-run stub's 0 s stays 0; a measured clip holds at least one frame (#455: a length in
+    milliseconds rounded up started every next clip late, and the errors added up)."""
+    exact = length * q.numerator / q.denominator
+    vlen = (meta.get("video") or {}).get("duration") or 0.0
+    frames = math.ceil(exact - 0.01) if vlen and length > vlen else round(exact)
+    return frames if meta.get("dry_run") else max(1, frames)
+
+
+def frame_time(frames: int, q: Fraction) -> str:
+    """The time of frame `frames` at rate `q` in seconds, rounded down to the microsecond: never
+    after that frame's own timestamp, so a filter that starts on the first frame at or after it
+    (xfade's offset) starts on that frame and not the next (#468: 2.566667 written 2.567 started
+    the transition a frame late). Trailing zeros are dropped (0.5, not 0.500000)."""
+    us = (frames * q.denominator * 1_000_000) // q.numerator
+    text = f"{us // 1_000_000}.{us % 1_000_000:06d}".rstrip("0").rstrip(".")
+    return text or "0"
+
+
 def find_duplicates(paths: List[str]) -> List[Dict[str, Any]]:
     """Every path (compared by its resolved absolute form) listed more than once, with the 0-based
     list positions it appears at. A warning, not a refusal: repeating a clip can be intentional."""
@@ -543,6 +621,10 @@ def main() -> int:
     apply_common(args)
     if args.fps is not None and args.fps <= 0:
         die(f"--fps must be positive, got {args.fps:g}")
+    # nan and inf are refused by the parser (finite_float); a negative length was taken as the
+    # one-frame minimum and the join succeeded with a transition nobody asked for
+    if args.duration < 0:
+        die(f"--duration must be 0 or more seconds, got {args.duration:g}")
 
     if args.list:
         if args.inputs:
@@ -666,6 +748,9 @@ def main() -> int:
         w, h = fw, fh
     fps = args.fps or first.get("fps") or 30.0
     fps = round(fps) if abs(fps - round(fps)) < 0.02 else fps
+    # the exact rate every length below is counted in (30000/1001, not 29.97)
+    rate_q = output_rate(fps, first, bool(args.fps))
+    fps = float(rate_q)
     w, h = w - (w % 2), h - (h % 2)
     note_short_segments(args.inputs, metas, MIN_SEGMENT_FRAMES / fps, f"{MIN_SEGMENT_FRAMES} frames at {fps:g} fps")
     durs = [m.get("duration") or 0.0 for m in metas]
@@ -675,11 +760,37 @@ def main() -> int:
     # its picture and its sound together. The plain cut used to take the raw streams, and a sound
     # past the picture (a music bed padded to the container, even a 20 ms AAC tail) left a hole in
     # the video there.
-    lens = [clip_length(m, fps) for m in metas]
+    # Each length is a whole number of frames of the output rate, and each sound length the
+    # samples those frames last (#455): a length in milliseconds rounded 5 frames at 30 fps
+    # (0.166667 s) up to 0.167 s, the concat filter started the next clip after it, and 60 such
+    # clips left one-frame holes from about 8 s on. Sample counts come from the running frame
+    # total, so the sound never drifts from the picture by more than one sample.
+    lmetas = [with_whole_picture(m, rate_q) for m in metas]
+    frames = [clip_frames(m, clip_length(m, fps), rate_q) for m in lmetas]
+    # the transition is a whole number of frames too, so xfade's offsets (and acrossfade's
+    # overlap) land on frames of the output rate (#468). A transition is at least one frame:
+    # --duration 0 used to build acrossfade=ns=0, which FFmpeg refuses
+    tframes = max(1, round(d * fps)) if args.transition != "none" else 0
+    d = tframes / fps
+    lens = [f / fps for f in frames]
     place_silent(lens, d)
-    for p, dur in zip(args.inputs, lens):
-        if d and dur <= d * 2 and not STATE.dry_run:
-            die(f"{p} is only {dur:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+    for p, nf in zip(args.inputs, frames):
+        if d and nf <= tframes * 2 and not STATE.dry_run:
+            die(f"{p} is only {nf / fps:.2f}s, too short for a {d:.2f}s transition; shorten --duration")
+    # every sample boundary is a frame position of the OUTPUT rounded once: clip i spans output
+    # frames [start_i, start_i + frames_i) and overlaps the clip before it over [start_i,
+    # start_i + tframes), so its samples and each overlap's are differences of rounded
+    # cumulative positions and their sum telescopes to the output's own length. Rounding each
+    # overlap on its own (14414.4 samples -> 14414 at 30000/1001 and 9 frames) left the sound
+    # 0.4 samples longer per transition.
+    def at(frame: int) -> int:
+        return round(frame * JOIN_AUDIO_RATE / rate_q)
+    starts, start = [], 0
+    for i, nf in enumerate(frames):
+        starts.append(start)
+        start += nf - tframes
+    samples = [at(s0 + nf) - at(s0) for s0, nf in zip(starts, frames)]
+    overlaps = [at(s0 + tframes) - at(s0) for s0 in starts]
 
     cmd = ffmpeg_base()
     extra_inputs: List[str] = []
@@ -745,7 +856,10 @@ def main() -> int:
     if len(set(chans)) > 1:
         info(f"channel counts differ ({', '.join(str(c) for c in chans)}); every clip becomes {layout}")
     for i in range(n):
-        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={fps:g},format={pixfmt},settb=AVTB[v{i}]")
+        # the fps filter's time base is one frame (1/rate), so every timestamp downstream is a
+        # frame number and an offset in seconds is rounded to a whole frame, never a microsecond
+        # off it on any FFmpeg (AVTB left xfade to compare microseconds)
+        parts.append(f"[{i}:v]{convert[i]}{geo(i)},setsar=1,setpts=PTS-STARTPTS,fps={rate_q.numerator}/{rate_q.denominator},format={pixfmt}[v{i}]")
         # the sound is shifted by the picture's start, not to its own (#409): #338 started each
         # clip's picture at 0, and a per-stream PTS-STARTPTS then moved a sound that starts 0.3 s
         # after its picture 0.3 s early. Sound before the first frame is dropped and a late sound
@@ -755,23 +869,29 @@ def main() -> int:
 
     # pad the shorter stream to the clip's length: the audio with silence, the picture by holding
     # its last frame, then cut both there -- each clip boundary is then the same for both chains
+    # -- by frame and by sample, never by rounded seconds (#455)
     for i in range(n):
-        vlen = (metas[i].get("video") or {}).get("duration") or lens[i]
-        hold = f"tpad=stop_mode=clone:stop_duration={lens[i] - vlen:.3f}," if lens[i] > vlen else ""
-        parts.append(f"[v{i}]{hold}trim=duration={lens[i]:.3f}[vp{i}]")
-        parts.append(f"[a{i}]apad=whole_dur={lens[i]:.3f},atrim=duration={lens[i]:.3f}[ap{i}]")
+        vlen = (lmetas[i].get("video") or {}).get("duration") or lens[i]
+        have = round(vlen * fps)
+        # one frame more than the gap is held, and the trim cuts at the clip's last frame
+        hold = f"tpad=stop_mode=clone:stop={frames[i] - have + 1}," if frames[i] > have else ""
+        parts.append(f"[v{i}]{hold}trim=end_frame={frames[i]}[vp{i}]")
+        parts.append(f"[a{i}]apad=whole_len={samples[i]},atrim=end_sample={samples[i]}[ap{i}]")
     if args.transition == "none":
         chain = "".join(f"[vp{i}][ap{i}]" for i in range(n))
         parts.append(f"{chain}concat=n={n}:v=1:a=1[vout][aout]")
     else:
         vprev, aprev = "vp0", "ap0"
-        offset = 0.0
+        start = 0
         for i in range(1, n):
-            offset += lens[i - 1] - d
+            # clip i starts on frame `start` of the output; xfade starts on the first frame at or
+            # after its offset, so the offset is that frame's time rounded down (#468)
+            start += frames[i - 1] - tframes
             vout = f"vx{i}" if i < n - 1 else "vout"
             aout = f"ax{i}" if i < n - 1 else "aout"
-            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={d:g}:offset={offset:.3f}[{vout}]")
-            parts.append(f"[{aprev}][ap{i}]acrossfade=d={d:g}:c1=tri:c2=tri[{aout}]")
+            parts.append(f"[{vprev}][vp{i}]xfade=transition={args.transition}:duration={frame_time(tframes, rate_q)}"
+                         f":offset={frame_time(start, rate_q)}[{vout}]")
+            parts.append(f"[{aprev}][ap{i}]acrossfade=ns={overlaps[i]}:c1=tri:c2=tri[{aout}]")
             vprev, aprev = vout, aout
 
     # A pending input's stub is unmeasured (0x0, 0 fps, 0 s -- #77 keeps it honest rather than
@@ -784,7 +904,7 @@ def main() -> int:
                            "by its measured length")
     elif not d and any(m.get("dry_run") for m in metas):
         # the plain cut trims/holds every clip to clip_length too (2.4.1), so a pending clip's
-        # planned trim=duration=0.000 is the stub's placeholder, not the cut
+        # planned trim=end_frame=0 is the stub's placeholder, not the cut
         STATE_NOTES.append("the planned trim lengths count each pending input as 0 s long: a real run trims "
                            "or holds it to its measured length")
     output = args.output or default_output(args.inputs[0], "joined", "mp4")
@@ -818,6 +938,7 @@ def main() -> int:
     info(f"wrote {output} ({fmt_secs(measured)}, {expected_text(expected)}, {w}x{h} @ {fps:g}fps, {n} clips, {args.transition})")
     overlap = overlap_report(lens, expected)
     emit(output, mode="video", **overlap, **reported(), clips=n, transition=args.transition, expected_duration=expected,
+         frame_rate=f"{rate_q.numerator}/{rate_q.denominator}", clip_frames=frames, transition_frames=tframes,
          verification=verification, expect_streams={"video": 1, "audio": 1}, stream_reference=metas,
          audio_substituted=substituted,
          dropped_non_av_streams=any(m.get("subtitle_streams") or m.get("data_streams") for m in metas))

package/scripts/sequence.py

@@ -18,11 +18,13 @@ import argparse
 import re
 import sys
 import tempfile
+from fractions import Fraction
 from pathlib import Path
 
 from _common import add_common, apply_common, default_output, die, emit, ffmpeg_base, info, probe, run, video_args, X264_PRESETS, concat_list_line, fmt_secs
 from _common.emit import note, warn
 from _common.probe import display_size, square_pixels_note
+from _common.timeline import TimelineError, exact_rate
 
 
 def even(n: float) -> int:
@@ -34,6 +36,30 @@ def _concat_list_line(path: Path) -> str:
     return concat_list_line(str(path))
 
 
+def frame_durations(count: int, rate: Fraction) -> list:
+    """The concat-list duration of each of `count` frames at `rate`, in whole microseconds: frame
+    i lasts round(start(i+1)) - round(start(i)) with start(i) = i/rate, each position rounded
+    once, so the demuxer's running sum is frame i's exact start to within half a microsecond at
+    every frame (#474: 1/30 written 0.033333 fell 3.3e-7 s behind per frame, half a frame after
+    about 50,000 frames)."""
+    def at(i: int) -> int:
+        return round(i * 1_000_000 / rate)
+    return [at(i + 1) - at(i) for i in range(count)]
+
+
+def concat_list(frames: list, rate: Fraction) -> str:
+    """The concat-demuxer list for `frames` (paths) shown one frame each at `rate`."""
+    lines = []
+    framerate = f"option framerate {rate.numerator}/{rate.denominator}"
+    for f, us in zip(frames, frame_durations(len(frames), rate)):
+        lines.append(_concat_list_line(f))
+        lines.append(framerate)
+        lines.append(f"duration {us // 1_000_000}.{us % 1_000_000:06d}")
+    lines.append(_concat_list_line(frames[-1]))  # concat demuxer: last entry's duration is ignored, so repeat it
+    lines.append(framerate)
+    return "\n".join(lines)
+
+
 def natural_key(name: str) -> list:
     """img2 < img10: digit runs compare as numbers, the rest case-insensitively."""
     return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", name)]
@@ -70,6 +96,10 @@ def main() -> int:
 
     if args.fps <= 0:
         die("--fps must be > 0")
+    try:
+        rate = exact_rate(args.fps)  # 29.97 is 30000/1001, as every other tool reads it
+    except TimelineError as exc:
+        die(f"--fps: {exc}")
     directory = Path(args.dir)
     if not directory.is_dir():
         die(f"--dir not found or not a directory: {args.dir}")
@@ -123,27 +153,20 @@ def main() -> int:
         out_w, out_h = even(sw), even(sh)
 
     output = args.output or default_output(str(directory).rstrip("/\\") or "sequence", "sequence", "mp4")
-    frame_duration = 1.0 / args.fps
-
     with tempfile.TemporaryDirectory(prefix="ffmpeg-skill-sequence-") as tmp:
         list_path = Path(tmp) / "frames.txt"
-        lines = []
-        for f in frames:
-            lines.append(_concat_list_line(f.resolve()))
-            lines.append(f"duration {frame_duration:.6f}")
-        lines.append(_concat_list_line(frames[-1].resolve()))  # concat demuxer: last entry's duration is ignored, so repeat it
-        list_path.write_text("\n".join(lines), encoding="utf-8")
+        list_path.write_text(concat_list([f.resolve() for f in frames], rate), encoding="utf-8")
 
         cmd = ffmpeg_base() + ["-f", "concat", "-safe", "0", "-i", str(list_path)]
-        vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={args.fps:g}"]
+        vf = [f"scale={out_w}:{out_h}", "setsar=1", f"fps={rate.numerator}/{rate.denominator}"]
         cmd += ["-vf", ",".join(vf)]
         # RGB (PNG) frames are converted to the BT.709 the line is tagged with (the first frame's probe)
         cmd += video_args(None, args.crf, args.preset, source=frame_meta)
         # The concat demuxer's trailing repeated-last-file trick (needed so the last real file's
         # duration line takes effect) has been observed to produce an extra frame's worth of
         # duration on some ffmpeg builds -- force the exact intended length rather than trust it.
-        total_duration = len(frames) * frame_duration
-        cmd += ["-t", f"{total_duration:.6f}", "-an", output]
+        total_us = sum(frame_durations(len(frames), rate))
+        cmd += ["-t", f"{total_us // 1_000_000}.{total_us % 1_000_000:06d}", "-an", output]
         run(cmd)
 
     result = probe(output, role="output")

package/scripts/silence.py

@@ -28,6 +28,7 @@ from _common import (filler_spans, FILLER_WORDS, FILLER_AMBIGUOUS, FILLER_DISCOU
                      FILLER_PAD, read_text_or_die)
 from _common import asr as _asr
 from _common.emit import warn
+from _common.runner import replace_checked
 from _common import guard_sidecar, refuse_existing_outputs, refuse_output_is_input, _check_output_path
 from _common.emit import refuse
 from _common import detect_silences as detect, STATE, add_common, apply_common, default_output, die, emit, info, is_audio_output, print_json, probe, X264_PRESETS, measured_level_dbfs, fmt_secs
@@ -261,7 +262,8 @@ def write_time_map(path: str, tm: Dict[str, Any]) -> None:
         mask = os.umask(0)  # mkstemp makes the file 0600; give the map the mode open() would have
         os.umask(mask)
         os.chmod(tmp, 0o666 & ~mask)
-        os.replace(tmp, path)
+        # under the map's lock, and only while it is the file refuse_existing_outputs() decided about
+        replace_checked(tmp, path)
     except BaseException:
         try:
             os.remove(tmp)