ffmpeg-skill 3.1.6 → 3.1.8

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/caption.py

@@ -54,6 +54,7 @@ from _common import asr as _asr
 from _common.asr import ENGINE_CHOICES
 from _common.emit import warn
 from _common.probe import display_size, square_pixels, square_pixels_note
+from _common.runner import subtitle_codec_for, subtitle_container_holds
 from _common.fonts import font_choice, record_font_choice
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
@@ -145,7 +146,9 @@ def word_durations_from_audio(video: str, start: float, end: float, n_words: int
         return [total_cs]
     ffmpeg = require_tool("ffmpeg")
     cmd = [ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-ss", f"{start:.3f}", "-i", video,
-           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
+           "-map", f"0:a:{audio_stream}", "-t", f"{end - start:.3f}", "-vn",
+           # a sound that starts late is padded to its place on the file's clock (#414)
+           "-af", "aresample=async=1:first_pts=0", "-ac", "1", "-ar", "8000", "-f", "s16le", "-"]
     proc = run_analysis(cmd, check=False, text=False)  # under --timeout like every other measurement
     n = len(proc.stdout) // 2
     if proc.returncode != 0 or n < 800:
@@ -887,6 +890,23 @@ def track_title_for(code: Optional[str], given: Optional[str]) -> Optional[str]:
     return LANG_TITLES.get(code.split("-")[0].lower(), code)
 
 
+# a timing line in the grammar ffmpeg's SRT demuxer and parse_srt() read alike: hours, minutes,
+# seconds and three-digit milliseconds on both sides (ffmpeg allows position fields after it)
+_SHARED_SRT_TIMING = re.compile(r"^\s*\d{2,}:\d{2}:\d{2}[,.]\d{3}\s*-->\s*\d{2,}:\d{2}:\d{2}[,.]\d{3}(\s.*)?$")
+
+
+def srt_timings_shared_grammar(path: str) -> bool:
+    """True when every timing line of the SRT at `path` reads the same to ffmpeg's SRT demuxer as
+    to parse_srt(). ffmpeg refuses `00:01,000` (no hours) and reads `00:00:01,5` as 1.005 s, where
+    parse_srt() reads 1.5 s (#414); such a file is handed to ffmpeg as a rewritten copy."""
+    text = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n")
+    # a cue's timing line is its first line with "-->", as parse_srt() reads it (and ffmpeg too);
+    # a later line holding "-->" is dialogue, not a timing this check should judge
+    blocks = [[ln for ln in b.split("\n") if ln.strip()] for b in re.split(r"\n\s*\n", text)]
+    timings = [next((ln for ln in b if "-->" in ln), None) for b in blocks]
+    return all(_SHARED_SRT_TIMING.match(line) for line in timings if line is not None)
+
+
 def mux_subtitle_codec(output: str) -> str:
     ext = Path(output).suffix.lower()
     if ext in (".mp4", ".m4v", ".mov"):
@@ -1130,6 +1150,11 @@ def main() -> int:
             die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
         if args.audio_stream and not audio_streams:
             die("--audio-stream needs an input with audio streams")
+        if args.transcribe and not audio_streams:
+            # refused before any engine runs, as silence.py refuses it, not an unclassified
+            # "Stream map '0:a:0' matches no streams" from the WAV extraction (#414)
+            die(f"--transcribe needs speech to transcribe, and {args.input} has no audio stream",
+                kind="input", hint="pick the file that carries the sound, or write the cues with --text")
         if args.mode != "mux":
             # before any transcription or sidecar: a build without libass fails these at parse time
             # with a message that names no filter (#393), so ask the build first, dry run included
@@ -1380,9 +1405,15 @@ def main() -> int:
     side_notes: List[str] = list(getattr(args, "_asr_notes", None) or [])
     ass_counts: dict = {}  # --ass: ass_shifted / ass_unshifted (with --offset) and ass_malformed, into `caption`
     ass_sample_path = args.ass
+    normalised_only = False  # srt_path is a copy of the caller's SRT that only rewrites its timings
     if args.srt and not (args.text or args.transcribe) and os.path.exists(srt_path or ""):
         adjusted, changed = lay_out(parse_srt(srt_path))
-        if changed:
+        # ffmpeg's own SRT reader takes a narrower grammar than parse_srt(): a time without hours
+        # is refused and ",5" is read as 5 ms where this tool reads 500. A file outside the grammar
+        # both share goes to ffmpeg as the copy this tool writes, so it gets the cues counted
+        # here (#414)
+        normalised_only = not changed and not srt_timings_shared_grammar(srt_path)
+        if changed or normalised_only:
             new_srt = os.path.splitext(output)[0] + "_adjusted.srt"
             claim([(new_srt, "adjusted SRT")])
             if STATE.dry_run:
@@ -1392,8 +1423,10 @@ def main() -> int:
                 info(f"wrote {new_srt} ({len(adjusted)} cues, adjusted from {os.path.basename(srt_path)})")
             srt_path = new_srt
             planned_cues = adjusted
-            side_notes.append(f"the burned subtitles are {new_srt}, the adjusted copy of "
-                              f"{os.path.basename(args.srt)} this run writes (--offset/--max-lines/--min-duration)"
+            why = ("--offset/--max-lines/--min-duration" if changed else
+                   "its timings rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
+            side_notes.append(f"the {'muxed' if args.mode == 'mux' else 'burned'} subtitles are {new_srt}, the adjusted copy of "
+                              f"{os.path.basename(args.srt)} this run writes ({why})"
                               + ("; re-run this command without --dry-run to produce it" if STATE.dry_run else ""))
     if args.ass and args.offset and os.path.exists(args.ass):
         shifted = os.path.splitext(output)[0] + "_offset.ass"
@@ -1424,10 +1457,34 @@ def main() -> int:
                             and not (STATE.dry_run and (args.text or args.transcribe))):
             die(f"SRT file not found: {srt_path}")
         codec = mux_subtitle_codec(output)
+        out_ext = Path(output).suffix.lower().lstrip(".")
+        # The picture and the sound are copied: a WebM holds only VP8/VP9/AV1 and Opus/Vorbis, so
+        # anything else is refused here, not left to fail unclassified in the muxer (#414)
+        if out_ext == "webm":
+            vcodec = (meta.get("video") or {}).get("codec")
+            # the stream -map 0:a:N copies (--audio-stream), not always the first one
+            audio_streams = meta.get("audio_streams") or []
+            acodec = audio_streams[args.audio_stream].get("codec") if args.audio_stream < len(audio_streams) else None
+            bad = [c for c in (vcodec,) if c and c not in ("vp8", "vp9", "av1")] + \
+                  [c for c in (acodec,) if c and c not in ("opus", "vorbis")]
+            if bad:
+                die(f"--mode mux copies the picture and the sound, and a .webm holds only VP8/VP9/AV1 video and "
+                    f"Opus/Vorbis audio; {args.input} carries {' and '.join(bad)}", kind="input",
+                    hint="write .mkv (any codec) or .mp4 instead, or re-encode first with export.py")
         # Keep any subtitle track(s) the input already has (e.g. chaining --mode mux once per
-        # language to build a multi-language set) -- copied byte-identical, distinct from the
-        # newly-added SRTs' own codec below.
+        # language to build a multi-language set): copied where the output container holds them as
+        # they are, else converted to its own text format as export.py converts them (#380, #414);
+        # a track the container cannot hold at all (a bitmap one in MPEG-4 or WebM) is refused.
         existing_subs = meta.get("subtitle_streams") or 0
+        existing_details = list(meta.get("subtitle_stream_details") or [])
+        existing_codecs = [(existing_details[i] if i < len(existing_details) else {}).get("codec") or ""
+                           for i in range(existing_subs)]
+        unheld = sorted({c or "unknown" for c in existing_codecs if not subtitle_container_holds(c, out_ext)})
+        if unheld:
+            die(f"{args.input} already carries a subtitle track ({', '.join(unheld)}) that a .{out_ext} file cannot "
+                "hold, and --mode mux keeps every existing track", kind="input",
+                hint="write .mkv, which holds any subtitle codec")
+        existing_out = [subtitle_codec_for(c, out_ext) for c in existing_codecs]
         # the first entry's path is srt_path, which --offset/--max-lines may have repointed at an
         # adjusted copy; the rest are taken as written
         added = [(srt_path, srt_tracks[0][1] if srt_tracks else args.language)] + \
@@ -1435,6 +1492,18 @@ def main() -> int:
         for path, _lang in added[1:]:
             if not os.path.exists(path) and not STATE.dry_run:
                 die(f"SRT file not found: {path}")
+        for n in range(1, len(added)):
+            path, lang = added[n]
+            if os.path.exists(path) and not srt_timings_shared_grammar(path):
+                # the same rule as the first track (#414): ffmpeg is given what parse_srt() reads
+                copy = f"{os.path.splitext(output)[0]}_track{n}.srt"
+                claim([(copy, f"normalised SRT {n}")])
+                if not STATE.dry_run:
+                    write_srt(parse_srt(path), copy)
+                    info(f"wrote {copy} (timings of {os.path.basename(path)} rewritten as hh:mm:ss,mmm)")
+                side_notes.append(f"subtitle track {n} is {copy}, a copy of {os.path.basename(path)} with its timings "
+                                  "rewritten as hh:mm:ss,mmm, which ffmpeg reads as this tool does")
+                added[n] = (copy, lang)
         titles = list(args.track_title or [])
         mp4_family = Path(output).suffix.lower() in (".mp4", ".m4v", ".mov")
         dropped_titles: List[str] = []
@@ -1453,13 +1522,16 @@ def main() -> int:
         if mp4_family:
             cmd += ["-movflags", "+faststart"]
         for i in range(existing_subs):
-            cmd += [f"-c:s:{i}", "copy"]
+            cmd += [f"-c:s:{i}", existing_out[i]]
         tracks: List[Dict[str, Any]] = []
+        converted: List[str] = []
         for i in range(existing_subs):
-            kept = (meta.get("subtitle_stream_details") or [])
-            detail = kept[i] if i < len(kept) else {}
+            detail = existing_details[i] if i < len(existing_details) else {}
+            written = detail.get("codec") if existing_out[i] == "copy" else existing_out[i]
+            if existing_out[i] != "copy":
+                converted.append(f"{detail.get('codec')} -> {existing_out[i]}")
             tracks.append({"index": i, "file": None, "language": detail.get("language"),
-                           "title": detail.get("title"), "codec": detail.get("codec"),
+                           "title": detail.get("title"), "codec": written,
                            "default": False, "cues": None, "kept_from_input": True})
         for n, (path, lang) in enumerate(added):
             idx = existing_subs + n
@@ -1510,6 +1582,9 @@ def main() -> int:
             notes.append(f"{total} subtitle tracks in an MPEG-4 container: the tracks are all there, "
                          "but many players only ever show the first -- write to .mkv for a "
                          "deliverable a viewer can actually switch")
+        if converted:
+            notes.append(f"the input's own subtitle track(s) were converted to the .{out_ext} container's text format "
+                         f"({', '.join(converted)}): their text and timing are kept, styling a format cannot carry is not")
         if dropped_titles:
             notes.append("an MPEG-4 container has no per-track title this tool can write back "
                          f"({', '.join(dropped_titles)} would be dropped), so the tracks are "
@@ -1521,6 +1596,14 @@ def main() -> int:
                          "as given and may not survive")
         run(cmd)
         result = probe(output, role="output")
+        # the language and title each track carries in the written file: a converted track keeps
+        # only what the container can store (MPEG-4 drops a two-letter code and every title)
+        written = result.get("subtitle_stream_details") or []
+        if len(written) == len(tracks):
+            for track, detail in zip(tracks, written):
+                track["language"] = detail.get("language")
+                if track["kept_from_input"]:
+                    track["title"] = detail.get("title")
         info(f"wrote {output} ({fmt_secs(result.get('duration'))}, mux, {len(added)} "
              f"subtitle track(s) added, codec {codec})")
         emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}),
@@ -1587,7 +1670,8 @@ def main() -> int:
             cues if (args.text or args.transcribe) else (
                 planned_cues if planned_cues is not None else parse_srt(srt_path)))
         if args.karaoke and not getattr(args, "_word_timings", None):
-            args._word_timings = whisper_word_timings(srt_path)
+            # a copy that only rewrote the timings keeps the caller's word-timing JSON beside it
+            args._word_timings = whisper_word_timings(args.srt if normalised_only else srt_path)
         ass_path = args.write_ass or os.path.splitext(output)[0] + ".ass"
         claim([(ass_path, "ASS")])
         w, h = display_size(meta["video"])

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