ffmpeg-skill 1.16.1 → 1.17.0

package/scripts/caption.py

@@ -40,17 +40,27 @@ import unicodedata
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
-from _platforms import PLATFORMS, PLATFORM_CHOICES, ass_units, resolve as resolve_platform
+from _platforms import (PLATFORMS, PLATFORM_CHOICES, ASS_SCRIPT_HEIGHT, ass_units,
+                        resolve as resolve_platform)
 from _ass_overlay import EMOJI_SENTINEL, emoji_placeholder, ass_escape
 from _common import emoji_filter_chain, EMOJI_ASSET_HINT, emoji_asset_for, emoji_codepoint_name, emoji_support, resolve_emoji_assets, ADVANCE_EM, LATIN_EM, NO_SPACE_SCRIPTS, _char_em, char_script, text_width_em, emoji_clusters, has_emoji, detect_script, BIDI_SCRIPTS, STATE, brand_states_font, 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
 # The line breaker, lifted into _common/text.py in 1.16.0 so graphics.py can use the same rules.
+# The ASR bridge and the SRT reader/writer live in _common.asr since 1.17 (silence.py --filler
+# shares them). They stay caption.py's public names -- every caller and test that reached for
+# caption.parse_srt / caption.transcribe / caption.whisper_word_timings before 1.17 still does.
+from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whisper_word_timings,
+                     write_srt)
 from _common import (SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, wrap_text, wrap_variants, best_break,
+                     fit_size, line_em_for_size, MIN_CAPTION_FRACTION,
                      break_penalty, _is_weak_line, _atoms, _join, _break_spaced, _bare_word, _function_words,
                      _split_hyphens, FUNCTION_WORDS, JA_PARTICLES, JA_SENTENCE_END, _fix_orphans, _rebalance)
 
 # The breaker's names are caption.py's public surface as much as _common's: every caller and test
 # that reached for `caption.wrap_text` before 1.16 still does.
-__all__ = ["SAFE_WIDTH_FRACTION", "ORPHAN_MIN_EM", "WRAP_MODES", "wrap_text", "wrap_variants",
+__all__ = ["parse_srt", "write_srt", "transcribe", "whisper_word_timings", "die_no_engine",
+           "ASR_INSTALL_HINT",
+           "SAFE_WIDTH_FRACTION", "ORPHAN_MIN_EM", "WRAP_MODES", "wrap_text", "wrap_variants",
+           "fit_size", "line_em_for_size", "MIN_CAPTION_FRACTION",
            "best_break", "break_penalty", "_is_weak_line", "_atoms", "_join", "_break_spaced",
            "_bare_word", "_function_words", "_split_hyphens", "FUNCTION_WORDS", "JA_PARTICLES",
            "JA_SENTENCE_END", "_fix_orphans", "_rebalance", "char_script", "NO_SPACE_SCRIPTS",
@@ -97,150 +107,6 @@ def parse_text_cues(path: str, auto_seconds: float, gap: float, fps: Optional[fl
     return cues
 
 
-def transcribe(video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int = 0) -> List[Tuple[float, float, str]]:
-    """Optional local ASR bridge. Tries, in order: whisper-cli / main (whisper.cpp), faster-whisper (python),
-    whisper (openai-whisper CLI). Produces an SRT with word timings where the engine supports it.
-    No engine installed -> clear error with install hints; the skill never depends on one."""
-    import shutil
-    import subprocess
-    import tempfile
-    from _common import require_tool, run_analysis, STATE
-    ffmpeg = require_tool("ffmpeg")
-    tmpdir = tempfile.mkdtemp(prefix="ffskill_asr_")
-    try:
-        return _transcribe_in(tmpdir, video, out_srt, language, model, audio_stream, ffmpeg, shutil, subprocess)
-    finally:
-        shutil.rmtree(tmpdir, ignore_errors=True)
-
-
-def _asr_run(cmd: List[str], subprocess, name: str) -> "subprocess.CompletedProcess":
-    """Run a speech-to-text engine under the same wall-clock limit as an ffmpeg call."""
-    from _common import STATE, die
-    limit = STATE.timeout or None
-    try:
-        return subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=limit)
-    except subprocess.TimeoutExpired:
-        die(f"{name} exceeded the {limit:.0f} s time limit and was killed; raise --timeout for a long recording",
-            code=124, kind="timeout")
-    return None  # unreachable
-
-
-def _transcribe_in(tmpdir: str, video: str, out_srt: str, language: Optional[str], model: str, audio_stream: int,
-                   ffmpeg: str, shutil, subprocess) -> List[Tuple[float, float, str]]:
-    from _common import run_analysis, STATE, die
-    wav = os.path.join(tmpdir, "audio.wav")
-    # A wav in our own temp dir: a measurement input for the engine, not a deliverable, so it
-    # is not a run() call (no --dry-run gate, not recorded), but it keeps the time limit and
-    # reports an unreadable input as kind ffmpeg instead of a CalledProcessError traceback.
-    run_analysis([ffmpeg, "-hide_banner", "-loglevel", "error", "-nostdin", "-y", "-i", video,
-                  "-map", f"0:a:{audio_stream}", "-vn", "-ac", "1", "-ar", "16000", "-c:a", "pcm_s16le", wav])
-    # 1. whisper.cpp
-    cli = shutil.which("whisper-cli") or shutil.which("whisper-cpp")
-    if not cli:
-        # older whisper.cpp builds ship the binary as plain `main`; accept it only when it lives
-        # in a directory that names whisper, so an unrelated /usr/bin/main is never run
-        main_bin = shutil.which("main")
-        if main_bin and "whisper" in os.path.dirname(os.path.realpath(main_bin)).lower():
-            cli = main_bin
-    if cli:
-        model_path = model
-        if not os.path.exists(model_path):
-            for cand in (os.path.expanduser(f"~/.cache/whisper.cpp/ggml-{model}.bin"), f"models/ggml-{model}.bin", f"/usr/local/share/whisper/ggml-{model}.bin"):
-                if os.path.exists(cand):
-                    model_path = cand
-                    break
-        base = os.path.join(tmpdir, "out")
-        cmd = [cli, "-m", model_path, "-f", wav, "-osrt", "-of", base]
-        if language:
-            cmd += ["-l", language]
-        proc = _asr_run(cmd, subprocess, "whisper.cpp")
-        if proc.returncode == 0 and os.path.exists(base + ".srt"):
-            info(f"transcribed with whisper.cpp ({os.path.basename(cli)}, model {os.path.basename(model_path)})")
-            cues = parse_srt(base + ".srt")
-            write_srt(cues, out_srt)
-            return cues
-        info("whisper.cpp found but failed: " + (proc.stderr.strip().splitlines() or ["?"])[-1][:200])
-    # 2. faster-whisper (python package)
-    try:
-        from faster_whisper import WhisperModel  # type: ignore
-        import threading
-        result: list = []
-
-        def work() -> None:
-            m = WhisperModel(model, device="cpu", compute_type="int8")
-            segments, _ = m.transcribe(wav, language=language, word_timestamps=False)
-            result.extend((seg.start, seg.end, seg.text.strip()) for seg in segments if seg.text.strip())
-
-        # An in-process engine gets the same wall-clock limit as the CLI engines and ffmpeg.
-        t = threading.Thread(target=work, daemon=True)
-        t.start()
-        t.join(STATE.timeout or None)
-        if t.is_alive():
-            die(f"faster-whisper exceeded the {STATE.timeout:.0f} s time limit; raise --timeout for a long recording", code=124, kind="timeout")
-        cues = list(result)
-        if cues:
-            info("transcribed with faster-whisper")
-            write_srt(cues, out_srt)
-            return cues
-    except ImportError:
-        pass
-    # 3. openai-whisper CLI
-    if shutil.which("whisper"):
-        cmd = ["whisper", wav, "--model", model, "--output_format", "srt", "--output_dir", tmpdir]
-        if language:
-            cmd += ["--language", language]
-        proc = _asr_run(cmd, subprocess, "openai-whisper")
-        srt = os.path.join(tmpdir, "audio.srt")
-        if proc.returncode == 0 and os.path.exists(srt):
-            info("transcribed with openai-whisper")
-            cues = parse_srt(srt)
-            write_srt(cues, out_srt)
-            return cues
-    die("no local speech-to-text engine found for --transcribe.\n"
-        "Install one (all run offline):\n"
-        "  whisper.cpp:    brew install whisper-cpp   (then download a model: ggml-base.bin)\n"
-        "  faster-whisper: pip install faster-whisper\n"
-        "  openai-whisper: pip install openai-whisper\n"
-        "Or write the cues by hand with --text cues.txt (see format above).")
-    return []
-
-
-def parse_srt(path: str) -> List[Tuple[float, float, str]]:
-    cues: List[Tuple[float, float, str]] = []
-    block: List[str] = []
-    content = read_text_or_die(path, "--srt").lstrip("\ufeff").replace("\r\n", "\n") + "\n\n"
-    for line in content.split("\n"):
-        if line.strip():
-            block.append(line)
-            continue
-        if block:
-            times = next((b for b in block if "-->" in b), None)
-            if times:
-                a, b = times.split("-->")
-                text = "\n".join(block[block.index(times) + 1:]).strip()
-                try:
-                    cues.append((parse_time(a), parse_time(b), text))
-                except ValueError as e:  # includes MissingFpsError: SRT timings are hh:mm:ss,ms, never frames
-                    die(f"{path}: cannot read the timing line {times.strip()!r}: {e}")
-            block = []
-    if not cues:
-        die(f"no cues found in {path}")
-    return cues
-
-
-def write_srt(cues: List[Tuple[float, float, str]], path: str) -> None:
-    with open(path, "w", encoding="utf-8") as fh:
-        for i, (s, e, t) in enumerate(cues, 1):
-            # A blank line is SRT's own block separator (index/timecode/text, blank, next block).
-            # Cue text can contain one -- parse_text_cues() turns a bare "|" into "\n", so a source
-            # line with two adjacent pipes ("a||b") becomes "a\n\nb" -- and writing that blank line
-            # raw would split one cue into two malformed half-blocks (the second missing its own
-            # index/timecode). Collapse any run of blank lines within the cue text to a single
-            # newline so the cue's own text can never fake the format's block boundary.
-            t = re.sub(r"\n{2,}", "\n", t).strip("\n")
-            fh.write(f"{i}\n{fmt_srt_time(s)} --> {fmt_srt_time(e)}\n{t}\n\n")
-
-
 def word_durations_from_audio(video: str, start: float, end: float, n_words: int, audio_stream: int = 0) -> List[int]:
     """Split a cue's time across n_words in proportion to speech energy (centiseconds each).
 
@@ -434,7 +300,8 @@ def plan_emoji(cues, args, play_w, play_h, brand=None):
 
 def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float], max_lines: int,
                 min_duration: float, offset: float, wrap: str = "phrase",
-                lang: Optional[str] = None) -> Tuple[List[Tuple[float, float, str]], dict]:
+                lang: Optional[str] = None, per_cue_em: Optional[List[Optional[float]]] = None,
+                per_cue_size: Optional[List[int]] = None) -> Tuple[List[Tuple[float, float, str]], dict]:
     """Shift, wrap, split and lengthen cues so they can actually be read.
 
     `offset` moves every cue (a transcript that runs early/late); `max_em` wraps each cue to the
@@ -442,11 +309,25 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
     a cue needing more than `max_lines` lines is split into consecutive cues sharing its time in
     proportion to their text; a cue shorter than `min_duration` is lengthened, never past the next
     cue's start. Returns the new cues and a count of what changed.
+
+    `per_cue_em` (--fit-size-scope cue) gives cue i its OWN line budget instead of the file's:
+    a cue drawn at a larger size has a narrower line in em, and wrapping it to the file-wide
+    budget -- which is the budget of the SMALLEST size -- produced lines that overflowed the
+    frame when they were then drawn large. `per_cue_size` rides along so the caller knows which
+    size each OUTPUT cue belongs to after splits have renumbered them; it comes back as
+    `stats["cue_sizes"]`, one entry per returned cue.
     """
     stats = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0, "rebalanced": 0,
              "wrap": wrap, "phrase_breaks": 0}
     staged: List[Tuple[float, float, str]] = []
-    for start, end, text in cues:
+    staged_sizes: List[Optional[int]] = []
+    for cue_index, (start, end, text) in enumerate(cues):
+        own_em = max_em
+        own_size = None
+        if per_cue_em is not None and cue_index < len(per_cue_em):
+            own_em = per_cue_em[cue_index]
+        if per_cue_size is not None and cue_index < len(per_cue_size):
+            own_size = per_cue_size[cue_index]
         if offset:
             start, end = start + offset, end + offset
             if end <= 0:
@@ -454,14 +335,14 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
                 continue
             start = max(0.0, start)
             stats["shifted"] += 1
-        if max_em and max_em > 0:
+        if own_em and own_em > 0:
             # one greedy fill per cue, three answers off it: what gets burnt in, what the
             # greedy wrap would have given (`rebalanced`) and what 1.15's wrap would have
             # given (`phrase_breaks`). Three wrap_text() calls re-ran the atomiser each time.
-            lines, greedy, measured = wrap_variants(text, max_em, mode=wrap, lang=lang)
+            lines, greedy, measured = wrap_variants(text, own_em, mode=wrap, lang=lang)
             if lines != [l for l in text.split("\n") if l.strip()]:
                 stats["wrapped"] += 1
-            if any(text_width_em(l) > max_em for l in lines):
+            if any(text_width_em(l) > own_em for l in lines):
                 # a run with no break point the wrapper may use (a long word, a Thai phrase
                 # without spaces) stays long rather than chopped: say so, and name the fix
                 stats["overlong"] = stats.get("overlong", 0) + 1
@@ -477,11 +358,13 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
                 for chunk, weight in zip(chunks, weights):
                     seg = (end - start) * weight / total_w
                     staged.append((t, min(end, t + seg), "\n".join(chunk)))
+                    staged_sizes.append(own_size)
                     t += seg
                 stats["split"] += len(chunks) - 1
                 continue
             text = "\n".join(lines)
         staged.append((start, end, text))
+        staged_sizes.append(own_size)
     out: List[Tuple[float, float, str]] = []
     for i, (start, end, text) in enumerate(staged):
         if min_duration and end - start < min_duration:
@@ -491,6 +374,8 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
                 stats["extended"] += 1
                 end = new_end
         out.append((start, end, text))
+    if per_cue_size is not None:
+        stats["cue_sizes"] = staged_sizes
     return out, stats
 
 
@@ -511,12 +396,7 @@ def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[
     --size is in ASS points against a 288-line script (what libass's force_style uses), so the
     rendered pixel size is size * play_h / 288.
     """
-    if not play_w or not play_h or not args.size:
-        return None
-    size_px = args.size * play_h / 288.0
-    if size_px <= 0:
-        return None
-    return (play_w * SAFE_WIDTH_FRACTION) / size_px
+    return line_em_for_size(args.size, play_w, play_h)
 
 
 def parse_ass_dialogue(path: str) -> str:
@@ -561,44 +441,6 @@ def shift_ass_file(src: str, dst: str, offset: float) -> int:
     return n
 
 
-def whisper_word_timings(srt_path: Optional[str]) -> List[Tuple[float, float, str]]:
-    """Word timings from a whisper JSON transcript sitting next to the SRT, if there is one.
-
-    whisper (and faster-whisper, and whisper.cpp's --output-json) can emit per-word start/end
-    times; when they are there, --karaoke should follow the real speech instead of splitting the
-    cue evenly. Looked for as <stem>.json and <stem>.words.json next to the SRT, in either the
-    {"segments": [{"words": [{"word": ..., "start": ..., "end": ...}]}]} or a bare
-    {"words": [...]} shape. Anything unreadable is simply "no word timings".
-    """
-    if not srt_path:
-        return []
-    stem = os.path.splitext(srt_path)[0]
-    for cand in (stem + ".words.json", stem + ".json"):
-        if not os.path.exists(cand):
-            continue
-        try:
-            data = json.loads(Path(cand).read_text(encoding="utf-8"))
-        except (OSError, ValueError):
-            continue
-        raw = []
-        if isinstance(data, dict):
-            raw = list(data.get("words") or [])
-            for seg in data.get("segments") or []:
-                raw.extend((seg or {}).get("words") or [])
-        words = []
-        for w in raw:
-            try:
-                text = str(w.get("word") or w.get("text") or "").strip()
-                if text:
-                    words.append((float(w["start"]), float(w["end"]), text))
-            except (AttributeError, KeyError, TypeError, ValueError):
-                continue
-        if words:
-            info(f"karaoke: word timings from {os.path.basename(cand)} ({len(words)} words)")
-            return sorted(words)
-    return []
-
-
 def word_durations_from_timings(words: List[Tuple[float, float, str]], start: float, end: float,
                                 n_words: int) -> Optional[List[int]]:
     """Centiseconds per word for one cue, from real word timings; None when they don't cover it."""
@@ -639,7 +481,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         "", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
     ]
     lines = []
-    for start, end, text in cues:
+    for cue_index, (start, end, text) in enumerate(cues):
         # ASS Dialogue text treats a literal `{...}` as an override block -- real style/animation
         # commands, not literal characters. Cue text (from --text, an SRT, or ASR transcription --
         # all effectively user-controlled) that happens to contain braces would otherwise be
@@ -657,6 +499,15 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
         elif args.animate == "slide":
             fx = "{\\fad(150,150)\\move(%d,%d,%d,%d,0,250)}" % (play_w // 2, play_h - margin + int(30 * scale), play_w // 2, play_h - margin)
         body = text
+        # --fit-size-scope cue: one size per cue, as a leading {\fsN} override. Opt-in only --
+        # see fit_size()'s docstring for why a size that changes cue to cue is not the default.
+        # The size is the one THIS cue was laid out at, carried through layout_cues; re-measuring
+        # here would measure the post-layout text (already carrying the wrap's newlines), which
+        # is a different string from the one the fit was computed on.
+        own_sizes = getattr(args, "_fit_sizes_out", None) or []
+        own = own_sizes[cue_index] if cue_index < len(own_sizes) else None
+        if own and own != args.size:
+            fx += "{\\fs%d}" % int(round(own * scale))
         if args.karaoke:
             # split each line into words and give every word an equal share of the cue (\k is in centiseconds)
             dur_cs = max(1, int(round((end - start) * 100)))
@@ -898,6 +749,15 @@ def main() -> int:
     emo.add_argument("--emoji-max", type=int, default=60,
                      help="most emoji overlays one run may build (default 60)")
     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("--fit-size", choices=["auto", "on", "off"], default="auto",
+                     help="shrink the caption size until the cue fits --max-lines, BEFORE splitting it: "
+                          "'auto' (default) only when no --size was given, 'on' always, 'off' for 1.16 behaviour")
+    sty.add_argument("--min-size", type=int, default=None,
+                     help="smallest size --fit-size may use, in ASS points (default 13 = 4.5%% of the frame height, "
+                          "the legibility floor)")
+    sty.add_argument("--fit-size-scope", choices=["file", "cue"], default="file",
+                     help="one fitted size for the whole file (default) or one per cue (a size that changes "
+                          "cue to cue reads as a mistake, so it is opt-in)")
     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)")
     sty.add_argument("--wrap", choices=list(WRAP_MODES), default="phrase",
                      help="how a cue too wide for the safe area is broken into lines: 'phrase' (default, 1.16) never "
@@ -930,6 +790,10 @@ def main() -> int:
     if args.brand and bcap.get("box") and not args.box:
         args.box = True
     args.font = args.font or (bcap.get("font") if args.brand else None) or brand.get("font") or "DejaVu Sans"
+    # --fit-size auto shrinks only a size the skill itself chose. An explicit --size is a
+    # statement about the look and is never quietly overridden; a brand's caption size is the
+    # same kind of statement, so it counts as explicit too.
+    args._size_explicit = args.size is not None or bool(args.brand and bcap.get("size") is not None)
     args.size = args.size if args.size is not None else (bcap.get("size", 24) if args.brand else 24)
     args.color = color_hex(args.color or (bcap.get("color") if args.brand else None) or bc.get("text", "FFFFFF"))
     args.outline_color = color_hex(args.outline_color or bc.get("outline", "000000"))
@@ -969,6 +833,11 @@ def main() -> int:
     args.offset = signed_time_arg(str(args.offset), "--offset")
     if args.max_lines < 1:
         die("--max-lines must be at least 1")
+    if args.min_size is not None and args.min_size < 1:
+        die("--min-size must be at least 1", kind="input")
+    if args.min_size is not None and args.min_size > args.size:
+        die(f"--min-size {args.min_size} is larger than --size {args.size}: the floor cannot be "
+            "above the size it is a floor for", kind="input")
     if args.min_duration < 0:
         die("--min-duration cannot be negative")
 
@@ -991,20 +860,95 @@ def main() -> int:
         play_w, play_h = meta["video"]["width"], meta["video"]["height"]
         if meta["video"].get("rotation") in (90, -90, 270, -270):
             play_w, play_h = play_h, play_w
-
+    # A --plan or --dry-run written before the input exists has no geometry to fit against, and a
+    # plan that describes a different FontSize from the run that executes it is not a plan. When
+    # --platform names a destination, that destination's frame IS the geometry the real run will
+    # have, so the fit is computed against it; with no platform there is nothing to stand in for
+    # the frame, and size_used is reported as null rather than presenting the requested size as
+    # the size that was used.
+    planned_frame = False
+    if not (play_w and play_h) and args.platform and PLATFORMS[args.platform].get("frame"):
+        frame = PLATFORMS[args.platform]["frame"]
+        play_w, play_h = frame["w"], frame["h"]
+        planned_frame = True
+        info(f"[plan] no geometry to measure yet; fitting the caption size against the "
+             f"--platform {args.platform} frame ({play_w}x{play_h})")
+
+    args._fit_floor = args.min_size if args.min_size is not None else ass_units(MIN_CAPTION_FRACTION)
+    fit_unmeasurable = not (play_w and play_h)
+    fit_stats: dict = {"fit_size": args.fit_size, "size_requested": args.size,
+                       "size_used": None if fit_unmeasurable else args.size,
+                       "size_floor": args._fit_floor,
+                       "size_pct_height": round(args.size * 100.0 / ASS_SCRIPT_HEIGHT, 2),
+                       "shrunk": 0, "fit_scope": args.fit_size_scope, "fit_exhausted": False}
     caption_stats: dict = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0,
                            "rebalanced": 0, "wrap": args.wrap, "phrase_breaks": 0}
+    caption_stats.update(fit_stats)
+
+    def fit_params():
+        return dict(size=fit_stats["size_requested"], min_size=args._fit_floor,
+                    max_lines=args.max_lines, play_w=play_w, play_h=play_h,
+                    mode=args.wrap, lang=args.language, scope=args.fit_size_scope)
+
+    def fit_the_size(cue_list):
+        """Shrink --size until every cue fits --max-lines, BEFORE the cue is split.
+
+        This is the whole point of the ordering: at a size the cue cannot fit, layout_cues splits
+        the sentence into consecutive cues and half of it arrives late (eval 17). The text is never
+        touched -- only the type size, and never below the legibility floor.
+        """
+        if args.fit_size == "off" or (args.fit_size == "auto" and args._size_explicit):
+            fit_stats["size_used"] = args.size    # a stated size IS the size used
+            return
+        if fit_unmeasurable:
+            # Nothing to measure against: size_used stays null rather than presenting the
+            # requested size as one that was fitted.
+            return
+        if args.mode == "mux":
+            # Soft subtitles carry no size: the player picks it. Shrinking would change nothing a
+            # viewer sees and would silently change the SRT this run writes, so the mux path is
+            # left exactly as 1.16 wrote it.
+            return
+        fit = fit_size(cue_list, **fit_params())
+        fit_stats["size_used"] = fit["size"]
+        fit_stats["size_source"] = "platform-frame" if planned_frame else "input"
+        fit_stats["shrunk"] = fit["shrunk"]
+        fit_stats["fit_exhausted"] = bool(fit["shrunk"]) and not fit["fits"]
+        fit_stats["size_pct_height"] = round(fit["size"] * 100.0 / ASS_SCRIPT_HEIGHT, 2)
+        if fit["size"] != args.size:
+            info(f"caption size {args.size} -> {fit['size']} ASS units "
+                 f"({fit_stats['size_pct_height']:.1f} % of frame height) so {fit['shrunk']} cue(s) "
+                 f"fit --max-lines {args.max_lines}; floor {args._fit_floor}")
+            args.size = fit["size"]
+        elif fit_stats["fit_exhausted"]:
+            info(f"caption size stays {args.size} ASS units: {fit['shrunk']} cue(s) still need more "
+                 f"than {args.max_lines} line(s) at the floor {args._fit_floor} and are split "
+                 "(--min-size goes smaller; `|` sets the break yourself)")
+        if args.fit_size_scope == "cue":
+            # Each cue is laid out at ITS OWN size, not at the file minimum. A cue drawn larger
+            # has a NARROWER line in em, so wrapping everything to the minimum size's (widest)
+            # budget and then drawing some cues large put lines off the side of the frame.
+            args._fit_cue_em = [line_em_for_size(fit["per_cue"].get(i, fit["size"]),
+                                                 play_w, play_h)
+                                for i in range(len(cue_list))]
+            args._fit_cue_size = [fit["per_cue"].get(i, fit["size"]) for i in range(len(cue_list))]
 
     def lay_out(cue_list):
         """Wrap to the safe area, split past --max-lines, lengthen to --min-duration, shift by
         --offset -- the one place every cue source goes through, so an SRT, a cue file and a
         transcript all come out equally readable."""
+        fit_the_size(cue_list)
         out, stats = layout_cues(cue_list, max_em=max_line_em(args, play_w, play_h),
                                  max_lines=args.max_lines, min_duration=args.min_duration,
-                                 offset=args.offset, wrap=args.wrap, lang=args.language)
+                                 offset=args.offset, wrap=args.wrap, lang=args.language,
+                                 per_cue_em=getattr(args, "_fit_cue_em", None),
+                                 per_cue_size=getattr(args, "_fit_cue_size", None))
+        # which size each OUTPUT cue belongs to, after splits have renumbered them
+        args._fit_sizes_out = stats.pop("cue_sizes", None)
         report_layout(stats)
         caption_stats.clear()
         caption_stats.update(stats)
+        caption_stats.update(fit_stats)
         return out, any(v for k, v in stats.items() if k != "wrap")
 
     # --srt is repeatable since 1.16 (one per language, each with an optional `:lang` suffix).

package/scripts/cut.py

@@ -25,11 +25,13 @@ Examples:
   python3 cut.py talk.mp4 --start 1:00 --end 2:00 -o part.wav                   # audio extraction
 """
 import argparse
+import json
 import os
 import sys
 import tempfile
 from typing import List, Tuple
 
+from _common import (beat_grid, snap_points, decode_pcm_mono, rms_envelope, BEAT_MIN_CONFIDENCE)
 from _common import 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, refuse_output_is_input, fmt_secs
 
 # outputs whose re-encode dropped a subtitle/data stream (reported as dropped_non_av_streams)
@@ -148,6 +150,123 @@ def cut_one(src: str, start: float, end: float, dst: str, reencode: bool, crf: i
     return reencode
 
 
+BEAT_RATE = 22050  # the decode rate the onset pass uses, matching scenes.py --beats
+
+
+def _grid_from_source(path: str, min_confidence: float) -> "dict":
+    """The beat grid of `path`: a scenes.py --json document if that is what it is, otherwise a
+    media file to measure. Reading a document is how a caller avoids a second decode."""
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            doc = json.load(fh)
+    except (OSError, ValueError):
+        doc = None
+    if isinstance(doc, dict) and doc.get("beat_grid"):
+        grid = dict(doc["beat_grid"])
+        grid["beats"] = doc.get("beats") or []
+        # A scenes.py document carries the supported subset since 1.17; one written by an older
+        # build does not, and a grid whose supported points are unknown is not one this tool may
+        # move a cut onto -- an unknown subset is not an empty one, but it is not a measurement
+        # either, so it is refused rather than silently treated as "all of them".
+        grid["supported_beats"] = doc.get("beat_grid", {}).get("supported_beats")
+        if grid["supported_beats"] is None:
+            grid["supported_beats"] = doc.get("supported_beats")
+        try:
+            tempo = grid.get("tempo_bpm")
+            grid["tempo_bpm"] = float(tempo) if tempo is not None else None
+            grid["confidence"] = float(grid.get("confidence") or 0.0)
+        except (TypeError, ValueError):
+            die(f"--snap-source {path}: beat_grid.tempo_bpm and .confidence must be numbers "
+                "(regenerate it with `scenes.py MUSIC --beats --json`)", kind="input")
+        if grid["beats"] and grid["tempo_bpm"] is None:
+            die(f"--snap-source {path}: this document lists beats but no tempo_bpm, so no grid "
+                "was actually measured in it. Regenerate it with "
+                "`scenes.py MUSIC --beats --json`.", kind="input")
+        grid["usable"] = grid["confidence"] >= min_confidence
+        return grid
+    if isinstance(doc, dict):
+        die(f"--snap-source {path}: this JSON has no beat_grid -- produce one with "
+            "`scenes.py MUSIC --beats --json`", kind="input")
+    samples = decode_pcm_mono(path, BEAT_RATE, check=False)
+    env = rms_envelope(samples, max(1, int(round(BEAT_RATE * 0.01))))
+    return beat_grid(env, 0.01, min_confidence=min_confidence)
+
+
+def snap_segments(args, segments, meta, total):
+    """Move every in/out point to the nearest measured beat. Returns (result dict, segments).
+
+    A cut point may move to a measured, onset-supported grid point and may not appear from one:
+    the number of segments is unchanged, and nothing is ever proposed. The keyframe/tolerance
+    decision downstream then runs on the snapped values, which is the right order -- whether a cut
+    can be lossless depends on where it actually lands.
+    """
+    source = args.snap_source or args.input
+    if not args.snap_source and not meta.get("audio"):
+        die("--snap beats needs audio to measure a beat in; this file has none. Cut without it "
+            "(--snap none), or pass --snap-source with the music bed.", kind="input")
+    # Compare the PARSED segments against the whole file, not the raw --start string: "0:00",
+    # "0.0" and "00:00:00" are all a zero start that a string comparison lets through, and the
+    # run would then snap the implicit end point and silently shorten a whole-file copy.
+    whole_file = (len(segments) == 1 and abs(segments[0][0]) < 1e-6
+                  and (not total or abs(segments[0][1] - total) < 1e-6))
+    if whole_file:
+        die("--snap beats has no in or out point to move: this run copies the whole file. Give "
+            "--start/--end (or --segments), or drop --snap.", kind="input")
+    # A floor of zero would make the confidence check vacuous -- a grid measured from noise scores
+    # above 0.0 and would pass -- and the whole point of the flag is that a cut only moves onto a
+    # pulse somebody can hear. The number is a floor on belief, so it must be a positive one.
+    if args.min_confidence <= 0:
+        die("--min-confidence must be greater than 0: at 0 every grid is 'reliable', including "
+            "one measured from noise, which is exactly what --snap beats must not cut to. Use "
+            "--snap none if you do not want the points moved at all.", kind="input")
+    grid = _grid_from_source(source, args.min_confidence)
+    confidence = float(grid.get("confidence") or 0.0)
+    tempo = grid.get("tempo_bpm")
+    if confidence < args.min_confidence or not grid.get("beats"):
+        die(f"no reliable beat grid in this audio (confidence {confidence:.2f}, needs "
+            f"{args.min_confidence:.2f}): cutting to invented beats would move your in/out points "
+            "to times nothing in the audio supports. Re-run with --snap none, or pass "
+            "--snap-source from a music bed.", kind="input")
+    # THE grid a cut may move onto is the onset-supported subset, never the full regular grid.
+    # beat_grid() reports a regular grid over the whole duration by design -- a grid has to be
+    # regular -- so it runs on through a passage with no music in it. Snapping to one of those
+    # points moves a cut to a time nothing in the audio marks, which is the fabrication this
+    # release forbids and which this tool's own refusal text promises it does not do.
+    supported = grid.get("supported_beats")
+    if supported is None:
+        die(f"--snap-source {source}: this document does not say which grid points a measured "
+            "onset supports, so there is no way to tell a beat from a gap in it. Regenerate it "
+            "with `scenes.py MUSIC --beats --json`.", kind="input")
+    if not supported:
+        die(f"no measured onset supports any point of this beat grid (confidence "
+            f"{confidence:.2f}): the grid is regular but nothing in the audio marks it, so every "
+            "move would be to an invented time. Re-run with --snap none, or pass --snap-source "
+            "from a music bed.", kind="input")
+    points = [t for seg in segments for t in seg]
+    moved = snap_points(points, supported, args.snap_tolerance)
+    out_segments = []
+    for i in range(0, len(moved), 2):
+        s, e = moved[i]["to"], moved[i + 1]["to"]
+        if e <= s:   # a snap that would collapse the segment is not applied to it
+            s, e = moved[i]["from"], moved[i + 1]["from"]
+            moved[i].update({"to": s, "delta": 0.0, "snapped": False, "beat_index": None})
+            moved[i + 1].update({"to": e, "delta": 0.0, "snapped": False, "beat_index": None})
+        out_segments.append((s, e))
+    snapped = sum(1 for m in moved if m["snapped"])
+    for m in moved:
+        if m["snapped"]:
+            info(f"--snap beats: {m['from']:.3f}s -> {m['to']:.3f}s ({m['delta'] * 1000:+.0f} ms)")
+    info(f"--snap beats: {tempo:.1f} BPM, confidence {confidence:.2f}; {snapped} of {len(moved)} "
+         f"point(s) moved, within {args.snap_tolerance:.3f}s, onto {len(supported)} of "
+         f"{len(grid['beats'])} grid point(s) a measured onset supports")
+    return ({"mode": "beats", "tolerance": args.snap_tolerance, "confidence": confidence,
+             "tempo_bpm": tempo, "grid": "supported", "grid_points": len(supported),
+             "moved": [dict(m) for m in moved], "snapped": snapped,
+             "unchanged": len(moved) - snapped,
+             "source": "measured" if not args.snap_source else args.snap_source},
+            out_segments)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     ap.add_argument("input")
@@ -159,6 +278,17 @@ def main() -> int:
     ap.add_argument("--segments", help="comma separated START-END list, e.g. '0:05-0:12,1:00-1:20' (joined in order)")
     ap.add_argument("--accurate", action="store_true", help="always re-encode for frame-accurate (video) / sample-accurate (audio) cuts (default: lossless -c copy, re-encoding only when the keyframe snap exceeds --tolerance)")
     ap.add_argument("--tolerance", type=float, default=0.5, help="max seconds a lossless cut may deviate before re-encoding kicks in (default 0.5, -1 = never)")
+    snap = ap.add_argument_group("beat snapping")
+    snap.add_argument("--snap", choices=["none", "beats"], default="none",
+                      help="move each in/out point to the nearest measured beat (default none)")
+    snap.add_argument("--snap-tolerance", type=float, default=0.12,
+                      help="most seconds a point may move with --snap beats (default 0.12, about a "
+                           "quarter of a beat at 120 BPM)")
+    snap.add_argument("--snap-source", metavar="FILE",
+                      help="take the beat grid from this scenes.py --beats --json document (or from "
+                           "this media file) instead of measuring the input again")
+    snap.add_argument("--min-confidence", type=float, default=BEAT_MIN_CONFIDENCE,
+                      help=f"refuse to snap below this measured beat confidence (default {BEAT_MIN_CONFIDENCE})")
     ap.add_argument("--crf", type=int, default=18, help="x264 CRF when re-encoding (default 18)")
     ap.add_argument("--preset", default="medium", choices=X264_PRESETS, help="x264 preset when re-encoding")
     add_common(ap)
@@ -196,6 +326,10 @@ def main() -> int:
             die("end must be after start")
         segments = [(start, end)]
 
+    snap_result = None
+    if args.snap == "beats":
+        snap_result, segments = snap_segments(args, segments, meta, total)
+
     for s, e in segments:
         if total and s >= total:
             die(f"segment start {s:.3f}s is beyond the media duration {total:.3f}s")
@@ -249,7 +383,8 @@ def main() -> int:
          # the trade the caller can offer instead of a re-encode (eval e02: "without losing quality")
          lossless_alternative=(f"--start {min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])):.3f} lands on a keyframe: "
                                f"stream copy with no re-encode, {abs(min(NEAREST_KEYFRAMES, key=lambda k: abs(k - segments[0][0])) - segments[0][0]):.2f}s off the requested start")
-         if mode == "hybrid" and NEAREST_KEYFRAMES and len(segments) == 1 else None)
+         if mode == "hybrid" and NEAREST_KEYFRAMES and len(segments) == 1 else None,
+         snap=snap_result)
     return 0