ffmpeg-skill 1.13.0 → 1.14.0

package/scripts/check.py

@@ -10,7 +10,8 @@ row's `fix` is the command that resolves it; a few of the less obvious FAILs
 not a restatement of the spec value -- for a caller reporting this to someone
 who doesn't already know why the spec says what it says.
 
-Platforms: youtube, shorts, reels, tiktok, x, linkedin, broadcast (EBU R128), podcast, custom
+Platforms: youtube, shorts, reels, tiktok, x, linkedin, facebook, broadcast (EBU R128),
+podcast, custom -- one table, shared with export.py and the render.py templates
 
 Examples:
   python3 check.py final.mp4 --platform youtube
@@ -25,19 +26,15 @@ import sys
 from fractions import Fraction
 from typing import Any, Dict, List
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, spec_of, resolve as resolve_platform
 from _common import STATE, add_common, apply_common, die, emit, info, probe, require_tool, run, run_analysis, dry_run_input_pending
 
-SPECS: Dict[str, Dict[str, Any]] = {
-    "youtube":   {"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},
-    "shorts":    {"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},
-    "reels":     {"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},
-    "tiktok":    {"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},
-    "x":         {"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},
-    "linkedin":  {"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},
-    "broadcast": {"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},
-    "podcast":   {"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},
-    "custom":    {"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},
-}
+# The one delivery table (scripts/_platforms.py): check.py's rows, export.py's presets and the
+# render.py templates all read it, so a platform's loudness spec is stated once. Only the
+# destinations that are compliance targets appear here; youtube-hdr / youtube-av1 are export
+# presets of the youtube target, not separate specs.
+SPECS: Dict[str, Dict[str, Any]] = {name: spec_of(name) for name in sorted(PLATFORMS)
+                                    if PLATFORMS[name]["check"] == name}
 
 
 def measure_loudness(path: str) -> Dict[str, float]:
@@ -66,7 +63,7 @@ def aspect_name(w: int, h: int) -> str:
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
-    ap.add_argument("--platform", choices=sorted(SPECS), default=None, help="delivery spec to check against (default: youtube, with judgement rows reported as WARN because no platform was named)")
+    ap.add_argument("--platform", choices=PLATFORM_CHOICES, default=None, help="delivery spec to check against (default: youtube, with judgement rows reported as WARN because no platform was named)")
     ap.add_argument("--max-duration", type=float, help="override max duration in seconds")
     ap.add_argument("--aspect", help="override allowed aspect (e.g. 9:16 or 16:9,1:1)")
     ap.add_argument("--lufs", type=float, help="override loudness target")
@@ -81,7 +78,7 @@ def main() -> int:
     # spent a paragraph explaining why they left them alone. Without a named platform the
     # judgement rows are advisory: WARN, not FAIL, and not counted as failed.
     named = args.platform is not None
-    args.platform = args.platform or "youtube"
+    args.platform = resolve_platform(args.platform) or "youtube"
     spec = dict(SPECS[args.platform])
     if args.max_duration is not None:
         spec["max_duration"] = args.max_duration
@@ -134,10 +131,10 @@ def main() -> int:
             row("fps", "PASS" if fps <= spec["fps_max"] + 0.01 else "FAIL", f"{fps:g}", f"<= {spec['fps_max']}", "fit.py --fps 30 (drops half the frames of 60 fps motion; fine for talking heads, visible on sports/gaming)")
         row("vfr", "PASS" if not v.get("variable_frame_rate_suspected") else "WARN", "variable" if v.get("variable_frame_rate_suspected") else "constant", "constant", "fit.py --fps N (any re-encode conforms it)")
         if spec["codecs"]:
-            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + args.platform.replace("shorts", "reels").replace("tiktok", "reels").replace("linkedin", "youtube").replace("broadcast", "prores"),
+            row("video codec", "PASS" if v.get("codec") in spec["codecs"] else "FAIL", v.get("codec"), "/".join(spec["codecs"]), "export.py --preset " + (PLATFORMS[args.platform].get("preset") or "youtube"),
                 reason="the platform's player may refuse to decode this codec at all, not just look worse")
         pf = v.get("pix_fmt") or ""
-        if args.platform in ("reels", "tiktok", "x", "linkedin"):
+        if args.platform in ("reels", "tiktok", "x", "linkedin", "facebook"):
             row("pixel format", "PASS" if pf == "yuv420p" else "FAIL", pf, "yuv420p (8-bit 4:2:0)", "export.py preset re-encodes to yuv420p",
                 reason="QuickTime and iOS commonly reject video that isn't 8-bit 4:2:0")
         if spec["sdr_only"] and v.get("hdr"):

package/scripts/export.py

@@ -6,7 +6,13 @@ sets BT.709 tags, and picks sensible codecs/bitrates.
 Presets:
   youtube   1920x1080 H.264 CRF 18 high profile, AAC 192k, 48 kHz, faststart
   youtube4k 3840x2160 H.264 CRF 18, AAC 192k
-  reels     1080x1920 9:16 H.264 CRF 20, AAC 128k, max 90 s (also Shorts/TikTok)
+  reels     1080x1920 9:16 H.264 CRF 20, AAC 128k, max 90 s (Instagram Reels)
+  tiktok    1080x1920 9:16 H.264 CRF 20, AAC 128k, max 600 s
+  shorts    1080x1920 9:16 H.264 CRF 20, AAC 128k, max 180 s (YouTube Shorts)
+  linkedin  1080x1080 1:1 H.264 CRF 20, AAC 128k, max 600 s
+  facebook  1920x1080 16:9 H.264 CRF 21, AAC 128k
+  youtube-hdr HEVC Main10 keeping the source's HDR10/HLG tags (refuses an SDR source)
+  youtube-av1 1080p AV1 (libsvtav1, libaom fallback); missing_tool when neither is built
   x         1280x720 H.264 CRF 22, AAC 128k, max 140 s (Twitter/X)
   prores    ProRes 422 HQ .mov, PCM 16-bit audio (editing master)
   h265      HEVC CRF 24 (libx265) with hvc1 tag for Apple compatibility
@@ -29,31 +35,82 @@ import sys
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, add_common, apply_common, bt709_tag_args, child_args, emit, cfr_args, default_output, die, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common import STATE, add_common, apply_common, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from check import SPECS as PLATFORMS, measure_loudness
+from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, resolve as resolve_platform
+# Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
+# from a literal restated here: before 1.14 they were typed twice and the facebook preset had
+# already drifted (no duration cap against the table's 14400 s).
+def _from_table(dest: str, **over) -> Dict:
+    """A preset's w/h/max read from PLATFORMS[dest], with the encoder settings given here.
+
+    `over` is for the two presets that are deliberately not the destination's own frame or cap:
+    `youtube4k` delivers to YouTube at 2160p, and neither youtube preset trims at YouTube's
+    12-hour limit (check.py reports it; export.py has never cut a long upload and does not start).
+    """
+    frame = PLATFORM_TABLE[dest]["frame"] or {}
+    spec = PLATFORM_TABLE[dest]["spec"]
+    max_duration = spec.get("max_duration")
+    out = {"w": frame.get("w"), "h": frame.get("h"),
+           "max": float(max_duration) if max_duration is not None else None}
+    out.update(over)
+    return out
+
+
+_H264_HIGH = ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"]
+_AAC_192 = ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"]
+_AAC_128 = ["-c:a", "aac", "-b:a", "128k", "-ar", "48000"]
+
+
+def _social(crf: str = "20") -> List[str]:
+    return ["-c:v", "libx264", "-preset", "medium", "-crf", crf, "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"]
+
+
 PRESETS: Dict[str, Dict] = {
-    "youtube": {"w": 1920, "h": 1080, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "1080p H.264, AAC 192k"},
-    "youtube4k": {"w": 3840, "h": 2160, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "slow", "-crf", "18", "-profile:v", "high", "-pix_fmt", "yuv420p"], "audio": ["-c:a", "aac", "-b:a", "192k", "-ar", "48000"], "max": None, "desc": "2160p H.264, AAC 192k"},
-    "reels": {"w": 1080, "h": 1920, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "20", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "48000"], "max": 90.0, "desc": "9:16 1080x1920, 30fps, max 90s (Reels/Shorts/TikTok)"},
-    "x": {"w": 1280, "h": 720, "ext": "mp4", "video": ["-c:v", "libx264", "-preset", "medium", "-crf", "22", "-profile:v", "high", "-pix_fmt", "yuv420p", "-r", "30"], "audio": ["-c:a", "aac", "-b:a", "128k", "-ar", "44100"], "max": 140.0, "desc": "720p H.264, max 140s (Twitter/X)"},
+    "youtube": dict(_from_table("youtube", max=None), ext="mp4", video=_H264_HIGH, audio=_AAC_192, desc="1080p H.264, AAC 192k"),
+    "youtube4k": dict(_from_table("youtube", w=3840, h=2160, max=None), ext="mp4", video=_H264_HIGH, audio=_AAC_192, desc="2160p H.264, AAC 192k"),
+    "reels": dict(_from_table("reels"), ext="mp4", video=_social(), audio=_AAC_128, desc="9:16 1080x1920, 30fps, max 90s (Instagram Reels)"),
+    "x": dict(_from_table("x"), ext="mp4", video=_social("22"), audio=["-c:a", "aac", "-b:a", "128k", "-ar", "44100"], desc="720p H.264, max 140s (Twitter/X)"),
     "prores": {"w": None, "h": None, "ext": "mov", "video": ["-c:v", "prores_ks", "-profile:v", "3", "-vendor", "apl0", "-pix_fmt", "yuv422p10le"], "audio": ["-c:a", "pcm_s16le"], "max": None, "desc": "ProRes 422 HQ master, PCM audio, source resolution"},
     "h265": {"w": None, "h": None, "ext": "mp4", "video": ["-c:v", "libx265", "-preset", "medium", "-crf", "24", "-pix_fmt", "yuv420p", "-tag:v", "hvc1"], "audio": ["-c:a", "aac", "-b:a", "160k"], "max": None, "desc": "HEVC CRF 24, hvc1 tag, source resolution"},
     "gif": {"w": 480, "h": None, "ext": "gif", "video": [], "audio": [], "max": None, "desc": "480px palette GIF, 12fps"},
     "copy": {"w": None, "h": None, "ext": None, "video": ["-c:v", "copy"], "audio": ["-c:a", "copy"], "max": None, "desc": "stream copy, no re-encode (source codecs/container/colour tags unchanged)"},
+    # 1.14: the destinations that used to be aliases of reels/youtube are their own presets, each
+    # sized and length-limited from the one platform table (scripts/_platforms.py) rather than from
+    # a comment. `reels` keeps its historical settings byte-for-byte so existing calls are unchanged.
+    "tiktok": dict(_from_table("tiktok"), ext="mp4", video=_social(), audio=_AAC_128, desc="9:16 1080x1920, 30fps, max 600s (TikTok)"),
+    "shorts": dict(_from_table("shorts"), ext="mp4", video=_social(), audio=_AAC_128, desc="9:16 1080x1920, 30fps, max 180s (YouTube Shorts)"),
+    "linkedin": dict(_from_table("linkedin"), ext="mp4", video=_social(), audio=_AAC_128, desc="1:1 1080x1080, 30fps, max 600s (LinkedIn)"),
+    "facebook": dict(_from_table("facebook"), ext="mp4", video=_social("21"), audio=_AAC_128, desc="16:9 1920x1080, 30fps, max 14400s (Facebook feed)"),
+    # HDR and AV1 deliveries: the encoder line comes from encoder_args() so the source's own
+    # HDR tags survive (hevc) and the AV1 encoder is chosen/refused in one place.
+    "youtube-hdr": {"w": None, "h": None, "ext": "mp4", "codec": "hevc", "video": [], "audio": _AAC_192, "max": None, "hdr_only": True, "desc": "HEVC Main10, source HDR10/HLG tags kept, AAC 192k (refuses an SDR source)"},
+    "youtube-av1": dict(_from_table("youtube", max=None), ext="mp4", codec="av1", video=[], audio=_AAC_192, desc="1080p AV1 (libsvtav1, libaom fallback), AAC 192k"),
 }
 
 
 
 # which check.py platform a preset targets (its loudness spec is measured after the write)
 HERE = Path(__file__).resolve().parent
-PLATFORM_OF = {"youtube": "youtube", "youtube4k": "youtube", "reels": "reels", "x": "x"}
+# broadcast's "preset" is prores, an editing master rather than a delivery: nothing is measured
+# against a loudness spec after writing it, exactly as before 1.14.
+_NOT_A_DELIVERY = frozenset({"broadcast"})
+# Derived from the same table: a destination whose "preset" is this one is the compliance target
+# its loudness is measured against (youtube4k and the two youtube variants deliver to youtube).
+PLATFORM_OF: Dict[str, str] = {PLATFORM_TABLE[n]["preset"]: PLATFORM_TABLE[n]["check"]
+                               for n in sorted(PLATFORM_TABLE)
+                               if PLATFORM_TABLE[n].get("preset") in PRESETS and PLATFORM_TABLE[n]["frame"]
+                               and n not in _NOT_A_DELIVERY}
+PLATFORM_OF["youtube4k"] = PLATFORM_TABLE["youtube"]["check"]
+# Aliases people write for a destination ('youtube-shorts', 'ig', 'twitter') name the same preset.
+PRESET_CHOICES: List[str] = sorted(set(PRESETS) | {a for a in _ALIASES if resolve_platform(a) in PRESETS})
 
 
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input", nargs="?")
     ap.add_argument("-o", "--output", help="output file (default: <name>_<preset>.<ext>)")
-    ap.add_argument("--preset", choices=sorted(PRESETS), help="delivery preset")
+    ap.add_argument("--preset", choices=PRESET_CHOICES, help="delivery preset (aliases: " + ", ".join(a for a in _ALIASES if resolve_platform(a) in PRESETS) + ")")
     ap.add_argument("--fit", choices=["pad", "crop"], default="pad", help="how to reach the preset frame when aspect differs (default pad)")
     ap.add_argument("--pad-color", default="black")
     add_pad_fill_args(ap)
@@ -65,6 +122,8 @@ def main() -> int:
     add_common(ap, codec=False)  # the preset decides the codec; --codec would only be refused
     args = ap.parse_args()
     apply_common(args)
+    if args.preset and args.preset not in PRESETS:
+        args.preset = resolve_platform(args.preset)
 
     if args.list:
         for name, p in PRESETS.items():
@@ -82,7 +141,13 @@ def main() -> int:
     if not meta.get("video"):
         die("input has no video stream")
     notes: List[str] = []
-    if meta["video"].get("hdr") and args.preset not in ("prores", "copy"):
+    if p.get("hdr_only") and not meta["video"].get("hdr"):
+        # The point of this preset is that the delivery stays HDR. Running it on an SDR source
+        # would write a 10-bit HEVC file labelled with SDR tags and call it an HDR delivery.
+        die(f"--preset {args.preset} delivers HDR and this source is SDR ({meta['video'].get('codec')}, "
+            f"{meta['video'].get('color_transfer') or 'untagged'})",
+            hint="use --preset youtube for an SDR delivery; there is no way to invent HDR range from an SDR master")
+    if meta["video"].get("hdr") and args.preset not in ("prores", "copy", "youtube-hdr"):
         notes.append("source is HDR (%s). This preset outputs SDR BT.709 tags without tone mapping; run color.py --to-sdr first for correct colours." % meta["video"].get("hdr_format"))
         info("warning: " + notes[-1])
     has_audio = bool(meta.get("audio"))
@@ -113,9 +178,20 @@ def main() -> int:
     if vf:
         cmd += ["-vf", ",".join(vf)]
     video = list(p["video"])
+    if p.get("codec"):
+        # encoder_args() is the one place that turns a codec name into encoder options: it keeps
+        # the source's HDR tags for hevc and refuses (kind: missing_tool) when no AV1 encoder is
+        # built, which is exactly what these two presets promise.
+        video = encoder_args(p["codec"], args.crf if args.crf is not None else (20 if p["codec"] == "hevc" else 32),
+                             "veryfast" if STATE.fast else "medium", meta)
+        # encoder_args() already applied --fast (its own preset scale per encoder: SVT-AV1 counts
+        # 1..12, not x264's names) and appends +faststart, which this tool adds again for mp4
+        while "-movflags" in video:
+            i = video.index("-movflags")
+            del video[i:i + 2]
     if args.crf is not None and "-crf" in video:
         video[video.index("-crf") + 1] = str(args.crf)
-    if STATE.fast and "-preset" in video:
+    if STATE.fast and "-preset" in video and not p.get("codec"):
         video[video.index("-preset") + 1] = "veryfast"
     cmd += video
     if args.preset != "copy":
@@ -123,7 +199,7 @@ def main() -> int:
         # no longer be a copy, and would silently mislabel colour the agent never actually looked at
         if "-r" not in video:
             cmd += cfr_args(meta)
-        if args.preset not in ("prores",):
+        if args.preset not in ("prores",) and not p.get("codec"):
             cmd += bt709_tag_args(video[video.index("-c:v") + 1])
     if out_ext == "mp4":
         cmd += ["-movflags", "+faststart"]

package/scripts/fit.py

@@ -4,7 +4,7 @@
 Duration: --duration N with --method speed (retime video+audio, pitch-preserving
 via atempo chaining) or --method trim (keep the first N seconds, or a centred
 window with --from-center). Aspect: --aspect 16:9|9:16|1:1|4:5|W:H with
---fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture) or --fit crop.
+--fit pad (letterbox/pillarbox with --pad-color, default black, or --pad-fill blur\nfor a blurred copy of the frame behind the picture), --fit crop, or --fit blur\n(the whole picture centred on a blurred, darkened copy of itself -- nothing\ncropped, no black bars).
 --width and/or --height set the output size: give one and the other follows
 the aspect (source aspect if --aspect is not also given); give both for an
 exact frame. --rotate 90|180|270 (clockwise) and --flip h|v apply a new
@@ -25,6 +25,7 @@ Examples:
   python3 fit.py input.mp4 --duration 30 --method trim
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --width 1080
   python3 fit.py input.mp4 --aspect 9:16 --fit pad --pad-fill blur   # the phone-editor look: blurred frame behind the bars
+  python3 fit.py input.mp4 --aspect 9:16 --fit blur                  # same look in one word (blurred + darkened fill)
   python3 fit.py input.mp4 --aspect 1:1 --fit crop --duration 15
   python3 fit.py input.mp4 --aspect 9:16 --fit crop --crop-x 1   # keep the right edge (e.g. product held stage-right)
   python3 fit.py input.mp4 --height 1080                         # width follows the source aspect
@@ -39,6 +40,7 @@ from fractions import Fraction
 from typing import List
 
 from _common import video_args, STATE, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, pad_filters, add_pad_fill_args, X264_PRESETS, time_arg, fmt_secs
+BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 ASPECT_PRESETS = {"16:9": Fraction(16, 9), "9:16": Fraction(9, 16), "1:1": Fraction(1, 1), "4:5": Fraction(4, 5), "4:3": Fraction(4, 3), "21:9": Fraction(21, 9)}
 
 
@@ -89,7 +91,11 @@ def main() -> int:
                    help="slow-motion quality: blend (frame blending) or interpolate (motion-compensated, slow but fluid). default none = duplicate frames")
     a = ap.add_argument_group("aspect")
     a.add_argument("--aspect", help="target aspect ratio, e.g. 16:9, 9:16, 1:1, 4:5")
-    a.add_argument("--fit", choices=["pad", "crop"], default="pad", help="pad (letterbox) or crop to reach the aspect (default pad)")
+    a.add_argument("--fit", choices=["pad", "crop", "blur"], default="pad",
+                   help="how to reach the aspect: pad (letterbox), crop, or blur -- the whole picture centred on a "
+                        "blurred, darkened copy of itself filling the rest (the phone-editor vertical, 1.14). "
+                        "The darkening is applied to SDR sources only: on an HDR source the background is blurred "
+                        "but left at its own levels, since an eq on PQ/HLG code values is not a -15%% perceptual dim")
     a.add_argument("--width", type=int, help="output width in px (default: keep source width or the width implied by the aspect); with --height also given, both are used directly")
     a.add_argument("--height", type=int, help="output height in px (default: keep source height or the height implied by the aspect); with --width also given, both are used directly")
     a.add_argument("--pad-color", default="black", help="pad colour, e.g. black, white, 0x101010 (default black)")
@@ -214,6 +220,19 @@ def main() -> int:
         if args.fit == "crop":
             vf.append(f"scale={out_w}:{out_h}:force_original_aspect_ratio=increase")
             vf.append(f"crop={out_w}:{out_h}:(in_w-out_w)*{args.crop_x:g}:(in_h-out_h)*{args.crop_y:g}")
+        elif args.fit == "blur":
+            # nothing is cropped and nothing is a black bar: the picture keeps its own aspect in
+            # the middle of a blurred, dimmed copy of itself (BLUR_DARKEN) filling the frame.
+            # The dimming is an eq on the code values, which is a -15 % perceptual dim on an SDR
+            # (gamma-encoded) signal and something else entirely on a PQ/HLG one -- so an HDR
+            # source keeps its blurred background undimmed rather than being silently altered
+            # (review 12). The blur itself is neutral either way, and no tone mapping happens.
+            darken = 0.0 if meta["video"].get("hdr") else BLUR_DARKEN
+            if not darken:
+                info("--fit blur: HDR source, so the blurred background is not dimmed "
+                     "(an eq on PQ/HLG code values is not the -15%% dim it is on SDR); "
+                     "run color.py --to-sdr first for the SDR look")
+            vf.append(pad_filters(out_w, out_h, "blur", args.pad_color, args.pad_blur, darken))
         else:
             vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur))
         vf.append("setsar=1")

package/scripts/graphics.py

@@ -9,6 +9,10 @@ Templates:
   progress      thin progress bar along the bottom that fills over the clip (or --start/--end)
   countdown     big numbers counting down from --from to 0 (--start/--end define the window)
   bug           persistent text bug (--title) in a corner, e.g. "@handle" or "LIVE"
+  sticker       rounded filled chip of --text that pops in at --position (the social sticker)
+  hook          full-width opening title card (--title) for --duration seconds with a thin
+                progress bar along the top -- the TikTok/Shorts opener
+  meme          white upper-case --top / --bottom lines with a heavy black outline
 
 Examples:
   python3 graphics.py talk.mp4 --template lower-third --name "Ada Lovelace" --title "Analyst" --start 2 --end 8
@@ -17,14 +21,18 @@ Examples:
   python3 graphics.py intro.mp4 --template countdown --from 5 --start 1 --end 6
   python3 graphics.py talk.mp4 --template lower-third --name "김민준" --title "감독" --lang ko
   python3 graphics.py clip.mp4 --template chapter --title "Part 2 — Setup" --position top-left --start 0 --end 5
+  python3 graphics.py reel.mp4 --template sticker --text "NEW" --position top-right --platform tiktok
+  python3 graphics.py reel.mp4 --template hook --title "How I cut this in one command" --duration 3
+  python3 graphics.py clip.mp4 --template meme --top "when the render" --bottom "finally finishes"
 """
 import argparse
 import sys
 from typing import List, Optional
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
 from _common import aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args, color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args, drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs
 
-TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug"]
+TEMPLATES = ["lower-third", "title", "chapter", "progress", "countdown", "bug", "sticker", "hook", "meme"]
 
 
 def ff_color(hex_rgb: str, alpha: float = 1.0) -> str:
@@ -53,12 +61,20 @@ def main() -> int:
     ap.add_argument("--template", choices=TEMPLATES, required=True)
     ap.add_argument("--brand", help="brand.json for colours, font, safe margin")
     ap.add_argument("--name", help="lower-third: name line")
-    ap.add_argument("--title", help="title / chapter / bug text, or lower-third second line")
+    ap.add_argument("--title", help="title / chapter / bug / hook text, or lower-third second line")
+    ap.add_argument("--text", help="sticker: the chip's text")
+    ap.add_argument("--top", help="meme: upper line")
+    ap.add_argument("--bottom", help="meme: lower line")
+    ap.add_argument("--duration", type=float, default=3.0, help="hook: seconds the opening card stays up (default 3)")
     ap.add_argument("--subtitle", help="title: smaller second line")
     ap.add_argument("--from", dest="count_from", type=int, default=5, help="countdown start number (default 5)")
     ap.add_argument("--start", help="show from (default 0)")
     ap.add_argument("--end", help="hide after (default end of clip)")
-    ap.add_argument("--position", choices=["top-left", "top-right", "bottom-left", "bottom-right"], default=None, help="corner for chapter/bug (default bottom-left / top-right)")
+    ap.add_argument("--position", choices=["top-left", "top-right", "bottom-left", "bottom-right"], default=None, help="corner for chapter/bug/sticker (default bottom-left / top-right / top-right)")
+    ap.add_argument("--margin", type=int, default=None, help="distance from the frame edge in px (default: brand safe_margin, or the --platform safe zone)")
+    ap.add_argument("--platform", choices=PLATFORM_CHOICES, default=None,
+                    help="keep the graphic out of this destination's UI: margins become the platform's safe zone "
+                         "(TikTok's description bar and like column, the Reels/Shorts chrome). An explicit --margin wins")
     ap.add_argument("--primary", help="override brand primary colour RRGGBB")
     ap.add_argument("--text-color", help="override text colour RRGGBB")
     ap.add_argument("--font")
@@ -72,6 +88,10 @@ def main() -> int:
     args = ap.parse_args()
     apply_common(args)
 
+    args.platform = resolve_platform(args.platform)
+    if args.platform and not PLATFORMS[args.platform].get("frame"):
+        info(f"--platform {args.platform}: this destination has no frame and no app chrome; margins unchanged")
+        args.platform = None
     brand = load_brand(args.brand)
     primary = color_hex(args.primary or brand["colors"]["primary"])
     text_c = color_hex(args.text_color or brand["colors"]["text"])
@@ -85,7 +105,7 @@ def main() -> int:
     args.lang = args.lang or (brand.get("lang") if args.brand else None)
     # a font that covers the text before drawtext renders boxes instead of glyphs (1.12)
     _script, script_file, _family = script_font_for_text(
-        " ".join(t for t in (args.name, args.title, args.subtitle) if t),
+        " ".join(t for t in (args.name, args.title, args.subtitle, args.text, args.top, args.bottom) if t),
         lang=args.lang, font=args.font, font_explicit=bool(args.font), font_file=args.font_file or brand.get("font_file"))
     fo = font_opts(brand, args.font, args.font_file, script_file)
 
@@ -101,6 +121,19 @@ def main() -> int:
     if meta["video"].get("rotation") in (90, -90, 270, -270):
         W, H = H, W
     dur = meta.get("duration") or 0.0
+    # Per-edge margins. Without --margin/--platform every edge is the brand safe margin, exactly
+    # as before; --margin sets all four; --platform takes each edge from the destination's safe
+    # zone (scripts/_platforms.py), which is what keeps a sticker off TikTok's like column.
+    m_top = m_bottom = m_left = m_right = margin
+    if args.margin is not None:
+        if args.margin < 0:
+            die(f"--margin must be >= 0, got {args.margin}")
+        m_top = m_bottom = m_left = m_right = margin = args.margin
+    elif args.platform:
+        px = safe_margins_px(args.platform, W, H)
+        m_top, m_bottom, m_left, m_right = px["top"], px["bottom"], px["left"], px["right"]
+        margin = m_left
+        info(f"--platform {args.platform}: safe margins top {m_top} / bottom {m_bottom} / left {m_left} / right {m_right} px")
     fps = meta["video"].get("fps")
     s = time_arg(args.start, "--start", fps) if args.start else 0.0
     e = time_arg(args.end, "--end", fps) if args.end else dur
@@ -123,9 +156,9 @@ def main() -> int:
         pad = int(base * 0.02)
         bar_h = h1 + (h2 + pad if args.title else 0) + pad * 2
         bar_w = int(base * 0.62)
-        y0 = H - margin - bar_h
+        y0 = H - m_bottom - bar_h
         # slide in from the left over 0.4 s, slide out over 0.3 s (overlay evaluates x per frame)
-        x_expr = f"if(lt(t,{s:.3f}+0.4),-{bar_w}+({bar_w}+{margin})*((t-{s:.3f})/0.4),if(gt(t,{e:.3f}-0.3),{margin}-({bar_w}+{margin})*(1-({e:.3f}-t)/0.3),{margin}))"
+        x_expr = f"if(lt(t,{s:.3f}+0.4),-{bar_w}+({bar_w}+{m_left})*((t-{s:.3f})/0.4),if(gt(t,{e:.3f}-0.3),{m_left}-({bar_w}+{m_left})*(1-({e:.3f}-t)/0.3),{m_left}))"
         fc.append(f"color=c=0x{bg}@0.85:s={bar_w}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[bar]")
         fc.append(f"color=c=0x{primary}:s={int(base * 0.012)}x{bar_h}:r={meta['video'].get('fps') or 30:g},format=rgba[acc]")
         fc.append(f"[0:v][bar]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v1]")
@@ -153,8 +186,8 @@ def main() -> int:
         pos = args.position or ("bottom-left" if args.template == "chapter" else "top-right")
         fs = int(base * (0.04 if args.template == "chapter" else 0.032))
         padx, pady = int(fs * 0.6), int(fs * 0.35)
-        xe = f"{margin}" if "left" in pos else f"w-text_w-{margin}"
-        ye = f"{margin}" if "top" in pos else f"h-text_h-{margin}"
+        xe = f"{m_left}" if "left" in pos else f"w-text_w-{m_right}"
+        ye = f"{m_top}" if "top" in pos else f"h-text_h-{m_bottom}"
         box_color = ff_color(primary if args.template == "chapter" else bg, 0.9 if args.template == "chapter" else 0.7)
         txt_color = ff_color(bg if args.template == "chapter" else text_c)
         filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={drawtext_boxborderw(pady, padx)}:alpha='{fade_a}':{en}")
@@ -166,6 +199,58 @@ def main() -> int:
         fc.append(f"[0:v]drawbox=x=0:y=ih-{h}:w=iw:h={h}:color={ff_color(bg, 0.5)}:t=fill:{en}[v1]")
         fc.append(f"[v1][pb]overlay=x='-w+w*min(1,max(0,(t-{s:.3f})/{e - s:.3f}))':y={H - h}:{en}:eof_action=pass[vout]")
 
+    elif args.template == "sticker":
+        # A social sticker: a filled chip of text that pops in. drawtext's box gives the chip
+        # (its corners are square -- drawtext has no rounded box), and the pop is the two things
+        # drawtext *can* animate per frame: alpha and position, so the chip fades up while
+        # rising the last few pixels into place over 0.25 s.
+        if not args.text:
+            die("sticker needs --text")
+        pos = args.position or "top-right"
+        fs = int(base * 0.05)
+        padx, pady = int(fs * 0.7), int(fs * 0.45)
+        rise = int(fs * 0.5)
+        pop = f"min(1,(t-{s:.3f})/0.25)"
+        xe = f"{m_left}" if "left" in pos else f"w-text_w-{m_right}"
+        ye = (f"{m_top}+{rise}*(1-{pop})" if "top" in pos else f"h-text_h-{m_bottom}-{rise}*(1-{pop})")
+        alpha = f"min({pop},{fade_a})"
+        filters.append(f"drawtext=text='{escape_drawtext(args.text)}':{fo}:fontsize={fs}:fontcolor={ff_color(bg)}:"
+                       f"x={xe}:y='{ye}':box=1:boxcolor={ff_color(primary, 0.95)}:boxborderw={drawtext_boxborderw(pady, padx)}:"
+                       f"alpha='{alpha}':{en}")
+
+    elif args.template == "hook":
+        # The opener: a full-width card over the first --duration seconds with a thin bar along
+        # the top that empties as the card's time runs out, so the viewer sees how long it lasts.
+        if not args.title:
+            die("hook needs --title")
+        if args.duration <= 0:
+            die(f"--duration must be > 0, got {args.duration:g}")
+        he = min(e, s + args.duration)
+        hen = f"enable='between(t,{s:.3f},{he:.3f})'"
+        h1 = int(base * 0.085)
+        bar_h = max(3, int(base * 0.01))
+        band_h = int(base * 0.30)
+        y0 = (H - band_h) // 2
+        filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
+        filters.append(f"drawtext=text='{escape_drawtext(args.title)}':{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
+                       f"x=(w-text_w)/2:y=(h-text_h)/2:{hen}")
+        filters.append(f"drawbox=x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}:"
+                       f"color={ff_color(primary)}:t=fill:{hen}")
+
+    elif args.template == "meme":
+        # The classic layout: heavy white upper-case lines with a black outline, top and bottom,
+        # sized so a short line fills the frame's width without wrapping (drawtext never wraps).
+        if not (args.top or args.bottom):
+            die("meme needs --top and/or --bottom")
+        fs = int(base * 0.09)
+        bw = max(2, int(fs / 12))
+        white, black = ff_color("FFFFFF"), ff_color("000000")
+        for text, y in ((args.top, f"{m_top}"), (args.bottom, f"h-text_h-{m_bottom}")):
+            if not text:
+                continue
+            filters.append(f"drawtext=text='{escape_drawtext(text.upper())}':{fo}:fontsize={fs}:fontcolor={white}:"
+                           f"borderw={bw}:bordercolor={black}:x=(w-text_w)/2:y={y}:{en}")
+
     elif args.template == "countdown":
         n = args.count_from
         seg = (e - s) / (n + 1)

package/scripts/look.py

@@ -7,6 +7,7 @@ Examples:
   python3 look.py final.mp4 --tiles 4x5 --width 1600
   python3 look.py final.mp4 --at 2.5 --at 7          # single frames -> final_2.500s.png, final_7.000s.png
   python3 look.py before.mp4 --compare after.mp4 --at 4   # side-by-side frame
+  python3 look.py reel.mp4 --safe tiktok --at 3          # shade what TikTok's own UI covers
 Then view the PNG (Read tool / image viewer) and verify before reporting.
 """
 import argparse
@@ -15,6 +16,7 @@ import sys
 from pathlib import Path
 from typing import List
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, resolve as resolve_platform
 from _common import STATE, add_common, apply_common, default_font_file, die, emit, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, time_arg
 
 FONT = "fontcolor=white:fontsize=h/18:box=1:boxcolor=black@0.55:boxborderw=6:x=8:y=8"
@@ -39,6 +41,8 @@ def main() -> int:
     ap.add_argument("--width", type=int, default=1280, help="total width of the sheet / compare image (default 1280)")
     ap.add_argument("--compare", help="second video: place its frame next to the first (needs --at)")
     ap.add_argument("--no-timecode", action="store_true")
+    ap.add_argument("--safe", choices=PLATFORM_CHOICES, help="shade the zones this platform's UI covers (its description bar, "
+                                                       "like column, status bar) so you can see whether anything readable is under them")
     add_common(ap)
     args = ap.parse_args()
     apply_common(args)
@@ -55,6 +59,37 @@ def main() -> int:
     default_font = default_font_file("DejaVu Sans")
     font_prefix = f"fontfile={escape_filter_path(default_font)}:" if default_font else ""
     tc = "" if args.no_timecode else "," + timecode_filter(font_prefix)
+    # --safe: the platform's occluded zones, drawn as shaded boxes in fractions of the frame so
+    # the same filter is right at any scale (a tile of a contact sheet as much as a full frame).
+    safe_filter = ""
+    args.safe = resolve_platform(args.safe)
+    if args.safe and not PLATFORMS[args.safe].get("frame"):
+        info(f"--safe {args.safe}: this destination has no frame and no app chrome; nothing to shade")
+        args.safe = None
+    if args.safe:
+        z = PLATFORMS[args.safe]["safe"]
+        frame = PLATFORMS[args.safe]["frame"]
+        src = meta["video"]
+        if src.get("width") and src.get("height") and abs(src["width"] / src["height"] - frame["w"] / frame["h"]) > 0.02:
+            info(f"--safe {args.safe}: this source is {src['width']}x{src['height']}, not {args.safe}'s "
+                 f"{frame['w']}x{frame['h']} -- the zones are drawn as fractions of the frame you gave, "
+                 f"so reframe first (fit.py --aspect) to see what the app really covers")
+        boxes = []
+        for edge, frac in (("top", z["top"]), ("bottom", z["bottom"]), ("left", z["left"]), ("right", z["right"])):
+            if frac <= 0:
+                continue
+            if edge == "top":
+                boxes.append(f"drawbox=x=0:y=0:w=iw:h=ih*{frac:g}:color=red@0.35:t=fill")
+            elif edge == "bottom":
+                boxes.append(f"drawbox=x=0:y=ih*(1-{frac:g}):w=iw:h=ih*{frac:g}:color=red@0.35:t=fill")
+            elif edge == "left":
+                boxes.append(f"drawbox=x=0:y=0:w=iw*{frac:g}:h=ih:color=red@0.20:t=fill")
+            else:
+                boxes.append(f"drawbox=x=iw*(1-{frac:g}):y=0:w=iw*{frac:g}:h=ih:color=red@0.20:t=fill")
+        safe_filter = "," + ",".join(boxes) if boxes else ""
+        info(f"--safe {args.safe}: shaded top {z['top'] * 100:.0f}% / bottom {z['bottom'] * 100:.0f}% / "
+             f"left {z['left'] * 100:.0f}% / right {z['right'] * 100:.0f}% of the frame -- keep text out of those")
+    tc = safe_filter + tc
     # HDR sources: tone-map for the PNG so the agent judges representative colours, not raw HLG/PQ
     if meta["video"].get("hdr"):
         v = meta["video"]