ffmpeg-skill 3.6.0 → 3.6.1

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.0`) | any release |
+| `skill.version` | the npm / package.json version (`3.6.1`) | 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.0", "execution_mode": "local", "kind": "execution",
+  "skill": {"id": "ffmpeg-skill", "version": "3.6.1", "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"},
@@ -897,7 +897,7 @@ here claims otherwise until real exit-code/stderr sniffing exists to back that u
 A refusal also carries `error.reason`, a stable snake_case code for *why*
 (`contract --json` → `json_output.error_reasons` lists them: `output_exists`, `output_is_input`,
 `output_is_directory`, `output_dir_missing`, `output_dir_not_writable`, `output_locked`,
-`media_path_is_url`, `media_path_is_playlist` (an HLS or ffconcat playlist given as media),
+`media_path_is_url` (`subfile,...:` included), `media_path_is_playlist` (an HLS, DASH, IMF or ffconcat playlist given as media, DASH and IMF told by content whatever the file is called), `media_path_has_line_break` (a path with a line break, which a concat list cannot hold),
 `output_looks_like_option` (an output starting with `-`, other than `-` for stdout), `output_path_taken` (two files one run writes share a path), `media_path_not_a_file` (a FIFO or device as input), `silence.py --timemap`'s `timemap_path_taken`, `join.py --copy`'s `join_copy_mismatch`,
 `render.py`'s `plan_*` reasons, `--codec av1`/`prores`'s `encoder_missing` and
 `encoder_list_unreadable`, and `--transcribe`'s `asr_engine_missing`, `no_speech`, `engine_failed`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "3.6.0",
+  "version": "3.6.1",
   "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/_ass_overlay.py

@@ -54,7 +54,7 @@ def ass_time(sec: float) -> str:
 
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = str(hex_rgb).lstrip("#")
-    if len(h) != 6:
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
         raise ValueError(f"colour must be RRGGBB hex, got '{hex_rgb}'")
     return f"&H{alpha:02X}{h[4:6]}{h[2:4]}{h[0:2]}".upper()
 

package/scripts/_common/color.py

@@ -312,13 +312,20 @@ def fold_bt709_matrix(cmd: Sequence[str]) -> List[str]:
     return out[:at] + ["-vf", conv] + out[at:]
 
 
+_HEX6 = re.compile(r"^[0-9A-Fa-f]{6}$")
+
+
 def color_hex(value: str) -> str:
-    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'."""
+    """Normalise '#ffd200' / 'ffd200' / '0xFFD200' to 'FFD200'. Six hex digits only: the result is
+    written into libass styles and drawtext/color options, so a six-letter colour name ("yellow")
+    used to pass the length check and draw black, reported verified, and a quote or comma reached
+    the filter graph."""
     v = str(value).strip().lstrip("#")
     if v.lower().startswith("0x"):
         v = v[2:]
-    if len(v) != 6:
-        die(f"colour must be RRGGBB, got '{value}'")
+    if not _HEX6.match(v):
+        die(f"colour must be six hex digits RRGGBB (e.g. FFD200 or #ffd200), got '{value}'; colour names are not "
+            "accepted here")
     return v.upper()
 
 

package/scripts/_common/decision.py

@@ -148,7 +148,15 @@ def concat_list_line(path: str) -> str:
     """One `file '...'` line for the concat demuxer. The demuxer reads backslash as an escape
     inside the quoted form, so a Windows path (C:\\Users\\...\\part000.mp4) must be written
     with forward slashes -- ffmpeg opens either spelling on Windows -- and a single quote in the
-    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py."""
+    name is closed, escaped and reopened. Shared by cut.py (multi-segment) and sequence.py.
+
+    A line break has no escape in this format: the demuxer reads each line as its own directive,
+    so a name containing one would add `file` entries to the list and pull in files the caller
+    never named. Such a path is refused."""
+    if "\n" in str(path) or "\r" in str(path):
+        refuse("input", "media_path_has_line_break",
+               f"{str(path)!r} contains a line break, which ffmpeg's concat list cannot hold (each line is a "
+               "directive of its own); rename the file", path=str(path))
     # only on Windows: on POSIX the quoted form takes a backslash literally, and it is part of the name (#408)
     escaped = (str(path).replace("\\", "/") if _on_windows() else str(path)).replace("'", "'\\''")
     return f"file '{escaped}'"

package/scripts/_common/emit.py

@@ -8,6 +8,7 @@ from __future__ import annotations
 import json
 import math
 import os
+import stat
 import sys
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
@@ -319,7 +320,28 @@ def audit(event: str, details: Dict[str, Any], *, default_path: Optional[str] =
         rec["plan_sha256"] = plan_sha256
     rec["details"] = details
     try:
-        with open(path, "a", encoding="utf-8") as f:
+        # a default path is a hidden name in someone's output directory: never appended to through a
+        # symlink planted there. A log the caller named (--audit-log) is opened as named.
+        flags = os.O_WRONLY | os.O_APPEND | os.O_CREAT | (0 if ctx.audit_log else getattr(os, "O_NOFOLLOW", 0))
+        checked = not ctx.audit_log and not hasattr(os, "O_NOFOLLOW")
+        if checked and os.path.islink(path):
+            raise OSError(f"{path} is a symbolic link")
+        fd = os.open(path, flags, 0o666)
+        if checked:
+            # no O_NOFOLLOW (Windows): a link that appeared between the look above and the open is
+            # caught after it -- the descriptor must be the file now at that name, not a link's
+            # target -- and nothing is written through it
+            try:
+                st, at = os.fstat(fd), os.lstat(path)
+                # st_nlink: a link swapped for a hard link to its target before the lstat would
+                # otherwise pass the identity check; a log this tool created has one name
+                if (stat.S_ISLNK(at.st_mode) or (st.st_dev, st.st_ino) != (at.st_dev, at.st_ino)
+                        or not stat.S_ISREG(st.st_mode) or st.st_nlink != 1):
+                    raise OSError(f"{path} was replaced by a link while it was opened")
+            except BaseException:
+                os.close(fd)
+                raise
+        with os.fdopen(fd, "a", encoding="utf-8") as f:
             f.write(json.dumps(json_safe(rec), ensure_ascii=False, sort_keys=True) + "\n")
     except OSError as exc:
         warn(f"could not append the {event} record to the audit log {path} ({exc}); the run is unaffected",

package/scripts/_common/runner.py

@@ -775,21 +775,69 @@ _URL_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]+:")
 _URL_SCHEME_POSIX = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
 
 
+def _is_subfile_url(value: str) -> bool:
+    """ffmpeg's url_find_protocol() also opens `subfile,<options>:<url>` through the subfile
+    protocol: the scheme stops at the comma, so the regexes above never see it."""
+    return value.startswith("subfile,") and ":" in value[len("subfile,"):]
+
+
 def looks_like_url(value: str) -> bool:
     """True for a value ffmpeg would open through a protocol rather than as a local file."""
+    if _is_subfile_url(value):
+        return True
     scheme = _URL_SCHEME if os.name == "nt" else _URL_SCHEME_POSIX
     return bool(scheme.match(value)) and not value.startswith("pipe:")
 
 
-_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat")
+def url_scheme(value: str) -> str:
+    """The protocol name ffmpeg would open `value` through (for a looks_like_url() value)."""
+    return "subfile" if _is_subfile_url(value) else value.split(":", 1)[0].lower()
+
+
+_PLAYLIST_SUFFIXES = (".m3u8", ".m3u", ".ffconcat", ".mpd")
 _PLAYLIST_MAGIC = (b"#EXTM3U", b"ffconcat")
+# ffmpeg probes a text format over the whole probe buffer (up to -probesize, 5,000,000 bytes), not
+# over a fixed prefix, and reads that buffer as a C string, so the scan below stops at the first
+# NUL byte: a real media file has one within its first few bytes, a manifest has none.
+_MANIFEST_SCAN_LIMIT = 5_000_000
+
+
+def _manifest_kind(path: str) -> Optional[str]:
+    """"DASH" or "IMF" when ffmpeg's own probe would read `path` as that manifest, whatever its
+    name: dash_probe() looks for `<MPD` and `dash:profile` or `3GPP:PSS:profile:DASH1`
+    (case-insensitively), imf_probe() for
+    `<CompositionPlaylist` and `ContentTitle>`. Either one names other files, local or remote, that
+    ffmpeg then opens (a DASH BaseURL is followed over HTTP even under -protocol_whitelist file)."""
+    buf = bytearray()
+    try:
+        with open(path, "rb") as fh:
+            while len(buf) < _MANIFEST_SCAN_LIMIT:
+                chunk = fh.read(65536)
+                if not chunk:
+                    break
+                nul = chunk.find(b"\0")
+                if nul >= 0:
+                    buf += chunk[:nul]
+                    break
+                buf += chunk
+    except OSError:
+        return None
+    text = bytes(buf[:_MANIFEST_SCAN_LIMIT])
+    low = text.lower()
+    if b"<mpd" in low and (b"dash:profile" in low or b"3gpp:pss:profile:dash1" in low):
+        return "DASH"
+    if b"<CompositionPlaylist" in text and b"ContentTitle>" in text:
+        return "IMF"
+    return None
 
 
 def _refuse_playlist(value: str) -> None:
-    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, an ffconcat list) rather
-    than as media. A playlist names other files by path, so a media file handed to the skill could
-    pull in any file the user can read. The skill's own concat lists pass `-f concat` and are not
-    checked here."""
+    """Refuse an input that ffmpeg would read as a playlist (HLS .m3u8, a DASH .mpd, an IMF
+    composition playlist, an ffconcat list) rather than as media. A playlist names other files by
+    path or URL, so a media file handed to the skill could pull in any file the user can read, or
+    make ffmpeg fetch a URL. HLS and ffconcat are told by name or by their first bytes; DASH and IMF
+    by name or by the content ffmpeg's own probe looks for, anywhere before the first NUL byte. The
+    skill's own concat lists pass `-f concat` and are not checked here."""
     if os.path.exists(value) and not os.path.isfile(value) and not os.path.isdir(value):
         # a FIFO or a device: ffmpeg would block on it or read whatever it streams
         refuse("input", "media_path_not_a_file",
@@ -801,9 +849,14 @@ def _refuse_playlist(value: str) -> None:
                 head = fh.read(16).lstrip(b"\xef\xbb\xbf \t\r\n")
     except OSError:
         pass
+    kind = None
     if value.lower().endswith(_PLAYLIST_SUFFIXES) or head.startswith(_PLAYLIST_MAGIC):
+        kind = "HLS, DASH or ffconcat"
+    elif os.path.isfile(value):
+        kind = _manifest_kind(value)
+    if kind:
         refuse("input", "media_path_is_playlist",
-               f"{value!r} is a playlist (HLS or ffconcat), which ffmpeg would follow to the files it names; "
+               f"{value!r} is a playlist ({kind}), which ffmpeg would follow to the files or URLs it names; "
                "this skill takes media files only. Pass the media file itself", path=value)
 
 
@@ -836,9 +889,9 @@ def _refuse_url_media(cmd: Sequence[str]) -> None:
     for value in values:
         if looks_like_url(value):
             refuse("input", "media_path_is_url",
-                   f"{value!r} would be opened by ffmpeg as a URL ({value.split(':', 1)[0]}:), not as a local file; "
+                   f"{value!r} would be opened by ffmpeg as a URL ({url_scheme(value)}:), not as a local file; "
                    "this skill reads and writes local files only. Pass a plain path (a local name containing "
-                   "a colon works as ./name)", path=value, scheme=value.split(":", 1)[0].lower())
+                   "a colon works as ./name)", path=value, scheme=url_scheme(value))
 
 
 def _check_no_overwrite_input(cmd: Sequence[str]) -> None:
@@ -1243,10 +1296,73 @@ def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str]
         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}")
+    tmp = reserve_sibling(d, stem, ext)
     return list(cmd[:-1]) + [tmp], output, tmp
 
 
+def _reserve(d: str, stem: str, ext: str, tag: str) -> "Tuple[str, Optional[int]]":
+    """(path, open descriptor) of a hidden sibling created exclusively; (path, None) when the
+    directory refuses the create (the write that follows then fails there)."""
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    n = 1
+    while True:
+        path = os.path.join(d, f".{stem}.ffskill-" + (f"{tag}-" if tag else "") + f"{os.getpid()}"
+                            + (f"-{n}" if n > 1 else "") + ext)
+        try:
+            return path, os.open(path, flags, 0o666)
+        except FileExistsError:
+            n += 1
+        except OSError:
+            return path, None
+
+
+def reserve_sibling(d: str, stem: str, ext: str, tag: str = "") -> str:
+    """Create the hidden sibling `.<stem>.ffskill-<pid><ext>` (or `...-<pid>-<n><ext>` when that
+    name is taken) exclusively, and return its path, for ffmpeg to write with -y. O_EXCL never
+    opens an existing entry, a symlink included, so a name planted in the output directory
+    beforehand is never written through. What it cannot stop is someone who may delete files in
+    that directory replacing this one between the create and ffmpeg's open: not possible in a
+    sticky shared directory (/tmp), nor in one only the caller can write. A copy this process makes
+    itself goes through copy_to_sibling(), which writes the descriptor it created."""
+    path, fd = _reserve(d, stem, ext, tag)
+    if fd is None:
+        # fail closed: a name that was not created exclusively is never handed to ffmpeg
+        refuse("input", "output_dir_not_writable", f"cannot create a temporary file in {d or '.'!r}",
+               output=os.path.join(d, stem + ext), directory=d or ".")
+    os.close(fd)
+    return path
+
+
+def copy_to_sibling(src: str, dst: str) -> str:
+    """Copy `src` into a hidden sibling of `dst` created exclusively, through the descriptor that
+    created it (never by reopening the name), and return the sibling's path for os.replace()."""
+    import shutil
+    d, base = os.path.split(dst)
+    stem, ext = os.path.splitext(base)
+    path, fd = _reserve(d, stem, ext, "")
+    if fd is None:
+        raise OSError(f"cannot create a temporary file beside {dst}")
+    try:
+        fout = os.fdopen(fd, "wb")
+    except BaseException:
+        os.close(fd)
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    try:
+        with fout, open(src, "rb") as fin:
+            shutil.copyfileobj(fin, fout, 1 << 20)
+    except BaseException:
+        try:
+            os.remove(path)
+        except OSError:
+            pass
+        raise
+    return path
+
+
 HW_ENV = "FFMPEG_SKILL_HW"
 # set only by render.py/batch.py --hw/--no-hw for the stages they run: "the outer command chose
 # explicitly", so a child resolves $FFMPEG_SKILL_HW as a flag (export.py included), not a default
@@ -1846,7 +1962,6 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
     _check_existing_output(cmd)
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
-    tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
     with _OutputLock(dst):
         if move:
             try:
@@ -1855,14 +1970,16 @@ def place_output(src: str, dst: str, move: bool = False) -> None:
                 return
             except OSError:
                 pass
+        tmp = None
         try:
-            shutil.copyfile(src, tmp)
+            tmp = copy_to_sibling(src, dst)
             os.replace(tmp, dst)
         except OSError as e:
-            try:
-                os.remove(tmp)
-            except OSError:
-                pass
+            if tmp:
+                try:
+                    os.remove(tmp)
+                except OSError:
+                    pass
             die(f"could not place {dst}: {e}", kind="output")
     _remember_output(cmd)
 

package/scripts/_contract.py

@@ -424,7 +424,8 @@ ERROR_REASONS = {
     "output_exists": "an output already exists and --overwrite was not given; details.outputs: [{path, resolved, size, mtime_ns}]",
     "output_is_input": "the output resolves to the same file as an input; details: {output, input, resolved}",
     "output_is_directory": "the output path is a directory; details: {output}",
-    "media_path_is_playlist": "an input is a playlist (HLS .m3u8/.m3u or an ffconcat list, by name or by its first bytes) that ffmpeg would follow to the files it names; the skill takes media files only; details: {path}",
+    "media_path_is_playlist": "an input is a playlist that ffmpeg would follow to the files or URLs it names: HLS .m3u8/.m3u or an ffconcat list (by name or by its first bytes), a DASH manifest or an IMF composition playlist (by name or by the content ffmpeg's own probe looks for, whatever the file is called); the skill takes media files only; details: {path}",
+    "media_path_has_line_break": "a path written into a concat list (loop.py, join.py --copy, sequence.py, multi-part cuts) contains a line break, which the concat format cannot hold: each line is a directive, so the name would add entries to the list; details: {path}",
     "media_path_not_a_file": "an input exists but is not a regular file (a FIFO or a device), which ffmpeg would block on or read as a stream; details: {path}",
     "join_copy_mismatch": "join.py --copy: a clip's streams do not match the first clip's, it hides pre-roll frames with an edit list, or its picture and sound end more than 50 ms apart; details: {clips: [{index?, path, differs}]}",
     "output_path_taken": "two files one run writes (a side file and the output, or two side files) resolve to the same path, so the second would replace the first; details: {output, other}",

package/scripts/batch.py

@@ -33,7 +33,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from _common import STATE, add_common, apply_common, child_args, die, emit, info, run_tool, MEDIA_EXT as _MEDIA_EXT
-from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, env_hw, stop_children
+from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, stop_children
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 
 HERE = Path(__file__).resolve().parent
@@ -265,16 +265,18 @@ def deliver(src: str, final: Path) -> None:
         except OSError:
             # another filesystem: copy beside the final path and rename, so a copy that fails part
             # way never leaves a truncated file where the caller's was
-            import shutil
-            tmp = final.with_name(f".{final.stem}.ffskill-{os.getpid()}-{threading.get_ident()}{final.suffix}")
+            # created exclusively and written through the descriptor that created it: never through
+            # an entry planted at the name, and two threads delivering side by side get two names
+            tmp = None
             try:
-                shutil.copyfile(src, tmp)
+                tmp = copy_to_sibling(str(src), str(final))
                 os.replace(tmp, final)
             except OSError as exc:
-                try:
-                    os.remove(tmp)
-                except OSError:
-                    pass
+                if tmp:
+                    try:
+                        os.remove(tmp)
+                    except OSError:
+                        pass
                 raise ItemError({"step": None, "tool": None, "kind": "output",
                                  "message": f"could not deliver {src} to {final}: {exc}"})
     log(f"  delivered the last written file to {final}")

package/scripts/caption.py

@@ -926,8 +926,8 @@ def mux_subtitle_codec(output: str) -> str:
 
 def ass_color(hex_rgb: str, alpha: int = 0) -> str:
     h = hex_rgb.lstrip("#")
-    if len(h) != 6:
-        die(f"colour must be RRGGBB hex, got '{hex_rgb}'")
+    if len(h) != 6 or any(c not in "0123456789abcdefABCDEF" for c in h):
+        die(f"colour must be six hex digits RRGGBB, got '{hex_rgb}'")
     r, g, b = h[0:2], h[2:4], h[4:6]
     return f"&H{alpha:02X}{b}{g}{r}".upper()
 

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, run_analysis as _run_analysis, subtitle_codec_for
+from _common.runner import ffmpeg_encoders, guard_sidecar, remember_written, 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
@@ -213,7 +213,7 @@ def _key_fill(args, p: Dict, meta: Dict, output: str, cmd: List[str], vf: List[s
     if not STATE.dry_run:
         d, base = os.path.split(output)
         stem, ext = os.path.splitext(base)
-        fill_tmp = os.path.join(d, f".{stem}.ffskill-fill-{os.getpid()}{ext}")
+        fill_tmp = reserve_sibling(d, stem, ext, "fill")  # created exclusively: never through a planted link
     cmd += (p["audio"] if has_audio else ["-an"]) + [fill_tmp or output]
     cmd += ["-map", "[key]"] + p["video"] + tc_args + cfr_args(meta) + ["-an", key]
     try:

package/scripts/render.py

@@ -464,6 +464,64 @@ def check_overlay(ov: Any, label: str) -> None:
         die(f"{label}: scale sizes an image, logo or video layer; text size is font_size", kind="input")
 
 
+def project_input_files(proj: Dict[str, Any], rel: Any) -> List[str]:
+    """Every file a project names as an input: clip sources, music/replace/effects, the brand,
+    caption files (a --text value that names an existing file), overlay images, videos and fonts, the
+    audiogram image, a beat grid's source and the chapters file. Values of the wrong type are left
+    to the stage that reads them."""
+    found: List[str] = []
+
+    def add(value: Any, must_exist: bool = False) -> None:
+        if isinstance(value, str) and value:
+            p = rel(value)
+            if not must_exist or os.path.isfile(p):
+                found.append(p)
+
+    for c in proj.get("clips") or []:
+        if isinstance(c, dict):
+            add(c.get("src"))
+            if isinstance(c.get("snap"), dict):
+                add(c["snap"].get("source"))
+    for key in ("audio", "captions", "audiogram", "snap"):
+        if not isinstance(proj.get(key), dict):
+            continue
+        obj = proj[key]
+        if key == "audio":
+            for k in ("music", "replace", "effects"):
+                add(obj.get(k))
+        elif key == "captions":
+            add(obj.get("srt"))
+            add(obj.get("ass"))
+            add(obj.get("text"), must_exist=True)  # inline cue text is not a path
+        elif key == "audiogram":
+            add(obj.get("image"))
+        else:
+            add(obj.get("source"))
+    add(proj.get("brand"))
+    brand = proj.get("brand")
+    if isinstance(brand, str) and brand:
+        # the brand's own logo and font_file are read by the overlay and caption stages, resolved
+        # against the brand file as load_brand() resolves them; an unreadable brand is left to them
+        try:
+            data = json.loads(Path(rel(brand)).read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            data = None
+        if isinstance(data, dict):
+            base = Path(rel(brand)).resolve().parent
+            for k in ("logo", "font_file"):
+                v = data.get(k)
+                if isinstance(v, str) and v and "://" not in v:
+                    found.append(v if os.path.isabs(v) else str(base / v))
+    add(proj.get("chapters"), must_exist=True)
+    overlays = proj.get("overlays")
+    for ov in (overlays if isinstance(overlays, list) else []):  # any other type is the overlay stage's to refuse
+        if isinstance(ov, dict):
+            add(ov.get("image"))
+            add(ov.get("video"))
+            add(ov.get("font_file"))
+    return found
+
+
 def require_object(obj: Any, label: str) -> None:
     """Refuse a value that is not an object where the run reads it with .get(): "export": "reels"
     in a render, a string frame, a clip written as a bare path. 2.2.1 died there with a traceback
@@ -1216,8 +1274,13 @@ def main() -> int:
     if not clips:
         die("project.clips is empty")
     output = rel(proj.get("output") or "final.mp4")
-    # the final stage is a copy from the work dir, so run()'s own guard never sees the sources (review 5)
-    refuse_output_is_input(output, *[rel(c.get("src")) for c in clips if c.get("src")])
+    # the final stage is a copy from the work dir, so run()'s own guard never sees the sources
+    # (review 5): every file the project names is passed here, not only the clips, or --overwrite
+    # replaced a music bed or a brand file named as the output
+    if not args.stop_after or args.stop_after == "export":
+        # only a run that ends in the final copy writes `output`; a --stop-after preview writes
+        # its stage file inside the work directory and leaves `output` alone
+        refuse_output_is_input(output, *([os.path.abspath(args.project)] if args.project else []), *project_input_files(proj, rel))
     if _reaches("overlays", args.stop_after):
         # #326: an overlay video is the caller's file, never an earlier stage's output, so a
         # missing one is refused here, under --dry-run too, not after every stage before it ran
@@ -1396,7 +1459,12 @@ def main() -> int:
                           ("color", "--color"), ("background", "--background"),
                           ("width", "--width"), ("height", "--height"), ("fps", "--fps")):
             if ag.get(key) is not None:
-                argv += [flag, str(ag[key])]
+                value = ag[key]
+                if key == "image" and isinstance(value, str) and "://" not in value:
+                    # against the project file, as every other path here and as the output guard
+                    # checks it; it used to reach waveform.py as written, against the cwd
+                    value = rel(value)
+                argv += [flag, str(value)]
         argv += brand_args
         sh("waveform.py", *argv, stage="audiogram")
         current = nxt
@@ -1542,7 +1610,8 @@ def main() -> int:
         for k, flag in (("position", "--position"), ("start", "--start"), ("end", "--end"), ("fade", "--fade"), ("opacity", "--opacity"), ("scale", "--scale"), ("font_size", "--font-size"), ("font", "--font"), ("font_file", "--font-file"), ("margin", "--margin"), ("platform", "--platform"),
                         ("chromakey", "--chromakey"), ("chromakey_similarity", "--chromakey-similarity"), ("chromakey_blend", "--chromakey-blend")):
             if ov.get(k) is not None:
-                argv += [flag, str(ov[k])]
+                # font_file is a path: the same one project_input_files() guards
+                argv += [flag, rel(ov[k]) if k == "font_file" and ov[k] else str(ov[k])]
         if ov.get("box"):
             argv.append("--box")
         # review 12: the overlay stage was the one stage that never heard which destination this