ffmpeg-skill 2.6.0 → 2.8.0

package/scripts/_common/decision.py

@@ -478,6 +478,19 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     return _maybe_hw("hevc", crf, meta, True, _x265_hdr_default(v, crf, preset))
 
 
+def source_codec_video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium",
+                            keep_hevc: bool = False) -> List[str]:
+    """video_args(), except that with `keep_hevc` (cut.py --keep-hevc) an SDR HEVC source re-encodes
+    to HEVC (8-bit, BT.709-tagged, on VideoToolbox when --hw asks) instead of H.264: a cut is a trim,
+    so a re-encoded segment can come out in the codec the source (and any copied segment beside it)
+    is in. Opt-in within 2.x, where an SDR re-encode stays x264 unless asked. An HDR or BT.2020
+    source always takes video_args()'s Main10 line, and --codec always wins."""
+    v = (meta or {}).get("video") or {}
+    if keep_hevc and not STATE.codec and v.get("codec") == "hevc" and not v.get("bt2020_or_hdr"):
+        return encoder_args("hevc", crf, preset, meta)
+    return video_args(meta, crf, preset)
+
+
 def _x265_hdr_default(v: Dict[str, Any], crf: int, preset: str) -> List[str]:
     cs = v.get("color_space") or "bt2020nc"
     prim = v.get("color_primaries") or "bt2020"

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

@@ -1158,11 +1158,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 +1176,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
 
 

package/scripts/_contract.py

@@ -54,6 +54,8 @@ ROLES = {
 #   filter:<name>               `ffmpeg -filters`
 #   bsf:<name>                  `ffmpeg -bsfs`
 #   external:whisper            a local whisper engine (whisper.cpp / faster-whisper / openai-whisper)
+#   external:parakeet           a local Parakeet engine (parakeet-mlx, or parakeet-cli with a .gguf model);
+#                               English. Either external engine satisfies --transcribe.
 # "optional" entries name the flag or condition under which the capability is needed.
 FF = ["ffmpeg", "ffprobe"]
 X264 = "encoder:libx264"
@@ -76,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"},
@@ -145,7 +148,7 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                       required=FF + [X264], optional=[],
                       video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "caption": dict(role="execution", inputs=["video asset", "SRT/ASS file or timed text (--text)"], outputs=["video artifact with burnt-in captions (--mode burn)", "video artifact with one or several language-tagged soft subtitle streams (--mode mux, --srt file:lang repeated)", "generated .srt / .ass sidecar"],
-                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"},
+                    required=FF + [X264, AAC, "filter:subtitles"], optional=[{"capability": "filter:ass", "when": "--animate / --karaoke"}, HDR_X265, {"capability": "external:whisper", "when": "--transcribe"}, {"capability": "external:parakeet", "when": "--transcribe (English; either engine family satisfies it)"},
                                             {"capability": "encoder:mov_text", "when": "--mode mux with a .mp4/.m4v/.mov output"}, {"capability": "encoder:webvtt", "when": "--mode mux with a .webm output"}, {"capability": "encoder:srt", "when": "--mode mux with a .mkv output"}],
                     video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "overlay": dict(role="execution", inputs=["video asset", "image (--image / --logo), text (--text), or a second video (--video) to composite"], outputs=["video artifact with the overlay composited"],
@@ -172,7 +175,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
                     required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"},
-                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"}] + AUDIO_OUT,
+                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"},
+                                                                    {"capability": "external:parakeet", "when": "--filler --transcribe (English; either engine family satisfies it)"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
                  required=FF + ["filter:xfade", "filter:acrossfade"],
@@ -251,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"),
@@ -409,7 +413,8 @@ def output_schema(name: str, meta: Dict[str, Any], hw: bool = False) -> Dict[str
                  "notes": {"type": "array", "items": {"type": "string"}, "description": "present when no --platform was named: youtube was assumed and judgement rows are WARN"},
                  "checks": {"type": "array", "items": {"type": "object", "properties": {"check": {"type": "string", "description": "row name; --content adds black, frozen and silence; audio FAILs when the track is present but silent (peak <= -50 dBFS)"}, "status": {"enum": ["PASS", "WARN", "FAIL"]}, "value": {}, "expected": {}, "fix": {"type": "string"}, "kind": {"enum": ["format", "judgement"]}}}}}
     elif name == "caption":
-        extra = {"caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input"},
+        extra = {"transcription": {"type": "object", "description": "with --transcribe: {engine, model, language, routing (why auto chose it), detected_language when auto detected it}; when auto ran the English-only Parakeet model on English assumed, notes says so"},
+                 "caption": {"type": "object", "description": "cue layout: shifted / wrapped / rebalanced / split / extended / dropped counts, plus wrap ('phrase' or 'measured'), phrase_breaks (1.16), broken_inside_word -- atoms hard-sliced at the column edge because they did not fit alone even at the size floor (1.18.4) -- and overlong -- now residual: a single character alone wider than the column. Burn mode: cues_burned -- non-blank cues that overlap [0, duration] and are drawn -- and cues_outside -- non-blank cues wholly outside it (2.2.6); a burn with no visible cue is refused, kind input"},
                  "tracks": {"type": "array", "description": "--mode mux: one entry per subtitle stream in the output ({index, file, language, title, codec, default, cues, kept_from_input}); a stream the input already carried has file null and kept_from_input true (1.16)"},
                  "subtitle_tracks": {"type": "integer", "description": "--mode mux: how many subtitle streams the output carries"},
                  "emoji": {"type": "object", "description": "how the emoji in the text were drawn (mode, overlays, missing)"},
@@ -430,7 +435,9 @@ 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"},
-                 "speech_aware": {"type": "object", "description": "--speech-aware (1.18): {min_silence, floor, breaths_kept, breaths_kept_seconds, breaths}"}}
+                 "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, ...}"},
+                 "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"}}
     elif name == "sync":
         extra = {"reference": {"type": "string"}, "second": {"type": "string"}, "offset_seconds": {"type": "number"}, "confidence": {"type": "number"}, "meaning": {"type": "string"}, "drift": {"type": "object"},
                  "sources": {"type": "array", "description": "1.18: [{path, offset_s, confidence, drift_ppm}], one per SOURCE; the only per-source shape once more than one SOURCE is given"}}
@@ -447,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":
@@ -469,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)"},
@@ -672,6 +697,13 @@ def _whisper_available() -> bool:
     return importlib.util.find_spec("faster_whisper") is not None or importlib.util.find_spec("whisper") is not None
 
 
+def _parakeet_available() -> bool:
+    """parakeet-mlx on PATH, or parakeet-cli with a model it can find (PARAKEET_CPP_MODEL or a
+    .gguf in ~/.cache/parakeet.cpp) -- the same test the speech bridge applies before running it."""
+    from _common.asr import _parakeet_available as runtime_check  # the bridge's own test, not a copy of it
+    return any(runtime_check(e, shutil) for e in ("parakeet-mlx", "parakeet.cpp"))
+
+
 def _hw_default() -> Dict[str, Any]:
     """--hw's machine facts, normalised (never the raw environment value): whether VideoToolbox
     constant-quality encoding can run here (the tools' own check: Apple Silicon hardware, also
@@ -870,6 +902,8 @@ def doctor() -> Dict[str, Any]:
             state[cap] = _from("bsfs", cap[4:])
         elif cap == "external:whisper":
             state[cap] = "available" if _whisper_available() else "missing"
+        elif cap == "external:parakeet":
+            state[cap] = "available" if _parakeet_available() else "missing"
         else:
             state[cap] = "missing"
     available = sorted(c for c, st in state.items() if st == "available")
@@ -997,7 +1031,15 @@ def _capability_fix_hint(cap: str) -> str:
         return (f"no installed font covers {LANGUAGE_NAMES.get(script, script)} text on this machine; "
                 f"{FONT_INSTALL_HINT} (doctor --json .fonts.scripts lists every script)")
     if cap == "external:whisper":
-        return "install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe"
+        return ("install a local whisper (whisper-cli, whisper-cpp, faster-whisper or openai-whisper) for --transcribe; "
+                "faster-whisper and openai-whisper download their model on first use, and every engine transcribes "
+                "on this machine (the audio is never uploaded)")
+    if cap == "external:parakeet":
+        from _common.asr import PARAKEET_MLX_DEFAULT_MODEL
+        return ("for English --transcribe, install parakeet-mlx (uv tool install parakeet-mlx; its first run downloads "
+                f"{PARAKEET_MLX_DEFAULT_MODEL} from Hugging Face, then it transcribes on this machine and the audio is "
+                "never uploaded) or parakeet-cli with a tdt-0.6b-v2 .gguf in ~/.cache/parakeet.cpp; a local whisper "
+                "covers every language")
     return f"'{cap}' is not available; see docs/contract.md"
 
 
@@ -1362,7 +1404,7 @@ def build(detect: bool = True) -> Dict[str, Any]:
     version = skill_version()
     tools = [tool_spec(n, version) for n in public_tools()]
     wanted = required_capabilities()
-    caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper"}
+    caps: Dict[str, Any] = {"required": wanted["required"], "optional": wanted["optional"], "naming": "ffmpeg | ffprobe | encoder:<name> | filter:<name> | bsf:<name> | external:whisper | external:parakeet"}
     if detect:
         d = doctor()
         caps.update({"available": d["available"], "missing": d["missing"], "missing_optional": d["missing_optional"],
@@ -1389,8 +1431,21 @@ def build(detect: bool = True) -> Dict[str, Any]:
         "execution": {
             "shell": False,
             "arbitrary_executables": False,
-            "subprocess": "argv list only: [python3, scripts/<tool>.py, ...] and [ffmpeg|ffprobe, ...] resolved from PATH",
+            "subprocess": "argv list only: [python3, scripts/<tool>.py, ...] and [ffmpeg|ffprobe, ...] resolved from PATH; "
+                          "with --transcribe, a local speech engine's CLI (whisper.cpp's whisper-cli / whisper-cpp / main, "
+                          "openai-whisper's whisper, parakeet-mlx, parakeet-cli) resolved from PATH",
             "network": False,
+            # `network` is about the skill's own code. A speech engine may fetch its model weights the
+            # 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",
+                "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)"},
+                "none": ["whisper.cpp", "parakeet.cpp"],
+                "offline": "HF_HUB_OFFLINE=1 keeps faster-whisper and parakeet-mlx on the cached copy",
+            },
             "input_mutation": False,
         },
         "invocation": {

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
 
 

package/scripts/caption.py

@@ -49,6 +49,8 @@ from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji
 # The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
 # shares them). They stay caption.py's public names -- every caller and test that reached for
 # caption.parse_srt / caption.transcribe / caption.whisper_word_timings before 1.17 still does.
+from _common import asr as _asr
+from _common.asr import ENGINE_CHOICES
 from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
                      write_srt)
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
@@ -901,7 +903,7 @@ def main() -> int:
                           "them; .mkv is the honest multi-track container and stores the code you give verbatim")
     src.add_argument("--ass", help="ASS file to burn (styles inside the file are used)")
     src.add_argument("--text", help="plain text cue file to convert into SRT (see format above)")
-    src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (whisper-cli / whisper / faster-whisper); never required")
+    src.add_argument("--transcribe", action="store_true", help="generate the SRT from the audio with a local speech-to-text engine if one is installed (parakeet-mlx / parakeet.cpp / whisper-cli / whisper / faster-whisper); never required")
     src.add_argument("--language", "--lang", help="language code (e.g. en, ja, zh, ko): the language for --transcribe (default auto), "
                                                   "the tag on the subtitle stream with --mode mux, and the hint that says whether Han-only "
                                                   "text is Chinese, Japanese or Korean when a font is picked by script")
@@ -914,7 +916,12 @@ def main() -> int:
                           "(default: none, so no player burns in a language the viewer did not ask for)")
     src.add_argument("--offset", default="0", help="shift every cue by TIME (seconds, mm:ss, hh:mm:ss.ms or "
                                                     "hh:mm:ss:ff; a leading - shifts earlier); works for --text, --srt and --ass")
-    src.add_argument("--model", default="base", help="whisper model name/path for --transcribe (default base)")
+    src.add_argument("--model", default="base",
+                     help="speech model for --transcribe: a whisper model name/path (default base), or a Parakeet "
+                          "model (an mlx-community/parakeet-* repo or a .gguf) for the Parakeet engines")
+    src.add_argument("--engine", choices=ENGINE_CHOICES, default=None,
+                     help="speech engine for --transcribe (default: $FFMPEG_SKILL_ASR_ENGINE, else auto = Parakeet "
+                          "for English speech when installed, else whisper.cpp / faster-whisper / openai-whisper)")
     src.add_argument("--write-srt", help="where to save the generated SRT (default: <text>.srt)")
     src.add_argument("--auto-seconds", type=float, default=3.0, help="duration for cues without timing (default 3)")
     src.add_argument("--gap", type=float, default=0.0, help="gap after auto-timed cues in seconds")
@@ -1241,8 +1248,13 @@ def main() -> int:
             cues = []
             info(f"[dry-run] would transcribe {args.input} and write {srt_path}")
         else:
-            cues = transcribe(args.input, srt_path, args.language, args.model, args.audio_stream)
-            args._word_timings = whisper_word_timings(srt_path)
+            # the call's own result, not module state: engine, routing and words belong to this run
+            asr_run = _asr.transcribe_result(args.input, srt_path, args.language, args.model, args.audio_stream,
+                                             engine=args.engine)
+            cues = asr_run.cues
+            args._asr = dict(asr_run.facts)
+            args._asr_notes = list(asr_run.notes)
+            args._word_timings = whisper_word_timings(srt_path) or sorted((w["start"], w["end"], w["word"]) for w in asr_run.words)
             cues, changed = lay_out(cues)
             if changed:
                 write_srt(cues, srt_path)
@@ -1279,7 +1291,8 @@ def main() -> int:
     # WRITING waits for a real run (the rule every side file in this tool follows), which is why
     # the cues are kept in hand below for the font sample and the ASS generator.
     planned_cues: Optional[List[Tuple[float, float, str]]] = None
-    side_notes: List[str] = []
+    # an English-only transcript made on an assumption says so first (asr.assumed_english_note)
+    side_notes: List[str] = list(getattr(args, "_asr_notes", None) or [])
     ass_sample_path = args.ass
     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))
@@ -1416,7 +1429,8 @@ def main() -> int:
         result = probe(output, role="output")
         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 {}))
+        emit(output, tracks=tracks, subtitle_tracks=total, **({"notes": notes} if notes else {}),
+             **({"transcription": args._asr} if getattr(args, "_asr", None) else {}))
         return 0
 
     # A font that covers the text, before anything is rendered: non-Latin cues in a Latin-only
@@ -1582,6 +1596,8 @@ def main() -> int:
         info("caption text unchanged: the cues were burned exactly as given (line breaks, timing "
              "and type size only)")
     extra["caption"] = dict(caption_stats)
+    if getattr(args, "_asr", None):
+        extra["transcription"] = args._asr
     if emoji_plan:
         notes = list(extra.get("notes") or [])
         if emoji_plan["mode"] == "mono":