ffmpeg-skill 3.8.20 → 3.8.22

package/scripts/batch.py

@@ -34,10 +34,10 @@ 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, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
+from _common.runner import (with_flags, HW_FORCED_ENV, OWNED_ENV, _OutputLock, add_hw_orchestrator_args, copy_to_sibling, env_hw, read_json,
                             owned_identity, stop_children)
-from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
-from _common.decision import NO_DEFAULT_ENCODE_EXT, rebase_project_paths
+from _common.emit import absorb_stage_hw, audit, note, record_skip, shown, steps_encoder_report, warn
+from _common.decision import NO_DEFAULT_ENCODE_EXT, brand_asset_files, rebase_project_paths
 from _common.runner import parse_json
 
 HERE = Path(__file__).resolve().parent
@@ -70,6 +70,40 @@ def file_key(path: Path) -> str:
     return h.hexdigest()
 
 
+def side_input_file(value: str) -> Path:
+    """The file a side-input argument reads: the argument itself, or, when that is no file and it
+    ends in `:SUFFIX`, the part before the last colon when that is one (caption.py's
+    `--srt FILE:LANG`, which split_srt_lang() reads the same way). Keying the whole token hashed a
+    path that does not exist, so an edited subtitle file kept its key (#510 review)."""
+    path = Path(value)
+    try:
+        if path.is_file() or ":" not in value:
+            return path
+        head = Path(value.rpartition(":")[0])
+        return head if value.rpartition(":")[0] and head.is_file() else path
+    except OSError:
+        return path
+
+
+def is_brand_value(step: List[Any], j: int) -> bool:
+    """Whether step[j] is the value of --brand (`--brand X` or `--brand=X`)."""
+    arg = str(step[j])
+    return arg.startswith("--brand=") or (j > 0 and str(step[j - 1]) == "--brand")
+
+
+def key_brand_assets(h: Any, path: Path) -> None:
+    """Hash the logo and font file a brand file names into `h`: the brand file's own bytes do not
+    change when one of them is replaced under its name (#510 review; render.py's stage key and a
+    project recipe's key already cover them)."""
+    for key, asset in brand_asset_files(str(path)):
+        a = Path(asset)
+        try:
+            ident = file_key(a) if a.is_file() else "-"
+        except OSError:
+            ident = "-"
+        h.update(f"brand:{key}\0{asset}\0{ident}\0".encode())
+
+
 def side_inputs_key(recipe: Dict[str, Any]) -> str:
     """The files a recipe's steps name besides {in}/{out} (check.py --compare REF, a LUT, a logo),
     keyed by their own content: editing or removing one is a change the cache must see, or a QC
@@ -77,16 +111,18 @@ def side_inputs_key(recipe: Dict[str, Any]) -> str:
     Read on every pass, so a --watch loop sees the edit too."""
     h = hashlib.sha1(usedforsecurity=False)
     for step in recipe.get("steps") or []:
-        for arg in step[1:] if isinstance(step, list) else []:
-            if not isinstance(arg, str) or "{" in arg:
+        for j, arg in enumerate(step) if isinstance(step, list) else []:
+            if j == 0 or not isinstance(arg, str) or "{" in arg:
                 continue
             value = arg.split("=", 1)[1] if arg.startswith("-") and "=" in arg else arg
             if value.startswith("-") or not value:
                 continue
-            path = Path(value)
+            path = side_input_file(value)
             try:
                 if path.is_file():
                     h.update(f"{value}\0{file_key(path)}\0".encode())
+                    if is_brand_value(step, j):
+                        key_brand_assets(h, path)
                     continue
             except OSError:
                 pass
@@ -94,6 +130,40 @@ def side_inputs_key(recipe: Dict[str, Any]) -> str:
     return h.hexdigest()[:8]
 
 
+def item_side_inputs_key(recipe: Dict[str, Any], src: Path) -> "tuple[str, Optional[Dict[str, Any]]]":
+    """The side inputs a step names through a placeholder, for one item (#510): `--image {in}.png`
+    in the first step is a file beside this item's source, and editing it is a change the cache
+    must see as side_inputs_key() sees a literal path's. Returns (key part, None), "" when the
+    recipe names none, or ("", why) when one cannot be resolved before the item runs: a later
+    step's {in} is an intermediate that does not exist yet, so its file cannot be keyed, and the
+    item is not served from the cache at all."""
+    h = hashlib.sha1(usedforsecurity=False)
+    named = False
+    for i, step in enumerate(recipe.get("steps") or []):
+        for j, arg in enumerate(step) if isinstance(step, list) else []:
+            if j == 0 or not isinstance(arg, str) or "{in}" not in arg or "{out}" in arg:
+                continue  # literal paths are side_inputs_key()'s; {out} names an output, not an input
+            value = arg.split("=", 1)[1] if arg.startswith("-") and "=" in arg else arg
+            if value == "{in}" or "{in}" not in value:
+                continue  # the step's own input
+            if i > 0:
+                return "", {"reason": "side_input_unresolved", "step": i, "argument": arg,
+                            "message": f"step {i} names {arg!r}, a file derived from an intermediate that does not "
+                                       "exist before the item runs, so the cache cannot key it; the item always runs"}
+            path = side_input_file(value.replace("{in}", str(src)))
+            named = True
+            try:
+                if path.is_file():
+                    h.update(f"{path}\0{file_key(path)}\0".encode())
+                    if is_brand_value(step, j):
+                        key_brand_assets(h, path)
+                    continue
+            except OSError:
+                pass
+            h.update(f"{path}\0-\0".encode())
+    return (h.hexdigest()[:8] if named else ""), None
+
+
 def caseless_glob(pattern: str) -> str:
     """`pattern` with every letter outside a [...] class matched in either case: "*.mp4" finds
     GOPR0001.MP4, as it already did on macOS's and Windows' default filesystems, so a recipe means
@@ -201,6 +271,8 @@ _LOG = threading.local()
 # left, or one another item delivered (two items naming one side file) is still refused.
 _OWN_OUTPUTS: Dict[str, Dict[str, Dict[str, int]]] = {}
 _OWN_LOCK = threading.Lock()
+# source -> (final path, its owned_identity() before the last step started), while that step runs
+_WATCHED: Dict[str, Any] = {}
 # set by batch.py's signal handler: a --jobs worker between two steps must not start the next one
 _STOP = threading.Event()
 
@@ -257,7 +329,8 @@ def run_step(argv: List[str], per_call: "Optional[float]" = None,
     if _STOP.is_set():
         return False, {"status": "failed", "exit_code": 130,
                        "error": {"kind": "interrupted", "message": f"interrupted before {script} started"}}
-    cmd = [str(HERE / script)] + argv[1:] + child_args() + (["--json"] if "--json" not in argv[1:] else [])
+    # before a bare `--` in the step, where argparse still reads them as options (#510 review)
+    cmd = [str(HERE / script)] + with_flags(argv[1:], child_args() + (["--json"] if "--json" not in argv[1:] else []))
     log("  → " + " ".join(os.path.basename(c) if i < 1 else c for i, c in enumerate(cmd)))
     env = dict(os.environ, **{OWNED_ENV: str(owned)}) if owned else None
     proc = run_tool(cmd, per_call=per_call, env=env)
@@ -354,6 +427,41 @@ def check_recipe_types(recipe: Dict[str, Any]) -> None:
                 kind="input")
 
 
+STEP_WRITES_WITHOUT_OUT = "step_writes_without_out"
+
+
+def names_output(step: Any) -> bool:
+    """Whether a step names where it writes itself (-o/--output with a path that is not {out}): a
+    side product the caller placed on purpose (look.py {in} -o {in}.png), not an implicit output."""
+    for tok in (step[1:] if isinstance(step, list) else []):
+        tok = str(tok)
+        if tok in ("-o", "--output") or tok.startswith("--output=") or (tok.startswith("-o") and not tok.startswith("--") and len(tok) > 2):
+            return True
+    return False
+
+
+def work_files(work: Path) -> "set":
+    """The names of the files directly in an item's work directory, batch's own excepted (the
+    owned*.json snapshots, the owned-report directory, hidden temporaries)."""
+    try:
+        return {p.name for p in work.iterdir()
+                if p.is_file() and not p.name.startswith(".") and not (p.name.startswith("owned") and p.suffix == ".json")}
+    except OSError:
+        return set()
+
+
+def wrote_without_out(i: int, tool: str, path: str, src: Path) -> Dict[str, Any]:
+    """The error of a step that reports an output file while naming no {out}: the batch stops."""
+    written = not STATE.dry_run and os.path.isfile(path)
+    where = (f"this run wrote {path} for {src.name} before stopping and left it there; no later item ran"
+             if written else "nothing was written" + (" (dry run)" if STATE.dry_run else ""))
+    return {"step": i, "tool": tool, "kind": "input", "reason": STEP_WRITES_WITHOUT_OUT,
+            "message": (f"step {i} ({tool}) names no {{out}} but writes {path}, its own default output: the next "
+                        f"step does not read it and the batch does not deliver it; {where}"),
+            "hint": f"give step {i} \"-o\", \"{{out}}\" so its file is the one the next step reads and the batch delivers",
+            "details": {"step": i, "tool": tool, "file": path, "written": written}}
+
+
 def step_writes(step: Any) -> bool:
     """Whether a recipe step writes a file: it names {out} (check.py and probe.py do not)."""
     return isinstance(step, list) and any("{out}" in str(a) for a in step[1:])
@@ -520,11 +628,21 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         proj["output"] = str(final.resolve())
         pj = work / "project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
-        ok, _doc = run_step(["render.py", str(pj)], budget(), owned=owned(0))
+        owned_cfg = owned(0)
+        if not STATE.dry_run:
+            # the render writes the final path itself: a stop while it runs reports a file it left
+            # there as kept, as for a steps recipe's last step (#510 review)
+            with _OWN_LOCK:
+                _WATCHED[str(src)] = (str(final), owned_identity(str(final)))
+        ok, _doc = run_step(["render.py", str(pj)], budget(), owned=owned_cfg)
+        if ok:
+            with _OWN_LOCK:
+                _WATCHED.pop(str(src), None)
         step_docs = [("render", _doc)]
         failure = None if ok else step_error(0, "render.py", _doc)
         cut_reencoded: List[bool] = []
         cut_reasons: List[str] = []
+        cut_possible: List[List[str]] = []
     else:
         steps = recipe.get("steps") or []
         if not steps:
@@ -536,6 +654,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         cut_reencoded = []
         step_docs = []
         cut_reasons = []
+        cut_possible = []
         for i, step in enumerate(steps):
             last = i == len(steps) - 1
             # the item's directory is its own, so the name needs no stem (a long one overflowed it)
@@ -546,7 +665,17 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
             if last and writes and track and is_own_output(src, final):
                 log(f"  {final.name} is this run's own earlier output, unchanged since: it may be replaced")
-            step_ok, doc = run_step(argv, budget(), owned=owned(i))
+            owned_cfg = owned(i)
+            before = set() if last else work_files(work)
+            if last and writes and not STATE.dry_run:
+                # what is at the final path before the step that writes it: a stop while it runs
+                # reports a file the step left there as kept, not as nothing (#510)
+                with _OWN_LOCK:
+                    _WATCHED[str(src)] = (str(final), owned_identity(str(final)))
+            step_ok, doc = run_step(argv, budget(), owned=owned_cfg)
+            if step_ok:
+                with _OWN_LOCK:
+                    _WATCHED.pop(str(src), None)  # a stopped step's stays for interrupted_row()
             step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
             # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut (or its
             # --segments join) re-encoded, for the reasons in its `reencode_reason` (distinct per
@@ -555,10 +684,26 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             if step_ok and argv and argv[0] == "cut.py" and isinstance(doc, dict) and "reencoded" in doc:
                 cut_reencoded.append(bool(doc["reencoded"]))
                 cut_reasons.extend(r for r in (doc.get("reencode_reason") or []) if isinstance(r, str))
+                # a dry run's planned copy may still re-encode: what each call's plan says (#510 review)
+                cut_possible.append([r for r in (doc.get("possible_reencode_reason") or []) if isinstance(r, str)])
             if not step_ok:
                 ok = False
                 failure = step_error(i, str(argv[0]) if argv else None, doc)
                 break
+            reported = doc.get("output") if isinstance(doc, dict) else None
+            if not writes and isinstance(reported, str) and reported and not names_output(step):
+                # #510: the step wrote (or under --dry-run would write) its own default output, which
+                # the next step does not read and the batch does not deliver: refused, and the batch stops
+                raise ItemError(wrote_without_out(i, str(argv[0]), os.path.abspath(reported), src))
+            if writes and not last:
+                lost = sorted(set(work_files(work)) - before - {os.path.basename(out)})
+                if lost:
+                    # a side file the step wrote beside its intermediate (caption.py's .srt, an .ass):
+                    # the item's work directory goes when the item ends, and it with it (#510)
+                    record_skip(f"{src.name}: step {i} ({argv[0]}) also wrote {', '.join(lost)} beside its intermediate; "
+                                "it is removed with the item's work directory, not delivered (only the last step's "
+                                "side files land beside the output)",
+                                "batch_side_file_not_delivered", file=str(src), step=i, tool=str(argv[0]), files=lost)
             if writes:
                 cur = out
         if ok and cur != str(final) and not writes_nothing(recipe):
@@ -598,6 +743,8 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
     if cut_reencoded:
         result["cut_reencoded"] = cut_reencoded
         result["cut_reencode_reasons"] = cut_reasons
+        if STATE.dry_run:
+            result["cut_possible_reencode_reason"] = cut_possible
     # the encoder each item really ran and its GPU facts (--hw / FFMPEG_SKILL_HW: on VideoToolbox,
     # fell back and why): this process encodes nothing itself, so its top-level hw.used is null
     result.update(steps_encoder_report(step_docs))
@@ -613,11 +760,17 @@ def output_identity(path: str) -> "Optional[Dict[str, int]]":
     return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
 
 
-def cached_output_changed(hit: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
+def cached_output_changed(hit: Dict[str, Any], recipe: "Optional[Dict[str, Any]]" = None) -> "Optional[Dict[str, Any]]":
     """None when the entry's output is still the file this batch wrote; else why it is not served:
-    output_missing, output_changed (size or mtime differ: something replaced or edited it) or
+    output_missing, output_changed (size or mtime differ: something replaced or edited it),
     entry_unverifiable (an entry written by 2.10.11 or earlier recorded no identity, so nothing can say
-    the file is the one it describes)."""
+    the file is the one it describes), or entry_predates_output_check: the recipe has a step that
+    names no {out}, and the entry was stored before such a step's own output was checked (#510), so
+    a step that writes its default output (metadata.py {in}) was cached as one that writes nothing."""
+    steps = (recipe or {}).get("steps") or []
+    if not (recipe or {}).get("project") and any(not step_writes(st) for st in steps) and not hit.get("output_checked"):
+        return {"reason": "entry_predates_output_check", "output": hit.get("output"),
+                "message": "the entry was stored before batch checked what a step naming no {out} writes"}
     if hit.get("written") is False or ("output" in hit and hit["output"] is None):
         return None  # a recipe that writes nothing (check.py over a folder): no file to have changed
     out = str(hit.get("output") or "")
@@ -654,6 +807,7 @@ def main() -> int:
     started = time.time()
     with _OWN_LOCK:
         _OWN_OUTPUTS.clear()
+        _WATCHED.clear()
     folder = Path(args.folder).resolve()  # relative 'bdir' used to become bdir/bdir/out once joined with the default outdir
     if not folder.is_dir():
         die(f"not a folder: {folder}")
@@ -759,6 +913,7 @@ def main() -> int:
     cache_lock = threading.Lock()
     timed_out = {"hit": False}
     interrupted: Dict[str, Any] = {"hit": False, "signal": None}
+    refused: Dict[str, Any] = {"hit": False}  # a step wrote without naming {out}: no later item runs (#510)
     _STOP.clear()
     # Ctrl-C (and SIGTERM where it is delivered) stops the running steps and reports the table:
     # the shared handler would exit with "nothing was written" and no rows, and inside an item it
@@ -766,6 +921,11 @@ def main() -> int:
     import signal as _signal
 
     def _interrupt(signum: int, frame: Any) -> None:
+        if interrupted["signal"] is not None:
+            # a second signal while the first one's stop runs (Ctrl-C reaches the whole group, and a
+            # parent then sends SIGTERM): raising again broke into the stop or the table, and the
+            # exit code became the second signal's (#510 review; runner._on_signal() does the same)
+            return
         interrupted["signal"] = signum
         _STOP.set()
         stop_children()
@@ -862,8 +1022,19 @@ def main() -> int:
             finally:
                 shutil.rmtree(iw, ignore_errors=True)
 
-        def store(key: str, r: Dict[str, Any]) -> None:
-            if not (r["ok"] and not STATE.dry_run):
+        def store(key: "Optional[str]", r: Dict[str, Any]) -> None:
+            if not key or not (r["ok"] and not STATE.dry_run):
+                return
+            # the key was made before the item ran: a source or side input edited while it waited
+            # or ran made an output the key does not describe, and a later restore of the old file
+            # would have served it (#510 review). Made again here; not stored when it changed
+            try:
+                now = item_key(Path(r["file"]))
+            except OSError:
+                now = None
+            if now != key:
+                record_skip(f"{Path(r['file']).name}: its source or a side input changed while it was processed, so its "
+                            "output is not cached (the next run makes it again)", "batch_cache_inputs_changed", file=r["file"])
                 return
             # The read-modify-write of the in-memory dict needs the lock even though the file
             # write is already atomic: two finishers could otherwise serialise from two different
@@ -874,7 +1045,8 @@ def main() -> int:
                 for stale in [k for k, v in cache.items() if r["output"] and r.get("written", True) and k != key and isinstance(v, dict) and v.get("output") == r["output"]]:
                     del cache[stale]
                 # the output as this run left it: a later hit is served only while it is unchanged
-                cache[key] = dict(r, output_identity=output_identity(r["output"]) if r["output"] and r.get("written", True) else None)
+                cache[key] = dict(r, output_identity=output_identity(r["output"]) if r["output"] and r.get("written", True) else None,
+                                  output_checked=True)  # every step's own output was checked (#510): see cached_output_changed()
                 # write_text isn't atomic -- a process killed mid-write (or a --watch loop racing
                 # a concurrent manual run) could leave a truncated file that json.loads() above
                 # then silently treats as "no cache" (a ValueError -> {}), discarding every prior
@@ -895,6 +1067,16 @@ def main() -> int:
         # read on every pass: a --watch loop serves nothing from an edited project.json, cue file or
         # music bed (computed once before the loop, it did: A81)
         pass_key = recipe_key(recipe) + gpu_key() + side_inputs_key(recipe)
+
+        def item_key(src: Path) -> "Optional[str]":
+            """The cache key of one item as its files are now: file_key(src), the recipe, the GPU
+            setting and the side inputs (literal and per item); None when one cannot be keyed.
+            Recomputed by store(), so the side inputs are read again then (pass_key's included)."""
+            per, why = item_side_inputs_key(recipe, src)
+            if why:
+                return None
+            base = recipe_key(recipe) + gpu_key() + side_inputs_key(recipe)
+            return f"{file_key(src)}:{base}" + (":" + per if per else "")
         polled = settle_poll(files)
         for i, src in enumerate(files):
             if str(src) in polled:
@@ -903,12 +1085,21 @@ def main() -> int:
                             "seconds": 0.0, "skipped": "settling"}
                 continue
             key = f"{file_key(src)}:{pass_key}"
+            per_item, unkeyed = item_side_inputs_key(recipe, src)
+            if unkeyed:
+                # nothing can say the cached output still matches its side input: run it, unstored
+                cache_miss[i] = unkeyed
+                info(f"{src.name}: {unkeyed['message']}")
+                pending.append((i, src, None))
+                continue
+            if per_item:
+                key += ":" + per_item
             hit = cache.get(key)
             if isinstance(hit, dict) and not args.force:
-                why = cached_output_changed(hit)
+                why = cached_output_changed(hit, recipe)
                 if why is None:
                     info(f"skip (cached) {src.name}")
-                    slots[i] = {**{k: v for k, v in hit.items() if k != "output_identity"}, "cached": True}
+                    slots[i] = {**{k: v for k, v in hit.items() if k not in ("output_identity", "output_checked")}, "cached": True}
                     continue
                 cache_miss[i] = why
                 facts = {k: v for k, v in why.items() if k not in ("reason", "message")}
@@ -950,12 +1141,26 @@ def main() -> int:
             row.update(ok=False, verified=False)
             if started:
                 row["interrupted"] = True
+                with _OWN_LOCK:
+                    watched = _WATCHED.pop(str(src), None)
+                if watched and owned_identity(watched[0]) not in (None, watched[1]):
+                    # the stopped step had written the final file (export.py's --normalize pass keeps
+                    # its encode): it is there, unverified, without the step that was stopped (#510)
+                    row["kept"] = watched[0]
                 row.setdefault("error", {"step": None, "tool": None, "kind": "interrupted",
                                          "message": "interrupted while this item was running; its running step was stopped"})
             else:
                 row["skipped"] = "interrupted"
             return row
 
+        def refused_row(src: Path) -> "Dict[str, Any]":
+            """An item not started because an earlier one's step wrote a file without naming {out}."""
+            return {"file": str(src), **row_output(src, recipe, outdir), "ok": False, "verified": False,
+                    "seconds": 0.0, "skipped": "recipe_refused"}
+
+        def is_refusal(r: "Optional[Dict[str, Any]]") -> bool:
+            return bool(r) and ((r or {}).get("error") or {}).get("reason") == STEP_WRITES_WITHOUT_OUT
+
         def with_miss(i: int, r: Dict[str, Any]) -> Dict[str, Any]:
             if i in cache_miss:
                 r["cache_miss"] = {k: v for k, v in cache_miss[i].items() if k != "message"}
@@ -980,6 +1185,11 @@ def main() -> int:
                     if isinstance(exc, SystemExit) and not exc.code:
                         raise
                     slots[i] = with_miss(i, failed_row(src, exc))
+                    if is_refusal(slots[i]):
+                        refused["hit"] = True
+                        for j, later, _k in pending[n + 1:]:
+                            slots[j] = refused_row(later)
+                        break
                     continue
                 slots[i] = with_miss(i, r)
                 store(key, r)
@@ -1011,7 +1221,7 @@ def main() -> int:
                 # list up front would put every item past the deadline check before the first one
                 # had finished, and the shared budget could then never stop anything.
                 while queue or in_flight:
-                    while queue and len(in_flight) < jobs:
+                    while queue and len(in_flight) < jobs and not refused["hit"]:
                         if deadline is not None and time.monotonic() >= deadline:
                             break
                         i, src, key = queue.pop(0)
@@ -1030,8 +1240,10 @@ def main() -> int:
                         except BaseException as exc:    # noqa: BLE001 - reported, never swallowed
                             slots[i] = failed_row(src, exc)
                             lines[i] = [f"=== {src.name}", f"    failed: {exc}"]
+                        if is_refusal(slots[i]):
+                            refused["hit"] = True  # the items in flight finish; none is started after
                 for i, src, key in queue:
-                    slots[i] = timed_out_row(src)
+                    slots[i] = refused_row(src) if refused["hit"] else timed_out_row(src)
             except KeyboardInterrupt:
                 # Spec 4.1: cancel what has not started, stop the running steps (the handler
                 # already did), and REPORT every item -- exit 130 with the table, never a
@@ -1062,7 +1274,7 @@ def main() -> int:
         return [r for r in slots if r is not None]
 
     results = one_pass()
-    if args.watch:
+    if args.watch and not refused["hit"]:
         info(f"watching {folder} every {args.watch:g}s (Ctrl-C to stop)")
         # the shared SIGINT handler (install_signal_handlers) exits 130 with "nothing was written",
         # which is wrong for a watch that already processed files: while idle between passes,
@@ -1076,7 +1288,7 @@ def main() -> int:
                 finally:
                     signal.signal(signal.SIGINT, previous)
                 results = one_pass()
-                if interrupted["hit"]:
+                if interrupted["hit"] or refused["hit"]:
                     break  # the pass reported its rows; a watch interrupted mid-pass stops here
         except KeyboardInterrupt:
             info("watch stopped")
@@ -1095,11 +1307,27 @@ def main() -> int:
         # finished, interrupted while running, or not started.
         stopped = sum(1 for r in results if r.get("interrupted"))
         not_started = sum(1 for r in results if r.get("skipped") == "interrupted")
+        kept = [r["kept"] for r in results if r.get("kept")]
         die(f"interrupted after {done} of {len(results)} item(s): {stopped} stopped while running and "
-            f"{not_started} not started; the finished outputs are kept",
+            f"{not_started} not started; the finished outputs are kept"
+            + ((f", and {', '.join(kept)} " + ("was written by a step that was stopped and is" if len(kept) == 1 else
+                                              "were written by steps that were stopped and are") + " kept, unverified")
+               if kept else ""),
             code=128 + int(interrupted["signal"] or 2), kind="interrupted", output=None, dry_run=STATE.dry_run, results=results,
             processed=done, total=len(results), jobs=jobs, jobs_requested=requested,
             timed_out=timed_out["hit"])
+    if refused["hit"]:
+        rows = [r for r in results if ((r.get("error") or {}).get("reason")) == STEP_WRITES_WITHOUT_OUT]
+        first = rows[0]["error"]
+        files = [r["error"]["details"]["file"] for r in rows]
+        written = [f for r, f in zip(rows, files) if r["error"]["details"].get("written")]
+        not_run = sum(1 for r in results if r.get("skipped") == "recipe_refused")
+        die(first["message"] + (f" ({len(rows)} items in flight wrote one each: {', '.join(written)})" if len(written) > 1 else "")
+            + (f"; {not_run} item(s) not started" if not_run else ""),
+            kind="input", hint=first.get("hint"), output=None, dry_run=STATE.dry_run, results=results,
+            processed=done, total=len(results),
+            error_extra={"reason": STEP_WRITES_WITHOUT_OUT,
+                         "details": dict(first["details"], files=files, written_files=written, not_started=not_run)})
     if timed_out["hit"]:
         skipped = [r["file"] for r in results if r.get("skipped") == "timeout"]
         die(f"the batch's {STATE.timeout:g} s budget ran out with {len(skipped)} item(s) not "
@@ -1140,8 +1368,15 @@ def main() -> int:
             for r in res.get("cut_reencode_reasons") or []:
                 reasons[r] = reasons.get(r, 0) + 1
         why = (" (reencode_reason: " + ", ".join(f"{k} x{v}" for k, v in reasons.items()) + ")") if reasons else ""
-        info(f"cut.py: {copied}/{len(all_cuts)} call(s) stayed fully lossless stream-copy "
-             f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} re-encoded a range or its --segments join{why}")
+        if STATE.dry_run:
+            # a dry run's counts are cut.py's plans: a planned copy may still re-encode in a real run,
+            # which measures where it lands (cut.py's possible_reencode_reason, #510)
+            info(f"cut.py: {copied}/{len(all_cuts)} call(s) planned as a lossless stream copy "
+                 f"({cut_summary['stream_copy_rate']:.0%}), which a real run may still re-encode (each row's "
+                 f"cut_possible_reencode_reason); {len(all_cuts) - copied} planned to re-encode a range or its --segments join{why}")
+        else:
+            info(f"cut.py: {copied}/{len(all_cuts)} call(s) stayed fully lossless stream-copy "
+                 f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} re-encoded a range or its --segments join{why}")
     unverified = [shown(os.path.basename(r["file"])) for r in results if r.get("ok") and not r.get("verified")]
     if unverified and not STATE.dry_run:
         note(f"{len(unverified)} item(s) completed but did not verify everything they wrote (see each row's unverified): "

package/scripts/cut.py

@@ -260,6 +260,38 @@ def _outcome(meta: dict, dst: str, reencoded: bool, reasons: List[str], **copy)
 EDIT_LIST_EXTS = (".mp4", ".mov", ".m4v")
 
 
+def possible_reencode_reason(mode: str, outcomes: List[dict], segments: int) -> List[str]:
+    """Under --dry-run, the reencode_reason values a real run may still add to a plan of mode copy
+    or smart, which would then report hybrid or accurate (#510): the dry run reads no packets for a
+    single copy, so where its copy lands, and every check a real run makes on the written file,
+    are not known yet. [] for a real run and for a plan that already re-encodes."""
+    if not STATE.dry_run:
+        return []
+    if mode == "smart":
+        return ["smart_fallback"]  # the checks run on the written file (smart.checks is null)
+    if mode != "copy":
+        return []
+    possible = ["copy_failed", "stream_lost"]
+    if any(o.get("length_unjudged") for o in outcomes):
+        possible.append("tolerance")
+    if segments > 1:
+        possible.append("concat_fallback")
+    return possible
+
+
+def possible_reencode_note(mode: str, possible: List[str], tolerance: float) -> str:
+    """The plan's notes line for possible_reencode_reason."""
+    if mode == "smart":
+        return ("planned as a smart cut: a real run checks the written cut against the source and re-encodes "
+                "the whole cut instead (mode accurate, reencode_reason smart_fallback) when a check fails")
+    why = ("planned as a stream copy: a real run may re-encode it instead (mode hybrid, reencode_reason "
+           + ", ".join(possible) + ")")
+    if "tolerance" in possible:
+        why += (f"; where the copy lands is measured only from the written file, and a copy that lands "
+                f"{tolerance:.2f}s (--tolerance) or more from the requested cut is re-encoded")
+    return why
+
+
 def _with_notes(outcome: dict, notes: List[str]) -> dict:
     """An outcome with the notes of the attempt that led to it put first."""
     outcome["notes"] = list(notes) + list(outcome.get("notes") or [])
@@ -1013,10 +1045,15 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
                  f"(> {tolerance:.2f}s tolerance); re-encoding this segment for accuracy{alt}")
             return _with_notes(cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["tolerance"], edit_list_ok), notes)
     if reencode or audio_only:
-        return _outcome(meta, dst, reencode, reasons)
+        # an audio-only copy is judged by its written length too (above): a dry run that wrote
+        # nothing says a real run may still re-encode it (#510 review)
+        pending = {"length_unjudged": True} if (STATE.dry_run and not reencode and copy_t is None and tolerance >= 0) else {}
+        return _outcome(meta, dst, reencode, reasons, **pending)
     if STATE.dry_run:
-        # the planned copy: whether it keeps an edit list is known; where it lands is not
-        return _outcome(meta, dst, False, reasons, edit_list=edit_list and edit_list_ok, start_snapped=None)
+        # the planned copy: whether it keeps an edit list is known; where it lands is not, so a
+        # real run that judges the written copy by its length may still re-encode it (#510)
+        return _outcome(meta, dst, False, reasons, edit_list=edit_list and edit_list_ok, start_snapped=None,
+                        length_unjudged=copy_t is None and tolerance >= 0)
     fps = (meta.get("video") or {}).get("fps")
     # a concat part's edit list does not hide its pre-roll in the join, so it presents from the keyframe
     shown = edit_list and edit_list_ok
@@ -1877,6 +1914,9 @@ def main() -> int:
     mode = ("smart" if smart_doc is not None and smart_doc["applied"] else
             "copy" if not reencoded else ("accurate" if args.accurate else "hybrid"))
     notes: List[str] = vfr_notes + join_notes + [n for o in outcomes for n in o.get("notes") or []]
+    possible = possible_reencode_reason(mode, outcomes, len(segments))
+    if possible:
+        notes.append(possible_reencode_note(mode, possible, args.tolerance))
     single = outcomes[0] if len(outcomes) == 1 else {}
     stored = single.get("stored_preroll_seconds")
     if single.get("edit_list") and stored:
@@ -1930,7 +1970,7 @@ def main() -> int:
          requested_segments=[[round(s, 6), round(e, 6)] for s, e in requested] if len(requested) > 1 else None,
          requested_duration=round(expected, 6), output_duration=round(got, 6) if got is not None and not STATE.dry_run else None,
          duration_delta_seconds=round(error_ms / 1000, 6) if error_ms is not None else None,
-         mode=mode, keyframe_snapped=report["keyframe_snapped"], start_snapped=report["start_snapped"],
+         mode=mode, possible_reencode_reason=possible, keyframe_snapped=report["keyframe_snapped"], start_snapped=report["start_snapped"],
          reencode_reason=reencode_reason, least_exact_precision=report["least_exact_precision"],
          segment_precision=report["segment_precision"],
          edit_list=bool(single.get("edit_list")), stored_preroll_seconds=stored, av_start_skew_seconds=skew,

package/scripts/fit.py

@@ -36,9 +36,9 @@ Examples:
 import argparse
 import sys
 from fractions import Fraction
-from typing import List
+from typing import Any, List
 
-from _common.decision import SEEK_MARGIN, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, stream_starts
+from _common.decision import SEEK_MARGIN, atempo_chain_with_lead, delivered_rate, frame_durations, frame_rate, grid_at_or_after, length_output_t, stream_starts
 from _common.timeline import exact_rate, output_timecode_args
 from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, cfr_args, cfr_filter, default_output, die, ffmpeg_base, info, probe, run, run_keeping_subtitles, validate_color, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs, frame_size, display_size, square_pixels, square_pixels_note, note
 from _common.emit import input_length
@@ -53,18 +53,21 @@ def parse_aspect(value: str) -> Fraction:
     return ratio
 
 
-def atempo_chain(factor: float) -> str:
-    """atempo accepts 0.5..100 per instance; chain for extreme factors."""
+def atempo_chain(factor: float, sample_rate: Any = 0) -> str:
+    """atempo accepts 0.5..100 per instance; chain for extreme factors. The chain is led by the
+    samples atempo leaves out (atempo_chain_with_lead, at the track's `sample_rate`), so the
+    retimed sound keeps its timing against the retimed picture (#523: about 21 ms early in input
+    time without them)."""
     parts: List[str] = []
     remaining = factor
     while remaining < 0.5:
-        parts.append("atempo=0.5")
+        parts.append("0.5")
         remaining /= 0.5
     while remaining > 100.0:
-        parts.append("atempo=100.0")
+        parts.append("100.0")
         remaining /= 100.0
-    parts.append(f"atempo={remaining:.6f}")
-    return ",".join(parts)
+    parts.append(f"{remaining:.6f}")
+    return atempo_chain_with_lead(parts, sample_rate)
 
 
 def picture_output_t(target: float, meta: dict) -> str:
@@ -218,7 +221,7 @@ def main() -> int:
                     vf.append(frame_durations(meta, delivered_rate(meta) or frame_rate(meta) or src_fps))
                     regridded = True
                 if has_audio:
-                    af.append(atempo_chain(factor))
+                    af.append(atempo_chain(factor, rate))
             # atempo's sound is not the input's length over the factor (it comes out some
             # milliseconds short or long), and the millisecond -t stays on a retimed track: padding
             # it to the target's samples (apad after atempo in -af) never ended on FFmpeg 8.0.1