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.
Python agent-skillsai-agentsaudio-processingcaptionsclaude-codecodexcoding-agentcursorffmpegloudness-normalizationmcpmcp-servermodel-context-protocolpythonsubtitlestranscodingvideovideo-editingvideo-processingwhisper
fix: 1.17.2 — caption ASS side margins from the horizontal safe zone (#239)
claude[bot]850a535ed43d
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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 thecaption `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 cuediff --git a/README.md b/README.mdindex 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.gifindex 988558f..72c89f7 100644Binary files a/docs/demos/captions_pop_karaoke.gif and b/docs/demos/captions_pop_karaoke.gif differdiff --git a/docs/demos/template_tiktok.gif b/docs/demos/template_tiktok.gifindex 5a15ea0..5fe9bc3 100644Binary files a/docs/demos/template_tiktok.gif and b/docs/demos/template_tiktok.gif differdiff --git a/docs/roadmap.md b/docs/roadmap.mdindex 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 talso root-caused a defect the two previous patches had been aiming at symptoms of: `caption.py`'sgenerated-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 isplanned.| 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 perline" 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.mdindex 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 TikTokcaption size (24 ASS units against the 288-line script grid) a line has aboutsix 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-capablelibass and refuses otherwise. Nothing is ever downloaded. What this machine cando: `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 afull em per character, Latin per character from a table read off DejaVu Sans (soan 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.pyindex 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 therendered 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: intscale = play_h / 288.0 # our --size is relative to a 288-line script like force_stylesize = 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" oneprimary = 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.pyindex d2d1431..377e6ad 100644--- a/tests/_fixtures.py+++ b/tests/_fixtures.py@@ -22,6 +22,7 @@ HERE = Path(__file__).resolve().parentOUT = 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: E402TONES = ("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.stdoutif 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 Falsediff --git a/tests/fixtures/caption_1_16_1_fitsize_off.ass b/tests/fixtures/caption_1_16_1_fitsize_off.assindex 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 meDialogue: 0,0:00:03.00,0:00:04.80,Default,,0,0,0,,{\fad(200,200)}Segunda\Nlínea deDialogue: 0,0:00:04.80,0:00:06.00,Default,,0,0,0,,{\fad(200,200)}subtítulosdiff --git a/tests/test_picture.py b/tests/test_picture.pyindex 88328c7..377dd6b 100644--- a/tests/test_picture.py+++ b/tests/test_picture.py@@ -18,7 +18,7 @@ import unittest.mockfrom pathlib import Pathsys.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: E402from _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 -- thebudget of the smallest size, which is the widest line in em -- and then drawn at its ownlarger 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 importlibtext_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 flagdrawn = 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 judgementthe agent has to make -- the run states it (eval 18 cs2/cs3, where one run rewrote the