ffmpeg-skill 3.2.2 → 3.3.0

package/scripts/_common/emit.py

@@ -163,6 +163,74 @@ def _report_dropped_hdr10_metadata(meta: Dict[str, Any], ctx: "Context") -> None
         ctx.notes.append(note_line)
 
 
+# source_carry: the items compared, in report order. The first group is content a viewer or
+# listener notices missing and raises the warning; the second is tags, listed but never warned
+# about (every camera file has a creation_time, so a warning for it would fire on every run).
+CARRY_CONTENT = ("subtitles", "chapters", "cover_art", "audio_channels")
+CARRY_TAGS = ("creation_time", "audio_language", "timecode")
+_CARRY_NAMES = {"subtitles": "subtitle track", "chapters": "chapters", "cover_art": "cover picture",
+                "audio_channels": "audio channels"}
+
+
+def source_carry(output: Optional[str], ctx: "Context", extra: Dict[str, Any]) -> "Optional[Dict[str, List[str]]]":
+    """What the first input carried besides its picture and sound, and whether the written file
+    still has it (#401): {"kept": [...], "dropped": [...]}, or None when the source had none of
+    it or the two files are not comparable. Measured on the written file, so the tool, encoder or
+    FFmpeg version that dropped it does not matter. A report, not a check: `verified` is not
+    touched. Not compared: two or more picture or sound sources (which one's items the output
+    should carry is the tool's choice), an output that is not a media file, and items bound to a
+    stream the output does not have at all (a sound-only extract has no subtitle track or
+    timecode to lose; a picture-only output has no audio channels). Audio channels are an item
+    only for a surround source (more than two)."""
+    from .probe import MEDIA_EXT, _STILL_EXT, carry_inventory
+    first = getattr(STATE, "first_input", None)
+    if not first or not output:
+        return None
+    # a tool that reads its own output back (cut.py measures the cut it wrote) probed it as an
+    # input too: that is not a second source
+    own = os.path.realpath(output)
+    if any(len(set(getattr(STATE, name, None) or ()) - {own}) > 1 for name in ("video_inputs", "audio_inputs")):
+        return None
+    ext = os.path.splitext(output)[1].lower()
+    if ext not in MEDIA_EXT or ext in _STILL_EXT:
+        return None  # a still, a contact sheet or an animated GIF holds none of these
+    src, out = carry_inventory(first[0]), carry_inventory(output)
+    if not src or not out or os.path.realpath(first[0]) == os.path.realpath(output):
+        return None
+    kept: List[str] = []
+    dropped: List[str] = []
+    for item in CARRY_CONTENT + CARRY_TAGS:
+        if not src.get(item):
+            continue
+        if item == "audio_channels" and src[item] <= 2:
+            continue  # mono and stereo are what every tool writes; only a surround layout can be folded down
+        if item in ("subtitles", "timecode") and src["has_video"] and not out["has_video"]:
+            continue
+        if item in ("audio_channels", "audio_language") and not out["has_audio"]:
+            continue
+        (kept if out.get(item, 0) >= src[item] else dropped).append(item)
+    if not kept and not dropped:
+        return None
+    said = set()
+    if extra.get("dropped_non_av_streams") or any(w.get("code") == "non_av_streams_dropped" for w in ctx.fallbacks):
+        said.add("subtitles")  # the tool's own field already says the track went
+    loud = [i for i in dropped if i in CARRY_CONTENT and i not in said]
+    if loud:
+        parts = []
+        for i in loud:
+            if i == "audio_channels":
+                parts.append(f"{src[i] - out.get(i, 0)} of its {src[i]} audio channels")
+            else:
+                parts.append("its " + _CARRY_NAMES[i])
+        warn("the source carried " + ", ".join(parts) + " that this output does not have "
+             "(source_carry lists everything kept and dropped)",
+             "source_items_dropped", ctx=ctx, dropped=loud)
+        note_line = ctx.warnings[-1]["message"] if ctx.warnings else None
+        if note_line and note_line not in ctx.notes:
+            ctx.notes.append(note_line)
+    return {"kept": kept, "dropped": dropped}
+
+
 def refuse(kind: str, reason: str, msg: str, *, hint: Optional[str] = None, code: int = 1,
            ctx: "Optional[Context]" = None, extra: "Optional[Dict[str, Any]]" = None, **details: Any) -> "None":
     """die() for a refusal a caller has to act on: `error.reason` is a stable snake_case code for
@@ -710,6 +778,9 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
         meta = verify_output(output)  # dies (status: failed, kind: output) if the artifact is unusable
         _report_dropped_audio_tracks(meta, ctx)
         _report_dropped_hdr10_metadata(meta, ctx)
+        carry = source_carry(output, ctx, extra)
+        if carry and "source_carry" not in extra:
+            extra["source_carry"] = carry
     if ctx.json:
         doc: Dict[str, Any] = {"status": "completed", "output": output, "dry_run": ctx.dry_run, "commands": list(ctx.commands)}
         if meta:

package/scripts/_common/probe.py

@@ -402,9 +402,30 @@ def probe(path: str, role: str = "input") -> Dict[str, Any]:
                              (out.get("video") or {}).get("hdr10_static"))
     if role == "input" and out["timecode"].get("value") and getattr(STATE, "source_timecode", None) is None:
         STATE.source_timecode = (out["timecode"]["value"], duration)
+    # what a source carries besides its picture and sound, for emit()'s source_carry comparison:
+    # kept beside the probe, not in it, so no probe document changes
+    lang = (audio.get("tags") or {}).get("language") if audio else None
+    _CARRY[os.path.realpath(path)] = {
+        "subtitles": len(subs),
+        "chapters": len(raw.get("chapters") or []),
+        "cover_art": sum(1 for s in streams if s.get("codec_type") == "video" and s.get("disposition", {}).get("attached_pic", 0)),
+        "creation_time": 1 if any(k.lower() == "creation_time" for k in (fmt.get("tags") or {})) else 0,
+        "audio_language": 1 if lang and lang.lower() != "und" else 0,
+        "timecode": 1 if out["timecode"].get("value") else 0,
+        "audio_channels": (_to_int(audio.get("channels")) or 0) if audio else 0,
+        "has_video": bool(video), "has_audio": bool(audio),
+    }
     return out
 
 
+_CARRY: Dict[str, Dict[str, Any]] = {}
+
+
+def carry_inventory(path: str) -> "Optional[Dict[str, Any]]":
+    """The carry-over items probe() last read off `path` (see emit()'s source_carry), or None."""
+    return _CARRY.get(os.path.realpath(path)) if path else None
+
+
 def _hdr10_static(ffprobe: str, path: str, stream: Dict[str, Any]) -> "Optional[Dict[str, Any]]":
     """A PQ stream's mastering display and content light level, from the stream (an mdcv/clli box,
     a Matroska colour element) or else its first frame (the HEVC SEI / AV1 metadata OBU): one
@@ -478,25 +499,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 +640,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
@@ -1066,9 +1067,14 @@ class _OutputLock:
 def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
     """An odd-sized source (641x359 screen captures, some 4:4:4 masters) fails every yuv420p
     encode with "width/height not divisible by 2" (sweep F8, 15 tools). Return the same command
-    with an even-dimension scale prepended to its -vf chain (or a new -vf when the command had
+    with an even-dimension scale appended to its -vf chain (or a new -vf when the command had
     none); None when the failure is something else or the graph is a -filter_complex the
-    caller has to fix itself."""
+    caller has to fix itself.
+
+    Appended, not prepended: what the encoder refuses is the frame the chain hands it, and a
+    chain can make an even frame odd again (squaring non-square pixels to 636x1401, a conversion
+    that restores the source's own size). Through 3.2.3 the scale went first, so caption.py on an
+    odd-sized clip retried and failed the same way (#438)."""
     if "not divisible by 2" not in stderr or EVEN_SCALE in cmd or any(EVEN_SCALE in a for a in cmd):
         return None
     if "-filter_complex" in cmd:
@@ -1076,7 +1082,7 @@ def _odd_dimension_retry(cmd: List[str], stderr: str) -> Optional[List[str]]:
     new = list(cmd)
     if "-vf" in new:
         i = new.index("-vf") + 1
-        new[i] = EVEN_SCALE + "," + new[i]
+        new[i] = new[i] + "," + EVEN_SCALE
         return new
     if "-c:v" in new and new[new.index("-c:v") + 1] == "copy":
         return None
@@ -2025,7 +2031,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