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
#!/usr/bin/env python3
"""Render a set of positioned text elements as an ASS file, so libass draws them instead of
drawtext.
Private helper (leading underscore): not a tool, no TOOL_META entry, no contract or MCP surface.
Why it exists (1.15): drawtext cannot SHAPE. On a build with fribidi it gets bidi and Arabic
joining right, but it never reorders or re-clusters -- Devanagari matras come out in logical
order and Thai/Lao marks stack wrongly -- because drawtext does not use harfbuzz even in an
--enable-libharfbuzz build. libass does. `graphics.py` keeps computing exactly the geometry it
computed before; only the renderer changes, and only for text that needs it.
Each element is a dict:
{"text", "x", "y", "size", "color", "font", "bold", "outline", "outline_color",
"shadow", "align", "start", "end", "fade", "move", "scale_t", "box", "box_color"}
`align` is the ASS numpad alignment of (x, y) -- 7 is top-left, 5 centre, 2 bottom-centre -- so
a centred title needs no text-width measurement at all. `move` is (x1, y1, x2, y2, t1, t2) in
milliseconds relative to the line's own start; `fade` is (in_ms, out_ms); `scale_t` is
(t1_ms, t2_ms, percent) for a pop.
"""
from typing import Any, Dict, List, Optional, Sequence
# One sentinel character stands in drawn text where an emoji was, so the placeholder is inserted
# AFTER the brace-stripping that keeps caller-supplied text from injecting override commands.
EMOJI_SENTINEL = "\ue000"
def emoji_placeholder(box_px: float) -> str:
r"""The ASS override that reserves exactly `box_px` of advance and draws nothing.
Measured, not assumed (1.15 spec, open question 2). U+2588 FULL BLOCK is NOT 1.0 em: its
advance measured 0.83 em in FreeSans, 0.79 in WenQuanYi Zen Hei and 0.66 in DejaVu Sans,
IPAPGothic and Loma, so a block reserves the wrong gap in every face this repo resolves.
The spec's fallback, alpha-hidden figure spaces (U+2007), measured 0.46-0.55 em and only
quantises the gap to half an em. What IS exact in all five faces is that same alpha-hidden
whitespace carried by `\fsp` (letter spacing, in script pixels) on a zero-width space: the
next glyph starts exactly `box_px` later, with no font dependence at all (verified by render,
including inside a karaoke run, where the placeholder is its own zero-duration \kf segment).
`\r` restores the style for the rest of the line.
"""
return "{\\alpha&HFF&\\fsp%.1f}\u200b{\\r}" % box_px
def ass_time(sec: float) -> str:
cs = int(round(max(0.0, sec) * 100))
h, rem = divmod(cs, 360000)
m, rem = divmod(rem, 6000)
s, cs = divmod(rem, 100)
return f"{h}:{m:02d}:{s:02d}.{cs:02d}"
def ass_color(hex_rgb: str, alpha: int = 0) -> str:
h = str(hex_rgb).lstrip("#")
if len(h) != 6:
raise ValueError(f"colour must be RRGGBB hex, got '{hex_rgb}'")
return f"&H{alpha:02X}{h[4:6]}{h[2:4]}{h[0:2]}".upper()
def ass_field(name: str) -> str:
"""A font name or style name for a comma-delimited ASS field: no escape mechanism exists, so
the delimiters are dropped (the same call caption.py's ass_font_name() makes)."""
out = "".join(ch for ch in str(name or "") if ord(ch) >= 0x20 and ch not in ",:\\'")
return out or "Sans"
# After a literal backslash, these characters would start an ASS sequence libass acts on
# (\N, \n, \h) or an override block (\{ is an escape, so \\{ is ambiguous). A zero-width space
# between the two breaks the sequence without changing what the reader sees.
_ASS_AFTER_BACKSLASH = frozenset("Nnh{}")
def ass_escape(text: str) -> str:
"""Element text for a Dialogue, with every character the user typed still in it.
`{` and `}` would open and close an override block -- real style and animation commands
(\\pos, \\t, \\fscx), so caller-supplied text containing them could reposition, rescale or
recolour itself and everything after it. libass has escapes for exactly this (`\\{`, `\\}`),
so 1.15.0 escapes them instead of deleting them: `A {b} c \\ d` now reaches the picture
verbatim through the ASS route, the way it already did through drawtext. A literal backslash
needs no escape of its own in libass (`\\\\` renders as TWO backslashes, it is not an escape);
only a backslash immediately before one of _ASS_AFTER_BACKSLASH is ambiguous, and a
zero-width space parts them.
"""
s = str(text or "")
out = []
for i, ch in enumerate(s):
if ch == "{":
out.append("\\{")
elif ch == "}":
out.append("\\}")
elif ch == "\n":
out.append("\\N")
elif ch == "\\":
out.append("\\\u200b" if (i + 1 < len(s) and s[i + 1] in _ASS_AFTER_BACKSLASH) else "\\")
else:
out.append(ch)
return "".join(out)
def ass_text(text: str) -> str:
"""Back-compatible name for ass_escape()."""
return ass_escape(text)
def text_overlay_ass(elements: Sequence[Dict[str, Any]], *, play_w: int, play_h: int,
path: str, fonts_dir: Optional[str] = None) -> str:
"""Write `elements` as an ASS file at `path` and return the path."""
header = [
"[Script Info]", "ScriptType: v4.00+", f"PlayResX: {play_w}", f"PlayResY: {play_h}",
# YCbCr Matrix: None -- the colours are RGB, to be put in the video's own matrix: FFmpeg 8.x's
# ass filter reads an absent header as BT.601 whatever the picture is tagged (drawn_chain)
"WrapStyle: 2", "ScaledBorderAndShadow: yes", "YCbCr Matrix: None", "",
"[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",
]
events: List[str] = []
for i, el in enumerate(elements):
name = f"E{i}"
colour = ass_color(el.get("color", "FFFFFF"))
outline_colour = ass_color(el.get("outline_color", "000000"))
box = bool(el.get("box"))
back = ass_color(el.get("box_color", el.get("outline_color", "000000")),
int(el.get("box_alpha", 0)))
header.append(
f"Style: {name},{ass_field(el.get('font') or 'Sans')},{int(round(el['size']))},"
f"{colour},{colour},{outline_colour},{back},{-1 if el.get('bold') else 0},0,0,0,"
f"100,100,0,0,{3 if box else 1},{float(el.get('outline', 0)):.1f},"
f"{float(el.get('shadow', 0)):.1f},{int(el.get('align', 7))},0,0,0,1")
tags = [f"\\an{int(el.get('align', 7))}"]
move = el.get("move")
if move:
x1, y1, x2, y2, t1, t2 = move
tags.append(f"\\move({x1:.0f},{y1:.0f},{x2:.0f},{y2:.0f},{t1:.0f},{t2:.0f})")
else:
tags.append(f"\\pos({el['x']:.0f},{el['y']:.0f})")
fade = el.get("fade")
if fade:
tags.append(f"\\fad({fade[0]:.0f},{fade[1]:.0f})")
scale_t = el.get("scale_t")
if scale_t:
t1, t2, pct = scale_t
tags.append(f"\\fscx{pct:.0f}\\fscy{pct:.0f}\\t({t1:.0f},{t2:.0f},\\fscx100\\fscy100)")
events.append(
f"Dialogue: 0,{ass_time(el['start'])},{ass_time(el['end'])},{name},,0,0,0,,"
"{" + "".join(tags) + "}" + ass_text(el["text"]).replace(
EMOJI_SENTINEL, emoji_placeholder(el.get("box_px") or el["size"])))
body = "\n".join(header + ["", "[Events]",
"Format: Layer, Start, End, Style, Name, MarginL, MarginR, "
"MarginV, Effect, Text"] + events) + "\n"
with open(path, "w", encoding="utf-8-sig") as fh:
fh.write(body)
return path