ffmpeg-skill 3.1.4 → 3.1.6

package/scripts/cropdetect.py

@@ -34,7 +34,8 @@ from collections import Counter
 from typing import Dict, List, Optional, Tuple
 
 from _common import add_common, apply_common, die, emit, info, print_json, probe, require_tool, run_analysis, decode_gray_frames, frame_flow
-from _common.emit import warn
+from _common.emit import note, warn
+from _common.probe import display_size, square_pixels, square_pixels_note
 
 MOTION_CENTRE_FPS = 2.0
 MOTION_CENTRE_W, MOTION_CENTRE_H = 64, 36
@@ -43,10 +44,11 @@ CROP_RE = re.compile(r"crop=(\d+):(\d+):(\d+):(\d+)")
 
 
 def detect(path: str, seconds: float, samples: int, limit: float, round_to: int, duration: float,
-           failed: "Optional[List[Dict]]" = None) -> List[Tuple[int, int, int, int]]:
+           failed: "Optional[List[Dict]]" = None, square: str = "") -> List[Tuple[int, int, int, int]]:
     """Crop rectangles from `samples` windows spread over the file. A window ffmpeg cannot decode
     is skipped, and appended to `failed` as {start, seconds, error} when the caller passes a list,
-    so the result can say how many of the readings it stands on."""
+    so the result can say how many of the readings it stands on. `square` is the source's
+    square_pixels() scale, run first so the rectangle is in the frame crop.py crops (#411)."""
     ffmpeg = require_tool("ffmpeg")
     per_window = max(0.5, seconds / max(1, samples))
     rects: List[Tuple[int, int, int, int]] = []
@@ -55,7 +57,7 @@ def detect(path: str, seconds: float, samples: int, limit: float, round_to: int,
         start = 0.0 if duration <= 0 else (duration - per_window) * i / max(1, samples - 1) if samples > 1 else 0.0
         start = max(0.0, start)
         cmd = [ffmpeg, "-hide_banner", "-nostdin", "-ss", f"{start:.3f}", "-i", path, "-t", f"{per_window:.3f}",
-               "-vf", f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
+               "-vf", (square + "," if square else "") + f"cropdetect=limit={limit:g}:round={round_to}:reset=1", "-f", "null", "-"]
         proc = run_analysis(cmd, check=False)
         if proc.returncode != 0:
             # One window ffmpeg cannot decode (a damaged stretch) is skipped; the other windows
@@ -144,16 +146,18 @@ def main() -> int:
     meta = probe(args.input)
     if not meta.get("video"):
         die("input has no video stream")
-    sw, sh = meta["video"]["width"], meta["video"]["height"]
     # cropdetect and the grey decode both see the frame after ffmpeg applies rotation, so the
     # rectangle and the motion points are in that frame. Reporting the stored size made a
-    # 176x320 crop look taller than a 320x180 source.
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        sw, sh = sh, sw
+    # 176x320 crop look taller than a 320x180 source. A non-square-pixel source is measured
+    # squared at its display aspect, the frame crop.py then crops (#411).
+    sw, sh = display_size(meta["video"])
+    if square_pixels_note(meta["video"]):
+        note(square_pixels_note(meta["video"]))
     duration = meta.get("duration") or 0.0
 
     failed: List[Dict] = []
-    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed)
+    rects = detect(args.input, args.seconds, args.samples, args.limit, args.round_to, duration, failed,
+                   square_pixels(meta["video"]))
     # windows_failed: a window ffmpeg could not decode was skipped without a word, so a
     # crop measured on one window of five read as well-founded as one measured on all five
     result: Dict = {"file": args.input, "source_width": sw, "source_height": sh,

package/scripts/cut.py

@@ -61,6 +61,7 @@ from typing import List, Tuple
 from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import require_tool
 from _common.probe import TS_EXTS, signatures_match, stream_signature
+from _common.decision import grid_at_or_after
 from _common import warn, sibling_temp, source_codec_video_args, STATE, add_common, apply_common, audio_codec_for, emit, aac_args, cfr_args, default_output, die, ffmpeg_base, info, is_audio_output, time_arg, probe, run, X264_PRESETS, keyframes_near, MissingFpsError, concat_list_line, place_output, refuse_output_is_input, fmt_secs, measure_frame_timing, dry_run_input_pending
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
@@ -1013,10 +1014,9 @@ def _fraction_rate(text: str) -> float:
     return float(num) / float(den or 1)
 
 
-def _grid_at_or_after(t: float, v0: float, rate: float) -> float:
-    """The time of the first frame at or after `t` on a constant-rate grid starting at `v0`."""
-    import math
-    return v0 + math.ceil((t - v0) * rate - 1e-6) / rate
+# the first frame at or after t on the source's grid; shared with the tools that cut both streams
+# on one set of bounds (#409)
+_grid_at_or_after = grid_at_or_after
 
 
 def _join_chunk(src: str, segments: List[Tuple[float, float]], dst: str, meta: dict, crf: int, preset: str,

package/scripts/export.py

@@ -38,9 +38,10 @@ import tempfile
 from pathlib import Path
 from typing import Dict, List
 
-from _common import STATE, run_analysis, add_common, apply_common, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
+from _common import STATE, run_analysis, add_common, apply_common, bt709_label_filter, bt709_matrix_args, bt709_tag_args, child_args, emit, cfr_args, default_output, die, encoder_args, ffmpeg_base, info, probe, require_tool, run, run_tool, validate_color, pad_filters, add_pad_fill_args, fmt_secs
 from _common.decision import hw_preset_video, restate_last_swap
 from _common.emit import note, record_fallback, record_skip, warn
+from _common.probe import square_pixels, square_pixels_note
 from check import SPECS as PLATFORMS, measure_loudness
 from _platforms import ALIASES as _ALIASES, PLATFORMS as PLATFORM_TABLE, TP_TOLERANCE_DB, resolve as resolve_platform
 # Frame and duration limit come from the one platform table (scripts/_platforms.py) rather than
@@ -358,6 +359,9 @@ def main() -> int:
     out_ext = Path(output).suffix.lstrip(".").lower()
 
     vf: List[str] = []
+    # A GIF is RGB: an untagged SDR source is labelled BT.709 (tags only) for palettegen's conversion,
+    # which read "unknown" as BT.601 (C03028 came out B31F28, #410); a tagged one is read by its tag
+    gif_label = bt709_label_filter(meta) if args.preset == "gif" else None
     if p["w"] and not args.no_scale:
         if p["h"]:
             if args.fit == "crop":
@@ -370,6 +374,11 @@ def main() -> int:
             vf.append("setsar=1")
         else:
             vf.append(f"scale={p['w']}:-2")
+        # sized in square pixels: a non-square-pixel master is squared at its display aspect
+        # first, or the preset's frame would squash it (#411)
+        if square_pixels(meta["video"]):
+            vf.insert(0, square_pixels(meta["video"]))
+            note(square_pixels_note(meta["video"]))
     if args.repair and args.preset != "copy":
         die("--repair is a remux: use it with --preset copy (a re-encoding preset already rebuilds every frame)")
     if args.max_mb is not None and args.preset == "gif":
@@ -387,7 +396,7 @@ def main() -> int:
         cmd += ["-map", "0:V:0"] + (["-map", "0:a:0"] if has_audio else [])
 
     if args.preset == "gif":
-        chain = ",".join(["fps=12"] + vf) if vf else "fps=12"
+        chain = ",".join(([gif_label] if gif_label else []) + ["fps=12"] + vf)
         fc = f"[0:v]{chain},split[a][b];[a]palettegen=stats_mode=diff[p];[b][p]paletteuse=dither=bayer:bayer_scale=5:diff_mode=rectangle"
         cmd += ["-filter_complex", fc, "-loop", "0", output]
         run(cmd)

package/scripts/fit.py

@@ -39,7 +39,7 @@ import sys
 from fractions import Fraction
 from typing import List
 
-from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, 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, frame_size
+from _common import video_args, STATE, add_common, apply_common, emit, aac_args, aspect_ratio, 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, frame_size, display_size, square_pixels, square_pixels_note, note
 BLUR_DARKEN = 0.15  # how much --fit blur dims the blurred background copy (eq brightness)
 
 
@@ -125,9 +125,8 @@ def main() -> int:
     if args.audio_stream and not audio_streams:
         die("--audio-stream needs an input with audio streams")
     src_dur = meta["duration"] or 0.0
-    sw, sh = meta["video"]["width"], meta["video"]["height"]
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        sw, sh = sh, sw
+    # the displayed frame: rotation applied and non-square pixels squared (#411)
+    sw, sh = display_size(meta["video"])
     if args.rotate in (90, 270):
         sw, sh = sh, sw
     has_audio = bool(meta.get("audio"))
@@ -204,6 +203,11 @@ def main() -> int:
         else:
             vf.append(pad_filters(out_w, out_h, args.pad_fill, args.pad_color, args.pad_blur, meta=meta))
         vf.append("setsar=1")
+        # a non-square-pixel source is made square at its display aspect before anything else
+        # (the size above is computed in that frame), so the fitted picture is not squashed
+        if square_pixels(meta["video"]):
+            vf.insert(0, square_pixels(meta["video"]))
+            note(square_pixels_note(meta["video"]))
 
     if args.fps:
         vf.append(f"fps={args.fps:g}")

package/scripts/freeze.py

@@ -19,6 +19,7 @@ Examples:
 import argparse
 import sys
 
+from _common.decision import av_trim, frame_durations, frame_rate, grid_at_or_after, stream_starts
 from _common import add_common, apply_common, aac_args, cfr_args, default_output, die, emit, ffmpeg_base, info, probe, run_keeping_subtitles, video_args, X264_PRESETS, MissingFpsError, time_arg, fmt_secs, run
 
 
@@ -55,14 +56,24 @@ def main() -> int:
     has_audio = bool(meta.get("audio"))
     output = args.output or default_output(args.input, "freeze")
 
-    if args.mode == "extend":
+    # Both streams are cut at the same frame time and shifted by the same constants (#409): the
+    # head runs from the first frame, the tail from the first frame at or after --at. Rebasing each
+    # stream to its own start moved a sound that starts 0.3 s late 0.279 s early, and a picture that
+    # starts 0.1 s late 0.1 s early (147 frames for 150).
+    v0 = stream_starts(meta)[0]
+    rate = frame_rate(meta) or fps
+    cut_at = grid_at_or_after(at, v0, rate)
+    # no frame at or after --at (no --at holds at the clip's end): the insert tail would be empty
+    # and the hold lost, so hold the last frame as --mode extend does (#416 review)
+    vend = v0 + (meta["video"].get("duration") or dur - v0)
+    if args.mode == "extend" or cut_at >= vend - 0.5 / rate:
         # tpad's stop_duration clones the last frame for the given duration; no PTS surgery
         # needed since it only ever appends past the real end.
         vf = f"tpad=stop_mode=clone:stop_duration={args.hold:.3f}"
         cmd = ffmpeg_base() + ["-i", args.input, "-vf", vf, "-map", "0:v:0"]
         if has_audio:
             cmd += ["-map", "0:a:0?", "-af", f"apad=pad_dur={args.hold:.3f}"]
-    elif at == 0:
+    elif at == 0 or cut_at <= v0 + 1e-6:
         # A freeze at the very start has no preceding "head" segment to hold on to (the
         # split/trim/concat approach below needs a non-empty head, which trim=end=0 can't give
         # it -- ffmpeg fails filtering an empty stream). Symmetric to --mode extend at the other
@@ -73,22 +84,39 @@ def main() -> int:
             cmd += ["-map", "0:a:0?", "-af", f"adelay={int(args.hold * 1000)}:all=1"]
     else:
         # freeze N frames at `at` by holding on that one source frame for --hold seconds, then
-        # resuming the rest of the clip: split the timeline at `at`, freeze-frame the first
-        # part's last frame for --hold seconds via tpad, concat with the remainder.
+        # resuming the rest of the clip: split the timeline at `at` and hold the remainder's
+        # FIRST frame -- the frame shown at `at` -- for --hold seconds (a segment of its own, below).
+        # Through 3.1.3 the head's last frame was held, the frame before `at`: at a cut, the last
+        # frame of the previous shot (#411).
         n = max(1, round(args.hold * fps))
         # The video hold length is rounded to a whole number of frames (n / fps), but the audio
         # side used to pad by the raw --hold value -- up to half a frame duration off from what
         # the video actually holds for, a permanent A/V drift from this point on. Pad audio by
         # the same, frame-rounded duration the video actually gets.
         actual_hold = n / fps
-        vf = (f"[0:v]split[a][b];[a]trim=end={at:.3f},setpts=PTS-STARTPTS[head];"
-              f"[b]trim=start={at:.3f},setpts=PTS-STARTPTS[tail];"
-              f"[head]tpad=stop_mode=clone:stop={n}[frozen];"
-              f"[frozen][tail]concat=n=2:v=1:a=0[outv]")
+        head_v, head_a = av_trim(v0, cut_at, rate)
+        tail_v, tail_a = av_trim(cut_at, None, rate)
+        # The hold is its own segment: the frame at cut_at, cut on the input's clock and cloned to
+        # n frames there (tpad's stop clone), then shifted like the tail. From FFmpeg 7.0 setpts
+        # leaves its output's frame rate unknown and its frames' durations 0, so the earlier tpad
+        # start clone after av_trim's setpts stamped every clone 0 and the hold was dropped (a 3 s
+        # freeze came out 1.97 s on 7.1). Cloning before setpts and concatenating the hold before
+        # the tail reads the same on every version; the tail's first frame then shows n + 1 times,
+        # as tpad's start clone showed it.
+        # The held frame is the first frame at or after the cut, whatever its time: on a variable
+        # frame rate a nominal one-frame window around cut_at can hold no frame (frames at 0.033
+        # and 0.100, --at 0.06), and the hold was lost (#416 review). A second trim keeps that one
+        # frame; on a constant rate it is the frame at cut_at, as before.
+        half = 0.5 / rate
+        hold_v = (f"trim=start={cut_at - half:.6f},trim=end_frame=1,"
+                  f"tpad=stop_mode=clone:stop={n - 1},setpts=PTS-STARTPTS")
+        vf = (f"[0:v]split=3[a][b][c];[a]{head_v}[head];"
+              f"[b]{hold_v}[hold];[c]{tail_v}[tail];"
+              f"[head][hold][tail]concat=n=3:v=1:a=0,{frame_durations(meta, rate)}[outv]")
         cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", vf, "-map", "[outv]"]
         if has_audio:
-            af = (f"[0:a]asplit[aa][ab];[aa]atrim=end={at:.3f},asetpts=PTS-STARTPTS[ahead];"
-                  f"[ab]atrim=start={at:.3f},asetpts=PTS-STARTPTS[atail];"
+            af = (f"[0:a]asplit[aa][ab];[aa]{head_a}[ahead];"
+                  f"[ab]{tail_a}[atail];"
                   f"[ahead]apad=pad_dur={actual_hold:.6f}[afrozen];"
                   f"[afrozen][atail]concat=n=2:v=0:a=1[outa]")
             cmd = ffmpeg_base() + ["-i", args.input, "-filter_complex", f"{vf};{af}", "-map", "[outv]", "-map", "[outa]"]

package/scripts/graphics.py

@@ -32,16 +32,17 @@ import sys
 from typing import List, Optional, Tuple
 
 from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as resolve_platform
-from _common import (require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
+from _common import (guard_sidecar, require_filter, aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
                      color_hex, default_output, die, draws_chroma, drawn_chain, emit, escape_drawtext, escape_filter_path,
-                     ffmpeg_base, info, label_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
+                     ffmpeg_base, info, layer_base_chain, load_brand, parse_time, probe, rgb_chain_to_bt709, run, run_keeping_subtitles, video_args,
                      drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
                      LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
                      emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
                      EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
                      SAFE_WIDTH_FRACTION, drawtext_draws_newline_glyph, is_multiline, _DRAWTEXT_PENDING)
-from _common.emit import warn
+from _common.emit import note, warn
 from _common.fonts import font_choice, record_font_choice
+from _common.probe import display_size, square_pixels, square_pixels_note
 from _ass_overlay import text_overlay_ass, EMOJI_SENTINEL
 from _common import drawtext_fontfile  # noqa: E402
 
@@ -170,9 +171,11 @@ def main(force_route: Optional[str] = None) -> int:
         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")
-    W, H = meta["video"]["width"], meta["video"]["height"]
-    if meta["video"].get("rotation") in (90, -90, 270, -270):
-        W, H = H, W
+    # the displayed frame: rotation applied, non-square pixels squared (square_pixels(), #411)
+    W, H = display_size(meta["video"])
+    square = square_pixels(meta["video"])
+    if square:
+        note(square_pixels_note(meta["video"]))
     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
@@ -373,9 +376,21 @@ def main(force_route: Optional[str] = None) -> int:
         h1 = int(base * 0.055)
         h2 = int(base * 0.038)
         pad = int(base * 0.02)
-        name_h = block_h(args.name, h1)
-        bar_h = name_h + (block_h(args.title, h2) + pad if args.title else 0) + pad * 2
-        bar_w = int(base * 0.62)
+        tx_pad = int(base * 0.035)
+        # both lines wrap to the room between the side margins, less the text's own inset, and
+        # the bar widens (up to that room) to the widest line: through 3.1.3 the bar was a fixed
+        # 62 % of the short side and a long name ran past it and off the frame (#411)
+        room = W - m_left - m_right
+        lt_frac = max(0.1, min(1.0, (room - 2 * tx_pad) / float(W))) if W else SAFE_WIDTH_FRACTION
+        lt_name = wrapped(args.name, h1, lt_frac)
+        lt_title = wrapped(args.title, h2, lt_frac) if args.title else args.title
+        widest = max([text_width_em(ln) * h1 for ln in lt_name.split("\n")]
+                     + [text_width_em(ln) * h2 for ln in (lt_title or "").split("\n")])
+        name_h = block_h(lt_name, h1)
+        bar_h = name_h + (block_h(lt_title, h2) + pad if lt_title else 0) + pad * 2
+        # the 62 % floor never takes the bar past the right margin (#416 review: at a large --scale
+        # it did)
+        bar_w = max(1, min(room, max(int(base * 0.62), int(widest + 0.999) + 2 * tx_pad)))
         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}+{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}))"
@@ -383,12 +398,11 @@ def main(force_route: Optional[str] = None) -> int:
         fc.append(f"{layer_src(primary, 1.0, int(base * 0.012), bar_h)}[acc]")
         fc.append(f"[0:v][bar]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v1]")
         fc.append(f"[v1][acc]overlay=x='{x_expr}':y={y0}:{en}:eof_action=pass[v2]")
-        tx_pad = int(base * 0.035)
         tx = f"({x_expr})+{tx_pad}"
         x_rest, x_off = m_left + tx_pad, -bar_w + tx_pad
         draws = []
-        for text, fs, colour, ty in ((args.name, h1, text_c, y0 + pad),
-                                     (args.title, h2, primary, y0 + pad + name_h + pad // 2)):
+        for text, fs, colour, ty in ((lt_name, h1, text_c, y0 + pad),
+                                     (lt_title, h2, primary, y0 + pad + name_h + pad // 2)):
             if not text:
                 continue
             draws.append(f"drawtext={drawtext_text_opts(text)}:{fo}:fontsize={fs}:"
@@ -416,24 +430,33 @@ def main(force_route: Optional[str] = None) -> int:
             die("title needs --title")
         h1 = int(base * 0.11)
         h2 = int(base * 0.045)
+        # the title and the subtitle wrap to the frame's safe width (#411: they never did)
+        title_t = wrapped(args.title, h1)
+        sub_t = wrapped(args.subtitle, h2) if args.subtitle else args.subtitle
         fill_box(bg, 0.55, "x=0:y=0:w=iw:h=ih", 0, 0, W, H, en)
         # the title is centred as a block, so the bar and the subtitle sit below its last line:
         # `title_h` is the block's height, as the one-line layout has always taken h1; a further
         # subtitle line hangs below the first, whose position the one-line layout fixes
-        title_h = block_h(args.title, h1)
+        title_h = block_h(title_t, h1)
         sub_y = title_h // 2 + int(base * 0.03)
-        sub_extra = block_h(args.subtitle, h2) - h2 if args.subtitle else 0
-        add_text(args.title,
-                 f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
+        sub_extra = block_h(sub_t, h2) - h2 if sub_t else 0
+        tall = title_h + (sub_y - title_h // 2 + block_h(sub_t, h2) if sub_t else 0)
+        if tall > H:
+            # the wrap measures width only; a centred block taller than the frame loses its first
+            # and last lines off the edges (#416 review)
+            note(f"the wrapped title{' and subtitle' if sub_t else ''} are about {tall} px tall, taller than the "
+                 f"{H} px frame: the lines past its edges are not drawn -- shorten the text or lower --scale")
+        add_text(title_t,
+                 f"drawtext={drawtext_text_opts(title_t)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if sub_t else 0}:alpha='{fade_a}':{en}",
                  size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
-                 y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
+                 y=H / 2 - (h2 if sub_t else 0), outline=max(1.0, h1 / 20.0),
                  outline_color="000000", start=s, end=e, fade=(300, 300))
         acc_w, acc_h = int(base * 0.12), max(2, int(base * 0.006))
         fill_box(primary, 1.0, f"x=(iw-{acc_w})/2:y=(ih)/2+{title_h // 2}:w={acc_w}:h={acc_h}",
                  (W - acc_w) // 2, H // 2 + title_h // 2, acc_w, acc_h, en)
-        if args.subtitle:
-            add_text(args.subtitle,
-                     f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{sub_y + sub_extra // 2}:alpha='{fade_a}':{en}",
+        if sub_t:
+            add_text(sub_t,
+                     f"drawtext={drawtext_text_opts(sub_t)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{sub_y + sub_extra // 2}:alpha='{fade_a}':{en}",
                      size=h2, color=primary, font=ass_font_family(), align=5, x=W / 2,
                      y=H / 2 + sub_y + sub_extra // 2, outline=max(1.0, h2 / 20.0),
                      outline_color="000000", start=s, end=e, fade=(300, 300))
@@ -444,6 +467,8 @@ def main(force_route: Optional[str] = None) -> 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)
+        # the chip wraps to the room between the side margins, as the sticker's does (#411)
+        chip_t = wrapped(args.title, fs, chip_frac(m_left, m_right, padx))
         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)
@@ -451,8 +476,8 @@ def main(force_route: Optional[str] = None) -> int:
         box_hex = primary if args.template == "chapter" else bg
         txt_hex = bg if args.template == "chapter" else text_c
         align = (7 if "left" in pos else 9) if "top" in pos else (1 if "left" in pos else 3)
-        add_text(args.title,
-                 f"drawtext={drawtext_text_opts(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}",
+        add_text(chip_t,
+                 f"drawtext={drawtext_text_opts(chip_t)}:{fo}:fontsize={fs}:fontcolor={txt_color}:x={xe}:y={ye}:box=1:boxcolor={box_color}:boxborderw={drawtext_boxborderw(pady, padx)}:alpha='{fade_a}':{en}",
                  size=fs, color=txt_hex, font=ass_font_family(), align=align,
                  x=(m_left if "left" in pos else W - m_right),
                  y=(m_top if "top" in pos else H - m_bottom),
@@ -587,52 +612,62 @@ def main(force_route: Optional[str] = None) -> int:
         seen: List[str] = []
         for el in elements:
             el["box_px"] = int(round(el["size"] * scale_em))
-            line = el["text"]
-            clusters = emoji_clusters(line)
-            if not clusters or emoji_mode not in ("png",):
+            if not emoji_clusters(el["text"]) or emoji_mode not in ("png",):
                 continue
-            line_w = text_width_em(line, scale_em) * el["size"]
+            # a wrapped label is several lines: each is measured from its own start and sits one
+            # line pitch below the last (#416 review: they were measured as one line, on the first)
+            all_lines = el["text"].split("\n")
             align = int(el.get("align", 7))
-            left = el["x"] if align in (7, 4, 1) else (
-                el["x"] - line_w / 2.0 if align in (8, 5, 2) else el["x"] - line_w)
             line_h = el["size"] * 1.2
-            y_top = el["y"] if align in (7, 8, 9) else (
-                el["y"] - line_h / 2.0 if align in (4, 5, 6) else el["y"] - line_h)
-            # An RTL line is rendered right-to-left: measure the suffix, not the logical prefix.
-            rtl = detect_script(line) in BIDI_SCRIPTS
-            rebuilt, cursor = "", 0
-            for idx, cluster in clusters:
-                name = emoji_codepoint_name(cluster)
-                if name not in seen:
-                    seen.append(name)
-                asset = emoji_asset_for(cluster, emoji_assets)
-                if not asset:
-                    if name not in missing:
-                        missing.append(name)
-                    rebuilt += line[cursor:idx + len(cluster)]
-                    cursor = idx + len(cluster)
+            block = len(all_lines) * line_h
+            block_top = el["y"] if align in (7, 8, 9) else (
+                el["y"] - block / 2.0 if align in (4, 5, 6) else el["y"] - block)
+            rebuilt_lines = []
+            for k, line in enumerate(all_lines):
+                clusters = emoji_clusters(line)
+                if not clusters:
+                    rebuilt_lines.append(line)
                     continue
-                if rtl:
-                    prefix_px = line_w - text_width_em(line[:idx] + cluster, scale_em) * el["size"]
-                else:
-                    prefix_px = text_width_em(line[:idx], scale_em) * el["size"]
-                if el.get("x_expr"):
-                    # the lower-third slides: the emoji rides the same expression the bar does
-                    x = f"({el['x_expr']})+{prefix_px:.0f}"
-                else:
-                    x = int(round(max(0.0, min(left + prefix_px, W - el["box_px"]))))
-                emoji_overlays.append({"asset": asset, "cluster": name, "x": x,
-                                       "y": int(round(max(0.0, min(y_top + (line_h - el["box_px"]) / 2.0,
-                                                                   H - el["box_px"])))),
-                                       "start": round(el["start"], 3), "end": round(el["end"], 3),
-                                       "box": el["box_px"],
-                                       # every template fades its text in and out over 0.3 s
-                                       # (fade_a above); the PNG rides the same envelope.
-                                       "fade_in": round(min(0.3, max(0.0, (el["end"] - el["start"]) / 2.0)), 3),
-                                       "fade_out": round(min(0.3, max(0.0, (el["end"] - el["start"]) / 2.0)), 3)})
-                rebuilt += line[cursor:idx] + EMOJI_SENTINEL
-                cursor = idx + len(cluster)
-            el["text"] = rebuilt + line[cursor:]
+                line_w = text_width_em(line, scale_em) * el["size"]
+                left = el["x"] if align in (7, 4, 1) else (
+                    el["x"] - line_w / 2.0 if align in (8, 5, 2) else el["x"] - line_w)
+                y_top = block_top + k * line_h
+                # An RTL line is rendered right-to-left: measure the suffix, not the logical prefix.
+                rtl = detect_script(line) in BIDI_SCRIPTS
+                rebuilt, cursor = "", 0
+                for idx, cluster in clusters:
+                    name = emoji_codepoint_name(cluster)
+                    if name not in seen:
+                        seen.append(name)
+                    asset = emoji_asset_for(cluster, emoji_assets)
+                    if not asset:
+                        if name not in missing:
+                            missing.append(name)
+                        rebuilt += line[cursor:idx + len(cluster)]
+                        cursor = idx + len(cluster)
+                        continue
+                    if rtl:
+                        prefix_px = line_w - text_width_em(line[:idx] + cluster, scale_em) * el["size"]
+                    else:
+                        prefix_px = text_width_em(line[:idx], scale_em) * el["size"]
+                    if el.get("x_expr"):
+                        # the lower-third slides: the emoji rides the same expression the bar does
+                        x = f"({el['x_expr']})+{prefix_px:.0f}"
+                    else:
+                        x = int(round(max(0.0, min(left + prefix_px, W - el["box_px"]))))
+                    emoji_overlays.append({"asset": asset, "cluster": name, "x": x,
+                                           "y": int(round(max(0.0, min(y_top + (line_h - el["box_px"]) / 2.0,
+                                                                       H - el["box_px"])))),
+                                           "start": round(el["start"], 3), "end": round(el["end"], 3),
+                                           "box": el["box_px"],
+                                           # every template fades its text in and out over 0.3 s
+                                           # (fade_a above); the PNG rides the same envelope.
+                                           "fade_in": round(min(0.3, max(0.0, (el["end"] - el["start"]) / 2.0)), 3),
+                                           "fade_out": round(min(0.3, max(0.0, (el["end"] - el["start"]) / 2.0)), 3)})
+                    rebuilt += line[cursor:idx] + EMOJI_SENTINEL
+                    cursor = idx + len(cluster)
+                rebuilt_lines.append(rebuilt + line[cursor:])
+            el["text"] = "\n".join(rebuilt_lines)
         # `or 60` would swallow --emoji-max 0, the one value meaning "none at all".
         _max = 60 if args.emoji_max is None else int(args.emoji_max)
         if len(emoji_overlays) > _max:
@@ -648,6 +683,10 @@ def main(force_route: Optional[str] = None) -> int:
                             "overlays": len(emoji_overlays)}
         ass_path = args.write_ass or os.path.splitext(output)[0] + "_gfx.ass"
         require_filter("ass", "drawing this text through libass")  # before the sidecar is written
+        # a file this run writes itself: never the input or the video, a missing directory or an
+        # existing file without --overwrite is refused before anything is written (#408)
+        guard_sidecar(ass_path, *[q for q in (args.input, getattr(args, "brand", None), getattr(args, "font_file", None))
+                                  if isinstance(q, str)], siblings=(output,))
         if STATE.dry_run:
             info(f"[dry-run] would write {ass_path} ({len(elements)} text elements)")
         else:
@@ -669,7 +708,7 @@ def main(force_route: Optional[str] = None) -> int:
         drawboxes.append(f"drawbox={geo}:color={ff_color(colour, alpha)}:t=fill:{enable}")
     filters = [("" if as_layers else drawboxes[int(f[len(BOX):])]) if f.startswith(BOX) else f for f in filters]
     filters = [f for f in filters if f]
-    base_label = label_chain(meta, meta) if (layers or converted) else ""
+    base_label = layer_base_chain(meta) if (layers or converted) else ""
     text = (drawn_chain(",".join(filters), meta, re.findall(r"color=([0-9A-Za-z#@.]+)", ",".join(filters)),
                         labelled=bool(base_label)) if filters else "")
     if layers:
@@ -682,10 +721,12 @@ def main(force_route: Optional[str] = None) -> int:
     fc = [c.replace(TEXT, text or "null") for c in fc]
     if fc and base_label:
         fc = [f"[0:v]{base_label}null[gbase]"] + [c.replace("[0:v]", "[gbase]") for c in fc]
+    if fc and square:
+        fc = [f"[0:v]{square}[gsq]"] + [c.replace("[0:v]", "[gsq]") for c in fc]
 
     cmd = ffmpeg_base() + ["-i", args.input]
     if route == "ass" or emoji_overlays:
-        chains = list(fc) if fc else [f"[0:v]{text or 'null'}[vout]"]
+        chains = list(fc) if fc else [f"[0:v]{(square + ',') if square else ''}{text or 'null'}[vout]"]
         last = "vout"
         if route == "ass":
             vf = f"ass=filename={escape_filter_path(ass_path)}"
@@ -698,7 +739,7 @@ def main(force_route: Optional[str] = None) -> int:
             last = "vtxt"
         eo, emoji_inputs = emoji_filter_chain({"overlays": emoji_overlays}, last, "vfinal", first_input=1,
                                               to_yuv=rgb_chain_to_bt709(meta),
-                                              base_chain=label_chain(meta, meta) if rgb_chain_to_bt709(meta) else "")
+                                              base_chain=layer_base_chain(meta))
         for spec in emoji_inputs:
             cmd += spec
             asset = spec[-1]
@@ -712,7 +753,7 @@ def main(force_route: Optional[str] = None) -> int:
     elif fc:
         cmd += ["-filter_complex", ";".join(fc), "-map", "[vout]", "-map", f"0:a:{args.audio_stream}?"]
     else:
-        cmd += ["-vf", text, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
+        cmd += ["-vf", (square + "," if square else "") + text, "-map", "0:v:0", "-map", f"0:a:{args.audio_stream}?"]
     cmd += video_args(meta, args.crf, args.preset) + cfr_args(meta)
     cmd += aac_args() if meta.get("audio") else ["-an"]
     dropped_streams = run_keeping_subtitles(cmd, output)