ffmpeg-skill 3.1.7 → 3.2.0

package/scripts/_contract.py

@@ -131,7 +131,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                                             {"capability": "filter:scdet", "when": "--auto-chapters --from scenes|both"}],
                      video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "loop": dict(role="execution", inputs=["video asset"], outputs=["video artifact repeated to the requested count or duration (--boomerang: played forward then backward, silent)"],
-                 required=FF + [X264, AAC], optional=[{"capability": "filter:reverse", "when": "--boomerang"}, {"capability": "filter:loop", "when": "--boomerang"}],
+                 required=FF + [X264, AAC], optional=[{"capability": "filter:reverse", "when": "--boomerang"}, {"capability": "filter:loop", "when": "--boomerang"}, {"capability": "filter:xfade", "when": "--crossfade"}, {"capability": "encoder:ffv1", "when": "--crossfade"}, {"capability": "encoder:flac", "when": "--crossfade"}],
                  video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "insert": dict(role="execution", inputs=["still image"], outputs=["silent video artifact of the requested duration / frame size / fps"],
                    required=FF + [X264], optional=[{"capability": "filter:zoompan", "when": "--zoom / --pan"}],
@@ -197,8 +197,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   required=FF + [X264, AAC], optional=[HDR_X265],
                   video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
-                   required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
-                                          {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
+                   required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores and dnxhr-* use pcm_s16le, copy stream-copies, gif has no audio)"},
+                                          {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"}, {"capability": "encoder:dnxhd", "when": "preset dnxhr-lb / dnxhr-sq / dnxhr-hq / dnxhr-hqx / dnxhr-444"}, {"capability": "encoder:prores_ks", "when": "preset prores4444 / prores4444xq / key-fill"}, {"capability": "encoder:qtrle", "when": "preset qtrle"}, {"capability": "encoder:libvpx-vp9", "when": "preset vp9-alpha"}, {"capability": "encoder:hap", "when": "preset hap-alpha (an ffmpeg built with snappy)"}, {"capability": "filter:alphaextract", "when": "an alpha preset (the alpha is read back)"},
                                           {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
                                                      {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"},
                                           {"capability": "filter:loudnorm", "when": "preset youtube / youtube4k / reels / x with audio: the written file is measured against the platform's loudness target (result `loudness`)"}],
@@ -219,7 +219,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)", "editor timeline (.fcpxml / .edl / .otio) instead of a render (--export-timeline)"],
                    required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
                    video_required=False, audio_only=True, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
-    "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
+    "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir (none for a steps recipe, not a render project, in which no step names {out}: its rows carry written: false)", "content-hash cache"],
                   required=FF, optional=[{"capability": "delegated", "when": "each recipe step runs the named script with its capabilities"}],
                   video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="cached", deterministic=True),
     "verify": dict(role="verification", inputs=["media files and/or folders"], outputs=["PASS/FAIL JSON per step", "Markdown report (--report)", "step outputs (--out / --keep)"],
@@ -276,7 +276,7 @@ REENCODE_META: Dict[str, Dict[str, str]] = {
     "speedramp": dict(video="always", audio="always", note="setpts/atempo per segment always forces a re-encode of both streams"),
     "broll":    dict(video="always", audio="conditional", note="the overlay graph always re-encodes the video stream; A's audio is stream-copied under --audio a and re-encoded to AAC under --audio b/mix"),
     "metadata": dict(video="never", audio="never", note="-c copy on every stream; only the container's chapters and tags change -- --auto-chapters decodes to measure, but still writes with -c copy"),
-    "loop":     dict(video="always", audio="conditional", note="the repeats (the concat demuxer, the file listed once per repeat) always re-encode both streams; the audio codec is always AAC when present. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
+    "loop":     dict(video="always", audio="conditional", note="the repeats (the concat demuxer, the file listed once per repeat) always re-encode both streams; the audio codec is always AAC when present. --crossfade first writes one repeat losslessly (FFV1 + FLAC, a temporary file) and repeats that, so the output still has one lossy encode. --boomerang re-encodes the video through reverse/loop filters and drops the audio"),
     "insert":    dict(video="always", audio="never", note="always encodes a fresh silent clip from the still image; there is no audio stream to touch"),
     "background": dict(video="always", audio="never", note="always encodes a fresh generated clip; there is no input to copy from"),
     "reverse":   dict(video="always", audio="conditional", note="video always re-encodes (reverse buffers and re-emits every frame); audio re-encodes to AAC when present and not dropped by --no-audio"),
@@ -622,7 +622,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given; with --fix-drift each also carries drift_skipped_reason"},
                  "drift_skipped_reason": {"type": ["string", "null"], "enum": ["too_short", "low_confidence", None], "description": "--fix-drift, one SOURCE: why the drift correction was not applied (too_short: no tail window far enough from the head; low_confidence: the tail did not correlate), null when it was; also a diagnostics.skipped entry, drift_correction_skipped"}}
     elif name == "look":
-        extra = {"outputs": {"type": "array", "items": {"type": "string"}}}
+        extra = {"outputs": {"type": "array", "items": {"type": "string"}},
+                 "guides": {"type": "array", "description": "--guides only: each outline drawn on the PNG, {guide: action|title, fraction (0.93 / 0.90 of the frame, SMPTE ST 2046-1), of: frame} or {guide: 4:3, window, action: 0.90, title: 0.80}; drawn on the preview only"}}
     elif name == "render":
         extra = {"stages": {"type": "array", "items": {"type": "string"}}, "check": {"type": ["object", "null"], "description": "check.py's document for a \"check\" stage with a platform, \"content\": true, or both; when check.py printed none, a failure document with error.reason check_output_unparsed"},
                  "cache": {"type": ["object", "null"], "description": "--cache: {dir, ffmpeg, hits, misses, miss_reasons: [{stage, reason: not_cached|sidecar_missing|artifact_missing|sidecar_corrupt|artifact_truncated|no_output_path, ...}], saved_seconds, entries, would_hit (--dry-run)}"},
@@ -652,14 +653,19 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "export":
         extra = {"repair": {"type": "object", "description": "--repair (2.24): {before, after}, each {timestamp_warnings, decode_errors} counted over one full decode at -v warning"},
                  "loudness": {"type": "object", "description": "platform presets with audio: the written file's lufs/tp against the platform's target_lufs/target_tp, ok true when inside the spec; normalized true when --normalize ran loudness.py on the file; silent true (lufs \"-inf\", ok false, no normalize) when the written audio is silent; measured false (lufs, tp and ok null, reason not_measured) when the measurement could not be read"},
+                 "alpha_mode": {"enum": ["straight", "premultiplied"], "description": "alpha presets only (prores4444, prores4444xq, qtrle, vp9-alpha, hap-alpha): how the colour was written, from --alpha-mode (default straight). The `alpha` verification step compares the written file's alpha with the source's frame by frame, tolerance 2 of 255 per frame (comparison: {ok, paired, worst_delta, worst_frame}; with a different frame count the mean and the most transparent frame, paired false; frames: {expected, measured}, each {mean, min, frames}); `codec` compares the written codec and profile with the preset's"},
+                 "key": {"type": "object", "description": "--preset key-fill only: the key file {output (<out stem>_key.mov), identity, sha256, timecode (the source's start timecode written on both, or null)}. Verification adds key_fill_pair (width, height, frame count, rate and the video streams' lengths equal on both files) and key_level (the key's level against the source's alpha frame by frame, tolerance 2 of 255); the source's subtitle/data streams are not written (non_av_streams.dropped, reason key_fill)"},
+                 "fill_sha256": {"type": "string", "description": "--preset key-fill only: the fill file's SHA-256 (the key's is key.sha256)"},
                  "trimmed": {"type": "object", "description": "present when the source was longer than the preset's platform maximum and the export was cut to it (no --allow-long): {from, to} in seconds; notes says so too"},
-                 "non_av_streams": {"type": "object", "description": "the source's subtitle and data streams: {kept: [{type: subtitle|data, index (n-th of its type), codec, language (subtitle), output_codec}], dropped: [{type, index, codec, language, reason: write_failed|gif|not_in_output}]}, read back from the written file (under --dry-run, as planned). A subtitle track is copied when the container holds it as it is, else converted to the container's text track (mov_text in .mp4/.mov, SubRip in .mkv); a trimmed export cuts it at the same point. Both lists are empty for a source with neither"},
+                 "non_av_streams": {"type": "object", "description": "the source's subtitle and data streams: {kept: [{type: subtitle|data, index (n-th of its type), codec, language (subtitle), output_codec}], dropped: [{type, index, codec, language, reason: write_failed|gif|key_fill|not_in_output}]}, read back from the written file (under --dry-run, as planned). A subtitle track is copied when the container holds it as it is, else converted to the container's text track (mov_text in .mp4/.mov, SubRip in .mkv); a trimmed export cuts it at the same point. Both lists are empty for a source with neither"},
                  "dropped_non_av_streams": {"type": "boolean", "description": "true when non_av_streams.dropped is not empty; a notes line says so too"},
                  "notes": {"type": "array", "items": {"type": "string"}}}
     elif name == "loudness":
         extra = {"measured": {"type": "object", "description": "the loudnorm measurement of the input (input_i, input_tp, input_lra, input_thresh, target_offset); with --measure-only it is the whole result"},
                  "targets": {"type": "object", "description": "the requested lufs / tp / lra"},
-                 "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"}}
+                 "result": {"type": "object", "description": "the written file measured again (input_i, input_tp, input_lra, ...), plus tp_ceiling_used, audio_bitrate_used and encodes"},
+                 "versions": {"type": "array", "description": "--versions only (output is then null): one row per target, {target, output, targets, result}; every row's loudness and duration steps are in verification with a `version` key, and verified is true only when every version met its own target"},
+                 "outputs": {"type": "array", "items": {"type": "string"}, "description": "--versions only: the files written, in the order asked"}}
     elif name == "color":
         extra = {"dropped_non_av_streams": {"type": "boolean"},
                  "sdr_path": {"enum": ["tonemap", "gamut"], "description": "--to-sdr only: tonemap for PQ / HLG / Dolby Vision (and --force on an untagged file); gamut for BT.2020 primaries on an SDR transfer, converted to BT.709 without a tone map"},
@@ -668,6 +674,9 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "measurements": {"type": "object", "description": "--correct only: signalstats levels of input and output"}}
     elif name == "loop":
         extra = {"boomerang": {"type": "boolean", "description": "--boomerang: frames 0..N-1 then N-2..1, repeated, so neither turnaround frame is shown twice"},
+                 "crossfade": {"type": "number", "description": "--crossfade only: the fade used, in seconds, rounded to whole frames; one repeat is the clip minus this"},
+                 "expected_duration": {"type": "number", "description": "seconds requested: --duration, or --times x one repeat (the clip, the clip minus the crossfade, or a boomerang round trip); the duration verification step compares the file against it within 1.5 frames"},
+                 "seam": {"type": "object", "description": "not with --boomerang: the first seam of the written file measured (at: between_repeats, or end_to_start for one repeat; time; video_step and video_typical_step, the mean luma change across the seam and the median one between neighbouring frames on a 64x36 grey copy, 0-255; audio_level_step_db, the RMS level 20 ms after the seam minus 20 ms before). A measurement, not a pass/fail: a step far above the typical one is a visible jump"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "--boomerang on a source with audio: the audio was dropped"}}
     elif name == "cut":
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},

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, add_hw_orchestrator_args, env_hw, stop_children
+from _common.runner import HW_FORCED_ENV, _OutputLock, add_hw_orchestrator_args, env_hw, stop_children
 from _common.emit import absorb_stage_hw, audit, note, shown, steps_encoder_report, warn
 
 HERE = Path(__file__).resolve().parent
@@ -59,6 +59,30 @@ def file_key(path: Path) -> str:
     return h.hexdigest()
 
 
+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
+    pass is served its old verdict against a reference that changed or is gone (#428 review).
+    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:
+                continue
+            value = arg.split("=", 1)[1] if arg.startswith("-") and "=" in arg else arg
+            if value.startswith("-") or not value:
+                continue
+            path = Path(value)
+            try:
+                if path.is_file():
+                    h.update(f"{value}\0{file_key(path)}\0".encode())
+                    continue
+            except OSError:
+                pass
+            h.update(f"{value}\0-\0".encode())  # absent now: different from when it existed
+    return h.hexdigest()[:8]
+
+
 def recipe_key(recipe: Dict[str, Any]) -> str:
     # A "project" recipe is just {"project": "<path>", "clip_key": N} -- the actual settings
     # (export preset, captions, everything) live in the file at that path, not in this dict.
@@ -182,9 +206,80 @@ def final_path(src: Path, recipe: Dict[str, Any], outdir: Path) -> Path:
     # detection of its own; see one_pass()'s pre-flight check, which uses this same computation
     # to catch that before any file is actually processed (and the earlier one silently clobbered).
     final_ext = recipe.get("ext") or src.suffix.lstrip(".") or "mp4"
+    steps = recipe.get("steps") or []
+    if not recipe.get("ext") and not recipe.get("project") and steps and not step_writes(steps[-1]) and not writes_nothing(recipe):
+        # the last step writes nothing, so what is delivered is an intermediate: its name says its
+        # container (a .webm source's fit.py step writes MP4, which must not be named .webm)
+        final_ext = intermediate_ext(src)
     return outdir / f"{src.stem}{suffix}.{final_ext}"
 
 
+def intermediate_ext(src: Path) -> str:
+    """The extension of an item's intermediate step files: the source's own for an audio file,
+    else mp4 (the tools' encoders write x264/AAC, which .webm and friends do not take)."""
+    return src.suffix.lstrip(".") if src.suffix.lower() in (".wav", ".mp3", ".m4a", ".flac") else "mp4"
+
+
+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:])
+
+
+def writes_nothing(recipe: Dict[str, Any]) -> bool:
+    """A steps recipe in which no step names {out}: it measures each file and writes none."""
+    return not recipe.get("project") and not any(step_writes(st) for st in recipe.get("steps") or [])
+
+
+def row_output(src: Path, recipe: Dict[str, Any], outdir: Path) -> Dict[str, Any]:
+    """An item's output fields for its row: `output` is always the final path, a string as it has
+    been since 1.x (a --json key never changes type within a major), and a recipe that writes
+    nothing adds `written: false` (#415, #428 review)."""
+    fields: Dict[str, Any] = {"output": str(final_path(src, recipe, outdir))}
+    if writes_nothing(recipe):
+        fields["written"] = False
+    return fields
+
+
+def deliver(src: str, final: Path) -> None:
+    """Move an item's last written intermediate to its final path, under the output guard every
+    tool applies: an existing file is replaced only with --overwrite. A dry run writes nothing."""
+    if STATE.dry_run:
+        # the refusal the real run would meet, as a step writing {out} plans it (#428 review)
+        if final.exists() and not STATE.overwrite:
+            raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
+                             "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
+        log(f"  [dry-run] would deliver the last written file to {final}")
+        return
+
+    def locked(msg: str, hint: str, details: Dict[str, Any]) -> None:
+        raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_locked",
+                         "message": msg, "hint": hint, "details": details})
+    # under the output lock every tool's write holds, so the existence check and the move are one
+    # step for another run delivering or writing the same path
+    with _OutputLock(str(final), on_locked=locked):
+        if final.exists() and not STATE.overwrite:
+            raise ItemError({"step": None, "tool": None, "kind": "input", "reason": "output_exists",
+                             "message": f"refusing to overwrite existing output {str(final)!r}: pass --overwrite to replace it"})
+        try:
+            os.replace(src, final)
+        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}")
+            try:
+                shutil.copyfile(src, tmp)
+                os.replace(tmp, final)
+            except OSError as exc:
+                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}")
+
+
 def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             deadline: "Optional[float]" = None) -> Dict[str, Any]:
     final = final_path(src, recipe, outdir)
@@ -211,7 +306,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
             proj["clips"].append({})
         proj["clips"][idx]["src"] = str(src.resolve())
         proj["output"] = str(final.resolve())
-        pj = work / f"{src.stem}_project.json"
+        pj = work / "project.json"
         pj.write_text(json.dumps(proj, indent=2), encoding="utf-8")
         ok, _doc = run_step(["render.py", str(pj)], budget())
         step_docs = [("render", _doc)]
@@ -231,7 +326,11 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         cut_reasons = []
         for i, step in enumerate(steps):
             last = i == len(steps) - 1
-            out = str(final) if last else str(work / f"{src.stem}_step{i}.{'mp4' if src.suffix.lower() not in ('.wav', '.mp3', '.m4a', '.flac') else src.suffix.lstrip('.')}")
+            # the item's directory is its own, so the name needs no stem (a long one overflowed it)
+            out = str(final) if last else str(work / f"step{i}.{intermediate_ext(src)}")
+            # a step that names no {out} (check.py, probe.py) writes nothing: the next step reads
+            # what this one read, and when it is the last, the last file written is delivered (#415)
+            writes = step_writes(step)
             argv = [str(a).replace("{in}", cur).replace("{out}", out) for a in step]
             step_ok, doc = run_step(argv, budget())
             step_docs.append((Path(str(argv[0])).stem if argv else "step", doc))
@@ -246,8 +345,16 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
                 ok = False
                 failure = step_error(i, str(argv[0]) if argv else None, doc)
                 break
-            cur = out
-    result: Dict[str, Any] = {"file": str(src), "output": str(final), "ok": ok, "seconds": round(time.time() - t0, 1)}
+            if writes:
+                cur = out
+        if ok and cur != str(final) and not writes_nothing(recipe):
+            # the last step wrote nothing: the item's deliverable is the last file a step wrote,
+            # which is in this item's work directory and would be removed with it (#415)
+            try:
+                deliver(cur, final)
+            except ItemError as exc:
+                ok, failure = False, exc.error
+    result: Dict[str, Any] = {"file": str(src), **row_output(src, recipe, outdir), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if failure:
         result["error"] = failure
     # `ok` is "every step completed" (design-decisions: a spec miss a tool cannot fix is completed +
@@ -291,6 +398,8 @@ def cached_output_changed(hit: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
     output_missing, output_changed (size or mtime differ: something replaced or edited it) or
     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)."""
+    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 "")
     now = output_identity(out) if out else None
     if now is None:
@@ -344,9 +453,22 @@ def main() -> int:
             if not isinstance(name, str) or name not in ALLOWED_STEP_SCRIPTS:
                 die(f"recipe step names a script that isn't one of this skill's own tools: {name!r} "
                     f"(must be a bare filename like 'silence.py', found in scripts/)")
+        if writes_nothing(recipe):
+            # a QC batch (check.py / probe.py on every file): its rows carry written: false, and its
+            # cache entries claim no file, so they are served rather than missed as output_missing (#415)
+            note("no recipe step names {out}: the steps only read each file, so no output is written "
+                 "(each row says written: false; its output path is not created)")
     outdir = Path(recipe.get("output_dir") or (folder / "out"))
     if not outdir.is_absolute():
         outdir = folder / outdir
+    # resolved, so an alias of the input folder ("sub/..", a symlink) is recognised as one: the
+    # input scan below excludes outdir's files by parentage, and the input check by resolved path
+    outdir = outdir.resolve()
+    if outdir == folder:
+        # the scan skips files under outdir, so it found nothing here, and with suffix "" a
+        # final path was the source itself, which --overwrite replaced (#428 review)
+        die(f"output_dir {recipe.get('output_dir')!r} is the input folder {folder}: its outputs would mix with "
+            "or replace the batch inputs -- set an \"output_dir\" outside it (the default is out/)", kind="input")
     work = Path(args.work) if args.work else outdir / ".work"
     # the children refuse an output whose directory does not exist, under --dry-run too, so the
     # directories are created for the plan as well -- and removed again afterwards when a dry
@@ -435,23 +557,47 @@ def main() -> int:
         # collapsing e.g. clip.mp4 and clip.mov to the same clip_out.mp4) -- catch that before
         # processing anything, rather than letting the later one silently overwrite the earlier
         # one's finished output with the cache still recording both as "ok".
-        by_final: Dict[Path, List[Path]] = {}
+        # Compared case-folded: Clip_out.mp4 and clip_out.mp4 are one file on macOS's and
+        # Windows' default filesystems, so a batch that only works on Linux is refused everywhere (#415).
+        by_final: Dict[str, List[Path]] = {}
         for src in files:
-            by_final.setdefault(final_path(src, recipe, outdir), []).append(src)
-        collisions = {dst: srcs for dst, srcs in by_final.items() if len(srcs) > 1}
+            by_final.setdefault(str(final_path(src, recipe, outdir)).casefold(), []).append(src)
+        collisions = {key: srcs for key, srcs in by_final.items() if len(srcs) > 1 and not writes_nothing(recipe)}
         if collisions:
-            detail = "; ".join(f"{dst.name} <- {', '.join(s.name for s in srcs)}" for dst, srcs in collisions.items())
-            die(f"{len(collisions)} output filename collision(s) in this batch -- rename the sources, "
+            detail = "; ".join(" / ".join(sorted({final_path(s, recipe, outdir).name for s in srcs}))
+                               + " <- " + ", ".join(s.name for s in srcs) for srcs in collisions.values())
+            die(f"{len(collisions)} output filename collision(s) in this batch (names that differ only in case are one "
+                f"file on macOS and Windows) -- rename the sources, "
                 f"or add a distinguishing \"suffix\"/\"ext\" per run, or split into separate globs: {detail}")
+        # A final path that is one of the inputs would replace a source -- an output_dir that is
+        # the input folder under another name ("sub/..") with suffix "" -- and --overwrite does
+        # not license that (#428 review). A recipe that writes nothing delivers no file.
+        if not writes_nothing(recipe):
+            inputs = {str(p.resolve()).casefold() for p in files}
+            hits = [s for s in files if str(final_path(s, recipe, outdir).resolve()).casefold() in inputs]
+            if hits:
+                die(f"{len(hits)} final output path(s) would replace a batch input ({', '.join(s.name for s in hits)}); "
+                    "the output_dir is the input folder -- set a different \"output_dir\" or a non-empty \"suffix\"",
+                    kind="input")
         def item_work(i: int, src: Path) -> Path:
-            """Where this item's intermediates go. Parallel items must not share one work dir:
-            the step file names are stem-derived, so two globs holding the same stem would write
-            over each other. Serial runs keep the flat layout 1.16 used, byte for byte."""
-            if jobs == 1:
-                return work
-            sub = work / f"{i}-{src.stem}"
-            sub.mkdir(parents=True, exist_ok=True)
-            return sub
+            """Where this item's intermediates go: a new directory of its own under the work
+            directory, removed with everything in it when the item ends (run_item()). The step
+            file names are stem-derived, so two items with one stem (clip.mp4, clip.mov) sharing a
+            directory refused each other's files, and a later run refused the files an earlier one
+            left there as someone else's (#415); parallel items had their own directories since
+            1.17, serial ones now do too."""
+            import tempfile
+            # no stem in the name: a stem near the 255-byte limit made the directory name too long
+            return Path(tempfile.mkdtemp(prefix=f"{i}-", dir=str(work)))
+
+        def run_item(i: int, src: Path) -> Dict[str, Any]:
+            """process() in the item's own work directory, which goes when it ends, however it ends."""
+            import shutil
+            iw = item_work(i, src)
+            try:
+                return process(src, recipe, outdir, iw, deadline)
+            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):
@@ -462,10 +608,10 @@ def main() -> int:
             with cache_lock:
                 # this run just rewrote r["output"]: an entry under another key (another recipe,
                 # the other GPU setting) that names the same file now describes bytes that are gone
-                for stale in [k for k, v in cache.items() if k != key and isinstance(v, dict) and v.get("output") == r["output"]]:
+                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"]))
+                cache[key] = dict(r, output_identity=output_identity(r["output"]) if r["output"] and r.get("written", True) else None)
                 # 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
@@ -483,8 +629,9 @@ def main() -> int:
         slots: "List[Optional[Dict[str, Any]]]" = [None] * len(files)
         pending: List[tuple] = []
         cache_miss: Dict[int, Dict[str, Any]] = {}
+        pass_key = rkey + side_inputs_key(recipe)
         for i, src in enumerate(files):
-            key = f"{file_key(src)}:{rkey}"
+            key = f"{file_key(src)}:{pass_key}"
             hit = cache.get(key)
             if isinstance(hit, dict) and not args.force:
                 why = cached_output_changed(hit)
@@ -503,7 +650,7 @@ def main() -> int:
 
         def timed_out_row(src: Path) -> "Dict[str, Any]":
             timed_out["hit"] = True
-            return {"file": str(src), "output": str(final_path(src, recipe, outdir)),
+            return {"file": str(src), **row_output(src, recipe, outdir),
                     "ok": False, "seconds": 0.0, "skipped": "timeout"}
 
         def failed_row(src: Path, exc: BaseException) -> "Dict[str, Any]":
@@ -522,13 +669,13 @@ def main() -> int:
                 error = {"step": None, "tool": None, "exception": exc.__class__.__name__,
                          "message": (str(exc) or exc.__class__.__name__)[:300]}
             log(f"    failed: {error['message']}")
-            return {"file": str(src), "output": str(final_path(src, recipe, outdir)),
+            return {"file": str(src), **row_output(src, recipe, outdir),
                     "ok": False, "verified": False, "seconds": 0.0, "error": error}
 
         def interrupted_row(src: Path, started: bool, r: "Optional[Dict[str, Any]]" = None) -> "Dict[str, Any]":
             """An item the interrupt reached: `interrupted: true` when it was running (its steps
             were stopped), `skipped: "interrupted"` when it had not started."""
-            row = dict(r) if r else {"file": str(src), "output": str(final_path(src, recipe, outdir)), "seconds": 0.0}
+            row = dict(r) if r else {"file": str(src), **row_output(src, recipe, outdir), "seconds": 0.0}
             row.update(ok=False, verified=False)
             if started:
                 row["interrupted"] = True
@@ -550,7 +697,7 @@ def main() -> int:
                     continue
                 info(f"=== {src.name}")
                 try:
-                    r = process(src, recipe, outdir, item_work(i, src), deadline)
+                    r = run_item(i, src)
                 except KeyboardInterrupt:
                     interrupted["hit"] = True
                     # the running item, then every one not started: each keeps its row
@@ -572,7 +719,7 @@ def main() -> int:
         def work_one(i: int, src: Path, key: str) -> Dict[str, Any]:
             _LOG.buffer = [f"=== {src.name}"]
             try:
-                r = process(src, recipe, outdir, item_work(i, src), deadline)
+                r = run_item(i, src)
                 if not interrupted["hit"]:   # a step the interrupt stopped is no result to keep
                     store(key, r)
                 return with_miss(i, r)
@@ -670,7 +817,7 @@ def main() -> int:
     info(f"{done}/{len(results)} processed, {sum(1 for r in results if r.get('cached'))} from cache")
     if not args.json:
         for r in results:
-            print(f"{'OK  ' if r['ok'] else 'FAIL'} {r['file']} -> {r['output']}" + (" (cached)" if r.get("cached") else ""))
+            print(f"{'OK  ' if r['ok'] else 'FAIL'} {r['file']} -> {r['output'] or '(no output: the steps only read it)'}" + (" (cached)" if r.get("cached") else ""))
     if interrupted["hit"]:
         # Ctrl-C on a batch that already produced files: the user needs the partial table, not a
         # traceback and not "nothing was written". Exit 130 (143 for SIGTERM) with every item:
@@ -684,7 +831,7 @@ def main() -> int:
             timed_out=timed_out["hit"])
     if timed_out["hit"]:
         skipped = [r["file"] for r in results if r.get("skipped") == "timeout"]
-        die(f"the batch's {STATE.timeout:.0f} s budget ran out with {len(skipped)} item(s) not "
+        die(f"the batch's {STATE.timeout:g} s budget ran out with {len(skipped)} item(s) not "
             f"started: {', '.join(os.path.basename(f) for f in skipped[:5])}"
             + (" ..." if len(skipped) > 5 else "")
             + ". --timeout is the whole run's limit, not each item's; raise it or split the folder.",

package/scripts/check.py

@@ -32,6 +32,7 @@ the row set is unchanged.
 """
 import argparse
 import json
+import os
 import re
 import sys
 from fractions import Fraction
@@ -164,6 +165,12 @@ def main() -> int:
 
     # read before anything is measured and again after: a file replaced mid-check is not the one graded
     identity_before = None if dry_run_input_pending(args.input) else file_identity(args.input)
+    if identity_before is None and STATE.dry_run and not os.path.exists(args.input):
+        # a render/batch plan's earlier stage would write this file: there is nothing to grade yet,
+        # and grading the probe's empty answer divided by a 0 height
+        emit(None, platform=args.platform, checks=[], failed=0, warnings=0, ok=False,
+             notes=[f"[dry-run] {args.input} does not exist yet, so nothing was checked"])
+        return 0
     meta = probe(args.input)
     v, a = meta.get("video") or {}, meta.get("audio") or {}
     rows: List[Dict[str, Any]] = []

package/scripts/color.py

@@ -23,6 +23,7 @@ import os
 import sys
 from typing import List, Optional
 
+from _common.runner import fail_if_classified
 from _common import STATE, add_common, analyze_levels, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, ffmpeg_bsfs, info, probe, require_tool, run, run_analysis, run_keeping_subtitles, x264_args, X264_PRESETS, fmt_secs
 from _common.emit import warn
 
@@ -320,6 +321,7 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
         cmd += ["-movflags", "+faststart"]
     cmd.append(output)
     proc = run(cmd, check=False)
+    fail_if_classified(proc)  # a full disk fails the re-encode too: its error, not two more encodes (#415)
     notes: List[str] = []
     reencoded = proc.returncode != 0
     if not reencoded and not STATE.dry_run:
@@ -345,6 +347,7 @@ def retag(args: argparse.Namespace, meta: dict, has_audio: bool) -> int:
         cmd = ffmpeg_base() + ["-i", args.input, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?",
                                 "-map", "0:s?", "-map", "0:d?"] + label + enc + ["-c:s", "copy", "-c:d", "copy", output]
         proc2 = run(cmd, check=False)
+        fail_if_classified(proc2)
         if proc2.returncode != 0:
             info("re-encode with subtitles/data streams kept also failed; dropping them")
             dropped_streams = True

package/scripts/cut.py

@@ -58,6 +58,7 @@ import tempfile
 import zlib
 from typing import List, Tuple
 
+from _common.runner import fail_if_classified
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
@@ -893,6 +894,7 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     proc = run(cmd, check=False)
     if proc.returncode != 0:
         if not reencode:
+            fail_if_classified(proc)  # a full disk fails the re-encode too: its error, not a retry (#415)
             info("stream copy failed, falling back to re-encode")
             return cut_one(src, start, end, dst, True, crf, preset, tolerance, meta, reasons + ["copy_failed"], edit_list_ok)
         die(f"ffmpeg failed:\n{proc.stderr.strip()}", kind="ffmpeg")
@@ -1604,6 +1606,7 @@ def main() -> int:
                         cmd += ["-movflags", "+faststart"]
                     cmd += [joined]
                     proc = run(cmd, check=False)
+                    fail_if_classified(proc)  # #415: a full disk is not a reason to re-cut every segment
                     if proc.returncode != 0:
                         info("concat with stream copy failed; re-cutting every segment from the source into one re-encode")
                         compatible = False