ffmpeg-skill 1.12.0 → 1.14.0

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)

package/scripts/audio.py

@@ -7,9 +7,12 @@ drops the picture, so `audio.py talk.mp4 -o talk.wav` is an extraction.
 Examples:
   python3 audio.py interview.mp4 --denoise                      # FFT noise reduction
   python3 audio.py interview.mp4 --voice                        # highpass + de-esser + compressor + denoise
+  python3 audio.py interview.mp4 --voice light                  # highpass + gentle compression only (light|medium|strong)
   python3 audio.py talk.mp4 --music bed.mp3 --duck              # music under speech, auto-ducked
   python3 audio.py talk.mp4 --music bed.mp3 --music-volume -18 --music-fade-out 3   # bed fades, voice does not
   python3 audio.py clip.mp4 --fade-in 0.5 --fade-out 1 --stereo
+  python3 audio.py talk.mp4 --music bed.mp3 --duck --duck-threshold -30 --duck-release 250   # ducks earlier and recovers faster
+  python3 audio.py band.wav --stereo-widen 0.5 -o wide.wav      # wider stereo image (a real stereo source; mono is refused)
   python3 audio.py surround.mov --downmix                       # 5.1 -> stereo with proper centre/LFE weights
   python3 audio.py clip.mp4 --replace narration.wav             # swap the audio track entirely
   python3 audio.py interview.mp4 -o interview.wav               # extract the audio (no video in the output)
@@ -18,12 +21,29 @@ Examples:
 """
 import argparse
 import sys
-from typing import List
+from typing import Any, Dict, List
 
 from _common import STATE, add_common, apply_common, audio_codec_for, db_to_linear, default_output, die, emit, ffmpeg_base, info, is_audio_output, probe, run, run_keeping_subtitles, fmt_secs
 
 VOICE_CHAIN = "highpass=f=80,deesser=i=0.4,afftdn=nf=-25:tn=1,acompressor=threshold=-18dB:ratio=3:attack=5:release=80:makeup=2"
 
+# --voice [light|medium|strong] (1.13). "medium" is the chain --voice has always produced, so a
+# bare --voice (and every existing call and MCP request) is byte-identical to before. "light"
+# leaves the noise floor and the sibilance alone -- it only removes rumble and evens the level,
+# which is what a good room recording needs; "strong" is for phone/laptop audio: a harder
+# de-esser, a second compression stage and a soft limiter at -1 dBFS so the peaks stop there
+# instead of at whatever the make-up gain produced.
+VOICE_LEVELS = {
+    "light": "highpass=f=80,acompressor=threshold=-18dB:ratio=2:attack=5:release=80:makeup=1",
+    "medium": VOICE_CHAIN,
+    "strong": VOICE_CHAIN + ",deesser=i=0.6,acompressor=threshold=-24dB:ratio=4:attack=5:release=120:makeup=3,alimiter=limit=0.891251:level=disabled",
+}
+
+# The sidechain threshold the music bed has used since 1.4 is the linear 0.05 that ffmpeg's
+# sidechaincompress takes; -26.0206 dBFS is that same number in the unit the flag speaks, so the
+# default command line is unchanged to the byte while the value is now sayable.
+DUCK_THRESHOLD_DB = -26.0206
+
 # Typed dynamics: every flag maps to one real option of one ffmpeg filter, validated against the
 # range that filter documents (ffmpeg -h filter=acompressor / alimiter / agate). dB flags are
 # converted to the linear value the filter takes, so no string reaches the graph unchecked.
@@ -79,13 +99,23 @@ def main() -> int:
     clean = ap.add_argument_group("clean-up")
     clean.add_argument("--denoise", action="store_true", help="FFT noise reduction (afftdn, adaptive)")
     clean.add_argument("--denoise-strength", type=float, default=25.0, help="noise floor in dB to remove, 10..60 (default 25)")
-    clean.add_argument("--voice", action="store_true", help="speech preset: highpass 80 Hz, de-esser, denoise, gentle compression")
+    clean.add_argument("--voice", nargs="?", const="medium", choices=["light", "medium", "strong"], default=None,
+                       help="speech preset (default medium when the flag is given bare): light = highpass 80 Hz + gentle compression; "
+                            "medium = highpass, de-esser, denoise, gentle compression; strong = medium plus a harder de-esser, a second "
+                            "compressor and a soft limiter at -1 dBFS. MCP/JSON callers may still send the 1.12 boolean true, "
+                            "which is the bare flag and so means medium")
     clean.add_argument("--gain", type=float, help="gain in dB applied to the main track")
     music = ap.add_argument_group("music")
     music.add_argument("--music", help="music file to mix underneath")
     music.add_argument("--music-volume", type=float, default=-14.0, help="music level in dB relative to full scale (default -14)")
     music.add_argument("--duck", action="store_true", help="auto-duck the music when the main track has speech (sidechain compressor)")
     music.add_argument("--duck-amount", type=float, default=12.0, help="how many dB to duck (default 12)")
+    music.add_argument("--duck-threshold", type=float, default=DUCK_THRESHOLD_DB,
+                       help="sidechain threshold in dBFS: the main track is heard as speech above this (default -26.02, the 0.05 linear used since 1.4)")
+    music.add_argument("--duck-attack", type=float, default=20.0, help="ms the bed takes to duck once speech starts (default 20)")
+    music.add_argument("--duck-release", type=float, default=400.0, help="ms the bed takes to come back up after speech (default 400)")
+    music.add_argument("--effects", help="a third track (sound effects/atmos) mixed in at --effects-volume; never ducked")
+    music.add_argument("--effects-volume", type=float, default=-14.0, help="effects level in dB relative to full scale (default -14)")
     music.add_argument("--music-loop", action="store_true", help="loop the music if shorter than the video")
     fades = ap.add_argument_group("fades / layout")
     fades.add_argument("--fade-in", type=float, default=0.0, help="seconds")
@@ -94,6 +124,10 @@ def main() -> int:
     channels = fades.add_mutually_exclusive_group()
     channels.add_argument("--stereo", action="store_true", help="force 2-channel output (mono is duplicated to both sides)")
     channels.add_argument("--mono", action="store_true", help="force 1-channel output")
+    fades.add_argument("--stereo-widen", type=float, default=None, metavar="AMOUNT",
+                       help="widen the stereo image, 0..1 (0 = untouched, 1 = maximum); needs a real stereo source: a mono input is "
+                            "refused (duplicating it leaves both channels identical, so there is nothing to widen) and more than two "
+                            "channels are refused unless --downmix folds them to stereo first")
     fades.add_argument("--downmix", action="store_true", help="downmix 5.1/7.1 to stereo using standard weights")
     fades.add_argument("--replace", help="replace the audio with this file (trimmed/padded to the video)")
     dyn = ap.add_argument_group("dynamics (typed; each flag is one option of ffmpeg's acompressor / alimiter / agate)")
@@ -124,6 +158,26 @@ def main() -> int:
         if not getattr(args, switch) and any(getattr(args, f) is not None for f in DYNAMICS[flag_group]):
             die(f"--{switch} is off but one of its parameters was given; add --{switch}")
 
+    # Same rule as the typed dynamics above, for the ducking knobs: a parameter for a switch that
+    # is off does nothing, and a caller who says --duck-release 250 and gets the default 400 ms has
+    # no way to notice. --duck itself needs a bed to duck.
+    duck_params = [f"--duck-{name}" for name in ("threshold", "attack", "release")
+                   if getattr(args, f"duck_{name}") != ap.get_default(f"duck_{name}")] + \
+                  (["--duck-amount"] if args.duck_amount != ap.get_default("duck_amount") else [])
+    if not args.duck and duck_params:
+        die(f"--duck is off but {duck_params[0]} was given; add --duck")
+    if args.duck and not args.music:
+        die("--duck ducks the music bed under the main track, but no --music was given; add --music FILE")
+
+    for flag, value, lo, hi in (("--duck-amount", args.duck_amount, 0.0, 60.0),
+                                ("--duck-threshold", args.duck_threshold, -60.0, 0.0),
+                                ("--duck-attack", args.duck_attack, 0.01, 2000.0),
+                                ("--duck-release", args.duck_release, 0.01, 9000.0)):
+        if not (lo <= value <= hi):
+            die(f"{flag} {value:g} is outside {lo:g}..{hi:g} (the range ffmpeg's sidechaincompress accepts)")
+    if args.stereo_widen is not None and not (0.0 <= args.stereo_widen <= 1.0):
+        die(f"--stereo-widen must be 0..1 (0 = untouched, 1 = maximum), got {args.stereo_widen:g}")
+
     meta = probe(args.input)
     dur = meta.get("duration") or 0.0
     has_video = bool(meta.get("video"))
@@ -136,6 +190,19 @@ def main() -> int:
         die(f"--audio-stream {args.audio_stream}: input has {len(streams)} audio stream(s), 0..{len(streams) - 1}")
     if args.audio_stream and not streams and not STATE.dry_run:
         die("--audio-stream needs an input with audio streams")
+    in_channels = (meta.get("audio") or {}).get("channels") or 0
+    if args.stereo_widen is not None:
+        if args.mono:
+            die("--stereo-widen and --mono contradict each other: there is no stereo image in a 1-channel output")
+        # Widening scales the side signal (L-R). Duplicating a mono track to two channels leaves
+        # L == R, so the side signal is exactly zero and scaling it changes nothing: --stereo is
+        # not a way in, it is a way to a file that measures mono no matter the amount asked for.
+        if in_channels == 1:
+            die("--stereo-widen needs a real stereo source: mono has no stereo image to widen; keep it mono or "
+                "use --stereo to duplicate it, but widening needs a real stereo source")
+        if in_channels > 2 and not args.downmix:
+            die(f"--stereo-widen needs a stereo track; this input has {in_channels} channels. Add --downmix to fold it "
+                "to stereo first (the widening then happens after the downmix), or leave the channels alone.")
 
     inputs: List[str] = ["-i", args.input]
     main_src = f"0:a:{args.audio_stream}"
@@ -150,7 +217,7 @@ def main() -> int:
     if args.downmix:
         fx.append("pan=stereo|FL=0.707*FC+FL+0.5*BL+0.5*SL+0.5*LFE|FR=0.707*FC+FR+0.5*BR+0.5*SR+0.5*LFE")
     if args.voice:
-        fx.append(VOICE_CHAIN)
+        fx.append(VOICE_LEVELS[args.voice])
     elif args.denoise:
         if not 10 <= args.denoise_strength <= 60:
             die(f"--denoise-strength must be 10..60 (dB of noise floor to remove), got {args.denoise_strength:g}")
@@ -172,6 +239,11 @@ def main() -> int:
         # 1 channel: already mono; the stereo pan used to halve it (-6 dB) because c1 was silence
     elif args.stereo:
         fx.append("aformat=channel_layouts=stereo")
+    if args.stereo_widen is not None:
+        # extrastereo widens by scaling the side (L-R) signal: m=1 is the input, m=3 is as wide
+        # as it goes before the centre collapses. It runs after the channel layout is settled, so
+        # a --downmix 5.1 source is widened on the stereo fold-down rather than on six channels.
+        fx.append(f"extrastereo=m={1 + 2 * args.stereo_widen:g}")
 
     graph: List[str] = []
     graph.append(f"[{main_src}]{','.join(fx) if fx else 'anull'}[main]")
@@ -192,13 +264,26 @@ def main() -> int:
         if args.duck:
             graph.append("[main]asplit=2[mainA][sc]")
             graph.append(
-                f"[music][sc]sidechaincompress=threshold=0.05:ratio={max(2.0, args.duck_amount / 3):.1f}:attack=20:release=400:makeup=1[ducked]"
+                f"[music][sc]sidechaincompress=threshold={db_to_linear(args.duck_threshold):.6g}"
+                f":ratio={max(2.0, args.duck_amount / 3):.1f}:attack={args.duck_attack:g}:release={args.duck_release:g}:makeup=1[ducked]"
             )
             graph.append("[mainA][ducked]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
         else:
             graph.append("[main][music]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mix]")
         last = "mix"
 
+    if args.effects:
+        # A third bed, mixed in at its own level and deliberately never ducked: effects are cut
+        # to the picture, so dipping them under speech would move them off their own frames.
+        probe(args.effects)
+        inputs += ["-i", args.effects]
+        e = f"{idx}:a:0"
+        idx += 1
+        efx = [f"volume={args.effects_volume:g}dB", f"atrim=0:{dur:.3f}" if dur else "anull"]
+        graph.append(f"[{e}]{','.join(efx)}[effects]")
+        graph.append(f"[{last}][effects]amix=inputs=2:duration=first:dropout_transition=2:normalize=0[mixfx]")
+        last = "mixfx"
+
     post: List[str] = []
     if args.fade_in:
         post.append(f"afade=t=in:st=0:d={args.fade_in:g}")
@@ -237,7 +322,16 @@ def main() -> int:
         die(f"{output} unexpectedly contains a video stream")
     info(f"wrote {output} ({fmt_secs(r['duration'])}, audio {a['codec']} {a['channels']}ch {a['sample_rate']}Hz"
          + (", video stream-copied" if has_video and not audio_out else ", video dropped" if has_video else "") + ")")
-    emit(output, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
+    audio_block: Dict[str, Any] = {"voice": args.voice, "stereo_widen": args.stereo_widen,
+                                   "effects": bool(args.effects), "effects_volume": args.effects_volume if args.effects else None}
+    if args.music:
+        audio_block["music_volume"] = args.music_volume
+        audio_block["duck"] = ({"amount_db": args.duck_amount, "threshold_db": round(args.duck_threshold, 4),
+                                "threshold_linear": float(f"{db_to_linear(args.duck_threshold):.6g}"),
+                                "ratio": round(max(2.0, args.duck_amount / 3), 1),
+                                "attack_ms": args.duck_attack, "release_ms": args.duck_release}
+                               if args.duck else None)
+    emit(output, audio=audio_block, video=bool(has_video and not audio_out), audio_stream=args.audio_stream,
          dynamics=[f for f in (args.gate and "agate", args.compress and "acompressor", args.limit and "alimiter") if f],
          dropped_non_av_streams=dropped_streams)
     return 0

package/scripts/caption.py

@@ -40,6 +40,7 @@ import unicodedata
 from pathlib import Path
 from typing import List, Optional, Tuple
 
+from _platforms import PLATFORMS, PLATFORM_CHOICES, ass_units, resolve as resolve_platform
 from _common import STATE, brand_states_font, char_script, script_font_for_text, signed_time_arg, brand_caption_style, color_hex, load_brand, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_filter_path, ffmpeg_base, fmt_srt_time, fmt_smpte_time, info, MissingFpsError, parse_time, probe, run, x264_args, X264_PRESETS, read_text_or_die, fmt_secs
 
 ALIGN = {"bottom": 2, "top": 8, "center": 5, "bottom-left": 1, "bottom-right": 3, "top-left": 7, "top-right": 9}
@@ -759,7 +760,10 @@ def main() -> int:
     sty.add_argument("--shadow", type=float, default=0.0, help="shadow depth (default 0)")
     sty.add_argument("--bold", action="store_true")
     sty.add_argument("--position", choices=sorted(ALIGN), default=None, help="on-screen placement (default bottom)")
-    sty.add_argument("--margin", type=int, default=30, help="vertical margin from the edge (default 30)")
+    sty.add_argument("--margin", type=int, default=None, help="vertical margin from the edge in ASS units (default 30, or the --platform safe zone)")
+    sty.add_argument("--platform", choices=PLATFORM_CHOICES, default=None,
+                     help="keep the captions out of this destination's UI: the margin becomes the platform's safe "
+                          "zone (TikTok's description bar, the Reels/Shorts chrome). An explicit --margin/--position wins")
     sty.add_argument("--box", action="store_true", help="draw an opaque box behind text instead of an outline")
     sty.add_argument("--max-lines", type=int, default=2, help="most lines one cue may occupy; a longer cue is split into consecutive cues (default 2)")
     sty.add_argument("--min-duration", type=float, default=1.0, help="shortest time a cue stays on screen in seconds, never past the next cue (default 1.0)")
@@ -792,6 +796,18 @@ def main() -> int:
     args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))
     args.outline = args.outline if args.outline is not None else (float(bcap.get("outline", 2)) if args.brand else 2.0)
     args.position = args.position or (bcap.get("position", "bottom") if args.brand else "bottom")
+    # --platform: the margin is the fraction of the frame that platform's own UI covers
+    # (scripts/_platforms.py). An explicit --margin is the more specific statement and wins;
+    # without either, the historical default 30 is unchanged.
+    # every tool resolves the spellings people write ('youtube-shorts' is 'shorts') in one place
+    args.platform = resolve_platform(args.platform)
+    if args.margin is None and args.platform and PLATFORMS[args.platform].get("frame"):
+        edge = PLATFORMS[args.platform]["safe"]["top" if args.position.startswith("top") else "bottom"]
+        args.margin = ass_units(edge)
+        info(f"--platform {args.platform}: caption margin {args.margin} ASS units ({edge * 100:.0f}% of the frame height, "
+             f"clear of the app's own UI)")
+    if args.margin is None:
+        args.margin = 30
     # a brand's caption.animate is a burn-in default; over --mode mux (soft subtitles) it used
     # to be applied anyway and then refused as "animation is burn only" -- ignore it there
     args.animate = args.animate or (bcap.get("animate", "none") if args.brand and args.mode != "mux" else "none")

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"):
@@ -162,6 +159,21 @@ def main() -> int:
 
     if a:
         row("audio", "PASS", f"{a.get('codec')} {a.get('channels')}ch {a.get('sample_rate')}Hz", "present")
+        if args.platform == "podcast":
+            # Podcast rows, informational: neither can fail a delivery, both are things a
+            # publisher notices after the fact. A 5.1 podcast master is the common one -- every
+            # player downmixes it, none of them the same way, and the centre-heavy dialogue
+            # comes back at a level nobody checked.
+            ch = a.get("channels") or 0
+            row("channels", "PASS" if ch in (1, 2) else "WARN", f"{ch}ch", "1 (mono) or 2 (stereo)",
+                "audio.py --downmix (5.1/7.1 to stereo with the standard weights) or audio.py --mono",
+                reason="podcast players downmix 5.1 unpredictably")
+    if args.platform == "podcast":
+        chapters = meta.get("chapters") or []
+        row("chapters", "PASS" if chapters else "WARN", f"{len(chapters)}" if chapters else "none", ">= 1 chapter marker",
+            "metadata.py episode.m4a --chapters chapters.txt (`TIME TITLE` per line; streams copied)",
+            reason="chapter markers are optional, but a podcast app shows them as the episode's seekable table of contents")
+    if a:
         if a.get("sample_rate") and a["sample_rate"] not in (44100, 48000):
             row("sample rate", "WARN", a["sample_rate"], "44100 or 48000", "loudness.py --sample-rate 48000")
         if not args.no_loudness and spec["lufs"] is not None: