ffmpeg-skill 1.18.3 → 1.18.4

package/README.md

@@ -416,7 +416,8 @@ type on every OS.
 | **F1 0.97** | `scenes.py`, 53 hard cuts between single takes, precision 0.95, recall 1.00 at the default threshold |
 | **exact to the sample** | `cut.py --accurate` on WAV, FLAC (44.1 kHz) and AAC → WAV; WAV stream copy within 2 ms; AAC output +21 ms of encoder priming, reported as `codec_frame` (0.9.1) |
 | **72 / 72** | agent runs of 24 prompts (12 English edits, 8 Japanese, 4 that must be declined), three repeats, graded by an independent model: routing, honest refusals and user's language 72/72, report format 71/72, visual check whenever the picture changed 24/24 (0.8.4) |
-| **8 / 12 routed** | eval 21 at 1.18.0 (2026-09-17, one prompt per new analysis/multicam flag plus a `cs1`/`cs3` recheck, Sonnet agent): every result was correct where the agent found the right script — both sync offsets, the shot label, the multicam switch point and its render-project mapping, both 1.17.2/1.17.3 rechecks — but 4 of 12 prompts hit a script the agent could not find, because SKILL.md named none of the five new flags (confirmed by grep). Three refused honestly rather than fabricate a number; one reached a correct answer without the intended flag, by luck of one fixture's silence durations. 1.18.1 (2026-09-17) is the SKILL.md fix, not yet re-evaluated. Written up in `evals/results/iteration-21.json` |
+| **7 / 8 routed** | eval 22 at 1.18.3 (2026-09-17, eight new symptom-only prompts for the five 1.18.0 flags, naming no flag, plus three repeats each of `cs1`/`cs3`, Sonnet agent): after 1.18.1's SKILL.md routing rows and 1.18.2's matching README rows, `scenes.py --shots`, `cropdetect.py --motion-centre`, `silence.py --speech-aware`, `sync.py`'s N-source form and `multicam.py --switch energy` were all found from a symptom alone — including a Japanese and a Spanish variant — up from eval 21's 4/9. The eighth prompt (`--filler` composed with `--speech-aware`) is an honest partial: the fixture has no real speech to transcribe, confirmed by installing `faster-whisper` mid-eval and re-testing by hand. `cs3` no longer rewrites the user's captions in any of 3 runs — the 1.17.3 fix holds through 1.18.1-1.18.3. Written up in `evals/results/iteration-22.json` |
+| **8 / 12 routed** | eval 21 at 1.18.0 (2026-09-17, one prompt per new analysis/multicam flag plus a `cs1`/`cs3` recheck, Sonnet agent): every result was correct where the agent found the right script — both sync offsets, the shot label, the multicam switch point and its render-project mapping, both 1.17.2/1.17.3 rechecks — but 4 of 12 prompts hit a script the agent could not find, because SKILL.md named none of the five new flags (confirmed by grep). Three refused honestly rather than fabricate a number; one reached a correct answer without the intended flag, by luck of one fixture's silence durations. 1.18.1 (2026-09-17) is the SKILL.md fix, since evaluated by eval 22. Written up in `evals/results/iteration-21.json` |
 | **20 / 20** | 1.17.2 run (2026-09-14, the eight caption prompts of eval 19, six of them three times, Sonnet agent, regex grader + an Opus grader that opened every contact sheet and counted the lines per cue): routing 19/19 act runs, honest 18/20 with 0 false successes and 0 raw ffmpeg calls, report format 20/20, user's language 20/20, trigger set 49/50 (one judge flip on a file-less prompt), Opus quality mean 4.25 (3.65 at eval 19). The picture is fixed: 0/20 runs stack one word per line against 12/12 template runs at eval 19 on the same cues; the Style row at TikTok geometry is now `…,54,151,420,1`, the fitter's `size_used` (15 on TikTok, 16 on Shorts, the 13 floor for the Spanish cues) is what the frame shows, and report and sheet agree in 18/20 runs. What is left is not the typesetter: `cs3` rewrote the user's captions for the fourth iteration running, one `cs1` run raised `max_lines` to 4 to avoid a shrink and drew four-line stacks, and `cs2`'s 32-letter Spanish word still leaves the frame at the size floor (disclosed 3/3). Written up in `evals/results/iteration-20.json` |
 | **26 / 26** | 1.17.1 run (2026-09-14, targeted re-run of the 18 prompts eval 18's follow-up named, plus three repeats each of the four caption-size prompts, Sonnet agent, regex grader + a full Opus grader over all 26 runs, every PNG opened and every written output re-probed): routing 23/26, honest refusals and failures 24/26 with 0 false successes and 0 raw ffmpeg calls, report format 26/26 with the third label gone, user's language 26/26, trigger set 50/50, Opus quality mean 3.65. 1.17.1's fix holds — `--fit-size` now fires on the `render.py --template` path in 12/12 caption runs (24 → 16, `dl4` to the 13-unit floor, `split` 0, `text_unchanged` true, identical across repeats), the beat, filler and `--jobs` prompts route on the first try, and `bt2` quotes its measured 0.184 confidence instead of denying the capability exists. The honest part: the picture is unchanged. `caption.py`'s `write_ass` writes the platform's *vertical* safe margin into `MarginL`, `MarginR` and `MarginV` alike (tiktok 63 ASS units → 420 px), so at `PlayResX` 1080 the text column is 240 px and libass wraps every word — the fitter budgets `play_w × 0.9`, which is why `split: 0` is true of the ASS text and false of the frame. It is the `--animate`/`--karaoke` path only, present since 1.14, and it explains eval 17's and eval 18's "one word per line" too; 1.17.2 is the patch and the finding is written up in `evals/results/iteration-19.json` |
 | **100 / 100** | 1.17.0 run (2026-09-14, one pass per prompt, Sonnet agent, regex grader + focused Opus grader on 28 runs, every written output re-probed, `check.py` re-run on every delivery output) on the set grown to 100 prompts (caption size fitting, beat-synced cuts, filler removal, batch `--jobs`, render `--cache`): routing 95% over the 64 act prompts, honest refusals and failures 22/25 with 0 false successes and 0 raw ffmpeg calls, report format 98/100 (two runs label an honest partial result with a third label), user's language 100/100 across seventeen languages, visual check 24/24, real execution 6/6 with honest failure 5/5, trigger set 50/50 including all five new 1.17 prompts, Opus quality mean 3.71. The honest part: `--fit-size` is unreachable on the template path (`render.py` forwards the platform table's caption size as an explicit `--size`, so the fitter declines to shrink a size it thinks the user chose, and the project schema rejects `fit_size` outright — only the one run that called `caption.py` by hand got 24 → 16, `split` 0), and SKILL.md names none of the 1.17 features, so beats, filler and `--cache` were each used in one run at most — 1.17.1 is the patch and the finding is written up in `evals/results/iteration-18.json` |

package/docs/contract.md

@@ -21,7 +21,7 @@ The contract is derived from the code that runs, not maintained beside it:
 | Field | Meaning | Changes when |
 |---|---|---|
 | `contract_version` | shape of this document (`1.0`) | a key is renamed, removed or changes meaning |
-| `skill.version` | the npm / package.json version (`1.18.3`) | any release |
+| `skill.version` | the npm / package.json version (`1.18.4`) | any release |
 
 A release that adds a tool or a flag keeps `contract_version`; a breaking change to the
 ToolSpec shape bumps it. Consumers pin on `contract_version` and read `skill.version`
@@ -88,19 +88,19 @@ spelling keeps working until 2.0.
 
 | What 2.0 removes | Since | Replacement | To be ready today |
 |---|---|---|---|
-| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.18.3 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
-| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.18.3 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
-| `json` and `progress` in the MCP `inputSchema` | 1.18.3 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
-| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.18.3 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
-| Overwriting an existing output with only a warning | 1.18.3 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
+| The per-tool v1 success keys next to `result_v2` (`output`, `probe`, `commands`, `verified`, `verification` and each tool's own keys at the top level) | 1.18.4 | `result_v2`, promoted to the top level in 2.0 | Run with `FFMPEG_SKILL_RESULT_V2=1` and read `result_v2` (`metrics`, `notes`, `details`) instead of the top-level keys |
+| `--crf` as an alias of `--quality` on every re-encoding tool that takes `--quality` (`export.py` keeps `--crf`: its preset chooses the encoder) | 1.18.4 | `--quality N` (the same CRF scale, codec-neutral) | Pass `--quality`; `--crf` warns on stderr and is marked in `--help` |
+| `json` and `progress` in the MCP `inputSchema` | 1.18.4 | nothing: the transport sets them itself | Stop sending them from an MCP client; run the server with `FFMPEG_SKILL_MCP_LEAN=1` to see the 2.0 schema |
+| `hdr` meaning "BT.2020 primaries *or* a PQ/HLG transfer" in `probe` | 1.18.4 | `hdr_signal` (true only for PQ / HLG / Dolby Vision); in 2.0 `hdr` takes that meaning | Key on `hdr_signal` for "is this a real HDR signal" and on `hdr_format` for the `BT.2020 SDR` case |
+| Overwriting an existing output with only a warning | 1.18.4 | `--overwrite` as explicit consent (refused without it from 2.0) | Set `FFMPEG_SKILL_NO_OVERWRITE=1` (the recommended agent setting) and pass `--overwrite` where a replacement is intended |
 
 ## Skill
 
 ```json
 {
   "contract_version": "1.0",
-  "deprecated": [{"what": "...", "since": "1.18.3", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
-  "skill": {"id": "ffmpeg-skill", "version": "1.18.3", "execution_mode": "local", "kind": "execution",
+  "deprecated": [{"what": "...", "since": "1.18.4", "replacement": "...", "removed_in": "2.0.0", "where": "cli | json | mcp | behaviour"}],
+  "skill": {"id": "ffmpeg-skill", "version": "1.18.4", "execution_mode": "local", "kind": "execution",
             "entrypoints": {"cli": "...", "mcp": "...", "contract": "...", "doctor": "..."},
             "not_provided": ["AI reasoning", "decisions", "production plans", "project IR", "approvals", "network access", "transcription engine"]},
   "requirements": {"python": ">=3.9 (standard library only)", "ffmpeg": ">=5.0", "ffprobe": ">=5.0"},
@@ -128,7 +128,7 @@ One entry per tool under `tools`, sorted by id. Tool ids are stable:
 | `output_schema` | what `--json` prints on stdout |
 | `supports_dry_run`, `dry_run` | whether `--dry-run` plans without running ffmpeg or writing files |
 | `supports_json` | whether `--json` exists |
-| `supports_json_brief` | whether `--json-brief` exists (1.18.3): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way |
+| `supports_json_brief` | whether `--json-brief` exists (1.18.4): the same success document with `probe` replaced by a compact `summary` (`duration_s`, `width`, `height`, `fps`, `vcodec`, `acodec`, `channels`, and `lufs` when the tool measured one), `commands` replaced by the number of commands run, and the per-step `verification` list dropped (its verdict stays in `verified`). Tool-specific keys are unchanged, `--json`'s own output is unchanged, and a failure prints the same failure document either way |
 | `mutates_input` | always `false`: no tool overwrites its input |
 | `produces_artifact` | writes a file (media, PNG, HTML, EDL) |
 | `verification` | `{required, tools}`: which tools to run on the output afterwards |
@@ -450,7 +450,7 @@ Per-tool keys added in 1.17, all additive:
 | `jobs`, `jobs_requested`, `wall_seconds`, `item_seconds_total`, `timed_out` | `batch.py` | the parallelism actually applied and the number asked for, the batch's wall clock, the sum of the per-item times (so the speed-up can be quoted), and whether the shared timeout budget ran out. A timed-out item carries `"skipped": "timeout"` in its result row |
 | `cache` | `render.py --cache` | `{dir, ffmpeg, hits, misses, saved_seconds, entries}`, plus `would_hit` under `--dry-run`. The ffmpeg build banner, the skill version, the contract version, the forwarded flags (`--fast`, `--codec`, …) and the output's extension are all part of every key, so a cache is never reused across any of them — a `--fast` draft is never served to a run that did not ask for one |
 
-Per-tool keys added in 1.18.3, all additive:
+Per-tool keys added in 1.18.4, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
@@ -458,7 +458,7 @@ Per-tool keys added in 1.18.3, all additive:
 | `text_unchanged` | `caption.py` | a sibling inside the `caption` block, **burn mode only** (`--mode mux` never touches the text and omits the key): `true` when the drawn text equals the cues that were handed in — nothing transcribed, no cue dropped, no cue **split** across two consecutive cues and no glyph stripped (`--emoji none`). Wrapping, line breaks and timing do not count: the words are the same. This tool never rewrites, shortens or translates a cue, so the key is a statement of what happened, not a judgement of the text |
 
 
-Per-tool keys added in 1.18.3, all additive:
+Per-tool keys added in 1.18.4, all additive:
 
 | key | tool | what it holds |
 |---|---|---|
@@ -588,7 +588,7 @@ most often across the corpus in `evals/agent_prompts*.json`. Every tool -- inclu
 -- is still callable by name through `tools/call` regardless of what `tools/list` advertised; the
 contract (`ffmpeg-skill contract --json`) still describes all 42 unconditionally. Set
 `FFMPEG_SKILL_MCP_FULL=1` (anything but "" or `0`) in the server's environment to make `tools/list`
-return all 42, as every version before 1.18.3 did.
+return all 42, as every version before 1.18.4 did.
 
 ## Consuming the contract from an agent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ffmpeg-skill",
-  "version": "1.18.3",
+  "version": "1.18.4",
   "description": "Agent Skill that gives coding agents (Claude Code, Cursor, Codex) a local video editor: 42 FFmpeg tools with a machine-readable contract, contract-derived MCP server, FFmpeg capability detection, probe-first / verify-last workflow. Cut, join, silence removal, fit, captions and karaoke, overlays, motion graphics, HDR to SDR, LUTs, audio clean-up and typed dynamics, sync with drift correction, multicam, loudness, delivery checks, project rendering, batch. No API keys, no cloud, no dependencies.",
   "keywords": [
     "ffmpeg",

package/scripts/_common/__init__.py

@@ -107,7 +107,7 @@ from _common.text import (
     JA_NO_LINE_END, JA_NO_LINE_START, JA_PARTICLE_WORDS, JA_PARTICLES, JA_SENTENCE_END, _join, ORPHAN_MIN_EM,
     PENALTY_FORBIDDEN, PENALTY_FUNCTION_WORD, PENALTY_FUNCTION_WORD_START, PENALTY_IDEOGRAPHS,
     PENALTY_NEUTRAL, PENALTY_OKURIGANA,
-    PENALTY_PARTICLE, PENALTY_SENTENCE_END, _rebalance, _rebalance_phrase, SAFE_WIDTH_FRACTION, _split_hyphens,
+    PENALTY_PARTICLE, PENALTY_SENTENCE_END, _rebalance, _rebalance_phrase, SAFE_WIDTH_FRACTION, _split_hyphens, _slice_atom,
     _particle_ends, _particle_starts, wrap_text, wrap_variants, WRAP_MODES,
     fit_size, line_em_for_size, MIN_CAPTION_FRACTION, ass_units_local,
     script_font_for_text, script_font_status, _script_font_uncached, _SCRIPT_RANGES, SCRIPTS, _SHAPING_BUILD_CACHE,
@@ -223,7 +223,7 @@ __all__ = [
     "PENALTY_FUNCTION_WORD_START",
     "JA_SENTENCE_END", "_join", "ORPHAN_MIN_EM", "PENALTY_FORBIDDEN", "PENALTY_FUNCTION_WORD",
     "PENALTY_IDEOGRAPHS", "PENALTY_NEUTRAL", "PENALTY_OKURIGANA", "PENALTY_PARTICLE", "PENALTY_SENTENCE_END",
-    "_rebalance", "_rebalance_phrase", "SAFE_WIDTH_FRACTION", "_split_hyphens", "_particle_ends",
+    "_rebalance", "_rebalance_phrase", "SAFE_WIDTH_FRACTION", "_split_hyphens", "_slice_atom", "_particle_ends",
     "_particle_starts", "wrap_text", "wrap_variants", "WRAP_MODES",
     "fit_size", "line_em_for_size", "MIN_CAPTION_FRACTION", "ass_units_local"
 ]

package/scripts/_common/text.py

@@ -38,7 +38,7 @@ from _common.wrap import (
     text_width_em, SAFE_WIDTH_FRACTION, ORPHAN_MIN_EM, WRAP_MODES, JA_PARTICLES, JA_PARTICLE_WORDS,
     JA_SENTENCE_END, JA_NO_LINE_START, JA_NO_LINE_END, FUNCTION_WORDS, _FUNCTION_WORDS_ANY, PENALTY_FORBIDDEN,
     PENALTY_OKURIGANA, PENALTY_FUNCTION_WORD, PENALTY_IDEOGRAPHS, PENALTY_NEUTRAL, PENALTY_FUNCTION_WORD_START,
-    PENALTY_PARTICLE, PENALTY_SENTENCE_END, _HYPHENS, _atoms, _split_hyphens, _join, _break_spaced, _is_kana,
+    PENALTY_PARTICLE, PENALTY_SENTENCE_END, _HYPHENS, _atoms, _split_hyphens, _slice_atom, _join, _break_spaced, _is_kana,
     _is_katakana_run, _is_hiragana, _is_ideograph, _is_weak_line, _function_words, _bare_word, _particle_starts,
     _particle_ends, break_penalty, _cut_penalty, best_break, _fix_orphans, _fix_weak_lines, _rebalance,
     _rebalance_phrase, _greedy_chunks, _balance, wrap_text, wrap_variants, MIN_CAPTION_FRACTION,

package/scripts/_common/wrap.py

@@ -265,6 +265,37 @@ def _split_hyphens(atoms: "List[Tuple[str, bool]]") -> "List[Tuple[str, bool]]":
     return out
 
 
+def _slice_atom(atom: str, max_em: float) -> "List[str]":
+    """The escape hatch (1.18.4): hard-slice a single atom that is wider than `max_em` all by
+    itself -- a word or run with no break point the wrapper may use, and that STILL does not fit
+    even alone on its own line. Nothing else in this file may ever chop an atom mid-character;
+    this is the one place that does, and only once every other mechanism (wrapping, then
+    caption.py's --min-size shrink) has already failed to make it fit.
+
+    No dictionary, no hyphenation library: an existing hyphen is preferred as the cut (the same
+    break R1 already allows), then whatever is left is cut again at exactly the widest prefix
+    that still measures within `max_em`, one character at a time. The characters themselves are
+    never rewritten -- every piece concatenates back to the original atom exactly."""
+    if text_width_em(atom) <= max_em:
+        return [atom]
+    for i in range(len(atom) - 2, 0, -1):
+        # latest hyphen whose left side still fits -- keeps the left half as large as possible
+        if atom[i] in _HYPHENS and text_width_em(atom[:i + 1]) <= max_em:
+            return [atom[:i + 1]] + _slice_atom(atom[i + 1:], max_em)
+    pieces: "List[str]" = []
+    cur = ""
+    for ch in atom:
+        candidate = cur + ch
+        if cur and text_width_em(candidate) > max_em:
+            pieces.append(cur)
+            cur = ch
+        else:
+            cur = candidate
+    if cur:
+        pieces.append(cur)
+    return pieces or [atom]
+
+
 def _join(left: str, atom: str, spaced: bool) -> str:
     """Put an atom back on a line, restoring the space that stood before it."""
     if not left:
@@ -574,15 +605,38 @@ def _rebalance_phrase(lines: "List[str]", max_em: float, lang: "Optional[str]")
     return out, moved
 
 
-def _greedy_chunks(raw: str, max_em: float) -> "List[str]":
-    """The greedy fill on its own: the line count every mode must keep."""
+def _greedy_chunks(raw: str, max_em: float, *, slice_overlong: bool = False,
+                   sliced: "Optional[List[int]]" = None) -> "List[str]":
+    """The greedy fill on its own: the line count every mode must keep.
+
+    `slice_overlong` (off by default -- only caption.py's final burn-in pass turns it on, never
+    fit_size()'s search) is the escape hatch: an atom that lands alone on a line and is STILL
+    wider than `max_em` -- a fitting atom never reaches this branch, so a Thai phrase or a
+    katakana run that already fits is completely untouched -- is hard-sliced by _slice_atom()
+    instead of kept whole. `sliced`, when given, gets one entry (the number of extra lines that
+    one atom produced) per atom actually sliced, which is how the caller counts
+    `broken_inside_word` without re-deriving it from the output lines."""
     current = ""
     chunk: "List[str]" = []
     for atom, spaced in _atoms(raw):
+        if slice_overlong and not current and text_width_em(atom) > max_em:
+            pieces = _slice_atom(atom, max_em)
+            if sliced is not None and len(pieces) > 1:
+                sliced.append(len(pieces) - 1)
+            chunk.extend(pieces[:-1])
+            current = pieces[-1]
+            continue
         candidate = _join(current, atom, spaced)
         if current and text_width_em(candidate) > max_em:
             chunk.append(current)
-            current = atom
+            if slice_overlong and text_width_em(atom) > max_em:
+                pieces = _slice_atom(atom, max_em)
+                if sliced is not None and len(pieces) > 1:
+                    sliced.append(len(pieces) - 1)
+                chunk.extend(pieces[:-1])
+                current = pieces[-1]
+            else:
+                current = atom
         else:
             current = candidate
     if current:
@@ -608,7 +662,8 @@ def _balance(chunk: "List[str]", max_em: float, mode: str, lang: "Optional[str]"
 
 
 def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "phrase",
-              lang: "Optional[str]" = None) -> "List[str]":
+              lang: "Optional[str]" = None, slice_overlong: bool = False,
+              sliced: "Optional[List[int]]" = None) -> "List[str]":
     """Wrap `text` to lines no wider than `max_em` em, keeping the manual breaks it already has.
 
     An atom wider than the whole line (one very long word) is left alone on its line rather than
@@ -626,11 +681,12 @@ def wrap_text(text: str, max_em: float, *, balance: bool = True, mode: str = "ph
     for raw in text.split("\n"):
         if not raw.strip():
             continue
-        chunk = _greedy_chunks(raw, max_em)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced)
         lines.extend(_balance(chunk, max_em, mode, lang) if balance else chunk)
     return lines or [text]
 def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
-                  lang: "Optional[str]" = None) -> "Tuple[List[str], List[str], List[str]]":
+                  lang: "Optional[str]" = None, slice_overlong: bool = False,
+                  sliced: "Optional[List[int]]" = None) -> "Tuple[List[str], List[str], List[str]]":
     """`(wrapped, greedy, measured)` for one cue from a single greedy fill.
 
     layout_cues needs all three -- `wrapped` is what is burnt in, `greedy` is what `rebalanced`
@@ -645,7 +701,7 @@ def wrap_variants(text: str, max_em: float, *, mode: str = "phrase",
     for raw in text.split("\n"):
         if not raw.strip():
             continue
-        chunk = _greedy_chunks(raw, max_em)
+        chunk = _greedy_chunks(raw, max_em, slice_overlong=slice_overlong, sliced=sliced)
         greedy.extend(chunk)
         wrapped.extend(_balance(list(chunk), max_em, mode, lang))
         measured.extend(chunk if mode == "measured" else _balance(list(chunk), max_em, "measured", None))

package/scripts/caption.py

@@ -53,7 +53,7 @@ from _common import (ASR_INSTALL_HINT, die_no_engine, parse_srt, transcribe, whi
 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)
+                     _split_hyphens, _slice_atom, 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.
@@ -62,7 +62,7 @@ __all__ = ["parse_srt", "write_srt", "transcribe", "whisper_word_timings", "die_
            "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",
+           "_bare_word", "_function_words", "_split_hyphens", "_slice_atom", "FUNCTION_WORDS", "JA_PARTICLES",
            "JA_SENTENCE_END", "_fix_orphans", "_rebalance", "char_script", "NO_SPACE_SCRIPTS",
            "text_width_em"]
 
@@ -319,6 +319,10 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
     """
     stats = {"shifted": 0, "wrapped": 0, "split": 0, "extended": 0, "dropped": 0, "rebalanced": 0,
              "wrap": wrap, "phrase_breaks": 0}
+    # ass_units_local's floor + the escape hatch below mean an atom this loop hands to
+    # wrap_variants(..., slice_overlong=True) can still overflow only if a SINGLE character is
+    # wider than the column -- practically unreachable at any real --min-size. `overlong` stays
+    # in stats for that theoretical remainder; `broken_inside_word` is the count that matters now.
     staged: List[Tuple[float, float, str]] = []
     staged_sizes: List[Optional[int]] = []
     for cue_index, (start, end, text) in enumerate(cues):
@@ -339,12 +343,19 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
             # 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, own_em, mode=wrap, lang=lang)
+            sliced_atoms: List[int] = []
+            lines, greedy, measured = wrap_variants(text, own_em, mode=wrap, lang=lang,
+                                                     slice_overlong=True, sliced=sliced_atoms)
             if lines != [l for l in text.split("\n") if l.strip()]:
                 stats["wrapped"] += 1
+            if sliced_atoms:
+                # the escape hatch fired: a word or run with no break point the wrapper may use
+                # was still wider than the column alone, even at the size in force, so it was
+                # hard-sliced at the column edge (or after its own hyphen) instead of clipping
+                stats["broken_inside_word"] = stats.get("broken_inside_word", 0) + len(sliced_atoms)
             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
+                # the escape hatch above could not make every piece fit -- only possible when a
+                # single character is wider than the column itself
                 stats["overlong"] = stats.get("overlong", 0) + 1
             if lines != greedy:
                 stats["rebalanced"] += 1
@@ -381,13 +392,19 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
 
 def report_layout(stats: dict) -> None:
     """One info line, only when a cue actually changed."""
-    parts = [f"{stats[k]} {k}" for k in ("shifted", "wrapped", "rebalanced", "phrase_breaks", "split", "extended", "dropped", "overlong") if stats.get(k)]
+    parts = [f"{stats[k]} {k}" for k in ("shifted", "wrapped", "rebalanced", "phrase_breaks", "split",
+             "extended", "dropped", "broken_inside_word", "overlong") if stats.get(k)]
     if parts:
         info("cues: " + ", ".join(parts))
+    if stats.get("broken_inside_word"):
+        info(f"{stats['broken_inside_word']} cue line(s) had a word or run with no break point "
+             "(Thai writes none inside a phrase) that was still wider than the column alone -- it "
+             "was sliced at the column edge (after its own hyphen when it has one) instead of "
+             "clipping past the frame; put a space or `|` where the line may break, or use a "
+             "smaller --size, to avoid the slice")
     if stats.get("overlong"):
-        info(f"{stats['overlong']} cue line(s) wider than the safe width: a word or a run with no break "
-             "point (Thai writes none inside a phrase) was kept whole rather than chopped -- put a "
-             "space or `|` where the line may break, or use a smaller --size")
+        info(f"{stats['overlong']} cue line(s) wider than the safe width even after slicing: a "
+             "single character was wider than the column -- use a smaller --size")
 
 
 def margins_x(args, play_w: Optional[int]) -> Tuple[int, int]: