ffmpeg-skill 3.1.6 → 3.1.8

package/scripts/_common/runner.py

@@ -14,7 +14,7 @@ import re
 import shutil
 import subprocess
 import sys
-from typing import Any, Dict, List, Optional, Sequence, Tuple
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
 
 
 INSTALL_HINTS = {
@@ -108,6 +108,13 @@ _FFMPEG_VERSION: "Optional[Tuple[int, int]]" = None
 _FFMPEG_VERSION_IS_RELEASE = False   # ffmpeg_version() read a release number, not the libavutil major
 
 
+def _probe_limit() -> float:
+    """The ceiling for a short read-only ffprobe/ffmpeg query run outside run(): PROBE_TIMEOUT, or
+    the caller's --timeout when that is lower (#415). Never unlimited: a version or stream-list read
+    that hangs is a stall, whatever --timeout 0 asks of the encodes."""
+    return min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+
+
 def ffmpeg_version() -> "Tuple[int, int]":
     """(major, minor) of the FFmpeg build on PATH, parsed once from `ffprobe -version`; (0, 0)
     when it cannot be read. ffprobe rather than ffmpeg because --dry-run promises never to run
@@ -120,7 +127,7 @@ def ffmpeg_version() -> "Tuple[int, int]":
         _FFMPEG_VERSION = (0, 0)
         try:
             out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                                 timeout=PROBE_TIMEOUT).stdout
+                                 timeout=_probe_limit()).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)", out)
             if m:
                 _FFMPEG_VERSION = (int(m.group(1)), int(m.group(2)))
@@ -158,7 +165,7 @@ def ffmpeg_release() -> "Optional[Tuple[int, int, int]]":
         _FFMPEG_RELEASE_READ = True
         try:
             out = subprocess.run([found_exe("ffprobe"), "-version"], stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                                 timeout=PROBE_TIMEOUT).stdout
+                                 timeout=_probe_limit()).stdout
             m = re.search(r"ffprobe version\s+n?(\d+)\.(\d+)(?:\.(\d+))?", out)
             if m:
                 _FFMPEG_RELEASE = (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0))
@@ -325,7 +332,7 @@ class Context:
     __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
                  "hw", "hw_source", "hw_notes", "hw_swaps", "hw_fallback", "hw_env_ignored", "hw_stages", "hw_auto",
                  "notes", "warnings", "fallbacks", "skipped", "audit_log", "stage_verification", "first_input", "audio_inputs", "video_inputs",
-                 "source_timecode", "smpte_hint")
+                 "source_timecode", "smpte_hint", "delivered")
 
     def __init__(self) -> None:
         self.reset()
@@ -337,6 +344,7 @@ class Context:
         self.video_inputs = set()  # real paths of the inputs probed that have a picture: with two or more, which one the output shows is the tool's choice (sync --trim-second, a join)
         self.source_timecode = None  # (start timecode, duration) of the first input probed that carries one (time_arg's SMPTE hint)
         self.smpte_hint = None    # what die() says when an hh:mm:ss:ff flag read past the end looks like a source timecode (#411)
+        self.delivered: List[str] = []  # deliverables written before a later step (export --normalize, render's chapters/check): a stop then keeps them (#415)
         self.audio_inputs = set()  # real paths of the inputs probed that have sound: with two or more, whose tracks an output should keep is the tool's choice (grid --audio-from, a mix)
         self.json_brief = False   # --json-brief: the same document trimmed to the fields a caller acts on
         self.progress = False     # run() streams percent / ETA to stderr for ffmpeg
@@ -533,12 +541,52 @@ def stop_children() -> None:
     _CHILDREN.clear()
 
 
+def mark_delivered(path: str) -> None:
+    """Record that this run has written its deliverable and still has a step to run on it (export's
+    --normalize, render's chapters and check stages): a timeout or an interrupt from then on says the
+    file is there and kept, instead of "nothing was written" (#415)."""
+    if path and path not in STATE.delivered:
+        STATE.delivered.append(path)
+
+
+def child_exit_code(doc: Any, returncode: Optional[int]) -> int:
+    """The exit code a tool passes on from a child tool that failed: the code its document states,
+    else its process's own, else 1. A child killed by a signal has a negative returncode (-9), which
+    as an exit code wraps (247); it is passed on as the shell reports it, 128 + the signal (137)."""
+    code = (doc.get("exit_code") if isinstance(doc, dict) else None) or returncode or 1
+    try:
+        code = int(code)
+    except (TypeError, ValueError):
+        return 1
+    return 128 - code if code < 0 else code
+
+
+def kept_deliverables() -> List[str]:
+    """The deliverables mark_delivered() named that are on disk."""
+    return [p for p in STATE.delivered if os.path.isfile(p)]
+
+
+def kept_clause() -> str:
+    """How a stopped run's message ends: "nothing was written", or which deliverable it had already
+    written and keeps (not the finished result: the step that was stopped did not run on it)."""
+    kept = kept_deliverables()
+    if not kept:
+        return "nothing was written"
+    return (f"{', '.join(kept)} had already been written by this run and {'is' if len(kept) == 1 else 'are'} kept, "
+            "without the step that was stopped (pass --overwrite to make it again)")
+
+
+def _kept_fields() -> Dict[str, Any]:
+    kept = kept_deliverables()
+    return {"output": kept[-1]} if kept else {}
+
+
 def _on_signal(signum: int, frame: Any) -> None:
     import signal as _signal
     name = {getattr(_signal, "SIGINT", None): "SIGINT", getattr(_signal, "SIGTERM", None): "SIGTERM"}.get(signum, str(signum))
     stop_children()
-    die(f"interrupted by {name}: the running command was stopped and its partial output removed; nothing was written",
-        code=128 + signum, kind="interrupted")
+    die(f"interrupted by {name}: the running command was stopped and its partial output removed; {kept_clause()}",
+        code=128 + signum, kind="interrupted", **_kept_fields())
 
 
 def install_signal_handlers() -> None:
@@ -895,10 +943,13 @@ class _OutputLock:
     the hour ran from the lock's creation, so a legitimate run longer than an hour lost its lock
     to a second writer. A takeover is recorded (`diagnostics.fallbacks`, stderr, and the audit
     log); so is running without a lock where none can be created (`diagnostics.warnings`)."""
-    def __init__(self, output: str) -> None:
+    def __init__(self, output: str, on_locked: "Optional[Callable[[str, str, Dict[str, Any]], None]]" = None) -> None:
+        # on_locked(message, hint, details): a caller that must not exit (batch.py's item worker)
+        # raises its own error for a held lock instead of the refusal below
         self.path: Optional[str] = None
         self.fd: Optional[int] = None
         self.output = output
+        self.on_locked = on_locked
         if output == "-" or output.startswith("pipe:") or output.startswith("-"):
             return
         d, base = os.path.split(os.path.abspath(output))
@@ -931,12 +982,14 @@ class _OutputLock:
                         taken = holder
                         continue
                 name = os.path.basename(self.path)[1:-len(".ffskill-lock")]
-                refuse("input", "output_locked",
-                       f"another run is writing {name!r} right now (lock {self.path}"
-                       + (f", pid {holder['pid']}" if holder.get("pid") else "") + "); wait for it or choose a different --output/-o path",
-                       hint=("wait for that run, or choose another -o path; if pid "
-                             f"{holder.get('pid')} is not an ffmpeg-skill run, delete {self.path}"),
-                       lock=self.path, output=os.path.abspath(self.output), **{k: v for k, v in holder.items() if k != "stale"})
+                msg = (f"another run is writing {name!r} right now (lock {self.path}"
+                       + (f", pid {holder['pid']}" if holder.get("pid") else "") + "); wait for it or choose a different --output/-o path")
+                hint = ("wait for that run, or choose another -o path; if pid "
+                        f"{holder.get('pid')} is not an ffmpeg-skill run, delete {self.path}")
+                details = dict(lock=self.path, output=os.path.abspath(self.output), **{k: v for k, v in holder.items() if k != "stale"})
+                if self.on_locked:
+                    self.on_locked(msg, hint, details)
+                refuse("input", "output_locked", msg, hint=hint, **details)
             except OSError as exc:
                 # an unlockable location (a read-only directory surfaces elsewhere): the run goes
                 # on without a lock, and says so -- two runs could now both write this output
@@ -1110,11 +1163,28 @@ def _remember_output(cmd: Sequence[str]) -> None:
         pass
 
 
+def remember_written(*paths: Optional[str]) -> None:
+    """Count files a child tool of this run wrote (render.py's stages, batch.py's steps) as this
+    run's own, as run() counts its ffmpeg outputs: a later stage that replaces one is not refused
+    as replacing someone else's file (#415)."""
+    for path in paths:
+        if path and os.path.isfile(path):
+            try:
+                STATE.written.add(os.path.realpath(path))
+            except OSError:
+                pass
+
+
 def _timed_out(cmd: Sequence[str], seconds: float) -> "None":
     _cleanup_partial_output(cmd)
-    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:.0f} s time limit and was killed; nothing was written. "
-        f"Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall",
-        code=124, kind="timeout")
+    if _is_ffmpeg(cmd) or seconds < PROBE_TIMEOUT:
+        advice = "Raise --timeout (or FFMPEG_SKILL_TIMEOUT) if the job is genuinely that long, or check the input for a stall"
+    else:
+        # a probe's own ceiling, which a higher --timeout does not raise: a read this long is a stall (#415)
+        advice = (f"A probe is limited to {PROBE_TIMEOUT:g} s whatever --timeout says, so this is a stall, not a long "
+                  "job: check that the input is readable (a network share, a file still being written)")
+    die(f"{os.path.basename(cmd[0])} exceeded the {seconds:g} s time limit and was killed; {kept_clause()}. {advice}",
+        code=124, kind="timeout", **_kept_fields())
 
 
 def _stage_existing_output(cmd: Sequence[str]) -> Tuple[List[str], Optional[str], Optional[str]]:
@@ -1446,7 +1516,7 @@ def run_tool(argv: Sequence[str], *, per_call: Optional[float] = None) -> subpro
         child.communicate()
         _unwatch(child)
         name = os.path.basename(str(argv[0]))
-        msg = f"{name} did not finish within {limit:.0f} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
+        msg = f"{name} did not finish within {limit:g} s (4x the per-ffmpeg --timeout plus 60 s) and was killed"
         doc = {"status": "failed", "exit_code": 124,
                "error": {"kind": "timeout", "message": msg, "code": ERROR_CODE["timeout"], "retryable": ERROR_RETRYABLE},
                "commands": []}
@@ -1479,13 +1549,56 @@ def _has_non_av_streams(cmd: Sequence[str]) -> bool:
     try:
         out = subprocess.run([found_exe("ffprobe"), "-v", "error", "-show_entries", "stream=codec_type", "-of", "csv=p=0", src],
                              stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace",
-                             timeout=PROBE_TIMEOUT).stdout
+                             timeout=_probe_limit()).stdout
     except (OSError, subprocess.TimeoutExpired):
         return True
     kinds = {ln.strip() for ln in out.splitlines() if ln.strip()}
     return not kinds or bool(kinds & {"subtitle", "data", "attachment"})
 
 
+def fail_if_classified(proc: subprocess.CompletedProcess) -> None:
+    """Stop with a failed attempt's own error when ffmpeg named a cause a second encode would hit
+    the same way (a full disk, a missing encoder or filter, an unreadable input): the rule
+    run_keeping_subtitles() follows since #389, for every copy-then-re-encode or keep-then-drop
+    fallback (#415). Returns when the failure is unclassified, so the caller's retry runs."""
+    if proc.returncode != 0 and classify_ffmpeg_failure(proc.stderr or ""):
+        _fail(proc.args, proc.returncode, proc.stderr or "")
+
+
+# eia_608 (a QuickTime c608 caption track) decodes to text, so it converts like one (ffmpeg 6.1)
+TEXT_SUBTITLES = frozenset({"mov_text", "subrip", "srt", "ass", "ssa", "webvtt", "text", "eia_608"})
+MP4_FAMILY = frozenset({"mp4", "m4v", "mov"})
+
+
+def subtitle_codec_for(codec: str, out_ext: str) -> str:
+    """The -c:s for one source subtitle stream going into a container with extension `out_ext`
+    (no dot): copy when the container holds it as it is, else the container's own text format --
+    mov_text in MPEG-4, srt in Matroska for a mov_text track, webvtt in WebM. A bitmap track is
+    returned as copy; subtitle_container_holds() says whether that copy can work."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext == "mov" and codec == "eia_608":
+        return "copy"  # QuickTime holds a c608 track as it is; .mp4 has no tag for it
+    if out_ext in MP4_FAMILY and codec in TEXT_SUBTITLES and codec != "mov_text":
+        return "mov_text"
+    if out_ext == "mkv" and codec == "mov_text":
+        return "srt"
+    if out_ext == "webm" and codec in TEXT_SUBTITLES and codec != "webvtt":
+        return "webvtt"
+    return "copy"
+
+
+def subtitle_container_holds(codec: str, out_ext: str) -> bool:
+    """Whether a subtitle stream of `codec` can be written to an `out_ext` container at all,
+    converted by subtitle_codec_for() where it must be: Matroska takes any, MPEG-4 a text track or
+    DVD bitmaps, WebM only text (as WebVTT)."""
+    out_ext = out_ext.lstrip(".").lower()
+    if out_ext in MP4_FAMILY:
+        return codec in TEXT_SUBTITLES or codec == "dvd_subtitle"
+    if out_ext == "webm":
+        return codec in TEXT_SUBTITLES
+    return True
+
+
 def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
     """Run an ffmpeg command that already maps its video/audio, trying first to also
     stream-copy any subtitle/data streams the source has (`-map 0:s?`/`0:d?` are no-ops when
@@ -1516,10 +1629,11 @@ def run_keeping_subtitles(cmd: List[str], output: str) -> bool:
 
 
 def _limit_for(cmd: Sequence[str]) -> Optional[float]:
-    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a fixed
-    short one, ffmpeg the configured one; None means unlimited."""
+    """The wall-clock ceiling for this command: ffprobe (and other read-only probes) get a short
+    one, PROBE_TIMEOUT or --timeout when that is lower (as _read_ff_list() does: a caller's
+    --timeout 2 bounds every child, #415), ffmpeg the configured one; None means unlimited."""
     if not _is_ffmpeg(cmd):
-        return PROBE_TIMEOUT if STATE.timeout else None
+        return min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else None
     return STATE.timeout or None
 
 
@@ -1893,7 +2007,7 @@ def _read_ff_list(flag: str, pattern: str) -> set:
     tool = "ffprobe" if STATE.dry_run else "ffmpeg"
     # --timeout bounds this read too: on Apple Silicon every CPU re-encode asks for the list
     # (#314), so a deadlocked ffmpeg must not outlive the limit the caller set before the encode
-    limit = min(PROBE_TIMEOUT, STATE.timeout) if STATE.timeout else PROBE_TIMEOUT
+    limit = _probe_limit()
     _LIST_ERRORS.pop(flag, None)
     names: set = set()
     why = None

package/scripts/_common/timeline.py

@@ -23,6 +23,7 @@ under `not_exported`, never silently dropped.
 import json
 import math
 import os
+import re
 from fractions import Fraction
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
@@ -110,6 +111,48 @@ def _picture(meta: Dict[str, Any]) -> Optional[Tuple[int, int]]:
     return (w, h)
 
 
+_TC = re.compile(r"^(\d{2}):(\d{2}):(\d{2})[:;.](\d{2,3})$")
+
+
+def _drop_frame(drop: Optional[bool], rate: Fraction) -> bool:
+    """Drop-frame counting applies to the NTSC rates only (29.97 and 59.94)."""
+    return bool(drop) and rate.denominator == 1001 and round(float(rate)) in (30, 60)
+
+
+def start_tc_frames(tc: Dict[str, Any], rate: Fraction) -> int:
+    """A source's start timecode (probe()'s `timecode`: {value, drop_frame}) as a frame count at
+    its own `rate`, drop-frame counted where it is one; 0 when the source has none (#414). A
+    label that does not exist at that rate (frame 29 at 25 fps, or a frame drop-frame counting
+    skips) is read as none, as probe() skips a malformed tag, rather than as a shifted start."""
+    m = _TC.match(str((tc or {}).get("value") or "").strip())
+    if not m:
+        return 0
+    h, mi, se, fr = (int(g) for g in m.groups())
+    nominal = int(round(float(rate)))
+    if mi > 59 or se > 59 or fr >= nominal:
+        return 0
+    frames = ((h * 60 + mi) * 60 + se) * nominal + fr
+    if _drop_frame(tc.get("drop_frame"), rate):
+        if se == 0 and mi % 10 and fr < nominal // 15:
+            return 0
+        minutes = h * 60 + mi
+        frames -= (nominal // 15) * (minutes - minutes // 10)
+    return frames
+
+
+def _tc_label(frames: int, rate: Fraction, drop: bool) -> str:
+    """`frames` as hh:mm:ss:ff at the nominal integer rate; drop-frame (`;`) for an NTSC source
+    whose own timecode is drop-frame, so the label is the one the media itself shows."""
+    nominal = int(round(float(rate)))
+    if not _drop_frame(drop, rate):
+        return _tc(frames, nominal)
+    d = nominal // 15
+    per_10, per_min = nominal * 600 - d * 9, nominal * 60 - d
+    tens, rem = divmod(frames, per_10)
+    frames += d * 9 * tens + (d * ((rem - d) // per_min) if rem > d else 0)
+    return _tc(frames, nominal)[:-3] + ";" + _tc(frames, nominal)[-2:]
+
+
 def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[str, Any]:
     """The editor-neutral timeline: every time in frames at `rate`.
 
@@ -172,6 +215,14 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if start < 0:
             raise TimelineError(f"clips[{i}].in must not be negative, got {c['in']!r}")
         end = _seconds(c["out"], f"clips[{i}].out", clip_fps) if c.get("out") is not None else dur
+        # as cut.py reads them (#414): an in at or past the media's end is refused, an out past it
+        # is the media's end -- the render clamps it there, so the timeline does too, and says so
+        if dur > 0 and start >= dur:
+            raise TimelineError(f"clips[{i}].in ({start:g}s) is at or past the end of {os.path.basename(src)} ({dur:.3f}s)")
+        if dur > 0 and end > dur + 1e-6:
+            notes.append(f"clips[{i}].out ({end:g}s) is past the end of {os.path.basename(src)} ({dur:.3f}s): "
+                         "the clip ends at the media's end, as the render cuts it")
+            end = dur
         if end <= start:
             raise TimelineError(f"clip {i}: out ({end:g}) is not after in ({start:g})")
         speed = _number(c.get("speed") or 1.0, f"clips[{i}].speed")
@@ -182,8 +233,17 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
         if reframe:
             reframed.append(os.path.basename(src))
         src_in, src_out = fr(start), fr(end)
+        # the source's own clock (#414): its frame rate, and its start timecode as a frame count at
+        # that rate. EDL source timecodes are counted at it (a 25 fps clip in a 29.97 sequence has
+        # no frame :29); FCPXML and OTIO start the media at it, so a conform finds the frames.
+        clip_rate = exact_rate(float(clip_fps)) if clip_fps else rate
+        tc = meta.get("timecode") or {}
+        tc_start = start_tc_frames(tc, clip_rate)
         clips.append({"index": i, "src": os.path.abspath(src), "name": os.path.basename(src),
                       "src_in": src_in, "src_out": src_out, "speed": speed,
+                      "in_seconds": Fraction(start).limit_denominator(1000000), "rate": clip_rate,
+                      "tc_start": tc_start, "tc_seconds": Fraction(tc_start) / clip_rate,
+                      "drop_frame": _drop_frame(tc.get("drop_frame"), clip_rate),
                       "length": int(round((src_out - src_in) / speed)),
                       "media_frames": fr(dur), "has_video": bool(meta.get("video")),
                       "has_audio": bool(meta.get("audio")),
@@ -219,12 +279,24 @@ def build(proj: Dict[str, Any], probes: Dict[str, Dict[str, Any]], rel) -> Dict[
     markers: List[Dict[str, Any]] = []
     chapters = proj.get("chapters")
     if isinstance(chapters, list):
+        total_seconds = Fraction(total) / rate
+        previous: Optional[float] = None
         for j, ch in enumerate(chapters):
             # read as render.py's chapters stage reads it (metadata.py): a chapter list carries
-            # no fps, so hh:mm:ss:ff needs its @fps there and here alike
-            at = fr(_seconds(ch.get("at", 0), f"chapters[{j}].at", None))
-            if 0 <= at < total:
-                markers.append({"at": at, "title": str(ch.get("title") or "")})
+            # no fps, so hh:mm:ss:ff needs its @fps there and here alike. What metadata.py refuses
+            # is refused here too, never dropped (#414): a chapter at or past the end, or one that
+            # does not come after the one before it.
+            at_s = _seconds(ch.get("at", 0), f"chapters[{j}].at", None)
+            if at_s < 0:
+                raise TimelineError(f"chapters[{j}].at must not be negative, got {ch.get('at')!r}")
+            if previous is not None and at_s <= previous:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s does not come after the previous one "
+                                    f"at {previous:g}s (metadata.py refuses it too)")
+            if at_s >= total_seconds:
+                raise TimelineError(f"chapters[{j}]: the chapter at {at_s:g}s starts at or after the end of the "
+                                    f"timeline ({float(total_seconds):.3f}s); metadata.py refuses it too")
+            previous = at_s
+            markers.append({"at": min(fr(at_s), total - 1), "title": str(ch.get("title") or "")})
     elif chapters:
         notes.append("chapters given as a file are not exported as markers; write them inline as [{at, title}]")
 
@@ -283,27 +355,38 @@ def to_edl(tl: Dict[str, Any]) -> str:
     ends = starts[1:] + [tl["total"]]
     lines = [f"TITLE: {tl['name']}", "FCM: NON-DROP FRAME", ""]
     n = 0
-    prev_src_end = 0
+    prev_src_end = ""
+    rate = tl["rate"]
+
+    def src_tc(c: Dict[str, Any], seq_frames: int) -> str:
+        """The source timecode `seq_frames` (sequence frames of source media) after the clip's in
+        point: counted at the clip's own rate from its own start timecode (#414)."""
+        own = c.get("rate") or rate
+        seconds = c.get("in_seconds", Fraction(c["src_in"]) / rate) + Fraction(seq_frames) / rate
+        return _tc_label(int(round(seconds * own)) + c.get("tc_start", 0), own, c.get("drop_frame", False))
+
     for i, c in enumerate(clips):
         n += 1
         chan = "B" if c["has_audio"] and c["has_video"] else ("V" if c["has_video"] else "A")
         rec_in, rec_out = hour + starts[i], hour + ends[i]
-        s_in = c["src_in"]
-        s_out = s_in + int(round((ends[i] - starts[i]) * c["speed"]))
+        s_in = src_tc(c, 0)
+        s_out = src_tc(c, int(round((ends[i] - starts[i]) * c["speed"])))
         if i > 0 and d:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(prev_src_end, fps_int)} {_tc(prev_src_end, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {prev_src_end} {prev_src_end} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_in, fps_int)}")
-            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} D    {d:03d} {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {clips[i - 1]['name']}")
             lines.append(f"* TO CLIP NAME: {c['name']}")
         else:
-            lines.append(f"{n:03d}  AX       {chan:<5} C        {_tc(s_in, fps_int)} {_tc(s_out, fps_int)} "
+            lines.append(f"{n:03d}  AX       {chan:<5} C        {s_in} {s_out} "
                          f"{_tc(rec_in, fps_int)} {_tc(rec_out, fps_int)}")
             lines.append(f"* FROM CLIP NAME: {c['name']}")
         lines.append(f"* SOURCE FILE: {c['src']}")
         if abs(c["speed"] - 1.0) > 1e-6:
-            lines.append(f"M2   AX       {fps_int * c['speed']:05.1f}                {_tc(s_in, fps_int)}")
+            # the speed in source frames per second, at the rate the source labels are counted in
+            own_fps = int(round(float(c.get("rate") or rate)))
+            lines.append(f"M2   AX       {own_fps * c['speed']:05.1f}                {s_in}")
         lines.append("")
         prev_src_end = s_out
     if tl["music"]:
@@ -326,6 +409,11 @@ def _t(frames: int, rate: Fraction) -> str:
     return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
 
 
+def _ts(value: Fraction) -> str:
+    """A rational FCPXML time from seconds."""
+    return f"{value.numerator}s" if value.denominator == 1 else f"{value.numerator}/{value.denominator}s"
+
+
 def _url(path: str) -> str:
     # pathlib builds the percent-encoded file:// URL itself (and the drive-letter form on
     # Windows): no network-library import in scripts/, not even for quoting (see the no-fetch test)
@@ -361,12 +449,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
             return seq_fmt
         return fmt(c["picture"][0], c["picture"][1], _t(1, exact_rate(float(c["fps"]))) if c["fps"] else fd)
 
-    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "") -> str:
+    def asset(path: str, name: str, frames: int, has_video: bool, has_audio: bool, format_id: str = "",
+              start: Fraction = Fraction(0)) -> str:
         if path in ids:
             return ids[path]
         rid = f"r{len(ids) + 1}"
         ids[path] = rid
-        res.append(f'    <asset id="{rid}" name="{q(name)}" start="0s" duration="{_t(frames, rate)}" '
+        # the media starts at its own start timecode (#414): a clip's start is counted from there
+        res.append(f'    <asset id="{rid}" name="{q(name)}" start="{_ts(start)}" duration="{_t(frames, rate)}" '
                    f'hasVideo="{int(has_video)}" hasAudio="{int(has_audio)}"'
                    + (f' format="{format_id}"' if has_video else "") + ' audioSources="1" audioChannels="2">\n'
                    f'      <media-rep kind="original-media" src="{q(_url(path))}"/>\n    </asset>')
@@ -377,7 +467,8 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
     markers = list(tl["markers"])
     for i, c in enumerate(tl["clips"]):
         cid = clip_fmt(c)
-        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid)
+        base = c.get("tc_seconds", Fraction(0))
+        rid = asset(c["src"], c["name"], c["media_frames"], c["has_video"], c["has_audio"], cid, base)
         if i > 0 and d:
             spine.append(f'        <transition name="Cross Dissolve" offset="{_t(c["record_in"] - c["trim_head"], rate)}" '
                          f'duration="{_t(d, rate)}"/>')
@@ -386,14 +477,15 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if abs(c["speed"] - 1.0) > 1e-6:
             # timeMap maps clip-local time to source time; two linear points give a constant speed
             inner.append("          <timeMap>")
-            inner.append(f'            <timept time="0s" value="{_t(src_start, rate)}" interp="linear"/>')
+            inner.append(f'            <timept time="0s" value="{_ts(base + Fraction(src_start) / rate)}" interp="linear"/>')
             inner.append(f'            <timept time="{_t(c["visible"], rate)}" '
-                         f'value="{_t(src_start + int(round(c["visible"] * c["speed"])), rate)}" interp="linear"/>')
+                         f'value="{_ts(base + Fraction(src_start + int(round(c["visible"] * c["speed"]))) / rate)}" interp="linear"/>')
             inner.append("          </timeMap>")
             start_attr = "0s"
         else:
-            start_attr = _t(src_start, rate)
-        local0 = src_start if abs(c["speed"] - 1.0) <= 1e-6 else 0
+            start_attr = _ts(base + Fraction(src_start) / rate)
+        # the clip's local time: the source's (from its start timecode), or 0 under a timeMap
+        local0 = base + Fraction(src_start) / rate if abs(c["speed"] - 1.0) <= 1e-6 else Fraction(0)
         # the FCPXML 1.10 DTD's order inside an asset-clip: timeMap, then the adjust-* elements
         # (adjust-conform), then anchored items (the music bed), then markers. Anything out of
         # that order does not validate, and Final Cut validates what it imports against that DTD.
@@ -404,13 +496,14 @@ def to_fcpxml(tl: Dict[str, Any]) -> str:
         if i == 0 and tl["music"]:
             m = tl["music"]
             mid = asset(m["src"], m["name"], m["media_frames"], False, True)
-            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_t(local0, rate)}" name="{q(m["name"])}" '
+            inner.append(f'          <asset-clip ref="{mid}" lane="-1" offset="{_ts(local0)}" name="{q(m["name"])}" '
                          f'start="0s" duration="{_t(m["length"], rate)}" audioRole="music"/>')
         for mk in [m for m in markers if c["record_in"] <= m["at"] < c["record_in"] + c["visible"]]:
-            inner.append(f'          <chapter-marker start="{_t(local0 + mk["at"] - c["record_in"], rate)}" '
+            inner.append(f'          <chapter-marker start="{_ts(local0 + Fraction(mk["at"] - c["record_in"]) / rate)}" '
                          f'duration="{fd}" value="{q(mk["title"])}"/>')
         head = (f'        <asset-clip ref="{rid}" offset="{_t(c["record_in"], rate)}" name="{q(c["name"])}" '
-                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" tcFormat="NDF"')
+                f'start="{start_attr}" duration="{_t(c["visible"], rate)}" format="{cid}" '
+                f'tcFormat="{"DF" if c.get("drop_frame") else "NDF"}"')
         spine.append(head + (">\n" + "\n".join(inner) + "\n        </asset-clip>" if inner else "/>"))
     out = ['<?xml version="1.0" encoding="UTF-8"?>', "<!DOCTYPE fcpxml>", '<fcpxml version="1.10">',
            "  <resources>", *res, "  </resources>", "  <library>", f'    <event name="{q(tl["name"])}">',
@@ -444,15 +537,17 @@ def to_otio(tl: Dict[str, Any]) -> str:
                           # OTIO: in_offset is the part before the cut, out_offset the part after
                           "in_offset": _rt(c["trim_head"], rate), "out_offset": _rt(tl["clips"][i - 1]["trim_tail"], rate)})
         src_start = c["src_in"] + int(round(c["trim_head"] * c["speed"]))
+        # the media's range starts at its start timecode (#414), in timeline frames
+        base = c.get("tc_seconds", Fraction(0)) * rate
         clip = {"OTIO_SCHEMA": "Clip.2", "name": c["name"], "metadata": {}, "enabled": True,
                 # OTIO's own convention: source_range starts at the media's in point and lasts the
                 # clip's length on the timeline; a LinearTimeWarp says how fast the media runs
                 # through it (core OTIO does not rescale durations by effects).
-                "source_range": _range(src_start, c["visible"], rate),
+                "source_range": _range(base + src_start, c["visible"], rate),
                 "effects": [], "markers": [],
                 "media_references": {"DEFAULT_MEDIA": {
                     "OTIO_SCHEMA": "ExternalReference.1", "name": c["name"], "metadata": {},
-                    "target_url": _url(c["src"]), "available_range": _range(0, c["media_frames"], rate),
+                    "target_url": _url(c["src"]), "available_range": _range(base, c["media_frames"], rate),
                     "available_image_bounds": None}},
                 "active_media_reference_key": "DEFAULT_MEDIA"}
         if abs(c["speed"] - 1.0) > 1e-6:

package/scripts/_contract.py

@@ -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)"],
@@ -440,6 +440,9 @@ ERROR_REASONS = {
     "encoder_missing": "--codec av1/prores: the build's encoder list was read and has no encoder for the codec (kind missing_tool; details: {codec, encoders}); or ffmpeg itself reported \"Unknown encoder\" for the encoder the command named (kind ffmpeg; details: {name}; the hint points at doctor)",
     "asr_engine_missing": "kind missing_tool: --transcribe (caption.py, silence.py --filler) found no local speech-to-text engine; the message lists the install lines; details: {}",
     "encoder_list_unreadable": "--codec av1/prores: the build's encoder list could not be read, so whether it has the encoder is unknown (kind ffmpeg); details: {codec, encoders, error}",
+    "no_speech": "kind input: --transcribe (caption.py, silence.py --filler) ran a local speech engine that heard no speech in the input; details: {engine}; also top-level reason and engine",
+    "engine_failed": "kind input: --transcribe: an installed speech engine ran and failed (a named --engine, or every engine --engine auto found); details: {engine, detail | engines: [{engine, reason, detail}]}; also top-level reason, engine and detail/engines",
+    "english_only": "kind input: --transcribe under --engine auto found only Parakeet engines, which it runs for English speech only, and the language is not English; details: {engine, engines}; also top-level reason, engine and engines",
 }
 
 # The codes of the collector's records (docs/design-decisions.md, "Nothing happens silently"):
@@ -547,13 +550,23 @@ FONT_USED_SCHEMA = {
 }
 
 
+# the tools whose --json carries `dropped_non_av_streams` (a test reads the sources)
+NON_AV_STREAM_TOOLS = frozenset({"audio", "broll", "color", "cut", "deinterlace", "denoise", "export", "fit", "freeze",
+                                 "graphics", "join", "loudness", "overlay", "pad", "proxy", "redact", "speedramp",
+                                 "sphere", "straighten"})
+
+
 def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str, Any]:
     """What the tool prints on stdout with --json (keys observed in the implementation). `hw`: the
     tool takes --hw, so its `notes` can also carry a VideoToolbox encode's quality line."""
     if name == "probe":
         return {"type": "object", "description": "one probe document, or an array of them for several inputs",
                 "properties": {"file": {"type": "string"}, "format": {"type": "string"}, "duration": {"type": "number"}, "size_bytes": {"type": "integer"},
-                               "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]}}, "additionalProperties": True}
+                               "video": {"type": ["object", "null"]}, "audio": {"type": ["object", "null"]},
+                               "timecode": {"type": "object", "description": "3.0.0: the source's start timecode {value, drop_frame, source}: the first HH:MM:SS[:;.]FF timecode tag from the video stream, then a tmcd data stream, then the container; all three null when none carries one"},
+                               "chapters": {"type": "array", "description": "the container's chapter markers [{index, start, end, title}]"},
+                               "subtitle_stream_details": {"type": "array", "description": "every subtitle stream in file order [{index (the n of -map 0:s:n), codec, language, title}]"}},
+                "additionalProperties": True}
     base = {"status": {"enum": ["completed"]}, "output": {"type": ["string", "null"], "description": "path written, or null"},
             "dry_run": {"type": "boolean"}, "commands": {"type": "array", "items": {"type": "string"}, "description": "every ffmpeg command line planned or run"},
             "probe": {"type": "object", "description": "probe of the output when a file was written"},
@@ -594,6 +607,13 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "speech": {"type": "array", "description": "--speech (1.18): [{time, speech_music_ratio}]"}}
     elif name == "silence":
         extra = {"silences": {"type": "array"}, "keep": {"type": "array"}, "input_duration": {"type": "number"}, "kept_duration": {"type": "number"}, "removed_seconds": {"type": "number"},
+                 "removed_seconds_total": {"type": "number", "description": "--filler: seconds removed in all, silence plus filler words (removed_seconds stays the silence alone)"},
+                 "cut_points": {"type": ["array", "null"], "description": "2.22: per cut {source_time, output_time, edge (out|in), rms_dbfs (the loudest channel 50 ms either side on the source; null for digital silence), filler (true on a removed filler word's edge)}; null when the source could not be decoded for it (cut_levels_unmeasured warning)"},
+                 "cut_warnings": {"type": ["array", "null"], "description": "the cut_points (not filler cuts) within 10 dB of --threshold: where to listen (a cut_near_sound warning); verified is unchanged"},
+                 "timemap": {"type": "string", "description": "--timemap FILE: the source-to-output time map written (JSON or CSV)"},
+                 "silence_kinds": {"type": "array", "description": "2.20: per detected silence, digital (at or below -90 dBFS) or below_threshold"},
+                 "silence_breakdown": {"type": "object", "description": "2.20: {digital, below_threshold}: the count and seconds of each, with the level that defines it"},
+                 "hint": {"type": "string", "description": "when nothing sat below --threshold: the track's measured level and the --threshold that would find its pauses"},
                  "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"},
                  "filler": {"type": "object", "description": "--filler: {lang, source (whisper-json:FILE | whisper:ENGINE | parakeet:ENGINE), engine, transcription (with --transcribe: {engine, model, language, routing}), removed, removed_count, matched_untimed (listed words in the transcript with no usable timing, not removed), matched_too_long (listed words longer than a filler, kept), ...}"},
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "--filler --transcribe under --engine auto: present when the English-only Parakeet model ran on English assumed (no --filler-lang, no language detected, no Whisper engine installed or none that succeeded); the transcript is wrong if the speech is not English"}}
@@ -651,6 +671,15 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "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"},
+                 "mode": {"enum": ["copy", "hybrid", "accurate"], "description": "copy: nothing re-encoded at any stage, the join included; accurate: --accurate was asked for or forced; hybrid: asked for lossless but a segment or the join re-encoded anyway (reencode_reason says why)"},
+                 "requested_start": {"type": ["number", "null"], "description": "one segment: the requested start, clamped to the media's duration (null for --segments)"},
+                 "requested_end": {"type": ["number", "null"], "description": "one segment: the requested end, clamped to the media's duration (null for --segments)"},
+                 "requested_segments": {"type": ["array", "null"], "description": "--segments: [[start, end], ...] requested, clamped to the media's duration (null for one segment)"},
+                 "requested_duration": {"type": "number", "description": "the requested length, as expected_duration"},
+                 "output_duration": {"type": ["number", "null"], "description": "the written file's length, measured (null under --dry-run)"},
+                 "duration_delta_seconds": {"type": ["number", "null"], "description": "output_duration minus requested_duration (null under --dry-run)"},
+                 "nearest_keyframes": {"type": ["array", "null"], "description": "the keyframes within 5 s of a start whose stream copy snapped past --tolerance and was re-encoded (null otherwise)"},
+                 "snap": {"type": ["object", "null"], "description": "--snap beats: {mode, tolerance, confidence, tempo_bpm, grid, grid_points, moved, snapped, unchanged, source}; null otherwise"},
                  "dropped_audio_streams": {"type": "integer", "description": "audio tracks of the source this cut did not write (cut writes one, on a stream copy as on a re-encode); 0 for a source with one or none. A notes line and an audio_tracks_dropped warning say so too"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
                  "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
@@ -696,6 +725,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "audio": {"type": "object", "description": "what the mix was built from: voice (null | light | medium | strong), stereo_widen, effects/effects_volume, and with --music the music_volume plus duck (null when --duck was not given, else the threshold in dB and linear, ratio, attack_ms, release_ms, amount_db actually used)"}}
     if name in ("overlay", "graphics", "caption", "grid"):
         extra["font_used"] = FONT_USED_SCHEMA
+    if name in NON_AV_STREAM_TOOLS and "dropped_non_av_streams" not in extra:
+        extra["dropped_non_av_streams"] = {"type": "boolean", "description": "true when the source's subtitle or data streams are not in the output: either the run leaves them out by design (a path whose output they would no longer match, such as speedramp.py's, join.py's or freeze.py's), or they could not be copied and the encode ran again without them (then a non_av_streams_dropped fallback says why); export.py's non_av_streams lists them"}
     if name == "cropdetect":
         extra.update({"windows": {"type": "integer", "description": "sampled windows (--samples)"},
                       "windows_failed": {"type": "integer", "description": "windows ffmpeg could not decode and that were skipped (a cropdetect_windows_failed warning when > 0); every window failing is a kind ffmpeg failure"}})