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: 1.17.2 — caption ASS side margins from the horizontal safe zone (#239)

claude[bot]850a535ed43d
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 29e2e22..afb96c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -12,6 +12,23 @@ _Automated release: version and notes generated from pull requests merged since
### Fixed
+- **Caption side margins are the horizontal safe zone, not the vertical one** (eval 19 headline,
+ present since 1.14). `caption.py`'s generated ASS (`--animate`, `--karaoke`, the emoji overlay
+ route) wrote `--margin` into the Style's `MarginL` and `MarginR` as well as `MarginV`. But
+ `--margin` is the *vertical* safe margin: `--platform tiktok` makes it 22 % of the frame height
+ = 63 ASS units = **420 px** on a 1080x1920 frame, so libass was given a 1080 - 840 = **240 px**
+ text column and broke "Hello world" into "Hello" over "world", one word per line — while the
+ fitter and the wrapper measured against the horizontal safe width, reported `split: 0` and put
+ no `\N` in the file. `MarginL`/`MarginR` now come from the destination's own `safe.left` /
+ `safe.right` (TikTok: 54 px and 151 px on a 1080-wide frame, the like/share rail included), or
+ from the conventional `(1 - SAFE_WIDTH_FRACTION)/2` border with no `--platform`, and the
+ fitter's budget is exactly `play_w - MarginL - MarginR`, so the wrap the ASS states is the wrap
+ libass draws. The SRT `force_style` burn path never set side margins and is unchanged.
+ **Behaviour change, allowed by the stability paragraph of `docs/contract.md` because it fixes a
+ defect**: the pinned `--fit-size off` fixture (`tests/fixtures/caption_1_16_1_fitsize_off.ass`)
+ carried the wrong margins and has been re-pinned; `--fit-size off` still means "the size is
+ never shrunk".
+
- **The caption size is fitted on the template path too.** `render.py --template NAME` fills the
caption `size` from the delivery table and forwarded it as an explicit `--size`, which is how
`caption.py` is told "a human chose this size" — so `--fit-size auto` never ran and a long cue
diff --git a/README.md b/README.md
index e881dc6..0cd6347 100644
--- a/README.md
+++ b/README.md
@@ -239,7 +239,7 @@ These are the rules the skill file gives the agent and the code enforces.
| Tool | What it does |
|---|---|
-| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area with a phrase-aware breaker (`--wrap phrase|measured`) and `--max-lines`/`--min-duration`/`--offset`; `--mode mux` takes a repeated `--srt file:lang` for several language-tagged, toggleable tracks in one file; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; `--fit-size` shrinks the size until a cue fits `--max-lines` instead of splitting the sentence (on by default on the delivery-template path since 1.17.1, where the size comes from the platform table); says `caption text unchanged` when it burned the cues exactly as given; optional local transcription |
+| `caption.py` | Burn SRT/ASS with font, size, colour, outline, position; build SRT from timed plain text; wraps to the safe area — with `--platform`, the destination's own left/right safe zone, which since 1.17.2 is also what the burnt ASS states as its side margins — with a phrase-aware breaker (`--wrap phrase|measured`) and `--max-lines`/`--min-duration`/`--offset`; `--mode mux` takes a repeated `--srt file:lang` for several language-tagged, toggleable tracks in one file; picks a font by script for non-Latin text (`--lang`); animated and word-by-word karaoke timed to the speech energy or real word timings; `--fit-size` shrinks the size until a cue fits `--max-lines` instead of splitting the sentence (on by default on the delivery-template path since 1.17.1, where the size comes from the platform table); says `caption text unchanged` when it burned the cues exactly as given; optional local transcription |
| `overlay.py` | Logos, watermarks and titles with position, time range, opacity, fades; `--platform NAME` keeps them clear of that destination's UI; `--video` for picture-in-picture, `--chromakey` for green-screen compositing |
| `graphics.py` | Lower-thirds, title cards, chapter chips, progress bars, countdowns, corner bugs, social stickers, opening hook cards and meme captions drawn by FFmpeg from a brand kit; `--platform NAME` keeps them inside that destination's safe zone; `--text-render` routes shaping scripts through libass and `--emoji-assets` composites colour emoji |
| `color.py` | HDR10 / HLG / Dolby Vision → SDR BT.709 tone mapping, DV layer stripping, 3D LUT (.cube), colour-tag rewriting, typed primary correction (exposure/contrast/saturation/gamma/white balance/lift-gain/levels/curves) |
diff --git a/docs/demos/captions_pop_karaoke.gif b/docs/demos/captions_pop_karaoke.gif
index 988558f..72c89f7 100644
Binary files a/docs/demos/captions_pop_karaoke.gif and b/docs/demos/captions_pop_karaoke.gif differ
diff --git a/docs/demos/template_tiktok.gif b/docs/demos/template_tiktok.gif
index 5a15ea0..5fe9bc3 100644
Binary files a/docs/demos/template_tiktok.gif and b/docs/demos/template_tiktok.gif differ
diff --git a/docs/roadmap.md b/docs/roadmap.md
index 0a1485e..0986f01 100644
--- a/docs/roadmap.md
+++ b/docs/roadmap.md
@@ -24,7 +24,7 @@ path in 12/12 caption runs, and the beat, filler and `--jobs` prompts route on t
also root-caused a defect the two previous patches had been aiming at symptoms of: `caption.py`'s
generated-ASS path writes the platform's *vertical* safe margin into `MarginL` and `MarginR` too,
so libass lays every caption into a 240 px column and stacks one word per line (see the 1.17.1
-section). **1.17.2 below is the patch and is planned for release.** Everything after 1.17.2 is
+section). **1.17.2 below is the patch — implemented, not tagged yet.** Everything after 1.17.2 is
planned.
| version | state | evidence |
@@ -42,7 +42,7 @@ planned.
| 1.16.1 | shipped + evaluated | caption-break patch from eval 17: a Thai run and a katakana word are never broken inside, `caption.py` reports `overlong` lines; eval 18 graded the tree that carries it and reported no wrapping defect |
| 1.17.0 | shipped, evaluated (eval 18) | eval 18 at 1.17.0 (`iteration-18.json`); tool count still 42; contract and MCP snapshots additive only. Two findings: `render.py` forwards the platform table's caption size as an explicit `--size`, so `--fit-size` never fires on the path every captioned prompt takes (and the project schema rejects `fit_size`), 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 |
| 1.17.1 | shipped, evaluated (eval 19) | eval 19 at 1.17.1 (`iteration-19.json`), 26 runs over the 18 prompts eval 18 named; tool count still 42, contract additive only. The patch holds: `--fit-size` fires on the template path 12/12 (24 → 16, `dl4` to the 13-unit floor, `split` 0, `text_unchanged` true), filler and beats route first try, the third label is gone, trigger 50/50. One finding, and it is older than the patch: `caption.py write_ass` writes the platform's vertical safe margin to `MarginL`/`MarginR` as well as `MarginV`, leaving a 240 px text column at `PlayResX` 1080, so the picture still stacks one word per line on the `--animate`/`--karaoke` path every template takes. Present since 1.14. 1.17.2 is the patch |
-| 1.17.2 | planned for release | patch from eval 19: horizontal caption margins from the platform's left/right safe zone, the fitter measuring the same budget, the never-rewrite-the-user's-captions refusal line, regression tests on the ASS path; tool count still 42, contract additive only |
+| 1.17.2 | implemented, not tagged yet | eval 19 headline: `caption.py` wrote the VERTICAL `--margin` into the ASS Style's `MarginL`/`MarginR` too, so TikTok geometry left a 240 px text column and libass stacked one word per line while the tool reported `split: 0`. The side margins are the destination's horizontal safe zone and the fitter measures the same column; the pinned `--fit-size off` ASS fixture was re-pinned (it carried the wrong margins). Tool count still 42, contract additive only |
| 1.18.0 → 1.21.0, 2.0.0 | planned | — |
## 1.8.0 — one-call delivery, quieter checks, encoder flags (shipped + evaluated, eval 8)
@@ -388,27 +388,30 @@ came out byte-identical, as did `--help` for all 42 tools.
since 1.14 introduced the platform margins, and it explains eval 17's and eval 18's "one word per
line" as well — both of which were patched at symptoms of this line. 1.17.2 is the patch.
-## 1.17.2 — horizontal caption margins (planned)
-
-The eval-19 patch. Small, and aimed at the line the last two patches missed.
-
-- **`caption.py write_ass` derives `MarginL` and `MarginR` from the platform's horizontal safe
- fractions × `play_w`** (defaulting to the 5 % title-safe), independently of `MarginV`, which
- keeps taking the vertical safe margin it takes today. No flag; the current behaviour is a bug,
- not a policy.
-- **The fitter measures the budget the Style row will actually grant**, so `size_used`, `split`
- and `text_unchanged` describe the rendered frame rather than a wider imaginary one.
-- **Regression tests on the ASS path**: a unit assertion that `Style` `MarginL + MarginR` is at
- most `(1 - SAFE_WIDTH_FRACTION) × play_w` at tiktok geometry, and an e2e asserting the generated
- ASS for "Hello world" at `--platform tiktok` contains no `\N`.
-- **One SKILL.md refusal line in the caption section**: never rewrite, shorten or paraphrase the
- user's caption text; offer `--max-lines` or a smaller size instead. `cs3` has taken the forbidden
- path in three iterations running (17, 18, 19) and the prose elsewhere in the file has not closed
- it.
-- **Eval 20** re-runs this set and the full 100, and grades the caption prompts on the contact
- sheet rather than on the fit stats — the question is how many lines the frame has, not what the
- fitter reports. Whether `silence.py --filler` should leave silences alone unless asked (eval 19
- fw1/fw3 each cut ~5 s nobody requested, both disclosed) is a 1.18.0 decision, not a patch.
+## 1.17.2 — the caption-margin patch (implemented, not tagged yet)
+
+- **Done. The caption Style's side margins are the horizontal safe zone.** Since 1.14 `write_ass`
+ wrote `--margin` — the *vertical* safe margin, 63 ASS units = 420 px at TikTok geometry — into
+ `MarginL` and `MarginR` as well, leaving libass a 240 px column on a 1080-wide frame: "Hello
+ world" was drawn as "Hello" over "world" while the fitter and the wrapper measured the
+ horizontal safe width and reported no wrap at all (eval 19 headline; dl4's Spanish cues hit the
+ 13-unit floor and still stacked). `MarginL`/`MarginR` now come from `safe.left`/`safe.right`,
+ or from the conventional 5 % border with no `--platform`, and `line_em_for_size`/`fit_size`
+ use exactly `play_w - MarginL - MarginR`. The SRT `force_style` path is unchanged.
+- The pinned `--fit-size off` fixture was re-pinned: it carried the wrong margins. A behaviour
+ change to fix a defect, with the CHANGELOG line the stability paragraph of `docs/contract.md`
+ asks for.
+
+- **Regression tests on the ASS path** (`tests/test_picture.py`): the Style row's `MarginL` and
+ `MarginR` equal the platform's safe zone at tiktok geometry, the generated ASS for "Hello world"
+ at `--platform tiktok` contains no `\N`, and the rasterised frame carries exactly `\N + 1` text
+ bands for the cw1 cues — the picture, not the fit stats.
+- **Not in this patch, carried to the next docs/skill change**: the SKILL.md refusal line "never
+ rewrite, shorten or paraphrase the user's caption text; offer `--max-lines` or a smaller size"
+ (`cs3` took the forbidden path in evals 17, 18 and 19). Whether `silence.py --filler` should
+ leave silences alone unless asked (eval 19 fw1/fw3) is a 1.18.0 decision, not a patch.
+- **Eval 20** re-runs the caption set, three repeats each, and grades the caption prompts on the
+ contact sheet rather than on the fit stats.
## 1.18.0 — measured analysis and multicam at scale (still no judgement) (planned)
diff --git a/references/scripts.md b/references/scripts.md
index 23b0588..6f6552a 100644
--- a/references/scripts.md
+++ b/references/scripts.md
@@ -952,6 +952,24 @@ caption.py INPUT --srt FILE[:LANG] | --ass FILE | --text CUES.txt [--write-srt O
[--emoji auto|color|png|mono|none] [--emoji-assets DIR] [--emoji-scale 1.0] [--emoji-max 60] [-o OUT]
caption.py --text CUES.txt --write-srt OUT.srt # generate the SRT only
```
+**Caption margins (1.17.2).** `--margin` is the **vertical** distance from the
+edge, in ASS units against the 288-line script grid (default 30; with
+`--platform` it becomes that destination's `safe.top`/`safe.bottom`, e.g. 22 %
+of the frame height = 63 units for TikTok's description bar). It is the ASS
+Style's `MarginV` and nothing else. The **side** margins come from the
+destination's horizontal safe zone — `safe.left` / `safe.right` in
+`scripts/_platforms.py`, 5 % and 14 % for TikTok, so a line stays off the
+like/share rail — and with no `--platform` from the conventional
+`(1 - SAFE_WIDTH_FRACTION)/2 = 5 %` border per side. The wrapper and `--fit-size`
+measure against exactly that column (`play_w - MarginL - MarginR`), so the line
+breaks the ASS states are the line breaks libass draws.
+
+Before 1.17.2 `--margin` was written into `MarginL` and `MarginR` too: at TikTok
+geometry that left a 240 px column on a 1080-wide frame and libass stacked one
+word per line while the tool reported no wrap at all. The `subtitles`/
+`force_style` burn path (no `--animate`/`--karaoke`) only ever set `MarginV` and
+is unchanged.
+
**`--fit-size` (1.17): the size is fitted before a cue is split.** At the TikTok
caption size (24 ASS units against the 288-line script grid) a line has about
six em, so an ordinary sentence needs four lines — and `--max-lines 2` then cut
@@ -1033,8 +1051,9 @@ warning; `--emoji none` strips them; `--emoji color` insists on a colour-capable
libass and refuses otherwise. Nothing is ever downloaded. What this machine can
do: `doctor --json` → `.fonts.emoji`. Details: `references/gotchas.md#emoji`.
-Readable by default (1.12, rebalanced in 1.15): every cue is wrapped to the safe area (90 % of the
-frame width) at the chosen `--size`, measured per script — CJK and Thai count a
+Readable by default (1.12, rebalanced in 1.15): every cue is wrapped to the safe area — the
+frame width minus the two side margins below, 90 % of it without a `--platform` — at the chosen
+`--size`, measured per script — CJK and Thai count a
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 —
diff --git a/scripts/caption.py b/scripts/caption.py
index 22965cc..954a61c 100755
--- a/scripts/caption.py
+++ b/scripts/caption.py
@@ -390,13 +390,66 @@ def report_layout(stats: dict) -> None:
"space or `|` where the line may break, or use a smaller --size")
+def margins_x(args, play_w: Optional[int]) -> Tuple[int, int]:
+ """(MarginL, MarginR) in ASS script pixels -- the HORIZONTAL safe zone, never --margin.
+
+ 1.17.2. --margin is the vertical distance from the edge (the platform's bottom UI: TikTok's
+ description bar is 22 % of the frame, 63 ASS units, 420 px on a 1920-tall frame). Writing it
+ into MarginL/MarginR as well, as 1.14-1.17.1 did, left a 1080-wide frame with a 240 px text
+ column and libass wrapped "Hello world" onto two lines while the fitter -- which measures
+ against the horizontal safe width -- reported no wrap at all.
+
+ The left/right margins come from the destination's own horizontal safe zone (`safe.left` /
+ `safe.right` in scripts/_platforms.py; TikTok reserves 14 % on the right for the like/share
+ rail), and without a --platform from the conventional (1 - SAFE_WIDTH_FRACTION)/2 border --
+ the same 5 % per side the wrapper has always assumed. A run that writes no ASS of its own
+ (the SRT force_style burn) keeps that symmetric border, so its budget is unchanged at
+ SAFE_WIDTH_FRACTION and the fitter still agrees with what libass will do.
+ """
+ if not play_w:
+ return 0, 0
+ if getattr(args, "platform", None) and PLATFORMS[args.platform].get("frame") and draws_own_ass(args):
+ safe = PLATFORMS[args.platform]["safe"]
+ left, right = float(safe["left"]), float(safe["right"])
+ else:
+ left = right = (1.0 - SAFE_WIDTH_FRACTION) / 2.0
+ return int(round(left * play_w)), int(round(right * play_w))
+
+
+def draws_own_ass(args) -> bool:
+ """True when this run generates its own ASS, and so sets its own Style margins.
+
+ An SRT burn goes through libass's force_style instead, which states MarginV only and leaves
+ the side margins at libass's own defaults -- that path's budget stays the historical
+ play_w * SAFE_WIDTH_FRACTION, unchanged by 1.17.2.
+ """
+ if getattr(args, "ass", None):
+ return False # the caller's own ASS: its Style is theirs, not ours
+ return (getattr(args, "animate", "none") or "none") != "none" or bool(getattr(args, "karaoke", False))
+
+
+def safe_width_fraction(args, play_w: Optional[int]) -> float:
+ """The fraction of the frame width a caption line may use -- play_w minus the two margins.
+
+ The fitter and libass have to agree to the pixel, so this is derived from the SAME rounded
+ MarginL/MarginR that go into the ASS Style rather than from the raw fractions. On a run that
+ writes no ASS of its own the margins are the symmetric border, i.e. SAFE_WIDTH_FRACTION, so
+ the SRT force_style path keeps its historical budget.
+ """
+ if not play_w:
+ return SAFE_WIDTH_FRACTION
+ left, right = margins_x(args, play_w)
+ return max(0.05, (play_w - left - right) / float(play_w))
+
+
def max_line_em(args, play_w: Optional[int], play_h: Optional[int]) -> Optional[float]:
"""How many em fit on one caption line at the chosen size, or None without video geometry.
--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.
"""
- return line_em_for_size(args.size, play_w, play_h)
+ return line_em_for_size(args.size, play_w, play_h,
+ safe_fraction=safe_width_fraction(args, play_w))
def parse_ass_dialogue(path: str) -> str:
@@ -467,7 +520,8 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
scale = play_h / 288.0 # our --size is relative to a 288-line script like force_style
size = int(round(args.size * scale))
- margin = int(round(args.margin * scale))
+ margin = int(round(args.margin * scale)) # vertical: MarginV, and the slide origin
+ margin_l, margin_r = margins_x(args, play_w) # horizontal: the frame's safe zone
# karaoke: PrimaryColour is the "sung" colour, SecondaryColour the "not yet sung" one
primary = ass_color(args.highlight_color if args.karaoke else args.color)
secondary = ass_color(args.color)
@@ -477,7 +531,7 @@ def write_ass(cues: List[Tuple[float, float, str]], path: str, args, play_w: int
"[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}", "WrapStyle: 0", "ScaledBorderAndShadow: yes", "",
"[V4+ Styles]",
"Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding",
- f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin},{margin},{margin},1",
+ f"Style: Default,{ass_font_name(args.font)},{size},{primary},{secondary},{outline},{back},{-1 if args.bold else 0},0,0,0,100,100,0,0,{3 if args.box else 1},{args.outline * scale:.1f},{args.shadow * scale:.1f},{ALIGN[args.position]},{margin_l},{margin_r},{margin},1",
"", "[Events]", "Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text",
]
lines = []
@@ -888,7 +942,8 @@ def main() -> int:
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)
+ mode=args.wrap, lang=args.language, scope=args.fit_size_scope,
+ safe_fraction=safe_width_fraction(args, play_w))
def fit_the_size(cue_list):
"""Shrink --size until every cue fits --max-lines, BEFORE the cue is split.
@@ -929,7 +984,8 @@ def main() -> int:
# 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)
+ play_w, play_h,
+ safe_fraction=safe_width_fraction(args, play_w))
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))]
diff --git a/tests/_fixtures.py b/tests/_fixtures.py
index d2d1431..377e6ad 100644
--- a/tests/_fixtures.py
+++ b/tests/_fixtures.py
@@ -22,6 +22,7 @@ HERE = Path(__file__).resolve().parent
OUT = Path(os.environ.get("OUT", ROOT / "tests" / "out"))
sys.path.insert(0, str(SCRIPTS))
sys.path.insert(0, str(HERE))
+from _common import escape_filter_path # noqa: E402
TONES = ("0.6*sin(2*PI*440*t)*gt(sin(2*PI*0.37*t)\\,0.3)+0.4*sin(2*PI*880*t)*gt(sin(2*PI*0.53*t+1)\\,0.6)"
"+0.3*sin(2*PI*220*t)*gt(sin(2*PI*0.21*t+2)\\,0.7)")
@@ -91,7 +92,7 @@ def _ass_ink_columns(ass_path, w, h, threshold=60):
"""The set of x columns that carry ink when `ass_path` is rendered over black at w x h."""
proc = subprocess.run(
["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=0.04" % (w, h),
- "-vf", "ass=%s" % str(ass_path).replace("\\", "/"), "-frames:v", "1",
+ "-vf", "ass=%s" % escape_filter_path(str(ass_path)), "-frames:v", "1",
"-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
data = proc.stdout
if len(data) < w * h:
@@ -99,6 +100,30 @@ def _ass_ink_columns(ass_path, w, h, threshold=60):
return {x for x in range(w) if any(data[y * w + x] > threshold for y in range(h))}
+def _ass_ink_rows(ass_path, w, h, threshold=60, gap=8, at=1.0):
+ """Bands of y rows that carry ink when `ass_path` is rendered over black at w x h.
+
+ One band per drawn text line (a blank row taller than `gap` separates two lines), so a caption
+ that libass wrapped onto two lines is visible as two bands without measuring any font.
+ """
+ # `at` matters: --animate fade/pop start at zero alpha, so the frame at t=0 is blank.
+ proc = subprocess.run(
+ ["ffmpeg", "-v", "error", "-f", "lavfi", "-i", "color=c=black:s=%dx%d:d=%.2f" % (w, h, at + 0.5),
+ "-ss", "%.2f" % at, "-vf", "ass=%s" % escape_filter_path(str(ass_path)), "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
+ data = proc.stdout
+ if len(data) < w * h:
+ return []
+ lit = [y for y in range(h) if sum(1 for v in data[y * w:(y + 1) * w] if v > threshold) > 2]
+ bands = []
+ for y in lit:
+ if bands and y - bands[-1][1] <= gap:
+ bands[-1][1] = y
+ else:
+ bands.append([y, y])
+ return [tuple(b) for b in bands]
+
+
def _family_installed(family):
if not shutil.which("fc-list"):
return False
diff --git a/tests/fixtures/caption_1_16_1_fitsize_off.ass b/tests/fixtures/caption_1_16_1_fitsize_off.ass
index b23da53..1891b27 100644
--- a/tests/fixtures/caption_1_16_1_fitsize_off.ass
+++ b/tests/fixtures/caption_1_16_1_fitsize_off.ass
@@ -7,11 +7,11 @@ ScaledBorderAndShadow: yes
[V4+ Styles]
Format: Name, Fontname, Fontsize, PrimaryColour, SecondaryColour, OutlineColour, BackColour, Bold, Italic, Underline, StrikeOut, ScaleX, ScaleY, Spacing, Angle, BorderStyle, Outline, Shadow, Alignment, MarginL, MarginR, MarginV, Encoding
-Style: Default,DejaVu Sans,160,&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,13.3,0.0,2,420,420,420,1
+Style: Default,DejaVu Sans,160,&H00FFFFFF,&H00FFFFFF,&H00000000,&H80000000,0,0,0,0,100,100,0,0,1,13.3,0.0,2,54,151,420,1
[Events]
Format: Layer, Start, End, Style, Name, MarginL, MarginR, MarginV, Effect, Text
-Dialogue: 0,0:00:00.00,0:00:01.94,Default,,0,0,0,,{\fad(200,200)}A third line\Nthe tool
-Dialogue: 0,0:00:01.94,0:00:03.00,Default,,0,0,0,,{\fad(200,200)}times\Nfor me
+Dialogue: 0,0:00:00.00,0:00:01.45,Default,,0,0,0,,{\fad(200,200)}A third\Nline the
+Dialogue: 0,0:00:01.45,0:00:03.00,Default,,0,0,0,,{\fad(200,200)}tool times\Nfor me
Dialogue: 0,0:00:03.00,0:00:04.80,Default,,0,0,0,,{\fad(200,200)}Segunda\Nlínea de
Dialogue: 0,0:00:04.80,0:00:06.00,Default,,0,0,0,,{\fad(200,200)}subtítulos
diff --git a/tests/test_picture.py b/tests/test_picture.py
index 88328c7..377dd6b 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -18,7 +18,7 @@ import unittest.mock
from pathlib import Path
sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _ass_advance, _ass_ink_columns, _emoji_assets, _families_for, _family_installed, _frame_ink, _no_fontconfig, _pixel_at, script, sh # noqa: E402
+from _fixtures import MediaFixtures, OUT, SCRIPTS, TONES, _ass_advance, _ass_ink_columns, _ass_ink_rows, _emoji_assets, _families_for, _family_installed, _frame_ink, _no_fontconfig, _pixel_at, script, sh # noqa: E402
from _common import default_font_file, detect_script, escape_filter_path, font_family_for_script, font_for_script, probe # noqa: E402
@@ -1707,10 +1707,15 @@ class PictureTests(MediaFixtures):
"""The regression: with scope=cue every cue was wrapped to the FILE's budget -- the
budget of the smallest size, which is the widest line in em -- and then drawn at its own
larger size, so lines ran off the side of the frame. Each cue is now laid out at the size
- it is drawn at, and no rendered line exceeds the safe width."""
+ it is drawn at, and no rendered line exceeds the safe width.
+
+ 1.17.2: "the safe width" is now the ASS Style's real column (play_w minus the horizontal
+ safe margins), not play_w * SAFE_WIDTH_FRACTION, and the third cue genuinely needs three
+ lines at the floor in TikTok's narrower column -- it is split, and says so."""
sys.path.insert(0, str(SCRIPTS))
import importlib
text_mod = importlib.import_module("_common.text")
+ caption_mod = importlib.import_module("caption")
vert = self._vertical()
cues = OUT / "cues_scope.txt"
cues.write_text("0:00-0:03 A third line the tool times for me\n"
@@ -1724,15 +1729,25 @@ class PictureTests(MediaFixtures):
"-o", OUT / "cap_scope.mp4", "--json").stdout)
cap = data["caption"]
self.assertEqual(cap["fit_scope"], "cue")
- self.assertEqual(cap["split"], 0)
+ # a cue is split only when the floor really cannot hold it, and then it is reported
+ self.assertEqual(bool(cap["split"]), bool(cap["fit_exhausted"]),
+ "a split without fit_exhausted means the budget, not the floor, gave way")
body = ass.read_text(encoding="utf-8-sig")
- style_px = int(next(l for l in body.splitlines() if l.startswith("Style:")).split(",")[2])
+ style_line = next(l for l in body.splitlines() if l.startswith("Style:"))
+ style_px = int(style_line.split(",")[2])
+ margin_l, margin_r = (int(style_line.split(",")[-4]), int(style_line.split(",")[-3]))
dialogue = [l for l in body.splitlines() if l.startswith("Dialogue:")]
- self.assertEqual(len(dialogue), 3)
+ self.assertGreaterEqual(len(dialogue), 3)
# at least two different drawn sizes, which is the whole point of the flag
drawn = set()
- safe_px = 1080 * text_mod.SAFE_WIDTH_FRACTION
+ # the column libass actually draws into -- the same number the fitter measured
+ safe_px = 1080 - margin_l - margin_r
+ self.assertAlmostEqual(safe_px / 1080.0,
+ caption_mod.safe_width_fraction(
+ type("A", (), {"platform": "tiktok", "animate": "fade",
+ "karaoke": False, "ass": None})(), 1080),
+ places=6)
for line in dialogue:
payload = line.split(",,0,0,0,,", 1)[1]
override = re.search(r"\{\\fs(\d+)\}", payload)
@@ -1745,9 +1760,15 @@ class PictureTests(MediaFixtures):
f"{rendered!r} is {width:.0f}px at size {px}, safe {safe_px:.0f}px")
self.assertGreaterEqual(len(drawn), 2)
- def test_caption_fit_size_off_is_byte_identical_to_1_16_1(self):
- """The stability answer: one flag restores the old ASS byte for byte. The pinned file
- was generated by 1.16.1's own caption.py (tests/fixtures/caption_1_16_1_fitsize_off.ass)."""
+ def test_caption_fit_size_off_matches_the_pinned_ass(self):
+ """The stability answer: one flag restores the old layout, byte for byte against a pinned
+ file (tests/fixtures/caption_1_16_1_fitsize_off.ass).
+
+ The fixture was generated by 1.16.1's own caption.py and RE-PINNED at 1.17.2: it carried
+ the defect this release fixes -- MarginL=MarginR=MarginV=420 on a 1080-wide frame, a
+ 240 px text column -- so it pinned wrong bytes. The re-pin keeps --fit-size off meaning
+ exactly what it meant (the size is never shrunk); only the side margins, and the wrap
+ budget that now agrees with them, differ."""
vert, cues = self._vertical(), self._fit_cues()
ass = OUT / "cap_fit_off.ass"
script("caption.py", vert, "--text", cues, "--platform", "tiktok", "--max-lines", "2",
@@ -1756,6 +1777,90 @@ class PictureTests(MediaFixtures):
pinned = Path(__file__).resolve().parent / "fixtures" / "caption_1_16_1_fitsize_off.ass"
self.assertEqual(ass.read_bytes(), pinned.read_bytes())
+ # ------------------------------------------------- 1.17.2: the horizontal margins are horizontal
+ def _style_margins(self, ass_path):
+ """(MarginL, MarginR, MarginV) from the ASS Style line."""
+ style = next(l for l in Path(ass_path).read_text(encoding="utf-8-sig").splitlines()
+ if l.startswith("Style: Default,"))
+ fields = style.split(",")
+ return int(fields[-4]), int(fields[-3]), int(fields[-2])
+
+ def test_caption_style_margins_are_the_horizontal_safe_zone(self):
+ """1.17.2, the eval-19 defect: --margin is the VERTICAL safe margin (TikTok's 22 % bottom
+ bar = 63 ASS units = 420 px on a 1920-tall frame) and 1.14-1.17.1 wrote it into MarginL
+ and MarginR as well, leaving a 240 px text column on a 1080-wide frame. The side margins
+ come from the destination's own left/right safe zone instead."""
+ sys.path.insert(0, str(SCRIPTS))
+ import importlib
+ platforms = importlib.import_module("_platforms")
+ ass = OUT / "cap_margins.ass"
+ script("caption.py", self._vertical(), "--text", self._fit_cues(), "--platform", "tiktok",
+ "--animate", "pop", "--karaoke", "--font", "DejaVu Sans",
+ "--write-ass", ass, "-o", OUT / "cap_margins.mp4")
+ left, right, vertical = self._style_margins(ass)
+ safe = platforms.safe_of("tiktok")
+ self.assertEqual((left, right), (round(safe["left"] * 1080), round(safe["right"] * 1080)))
+ self.assertAlmostEqual(vertical, safe["bottom"] * 1920, delta=4) # via whole ASS units
+ # the column libass is given, not the sliver the vertical margin used to leave
+ self.assertGreater(1080 - left - right, 0.75 * 1080)
+ self.assertLess(left + right, 2 * vertical)
+
+ def test_caption_style_margins_without_a_platform_are_the_conventional_border(self):
+ """No --platform: the sides are the (1 - SAFE_WIDTH_FRACTION)/2 border the wrapper has
+ always assumed, so the fitter's budget and libass's column are the same number."""
+ sys.path.insert(0, str(SCRIPTS))
+ import importlib
+ text_mod = importlib.import_module("_common.text")
+ ass = OUT / "cap_margins_noplat.ass"
+ script("caption.py", self._vertical(), "--text", self._fit_cues(), "--animate", "fade",
+ "--font", "DejaVu Sans", "--write-ass", ass, "-o", OUT / "cap_margins_noplat.mp4")
+ left, right, _ = self._style_margins(ass)
+ self.assertEqual(left + right,
+ round((1 - text_mod.SAFE_WIDTH_FRACTION) * 1080))
+
+ def test_caption_two_words_stay_on_one_line_at_tiktok_size(self):
+ """The headline symptom: "Hello world" came out as "Hello" over "world" while the tool
+ reported split 0 and no wrap at all -- the fitter measured the horizontal safe width and
+ libass was handed a 240 px column. With --max-lines 1 the fit is asked for a single line;
+ it is a single line in the ASS text AND a single band of lit rows in libass's raster."""
+ cues = OUT / "cues_two_words.txt"
+ cues.write_text("0:00-0:03 Hello world\n", encoding="utf-8")
+ ass = OUT / "cap_two_words.ass"
+ data = json.loads(script("caption.py", self._vertical(), "--text", cues,
+ "--platform", "tiktok", "--fit-size", "on", "--max-lines", "1",
+ "--animate", "pop", "--karaoke", "--font", "DejaVu Sans",
+ "--write-ass", ass, "-o", OUT / "cap_two_words.mp4",
+ "--json").stdout)
+ self.assertEqual(data["caption"]["split"], 0)
+ dialogue = [l for l in ass.read_text(encoding="utf-8-sig").splitlines()
+ if l.startswith("Dialogue:")]
+ self.assertEqual(len(dialogue), 1)
+ self.assertNotIn("\\N", dialogue[0].split(",,0,0,0,,", 1)[1])
+ bands = _ass_ink_rows(ass, 1080, 1920)
+ self.assertEqual(len(bands), 1, "the cue was drawn on %d lines: %s" % (len(bands), bands))
+
+ def test_caption_eval_cues_fit_two_lines_in_the_raster_too(self):
+ """The eval-17/18 cw1 cues on the TikTok template: <= 2 lines per cue in the ASS AND
+ <= 2 bands of lit rows per cue once libass has applied the Style margins."""
+ cues = self._fit_cues()
+ for index, (start, text) in enumerate((("0:00", "A third line the tool times for me"),
+ ("0:00", "Segunda l\u00ednea de subt\u00edtulos"))):
+ one = OUT / ("cues_band_%d.txt" % index)
+ one.write_text("%s-0:03 %s\n" % (start, text), encoding="utf-8")
+ ass = OUT / ("cap_band_%d.ass" % index)
+ script("caption.py", self._vertical(), "--text", one, "--platform", "tiktok",
+ "--max-lines", "2", "--animate", "fade", "--font", "DejaVu Sans",
+ "--write-ass", ass, "-o", OUT / ("cap_band_%d.mp4" % index))
+ dialogue = [l for l in ass.read_text(encoding="utf-8-sig").splitlines()
+ if l.startswith("Dialogue:")]
+ self.assertEqual(len(dialogue), 1, "the cue was split")
+ self.assertLessEqual(dialogue[0].count("\\N"), 1)
+ bands = _ass_ink_rows(ass, 1080, 1920)
+ self.assertLessEqual(len(bands), 2, "%r drew %d lines" % (text, len(bands)))
+ # the agreement itself: libass draws exactly the lines the ASS text asks for
+ self.assertEqual(len(bands), dialogue[0].count("\\N") + 1)
+ self.assertTrue(Path(cues).exists())
+
def test_caption_says_when_the_text_is_unchanged(self):
"""1.17.1: the report sentence "the text is yours, unchanged" should not be a judgement
the agent has to make -- the run states it (eval 18 cs2/cs3, where one run rewrote the