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(graphics): a wrapped title is drawn on its lines (#309)

Shogo Kajiyamab51c470543ec
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3c5cd47..69f5c8c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,7 @@
## Unreleased
-(nothing yet)
+- fix(graphics): a wrapped title is drawn on its lines. `graphics.py` wrapped a title that did not fit and sized its card for two lines, but the drawtext text file had every control character stripped, newline included, so "WHO SHOWS UP?", wrapped as "WHO\nSHOWS UP?", lost its line break and rendered on one line as "WHOSHOWS UP?", off both edges of the frame. Newlines are kept (`\r\n` and `\r` become `\n`; a tab, vertical tab or form feed becomes a space; other control characters are still stripped), and the centred templates (`title`, `hook`, `meme`) centre each line with drawtext's `text_align` on FFmpeg ≥ 6.1; on 5.1 and 6.0 the block is centred with its lines left-aligned. `overlay.py --text` keeps a user's newline too.
## 2.5.0
diff --git a/scripts/_common/__init__.py b/scripts/_common/__init__.py
index 6bf8d2c..8a924db 100644
--- a/scripts/_common/__init__.py
+++ b/scripts/_common/__init__.py
@@ -94,7 +94,7 @@ from _common.color import (
bt709_tag_args, color_hex, _COLOR_TOKEN_RE, _sdr_bt709, validate_color
)
from _common.text import (
- ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw,
+ ADVANCE_EM, BIDI_SCRIPTS, _char_em, char_script, default_font_file, detect_script, drawtext_boxborderw, drawtext_center_align,
drawtext_shaping, drawtext_text_opts, emoji_asset_for, EMOJI_ASSET_HINT, emoji_clusters, emoji_codepoint_name,
_EMOJI_COLOR_FAMILIES, _emoji_color_font, emoji_filter_chain, _emoji_name_candidates, EMOJI_RANGES,
_EMOJI_REGIONAL, emoji_support, _EMOJI_SUPPORT_CACHE, _EMOJI_TAIL, escape_drawtext, _family_rank, FC_LANG,
@@ -188,7 +188,7 @@ __all__ = [
"BEAT_REFRACTORY_S", "BEAT_WINDOW_S", "BEAT_SUPPORT_DIVISOR", "BEAT_ALIGN_DIVISOR",
"BEAT_Z_FLOOR", "BEAT_Z_SPAN",
"_onset_strength", "_pick_onsets", "_autocorrelation_peak", "_grid_score",
- "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw",
+ "default_font_file", "default_output", "DEFAULT_TIMEOUT", "detect_script", "die", "drawtext_boxborderw", "drawtext_center_align",
"_DRAWTEXT_PENDING", "drawtext_shaping", "drawtext_text_opts", "_DRAWTEXT_TMPDIR", "_drawtext_tmpdir",
"dry_run_input_pending", "emit", "emoji_asset_for", "EMOJI_ASSET_HINT", "emoji_clusters",
"emoji_codepoint_name", "_EMOJI_COLOR_FAMILIES", "_emoji_color_font", "emoji_filter_chain",
diff --git a/scripts/_common/drawtext.py b/scripts/_common/drawtext.py
index f9dbca6..0953787 100644
--- a/scripts/_common/drawtext.py
+++ b/scripts/_common/drawtext.py
@@ -97,6 +97,13 @@ def escape_drawtext(text: str) -> str:
)
+def drawtext_center_align() -> str:
+ """`:text_align=C` for a centred drawtext, so each line of a multi-line label is centred on
+ its own. The option arrived in FFmpeg 6.1 (5.x and 6.0 reject it); there the block is still
+ centred as a whole by its x expression, with its lines left-aligned inside it."""
+ return ":text_align=C" if ffmpeg_version() >= (6, 1) else ""
+
+
def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
r"""`textfile=<path>:expansion=none` for drawtext -- the one route that is provably safe for
every character on every build shape this repo uses.
@@ -106,8 +113,11 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
`%{...}` scanner, which is the reason `%` was unsafe (a bare `\%` logs "Stray %" on one build
and fails the whole filter chain on another). With the scanner off, `'`, `%`, `:`, `,`, `[`,
`]`, `;` and `\` all reach the picture verbatim -- 1.15 fixes `overlay.py --text "it's 100%
- done"` losing both characters. Control characters are still stripped: a one-line burnt-in
- label has no use for them.
+ done"` losing both characters. A newline is kept (`\r\n` and `\r` become `\n`): drawtext
+ draws it as a line break, and graphics.py's wrap puts them there on purpose (stripping them
+ ran a wrapped title off both edges of the frame). A tab, vertical tab or form
+ feed becomes a space, as the wrap measures it; other control characters are stripped (that
+ dates from the inline-escape route, where they broke the graph parser).
The file is UTF-8, mode 0600, in a private per-run directory (see _drawtext_tmpdir) that is
removed when the process ends. It is *registered* here and written by run() only if the
@@ -115,7 +125,8 @@ def drawtext_text_opts(text: str, tmpdir: "Optional[str]" = None) -> str:
printed plan therefore names a path that no longer exists once the run is over, which is the
same promise every other temp file in this skill makes.
"""
- cleaned = re.sub(r"[\x00-\x1f\x7f]", "", text or "")
+ cleaned = (text or "").replace("\r\n", "\n").replace("\r", "\n")
+ cleaned = re.sub(r"[\x00-\x08\x0e-\x1f\x7f]", "", re.sub(r"[\t\x0b\x0c]", " ", cleaned))
import hashlib
name = "t_" + hashlib.sha256(cleaned.encode("utf-8")).hexdigest()[:16] + ".txt"
if tmpdir is None:
diff --git a/scripts/_common/text.py b/scripts/_common/text.py
index 42617b0..2501850 100644
--- a/scripts/_common/text.py
+++ b/scripts/_common/text.py
@@ -31,7 +31,7 @@ from _common.emoji import (
)
from _common.drawtext import (
drawtext_boxborderw, SHAPING_SCRIPTS, BIDI_SCRIPTS, _SHAPING_BUILD_CACHE, drawtext_shaping, needs_shaping,
- escape_drawtext, drawtext_text_opts,
+ escape_drawtext, drawtext_text_opts, drawtext_center_align,
)
from _common.wrap import (
ADVANCE_EM, NO_SPACE_SCRIPTS, NO_BOUNDARY_SCRIPTS, LATIN_EM, LEADING_VOWELS, _is_mark, _char_em,
diff --git a/scripts/graphics.py b/scripts/graphics.py
index f6d30db..1c99296 100755
--- a/scripts/graphics.py
+++ b/scripts/graphics.py
@@ -35,7 +35,7 @@ from _platforms import PLATFORMS, PLATFORM_CHOICES, safe_margins_px, resolve as
from _common import (aac_args, add_common, brand_caption_style, script_font_for_text, apply_common, cfr_args,
color_hex, default_font_file, default_output, die, emit, escape_drawtext, escape_filter_path,
ffmpeg_base, info, load_brand, parse_time, probe, run, run_keeping_subtitles, video_args,
- drawtext_boxborderw, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
+ drawtext_boxborderw, drawtext_center_align, X264_PRESETS, time_arg, fmt_secs, STATE, drawtext_text_opts,
LANGUAGE_NAMES, needs_shaping, detect_script, BIDI_SCRIPTS, font_family_of_file, font_family_for_script, has_emoji,
emoji_clusters, emoji_codepoint_name, char_script, emoji_filter_chain, emoji_asset_for, emoji_support, resolve_emoji_assets,
EMOJI_ASSET_HINT, text_width_em, drawtext_shaping, wrap_text, WRAP_MODES,
@@ -356,14 +356,14 @@ def main() -> int:
h2 = int(base * 0.045)
filters.append(f"drawbox=x=0:y=0:w=iw:h=ih:color={ff_color(bg, 0.55)}:t=fill:{en}")
add_text(args.title,
- f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
+ f"drawtext={drawtext_text_opts(args.title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2-{h2 if args.subtitle else 0}:alpha='{fade_a}':{en}",
size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2,
y=H / 2 - (h2 if args.subtitle else 0), outline=max(1.0, h1 / 20.0),
outline_color="000000", start=s, end=e, fade=(300, 300))
filters.append(f"drawbox=x=(iw-{int(base * 0.12)})/2:y=(ih)/2+{h1 // 2 + (0 if args.subtitle else 0)}:w={int(base * 0.12)}:h={max(2, int(base * 0.006))}:color={ff_color(primary)}:t=fill:{en}")
if args.subtitle:
add_text(args.subtitle,
- f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
+ f"drawtext={drawtext_text_opts(args.subtitle)}:{fo}:fontsize={h2}:fontcolor={ff_color(primary)}{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2+{h1 // 2 + int(base * 0.03)}:alpha='{fade_a}':{en}",
size=h2, color=primary, font=ass_font_family(), align=5, x=W / 2,
y=H / 2 + h1 // 2 + int(base * 0.03), outline=max(1.0, h2 / 20.0),
outline_color="000000", start=s, end=e, fade=(300, 300))
@@ -444,8 +444,8 @@ def main() -> int:
filters.append(f"drawbox=x=0:y={y0}:w=iw:h={band_h}:color={ff_color(bg, 0.78)}:t=fill:{hen}")
hook_title = wrapped(args.title, h1)
add_text(hook_title,
- f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}:"
- f"x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
+ f"drawtext={drawtext_text_opts(hook_title)}:{fo}:fontsize={h1}:fontcolor={ff_color(text_c)}"
+ f"{drawtext_center_align()}:x=(w-text_w)/2:y=(h-text_h)/2:{hen}",
size=h1, color=text_c, font=ass_font_family(), align=5, x=W / 2, y=H / 2,
outline=max(1.0, h1 / 20.0), outline_color="000000", start=s, end=he)
filters.append(f"drawbox=x=0:y=0:w='iw*max(0,1-(t-{s:.3f})/{max(0.001, he - s):.3f})':h={bar_h}:"
@@ -466,7 +466,7 @@ def main() -> int:
meme_line = wrapped(text.upper(), fs)
add_text(meme_line,
f"drawtext={drawtext_text_opts(meme_line)}:{fo}:fontsize={fs}:fontcolor={white}:"
- f"borderw={bw}:bordercolor={black}:x=(w-text_w)/2:y={y}:{en}",
+ f"borderw={bw}:bordercolor={black}{drawtext_center_align()}:x=(w-text_w)/2:y={y}:{en}",
size=fs, color="FFFFFF", font=ass_font_family(), bold=True,
align=(8 if y == f"{m_top}" else 2), x=W / 2,
y=(m_top if y == f"{m_top}" else H - m_bottom),
diff --git a/tests/test_picture.py b/tests/test_picture.py
index f89eed2..6185847 100644
--- a/tests/test_picture.py
+++ b/tests/test_picture.py
@@ -2962,6 +2962,82 @@ class ApostropheAndPercentTests(unittest.TestCase):
self.assertIn("it's 100% done", ass)
+class MultiLineDrawtextTests(unittest.TestCase):
+ """graphics.py wrapped a title that did not fit ("WHO SHOWS UP?" at 1.4x on a
+ 1080x1920 frame) and sized its band for two lines, but the drawtext sanitiser stripped the
+ newline, so the title ran off both edges as "WHOSHOWS UP?"."""
+
+ W, H = 1080, 1920
+
+ def test_the_drawn_text_keeps_its_line_breaks_and_loses_other_control_characters(self):
+ import _common
+ for text, drawn in (("A\nB", "A\nB"), ("A\r\nB", "A\nB"), ("A\rB", "A\nB"), ("A\x07B\x00", "AB"),
+ ("tab\there\x0cnow", "tab here now")):
+ opts = _common.drawtext_text_opts(text, tmpdir=str(OUT))
+ path = re.search(r"textfile=(.+?\.txt)", opts.replace("\\", "")).group(1)
+ pending = {os.path.normpath(k): v for k, v in _common._DRAWTEXT_PENDING.items()}
+ self.assertEqual(pending[os.path.normpath(path)], drawn, repr(text))
+
+ def test_centred_lines_are_aligned_where_ffmpeg_can(self):
+ """drawtext's text_align arrived in FFmpeg 6.1; 5.x and 6.0 would reject it, and centre
+ the block as a whole with its lines left-aligned."""
+ import _common
+ saved = _common._FFMPEG_VERSION
+ try:
+ for version, expected in (((5, 1), ""), ((6, 0), ""), ((6, 1), ":text_align=C"), ((9, 0), ":text_align=C")):
+ _common._FFMPEG_VERSION = version
+ self.assertEqual(_common.drawtext_center_align(), expected, version)
+ finally:
+ _common._FFMPEG_VERSION = saved
+
+ def _gray(self, path, at):
+ raw = subprocess.run(["ffmpeg", "-v", "error", "-ss", str(at), "-i", str(path), "-frames:v", "1",
+ "-f", "rawvideo", "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE, check=True).stdout
+ self.assertEqual(len(raw), self.W * self.H)
+ return raw
+
+ def _bands(self, raw, top):
+ """(first row, last row, leftmost column, rightmost column) of each run of rows with
+ bright ink below `top`; a blank gap of more than 8 rows separates two lines."""
+ W = self.W
+ lit = [y for y in range(top, self.H) if sum(1 for v in raw[y * W:(y + 1) * W] if v > 200) > 2]
+ bands = []
+ for y in lit:
+ if bands and y - bands[-1][1] <= 8:
+ bands[-1][1] = y
+ else:
+ bands.append([y, y])
+ out = []
+ for y0, y1 in bands:
+ cols = [x for x in range(W) if any(raw[y * W + x] > 200 for y in range(y0, y1 + 1))]
+ out.append((y0, y1, min(cols), max(cols)))
+ return out
+
+ def test_a_wrapped_hook_title_is_drawn_on_two_centred_lines(self):
+ import _common
+ if not default_font_file("DejaVu Sans") and not default_font_file(""):
+ self.skipTest("no concrete font file on this machine for drawtext")
+ OUT.mkdir(parents=True, exist_ok=True)
+ bg = OUT / "t1_bg.mp4"
+ if not bg.exists():
+ sh("ffmpeg", "-y", "-v", "error", "-f", "lavfi", "-i", f"color=c=0x202020:s={self.W}x{self.H}:r=30:d=4",
+ "-c:v", "libx264", "-pix_fmt", "yuv420p", str(bg))
+ out = OUT / "t1_hook.mp4"
+ script("graphics.py", bg, "--template", "hook", "--title", "WHO SHOWS UP?", "--scale", "1.4",
+ "--duration", "2", "-o", out)
+ top = 40 # below the progress bar along the top edge
+ bands = self._bands(self._gray(out, 1.0), top)
+ self.assertEqual(len(bands), 2, f"two lines of text, got {bands}")
+ widths = [b[3] - b[2] for b in bands]
+ self.assertGreater(abs(widths[0] - widths[1]), 50, "the premise: lines of unequal width")
+ for band in bands:
+ self.assertLess(band[3], self.W - 1, "no line runs off the right edge")
+ self.assertGreater(band[2], 0, "no line runs off the left edge")
+ if _common.ffmpeg_version() >= (6, 1):
+ self.assertAlmostEqual((band[2] + band[3]) / 2, self.W / 2, delta=6, msg=f"line {band} is centred")
+ self.assertEqual(self._bands(self._gray(out, 3.0), top), [], "no text after the card's --duration")
+
+
class WrapReadabilityTests(unittest.TestCase):
"""1.15: no one-character orphan line, and a balanced break for spaced scripts."""