Skip to content

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

fix: captions never break inside a Thai run or a katakana word; over-wide lines are reported (eval 17) (#233)

claude[bot]116be90c4e24
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 98632e7..6b6c702 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,16 @@
## Unreleased
-(nothing yet)
+### Fixed
+
+- **Caption breaking, from eval 17.** A Thai run is no longer broken inside: Thai writes no space
+ inside a phrase and the wrapper has no dictionary, so every character-level break it took landed
+ inside a word (`ข|อง`, `เว|ลา`); the break now goes where the writer put a space or a `|`, and a
+ run with none stays long on its own line, the rule long Latin words already follow. A katakana
+ word is one atom (`タイ|ミング` was split like a run of kanji). `caption.py` reports an `overlong`
+ count in its caption stats and an info line naming the fix (a space or `|` where the line may
+ break, or a smaller `--size`) when a wrapped line is wider than the safe width. `--wrap measured`
+ follows the same atom rules (it is the post-passes that differ, not the pieces).
## 1.16.0
diff --git a/README.md b/README.md
index 760c055..005bde5 100644
--- a/README.md
+++ b/README.md
@@ -361,7 +361,7 @@ The short list for humans. The agent-facing version, with the reasoning, is the
- **Loudness targets.** −14 LUFS / −1 dBTP for YouTube and social platforms (the `loudness.py` default), `-I -16 --tp -1.5` for podcasts, `-I -23` for broadcast. A clip measured at −40 LUFS or below is room tone, not content; raising it raises the noise. Check true peak as well as LUFS: `check.py file --platform podcast` measures both.
- **Frame changes first, text second.** Captions and overlays burned before a crop or resize end up off-frame. Reframe, then caption.
- **Cropping 16:9 to 9:16 discards 70 % of the width.** `fit.py --fit crop` centres by default; pass `--crop-x`/`--crop-y` toward the subject, or pad with `--fit pad --pad-fill blur`. Look at the contact sheet before deciding.
-- **Phrase-aware caption breaking (1.16).** `caption.py`/`graphics.py --wrap phrase` (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; `--wrap measured` restores 1.15's width-only wrap. The text itself is never rewritten or shortened.
+- **Phrase-aware caption breaking (1.16).** `caption.py`/`graphics.py --wrap phrase` (the default) never breaks inside a word or on the wrong side of a hyphen, never leaves a lone digit, kana or punctuation pair on a line, prefers Japanese sentence ends and particles over a mid-word break, and never ends a line on an article or preposition. All four are penalties over break positions that already fit, so no line is widened and the line count never changes; `--wrap measured` restores 1.15's width-only wrap. The text itself is never rewritten or shortened. Since 1.16.1 a Thai run and a katakana word are never broken inside (Thai writes no space inside a phrase and there is no dictionary: the break goes where you put a space or `|`), and a line wider than the safe width is reported as `overlong` with the fix named.
- **Audiogram (1.16).** `waveform.py --image cover.png` (or `render.py --template audiogram`) puts the waveform over a still plate for an episode that has no picture, with `--platform` for the frame, `--title` and burnt-in captions. The image is a local file you give: nothing is fetched and no cover art is ever invented.
- **Emoji in captions and titles (1.15).** `caption.py`/`graphics.py --emoji-assets DIR` composites a PNG per emoji (Twemoji/Noto naming, `1f389.png`) on top of the text, because drawtext cannot load a colour emoji font at all and an installed one does not prove libass will draw it in colour — `doctor --json`'s `fonts.emoji` answers that from a render probe. Without assets the run still succeeds and reports `mode: mono`. Nothing is ever downloaded.
- **Indic and Thai text shaped correctly in titles and lower-thirds (1.15).** `graphics.py` renders Devanagari, Bengali, Tamil, Thai and Lao through libass automatically (`text_renderer: "ass"`), because drawtext never reorders matras or re-clusters marks; Arabic and Hebrew were already correct on a fribidi build. `--text-render drawtext` with such a script is refused, never rendered wrongly.
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 1c16587..312b397 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -34,7 +34,7 @@ sizes (see the 1.16.0 section); 1.16.1 below is the patch. Everything after that
| 1.15.0 | shipped + evaluated | eval 16 at 1.15.0 (`iteration-16.json`) |
| refactor after 1.15.0 | shipped, eval pending | contract + MCP snapshots and every `--help` byte-identical; 323/323 cases |
| 1.16.0 | shipped + evaluated | eval 17 at 1.16.0 (`iteration-17.json`); contract and MCP snapshots additive only; tool count still 42 |
-| 1.16.1 | planned | caption-break patch from eval 17 (katakana runs, no balancing inside Thai/Lao/Khmer/Myanmar runs, a note when a cue is split for width) |
+| 1.16.1 | shipped, eval pending | caption-break patch from eval 17: a Thai run and a katakana word are never broken inside, `caption.py` reports `overlong` lines; eval 18 |
| 1.17.0 → 1.21.0, 2.0.0 | planned | — |
## 1.8.0 — one-call delivery, quieter checks, encoder flags (shipped + evaluated, eval 8)
@@ -294,9 +294,9 @@ came out byte-identical, as did `--help` for all 42 tools.
and `caption.py` splits it into two-line cues exactly as 1.15.1 did (byte-identical ASS on
`cw1`, `dl1`, `dl4`). Thai still breaks inside words in both versions (no dictionary), and
1.16.0's balancing moves that break towards the middle of the run; a katakana word gets split
- (`タイ|ミング`). The `dl3` orphans are gone. Follow-ups: 1.16.1 (katakana runs unbreakable,
- greedy fill inside no-space runs without word boundaries, a note naming the manual `|` break
- when a cue is split for width) and, in 1.17.0, a caption size that fits the cue before the
+ (`タイ|ミング`). The `dl3` orphans are gone. Follow-ups: 1.16.1 (shipped: a Thai run is one atom, broken only at a space
+ or `|`; a katakana word is one atom; `caption.py` counts lines wider than the safe width as
+ `overlong` and names the fix) and, in 1.17.0, a caption size that fits the cue before the
cue is split.
## 1.17.0 — throughput (planned)
diff --git a/references/scripts.md b/references/scripts.md
index 75ae26f..30ea3e2 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -758,9 +758,13 @@ frame width) at the chosen `--size`, measured per script — CJK and Thai count
full em per character, Latin per character from a table read off DejaVu Sans (so
an all-caps line measures as wide as it draws), Cyrillic/Greek about 0.55,
Arabic/Hebrew 0.6, Devanagari 0.7, and a combining mark nothing at all —
-breaking between characters for CJK/Thai and at spaces otherwise, but never
-between a character and the combining marks that belong to it (Thai tone marks
-and vowel signs, Devanagari matras, Arabic and Hebrew points). A cue that would need more than `--max-lines` (default 2) is split
+breaking between characters for CJK (a katakana word stays whole) and at spaces
+otherwise, but never between a character and the combining marks that belong
+to it (Devanagari matras, Arabic and Hebrew points). Thai (1.16.1) is never
+broken inside a run: it writes no space inside a phrase and the wrapper has no
+dictionary, so the break goes where you put a space or a `|`, and a run with
+none stays long on its own line — `caption.py` counts such lines as `overlong`
+and says so. A cue that would need more than `--max-lines` (default 2) is split
into consecutive cues sharing its time; a cue shorter than `--min-duration`
(default 1.0 s) is held longer, never past the next cue's start; `--offset
TIME` shifts every cue (seconds, `mm:ss`, `hh:mm:ss.ms` or `hh:mm:ss:ff`, a
diff --git a/scripts/_common/text.py b/scripts/_common/text.py
index 87d1865..bdf16d3 100644
--- a/scripts/_common/text.py
+++ b/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
diff --git a/scripts/caption.py b/scripts/caption.py
index 67aa6b8..ac15cc7 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -461,6 +461,10 @@ def layout_cues(cues: List[Tuple[float, float, str]], *, max_em: Optional[float]
lines, greedy, measured = wrap_variants(text, max_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):
+ # 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
if lines != greedy:
stats["rebalanced"] += 1
if wrap != "measured" and lines != measured:
@@ -492,9 +496,13 @@ 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") if stats.get(k)]
+ parts = [f"{stats[k]} {k}" for k in ("shifted", "wrapped", "rebalanced", "phrase_breaks", "split", "extended", "dropped", "overlong") if stats.get(k)]
if parts:
info("cues: " + ", ".join(parts))
+ 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")
def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[float]:
diff --git a/tests/test_picture.py b/tests/test_picture.py
index 4934bd0..d0e7b5b 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -2244,9 +2244,10 @@ class WrapReadabilityTests(unittest.TestCase):
def test_caption_wrap_never_leaves_a_one_character_orphan_line(self):
C = self.caption
cases = [
- # th1's Thai cue and dl3's Japanese cue, at sizes where greedy wrapping stranded one character
- ("\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e17\u0e35\u0e48\u0e2a\u0e2d\u0e07\u0e02\u0e2d\u0e07\u0e04\u0e33\u0e1a\u0e23\u0e23\u0e22\u0e32\u0e22 "
- "\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e19\u0e35\u0e49\u0e15\u0e31\u0e49\u0e07\u0e40\u0e27\u0e25\u0e32\u0e43\u0e2b\u0e49\u0e2d\u0e31\u0e15\u0e42\u0e19\u0e21\u0e31\u0e15\u0e34", 8),
+ # dl3's Japanese cue at sizes where greedy wrapping stranded one character (the Thai
+ # case this test carried until 1.16.0 is gone: a Thai run is no longer broken inside,
+ # see test_th1_cue_exact_split); a Chinese run stands in for the per-character scripts
+ ("\u4eca\u5929\u5929\u6c14\u5f88\u597d\u6211\u4eec\u53bb\u516c\u56ed\u6563\u6b65\u5427\u597d", 7),
("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
"\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c", 10),
("\u3053\u3093\u306b\u3061\u306f\u3001\u4e16\u754c 2 \u884c\u76ee\u306e\u5b57\u5e55\u3067\u3059 "
@@ -2382,14 +2383,39 @@ class PhraseWrapTests(unittest.TestCase):
["\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c", "\u6c7a\u307e\u308b\u884c"])
def test_th1_cue_exact_split(self):
- """th1: the trailing line is never the stranded `\u0e44\u0e2b\u0e25` alone."""
+ """th1: the trailing line is never the stranded `\u0e44\u0e2b\u0e25` alone -- and since 1.16.1 a
+ Thai run is never broken inside at all. Thai writes no space inside a phrase and the
+ wrapper has no dictionary, so every character-level break eval 17 took landed inside a
+ word (`\u0e02|\u0e2d\u0e07`, `\u0e40\u0e27|\u0e25\u0e32`). The break goes where the writer put a space; a run
+ with none stays long on its own line, the rule long Latin words already follow."""
C = self.caption
- text = "\u0e2a\u0e27\u0e31\u0e2a\u0e14\u0e35\u0e0a\u0e32\u0e27\u0e42\u0e25\u0e01 \u0e40\u0e2a\u0e35\u0e22\u0e07\u0e19\u0e49\u0e33\u0e44\u0e2b\u0e25"
+ first, second = "\u0e2a\u0e27\u0e31\u0e2a\u0e14\u0e35\u0e0a\u0e32\u0e27\u0e42\u0e25\u0e01", "\u0e40\u0e2a\u0e35\u0e22\u0e07\u0e19\u0e49\u0e33\u0e44\u0e2b\u0e25"
+ text = first + " " + second
for max_em in (self.NARROW, 8.0, self.W):
with self.subTest(max_em=max_em):
lines = C.wrap_text(text, max_em)
- self.assertNotEqual(lines[-1].strip(), "\u0e44\u0e2b\u0e25", lines)
+ self.assertEqual(lines, [first, second], lines)
self.assertFalse(C._is_weak_line(lines[-1]), lines)
+ # a Thai run with no space is one atom: never chopped, however narrow the line
+ run = "\u0e1a\u0e23\u0e23\u0e17\u0e31\u0e14\u0e17\u0e35\u0e48\u0e2a\u0e2d\u0e07\u0e02\u0e2d\u0e07\u0e04\u0e33\u0e1a\u0e23\u0e23\u0e22\u0e32\u0e22"
+ self.assertEqual(C.wrap_text(run, self.NARROW), [run])
+ self.assertEqual(C.wrap_text(run, 8.0, mode="measured"), [run])
+
+ def test_katakana_run_is_one_atom(self):
+ """eval 17 dl3: `\u30bf\u30a4|\u30df\u30f3\u30b0` -- a katakana loan word was broken like a run of kanji.
+ Katakana plus the prolonged-sound mark are one atom; the break lands before or after
+ the word, and a word too wide for the line stays long rather than chopped."""
+ C = self.caption
+ jp = "\u81ea\u52d5\u3067\u30bf\u30a4\u30df\u30f3\u30b0\u304c\u6c7a\u307e\u308b\u884c"
+ for max_em in (self.NARROW, 8.0, 10.0):
+ with self.subTest(max_em=max_em):
+ joined = "".join(C.wrap_text(jp, max_em))
+ self.assertEqual(joined, jp)
+ for line in C.wrap_text(jp, max_em):
+ self.assertFalse(line.endswith("\u30bf\u30a4") or line.startswith("\u30df\u30f3\u30b0"), line)
+ self.assertEqual(C.wrap_text(jp, self.NARROW), ["\u81ea\u52d5\u3067", "\u30bf\u30a4\u30df\u30f3\u30b0\u304c", "\u6c7a\u307e\u308b\u884c"])
+ self.assertEqual(C.wrap_text("\u30b3\u30f3\u30d4\u30e5\u30fc\u30bf\u30fc\u3092\u8cb7\u3063\u305f", 7.0), ["\u30b3\u30f3\u30d4\u30e5\u30fc\u30bf\u30fc", "\u3092\u8cb7\u3063\u305f"])
+ self.assertEqual([a for a, _ in C._atoms("\u30bf\u30a4\u30df\u30f3\u30b0\u304c")][0], "\u30bf\u30a4\u30df\u30f3\u30b0")
# -------------------------------------------------------------- R4: function words
def test_function_word_never_ends_a_line(self):