Skip to content

Local video editor for coding agents: 42 FFmpeg tools with a machine-readable contract and an MCP server, for Claude Code, Cursor and Codex. Cut, captions, reframe, loudness, platform exports. No cloud, no API keys.

30.7 KB
Raw Blame
#!/usr/bin/env python3
"""Composite a logo/image or a text title onto a video with position, timing,
opacity and fade in/out.

Positions: top-left, top, top-right, left, center, right, bottom-left, bottom,
bottom-right, or explicit "X,Y" pixels (negative counts from the far edge).

--video composites a second VIDEO as a picture-in-picture layer (position,
scale, opacity, time-range -- same knobs as --image), instead of a still
image or text. --place SRC_START-SRC_END@AT (repeatable, with --video) shows only
that range of the layer, starting at AT on the main timeline: one pass lays
several pieces of a layer (say, graphics rendered back to back) at their own
times, and the main picture shows untouched everywhere else. Only the main input's audio is kept; the PiP layer's own
audio track, if any, is dropped -- mixing two audio tracks is a job for
audio.py, not this tool. --chromakey COLOR (with --video) turns that colour
transparent first (green-screen removal) before compositing.

Examples:
  python3 overlay.py input.mp4 --image logo.png --position top-right --scale 200 --opacity 0.8
  python3 overlay.py input.mp4 --image lower_third.png --position bottom-left --start 2 --end 8 --fade 0.5
  python3 overlay.py input.mp4 --text "Episode 12" --position bottom --font-size 48 --start 1 --end 5 --fade 0.3
  python3 overlay.py input.mp4 --text "こんにちは" --font-file /path/NotoSansCJK-Bold.ttc --box
  python3 overlay.py input.mp4 --video webcam.mp4 --position bottom-right --scale 480 --opacity 0.9
  python3 overlay.py bg.mp4 --video greenscreen.mp4 --chromakey 0x00ff00 --chromakey-similarity 0.15
  python3 overlay.py talk.mp4 --video cues.mov --position 0,0 --margin 0 --place 0-2.5@12 --place 2.5-6@40
"""
import argparse
import re
import sys
from typing import List, Optional

from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
from _common import STATE, script_font_for_text, drawtext_clean, drawtext_line_metrics, drawtext_text_opts, drawtext_draws_newline_glyph, is_multiline, needs_shaping, LANGUAGE_NAMES, has_emoji, detect_script, emoji_clusters, load_brand, drawn_chain, label_chain, matrix_chain, rgb_chain_to_bt709, video_args, add_common, apply_common, emit, aac_args, cfr_args, default_output, die, escape_drawtext, escape_filter_path, ffmpeg_base, info, parse_time, probe, run, run_keeping_subtitles, validate_color, x264_args, X264_PRESETS, time_arg, fmt_secs
from _common.emit import warn
from _common.fonts import font_choice, record_font_choice

# Per-edge margins: a platform's UI does not cover the same fraction of every edge (TikTok's
# like column is 14 % of the width, its description block 22 % of the height), so a position
# names the edges it is measured from rather than one --margin for all four.
POS = {
    "top-left": ("{left}", "{top}"),
    "top": ("(W-w)/2", "{top}"),
    "top-right": ("W-w-{right}", "{top}"),
    "left": ("{left}", "(H-h)/2"),
    "center": ("(W-w)/2", "(H-h)/2"),
    "right": ("W-w-{right}", "(H-h)/2"),
    "bottom-left": ("{left}", "H-h-{bottom}"),
    "bottom": ("(W-w)/2", "H-h-{bottom}"),
    "bottom-right": ("W-w-{right}", "H-h-{bottom}"),
}


def position_exprs(pos: str, margin: int, text_mode: bool, margins: Optional[dict] = None):
    edges = margins or {}
    m = {edge: int(edges.get(edge, margin)) for edge in ("top", "bottom", "left", "right")}
    if pos in POS:
        x, y = (e.format(**m) for e in POS[pos])
    else:
        try:
            xs, ys = pos.split(",")
            xv, yv = int(xs), int(ys)
        except ValueError:
            die(f"bad --position '{pos}'")
        x = f"W-w{xv}" if xv < 0 else str(xv)
        y = f"H-h{yv}" if yv < 0 else str(yv)
    if text_mode:
        # drawtext uses w/h for the text box but lower-case main dims differ: W/H -> w/h, w/h -> text_w/text_h
        x = x.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
        y = y.replace("W", "main_w").replace("w", "text_w").replace("H", "main_h").replace("h", "text_h")
        x = x.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
        y = y.replace("main_text_w", "main_w").replace("main_text_h", "main_h")
    return x, y


def enable_expr(start: Optional[float], end: Optional[float]) -> str:
    if start is None and end is None:
        return ""
    s = f"{start:.3f}" if start is not None else "0"
    if end is None:
        return f"gte(t,{s})"
    return f"between(t,{s},{end:.3f})"


def alpha_expr(opacity: float, start: Optional[float], end: Optional[float], fade: float) -> str:
    """Time-varying alpha with linear fade in/out inside [start, end]."""
    if fade <= 0 or (start is None and end is None):
        return f"{opacity:g}"
    s = start if start is not None else 0.0
    parts = [f"{opacity:g}"]
    fin = f"min(1,(t-{s:.3f})/{fade:g})"
    parts.append(fin)
    if end is not None:
        parts.append(f"min(1,({end:.3f}-t)/{fade:g})")
    return "max(0," + "*".join(parts) + ")"


def _num(v: float) -> str:
    """A measured pixel value as an expression literal (no exponent form)."""
    return f"{v:.6f}".rstrip("0").rstrip(".")


def per_line_drawtext(lines: List[str], x: str, y: str, font_opt: str, args: argparse.Namespace,
                      box: List[str], timing: List[str]) -> str:
    """The drawtext chain for a multi-line --text on a release whose drawtext draws a box at each
    line break (drawtext_draws_newline_glyph): one drawtext per line, each line alone, placed
    where one multi-line drawtext puts it on a fixed release.

    That block's layout is drawtext's own (measure_text/draw_text): text_w is the widest line,
    text_h = lh*(lines-1) + the first line's top_a + the last line's bottom_d, the lines are
    left-aligned at x, and line i's baseline is y + top_a + i*lh. Each line is measured alone
    (drawtext_line_metrics), so the box the bug adds is in no number; x and y keep the caller's
    position expressions with text_w/text_h replaced by the block's values, and each line is
    drawn with y_align=baseline at its own baseline. The outlines of every line are drawn before
    any line's text, as one drawtext draws them, so a descender's outline never covers the next
    line's glyphs; the --box is drawn once, by the first line, at the block's size (boxw/boxh).
    Bit-identical to one multi-line drawtext on 8.1.3 for every named position, with and without
    --box; a font whose glyph boxes are not whole pixels (no hinting) can sit one row lower, since
    drawtext reports top_a rounded up."""
    m = drawtext_line_metrics(lines, font_opt, args.font_size)
    seen = [d for d in m if d]
    lh = seen[0]["lh"]
    width = max(d["w"] for d in seen)
    # an empty first/last line has no glyphs: drawtext's -32000/64 start values, as it measures them
    top = m[0]["top"] if m[0] else -500.0
    bottom = m[-1]["bottom"] if m[-1] else -500.0
    height = lh * (len(lines) - 1) + top + bottom

    def block(expr: str) -> str:
        return re.sub(r"\btext_h\b", _num(height), re.sub(r"\btext_w\b", _num(width), expr))

    bx, by = block(x), block(y)
    passes = ([[f"borderw={args.border}", f"bordercolor={args.border_color}", "fontcolor=black@0"],
               ["fontcolor=" + args.font_color]] if args.border else [["fontcolor=" + args.font_color]])
    filters = []
    for n, paint in enumerate(passes):
        for i, line in enumerate(lines):
            if not line:
                continue
            opts = [drawtext_text_opts(line), f"fontsize={args.font_size}", f"x={bx}", f"y={by}+{_num(top + i * lh)}",
                    "y_align=baseline", font_opt] + paint + timing[:1]
            if box and n == 0 and not filters:
                opts += box + [f"boxw={_num(width)}", f"boxh={_num(height)}"]
            filters.append("drawtext=" + ":".join(opts + timing[1:]))
    return ",".join(filters)


# one time inside --place: seconds, mm:ss, hh:mm:ss.ms or hh:mm:ss:ff with an optional @fps
# suffix (the time grammar's own); times are never negative, so '-' only separates the range
_PLACE_TIME = r"[^@\-]+(?:@[0-9.]+)?"


def parse_placements(specs: List[str], main_fps: Optional[float], layer_fps: Optional[float]) -> List[tuple]:
    """--place SRC_START-SRC_END@AT -> [(src_start, src_end, at)], refusing empty, negative or
    overlapping placements (two pieces on screen at once would stack in an order nobody asked for).
    SRC_START/SRC_END are positions in the layer, so an hh:mm:ss:ff timecode there counts the
    layer's frames; AT is a position on the main timeline and counts the main video's."""
    out = []
    for spec in specs:
        m = re.fullmatch(rf"\s*({_PLACE_TIME})-({_PLACE_TIME})@({_PLACE_TIME})\s*", spec)
        if not m:
            die(f"--place {spec!r}: use SRC_START-SRC_END@AT, e.g. 0-2.5@12 (times are not negative)")
        a = time_arg(m.group(1), "--place", layer_fps)
        b = time_arg(m.group(2), "--place", layer_fps)
        at = time_arg(m.group(3), "--place", main_fps)
        if b <= a:
            die(f"--place {spec!r}: the layer range ends before it starts")
        out.append((a, b, at))
    spans = sorted((at, at + (b - a)) for a, b, at in out)
    for (s1, e1), (s2, _e2) in zip(spans, spans[1:]):
        if s2 < e1 - 1e-6:
            die(f"--place: pieces overlap on the main timeline ({s1:g}-{e1:g} s and from {s2:g} s)")
    return out


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    ap.add_argument("input")
    ap.add_argument("-o", "--output", help="output file (default: <name>_overlay.<ext>)")
    ap.add_argument("--audio-stream", type=int, default=0,
                     help="which audio stream of the input to keep, 0-based in file order (probe.py lists them under "
                          "audio_streams) -- matters on a multi-track input (dubbed languages, M&E stems); default 0, "
                          "the first track, same as leaving it unset always did")
    src = ap.add_mutually_exclusive_group()
    src.add_argument("--image", help="PNG/JPG (alpha respected) to composite")
    src.add_argument("--text", help="text to draw (drawtext)")
    src.add_argument("--logo", action="store_true", help="composite the brand logo from --brand (position/scale/opacity from brand.json)")
    src.add_argument("--video", help="a second video to composite as a picture-in-picture layer")
    ap.add_argument("--place", action="append", default=[], metavar="SRC_START-SRC_END@AT",
                    help="with --video, repeatable: show this range of the layer starting at AT on the main "
                         "timeline (e.g. 0-2.5@12); the layer is hidden outside its placed ranges. Times in "
                         "seconds or HH:MM:SS. Not with --start/--end/--fade")
    ck = ap.add_argument_group("chroma key (with --video)")
    ck.add_argument("--chromakey", help="colour to key out (green-screen removal), e.g. 0x00ff00 or green")
    ck.add_argument("--chromakey-similarity", type=float, default=0.15, help="how close a pixel must be to --chromakey to become transparent, 0..1 (default 0.15)")
    ck.add_argument("--chromakey-blend", type=float, default=0.05, help="soften the key edge, 0..1 (default 0.05)")
    ap.add_argument("--brand", help="brand.json (logo, font, colours, safe margin)")
    ap.add_argument("--position", default="top-right", help="named position or X,Y (default top-right)")
    ap.add_argument("--margin", type=int, default=24, help="margin from the edges in px (default 24)")
    ap.add_argument("--platform", choices=PLATFORM_CHOICES, default=None,
                    help="keep the overlay out of this destination's UI: each edge's margin becomes that "
                         "platform's safe zone (scripts/_platforms.py), so a top-left logo clears TikTok's "
                         "status bar and a right-hand one clears the like column. An explicit --margin wins")
    ap.add_argument("--start", help="show from this time (default: whole video)")
    ap.add_argument("--end", help="hide after this time")
    ap.add_argument("--fade", type=float, default=0.0, help="fade-in duration in seconds (at --start or 0); the fade-out happens only at --end")
    ap.add_argument("--opacity", type=float, default=1.0, help="0..1 (default 1)")
    img = ap.add_argument_group("image options")
    img.add_argument("--scale", type=int, help="width in px for an image, logo or video layer (keeps aspect); text size is --font-size")
    img.add_argument("--scale-percent", type=float,
                     help="width as a %% of the displayed frame for an image, logo or video layer (keeps aspect); "
                          "a 90 or 270 degree rotation uses the stored height; text size is --font-size")
    txt = ap.add_argument_group("text options")
    txt.add_argument("--font", default="DejaVu Sans", help="fontconfig font name")
    txt.add_argument("--font-file", help="explicit .ttf/.otf/.ttc path (use this for CJK fonts)")
    txt.add_argument("--font-size", type=int, default=42)
    txt.add_argument("--font-color", default="white")
    txt.add_argument("--border", type=int, default=2, help="text outline width (default 2)")
    txt.add_argument("--border-color", default="black")
    txt.add_argument("--box", action="store_true", help="draw a translucent box behind the text")
    emo = ap.add_argument_group("emoji (1.15)")
    emo.add_argument("--emoji", choices=["auto", "color", "png", "mono", "none"], default="auto",
                     help="how emoji in --text are drawn. overlay.py draws through drawtext, which cannot load "
                          "a colour emoji font at all, so only 'mono'/'none' render here -- 'png'/'color' name "
                          "caption.py/graphics.py instead")
    emo.add_argument("--emoji-assets", metavar="DIR", help="directory of emoji PNGs named by code point "
                                                           "(used by caption.py/graphics.py; overlay.py has no PNG route)")
    emo.add_argument("--emoji-scale", type=float, default=1.0, help="emoji box as a multiple of the font size")
    emo.add_argument("--emoji-max", type=int, default=60, help="most emoji overlays one run may build")
    txt.add_argument("--box-color", default="[email protected]")
    enc = ap.add_argument_group("encoding")
    enc.set_defaults(crf=18)  # --quality's default (the --crf alias was removed in 2.0)
    enc.add_argument("--preset", default="medium", choices=X264_PRESETS)
    add_common(ap)
    args = ap.parse_args()
    apply_common(args)

    brand = load_brand(args.brand)
    if args.logo:
        if not brand.get("logo"):
            die("--logo needs a brand.json with a 'logo' entry")
        args.image = brand["logo"]
        if args.position == ap.get_default("position"):
            args.position = brand.get("logo_position", "top-right")
        if not args.scale and not args.scale_percent:
            args.scale = int(brand.get("logo_scale", 160))
        if args.opacity == 1.0:
            args.opacity = float(brand.get("logo_opacity", 1.0))
    if args.text is not None and not args.text.strip():
        die("--text is blank -- give the words to draw", kind="input")
    if not (args.image or args.text or args.video):
        die("give --image, --text, --logo or --video")
    # --scale is a layer width. On a text draw it used to be accepted and ignored (fontsize stayed
    # at --font-size), so a project that asked for 200 px text completed with the 42 px default.
    if args.text and not (args.image or args.video) and (args.scale is not None or args.scale_percent is not None):
        die("--scale and --scale-percent size an image, logo or video layer; text size is --font-size", kind="input")
    if args.brand:
        if args.margin == ap.get_default("margin"):
            args.margin = int(brand.get("safe_margin", args.margin))
        if args.font == ap.get_default("font"):
            args.font = brand.get("font", args.font)
        if not args.font_file and brand.get("font_file"):
            args.font_file = brand["font_file"]
    if args.text:
        # 1.15: drawtext never reorders or re-clusters (no harfbuzz), so Devanagari matras and
        # Thai/Lao mark stacking come out wrong on EVERY build. A wrong frame is not a delivery:
        # refuse and name the two tools that render the script correctly through libass.
        _sc = detect_script(args.text, getattr(args, "lang", None))
        if needs_shaping(_sc):
            die(f"{LANGUAGE_NAMES.get(_sc, _sc)} text cannot be shaped by drawtext on any ffmpeg build "
                "(the marks are reordered by harfbuzz, which drawtext does not use): draw it with "
                "caption.py (--text cues, burned through libass) or graphics.py (--template with "
                "--text-render ass) instead", kind="input")
        if has_emoji(args.text):
            if args.emoji in ("png", "color"):
                die(f"--emoji {args.emoji}: overlay.py draws text with drawtext, which cannot load a colour "
                    "emoji font and cannot place a PNG inside a line -- use caption.py (--emoji-assets) for "
                    "cues or graphics.py (--template) for a title card", kind="input")
            if args.emoji == "none":
                for _i, _cl in list(reversed(emoji_clusters(args.text))):
                    args.text = args.text[:_i] + args.text[_i + len(_cl):]
                warn("emoji: stripped from the drawn text (--emoji none)", "emoji_stripped", mode="none")
            else:
                warn("emoji are drawn by the text font here (monochrome at best); "
                     "caption.py/graphics.py composite colour PNGs with --emoji-assets", "emoji_monochrome")
    script_file = script_family = None
    if args.text and not args.font_file:
        # 1.12: non-Latin overlay text picks a font by script, so a title in Japanese, Korean,
        # Arabic ... draws glyphs instead of boxes. drawtext does not shape or reorder RTL text --
        # see references/gotchas.md#fonts-by-script.
        _script, script_file, script_family = script_font_for_text(
            args.text, font=args.font, font_explicit=args.font != ap.get_default("font"), font_file=args.font_file)
    # the font drawtext gets, reported as `font_used` and recorded when it is not the one asked for
    font_used = font_choice(args.font, font_file=args.font_file, script_file=script_file, script_family=script_family)
    args.font_file = font_used["file"]
    if args.text:
        record_font_choice(font_used)
    meta = probe(args.input)
    if not meta.get("video"):
        die("input has no video stream")
    audio_streams = meta.get("audio_streams") or []
    if audio_streams and not (0 <= args.audio_stream < len(audio_streams)):
        die(f"--audio-stream {args.audio_stream}: input has {len(audio_streams)} audio stream(s), 0..{len(audio_streams) - 1}")
    if args.audio_stream and not audio_streams:
        die("--audio-stream needs an input with audio streams")
    vw = meta["video"]["width"] or 0
    vh = meta["video"].get("height") or 0
    # ffmpeg applies display rotation before the filter graph, so the frame this overlay is
    # composited on is the displayed one. A 320x180 phone file tagged 90 degrees is 180 wide here.
    if meta["video"].get("rotation") in (90, -90, 270, -270):
        vw, vh = vh, vw
    # --platform: the edges this destination's own UI covers, in pixels of this frame. An
    # explicit --margin (or a brand safe_margin, applied above) is the more specific statement
    # and wins; without either, the historical 24 px default is unchanged.
    safe_margins = None
    args.platform = resolve_platform(args.platform)
    if args.platform and args.margin == ap.get_default("margin") and PLATFORMS[args.platform].get("frame"):
        # a dry run has no real frame to measure (the probe is stubbed rather than guessed), so
        # fall back to the destination's own delivery frame -- which is what the fitted
        # intermediate this stage runs on will be anyway
        frame = PLATFORMS[args.platform]["frame"]
        pw, ph = vw or frame["w"], vh or frame["h"]
        safe_margins = safe_margins_px(args.platform, pw, ph)
        info(f"--platform {args.platform}: safe margins top {safe_margins['top']} / bottom {safe_margins['bottom']} / "
             f"left {safe_margins['left']} / right {safe_margins['right']} px (clear of the app's own UI)")
    fps = meta["video"].get("fps")
    start = time_arg(args.start, "--start", fps) if args.start else None
    end = time_arg(args.end, "--end", fps) if args.end else None
    if start is not None and end is not None and end <= start:
        die("--end must be after --start")
    if not 0 <= args.opacity <= 1:
        die("--opacity must be within 0..1")
    if args.chromakey and not args.video:
        die("--chromakey needs --video")
    if args.chromakey:
        validate_color(args.chromakey, "--chromakey")
    validate_color(args.font_color, "--font-color")
    validate_color(args.border_color, "--border-color")
    validate_color(args.box_color, "--box-color")
    if not 0 < args.chromakey_similarity <= 1:
        die("--chromakey-similarity must be within (0, 1]")
    if not 0 <= args.chromakey_blend <= 1:
        die("--chromakey-blend must be within 0..1")
    if args.place and not args.video:
        die("--place needs --video")
    if args.place and (args.start or args.end or args.fade):
        die("--place sets when each piece shows: drop --start / --end / --fade")

    output = args.output or default_output(args.input, "overlay")
    enable = enable_expr(start, end)
    cmd = ffmpeg_base() + ["-i", args.input]

    if args.image:
        probe(args.image)
        chain: List[str] = ["format=rgba"]
        if args.scale_percent:
            chain.append(f"scale={int(vw * args.scale_percent / 100)}:-1")
        elif args.scale:
            chain.append(f"scale={args.scale}:-1")
        if args.opacity < 1:
            chain.append(f"colorchannelmixer=aa={args.opacity:g}")
        if args.fade > 0:
            # no --start: fade in at 0. The fade-out only exists when --end names a moment the
            # overlay leaves; without --end it stays to the last frame ("fade in at the start" is
            # the common ask, and a matching fade-out at the very end surprised every eval run)
            s = start if start is not None else 0.0
            chain.append(f"fade=t=in:st={s:.3f}:d={args.fade:g}:alpha=1")
            if end is not None and end > args.fade:
                chain.append(f"fade=t=out:st={end - args.fade:.3f}:d={args.fade:g}:alpha=1")
        x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
        ov = f"overlay={x}:{y}:format=auto"
        if enable:
            ov += f":enable='{enable}'"
        # -loop 1 turns the still into a timed stream so fade/enable expressions see real timestamps
        cmd = ffmpeg_base() + ["-i", args.input, "-loop", "1", "-i", args.image]
        # the RGBA still is converted to the BT.709 the output is tagged with (overlay's own
        # RGB-to-YUV step used BT.601), and an untagged main is labelled BT.709 (tags only) so
        # 7.1+'s negotiation does not convert one picture to the other's "unknown" matrix
        base = label_chain(meta, meta) if rgb_chain_to_bt709(meta) else ""
        fc = (f"[1:v]{','.join(chain)},setpts=PTS-STARTPTS{rgb_chain_to_bt709(meta)}[ov];"
              + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
        if meta.get("duration"):
            # An explicit -t is exact and, unlike -shortest, only bounds the *main* input's
            # streams -- a preserved subtitle/data stream that ends earlier (run_keeping_subtitles)
            # must not be allowed to cut the whole output short via -shortest's "stop at whichever
            # mapped stream finishes first" semantics.
            cmd += ["-t", f"{meta['duration']:.3f}"]
        else:
            # No known duration to bound by -t (e.g. probe found no video duration): -shortest is
            # the only thing stopping the looped still from running forever. FFmpeg 7+'s
            # shortest_buf_duration slack (up to 10s) is an accepted imprecision here since there is
            # no better bound available.
            cmd += ["-shortest"]
    elif args.video:
        pip_meta = probe(args.video)
        if not pip_meta.get("video"):
            die(f"--video {args.video} has no video stream")
        layer_fps = pip_meta["video"].get("fps")
        placements = parse_placements(args.place, fps, layer_fps) if args.place else []
        # bounds from the video streams (a longer audio track would let a range run past the last
        # picture); the container duration only when a stream has none
        layer_dur = pip_meta["video"].get("duration") or pip_meta.get("duration")
        main_dur = meta["video"].get("duration") or meta.get("duration")
        # half a layer frame of slack absorbs a hand-typed end that rounds the last frame's end
        # (2.033 for 61 frames at 30 fps); anything longer asks for pictures the layer does not have
        slack = 0.5 / layer_fps if layer_fps else 0.02
        for a, b, at in placements:
            if layer_dur and a >= layer_dur:
                # the slack below is for an end rounded past the last frame; a start there selects
                # no picture at all and the "placed" piece would silently never show
                die(f"--place {a:g}-{b:g}@{at:g}: starts at or after the layer's end ({layer_dur:.3f} s)")
            if layer_dur and b > layer_dur + slack:
                die(f"--place {a:g}-{b:g}@{at:g}: the layer is only {layer_dur:.3f} s long")
            if main_dur and at >= main_dur:
                die(f"--place {a:g}-{b:g}@{at:g}: starts after the main video ends ({main_dur:.3f} s)")
        chain = []
        if args.scale_percent:
            chain.append(f"scale={int(vw * args.scale_percent / 100)}:-2")
        elif args.scale:
            chain.append(f"scale={args.scale}:-2")
        chain.append("format=yuva420p")
        if args.chromakey:
            chain.append(f"chromakey={args.chromakey}:{args.chromakey_similarity:g}:{args.chromakey_blend:g}")
        if args.opacity < 1:
            chain.append(f"colorchannelmixer=aa={args.opacity:g}")
        x, y = position_exprs(args.position, args.margin, text_mode=False, margins=safe_margins)
        ov = f"overlay={x}:{y}:format=auto"
        if enable:
            ov += f":enable='{enable}'"
        cmd = ffmpeg_base() + ["-i", args.input, "-i", args.video]
        # both pictures converted by their own colour tags to the BT.709 the output is tagged with;
        # beside a converted one an untagged one gets its BT.709 label, tags only, so 7.1+'s
        # overlay does not convert one to the other's "unknown" (BT.601) matrix
        base, pip = matrix_chain(meta, meta), matrix_chain(pip_meta, meta)
        if base or pip:
            base, pip = base or label_chain(meta, meta), pip or label_chain(pip_meta, meta)
        if placements:
            # each placed piece: its range of the layer, re-timed to start at AT; eof_action=pass shows
            # the main picture untouched once a piece ends (the default would freeze its last frame)
            pieces = len(placements)
            # trim selects by timestamp: start the layer's at 0 so SRC_START/SRC_END count from its
            # first picture even when its video stream starts later than the file (audio first)
            fc = f"[1:v]setpts=PTS-STARTPTS,{pip}{','.join(chain)},split={pieces}" + "".join(f"[p{i}]" for i in range(pieces)) + ";"
            for i, (a, b, at) in enumerate(placements):
                fc += f"[p{i}]trim=start={a:.6f}:end={b:.6f},setpts=PTS-STARTPTS+{at:.6f}/TB[q{i}];"
            prev = f"[0:v]{base}null[m]" if base else None
            if prev:
                fc += prev + ";"
            cur = "[m]" if base else "[0:v]"
            for i in range(pieces):
                nxt = "[out]" if i == pieces - 1 else f"[m{i}]"
                fc += f"{cur}[q{i}]{ov}:eof_action=pass{nxt}" + ("" if i == pieces - 1 else ";")
                cur = nxt
        else:
            fc = (f"[1:v]{pip}{','.join(chain)}[ov];"
                  + (f"[0:v]{base}null[base];[base]" if base else "[0:v]") + f"[ov]{ov}[out]")
        cmd += ["-filter_complex", fc, "-map", "[out]", "-map", f"0:a:{args.audio_stream}?"]
        if meta.get("duration"):
            # See the --image branch above: -t (exact, bounds only the main input) instead of
            # -shortest (would also stop at a preserved subtitle/data stream that ends earlier).
            cmd += ["-t", f"{meta['duration']:.3f}"]
        else:
            cmd += ["-shortest"]
    else:
        x, y = position_exprs(args.position, args.margin, text_mode=True, margins=safe_margins)
        # 1.15: the text goes in a FILE with expansion off, so `'` and `%` survive verbatim
        # (they used to be dropped by escape_drawtext) and no character can reach the graph parser.
        font_opt = (f"fontfile={escape_filter_path(args.font_file)}" if args.font_file
                    else f"font='{escape_drawtext(args.font)}'")
        alpha = alpha_expr(args.opacity, start if start is not None else (0.0 if args.fade > 0 else None), end, args.fade)
        timing = ([f"alpha='{alpha}'"] if alpha != "1" else []) + ([f"enable='{enable}'"] if enable else [])
        box = ["box=1", f"boxcolor={args.box_color}", "boxborderw=12"] if args.box else []
        if is_multiline(args.text) and drawtext_draws_newline_glyph():
            # this release's drawtext draws the font's missing-glyph box at every line break and
            # counts it in text_w: one drawtext per line, placed where one block would put it
            drawing = per_line_drawtext(drawtext_clean(args.text).split("\n"), x, y, font_opt, args, box, timing)
        else:
            opts = [drawtext_text_opts(args.text), f"fontsize={args.font_size}", f"x={x}", f"y={y}",
                    f"borderw={args.border}", f"bordercolor={args.border_color}", font_opt,
                    f"fontcolor={args.font_color}"] + timing[:1] + box + timing[1:]
            drawing = "drawtext=" + ":".join(opts)
        # a font/border/box colour with chroma lands in the BT.709 the output is tagged with
        colours = [args.font_color] + ([args.border_color] if args.border else []) + ([args.box_color] if args.box else [])
        cmd += ["-vf", drawn_chain(drawing, meta, colours), "-map", "0:v:0"]
        if meta.get("audio"):
            cmd += ["-map", f"0:a:{args.audio_stream}"]

    cmd += video_args(meta, args.crf, args.preset, convert_matrix=not args.video) + cfr_args(meta)
    cmd += aac_args() if meta.get("audio") else ["-an"]
    dropped_streams = run_keeping_subtitles(cmd, output)
    if not STATE.dry_run:
        result = probe(output, role="output")
        info(f"wrote {output} ({fmt_secs(result['duration'])})")
    emit(output, dropped_non_av_streams=dropped_streams, **({"font_used": font_used} if args.text else {}))
    return 0


if __name__ == "__main__":
    sys.exit(main())