ffmpeg-skill 1.16.0 → 1.17.0

package/scripts/_common/decision.py

@@ -7,6 +7,7 @@ and encoder-selection rules testable on their own.
 from __future__ import annotations
 
 import json
+import math
 import os
 import argparse
 from pathlib import Path
@@ -518,3 +519,348 @@ def propose_chapters(duration: float, silences: "Sequence", scene_cuts: "Sequenc
 def description_block(chapters: "Sequence") -> str:
     """The YouTube description form of a chapter list: `00:00 Chapter 1` per line."""
     return "\n".join(f"{fmt_chapter_time(c['at'])} {c['title']}" for c in chapters)
+
+
+# ------------------------------------------------------------------ the beat grid (1.17)
+#
+# A beat grid is a measurement of the music's periodicity -- not a statement about where a cut
+# belongs. Everything here is arithmetic on an RMS envelope somebody else decoded; nothing in this
+# module decides to cut anything, and nothing invents a beat the audio does not support.
+
+BEAT_ONSET_K = 1.5          # peak threshold: median + k * MAD over the local window
+BEAT_WINDOW_S = 1.0         # +/- this many seconds is "local" for the threshold
+BEAT_REFRACTORY_S = 0.06    # two onsets closer than this are one onset
+BEAT_SUPPORT_DIVISOR = 4    # a grid point with no onset within interval/4 is "unsupported"
+BEAT_ALIGN_DIVISOR = 8      # an onset within interval/8 of a grid point counts as aligned
+BEAT_MIN_CONFIDENCE = 0.5   # the default below which a tool that CHANGES a file refuses to snap
+BEAT_OCTAVE_MARGIN = 1.2    # a half/double-tempo grid must explain this much more onset strength
+BEAT_Z_FLOOR = 2.0          # autocorrelation z-score at which periodicity starts counting
+BEAT_Z_SPAN = 4.0           # ... and the span over which it reaches 1.0
+
+
+def _onset_strength(envelope: "Sequence[float]") -> "List[float]":
+    """Half-wave-rectified first difference of log(env), i.e. a compression-domain spectral-flux
+    analogue. The log matters: the level-domain difference over-weights the loud sections, so a
+    quiet verse contributes no onsets at all and the tempo is measured on the chorus alone."""
+    import math as _math
+    log_env = [_math.log(max(0.0, float(e)) + 1e-9) for e in envelope]
+    return [0.0] + [max(0.0, log_env[i] - log_env[i - 1]) for i in range(1, len(log_env))]
+
+
+def _pick_onsets(strength: "Sequence[float]", step_s: float) -> "List[int]":
+    """Indices of local maxima above median + k*MAD over a +/-BEAT_WINDOW_S window, with a
+    refractory gap. A median/MAD threshold rather than a mean/stdev one because a handful of very
+    strong hits would drag a mean-based threshold above every other onset in the piece."""
+    n = len(strength)
+    if n < 3:
+        return []
+    half = max(1, int(round(BEAT_WINDOW_S / max(step_s, 1e-9))))
+    refractory = max(1, int(round(BEAT_REFRACTORY_S / max(step_s, 1e-9))))
+    picked: "List[int]" = []
+    for i in range(1, n - 1):
+        s = strength[i]
+        if s <= 0 or s < strength[i - 1] or s < strength[i + 1]:
+            continue
+        window = sorted(strength[max(0, i - half):min(n, i + half + 1)])
+        if not window:
+            continue
+        med = window[len(window) // 2]
+        devs = sorted(abs(x - med) for x in window)
+        mad = devs[len(devs) // 2]
+        if s < med + BEAT_ONSET_K * mad or s <= med:
+            continue
+        if picked and i - picked[-1] < refractory:
+            if s > strength[picked[-1]]:
+                picked[-1] = i
+            continue
+        picked.append(i)
+    return picked
+
+
+def _autocorrelation_peak(strength: "Sequence[float]", step_s: float,
+                          bpm_range: "Sequence[float]") -> "tuple":
+    """(best lag in samples, peak, mean, standard deviation) of the onset signal's
+    autocorrelation over the lags `bpm_range` allows, or (None, 0.0, 0.0, 0.0).
+
+    The spread matters as much as the peak: every signal's autocorrelation has a maximum
+    somewhere, so "the peak is above the mean" says nothing. How far above it stands relative to
+    the spread of the other lags is what separates a pulse from noise.
+    """
+    n = len(strength)
+    hi_bpm, lo_bpm = max(bpm_range), min(bpm_range)
+    lag_min = max(1, int(round(60.0 / hi_bpm / max(step_s, 1e-9))))
+    lag_max = int(round(60.0 / lo_bpm / max(step_s, 1e-9)))
+    lag_max = min(lag_max, n - 1)
+    if lag_max < lag_min:
+        return (None, 0.0, 0.0, 0.0)
+    mean = sum(strength) / n if n else 0.0
+    centred = [s - mean for s in strength]
+    best_lag, best = None, 0.0
+    values = []
+    for lag in range(lag_min, lag_max + 1):
+        acc = sum(centred[i] * centred[i + lag] for i in range(n - lag))
+        acc /= (n - lag)
+        values.append(acc)
+        if best_lag is None or acc > best:
+            best_lag, best = lag, acc
+    mean_acc = sum(values) / len(values) if values else 0.0
+    var = sum((v - mean_acc) ** 2 for v in values) / len(values) if values else 0.0
+    return (best_lag, best, mean_acc, math.sqrt(var))
+
+
+def _grid_score(onset_times: "Sequence[float]", strength_at: "Dict[int, float]",
+                interval: float, phase: float) -> float:
+    """Total onset strength landing within interval/BEAT_ALIGN_DIVISOR of the grid."""
+    if interval <= 0:
+        return 0.0
+    tol = interval / BEAT_ALIGN_DIVISOR
+    total = 0.0
+    for i, t in enumerate(onset_times):
+        off = (t - phase) % interval
+        if min(off, interval - off) <= tol:
+            total += strength_at.get(i, 1.0)
+    return total
+
+
+def beat_grid(envelope: "Sequence[float]", step_s: float, *,
+              bpm_range: "Sequence[float]" = (60, 200),
+              min_confidence: float = BEAT_MIN_CONFIDENCE,
+              duration: "Optional[float]" = None) -> "Dict[str, Any]":
+    """A beat grid from an RMS envelope. Pure: numbers in, a dict out -- no ffmpeg, no I/O.
+
+    Returns {"beats": [t, ...], "tempo_bpm": float|None, "interval": float|None,
+             "confidence": 0..1, "onsets": [t, ...], "phase": float,
+             "supported": int, "unsupported": int, "usable": bool,
+             "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo, hi]}
+
+    The method, in full, so a report can quote it:
+      1. onset strength = half-wave-rectified first difference of log(env + 1e-9);
+      2. onsets = local maxima above median + 1.5 * MAD over a +/-1 s window, 60 ms refractory;
+      3. tempo = the best autocorrelation lag of the onset signal inside `bpm_range`, with its
+         half and double checked and the one whose onsets align better preferred (octave
+         disambiguation: 60, 120 and 240 BPM all autocorrelate on a 120 BPM track);
+      4. phase = the offset in [0, interval) at which the grid catches the most onset strength;
+      5. beats = phase + n * interval across the duration. A grid must be regular, so a grid
+         point with no measured onset within interval/4 is still reported -- and counted in
+         `unsupported`, so a caller can see how much of the grid the audio actually supports.
+         `supported_beats` is the subset that a measured onset does support: it is what a tool
+         that MOVES something must snap to, because a regular grid runs on through a passage with
+         no music in it and a point moved there was moved to a time nothing in the audio marks;
+      6. confidence = 0.5 * clip((z - 2) / 4, 0, 1)
+                    + 0.5 * (fraction of onsets within interval/8 of a grid point),
+         where z is how many standard deviations the winning autocorrelation lag stands above
+         the mean of the others. The plain peak/mean ratio is not used: every signal's
+         autocorrelation has a maximum somewhere, so a peak above the mean says nothing -- noise
+         scores 2.9 on it, which would read as full confidence.
+
+    A flat or empty envelope has no pulse: confidence 0.0, tempo None, beats []. That is a
+    measurement, not a failure -- the caller decides whether 0.0 is enough to act on.
+    """
+    step_s = float(step_s)
+    env = list(envelope or [])
+    lo_bpm, hi_bpm = float(min(bpm_range)), float(max(bpm_range))
+    out: "Dict[str, Any]" = {
+        "beats": [], "supported_beats": [], "tempo_bpm": None, "interval": None,
+        "confidence": 0.0, "onsets": [],
+        "phase": 0.0, "supported": 0, "unsupported": 0, "usable": False,
+        "method": "rms-flux-autocorrelation", "step_s": step_s, "range_bpm": [lo_bpm, hi_bpm],
+    }
+    if len(env) < 4 or step_s <= 0:
+        return out
+    total_s = float(duration) if duration else len(env) * step_s
+
+    strength = _onset_strength(env)
+    if not any(strength):
+        return out
+    idx = _pick_onsets(strength, step_s)
+    onset_times = [i * step_s for i in idx]
+    out["onsets"] = [round(t, 4) for t in onset_times]
+    if len(idx) < 2:
+        return out
+
+    best_lag, peak, mean_acc, sd_acc = _autocorrelation_peak(strength, step_s, (lo_bpm, hi_bpm))
+    if not best_lag or peak <= 0:
+        return out
+    interval = best_lag * step_s
+    strength_at = {i: strength[j] for i, j in enumerate(idx)}
+
+    # Octave disambiguation: try half and double the candidate interval and keep the one whose
+    # grid catches the most onset strength per grid point (per point, or a denser grid always wins).
+    candidates = [interval]
+    for factor in (0.5, 2.0):
+        alt = interval * factor
+        if 60.0 / hi_bpm <= alt <= 60.0 / lo_bpm:
+            candidates.append(alt)
+
+    def best_phase(iv: float) -> "tuple":
+        steps = max(4, int(round(iv / step_s)))
+        best_ph, best_sc = 0.0, -1.0
+        for k in range(steps):
+            ph = k * iv / steps
+            sc = _grid_score(onset_times, strength_at, iv, ph)
+            if sc > best_sc:
+                best_ph, best_sc = ph, sc
+        return best_ph, best_sc
+
+    # The winner is the grid that explains the most measured onset strength -- "more onsets fall
+    # on it", the standard octave rule. An alternative must explain appreciably more (a fifth
+    # again) to displace the autocorrelation's own answer: a half-tempo grid catches a subset of
+    # the same onsets and a double-tempo grid catches the same set plus empty points, so a bare
+    # ">" would flip the answer on noise.
+    base_phase, base_score = best_phase(interval)
+    interval, phase = interval, base_phase
+    for alt in candidates[1:]:
+        alt_phase, alt_score = best_phase(alt)
+        if alt_score > base_score * BEAT_OCTAVE_MARGIN:
+            interval, phase, base_score = alt, alt_phase, alt_score
+
+    beats = []
+    t = phase
+    while t <= total_s + 1e-9:
+        beats.append(round(t, 4))
+        t += interval
+    support_tol = interval / BEAT_SUPPORT_DIVISOR
+    supported_beats = [b for b in beats
+                       if any(abs(b - o) <= support_tol for o in onset_times)]
+    supported = len(supported_beats)
+    align_tol = interval / BEAT_ALIGN_DIVISOR
+    aligned = sum(1 for o in onset_times
+                  if min((o - phase) % interval, interval - (o - phase) % interval) <= align_tol)
+
+    # How many spreads the best lag stands above the rest of them, mapped onto [0, 1]: a click
+    # track measures z ~= 6, a jittery human performance ~= 5, pseudo-random levels ~= 2.4, so
+    # the band [BEAT_Z_FLOOR, BEAT_Z_FLOOR + BEAT_Z_SPAN] = [2, 6] is where the answer changes.
+    z = ((peak - mean_acc) / sd_acc) if sd_acc > 0 else 0.0
+    periodicity = max(0.0, min(1.0, (z - BEAT_Z_FLOOR) / BEAT_Z_SPAN))
+    alignment = aligned / len(onset_times) if onset_times else 0.0
+    confidence = round(0.5 * periodicity + 0.5 * alignment, 3)
+
+    out.update({
+        "beats": beats, "supported_beats": supported_beats,
+        "interval": round(interval, 6), "tempo_bpm": round(60.0 / interval, 2),
+        "phase": round(phase, 4), "confidence": confidence, "supported": supported,
+        "unsupported": len(beats) - supported,
+        "usable": confidence >= float(min_confidence),
+    })
+    return out
+
+
+def snap_points(points: "Sequence[float]", beats: "Sequence[float]",
+                tolerance: float) -> "List[Dict[str, Any]]":
+    """Move each given point to the nearest beat within `tolerance` seconds.
+
+    Pure. Returns [{"from": t, "to": t2, "delta": d, "snapped": bool, "beat_index": i|None}].
+    A point with no beat inside `tolerance` is returned unchanged with snapped=False.
+
+    NEVER invents a point: len(out) == len(points), always, and every `to` is either a value that
+    was in `beats` or the caller's own `from`. This is the whole no-fabrication rule for beat
+    snapping -- a cut point may move to a measured grid point, and may not appear from one.
+    """
+    grid = sorted(float(b) for b in (beats or []))
+    out: "List[Dict[str, Any]]" = []
+    for p in points:
+        p = float(p)
+        best_i, best_d = None, None
+        for i, b in enumerate(grid):
+            d = abs(b - p)
+            if best_d is None or d < best_d:
+                best_i, best_d = i, d
+        if best_i is not None and best_d is not None and best_d <= float(tolerance):
+            out.append({"from": p, "to": grid[best_i], "delta": round(grid[best_i] - p, 6),
+                        "snapped": True, "beat_index": best_i})
+        else:
+            out.append({"from": p, "to": p, "delta": 0.0, "snapped": False, "beat_index": None})
+    return out
+
+
+# ------------------------------------------------------------- filler words (1.17)
+#
+# A filler word is removed only when a speech engine measured a start/end pair for it. There is no
+# heuristic fallback -- no "cut the 0.3 s blips that look like an 'um'", no language guess from the
+# filename. Without timings there is nothing to cut, and the tool says so.
+#
+# What is NOT in these lists is the substance of the decision. "like", "tipo" and "cioè" are
+# discourse markers, not disfluencies: they are grammatical words in most sentences, and removing
+# them cuts meaning rather than noise. That is a judgement about content, which this skill does not
+# make. They are reachable with --filler-extra, and documented as what they are.
+FILLER_WORDS = {
+    "en": frozenset({"um", "uh", "erm", "hmm", "mm", "mhm", "er", "ah"}),
+    # なんか is the most common Japanese filler AND a pronoun/adverb spelled identically. It is in the
+    # default list because leaving it out makes --filler useless for Japanese, and every run that
+    # removes one warns that it is often a content word (--filler-keep なんか takes it out).
+    "ja": frozenset({"えー", "えーと", "えっと", "あの", "あのー", "その", "そのー", "まあ", "なんか"}),
+    "es": frozenset({"eh", "este", "esto", "mmm"}),
+    "de": frozenset({"äh", "ähm", "hm"}),
+    "fr": frozenset({"euh", "hein"}),
+    "pt": frozenset({"é", "hum"}),
+    "it": frozenset({"ehm"}),
+}
+
+# Words in a default list that are also ordinary vocabulary: every run that removes one says so.
+FILLER_AMBIGUOUS = {
+    "ja": frozenset({"なんか", "あの", "その", "まあ"}),
+    "es": frozenset({"este", "esto"}),
+    "pt": frozenset({"é"}),
+}
+
+# Discourse markers people ask for by name. Not defaults; named here so --help and the docs can
+# say what adding one costs.
+FILLER_DISCOURSE_MARKERS = {
+    "en": ("like", "you know"),
+    "pt": ("tipo",),
+    "it": ("cioè",),
+}
+
+FILLER_MAX_WORD = 1.2   # a longer "uhhh" is a held vowel someone meant
+FILLER_MIN_GAP = 0.05   # spans closer than this become one span
+FILLER_PAD = 0.02       # trimmed either side of the word
+
+
+def normalise_filler_token(word: str) -> str:
+    """A spoken token stripped to what a word list can be compared against: case-folded, with
+    surrounding punctuation and whitespace removed. Never a substring match -- "umbrella" must
+    survive a list containing "um"."""
+    import unicodedata as _ud
+    text = str(word or "").strip()
+    text = "".join(ch for ch in text
+                   if not _ud.category(ch).startswith("P") or ch in "-'’")
+    return text.strip("-'’").casefold()
+
+
+def filler_spans(words, wordlist, *, pad: float = FILLER_PAD, min_gap: float = FILLER_MIN_GAP,
+                 max_word: float = FILLER_MAX_WORD) -> "List[Dict[str, Any]]":
+    """Time spans to remove, from measured word timings. Pure: no subprocess, no I/O.
+
+    `words` is [{"word", "start", "end"}] as whisper emits. A word is removed only when its
+    normalised form is in `wordlist` AND it carries a real start < end pair AND its length is
+    <= max_word. Adjacent spans closer than min_gap merge. Returns [{"start", "end", "word"}]
+    sorted and non-overlapping.
+    """
+    listed = {normalise_filler_token(w) for w in (wordlist or set())}
+    listed.discard("")
+    hits = []
+    for entry in words or []:
+        if not isinstance(entry, dict):
+            continue
+        token = normalise_filler_token(entry.get("word") or entry.get("text") or "")
+        if not token or token not in listed:
+            continue
+        try:
+            start, end = float(entry["start"]), float(entry["end"])
+        except (KeyError, TypeError, ValueError):
+            continue     # no measured timing: nothing to cut
+        if not (end > start) or (end - start) > max_word:
+            continue
+        hits.append({"start": max(0.0, start - pad), "end": end + pad, "word": token})
+    hits.sort(key=lambda h: (h["start"], h["end"]))
+    merged: "List[Dict[str, Any]]" = []
+    for h in hits:
+        if merged and h["start"] - merged[-1]["end"] <= min_gap:
+            merged[-1]["end"] = max(merged[-1]["end"], h["end"])
+            merged[-1]["word"] = merged[-1]["word"] + " " + h["word"]
+        else:
+            merged.append(dict(h))
+    for m in merged:
+        m["start"] = round(m["start"], 4)
+        m["end"] = round(m["end"], 4)
+    return merged

package/scripts/_common/text.py

@@ -440,7 +440,14 @@ ADVANCE_EM = {"ja": 1.0, "zh": 1.0, "ko": 1.0, "th": 1.0, "hi": 0.7, "ar": 0.6,
 
 
 # Scripts written without spaces: a line breaks between any two characters.
-NO_SPACE_SCRIPTS = ("ja", "zh", "ko", "th")
+# Scripts a line may break inside a run of, one character at a time. Thai is deliberately NOT
+# here since 1.16.1: it writes no space inside a phrase, and without a dictionary the wrapper
+# cannot see where one word ends -- every character-level break it took in eval 17 landed inside
+# a word. A Thai run is therefore one atom, broken only at the spaces (or the manual `|`) the
+# writer put there; an over-long run stays long on its own line, the rule long Latin words
+# already follow.
+NO_SPACE_SCRIPTS = ("ja", "zh", "ko")
+NO_BOUNDARY_SCRIPTS = ("th",)   # per-character breaking would chop words: keep the run whole
 
 
 # Per-character Latin advances in em, read off DejaVu Sans (the default caption family, and close
@@ -1085,7 +1092,10 @@ def _atoms(line: str) -> "List[Tuple[str, bool]]":
             if word:
                 out.append((word, spaced))
                 word = ""
-            if out and (attach_next or _is_mark(ch)):
+            if out and not pending and _is_katakana_run(ch) and _is_katakana_run(out[-1][0][-1]):
+                # a katakana word (タイミング, コンピューター) is one atom: eval 17 saw タイ|ミング
+                out[-1] = (out[-1][0] + ch, out[-1][1])
+            elif out and (attach_next or _is_mark(ch)):
                 # never break between a base and the mark (or the leading vowel) that belongs to
                 # it: the line would start with an orphaned tone mark or vowel sign
                 out[-1] = (out[-1][0] + ch, out[-1][1])
@@ -1153,6 +1163,12 @@ def _is_kana(ch: str) -> bool:
     return 0x3040 <= ord(ch) <= 0x30FF
 
 
+def _is_katakana_run(ch: str) -> bool:
+    """Katakana proper plus the prolonged-sound mark: the characters one loan word is made of."""
+    cp = ord(ch)
+    return (0x30A1 <= cp <= 0x30FA) or cp == 0x30FC or (0x31F0 <= cp <= 0x31FF) or (0xFF66 <= cp <= 0xFF9F)
+
+
 def _is_hiragana(ch: str) -> bool:
     return 0x3040 <= ord(ch) <= 0x309F
 
@@ -1513,3 +1529,127 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
     if not greedy:
         greedy = [text]
     return (wrapped or [text], greedy, measured or [text])
+
+
+# --- caption size that fits the cue (1.17) -------------------------------------------------
+# The legibility floor: 4.5 % of the frame height, ass_units(0.045) = 13 against the 288-line
+# ASS script grid. One floor for every destination -- 87 px of type on a 1920-tall frame, above
+# the ~3.5 % where mobile legibility bottoms out and where the platforms' own caption UIs sit.
+# Nothing per-platform is measured, so nothing per-platform is claimed. (The eval-17 cues happen
+# to land exactly on it: 13 is the smallest size at which every one of them fits two lines.)
+MIN_CAPTION_FRACTION = 0.045
+ASS_SCRIPT_HEIGHT = 288  # caption.py's --size/--margin reference grid; mirrors _platforms
+
+
+def line_em_for_size(size: float, play_w: "Optional[int]", play_h: "Optional[int]", *,
+                     safe_fraction: float = SAFE_WIDTH_FRACTION,
+                     script_height: int = ASS_SCRIPT_HEIGHT) -> "Optional[float]":
+    """How many em fit on one caption line at `size`, or None without geometry.
+
+    `size` is in ASS points against a `script_height`-line script (what libass's force_style
+    uses), so the rendered pixel size is size * play_h / script_height. This is the one width
+    formula: caption.py::max_line_em and fit_size() both call it.
+    """
+    if not play_w or not play_h or not size:
+        return None
+    size_px = size * play_h / float(script_height)
+    if size_px <= 0:
+        return None
+    return (play_w * safe_fraction) / size_px
+
+
+def fit_size(cues, *, size: int, min_size: "Optional[int]" = None, max_lines: int = 2,
+             play_w: "Optional[int]" = None, play_h: "Optional[int]" = None,
+             safe_fraction: float = SAFE_WIDTH_FRACTION, mode: str = "phrase",
+             lang: "Optional[str]" = None, script_height: int = ASS_SCRIPT_HEIGHT,
+             step: int = 1, scope: str = "file") -> "Dict[str, Any]":
+    """The largest size in [min_size, size] at which every cue wraps to <= max_lines lines.
+
+    Pure: strings and integers in, a dict out. No ffmpeg, no ffprobe, no I/O -- the caption size
+    is a text-measurement decision, and measuring it must not need a subprocess.
+
+    `cues` is an iterable of cue texts (or of (start, end, text) tuples, as caption.py holds
+    them before layout). Returns
+    {"size", "floor", "requested", "scope", "shrunk", "fits", "per_cue", "max_em", "steps"}.
+
+    The search is a linear walk downwards, not a bisection, and deliberately so:
+    len(wrap_text(t, max_em)) is NOT guaranteed monotone in max_em under the phrase rules -- a
+    rebalance that is discarded at one width can be applied at the next -- and a non-monotone
+    predicate breaks bisection. 24 -> 13 is at most twelve iterations of pure string work.
+
+    `scope="cue"` returns one size per cue index in `per_cue`, with `size` the minimum of them;
+    the caller writes a per-cue {\\fsN} override. The default is `scope="file"`: a caption track
+    whose type size changes from cue to cue reads as a mistake, and one measured line width per
+    file is what makes the wrap behaviour reproducible.
+    """
+    # `texts` stays parallel to `cues`: a blank cue becomes None rather than being dropped, so
+    # per_cue[i] always refers to the caller's cue i. caption.py indexes layout by these keys.
+    texts: "List[Optional[str]]" = []
+    for cue in cues or []:
+        if isinstance(cue, (tuple, list)):
+            raw = cue[2] if len(cue) > 2 else cue[-1]
+        else:
+            raw = cue
+        texts.append(raw if raw and str(raw).strip() else None)
+    measurable = [t for t in texts if t is not None]
+    requested = int(size)
+    floor = int(min_size) if min_size is not None else ass_units_local(MIN_CAPTION_FRACTION,
+                                                                      script_height)
+    floor = max(1, min(floor, requested))
+    step = max(1, int(step))
+    result: "Dict[str, Any]" = {"size": requested, "floor": floor, "requested": requested,
+                                "scope": scope, "shrunk": 0, "fits": True, "per_cue": {},
+                                "max_em": None, "steps": 0}
+    em_at = lambda sz: line_em_for_size(sz, play_w, play_h, safe_fraction=safe_fraction,
+                                        script_height=script_height)
+    base_em = em_at(requested)
+    result["max_em"] = base_em
+    if not measurable or base_em is None or max_lines < 1:
+        # No geometry means no measurable width: leave the size exactly as asked.
+        return result
+
+    def lines_at(text: str, sz: int) -> int:
+        em = em_at(sz)
+        if em is None:
+            return 1
+        return len(wrap_text(text, em, mode=mode, lang=lang))
+
+    over_at_requested = [t for t in measurable if lines_at(t, requested) > max_lines]
+    result["shrunk"] = len(over_at_requested)
+
+    def best_for(subset) -> "Tuple[int, bool]":
+        """(largest size in [floor, requested] fitting every text in `subset`, did it fit)."""
+        sz = requested
+        while sz >= floor:
+            result["steps"] += 1
+            if all(lines_at(t, sz) <= max_lines for t in subset):
+                return sz, True
+            sz -= step
+        return floor, all(lines_at(t, floor) <= max_lines for t in subset)
+
+    if scope == "cue":
+        per_cue = {}
+        fits_all = True
+        for i, t in enumerate(texts):
+            if t is None:
+                per_cue[i] = requested    # a blank cue draws nothing; it constrains nothing
+                continue
+            sz, ok = best_for([t])
+            per_cue[i] = sz
+            fits_all = fits_all and ok
+        result["per_cue"] = per_cue
+        sized = [v for i, v in per_cue.items() if texts[i] is not None]
+        result["size"] = min(sized) if sized else requested
+        result["fits"] = fits_all
+    else:
+        sz, ok = best_for(measurable)
+        result["size"] = sz
+        result["fits"] = ok
+    result["max_em"] = em_at(result["size"])
+    return result
+
+
+def ass_units_local(fraction: float, script_height: int = ASS_SCRIPT_HEIGHT) -> int:
+    """`fraction` of the frame height in ASS units. Mirrors _platforms.ass_units, kept here so
+    _common.text stays importable without the scripts/ top level on sys.path."""
+    return int(round(fraction * script_height))

package/scripts/_contract.py

@@ -170,7 +170,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                      required=FF + ["filter:loudnorm"], optional=[{"capability": AAC, "when": "output extension isn't .mp3/.opus/.ogg/.flac (audio_codec_for()'s default)"}] + AUDIO_OUT,
                      video_required=False, audio_only=True, visual=False, verify=["probe", "check"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "silence": dict(role="analysis_and_execution", inputs=["video or audio asset"], outputs=["silence list JSON (--list)", "artifact with silences removed", "EDL text (--edl)"],
-                    required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"}] + AUDIO_OUT,
+                    required=FF + ["filter:silencedetect"], optional=[{"capability": X264, "when": "removing silences from a video"}, HDR_X265, {"capability": AAC, "when": "removing silences from a video"},
+                                                                    {"capability": "external:whisper", "when": "--filler --transcribe"}] + AUDIO_OUT,
                     video_required=False, audio_only=True, visual=False, verify=["probe"], produces_artifact=True, idempotency="content_equivalent", deterministic=True),
     "join": dict(role="execution", inputs=["two or more video assets, or two or more audio-only assets"], outputs=["concatenated video artifact", "concatenated audio artifact (audio-only inputs, audio output extension)"],
                  required=FF + ["filter:xfade", "filter:acrossfade"],
@@ -197,7 +198,8 @@ TOOL_META: Dict[str, Dict[str, Any]] = {
                   required=["ffprobe"], optional=[{"capability": "ffmpeg", "when": "loudness rows (default)"}, {"capability": "filter:loudnorm", "when": "loudness rows (default)"}],
                   video_required=False, audio_only=True, visual=False, verify=[], produces_artifact=False, idempotency="bit_exact", deterministic=True),
     "scenes": dict(role="analysis", inputs=["video asset"], outputs=["scene / audio-peak / highlight JSON on stdout", "EDL text (--edl)", "per-scene contact sheet PNG (--sheet)"],
-                   required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"}],
+                   required=FF + ["filter:scdet"], optional=[{"capability": "filter:drawtext", "when": "--sheet"}, {"capability": "filter:tile", "when": "--sheet"},
+                                                            {"capability": "ffmpeg", "when": "--beats (one audio decode for the onset pass)"}],
                    video_required=True, audio_only=False, visual=False, verify=[], produces_artifact=True, idempotency="bit_exact", deterministic=True),
     "look": dict(role="verification", inputs=["video artifact"], outputs=["PNG contact sheet / frames / side-by-side"],
                  required=FF + ["filter:tile"], optional=[{"capability": "filter:drawtext", "when": "timecode stamps (default; --no-timecode to skip)"},