ffmpeg-skill 3.2.1 → 3.2.3

package/scripts/_common/decision.py

@@ -741,6 +741,13 @@ def _x264_raw(crf: int, preset: str, keep_bt709: bool = True) -> List[str]:
     return args
 
 
+def keeps_source_tags() -> bool:
+    """True when the line being written is an editing master that keeps the source's colour tags
+    and converts no matrix: --codec prores, or an alpha line (--keep-alpha / --transparent,
+    _common.alpha). The BT.709 conversions and labels below are for lines tagged BT.709."""
+    return STATE.codec == "prores" or STATE.alpha_line is not None
+
+
 def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True,
               source: Optional[Dict[str, Any]] = None) -> List[str]:
     """SDR H.264 encoder args -- or, when --codec named another encoder, that encoder's SDR args
@@ -753,7 +760,7 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True,
         args = encoder_args(STATE.codec, crf, preset, None, keep_bt709)
     else:
         args = _maybe_hw("h264", crf, None, keep_bt709, _x264_raw(crf, preset, keep_bt709))
-    return args + (bt709_matrix_args(source) if keep_bt709 and STATE.codec != "prores" else [])
+    return args + (bt709_matrix_args(source) if keep_bt709 and not keeps_source_tags() else [])
 
 
 def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium", convert_matrix: bool = True,
@@ -777,7 +784,7 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     video_args(None)); its RGB or BT.601 pixels are converted to the BT.709 that line is tagged with.
     """
     v = (meta or {}).get("video") or {}
-    fix = bt709_matrix_args(meta if source is None else source) if convert_matrix and STATE.codec != "prores" else []
+    fix = bt709_matrix_args(meta if source is None else source) if convert_matrix and not keeps_source_tags() else []
     if STATE.codec:
         return encoder_args(STATE.codec, crf, preset, meta) + fix
     if not v.get("bt2020_or_hdr"):
@@ -790,7 +797,7 @@ def matrix_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, A
     video_args(line_meta, convert_matrix=False): the conversion one source's own chain starts
     with ("<filter>," -- bt709_matrix_filter), or "" when that source needs none or the line does
     not tag BT.709 (an HDR/BT.2020 line keeps its tags, --codec prores keeps the source's)."""
-    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+    if keeps_source_tags() or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
         return ""
     f = bt709_matrix_filter(meta)
     return f + "," if f else ""
@@ -801,7 +808,7 @@ def label_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, An
     cell beside a converted cell), encoded through video_args(line_meta): the BT.709 label an
     untagged one's chain starts with ("<setparams>," -- bt709_label_filter), or "" (a tagged, RGB or
     HDR picture, or a line that does not tag BT.709)."""
-    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+    if keeps_source_tags() or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
         return ""
     f = bt709_label_filter(meta)
     return f + "," if f else ""
@@ -813,7 +820,7 @@ def range_chain(meta: Optional[Dict[str, Any]], line_meta: Optional[Dict[str, An
     takes after its matrix_chain()/label_chain() ("<filter>," -- limited_range_filter), or "" (a
     limited, RGB or HDR picture, or a line that does not tag BT.709). Every SDR picture such a
     tool mixes is then limited range, whatever each one was: the filters mix samples, not colours."""
-    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+    if keeps_source_tags() or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
         return ""
     f = limited_range_filter(meta)
     return f + "," if f else ""
@@ -835,7 +842,12 @@ def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva
     is encoded through video_args(line_meta): "," + the conversion to BT.709 YUV to end that chain
     with (rgb_to_bt709_filter), or "" when the line does not tag BT.709 (the lines matrix_chain()
     leaves alone). Without it the graph's own RGB-to-YUV step used FFmpeg's BT.601 default."""
-    if STATE.codec == "prores" or ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"):
+    v = (line_meta or {}).get("video") or {}
+    if STATE.alpha_line is not None and v.get("color_space") == "bt709" and not v.get("bt2020_or_hdr"):
+        # an alpha line keeps the source's tags: on a BT.709-tagged picture an RGB layer is made
+        # BT.709 too (FFmpeg 6.1's own conversion is BT.601), in 4:4:4 with its alpha plane
+        return "," + rgb_to_bt709_filter("yuva444p")
+    if keeps_source_tags() or v.get("bt2020_or_hdr"):
         return ""
     return "," + rgb_to_bt709_filter(pix_fmt)
 
@@ -843,7 +855,7 @@ def rgb_chain_to_bt709(line_meta: Optional[Dict[str, Any]], pix_fmt: str = "yuva
 def draws_chroma(colours: Sequence[Any], line_meta: Optional[Dict[str, Any]]) -> bool:
     """True when one of `colours` has chroma (is_neutral_color) and the line video_args(line_meta)
     tags the output BT.709 -- when a drawn colour needs drawn_chain() at all."""
-    return (not all(is_neutral_color(c) for c in colours if c is not None) and STATE.codec != "prores"
+    return (not all(is_neutral_color(c) for c in colours if c is not None) and not keeps_source_tags()
             and not ((line_meta or {}).get("video") or {}).get("bt2020_or_hdr"))
 
 
@@ -1220,25 +1232,128 @@ def _grid_score(onset_times: "Sequence[float]", strength_at: "Dict[int, float]",
     return total
 
 
+BEAT_ZERO_TOL_S = 0.01      # a fitted grid point this little before 0 s is the beat at 0.0
+BEAT_REFINE_TOL_NATS = 1.0  # onset refinement: the latest time within this of the best log ratio
+
+
+def refine_onset_times(onset_times: "Sequence[float]", step_s: float, pcm: "Sequence[float]",
+                       rate: int) -> "List[float]":
+    """Each envelope-step onset time placed at the sample where the sound starts. Pure.
+
+    An onset picked on the step_s envelope is only known to the step: it is the start of the block
+    the level rose in, so a click is reported up to one step early (5 ms on average at 10 ms).
+    Around each one, over [t - step, t + 2 step], every candidate time c is scored by
+    log(energy of [c, c + step]) - log(energy of [c - step, c]) -- the rise from the step before c
+    to the step after it, which is largest where the sound starts. Ahead of a hit out of digital
+    silence that score is flat (the window before is silent wherever it ends), so the LATEST
+    candidate within BEAT_REFINE_TOL_NATS of the best is taken: past the start, the window before
+    fills with the hit's own attack and the score falls off at once. Candidates are 0.25 ms apart.
+    A time the PCM does not cover is returned unchanged.
+    """
+    rate = int(rate)
+    w = max(1, int(round(step_s * rate)))
+    hop = max(1, int(round(rate * 0.00025)))
+    n = len(pcm)
+    out: "List[float]" = []
+    for t in onset_times:
+        centre = int(round(t * rate))
+        lo, hi = centre - w, centre + 2 * w
+        if lo - w < 0 or hi + w > n:
+            out.append(t)
+            continue
+        base = lo - w
+        prefix = [0.0]
+        acc = 0.0
+        for x in pcm[base:hi + w + 1]:
+            acc += x * x
+            prefix.append(acc)
+        scored = []
+        for c in range(lo, hi + 1, hop):
+            k = c - base
+            before = (prefix[k] - prefix[k - w]) / w
+            after = (prefix[k + w] - prefix[k]) / w
+            scored.append((math.log(after + 1e-12) - math.log(before + 1e-12), c))
+        best = max(sc for sc, _ in scored)
+        c_best = max(c for sc, c in scored if sc >= best - BEAT_REFINE_TOL_NATS)
+        out.append(c_best / rate)
+    return out
+
+
+def _refine_grid(onset_times: "Sequence[float]", strengths: "Sequence[float]", interval: float,
+                 phase: float, lo_bpm: float, hi_bpm: float) -> "tuple":
+    """(interval, phase) refitted by weighted least squares to the onsets that land on the grid.
+
+    Each grid point k is paired with the STRONGEST onset within interval/BEAT_ALIGN_DIVISOR of it
+    (one per point: the weak onsets noise and a hit's own decay leave around a beat must not pull
+    it), and onset_time = phase + k * interval is solved for both unknowns with each pair weighted
+    by its onset strength squared; the pairing is then redone against the refitted grid, until it
+    stops moving (three passes at most). This only sharpens the grid the autocorrelation chose --
+    the tempo cannot leave `bpm_range`, an octave cannot flip (a refit that moves the interval by
+    more than interval/BEAT_ALIGN_DIVISOR is discarded), and fewer than four paired grid points
+    keep the original: the fit needs evidence, and an onset-free stretch gives it none.
+    Returns phase in [0, interval).
+    """
+    iv, ph = float(interval), float(phase)
+    for _ in range(3):
+        tol = iv / BEAT_ALIGN_DIVISOR
+        best: "Dict[int, tuple]" = {}
+        for t, st in zip(onset_times, strengths):
+            k = round((t - ph) / iv)
+            if abs(t - (ph + k * iv)) <= tol and (k not in best or st > best[k][1]):
+                best[k] = (t, st)
+        pairs = [(k, t, max(st, 1e-9) ** 2) for k, (t, st) in best.items()]
+        if len(pairs) < 4:
+            break
+        sw = sum(w for _, _, w in pairs)
+        mk = sum(w * k for k, _, w in pairs) / sw
+        mt = sum(w * t for _, t, w in pairs) / sw
+        sxx = sum(w * (k - mk) ** 2 for k, _, w in pairs)
+        if sxx <= 0:
+            break
+        new_iv = sum(w * (k - mk) * (t - mt) for k, t, w in pairs) / sxx
+        if not (60.0 / hi_bpm <= new_iv <= 60.0 / lo_bpm) or abs(new_iv - interval) > interval / BEAT_ALIGN_DIVISOR:
+            break
+        new_ph = mt - new_iv * mk
+        moved = abs(new_iv - iv) < 1e-9 and abs(new_ph - ph) < 1e-7
+        iv, ph = new_iv, new_ph
+        if moved:
+            break
+    return iv, ph % iv
+
+
 def beat_grid(envelope: "Sequence[float]", step_s: float, *,
               bpm_range: "Sequence[float]" = (60, 200),
               min_confidence: float = BEAT_MIN_CONFIDENCE,
-              duration: "Optional[float]" = None) -> "Dict[str, Any]":
+              duration: "Optional[float]" = None,
+              pcm: "Optional[Sequence[float]]" = None,
+              pcm_rate: "Optional[int]" = None) -> "Dict[str, Any]":
     """A beat grid from an RMS envelope. Pure: numbers in, a dict out -- no ffmpeg, no I/O.
 
     Returns {"beats": [t, ...], "tempo_bpm": float|None, "interval": float|None,
              "confidence": 0..1, "onsets": [t, ...], "phase": float,
              "supported": int, "unsupported": int, "usable": bool,
-             "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo, hi]}
+             "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo, hi],
+             "onset_refinement": "pcm-window-ratio" | None}
+
+    `step_s` must be the envelope's real step (block samples / rate), not the one asked for:
+    every time below is index * step_s. `pcm` and `pcm_rate`, when given, are the samples the
+    envelope was built from; each onset is then placed on them (refine_onset_times) instead of at
+    the start of its envelope block.
 
     The method, in full, so a report can quote it:
       1. onset strength = half-wave-rectified first difference of log(env + 1e-9);
-      2. onsets = local maxima above median + 1.5 * MAD over a +/-1 s window, 60 ms refractory;
+      2. onsets = local maxima above median + 1.5 * MAD over a +/-1 s window, 60 ms refractory,
+         each placed to 0.25 ms on `pcm` when it is given;
       3. tempo = the best autocorrelation lag of the onset signal inside `bpm_range`, with its
          half and double checked and the one whose onsets align better preferred (octave
          disambiguation: 60, 120 and 240 BPM all autocorrelate on a 120 BPM track);
       4. phase = the offset in [0, interval) at which the grid catches the most onset strength;
-      5. beats = phase + n * interval across the duration. A grid must be regular, so a grid
+         then interval and phase are refitted by least squares to the onsets within interval/8 of
+         the grid (_refine_grid), so the tempo is not rounded to a whole number of envelope steps
+         (until 3.2.0, at 10 ms, 90 BPM was measured as 0.67 s and the grid drifted 40-90 ms off the
+         music over 30 s);
+      5. beats = phase + n * interval across the duration (a point within BEAT_ZERO_TOL_S, 10 ms,
+         before 0 s is reported at 0.0; one further before is not reported). A grid must be regular, so a grid
          point with no measured onset within interval/4 is still reported -- and counted in
          `unsupported`, so a caller can see how much of the grid the audio actually supports.
          `supported_beats` is the subset that a measured onset does support: it is what a tool
@@ -1262,6 +1377,7 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         "confidence": 0.0, "onsets": [],
         "phase": 0.0, "supported": 0, "unsupported": 0, "usable": False,
         "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo_bpm, hi_bpm],
+        "onset_refinement": None,
     }
     if len(env) < 4 or step_s <= 0:
         return out
@@ -1272,6 +1388,10 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         return out
     idx = _pick_onsets(strength, step_s)
     onset_times = [i * step_s for i in idx]
+    if pcm and pcm_rate:
+        # the PCM the envelope came from places each onset to the sample (refine_onset_times)
+        onset_times = refine_onset_times(onset_times, step_s, pcm, int(pcm_rate))
+        out["onset_refinement"] = "pcm-window-ratio"
     out["onsets"] = [round(t, 4) for t in onset_times]
     if len(idx) < 2:
         return out
@@ -1312,11 +1432,29 @@ def beat_grid(envelope: "Sequence[float]", step_s: float, *,
         if alt_score > base_score * BEAT_OCTAVE_MARGIN:
             interval, phase, base_score = alt, alt_phase, alt_score
 
+    # The autocorrelation lag is a whole number of envelope steps, so the interval it gives is the
+    # true one rounded to step_s: 90 BPM (0.6667 s) comes out as 0.67 s at 10 ms, 3.3 ms per beat
+    # that a phase+n*interval grid accumulates to tens of ms within a bar or two of either end
+    # (40-90 ms over 30 s). Refit interval and phase to the onsets themselves (_refine_grid).
+    interval, phase = _refine_grid(onset_times, [strength[j] for j in idx], interval, phase,
+                                   lo_bpm, hi_bpm)
+
     beats = []
-    t = phase
-    while t <= total_s + 1e-9:
-        beats.append(round(t, 4))
-        t += interval
+    # The first grid point at or after 0, where "at" allows BEAT_ZERO_TOL_S (one 10 ms envelope
+    # step, the accuracy the grid had before the refit): a track that starts on the beat has no
+    # measurable onset at 0 (there is no step before it), so its phase is fitted from the later
+    # beats and lands a few ms either side of 0 -- that is the beat at 0.0, not a dropped one. A
+    # point further before 0 is not moved there: 0.0 would then be a time the grid does not mark
+    # (a 120 BPM grid with phase 0.46 has its point at -0.04 s), and an onset at 0.08 s would make
+    # it a "supported" snap target. Indexing by n instead of adding the interval up keeps the
+    # float error of a long file out of the last beats.
+    n = -1 if phase - interval >= -BEAT_ZERO_TOL_S else 0
+    while True:
+        t = phase + n * interval
+        if t > total_s + 1e-9:
+            break
+        beats.append(round(max(0.0, t), 4))
+        n += 1
     support_tol = interval / BEAT_SUPPORT_DIVISOR
     supported_beats = [b for b in beats
                        if any(abs(b - o) <= support_tol for o in onset_times)]

package/scripts/_common/probe.py

@@ -478,25 +478,35 @@ def _bit_depth(pix_fmt: Optional[str]) -> int:
     return n if 8 <= n <= 16 else 8
 
 
-def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
-    """Video keyframe timestamps within +-window seconds of t, ascending. Read with
-    -read_intervals so a long file is not scanned end to end; empty when ffprobe cannot say."""
-    ffprobe = require_tool("ffprobe")
-    lo = max(0.0, t - window)
-    proc = run([ffprobe, "-v", "error", "-select_streams", "v:0", "-skip_frame", "nokey",
-                "-read_intervals", f"{lo:.3f}%{t + window:.3f}", "-show_entries", "frame=pts_time",
+def keyframe_times(path: str, lo: float, hi: float, stream: str = "v:0") -> Optional[List[float]]:
+    """Keyframe timestamps of `stream` read from lo to hi seconds (file time), ascending and as
+    ffprobe prints them (microseconds). Read with -read_intervals so a long file is not scanned end
+    to end; the read starts at the keyframe at or before lo, so the first may lie before it. None
+    when ffprobe fails (unmeasured, not "no keyframes")."""
+    # an interval's end is exclusive (6.1: a keyframe at exactly hi is not read), so read a
+    # little past it and drop what lies beyond hi
+    proc = run([require_tool("ffprobe"), "-v", "error", "-select_streams", stream, "-skip_frame", "nokey",
+                "-read_intervals", f"{max(0.0, lo):.6f}%{hi + 0.01:.6f}", "-show_entries", "frame=pts_time",
                 "-of", "csv=p=0", path], quiet=True, check=False)
     if proc.returncode != 0:
-        return []
+        return None
     out: List[float] = []
     for line in proc.stdout.splitlines():
         try:
-            out.append(round(float(line.strip().rstrip(",")), 3))
+            k = float(line.strip().rstrip(","))
         except ValueError:
             continue
+        if k <= hi + 1e-6:
+            out.append(k)
     return sorted(set(out))
 
 
+def keyframes_near(path: str, t: float, window: float = 5.0) -> List[float]:
+    """Video keyframe timestamps within +-window seconds of t (to the ms), ascending; empty when
+    ffprobe cannot say (cut.py's best-effort hints; probe.py --keyframes-near uses keyframe_times)."""
+    return sorted(set(round(k, 3) for k in keyframe_times(path, t - window, t + window) or []))
+
+
 # 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
@@ -609,6 +619,162 @@ def measured_level_dbfs(path: str, seconds: Optional[float] = 120.0,
     return {"mean_dbfs": float(m_mean.group(1)), "peak_dbfs": float(m_max.group(1))}
 
 
+# Legal signal range of limited-range Y'CbCr (check.py --levels, color.py --legalize). Each standard
+# is stated in percent of the nominal swing, so the code limits follow from the bit depth: 0 % luma is
+# code 16 << (depth - 8), 100 % is 235 << (depth - 8); chroma's nominal swing is 16..240 (scaled the
+# same way) around the midpoint. A sample is legal when its code lies inside [lo, hi] inclusive.
+#   bt709     ITU-R BT.709 nominal range: luma 0..100 %, chroma 16..240 (8-bit) -- no excursion.
+#   ebu-r103  EBU R 103 tolerance: luma -1 %..103 %, RGB components -5 %..105 %. Chroma is held to the
+#             widest Cb/Cr an RGB triple inside -5 %..105 % can produce (|C| <= 0.55 of the RGB span,
+#             i.e. 8-bit 5..251); RGB gamut itself is not measured here (a per-plane Y'CbCr count).
+LEGAL_RANGES: Dict[str, Dict[str, Any]] = {
+    "bt709": {"luma_pct": (0.0, 100.0), "chroma_half_swing": 0.5,
+              "reference": "ITU-R BT.709 nominal range: luma 16-235, chroma 16-240 (8-bit; 10-bit 64-940 / 64-960)"},
+    "ebu-r103": {"luma_pct": (-1.0, 103.0), "chroma_half_swing": 0.55,
+                 "reference": "EBU R 103 tolerance: luma -1 %..103 % (8-bit 14-241), chroma as far as RGB -5 %..105 % "
+                              "reaches (8-bit 5-251)"},
+}
+LEGAL_RANGE_CHOICES = sorted(LEGAL_RANGES)
+
+
+def legal_limits(standard: str, bit_depth: int = 8) -> Dict[str, Tuple[int, int]]:
+    """{"y": (lo, hi), "c": (lo, hi)}: the inclusive legal code range of a limited-range sample at
+    `bit_depth`. A limit that falls between two codes is rounded inward (the code past it is out)."""
+    spec = LEGAL_RANGES[standard]
+    scale = 1 << (max(8, int(bit_depth)) - 8)
+    black, white = 16 * scale, 235 * scale
+    span = white - black
+    p_lo, p_hi = spec["luma_pct"]
+    y = (math.ceil(black + span * p_lo / 100.0 - 1e-9), math.floor(white + span * (p_hi - 100.0) / 100.0 + 1e-9))
+    mid, cspan = 128 * scale, 224 * scale
+    half = spec["chroma_half_swing"] * cspan
+    c = (max(0, math.ceil(mid - half - 1e-9)), min((256 * scale) - 1, math.floor(mid + half + 1e-9)))
+    return {"y": y, "c": c}
+
+
+_COMPONENT_DEPTHS: Dict[str, int] = {}
+
+
+def component_depth(pix_fmt: Optional[str]) -> int:
+    """Bits per luma sample of `pix_fmt`, from ffmpeg's own pixel-format table (`-pix_fmts`,
+    BIT_DEPTHS column): the depth the planes really hold, which the name does not always say --
+    nv12 is 8-bit 4:2:0 (the 12 is bits per pixel), p010le is 10-bit. Falls back to _bit_depth()
+    when ffmpeg does not list the format."""
+    name = str(pix_fmt or "")
+    if not _COMPONENT_DEPTHS:
+        proc = run_analysis([require_tool("ffmpeg"), "-hide_banner", "-pix_fmts"], check=False)
+        for line in (proc.stdout or "").splitlines():
+            cols = line.split()
+            if len(cols) == 5 and re.fullmatch(r"\d+(?:-\d+)*", cols[4]):
+                _COMPONENT_DEPTHS[cols[1]] = int(cols[4].split("-")[0])
+    return _COMPONENT_DEPTHS.get(name) or _bit_depth(name)
+
+
+def _metadata_frames(text: str, keys: Optional[frozenset] = None) -> List[Tuple[float, Dict[str, float]]]:
+    """metadata=print's output: one (pts_time, {key: value}) per `frame:` block, signalstats keys only
+    (only those in `keys` when given: signalstats prints ~25 per frame and an hour is 100k frames)."""
+    frames: List[Tuple[float, Dict[str, float]]] = []
+    for line in text.splitlines():
+        if line.startswith("frame:"):
+            m = re.search(r"pts_time:\s*(-?[0-9.]+|nan)", line)
+            t = float(m.group(1)) if m and m.group(1) != "nan" else float("nan")
+            frames.append((t, {}))
+        elif "lavfi.signalstats." in line and "=" in line and frames:
+            key, val = line.split("lavfi.signalstats.", 1)[1].split("=", 1)
+            key = key.strip()
+            if keys is not None and key not in keys:
+                continue
+            try:
+                frames[-1][1][key] = float(val)
+            except ValueError:
+                pass
+    return frames
+
+
+# the signalstats keys measure_signal_range reads: the frame's own extremes and BRNG, and the mask's means
+_OWN_KEYS = frozenset({"BRNG", "YMIN", "YMAX", "UMIN", "UMAX", "VMIN", "VMAX"})
+_MASK_KEYS = frozenset({"YAVG", "UAVG", "VAVG"})
+
+
+def measure_signal_range(path: str, standard: str, window: float = 10.0,
+                         bit_depth: Optional[int] = None, pix_fmt: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """Share of luma and chroma samples outside `standard`'s legal range, per clip and per `window`
+    seconds, plus min/max Y/U/V, from one decode of every frame of the first video stream.
+
+    The count is exact, not sampled from a histogram: each plane goes through lutyuv, which maps an
+    out-of-range code to the depth's top code (255 at 8 bits) and every other code to 0, and
+    signalstats' mean of that mask is the top code x the out-of-range share of that plane in that frame. Chroma planes are
+    counted at their own (subsampled) resolution, so "chroma" is the share of Cb and Cr samples. A
+    second signalstats ahead of the mask reads the frame's own MIN/MAX and BRNG (the share of pixels
+    with any component outside the BT.601/709 nominal range, signalstats' fixed limits). Every frame
+    holds the same number of samples, so a clip's share is the mean of its frames' shares.
+
+    The limits and the mask use `bit_depth`, or else the depth of `pix_fmt`'s planes
+    (component_depth(): nv12 is 8-bit, not 12). None when the measurement is not whole: nothing
+    decoded, ffmpeg failed part-way (a share from the frames read before the failure would grade a
+    file nobody measured to the end), or the two passes counted different frames."""
+    if standard not in LEGAL_RANGES:
+        die(f"unknown legal range {standard!r}; choose from {', '.join(LEGAL_RANGE_CHOICES)}")
+    import tempfile
+    from _common.decision import escape_filter_path
+    ffmpeg = require_tool("ffmpeg")
+    depth = int(bit_depth or component_depth(pix_fmt))
+    lim = legal_limits(standard, depth)
+    (ylo, yhi), (clo, chi) = lim["y"], lim["c"]
+    top = (1 << depth) - 1  # a literal: lutyuv's own maxval is 235 for limited-range luma, 240 for chroma
+    out = str(top) + "*(lt(val\\,{lo})+gt(val\\,{hi}))"
+    mask = (f"lutyuv=y='{out.format(lo=ylo, hi=yhi)}':u='{out.format(lo=clo, hi=chi)}'"
+            f":v='{out.format(lo=clo, hi=chi)}'")
+    with tempfile.TemporaryDirectory(prefix="ffskill_levels_") as tmp:
+        stats_file = os.path.join(tmp, "stats.txt")
+        vf = (f"signalstats=stat=brng,metadata=print:file={escape_filter_path(stats_file)},"
+              f"{mask},signalstats,metadata=print:file=-")
+        cmd = [ffmpeg, "-hide_banner", "-nostdin", "-i", path, "-map", "0:v:0", "-an", "-sn", "-dn", "-vf", vf, "-f", "null", "-"]
+        proc = run_analysis(cmd, check=False, record=True)
+        try:
+            with open(stats_file, encoding="utf-8", errors="replace") as f:
+                own = _metadata_frames(f.read(), _OWN_KEYS)
+        except OSError:
+            own = []
+    masks = _metadata_frames(proc.stdout or "", _MASK_KEYS)
+    if proc.returncode != 0 or not own or len(own) != len(masks):
+        return None
+    t0 = next((t for t, _ in own if t == t), 0.0)
+    rows: List[Dict[str, Any]] = []
+    for (t, s), (_, m) in zip(own, masks, strict=True):
+        y, u, v = (m.get(k, 0.0) / top * 100.0 for k in ("YAVG", "UAVG", "VAVG"))
+        rows.append({"t": (t - t0) if t == t else None, "y": y, "u": u, "v": v, "brng": s.get("BRNG", 0.0) * 100.0,
+                     "min": {k: s.get(k.upper() + "MIN") for k in "yuv"}, "max": {k: s.get(k.upper() + "MAX") for k in "yuv"}})
+
+    def summary(frames: List[Dict[str, Any]]) -> Dict[str, Any]:
+        k = len(frames)
+        share = {p: sum(f[p] for f in frames) / k for p in ("y", "u", "v", "brng")}
+        worst = max(frames, key=lambda f: max(f["y"], (f["u"] + f["v"]) / 2))
+        def ext(which: str, fn: Any) -> Dict[str, Any]:
+            vals = {p: [f[which][p] for f in frames if f[which][p] is not None] for p in "yuv"}
+            return {p: (int(fn(v)) if v else None) for p, v in vals.items()}
+        return {"frames": k,
+                "out_of_range_pct": {"y": round(share["y"], 4), "u": round(share["u"], 4), "v": round(share["v"], 4),
+                                     "chroma": round((share["u"] + share["v"]) / 2, 4)},
+                "brng_pct": round(share["brng"], 4),
+                "worst_frame": {"time": None if worst["t"] is None else round(worst["t"], 3),
+                                "y_pct": round(worst["y"], 4), "chroma_pct": round((worst["u"] + worst["v"]) / 2, 4)},
+                "min": ext("min", min), "max": ext("max", max)}
+
+    doc = {"standard": standard, "reference": LEGAL_RANGES[standard]["reference"], "bit_depth": depth,
+           "legal": {"y": list(lim["y"]), "c": list(lim["c"])}, "window_seconds": window, **summary(rows)}
+    windows: List[Dict[str, Any]] = []
+    if window and window > 0:
+        buckets: Dict[int, List[Dict[str, Any]]] = {}
+        for i, f in enumerate(rows):
+            buckets.setdefault(int((f["t"] if f["t"] is not None else i) // window), []).append(f)
+        for idx in sorted(buckets):
+            w = summary(buckets[idx])
+            windows.append({"start": round(idx * window, 3), "end": round((idx + 1) * window, 3), **w})
+    doc["windows"] = windows
+    return doc
+
+
 def analyze_levels(path: str, seconds: float = 20.0) -> Dict[str, Any]:
     """Sample luma/saturation statistics (signalstats) and guess whether the picture is Log-encoded.
 

package/scripts/_common/runner.py

@@ -329,7 +329,7 @@ class Context:
     makes it obvious what run()/emit() depend on and lets tests reset it with ``STATE.reset()``.
     """
 
-    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec",
+    __slots__ = ("dry_run", "json", "json_brief", "progress", "fast", "duration_hint", "commands", "timeout", "overwrite", "written", "preexisting", "plan", "plan_written", "plan_inputs", "codec", "alpha_line",
                  "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", "delivered")
@@ -359,6 +359,7 @@ class Context:
         self.plan_written = False                    # write_plan() ran (emit or the exit hook), so the hook does not write twice
         self.plan_inputs: List[str] = []             # side inputs (srt/ass/lut/font files) a tool named through escape_filter_path
         self.codec: Optional[str] = None             # --codec: encoder for the re-encode (None = x264 for SDR, x265 for HDR)
+        self.alpha_line: Optional[str] = None        # --keep-alpha / --transparent: the alpha line written (_common.alpha.ALPHA_CODECS)
         self.hw = False                              # --hw / $FFMPEG_SKILL_HW: VideoToolbox encoders where they apply
         self.hw_source: Optional[str] = None         # "flag" (--hw/--no-hw given) or "env" (FFMPEG_SKILL_HW), None = off by default
         self.hw_notes: List[str] = []                # why an encode stayed on (or fell back to) the CPU, for the result document
@@ -2025,7 +2026,7 @@ def _read_ff_list(flag: str, pattern: str) -> set:
         why = f"{tool} {flag} could not run: {exc}"
     if why:
         _LIST_ERRORS[flag] = why
-        what = {"-encoders": "encoder", "-bsfs": "bitstream filter"}.get(flag, "filter")
+        what = {"-encoders": "encoder", "-decoders": "decoder", "-bsfs": "bitstream filter"}.get(flag, "filter")
         warn(f"could not read this ffmpeg build's {what} list ({why}); nothing that needs it can be confirmed, which is not the same as the build lacking it",
              "ffmpeg_list_unreadable", list=flag.lstrip("-"), tool=tool, error=why)
     return names