ffmpeg-skill 2.5.1 → 2.7.0

package/scripts/_common/decision.py

@@ -16,7 +16,7 @@ from pathlib import Path
 from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.color import bt709_tag_args, _sdr_bt709
 from _common.emit import die
-from _common.runner import CODECS, STATE, ffmpeg_encoders
+from _common.runner import CODECS, STATE, ffmpeg_encoders, ffmpeg_version, hw_platform_reason
 
 
 def pad_filters(out_w: int, out_h: int, fill: str, color: str, blur: int, darken: float = 0.0) -> str:
@@ -277,7 +277,126 @@ def cfr_args(meta: Optional[Dict[str, Any]], fps: Optional[float] = None) -> Lis
     return ["-fps_mode", "cfr", "-r", f"{rate:g}"]
 
 
+# ------------------------------------------------------- VideoToolbox (--hw)
+#
+# CRF -> VideoToolbox -q:v (1-100, higher = better): at each CRF the highest -q:v whose SSIM matched
+# the CPU line's (x264/x265 medium) across the clips of tests/bench_vt.py -- synthetic CG, fractal
+# and grain plus iPhone 17 Pro 1080p (M3, FFmpeg 9.0.2), so a GPU encode never measures below the
+# CPU one. HDR has its own curve: its CPU line is x265 Main10 at CRF+2, and the Main10 VideoToolbox
+# line needs ~11-15 less -q:v for that SSIM (the SDR curve wrote HLG phone footage at 6-8x x265's
+# bytes). Matched quality costs 1.1-2.9x the bytes of x264/x265 on SDR and 1.9-3.5x on HDR --
+# which is why --hw is opt-in and delivery presets stay on the CPU (docs/design-decisions.md).
+
+
+def vt_quality(codec: str, crf: int, hdr: bool = False) -> int:
+    base, slope = (63.0, 1.6) if hdr else (75.0, 2.2) if codec == "h264" else (78.0, 2.0)
+    return max(1, min(100, int(round(base - slope * (crf - 18)))))
+
+
+def _vt_bt709(codec: str) -> List[str]:
+    """BT.709 tags for a VideoToolbox SDR encode. From FFmpeg 7.1 the -colorspace output options
+    drive a real matrix conversion on an untagged source (see bt709_tag_args), and VideoToolbox has
+    no -x264-params VUI route; a bitstream filter writes the VUI after encoding, which the filter
+    graph never sees (measured: 49.9 dB PSNR tag-neutral vs 23.8 dB through the output options).
+    It is used on every version, not only >= 7.1: it is tag-only everywhere, and a git build of
+    7.1 reads as (7, 0) from its libavutil major, which would otherwise take the converting path."""
+    return ["-bsf:v", f"{codec}_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1"]
+
+
+def _vt_args(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: bool) -> Optional[List[str]]:
+    """VideoToolbox encoder options for `codec`, or None (with a note in STATE.hw_notes) when the
+    request stays on the CPU: no VideoToolbox encoder for the codec, this machine cannot, or the
+    ffmpeg build lacks it."""
+    name = {"h264": "h264_videotoolbox", "hevc": "hevc_videotoolbox", "prores": "prores_videotoolbox"}.get(codec)
+    reason = None if name else f"no VideoToolbox encoder for {codec}"
+    reason = reason or hw_platform_reason()
+    if not reason and name not in ffmpeg_encoders():
+        reason = f"this ffmpeg build has no {name}"
+    if reason:
+        note = f"{reason}; encoded on the CPU"
+        if note not in STATE.hw_notes:
+            STATE.hw_notes.append(note)
+        return None
+    v = (meta or {}).get("video") or {}
+    hdr = bool(v.get("bt2020_or_hdr"))
+    hdr_tags = ["-colorspace", v.get("color_space") or "bt2020nc", "-color_primaries", v.get("color_primaries") or "bt2020",
+                "-color_trc", v.get("color_transfer") or "arib-std-b67"]
+    if codec == "prores":
+        return ["-c:v", name, "-profile:v", "hq", "-pix_fmt", "p210le"] + (hdr_tags if hdr else [])
+    # The HDR curve was fitted on the Main10 HEVC line; an 8-bit H.264 line (an export preset on
+    # an HDR source) replaces x264 at the same CRF and keeps the H.264 curve.
+    q = str(vt_quality(codec, crf, hdr and codec == "hevc"))
+    if codec == "h264":
+        return ["-c:v", name, "-q:v", q, "-profile:v", "high", "-pix_fmt", "yuv420p", "-movflags", "+faststart"] + \
+            (_vt_bt709("h264") if keep_bt709 else [])
+    if hdr:
+        # Measured on FFmpeg 9.0: HDR10 mastering-display and content-light side data carry through
+        # hevc_videotoolbox exactly as through libx265 (test_hw_hdr10_side_data_survives).
+        return ["-c:v", name, "-q:v", q, "-profile:v", "main10", "-pix_fmt", "p010le", "-tag:v", "hvc1"] + hdr_tags + ["-movflags", "+faststart"]
+    return ["-c:v", name, "-q:v", q, "-pix_fmt", "yuv420p", "-tag:v", "hvc1", "-movflags", "+faststart"] + \
+        (_vt_bt709("hevc") if keep_bt709 else [])
+
+
+def _maybe_hw(codec: str, crf: int, meta: Optional[Dict[str, Any]], keep_bt709: bool, cpu: List[str]) -> List[str]:
+    """`cpu` unchanged unless --hw / $FFMPEG_SKILL_HW is on and VideoToolbox can take `codec`; the
+    swap is remembered so run() can put the CPU line back if the GPU refuses the job."""
+    if not STATE.hw:
+        return cpu
+    vt = _vt_args(codec, crf, meta, keep_bt709)
+    if vt is None:
+        return cpu
+    # a copy: a caller that edits the returned line in place (export.py strips -movflags) must
+    # not edit the recorded slice with it, or restate_last_swap() never sees the line as built
+    STATE.hw_swaps.append((list(vt), cpu))
+    return vt
+
+
+_CPU_TO_CODEC = {"libx264": "h264", "libx265": "hevc", "prores_ks": "prores"}
+
+
+def hw_preset_video(video: List[str], meta: Optional[Dict[str, Any]], *, bt709: bool) -> List[str]:
+    """export.py's fixed-preset encoder line moved to VideoToolbox (same codec, the preset's -crf
+    mapped to -q:v, its -r kept); unchanged -- with the reason noted -- when that cannot apply.
+
+    `bt709`: whether export.py tags this preset's CPU line BT.709 (every fixed preset but prores,
+    whose master keeps the source's tags). The VideoToolbox line writes the format the CPU preset
+    writes: an h264/hevc preset is 8-bit with BT.709 tags whatever the source (on an HDR source it
+    says so in a note, as without --hw), so it is built as for an SDR source -- not the Main10 HDR
+    line, which would make the GPU file and its CPU fallback different formats."""
+    enc = video[video.index("-c:v") + 1] if "-c:v" in video else None
+    codec = _CPU_TO_CODEC.get(enc or "")
+    if codec is None:
+        return video
+    crf = int(video[video.index("-crf") + 1]) if "-crf" in video else 18
+    vt = _vt_args(codec, crf, meta if codec == "prores" else None, bt709)
+    if vt is None:
+        return video
+    vt = strip_movflags(vt)  # export adds it
+    if "-r" in video:
+        vt += ["-r", video[video.index("-r") + 1]]
+    # the CPU line export would have written: the preset's own options plus the BT.709 tags export
+    # adds to it (only to the CPU line), so a GPU->CPU fallback is tagged exactly like a CPU run
+    STATE.hw_swaps.append((list(vt), list(video) + (bt709_tag_args(enc) if bt709 else [])))
+    return vt
+
+
+def strip_movflags(args: List[str]) -> List[str]:
+    return [a for i, a in enumerate(args) if not (a == "-movflags" or (i and args[i - 1] == "-movflags"))]
+
+
+def restate_last_swap(before: List[str], after: List[str]) -> None:
+    """A caller that edits an encoder line after encoder_args() returned it (export.py strips
+    -movflags) restates the recorded swap, so run()'s GPU->CPU fallback still finds the slice."""
+    if STATE.hw_swaps and STATE.hw_swaps[-1][0] == before:
+        STATE.hw_swaps[-1] = (list(after), strip_movflags(STATE.hw_swaps[-1][1]))
+
+
 def encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> List[str]:
+    """encoder options for `codec` (_cpu_encoder_args), on VideoToolbox when --hw asks and it can."""
+    return _maybe_hw(codec, crf, meta, keep_bt709, _cpu_encoder_args(codec, crf, preset, meta, keep_bt709))
+
+
+def _cpu_encoder_args(codec: str, crf: int, preset: str, meta: Optional[Dict[str, Any]] = None, keep_bt709: bool = True) -> List[str]:
     """The one place that turns (--codec, --quality, --preset, source) into encoder options.
 
     h264 -> x264 8-bit BT.709 (refuses HDR: 8-bit H.264 cannot carry it); hevc -> x265, Main10
@@ -340,7 +459,7 @@ def x264_args(crf: int = 18, preset: str = "medium", keep_bt709: bool = True) ->
     (color.py's --to-sdr path builds its own H.264 line; the flag still has to reach it)."""
     if STATE.codec and STATE.codec != "h264":
         return encoder_args(STATE.codec, crf, preset, None, keep_bt709)
-    return _x264_raw(crf, preset, keep_bt709)
+    return _maybe_hw("h264", crf, None, keep_bt709, _x264_raw(crf, preset, keep_bt709))
 
 
 def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "medium") -> List[str]:
@@ -356,6 +475,10 @@ def video_args(meta: Optional[Dict[str, Any]], crf: int = 18, preset: str = "med
     v = (meta or {}).get("video") or {}
     if not v.get("bt2020_or_hdr"):
         return x264_args(crf, preset)
+    return _maybe_hw("hevc", crf, meta, True, _x265_hdr_default(v, 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"
     trc = v.get("color_transfer") or "arib-std-b67"

package/scripts/_common/emit.py

@@ -9,7 +9,7 @@ import json
 import math
 import os
 import sys
-from typing import Any, Dict, List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence, Tuple
 from _common.runner import Context, ERROR_CODE, ERROR_RETRYABLE, STATE
 
 
@@ -28,6 +28,14 @@ def die(msg: str, code: int = 1, kind: str = "input", *, ctx: "Optional[Context]
     ctx.plan = None  # a failed run plans nothing (the exit hook must not write a plan for it)
     STATE.plan = None  # the hook falls back to STATE when nothing passed a ctx; a failed run plans nothing there either
     sys.stderr.write(f"error: {msg}\n" + (f"hint: {hint}\n" if hint else ""))
+    if kind == "ffmpeg" and "hw" not in extra and (ctx.hw or ctx.hw_stages or ctx.hw_env_ignored):
+        # a tool's own ffmpeg failure (cut.py runs run(check=False) and dies itself; render.py
+        # re-raises a stage's) carries `encoder` and `hw` as run()'s _fail() does: under --hw /
+        # $FFMPEG_SKILL_HW two encoders may have run, and a caller must know whose failure it is
+        enc = extra.get("encoder") or _video_encoders(ctx.commands)[0]
+        if enc and "encoder" not in extra:
+            extra["encoder"] = enc
+        extra["hw"] = hw_report(ctx, enc)
     if ctx.json:
         doc: Dict[str, Any] = {
             "status": "failed", "exit_code": code,
@@ -63,6 +71,138 @@ def _set_current_ctx(ctx: "Context") -> None:
     _CURRENT_CTX = ctx
 
 
+ENV_HW_NOTE = ("VideoToolbox chosen by FFMPEG_SKILL_HW=1 (machine default; ~1.1-3.5x the bytes of x264/x265 "
+               "at matched quality); rerun with --no-hw for a final deliverable")
+ENV_NOT_FOR_DELIVERY_NOTE = ("FFMPEG_SKILL_HW=1 is not applied to export.py's delivery presets (a delivered file is where "
+                             "VideoToolbox's larger files cost most); pass --hw to put this export on the GPU")
+
+
+def _video_encoders(commands: Sequence[str]) -> "Tuple[Optional[str], Optional[str]]":
+    """(the last video encoder the command lines name, or `copy` for a stream copy; that encoder's
+    command line). A later copy (loudness.py after export's encode) keeps the encode before it."""
+    import re as _re
+    enc, line, copied = None, None, False
+    for c in commands:
+        for name in _re.findall(r"(?:^|\s)-(?:c:v|vcodec|codec:v)\s+(\S+)", c):
+            if name == "copy":
+                copied = True
+            else:
+                enc, line = name, c
+        if _re.search(r"(?:^|\s)-(?:c|codec)\s+copy(?:\s|$)", c):
+            copied = True
+    if enc is None and copied:
+        return "copy", None
+    return enc, line
+
+
+def hw_report(ctx: "Context", enc: Optional[str]) -> Dict[str, Any]:
+    """The `hw` object for a run whose last video encoder was `enc` (None: this process recorded
+    no encode -- batch.py, whose stages are child processes). `requested`: VideoToolbox was asked
+    for this run's encodes (by --hw, by $FFMPEG_SKILL_HW where it applies, or for a stage);
+    `source`: flag|env; `used`: the encoder that ran last is VideoToolbox; `fallback`: a job
+    VideoToolbox refused was re-encoded on the CPU, here or in a stage; `notes`: why. Under
+    --dry-run `used` is null and `fallback` false: nothing ran."""
+    stages = list(ctx.hw_stages)
+    requested = bool(ctx.hw) or any(st.get("requested") for st in stages)
+    source = ctx.hw_source if ctx.hw else next((st.get("source") for st in stages if st.get("requested")), None)
+    if not requested and ctx.hw_env_ignored:
+        source = "env"
+    # a stage that reported its source without asking (export.py under the variable: requested
+    # false, source env) still names where the request came from
+    source = source or next((st.get("source") for st in stages if st.get("source")), None)
+    vt = enc is not None and enc.endswith("_videotoolbox")
+    # `used` is what ran; a dry run ran nothing (the planned encoder is `encoder`), so null --
+    # as waveform.py's `silent` is null when nothing was measured
+    used = None if enc is None or ctx.dry_run else vt
+    notes = list(ctx.hw_notes)
+    if vt and source == "env" and not any(n.endswith(ENV_HW_NOTE) for n in notes):
+        # the machine default, not this call, chose the GPU: say what it costs and how to opt out
+        # (once: a stage that ran on it already said so)
+        notes.append(ENV_HW_NOTE)
+    if ctx.hw_env_ignored and enc not in (None, "copy"):
+        notes.append(ENV_NOT_FOR_DELIVERY_NOTE)
+    return {"requested": requested, "source": source, "used": used,
+            "fallback": bool(ctx.hw_fallback) or any(st.get("fallback") for st in stages), "notes": notes}
+
+
+def hw_quality_note(enc: Optional[str], line: Optional[str]) -> Optional[str]:
+    """The `notes` line every VideoToolbox encode carries: its quality is not the CRF encode's."""
+    import re as _re
+    if not enc or not enc.endswith("_videotoolbox"):
+        return None
+    if enc == "prores_videotoolbox":
+        return ("prores_videotoolbox is not prores_ks: the same 422 HQ profile from a different encoder, so size and detail "
+                "differ from the CPU encode; `verified` covers the output's measured properties, not parity with the CPU "
+                "encode; --no-hw for prores_ks")
+    m = _re.search(r"(?:^|\s)-q:v\s+(\d+)", line or "")
+    return (f"{enc}{' -q:v ' + m.group(1) if m else ''} is not CRF-equivalent: --quality (or the preset's CRF) is mapped "
+            "to -q:v by an approximate SSIM fit (docs/design-decisions.md), so size and detail differ from the x264/x265 "
+            "encode (~1.1-3.5x the bytes at matched SSIM); `verified` covers the output's measured properties, not quality "
+            "parity with the CPU encode; --no-hw for the CRF encode")
+
+
+def _encoder_report(ctx: "Context") -> Dict[str, Any]:
+    """`encoder`: the last video encoder this run's ffmpeg commands name (after any GPU->CPU
+    fallback, since run() rewrites the recorded command), `copy` for a stream copy; absent when no
+    command encoded video. `hw` (hw_report): present whenever VideoToolbox was asked for (--hw or
+    $FFMPEG_SKILL_HW, a stage's, or the variable a delivery preset does not take)."""
+    enc, _line = _video_encoders(ctx.commands)
+    out: Dict[str, Any] = {"encoder": enc} if enc else {}
+    if ctx.hw or ctx.hw_stages or ctx.hw_env_ignored:
+        out["hw"] = hw_report(ctx, enc)
+    return out
+
+
+def _hw_notes_for(ctx: "Context") -> List[str]:
+    """Top-level `notes` lines for the GPU encodes this result stands on: this tool's last encode,
+    and (render.py) every stage that ran on VideoToolbox."""
+    enc, line = _video_encoders(ctx.commands)
+    out: List[str] = []
+    for note in [hw_quality_note(enc, line)] + [st.get("quality_note") for st in ctx.hw_stages]:
+        if note and note not in out:
+            out.append(note)
+    return out
+
+
+def absorb_stage_hw(stage: str, doc: Any, ctx: "Optional[Context]" = None) -> None:
+    """render.py runs each stage as a child process: carry the stage's `hw` facts (fell back, and
+    why; ran on VideoToolbox, with its quality note) into this result, which records only the
+    command lines."""
+    ctx = ctx or STATE
+    hw = doc.get("hw") if isinstance(doc, dict) else None
+    if not isinstance(hw, dict):
+        return
+    for n in hw.get("notes") or []:
+        # once: this process may have said it already (waveform.py's own encode), or another stage
+        if n not in ctx.hw_notes and not any(existing.endswith(": " + n) for existing in ctx.hw_notes):
+            ctx.hw_notes.append(f"{stage}: {n}")
+    enc, line = _video_encoders([str(c) for c in (doc.get("commands") or [])])
+    quality = hw_quality_note(enc, line) if hw.get("used") else None
+    ctx.hw_stages.append({"stage": stage, "requested": bool(hw.get("requested")), "source": hw.get("source"),
+                          "used": hw.get("used"), "fallback": bool(hw.get("fallback")), "quality_note": quality})
+
+
+def steps_encoder_report(steps: Sequence["Tuple[str, Any]"]) -> Dict[str, Any]:
+    """batch.py's per-item `encoder`, `hw` and `notes`, from the --json documents of the steps
+    (child processes) that made the item: the last encoder a step ran (a later stream copy keeps
+    the encode before it), and their GPU facts as render.py's result carries its stages'."""
+    ctx = Context()
+    ctx.dry_run = STATE.dry_run
+    enc: Optional[str] = None
+    for name, doc in steps:
+        step_enc = doc.get("encoder") if isinstance(doc, dict) else None
+        if step_enc and (step_enc != "copy" or enc is None):
+            enc = step_enc
+        absorb_stage_hw(name, doc, ctx)
+    out: Dict[str, Any] = {"encoder": enc} if enc else {}
+    if ctx.hw_stages:
+        out["hw"] = hw_report(ctx, enc)
+        quality = [st["quality_note"] for st in ctx.hw_stages if st.get("quality_note")]
+        if quality:
+            out["notes"] = list(dict.fromkeys(quality))
+    return out
+
+
 def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any) -> None:
     """Final stdout line: the output path, or a JSON document with --json.
 
@@ -88,7 +228,11 @@ def emit(output: Optional[str], *, ctx: "Optional[Context]" = None, **extra: Any
             steps.insert(0, {"step": "exists", "ok": True})
         doc["verified"] = not ctx.dry_run and bool(steps) and all(s.get("ok") for s in steps)
         doc["verification"] = steps
+        doc.update(_encoder_report(ctx))
         doc.update(extra)
+        hw_notes = [n for n in _hw_notes_for(ctx) if n not in (doc.get("notes") or [])]
+        if hw_notes:
+            doc["notes"] = list(doc.get("notes") or []) + hw_notes
         if ctx.plan:
             doc["plan"] = write_plan(ctx.plan, output, extra, ctx=ctx)
         print_json(_brief(doc, meta) if ctx.json_brief else doc)