ffmpeg-skill 2.7.0 → 2.8.1

package/scripts/_common/emit.py

@@ -73,8 +73,17 @@ def _set_current_ctx(ctx: "Context") -> None:
 
 ENV_HW_NOTE = ("VideoToolbox chosen by FFMPEG_SKILL_HW=1 (machine default; ~1.1-3.5x the bytes of x264/x265 "
                "at matched quality); rerun with --no-hw for a final deliverable")
-ENV_NOT_FOR_DELIVERY_NOTE = ("FFMPEG_SKILL_HW=1 is not applied to export.py's delivery presets (a delivered file is where "
-                             "VideoToolbox's larger files cost most); pass --hw to put this export on the GPU")
+ENV_NOT_FOR_DELIVERY_BASE = ("FFMPEG_SKILL_HW=1 is not applied to export.py's delivery presets (a delivered file is where "
+                             "VideoToolbox's larger files cost most)")
+ENV_NOT_FOR_DELIVERY_NOTE = ENV_NOT_FOR_DELIVERY_BASE + "; pass --hw to put this export on the GPU"
+
+
+def env_not_for_delivery_note() -> str:
+    """The note for an export the variable left on the CPU: the advice to pass --hw only on a
+    machine that can take it (the same advice on a Linux box would send the caller to a flag that
+    then reports the CPU encode)."""
+    from _common import decision  # the same name the --hw decisions (and their tests) stand the platform in on
+    return ENV_NOT_FOR_DELIVERY_NOTE if decision.hw_platform_reason() is None else ENV_NOT_FOR_DELIVERY_BASE
 
 
 def _video_encoders(commands: Sequence[str]) -> "Tuple[Optional[str], Optional[str]]":
@@ -120,7 +129,7 @@ def hw_report(ctx: "Context", enc: Optional[str]) -> Dict[str, Any]:
         # (once: a stage that ran on it already said so)
         notes.append(ENV_HW_NOTE)
     if ctx.hw_env_ignored and enc not in (None, "copy"):
-        notes.append(ENV_NOT_FOR_DELIVERY_NOTE)
+        notes.append(env_not_for_delivery_note())
     return {"requested": requested, "source": source, "used": used,
             "fallback": bool(ctx.hw_fallback) or any(st.get("fallback") for st in stages), "notes": notes}
 

package/scripts/_common/probe.py

@@ -9,6 +9,7 @@ import json
 import math
 import os
 import re
+import statistics
 from fractions import Fraction
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.emit import die
@@ -285,6 +286,9 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "nb_frames": _to_int(video.get("nb_frames")),
             # the stream's own length (a container's also counts audio priming and a longer track)
             "duration": _to_float(video.get("duration")),
+            # where the stream starts; a video stream that starts after its audio (or the reverse)
+            # is how a lossless cut's A/V skew shows up
+            "start_time": _to_float(video.get("start_time")),
             "bitrate": _to_int(video.get("bit_rate")),
         }
     if audio:
@@ -295,6 +299,7 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
             "sample_rate": _to_int(audio.get("sample_rate")),
             "bitrate": _to_int(audio.get("bit_rate")),
             "duration": _to_float(audio.get("duration")),
+            "start_time": _to_float(audio.get("start_time")),
         }
         # every audio stream in file order: index n here is `-map 0:a:n` (audio.py --audio-stream n)
         out["audio_streams"] = [{
@@ -343,6 +348,93 @@ def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
     return sorted(set(out))
 
 
+# frame timing: is a stream's frame rate really variable? (cut.py's VFR guard)
+TIMING_WINDOWS = 5          # sampled windows per file, fewer on a short one
+TIMING_WINDOW_SECONDS = 6
+TIMING_MIN_DELTAS = 20      # fewer measured intervals than this is no evidence either way
+
+
+def complete_pts(packets: Sequence[Dict[str, Any]]) -> List[Any]:
+    """The pts of `packets` (as read, in decode order) whose frames are all there: those at or
+    before the last dts read. A read that stops just after a frame stored ahead of the B-frames
+    shown before it has missed those B-frames, and their gap would read as a dropped frame; every
+    frame shown by the last dts was decoded by then, so it was read. (FFmpeg 9.0's interval reads
+    measured whole on MP4; this keeps a demuxer that stops elsewhere from faking VFR.)"""
+    dts = [p["dts"] for p in packets if isinstance(p.get("dts"), int)]
+    pts = [p.get("pts") for p in packets]
+    return pts if not dts else [t for t in pts if isinstance(t, int) and t <= max(dts)]
+
+
+def classify_frame_timing(windows: Sequence[Sequence[Any]], time_base: Any) -> Dict[str, Any]:
+    """Whether the frame timing in sampled windows is constant. `windows` are lists of pts in
+    `time_base` ticks, the first starting at the file's first packet.
+
+    Each window's pts are sorted (decode order stores B-frames out of sequence) and differenced,
+    with repeats and missing values dropped. The file-start window also drops its first interval:
+    an edit list or encoder priming can stretch it without the frame rate being variable.
+    `sampled_cfr` needs every interval within one tick (at least 1 ms) of its window's median and
+    the window medians to agree, so a single dropped or irregular frame is `vfr`. The tolerance
+    never exceeds half a frame: a tick that coarse (AVI's 1/fps) cannot round an interval, and one
+    tick of slack there would pass a dropped frame. Fewer than
+    TIMING_MIN_DELTAS intervals is `inconclusive`. What happens between the windows is not seen."""
+    result: Dict[str, Any] = {"measured": "inconclusive", "windows": len(windows), "deltas": 0}
+    tick = _fraction(str(time_base)) if time_base else None
+    if not tick or tick <= 0:
+        return result
+    per_window: List[List[float]] = []
+    for i, pts in enumerate(windows):
+        vals = sorted(float(p) for p in pts if isinstance(p, (int, float)) and math.isfinite(p))
+        deltas = [(b - a) * float(tick) for a, b in zip(vals, vals[1:]) if b != a]
+        per_window.append(deltas[1:] if i == 0 else deltas)
+    per_window = [d for d in per_window if d]
+    result["deltas"] = sum(len(d) for d in per_window)
+    if result["deltas"] < TIMING_MIN_DELTAS:
+        return result
+    medians = [statistics.median(d) for d in per_window]
+    tol = min(max(0.001, float(tick) + 1e-6), min(medians) / 2)
+    steady = all(abs(x - m) <= tol for d, m in zip(per_window, medians) for x in d)
+    result["measured"] = "sampled_cfr" if steady and max(medians) - min(medians) <= tol else "vfr"
+    return result
+
+
+def timing_window_starts(duration: float, start: float = 0.0) -> List[float]:
+    """Up to TIMING_WINDOWS non-overlapping window starts spread over the file, the first on its
+    first packet. -read_intervals takes timestamps, so a file that starts at 10 s is read from 10."""
+    n = max(1, min(TIMING_WINDOWS, int((duration or 0.0) // TIMING_WINDOW_SECONDS)))
+    span = (duration or 0.0) - TIMING_WINDOW_SECONDS
+    return [round(start + (span * i / (n - 1) if n > 1 else 0.0), 3) for i in range(n)]
+
+
+def measure_frame_timing(path: str, duration: Optional[float], start: float = 0.0) -> Dict[str, Any]:
+    """classify_frame_timing over sampled windows of `path`'s first video stream that is not cover
+    art (probe()'s choice): one packet-only ffprobe per window, no decoding. An interval read seeks
+    back to the keyframe before its start and, given a relative end, ends that far past the
+    keyframe -- on a long GOP every window read the file's first seconds -- so each window names
+    its absolute end and keeps only the frames from its start. The first window does not seek at
+    all: a seek to the start of an edit-listed MP4 skips its keyframe, stored before the start
+    with a negative pts, and loses the frames that depend on it (seeks near the start behave
+    erratically, so no margin is safe). The cost: a file whose video begins long after its first
+    packet is demuxed, not decoded, up to the video start. An ffprobe failure is `inconclusive`."""
+    ffprobe = require_tool("ffprobe")
+    windows: List[List[Any]] = []
+    time_base = None
+    for i, t in enumerate(timing_window_starts(duration or 0.0, start)):
+        proc = run([ffprobe, "-v", "error", "-select_streams", "V:0", "-show_packets",
+                    "-show_entries", "packet=pts,dts:stream=time_base", "-of", "json",
+                    "-read_intervals", f"{t if i else ''}%{t + TIMING_WINDOW_SECONDS:.3f}", path], quiet=True, check=False)
+        try:
+            doc = json.loads(proc.stdout) if proc.returncode == 0 else None
+        except ValueError:
+            doc = None
+        if not isinstance(doc, dict):
+            return {"measured": "inconclusive", "windows": len(windows), "deltas": 0}
+        time_base = time_base or ((doc.get("streams") or [{}])[0] or {}).get("time_base")
+        tick = float(_fraction(str(time_base)) or 0) if time_base else 0.0
+        windows.append([p for p in complete_pts(doc.get("packets") or [])
+                        if isinstance(p, int) and p * tick >= t - 1e-6])
+    return classify_frame_timing(windows, time_base)
+
+
 def measured_level_dbfs(path: str, seconds: Optional[float] = 120.0,
                         audio_stream: Optional[int] = None) -> Optional[Dict[str, float]]:
     """Mean and peak level of the first `seconds` of audio (volumedetect), in dBFS; None if unmeasurable.

package/scripts/_common/runner.py

@@ -885,9 +885,10 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
                 why = videotoolbox_failure(proc.stderr or "")
                 if why is not None:
                     reason = f"VideoToolbox refused the encode: {why}"
+                    # said before the retry, without a claim about its outcome: a retry that never
+                    # returns (a timeout exits from inside _execute) leaves this line, which is true
+                    _set_refusal_note(ctx, reason, "; retrying on the CPU encoder")
                     info(reason + "; retrying on the CPU encoder")
-                    ctx.hw_notes.append(reason + "; re-encoded on the CPU")
-                    ctx.hw_fallback = True
                     ctx.commands[-1] = _cmdline(cpu_cmd[:-1] + [cmd[-1]])
                     if not quiet:
                         # echoed like the first attempt, so a caller that reads the "$ " lines
@@ -895,6 +896,11 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
                         info("$ " + ctx.commands[-1], ctx=ctx)
                     proc, tried = even_retry(_execute(cpu_cmd), cpu_cmd)
                     retried = True
+                    # the outcome replaces the line above: a failure document must not claim a
+                    # re-encode that did not happen, and hw.fallback is the same claim as a flag
+                    ok = proc.returncode == 0
+                    _set_refusal_note(ctx, reason, "; re-encoded on the CPU" if ok else "; the CPU retry failed too")
+                    ctx.hw_fallback = ctx.hw_fallback or ok
         if proc.returncode != 0 and check:
             _fail(tried, proc.returncode, proc.stderr or "", ctx=ctx, retried=retried)
         if final and tmp:
@@ -910,6 +916,14 @@ def run(cmd: Sequence[str], *, quiet: bool = False, check: bool = True, ctx: "Op
     return proc
 
 
+def _set_refusal_note(ctx: "Context", reason: str, outcome: str) -> None:
+    """One note per refusal: the latest outcome for `reason` replaces any earlier line for it, so a
+    job of many encodes names it once, and a process that ran an earlier job with the same refusal
+    does not keep that job's outcome beside this one."""
+    ctx.hw_notes[:] = [n for n in ctx.hw_notes if not n.startswith(reason)]
+    ctx.hw_notes.append(reason + outcome)
+
+
 def _execute(exec_cmd: List[str]) -> subprocess.CompletedProcess:
     """One attempt, never exiting on failure (run() decides after its retries)."""
     if STATE.progress and _is_ffmpeg(exec_cmd) and exec_cmd[-1] != "-":
@@ -1158,11 +1172,17 @@ def ffmpeg_base(overwrite: bool = True) -> List[str]:
     return cmd
 
 
-def place_output(src: str, dst: str) -> None:
+def place_output(src: str, dst: str, move: bool = False) -> None:
     """Deliver an already-rendered file to `dst` under the same rules as an ffmpeg output:
-    the path is checked, an existing file is only replaced through a sibling temp so a
-    failed copy never costs the caller what was there, and the result is remembered as ours.
-    render.py's final `copyfile()` used to bypass all three."""
+    the path is checked, the output's lock is held (as run() holds it for an ffmpeg write), an
+    existing file is only replaced through a sibling temp so a failed copy never costs the
+    caller what was there, and the result is remembered as ours. render.py's final
+    `copyfile()` used to bypass all of them.
+
+    `move`: `src` is a temp file the caller wrote next to `dst` (sibling_temp), renamed into place
+    with os.replace() under the lock instead of copied -- a checked `cut.py --segments` join was
+    copied whole, about 2 s for 240 MB. A rename that fails (another filesystem) falls back to
+    the copy."""
     import shutil
     cmd = ["ffmpeg", dst]
     _check_output_path(cmd)
@@ -1170,18 +1190,35 @@ def place_output(src: str, dst: str) -> None:
     d, base = os.path.split(dst)
     stem, ext = os.path.splitext(base)
     tmp = os.path.join(d, f".{stem}.ffskill-{os.getpid()}{ext}")
-    try:
-        shutil.copyfile(src, tmp)
-        os.replace(tmp, dst)
-    except OSError as e:
+    with _OutputLock(dst):
+        if move:
+            try:
+                os.replace(src, dst)
+                _remember_output(cmd)
+                return
+            except OSError:
+                pass
         try:
-            os.remove(tmp)
-        except OSError:
-            pass
-        die(f"could not place {dst}: {e}", kind="output")
+            shutil.copyfile(src, tmp)
+            os.replace(tmp, dst)
+        except OSError as e:
+            try:
+                os.remove(tmp)
+            except OSError:
+                pass
+            die(f"could not place {dst}: {e}", kind="output")
     _remember_output(cmd)
 
 
+def sibling_temp(dst: str, tag: str) -> str:
+    """A hidden path next to `dst`, with its extension (the muxer is chosen by it), for a file
+    place_output(..., move=True) renames into place: same directory, so the rename never
+    crosses a filesystem."""
+    d, base = os.path.split(dst)
+    stem, ext = os.path.splitext(base)
+    return os.path.join(d, f".{stem}.ffskill-{tag}-{os.getpid()}{ext}")
+
+
 _DRAWTEXT_TMPDIR: "Optional[str]" = None
 
 
@@ -1234,7 +1271,9 @@ def flush_drawtext_textfiles(cmd: "Sequence[str]") -> "List[str]":
         # symlink guard is belt and braces there and unavailable on Windows
         flags = os.O_WRONLY | os.O_CREAT | os.O_TRUNC | getattr(os, "O_NOFOLLOW", 0)
         fd = os.open(path, flags, 0o600)
-        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        # newline="\n": text mode would write each kept line break as CRLF on Windows, and
+        # drawtext from FFmpeg 6.1 draws that as a blank line plus a line break
+        with os.fdopen(fd, "w", encoding="utf-8", newline="\n") as fh:
             fh.write(body)
         written.append(path)
     return written

package/scripts/_contract.py

@@ -78,7 +78,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "--analyze"}, {"capability": "filter:signalstats", "when": "--analyze"}],
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
     "cut": dict(role="execution", inputs=["video or audio asset"], outputs=["cut video/audio artifact (same container family, or audio extracted when -o has an audio extension)"],
-                required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"}, HDR_X265, {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
+                required=FF, optional=[{"capability": X264, "when": "re-encode: --accurate, VFR source, or a keyframe farther than --tolerance"},
+                                       dict(HDR_X265, when=HDR_X265["when"] + "; with --keep-hevc on an HEVC source"), {"capability": AAC, "when": "re-encode of a video container"}] + AUDIO_OUT,
                 video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "fit": dict(role="execution", inputs=["video asset"], outputs=["video artifact at the requested duration / aspect / fps"],
                 required=FF + [X264, AAC], optional=[HDR_X265, {"capability": "filter:minterpolate", "when": "--smooth interpolate"},
@@ -234,7 +235,7 @@ DRY_RUN_ANALYSIS = {
     "scenes": "scene and audio-peak measurement runs; --sheet and --edl are not written",
     "report": "probe, loudness and contact-sheet measurements run; the HTML is not written",
     "cropdetect": "the cropdetect filter runs over the sampled windows to measure bars; this tool never writes a file regardless of --dry-run",
-    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written",
+    "silence": "silencedetect runs so the reported silences and keep ranges are real; the cut output is not written. --filler --transcribe also runs the speech engine (its word timings are what the filler spans are planned on), which may download a model on first use",
     "loudness": "the loudnorm measurement pass runs so input_i and the planned pass-2 command are real; the normalised output is not written",
     "check": "read-only tool; the loudness measurement (or, when it is skipped, the audio row's volumedetect) and the --content decode run under --dry-run too, so every row is present",
     "stabilize": "vidstabdetect (pass 1, into a temp file) runs; the stabilised output (pass 2) is not written",
@@ -254,7 +255,7 @@ DRY_RUN_NOTES = {
 # of the original audio codec never happens on those tools.
 REENCODE_META: Dict[str, Dict[str, str]] = {
     "probe":     dict(video="never", audio="never", note="analysis only, no artifact"),
-    "cut":       dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, a VFR source, or a keyframe snap past --tolerance (see cut.py --json: mode, keyframe_snapped)"),
+    "cut":       dict(video="conditional", audio="conditional", note="lossless -c copy preferred; re-encodes on --accurate, --codec, a VFR source (--vfr-guard), a keyframe snap past --tolerance, or a --segments join the parts cannot stream-copy (see cut.py --json: mode, reencode_reason, keyframe_snapped)"),
     "fit":       dict(video="always", audio="always", note="always re-encodes to AAC when audio is present, even if only --fps or --aspect was asked for"),
     "crop":      dict(video="always", audio="always", note="the crop filter always forces a re-encode of both streams"),
     "deinterlace": dict(video="always", audio="always", note="the yadif filter always forces a re-encode of the video stream; audio is re-encoded to AAC when present"),
@@ -453,7 +454,10 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     elif name == "verify":
         extra = {"report": {"type": ["string", "null"]}, "files": {"type": "array"}, "failed": {"type": "integer"}, "total": {"type": "integer"}}
     elif name == "batch":
-        extra = {"results": {"type": "array"}, "processed": {"type": "integer"}, "total": {"type": "integer"}}
+        extra = {"results": {"type": "array", "description": "one row per input; a row whose recipe ran cut.py carries cut_reencoded (each cut.py call's reencoded) and cut_reencode_reasons (each reason those calls named, once per call)"},
+                 "processed": {"type": "integer"}, "total": {"type": "integer"},
+                 "cut_stream_copy": {"type": ["object", "null"], "description": "cut.py calls across the folder: {calls, stream_copy, reencoded, stream_copy_rate}; null when no cut.py step ran"},
+                 "cut_reencode_reasons": {"type": ["object", "null"], "description": "how many cut.py calls named each reencode_reason ({} when none re-encoded); a re-encoded call whose row came from a cache an earlier 2.x batch wrote, which recorded no reasons, counts as unknown; null when no cut.py step ran"}}
     elif name == "report":
         extra = {"report": {"type": "string"}, "check": {"type": ["object", "null"]}}
     elif name == "export":
@@ -475,9 +479,24 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
         extra = {"expected_duration": {"type": "number", "description": "seconds requested"},
                  "duration_error_ms": {"type": ["number", "null"], "description": "written minus requested, measured by ffprobe (null under --dry-run)"},
                  "precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
-                               "description": "packet: stream copy on a packet/keyframe boundary; sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
+                               "description": "the whole run's: packet only when nothing re-encoded, the --segments join included (stream copy on a packet/keyframe boundary); sample: decoded audio trimmed to the sample, lossless output; codec_frame: sample-trimmed then framed by a lossy encoder (priming delay adds to the length); frame: re-encoded video"},
+                 "least_exact_precision": {"enum": ["packet", "sample", "codec_frame", "frame"],
+                                           "description": "the least exact segment's precision (the order packet, codec_frame, frame, sample); differs from precision only for an audio-only --segments join of copied and re-encoded parts"},
+                 "keyframe_snapped": {"type": "boolean", "description": "precision is packet: the run is a stream copy end to end, which lands on keyframes and packets. Whether a copied start really moved is start_snapped"},
+                 "start_snapped": {"type": ["boolean", "null"], "description": "measured: true when a copied segment's picture starts more than one frame from its requested start (the keyframe the copy's seek lands on, measured with the seek ffmpeg makes); false when every start is where asked (an MP4 edit list hides the pre-roll, the start is a keyframe, an audio-only copy, or everything re-encoded); null when a copied start was not measured (--dry-run)"},
                  "reencoded": {"type": "boolean"},
-                 "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"}}
+                 "reencode_reason": {"type": "array", "items": {"enum": ["requested", "codec", "vfr", "vfr_inconclusive", "pcm_container", "copy_failed", "tolerance", "concat_fallback"]},
+                                     "description": "why anything was re-encoded, distinct values in first-seen order ([] when nothing was): requested (--accurate), codec (--codec), vfr (a variable-frame-rate source forced --accurate), vfr_inconclusive (its frame timing could not be measured), pcm_container (compressed audio into a .wav), copy_failed (the stream copy errored), tolerance (a keyframe snap past --tolerance), concat_fallback (--segments parts could not be joined by stream copy)"},
+                 "segment_precision": {"type": ["array", "null"], "items": {"enum": ["packet", "sample", "codec_frame", "frame"]},
+                                       "description": "--segments only: each segment's precision in order; least_exact_precision is the least exact of them (null for a single segment)"},
+                 "edit_list": {"type": "boolean", "description": "--edit-list on a single MP4/MOV stream copy: it kept the edit list it wrote instead of -avoid_negative_ts make_zero, so the keyframe's pre-roll is stored but hidden and the picture and the sound start at the requested time (false for every other path, the default included)"},
+                 "stored_preroll_seconds": {"type": ["number", "null"], "description": "with edit_list: seconds decoded from the keyframe the copy's seek lands on up to the requested start and hidden by the edit list (a player that ignores edit lists shows them); null otherwise"},
+                 "av_start_skew_seconds": {"type": ["number", "null"], "description": "the output's audio start minus its video start (null when either is missing or under --dry-run); reported, never repaired: on a stream copy only, a warning in notes when it is more than max(2 frames, 0.1 s) away from the source's own skew where the copy's picture starts (the keyframe it began from; the requested start under --edit-list), naming --accurate (and --edit-list for a single MP4/MOV copy whose start snapped)"},
+                 "notes": {"type": "array", "items": {"type": "string"}, "description": "stored pre-roll behind an --edit-list edit list, or an --edit-list copy judged by its video; an A/V start skew with its remedies; a source the default --vfr-guard average took for VFR whose sampled timing is constant (naming --vfr-guard sampled), or a sampled measurement that forced or (--vfr-guard off) skipped a re-encode; a --segments segment ended with the video, or held on its last frame for its sound; a --segments join re-cut because the source uses open GOPs, because a later B-frame .mp4/.mov segment starts between keyframes, or because its join check failed"},
+                 "vfr_check": {"type": "object", "description": "the sampled frame timing of a video input that could still stream-copy: under --vfr-guard average (the default) only when its nominal and average frame rates differ, which re-encodes it (reason vfr) whatever the sample says; under sampled or off on every such input (absent for audio-only input or output, --accurate, --codec, or a --dry-run input a plan has not written yet): {heuristic: true, measured, method: \"sampled\", guard, windows, deltas}. measured is sampled_cfr (every packet interval in up to five 6 s windows within a tick, at least 1 ms and at most half a frame, of its window's median, and the windows agree; the file-start window's first interval is ignored), vfr (under sampled, forces a re-encode, reason vfr) or inconclusive (fewer than 20 intervals or ffprobe failed; under sampled, reason vfr_inconclusive). --vfr-guard off keeps the copy either way, with a note. Variable timing between the windows is not seen"},
+                 "lossless_alternative": {"type": ["string", "null"], "description": "when a lossless cut re-encoded because of the keyframe snap: the --start that would stream-copy instead, and how far it is from the request"},
+                 "join_check": {"type": ["object", "null"], "description": "--segments video stream-copy join: the written file measured by demuxing, {packets, expected_packets, max_step_seconds, audio_offset_ms, audio_parts_checked, ok}. expected_packets counts the source's video packets from each part's start keyframe to its end (or the end of the video); max_step_seconds is the largest presentation step (null when vfr_check measured anything but sampled_cfr, e.g. a --vfr-guard off join of variable timing, which checks the count only), and each step at a join must be the step its parts predict within 1 ms; audio_offset_ms is, per part, its sound's shift minus its picture's (+ = sound late) from audio packets matched by CRC32 to the source stream shaped like the joined audio (FFmpeg's default selection may copy one other than a:0; an MPEG-TS source's AAC is hashed without its ADTS headers) (null for a part with no unique match, e.g. digital silence; null as a whole when the source has no audio or the video check failed), and audio_parts_checked counts the measured parts; ok is the conjunction (counts, steps, every measured part within 5 ms), and false means the join was re-cut from the source (concat_fallback) and this is the failed measurement. null for a single segment, audio, --dry-run, --accurate/--codec/a forced re-encode, a segment that re-encoded, or a join that fell back before a copy join was attempted (open GOPs, a later B-frame segment starting between keyframes, parts that differ, a concat error)"},
+                 "segment_end_snap_seconds": {"type": ["array", "null"], "items": {"type": ["number", "null"]}, "description": "--segments stream-copy join: per segment, the signed seconds its end moved to the keyframe the copied part stops at (the first keyframe at or after the requested end, never an earlier one; null for a part that runs to the end of the video, a part of a source with no B-frames, which is cut to its requested end as in every 2.x release, or a Matroska/MPEG-TS part, which is not snapped). null as a whole unless the output is those copied parts: a single segment, audio, --dry-run, or any re-encode or fallback"}}
     elif name == "join":
         extra = {"mode": {"enum": ["video", "audio"]}, "clips": {"type": "integer"}, "transition": {"type": "string"},
                  "expected_duration": {"type": ["number", "null"], "description": "clip lengths minus the transitions; null under --dry-run while an input is pending (its length is unknown)"},
@@ -499,10 +518,15 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
     props = dict(base)
     props.update(extra)
     notes = props.get("notes")
-    if hw and isinstance(notes, dict) and notes.get("description"):
-        # a tool-specific condition is not the only one: emit() adds the GPU line to any tool
-        props["notes"] = dict(notes, description=notes["description"] + "; also, on a VideoToolbox encode (--hw / "
-                              "$FFMPEG_SKILL_HW), a line that its quality is not CRF-equivalent (see hw)")
+    if hw:
+        # emit() adds the VideoToolbox quality line to `notes` on every tool that takes --hw, so every
+        # such tool publishes `notes`, and a tool-specific condition (loop's "--boomerang ... the audio
+        # was dropped", export's own lines) is not the only one it can carry
+        gpu = "a line that its quality is not CRF-equivalent (on a VideoToolbox encode: --hw / $FFMPEG_SKILL_HW; see hw)"
+        if isinstance(notes, dict) and notes.get("description"):
+            props["notes"] = dict(notes, description=notes["description"] + "; also " + gpu)
+        else:
+            props["notes"] = dict(notes or {"type": "array", "items": {"type": "string"}}, description=gpu[0].upper() + gpu[1:])
     required = ["status", "output", "dry_run", "commands"]
     return {"type": "object", "properties": props, "required": required, "additionalProperties": True}
 
@@ -821,8 +845,9 @@ def doctor() -> Dict[str, Any]:
 
     `gpu_encoders` is a separate, honest answer to a question none of the required/optional
     capabilities above ask: which GPU-backed encoders (nvenc, videotoolbox, qsv, vaapi, amf) this
-    ffmpeg BUILD carries, from `-encoders` alone. No tool here requires or uses one -- every tool
-    still assumes CPU x264/x265 -- so `gpu_encoders` never affects `ok` or any tool's `usable`. It
+    ffmpeg BUILD carries, from `-encoders` alone. No tool requires one -- every tool runs on CPU
+    x264/x265 unless `--hw` / FFMPEG_SKILL_HW=1 puts it on VideoToolbox (Apple Silicon only) -- so
+    `gpu_encoders` never affects `ok` or any tool's `usable`. It
     only proves the build shipped the capability, never that the GPU/driver on this machine will
     actually accept a job (that needs a real encode, which this introspection never runs).
 
@@ -1420,7 +1445,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
             # first time it runs; faster-whisper is a library, so its fetch is made from the skill's own
             # process. A caller that sandboxes the network must know that before a first --transcribe.
             "model_downloads": {
-                "when": "first use of a speech engine (--transcribe) whose model is not cached yet; media is never uploaded",
+                "when": "first use of a speech engine (--transcribe; silence.py --filler --transcribe runs it under --dry-run too, caption.py --transcribe does not) whose model is not cached yet; media is never uploaded",
                 "in_process": {"faster-whisper": "Hugging Face (Systran/faster-whisper-<model>)"},
                 "child_process": {"parakeet-mlx": "Hugging Face (mlx-community/parakeet-*)",
                                   "openai-whisper": "OpenAI (its model checkpoint)"},
@@ -1494,7 +1519,7 @@ def main() -> int:
                 print(f"note: overall 'ok' means nothing REQUIRED BY EVERY TOOL is missing -- {len(not_usable)} tool(s) still can't run today: {', '.join(not_usable)} (see doctor --json .tools for why)")
             gpu = d["gpu_encoders"]
             if gpu["status"] == "parsed":
-                print(f"GPU-backed encoders in this build: {len(gpu['present'])} (no tool here uses one; names in doctor --json)")
+                print(f"GPU-backed encoders in this build: {len(gpu['present'])} (only --hw / FFMPEG_SKILL_HW=1 use one, VideoToolbox on Apple Silicon; names in doctor --json)")
             print(_fonts_summary_line(d["fonts"]))
             print("full detail: doctor --json (capability lists, per-tool `usable`, fix hints)")
             for err in d["errors"]:

package/scripts/batch.py

@@ -173,6 +173,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         ok, _doc = run_step(["render.py", str(pj)], budget())
         step_docs = [("render", _doc)]
         cut_reencoded: List[bool] = []
+        cut_reasons: List[str] = []
     else:
         steps = recipe.get("steps") or []
         if not steps:
@@ -181,18 +182,20 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
         ok = True
         cut_reencoded = []
         step_docs = []
+        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('.')}")
             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))
-            # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut needed
-            # the tolerance-triggered hybrid re-encode fallback (cut.py ORs its per-segment results
-            # into one top-level field; it doesn't report which range, so this is per cut.py call,
-            # not per --segments range).
+            # only cut.py's own doc carries `reencoded` -- true if ANY range this call cut (or its
+            # --segments join) re-encoded, for the reasons in its `reencode_reason` (distinct per
+            # call, so cut_reencode_reasons lists each reason once per cut.py call that named it).
+            # Per cut.py call, not per --segments range.
             if step_ok and argv and argv[0] == "cut.py" and isinstance(doc, dict) and "reencoded" in doc:
                 cut_reencoded.append(bool(doc["reencoded"]))
+                cut_reasons.extend(r for r in (doc.get("reencode_reason") or []) if isinstance(r, str))
             if not step_ok:
                 ok = False
                 break
@@ -200,6 +203,7 @@ def process(src: Path, recipe: Dict[str, Any], outdir: Path, work: Path,
     result: Dict[str, Any] = {"file": str(src), "output": str(final), "ok": ok, "seconds": round(time.time() - t0, 1)}
     if cut_reencoded:
         result["cut_reencoded"] = cut_reencoded
+        result["cut_reencode_reasons"] = cut_reasons
     # the encoder each item really ran and its GPU facts (--hw / FFMPEG_SKILL_HW: on VideoToolbox,
     # fell back and why): this process encodes nothing itself, so its top-level hw.used is null
     result.update(steps_encoder_report(step_docs))
@@ -563,23 +567,36 @@ def main() -> int:
         die(f"{len(results) - done} of {len(results)} items failed: {', '.join(failed_files[:5])}" + (" ..." if len(failed_files) > 5 else ""),
             kind="verification", output=None, dry_run=STATE.dry_run, results=results, processed=done, total=len(results))
     # cut.py's own `reencoded`, rolled up across every cut.py step this batch ran: how much of the
-    # folder landed on the fast lossless path (mode "copy") vs fell back to the tolerance-triggered
-    # hybrid re-encode on at least one range -- purely a function of the sources' keyframe placement
-    # relative to each cut point, not something a single run can predict, so it's worth reporting
-    # after the fact rather than not at all. Per cut.py call, not per --segments range: cut.py ORs
-    # its own per-segment results into one top-level field and doesn't say which range needed it.
+    # folder landed on the fast lossless path (mode "copy") vs re-encoded on at least one range.
+    # Keyframe placement, VFR sources, --accurate/--codec in the recipe and --segments joins all
+    # cause it, so the summary counts cut.py's own `reencode_reason` values rather than guessing
+    # one cause. Per cut.py call, not per --segments range.
     all_cuts = [r for res in results for r in (res.get("cut_reencoded") or [])]
     cut_summary = None
+    # how many cut.py calls named each reason, beside cut_stream_copy (whose shape is 2.x's,
+    # unchanged); null when no cut.py step ran
+    reasons: Optional[Dict[str, int]] = None
     if all_cuts:
         copied = sum(1 for r in all_cuts if not r)
         cut_summary = {"calls": len(all_cuts), "stream_copy": copied, "reencoded": len(all_cuts) - copied,
                         "stream_copy_rate": round(copied / len(all_cuts), 3)}
+        reasons = {}
+        for res in results:
+            if "cut_reencode_reasons" not in res:
+                # a row from a cache an earlier 2.x batch wrote: it says which calls re-encoded,
+                # not why, so they count as "unknown" rather than leaving {} ("none re-encoded")
+                unknown = sum(1 for r in res.get("cut_reencoded") or [] if r)
+                if unknown:
+                    reasons["unknown"] = reasons.get("unknown", 0) + unknown
+            for r in res.get("cut_reencode_reasons") or []:
+                reasons[r] = reasons.get(r, 0) + 1
+        why = (" (reencode_reason: " + ", ".join(f"{k} x{v}" for k, v in reasons.items()) + ")") if reasons else ""
         info(f"cut.py: {copied}/{len(all_cuts)} call(s) stayed fully lossless stream-copy "
-             f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} fell back to hybrid re-encode on at least one range")
+             f"({cut_summary['stream_copy_rate']:.0%}), {len(all_cuts) - copied} re-encoded a range or its --segments join{why}")
     emit(None, results=results, processed=done, total=len(results),
          jobs=jobs, jobs_requested=requested, wall_seconds=round(time.time() - started, 1),
          item_seconds_total=round(sum(float(r.get("seconds") or 0) for r in results), 1),
-         timed_out=timed_out["hit"], cut_stream_copy=cut_summary)
+         timed_out=timed_out["hit"], cut_stream_copy=cut_summary, cut_reencode_reasons=reasons)
     return 0