fix(ffmpeg): share literal drawtext escaping

Author: SysAdminDoc

CHANGELOG.md

@@ -145,6 +145,10 @@ record also lives in the git commit messages.
 - `escape_drawtext` documents/requires `expansion=none`: under default
   drawtext expansion a literal `%` cannot be escaped at all ("Stray %") and
   caption text containing `%{...}` would be interpreted as an expression.
+- Caption styles, click/keystroke overlays, tickers, quiz cards, telemetry
+  overlays, callouts, audiograms, brand watermarks, end screens, and guest
+  lower-thirds now use the shared `escape_drawtext()` contract with
+  `expansion=none`.
 - Audio-only export to `.aac` and `.ogg` no longer fails — those containers
   were handed the mp3 encoder; now mapped to `aac` / `libvorbis`.
 - Progress-parsing FFmpeg subprocess now decodes stdout/stderr as UTF-8 with

ROADMAP.md

@@ -23,10 +23,6 @@ history, not here.
   Why: six full :root token redefinitions (12, 4462, 5386, 13215, 15466, 17214), two divergent html.theme-light blocks (16701 vs 17628), three different :focus-visible rules, and a triplicated prefers-reduced-motion block — the effective theme is "whatever the last pass overrode" and ~⅓ of 18k lines is dead weight. Consolidate to one token block per theme; then retokenize the ~340 stray hex literals.
   Where: extension/com.opencut.panel/client/style.css
 
-- [ ] P2 — Drawtext escaping is duplicated and wrong about apostrophes in ~10 modules
-  Why: the local _escape_drawtext copies use \' inside single quotes (apostrophes silently dropped, graph can be mangled); helpers.escape_drawtext (ffmpeg-verified, expansion=none contract) should replace them.
-  Where: opencut/core/caption_styles.py:365-372, click_overlay.py, news_ticker.py, quiz_overlay.py, telemetry_overlay.py, callout_gen.py, audiogram.py, brand_kit.py, end_screen.py, guest_compilation.py
-
 ## P3 — Lower-severity correctness, UX, packaging
 
 - [ ] P3 — Inno installer writes HKCU/PlayerDebugMode in the elevated user's hive

opencut/core/audiogram.py

@@ -13,7 +13,7 @@
 import subprocess
 from typing import Callable, Optional
 
-from opencut.helpers import get_ffmpeg_path, get_ffprobe_path, run_ffmpeg
+from opencut.helpers import escape_drawtext, get_ffmpeg_path, get_ffprobe_path, run_ffmpeg
 
 logger = logging.getLogger("opencut")
 
@@ -47,12 +47,7 @@ def _get_audio_duration(filepath: str) -> float:
 
 def _escape_ffmpeg_text(text: str) -> str:
     """Escape special characters for FFmpeg drawtext filter."""
-    # FFmpeg drawtext requires escaping these characters
-    text = text.replace("\\", "\\\\")
-    text = text.replace(":", "\\:")
-    text = text.replace("'", "\\'")
-    text = text.replace("%", "%%")
-    return text
+    return escape_drawtext(text)
 
 
 def generate_audiogram(
@@ -211,7 +206,7 @@ def generate_audiogram(
         font_size = max(24, width // 25)
         title_y = height // 20
         fc_parts.append(
-            f"{current_label}drawtext=text='{escaped}':"
+            f"{current_label}drawtext=expansion=none:text='{escaped}':"
             f"fontsize={font_size}:fontcolor=white:x=(w-text_w)/2:y={title_y}:"
             f"shadowcolor=black@0.6:shadowx=2:shadowy=2[titled]"
         )

opencut/core/brand_kit.py

@@ -13,6 +13,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     get_video_info,
     output_path,
     run_ffmpeg,
@@ -300,12 +301,12 @@ def auto_correct_brand(
         color = _hex_to_ffmpeg_color(brand_kit.primary_color)
         margin = int(info["width"] * brand_kit.safe_zone_margin)
         fontsize = max(12, int(info["height"] * 0.02))
-        escaped_text = brand_kit.watermark_text.replace("'", "'\\''")
+        escaped_text = escape_drawtext(brand_kit.watermark_text)
 
         if filter_parts:
             # Chain onto previous filter output
             wm_filter = (
-                f"drawtext=text='{escaped_text}'"
+                f"drawtext=expansion=none:text='{escaped_text}'"
                 f":fontsize={fontsize}"
                 f":fontcolor={color}@0.3"
                 f":x=w-tw-{margin}:y=h-th-{margin}"
@@ -314,7 +315,7 @@ def auto_correct_brand(
             filter_parts[-1] = last + f"[branded];[branded]{wm_filter}"
         else:
             filter_parts.append(
-                f"[0:v]drawtext=text='{escaped_text}'"
+                f"[0:v]drawtext=expansion=none:text='{escaped_text}'"
                 f":fontsize={fontsize}"
                 f":fontcolor={color}@0.3"
                 f":x=w-tw-{margin}:y=h-th-{margin}"

opencut/core/callout_gen.py

@@ -14,6 +14,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     get_video_info,
     output_path,
     run_ffmpeg,
@@ -109,11 +110,7 @@ def to_dict(self) -> dict:
 
 def _escape_text(text: str) -> str:
     """Escape special characters for FFmpeg drawtext."""
-    text = text.replace("\\", "\\\\\\\\")
-    text = text.replace(":", "\\:")
-    text = text.replace("'", "\\'")
-    text = text.replace("%", "%%")
-    return text
+    return escape_drawtext(text)
 
 
 # ---------------------------------------------------------------------------
@@ -183,7 +180,7 @@ def _build_callout_filter(ann: Annotation, video_w: int, video_h: int) -> List[s
         y_pos = "h-th-40"
 
     filters.append(
-        f"drawtext=text='{escaped}'"
+        f"drawtext=expansion=none:text='{escaped}'"
         f":fontsize={ann.font_size}:fontcolor={ann.color}"
         f":x={x_pos}:y={y_pos}"
         f":box=1:boxcolor=black@0.6:boxborderw=6"
@@ -214,7 +211,7 @@ def _build_step_filter(ann: Annotation, video_w: int, video_h: int) -> List[str]
         f":color={ann.color}@0.9:t=fill:enable='{enable}'"
     )
     filters.append(
-        f"drawtext=text='{num_text}'"
+        f"drawtext=expansion=none:text='{num_text}'"
         f":fontsize=20:fontcolor=black"
         f":x={badge_x}+8:y={badge_y}+6"
         f":enable='{enable}'"
@@ -226,7 +223,7 @@ def _build_step_filter(ann: Annotation, video_w: int, video_h: int) -> List[str]
         text_x = f"{badge_x}+40"
         text_y = f"{badge_y}+4"
         filters.append(
-            f"drawtext=text='{escaped}'"
+            f"drawtext=expansion=none:text='{escaped}'"
             f":fontsize={ann.font_size}:fontcolor={ann.color}"
             f":x={text_x}:y={text_y}"
             f":box=1:boxcolor=black@0.6:boxborderw=4"

opencut/core/caption_styles.py

@@ -12,7 +12,7 @@
 from dataclasses import asdict, dataclass, field
 from typing import Callable, Dict, List, Optional
 
-from opencut.helpers import get_ffmpeg_path, output_path, run_ffmpeg
+from opencut.helpers import escape_drawtext, get_ffmpeg_path, output_path, run_ffmpeg
 
 logger = logging.getLogger("opencut")
 
@@ -364,12 +364,7 @@ def _position_y(position: str, height: int, font_size: int) -> int:
 
 def _escape_drawtext(text: str) -> str:
     """Escape text for FFmpeg drawtext filter."""
-    return (
-        text.replace("\\", "\\\\")
-        .replace("'", "\\'")
-        .replace(":", "\\:")
-        .replace("%", "%%")
-    )
+    return escape_drawtext(text)
 
 
 def _build_drawtext_filter(
@@ -388,7 +383,7 @@ def _build_drawtext_filter(
     bg_color = style.colors.get("background", "")
 
     parts = [
-        f"drawtext=text='{escaped}'",
+        f"drawtext=expansion=none:text='{escaped}'",
         "fontfile=''",
         f"fontsize={style.font_size}",
         f"fontcolor={text_color}",
@@ -497,7 +492,7 @@ def generate_style_preview(
     escaped = _escape_drawtext(sample_text)
 
     dt_parts = [
-        f"drawtext=text='{escaped}'",
+        f"drawtext=expansion=none:text='{escaped}'",
         f"fontsize={min(style.font_size, 36)}",
         f"fontcolor={text_color}",
         f"shadowcolor={shadow_color}",

opencut/core/click_overlay.py

@@ -15,6 +15,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     get_video_info,
     output_path,
     run_ffmpeg,
@@ -364,12 +365,7 @@ def render_click_overlay(
 
 def _escape_drawtext(text: str) -> str:
     """Escape special characters for FFmpeg drawtext filter."""
-    # FFmpeg drawtext requires escaping of : ; ' \ and %
-    text = text.replace("\\", "\\\\\\\\")
-    text = text.replace(":", "\\:")
-    text = text.replace("'", "\\'")
-    text = text.replace("%", "%%")
-    return text
+    return escape_drawtext(text)
 
 
 def render_keystroke_overlay(
@@ -451,7 +447,7 @@ def render_keystroke_overlay(
 
         # Background box + text
         dt_filter = (
-            f"drawtext=text='{escaped_keys}'"
+            f"drawtext=expansion=none:text='{escaped_keys}'"
             f":fontsize={font_size}"
             f":fontcolor={font_color}"
             f":x={x_expr}:y={y_expr}"

opencut/core/end_screen.py

@@ -18,6 +18,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     run_ffmpeg,
 )
 
@@ -178,7 +179,7 @@ def _build_end_screen_filter(
 
         # Get custom text from data
         custom_text = data.get(f"element_{i}_text", elem.label)
-        safe_text = custom_text.replace("'", "\\'").replace(":", "\\:")
+        safe_text = escape_drawtext(custom_text)
 
         out_label = f"e{i}"
 
@@ -188,7 +189,7 @@ def _build_end_screen_filter(
             parts.append(
                 f"[{prev_label}]drawbox=x={ex}:y={ey}:w={ew}:h={eh}"
                 f":color=0x{accent}@0.9:t=fill,"
-                f"drawtext=text='{safe_text}'"
+                f"drawtext=expansion=none:text='{safe_text}'"
                 f":fontsize={font_size}:fontcolor=0x{text_color}"
                 f":x={ex}+({ew}-text_w)/2:y={ey}+({eh}-text_h)/2"
                 f"[{out_label}]"
@@ -201,7 +202,7 @@ def _build_end_screen_filter(
                 f":color=0x333333@0.8:t=fill,"
                 f"drawbox=x={ex}:y={ey}:w={ew}:h={eh}"
                 f":color=0x{accent}@0.6:t=3,"
-                f"drawtext=text='{safe_text}'"
+                f"drawtext=expansion=none:text='{safe_text}'"
                 f":fontsize={font_size}:fontcolor=0x{text_color}@0.8"
                 f":x={ex}+({ew}-text_w)/2:y={ey}+({eh}-text_h)/2"
                 f"[{out_label}]"
@@ -212,7 +213,7 @@ def _build_end_screen_filter(
             parts.append(
                 f"[{prev_label}]drawbox=x={ex}:y={ey}:w={ew}:h={eh}"
                 f":color=0x{accent}@0.4:t=fill,"
-                f"drawtext=text='{safe_text}'"
+                f"drawtext=expansion=none:text='{safe_text}'"
                 f":fontsize={font_size}:fontcolor=0x{text_color}"
                 f":x={ex}+({ew}-text_w)/2:y={ey}+({eh}-text_h)/2"
                 f"[{out_label}]"
@@ -221,7 +222,7 @@ def _build_end_screen_filter(
             # Text element
             font_size = max(16, eh // 2)
             parts.append(
-                f"[{prev_label}]drawtext=text='{safe_text}'"
+                f"[{prev_label}]drawtext=expansion=none:text='{safe_text}'"
                 f":fontsize={font_size}:fontcolor=0x{text_color}"
                 f":x={ex}+({ew}-text_w)/2:y={ey}+({eh}-text_h)/2"
                 f"[{out_label}]"

opencut/core/guest_compilation.py

@@ -14,6 +14,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     get_ffmpeg_path,
     get_video_info,
     output_path,
@@ -209,7 +210,7 @@ def generate_name_card(
         x_expr = str(margin)
         y_expr = f"h-{margin}-th"
 
-    escaped_name = name.replace("'", "'\\''").replace(":", "\\:")
+    escaped_name = escape_drawtext(name)
 
     # Build drawtext with background box and fade
     fade_in_expr = f"if(lt(t,{style.fade_in}),t/{style.fade_in},1)"
@@ -218,7 +219,7 @@ def generate_name_card(
     alpha_expr = f"min({fade_in_expr},{fade_out_expr})"
 
     drawtext = (
-        f"drawtext=text='{escaped_name}'"
+        f"drawtext=expansion=none:text='{escaped_name}'"
         f":fontsize={fontsize}"
         f":fontcolor={style.font_color}"
         f":box=1:boxcolor={style.bg_color}:boxborderw={padding}"
@@ -327,7 +328,7 @@ def process_single_message(
         card_dur = name_style.display_duration
         fade_in = name_style.fade_in
         fade_out = name_style.fade_out
-        escaped_name = guest_name.replace("'", "'\\''").replace(":", "\\:")
+        escaped_name = escape_drawtext(guest_name)
 
         # Show name card for first N seconds with fade
         enable_expr = f"between(t,0,{card_dur})"
@@ -343,7 +344,7 @@ def process_single_message(
         y_expr = f"h-{margin}-th"
 
         vf_parts.append(
-            f"drawtext=text='{escaped_name}'"
+            f"drawtext=expansion=none:text='{escaped_name}'"
             f":fontsize={fontsize}"
             f":fontcolor={name_style.font_color}"
             f":box=1:boxcolor={name_style.bg_color}:boxborderw={padding}"

opencut/core/news_ticker.py

@@ -17,6 +17,7 @@
 
 from opencut.helpers import (
     FFmpegCmd,
+    escape_drawtext,
     get_video_info,
     output_path,
     run_ffmpeg,
@@ -127,13 +128,7 @@ def _load_ticker_text(
 
 def _escape_drawtext(text: str) -> str:
     """Escape text for FFmpeg drawtext filter."""
-    # FFmpeg drawtext special characters
-    text = text.replace("\\", "\\\\")
-    text = text.replace("'", "\\'")
-    text = text.replace(":", "\\:")
-    text = text.replace("%", "%%")
-    text = text.replace("\n", " ")
-    return text
+    return escape_drawtext(str(text).replace("\n", " "))
 
 
 # ---------------------------------------------------------------------------
@@ -235,7 +230,7 @@ def create_ticker(
     # Background bar + scrolling text
     vf = (
         f"drawbox=x=0:y={bar_y}:w=iw:h={bar_h}:color={bg_color}:t=fill,"
-        f"drawtext=text='{safe_text}'"
+        f"drawtext=expansion=none:text='{safe_text}'"
         f":fontsize={font_size}:fontcolor={font_color}"
         f":x='{x_expr}':y={text_y}"
     )
@@ -341,7 +336,7 @@ def create_ticker_overlay(
     # Generate with color source + drawtext
     fc = (
         f"color=c=0x{bg_color}:s={width}x{height}:d={duration},"
-        f"drawtext=text='{safe_text}'"
+        f"drawtext=expansion=none:text='{safe_text}'"
         f":fontsize={font_size}:fontcolor={font_color}"
         f":x='{x_expr}':y={text_y}"
         f"[out]"