ffmpeg-skill 1.13.0 → 1.15.0

package/scripts/_contract.py

@@ -79,7 +79,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                 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"},
-                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur"}],
+                                                     {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
+                                                     {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"}],
                 video_required=True, audio_only=False, visual=True, verify=["probe", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "crop": dict(role="execution", inputs=["video asset"], outputs=["video artifact cropped to the given pixel rectangle"],
                  required=FF + [X264, AAC], optional=[HDR_X265],
@@ -187,7 +188,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
     "export": dict(role="execution", inputs=["video asset"], outputs=["delivery artifact in the preset's format"],
                    required=FF, optional=[{"capability": X264, "when": "preset youtube / youtube4k / reels / x"}, {"capability": AAC, "when": "preset youtube / youtube4k / reels / x / h265 (prores uses pcm_s16le, copy stream-copies, gif has no audio)"},
                                           {"capability": X265, "when": "preset h265"}, {"capability": "encoder:prores_ks", "when": "preset prores"},
-                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur"},
+                                          {"capability": "filter:palettegen", "when": "preset gif"}, {"capability": "encoder:gif", "when": "preset gif"}, {"capability": "filter:boxblur", "when": "--pad-fill blur or --fit blur"},
+                                                     {"capability": "filter:eq", "when": "--fit blur (the background copy is dimmed)"},
                                           {"capability": "filter:loudnorm", "when": "preset youtube / youtube4k / reels / x with audio: the written file is measured against the platform's loudness target (result `loudness`)"}],
                    video_required=True, audio_only=False, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "check": dict(role="verification", inputs=["media artifact"], outputs=["compliance rows JSON on stdout (no file)"],
@@ -197,10 +199,11 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                    required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"}],
                    video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "look": dict(role="verification", inputs=["video artifact"], outputs=["PNG contact sheet / frames / side-by-side"],
-                 required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
+                 required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"},
+                                                          {"capability": "filter:drawbox", "when": "--safe NAME (the platform's occluded zones)"}, {"capability": "filter:zscale", "when": "HDR source"}, {"capability": "filter:tonemap", "when": "HDR source"}],
                  video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
-    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)"], outputs=["final video artifact", "work directory of stage outputs (--keep / --work)"],
-                   required=FF, optional=[{"capability": "delegated", "when": "each stage runs cut / join / fit / caption / overlay / audio / loudness / export / check with their capabilities"}],
+    "render": dict(role="execution", inputs=["project.json (clips, transitions, captions, overlays, audio, loudness, export, check)", "media asset plus --template NAME (a shipped delivery template)"], outputs=["final video artifact", "one artifact per destination plus a pack table (--template all)", "work directory of stage outputs (--keep / --work)"],
+                   required=FF, optional=[{"capability": "delegated", "when": "each stage (and each destination of --template) runs cut / join / fit / caption / graphics / overlay / audio / loudness / export / check with their capabilities"}],
                    video_required=True, audio_only=False, visual=True, verify=["probe", "check", "look"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "batch": dict(role="execution", inputs=["folder of media", "batch.json recipe (steps or a render project)"], outputs=["one artifact per input file in the recipe's output_dir", "content-hash cache"],
                   required=FF, optional=[{"capability": "delegated", "when": "each recipe step runs the named script with its capabilities"}],
@@ -765,11 +768,11 @@ def doctor() -> Dict[str, Any]:
         "ok": not missing_required and not unknown_required,
         "tools": _tool_usability(state),
         "gpu_encoders": _gpu_encoders(listings["encoders"]),
-        "fonts": _fonts_capability(),
+        "fonts": _fonts_capability(probe=True),
     }
 
 
-def _fonts_capability() -> Dict[str, Any]:
+def _fonts_capability(probe: bool = True) -> Dict[str, Any]:
     """The default drawtext family (issue #66) plus, since 1.12, one entry per script the tools
     can detect: which languages this machine can actually RENDER, not just which filters exist.
 
@@ -778,7 +781,7 @@ def _fonts_capability() -> Dict[str, Any]:
     here follows). Informational like the default font and gpu_encoders: a machine with no Thai
     font is not a broken install, it is a machine that must not be asked to burn Thai captions.
     """
-    from _common import SCRIPTS, font_for_script, script_font_status
+    from _common import SCRIPTS, font_for_script, script_font_status, emoji_support
 
     font = _default_font()
     result = _font_available(font)
@@ -791,7 +794,12 @@ def _fonts_capability() -> Dict[str, Any]:
         # distinction the tools refuse or continue on.
         status = script_font_status(script)
         scripts[script] = {"status": status, "file": font_for_script(script) if status == "available" else None}
-    return {"default_font": font, "status": result["status"], "detail": result["detail"], "scripts": scripts}
+    # 1.15: emoji are a separate question from the writing system, and the only honest answer is a
+    # render (an installed colour emoji font proves nothing -- libass on this build may still draw
+    # it monochrome). `probe=False` -- `contract --json --static`, and every static/JSON-only path -- skips
+    # that render, exactly as it skips the rest of the environment detection.
+    return {"default_font": font, "status": result["status"], "detail": result["detail"],
+            "scripts": scripts, "emoji": emoji_support(probe=probe)}
 
 
 def _fonts_summary_line(fonts: Dict[str, Any]) -> str:
@@ -816,6 +824,16 @@ def _fonts_summary_line(fonts: Dict[str, Any]) -> str:
         parts.append("no font for " + " ".join(by_state["missing"]))
     if by_state["unknown"]:
         parts.append("unknown (no fontconfig) " + " ".join(by_state["unknown"]))
+    emoji = fonts.get("emoji") or {}
+    mode = emoji.get("mode")
+    if mode == "color":
+        parts.append("emoji colour")
+    elif mode == "png":
+        parts.append("emoji colour (assets)")
+    elif mode == "mono":
+        parts.append("emoji monochrome -- --emoji-assets DIR for colour")
+    elif mode:
+        parts.append("emoji none")
     return "; ".join(parts)
 
 

package/scripts/_platforms.py

@@ -0,0 +1,251 @@
+#!/usr/bin/env python3
+"""One table per delivery destination (internal module, not a tool).
+
+Before 1.14 the same destination was described three times: check.py held the
+compliance spec (duration, aspect, codecs, loudness), export.py held the frame and
+encoder settings, and nothing at all held the part of the frame the app's own UI
+covers. A TikTok export therefore passed every check while its captions sat under
+the description bar. This module is the single table the delivery tools read:
+
+    PLATFORMS[name] = {
+        "frame":   {"w", "h", "aspect"} or None (audio-only destinations),
+        "fps":     the frame rate a delivery is conformed to (None = leave alone),
+        "spec":    check.py's compliance row values (max_duration, aspects,
+                   min_height, fps_max, codecs, max_bytes, lufs, lufs_tol, tp,
+                   sdr_only) -- the keys check.py's SPECS has always had,
+        "safe":    the fraction of the frame each edge's UI covers
+                   (top/bottom/left/right, 0..1) -- nothing readable goes there,
+        "caption": the caption defaults a template uses (size as a fraction of the
+                   frame height, position, box, outline, animate),
+        "preset":  the export.py preset that writes this destination's file,
+        "check":   the check.py platform name a delivery is verified against.
+    }
+
+Read by check.py (SPECS), export.py (PRESETS/PLATFORM_OF), render.py (templates),
+caption.py and graphics.py (--platform margins) and look.py (--safe).
+
+Safe zones are the app's own overlay, measured from each platform's published
+design guidance: TikTok's caption/description block and the like/comment column,
+Instagram's Reels UI, the Shorts player. They are deliberately generous -- a
+caption 2 % too high is readable, a caption under the share button is not. The
+feed destinations (YouTube, X, LinkedIn, Facebook) have no persistent overlay, so
+they carry the conventional 5 % title-safe border instead.
+
+ASS note: caption.py's --size and --margin are in the 288-line ASS script grid, so
+a fraction of the frame height is that fraction * 288 (ass_units() below); the
+burn scales it back to the real frame. graphics.py and look.py work in pixels.
+"""
+from typing import Any, Dict, List, Optional
+
+ASS_SCRIPT_HEIGHT = 288  # caption.py's --size/--margin reference grid
+
+
+def ass_units(fraction: float) -> int:
+    """A fraction of the frame height as a caption.py --size / --margin value."""
+    return int(round(fraction * ASS_SCRIPT_HEIGHT))
+
+
+# The edges a feed destination reserves: no app chrome, just the conventional title-safe border.
+_SAFE_5 = {"top": 0.05, "bottom": 0.05, "left": 0.05, "right": 0.05}
+_NO_SAFE = {"top": 0.0, "bottom": 0.0, "left": 0.0, "right": 0.0}
+
+# caption defaults: size is a fraction of the frame height (0.0833 = the 24 that every
+# vertical job in this repo has used since 1.2), position/box/outline/animate as the
+# caption.py flags of the same name.
+_CAP_VERTICAL = {"size": 0.0833, "position": "bottom", "box": False, "outline": 2, "animate": "pop"}
+_CAP_WIDE = {"size": 0.0694, "position": "bottom", "box": False, "outline": 2, "animate": "none"}
+
+PLATFORMS: Dict[str, Dict[str, Any]] = {
+    "tiktok": {
+        "title": "TikTok",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 600, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+        # the description/caption block along the bottom, the like/comment/share column on the
+        # right, the status bar and the "Following | For You" tabs at the top
+        "safe": {"top": 0.10, "bottom": 0.22, "left": 0.05, "right": 0.14},
+        "caption": _CAP_VERTICAL,
+        "preset": "tiktok", "check": "tiktok",
+    },
+    "reels": {
+        "title": "Instagram Reels",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 90, "aspects": ["9:16", "4:5", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": True},
+        "safe": {"top": 0.08, "bottom": 0.20, "left": 0.05, "right": 0.12},
+        "caption": _CAP_VERTICAL,
+        "preset": "reels", "check": "reels",
+    },
+    "shorts": {
+        "title": "YouTube Shorts",
+        "frame": {"w": 1080, "h": 1920, "aspect": "9:16"},
+        "fps": 30,
+        "spec": {"max_duration": 180, "aspects": ["9:16", "1:1"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 256 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": {"top": 0.06, "bottom": 0.18, "left": 0.05, "right": 0.12},
+        "caption": _CAP_VERTICAL,
+        "preset": "shorts", "check": "shorts",
+    },
+    "youtube": {
+        "title": "YouTube",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": {"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube", "check": "youtube",
+    },
+    "youtube-hdr": {
+        "title": "YouTube (HDR10)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": dict({"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                      "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                      "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False}),
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube-hdr", "check": "youtube",
+    },
+    "youtube-av1": {
+        "title": "YouTube (AV1)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": dict({"max_duration": 12 * 3600, "aspects": ["16:9", "9:16", "1:1", "4:3"], "min_height": 720, "fps_max": 60,
+                      "codecs": ["h264", "hevc", "prores", "av1", "vp9"], "max_bytes": 256 * 1024 ** 3,
+                      "lufs": -14, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False}),
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "youtube-av1", "check": "youtube",
+    },
+    "x": {
+        "title": "X (Twitter)",
+        "frame": {"w": 1280, "h": 720, "aspect": "16:9"},
+        "fps": 30,
+        "spec": {"max_duration": 140, "aspects": ["16:9", "1:1", "9:16"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264"], "max_bytes": 512 * 1024 ** 2,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "x", "check": "x",
+    },
+    "linkedin": {
+        "title": "LinkedIn",
+        "frame": {"w": 1080, "h": 1080, "aspect": "1:1"},
+        "fps": 30,
+        "spec": {"max_duration": 600, "aspects": ["16:9", "1:1", "9:16", "4:5"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264"], "max_bytes": 5 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "linkedin", "check": "linkedin",
+    },
+    "facebook": {
+        "title": "Facebook",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": 30,
+        "spec": {"max_duration": 240 * 60, "aspects": ["16:9", "1:1", "9:16", "4:5"], "min_height": 720, "fps_max": 60,
+                 "codecs": ["h264", "hevc"], "max_bytes": 4 * 1024 ** 3,
+                 "lufs": -14, "lufs_tol": 3.0, "tp": -1.0, "sdr_only": True},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "facebook", "check": "facebook",
+    },
+    "podcast": {
+        "title": "Podcast (audio)",
+        "frame": None,
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None,
+                 "codecs": None, "max_bytes": None,
+                 "lufs": -16, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+        "safe": _NO_SAFE,
+        "caption": _CAP_WIDE,
+        "preset": None, "check": "podcast",
+    },
+    # Not destinations an app owns, but compliance targets check.py has always had.
+    "broadcast": {
+        "title": "Broadcast (EBU R128)",
+        "frame": {"w": 1920, "h": 1080, "aspect": "16:9"},
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": ["16:9"], "min_height": 1080, "fps_max": 60,
+                 "codecs": ["prores", "dnxhd", "h264", "hevc", "mpeg2video"], "max_bytes": None,
+                 "lufs": -23, "lufs_tol": 1.0, "tp": -1.0, "sdr_only": False},
+        "safe": _SAFE_5,
+        "caption": _CAP_WIDE,
+        "preset": "prores", "check": "broadcast",
+    },
+    "custom": {
+        "title": "Custom",
+        "frame": None,
+        "fps": None,
+        "spec": {"max_duration": None, "aspects": None, "min_height": 0, "fps_max": None,
+                 "codecs": None, "max_bytes": None,
+                 "lufs": None, "lufs_tol": 2.0, "tp": -1.0, "sdr_only": False},
+        "safe": _NO_SAFE,
+        "caption": _CAP_WIDE,
+        "preset": None, "check": "custom",
+    },
+}
+
+# The canonical destination names.
+PLATFORM_NAMES: List[str] = sorted(PLATFORMS)
+# The spellings people actually write for those destinations. resolve() maps them onto the
+# canonical name, and every tool's --platform/--safe/--preset accepts both, so
+# `--platform youtube-shorts` and `--platform shorts` are the same request everywhere.
+ALIASES: Dict[str, str] = {"youtube-shorts": "shorts", "yt-shorts": "shorts", "yt": "youtube",
+                           "instagram": "reels", "ig": "reels", "twitter": "x", "fb": "facebook"}
+# One vocabulary for the word "platform": check.py, caption.py, graphics.py and look.py all
+# offer this list (review 12 found three different ones). It is the compliance targets -- the
+# destinations a delivery is checked against -- plus every alias; youtube-hdr and youtube-av1
+# are export presets of the youtube target, not separate destinations, so they are not in it.
+PLATFORM_CHOICES: List[str] = sorted({n for n in PLATFORMS if PLATFORMS[n]["check"] == n} | set(ALIASES))
+
+
+def has_frame(name: str) -> bool:
+    """True when this destination has a frame, and therefore a safe zone to place text inside."""
+    return bool(PLATFORMS.get(resolve(name) or "", {}).get("frame"))
+
+
+def spec_of(name: str) -> Dict[str, Any]:
+    """check.py's compliance row values for a destination."""
+    return dict(PLATFORMS[name]["spec"])
+
+
+def safe_of(name: str) -> Dict[str, float]:
+    return dict(PLATFORMS[name]["safe"])
+
+
+def loudness_of(name: str) -> Dict[str, float]:
+    s = PLATFORMS[name]["spec"]
+    return {"lufs": s["lufs"], "lufs_tol": s["lufs_tol"], "tp": s["tp"]}
+
+
+def safe_margins_px(name: str, width: int, height: int) -> Dict[str, int]:
+    """The safe zone in pixels for a frame of this size, as whole pixels per edge."""
+    s = PLATFORMS[name]["safe"]
+    return {"top": int(round(s["top"] * height)), "bottom": int(round(s["bottom"] * height)),
+            "left": int(round(s["left"] * width)), "right": int(round(s["right"] * width))}
+
+
+def caption_defaults(name: str) -> Dict[str, Any]:
+    """caption.py flag values for this destination: --size/--margin in ASS units."""
+    cap = dict(PLATFORMS[name]["caption"])
+    safe = PLATFORMS[name]["safe"]
+    edge = safe["top"] if cap["position"].startswith("top") else safe["bottom"]
+    cap["size"] = ass_units(cap["size"])
+    cap["margin"] = ass_units(edge)
+    return cap
+
+
+def resolve(name: Optional[str]) -> Optional[str]:
+    """Accept the spellings people write for a destination ('youtube-shorts', 'ig')."""
+    if not name:
+        return None
+    key = str(name).strip().lower()
+    return ALIASES.get(key, key)