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
"""Emoji: cluster detection (ZWJ sequences, keycaps, flags, skin tones), the PNG asset lookup,
the per-machine support probe and the overlay filter chain that composites the assets.
Split out of _common.text in the refactor after 1.17.3; every body is byte-identical.
"""
from __future__ import annotations
import os
import shutil
import subprocess
from typing import Any, Dict, List, Tuple, Optional
from _common.decision import escape_filter_path
from _common.emit import die
from _common.runner import ffmpeg_exe
# --------------------------------------------------------------------------- emoji (1.15)
# Emoji are orthogonal to the writing system: "やった 🎉" is Japanese AND emoji. They are detected
# separately from detect_script() so a cue's font resolution is still decided by its letters.
EMOJI_RANGES = (
(0x1F300, 0x1FAFF), # symbols & pictographs, supplemental, extended-A
(0x1F000, 0x1F0FF), # mahjong/domino/playing cards
(0x2600, 0x27BF), # misc symbols + dingbats
(0x2B00, 0x2BFF), # misc symbols and arrows
(0xFE0F, 0xFE0F), # VS16 (emoji presentation selector)
(0x1F1E6, 0x1F1FF), # regional indicators (flags)
(0x20E3, 0x20E3), # combining enclosing keycap
(0x1F3FB, 0x1F3FF), # skin-tone modifiers
)
# U+200D ZWJ is deliberately NOT in EMOJI_RANGES: it is ordinary Indic/Persian orthography
# (क्ष is ka + virama + ZWJ + ssa) and only becomes emoji glue *between two emoji bases*.
# Characters that never START a cluster: they bind to whatever stands before them.
_EMOJI_TAIL = frozenset({0x200D, 0xFE0F, 0x20E3} | set(range(0x1F3FB, 0x1F400)))
_EMOJI_REGIONAL = range(0x1F1E6, 0x1F200)
_ZWJ = 0x200D
_VS15 = 0xFE0E # text-presentation selector: "draw this as a character, not as an emoji"
_VS16 = 0xFE0F
_KEYCAP = 0x20E3
_KEYCAP_BASES = frozenset("0123456789#*")
def _is_emoji_char(ch: str) -> bool:
cp = ord(ch)
return any(lo <= cp <= hi for lo, hi in EMOJI_RANGES)
def _is_emoji_base(ch: str) -> bool:
"""Can this character START an emoji cluster? Pictographs and regional indicators can;
the joiners and modifiers (ZWJ, VS16, keycap, skin tone) never can -- they only bind to an
emoji base that already stands before them. Without this, a ZWJ or a VS16 sitting after an
ordinary letter turned that letter into "an emoji" and the PNG route replaced it with a gap."""
return ord(ch) not in _EMOJI_TAIL and _is_emoji_char(ch)
def emoji_clusters(text: str) -> "List[Tuple[int, str]]":
"""(index in `text`, cluster) for every emoji in it, ZWJ sequences, VS16, keycaps, flag pairs
and skin-tone modifiers kept together -- 👩💻 is one cluster, not three, and 1️⃣ starts at the
digit even though the digit is not itself an emoji character.
A cluster can only START at an emoji base (a pictograph, a regional indicator) or at a keycap
base (`0-9 # *`) that is actually followed by U+20E3. A ZWJ is glue *inside* a cluster, never
a starter and never a tail on its own: `क्ष` (Hindi ka + virama + ZWJ + ssa) and `abcdef`
contain no emoji. A base explicitly marked with U+FE0E (VS15, text presentation) is likewise
not an emoji -- the author asked for the character, not the picture.
"""
out: "List[Tuple[int, str]]" = []
i = 0
n = len(text or "")
while i < n:
ch = text[i]
start = i
if _is_emoji_base(ch):
j = i + 1
if j < n and ord(text[j]) == _VS15: # text presentation requested: not an emoji
i = j + 1
continue
elif ch in _KEYCAP_BASES:
j = i + 1
if j < n and ord(text[j]) == _VS16:
j += 1
if not (j < n and ord(text[j]) == _KEYCAP):
i += 1
continue
j += 1
else:
i += 1
continue
# extend: modifiers bind rightwards, a ZWJ only when a real emoji base follows it
while j < n:
cp = ord(text[j])
if cp in (_VS16, _KEYCAP) or 0x1F3FB <= cp <= 0x1F3FF:
j += 1
continue
if cp == _ZWJ and j + 1 < n and _is_emoji_base(text[j + 1]):
j += 2
continue
if (j == start + 1 and ord(ch) in _EMOJI_REGIONAL and cp in _EMOJI_REGIONAL):
j += 1
continue
break
out.append((start, text[start:j]))
i = j
return out
def has_emoji(text: str) -> bool:
return bool(emoji_clusters(text or ""))
def emoji_codepoint_name(cluster: str) -> str:
"""The asset filename stem for a cluster: lowercase hex code points joined by '-', the
Twemoji/Noto convention (1f389, 1f469-200d-1f4bb, 1f1ef-1f1f5)."""
return "-".join(f"{ord(c):x}" for c in cluster)
def _emoji_name_candidates(cluster: str) -> "List[str]":
"""Asset stems to try, most specific first: exact, without VS16, without skin tone, the ZWJ
sequence reduced to its first code point, the bare base."""
cps = [ord(c) for c in cluster]
names = [emoji_codepoint_name(cluster)]
def add(seq):
name = "-".join(f"{c:x}" for c in seq)
if name and name not in names:
names.append(name)
add([c for c in cps if c != 0xFE0F])
add([c for c in cps if c != 0xFE0F and not (0x1F3FB <= c <= 0x1F3FF)])
if 0x200D in cps:
add([cps[0]])
add([cps[0]])
return names
def emoji_asset_for(cluster: str, assets_dir: "Optional[str]") -> "Optional[str]":
"""The PNG for `cluster` under `assets_dir`, or None when nothing matches."""
if not assets_dir or not os.path.isdir(assets_dir):
return None
for name in _emoji_name_candidates(cluster):
for ext in (".png", ".PNG"):
candidate = os.path.join(assets_dir, name + ext)
if os.path.isfile(candidate):
return candidate
return None
EMOJI_ASSET_HINT = (
"point --emoji-assets at a directory of PNGs named by code point (1f389.png): "
"twemoji/assets/72x72 (Twemoji, CC-BY 4.0) or noto-emoji/png/128 (Noto Emoji, OFL/Apache-2.0) "
"are the two people already have. The skill has no network at runtime, so the assets must "
"already exist on this machine -- nothing is ever downloaded")
_EMOJI_COLOR_FAMILIES = ("Noto Color Emoji", "Apple Color Emoji", "Segoe UI Emoji")
def _fc_list_path(line: str) -> str:
"""The file from one `fc-list ... file` line.
fontconfig prints `<file>: <families>`. The separator is a colon followed by a space.
A Windows drive letter is `C:` followed by a backslash, so splitting on the first colon
yields `C` and the font is reported missing.
"""
if ": " in line:
return line.partition(": ")[0].strip()
return line.strip().rstrip(":")
_EMOJI_SUPPORT_CACHE: "Dict[Tuple[Optional[str], bool], Dict[str, Any]]" = {}
def _emoji_color_font() -> "Tuple[Optional[str], Optional[str], bool]":
"""(family, file, fontconfig_answered) for the first installed colour emoji family."""
exe = shutil.which("fc-list")
if not exe:
return None, None, False
for family in _EMOJI_COLOR_FAMILIES:
try:
proc = subprocess.run([exe, f":family={family}", "file"], stdout=subprocess.PIPE,
stderr=subprocess.DEVNULL, text=True, encoding="utf-8", errors="replace", timeout=10)
except (subprocess.TimeoutExpired, OSError):
return None, None, False
if proc.returncode != 0:
return None, None, False
for line in proc.stdout.splitlines():
path = _fc_list_path(line)
if path and os.path.exists(path):
return family, path, True
return None, None, True
def _libass_color_probe() -> "Optional[bool]":
"""Does THIS ffmpeg render an emoji in colour through libass? Answered by a render, never by
the font listing: Noto Color Emoji installs happily on builds whose freetype/libass has no
colour-bitmap path at all, and those render a monochrome outline instead (measured). ~80 ms.
None means the probe could not be run (no ffmpeg, a failure) -- unknown, not false."""
exe = ffmpeg_exe("ffmpeg")[0]
if not exe:
return None
import tempfile
with tempfile.TemporaryDirectory() as td:
srt = os.path.join(td, "e.srt")
with open(srt, "w", encoding="utf-8") as fh:
fh.write("1\n00:00:00,000 --> 00:00:01,000\n\U0001F389\n")
try:
proc = subprocess.run(
[exe, "-hide_banner", "-loglevel", "error", "-f", "lavfi",
"-i", "color=c=black:s=64x64:d=0.04",
"-vf", "subtitles=" + escape_filter_path(srt, bind=False), "-frames:v", "1",
"-f", "rawvideo", "-pix_fmt", "rgb24", "-"],
stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=20)
except (subprocess.TimeoutExpired, OSError):
return None
if proc.returncode != 0 or len(proc.stdout) < 64 * 64 * 3:
return None
data = proc.stdout
for i in range(0, 64 * 64 * 3, 3):
r, g, b = data[i], data[i + 1], data[i + 2]
if max(r, g, b) - min(r, g, b) > 40:
return True
return False
def emoji_support(assets: "Optional[str]" = None, probe: bool = True) -> "Dict[str, Any]":
"""What this machine can actually do with emoji, cached per process.
`mode` is `color` when a render probe proves libass draws colour, else `png` when an assets
directory resolves, else `mono` when some installed face has a glyph at all, else `none`.
An installed colour emoji font proves nothing on its own -- that is why `libass_color` comes
from a render (see references/gotchas.md#emoji). `probe=False` (`contract --json --static`, and every
static/JSON-only path) skips the render entirely and leaves `libass_color` unknown.
"""
key = (assets or None, bool(probe))
if key in _EMOJI_SUPPORT_CACHE:
return dict(_EMOJI_SUPPORT_CACHE[key])
family, file, fc_answered = _emoji_color_font()
libass_color = _libass_color_probe() if probe else None
assets_dir = assets if (assets and os.path.isdir(assets)) else None
if libass_color:
mode = "color"
elif assets_dir:
mode = "png"
elif family:
mode = "mono"
elif not fc_answered:
# No fontconfig to ask (a static ffmpeg build, a bare container): the PNG path needs none,
# so the honest answer is png-or-none, never "none because fc-list is missing".
mode = "none"
else:
mode = "none"
if not fc_answered:
detail = "no fontconfig on this machine; the PNG overlay path needs none"
elif libass_color:
detail = f"{family or 'an installed face'} renders in colour through libass on this ffmpeg"
elif family and libass_color is False:
detail = f"{family} installed but libass renders it monochrome on this build"
elif family and libass_color is None:
detail = f"{family} installed; the colour render probe was not run"
elif assets_dir:
detail = "no colour emoji family installed; using the PNG assets directory"
else:
detail = "no colour emoji family installed and no --emoji-assets directory"
result = {"mode": mode, "color_font": family, "color_font_file": file,
"libass_color": libass_color, "assets": assets_dir,
"detail": detail, "fix": EMOJI_ASSET_HINT}
_EMOJI_SUPPORT_CACHE[key] = result
return dict(result)
def resolve_emoji_assets(flag: "Optional[str]" = None, project: "Optional[str]" = None,
brand: "Optional[dict]" = None) -> "Optional[str]":
"""--emoji-assets DIR, else the project key, else brand.json, else FFMPEG_SKILL_EMOJI_ASSETS.
A directory that was named but does not exist is a failed job, never a silent downgrade."""
brand = brand or {}
styles = (brand.get("styles") or {}).get("caption") or {}
for value, where in ((flag, "--emoji-assets"), (project, "the project's text.emoji_assets"),
(styles.get("emoji_assets"), "brand.json styles.caption.emoji_assets"),
(brand.get("emoji_assets"), "brand.json emoji_assets"),
(os.environ.get("FFMPEG_SKILL_EMOJI_ASSETS"), "FFMPEG_SKILL_EMOJI_ASSETS")):
if not value:
continue
if not os.path.isdir(str(value)):
die(f"{where}: {value} is not a readable directory -- {EMOJI_ASSET_HINT}", kind="input")
return str(value)
return None
def emoji_filter_chain(plan, base_label, out_label, first_input=1, to_yuv="", base_chain=""):
"""(chains, inputs) that composite the planned PNGs on top of `base_label`.
`inputs` is a list of argv fragments, each ending in the asset path, to be appended to the
ffmpeg command in order (an overlay that fades needs `-loop 1` on its input so the still has
a timeline the fade filter can move along; one that does not is a plain `-i`).
`to_yuv` ends each PNG's chain: the caller's rgb_chain_to_bt709(meta), so the RGBA asset is
converted to the BT.709 the output is tagged with instead of by overlay's BT.601 default;
`base_chain` (label_chain(meta, meta): an untagged source's BT.709 label) goes in front of
the first overlay, so 7.1+ does not convert the two pictures to one another.
"""
overlays = plan.get("overlays") or []
if not overlays:
return [], []
# Group by everything that makes two uses of the same PNG a different STREAM: the fade is
# expressed in the cue's own timeline, so two cues cannot share one faded input.
def _key(o):
fades = (round(float(o.get("fade_in") or 0.0), 3), round(float(o.get("fade_out") or 0.0), 3))
window = (round(float(o["start"]), 3), round(float(o["end"]), 3)) if any(fades) else (None, None)
return (o["asset"], o["box"]) + fades + window
groups: "List[Tuple]" = []
for o in overlays:
if _key(o) not in groups:
groups.append(_key(o))
chains: List[str] = []
inputs: "List[List[str]]" = []
pads: "Dict[Tuple, List[str]]" = {}
for k, key in enumerate(groups):
asset, box, fin, fout, gstart, gend = key
uses = [o for o in overlays if _key(o) == key]
idx = first_input + k
labels = [f"e{k}_{j}" for j in range(len(uses))]
chain = f"[{idx}:v]format=rgba,scale={box}:{box}"
if fin or fout:
# -loop 1 gives the still an advancing timeline on the SAME clock as the main video,
# so the fade times below are the cue's own seconds. The emoji then appears and
# leaves with the text instead of popping in against a fading line.
# -t bounds the loop at the cue's end: an unbounded looped still never EOFs and the
# whole encode hangs (overlay keeps pulling from it after the main video is done).
inputs.append(["-loop", "1", "-t", f"{gend:.3f}", "-i", asset])
if fin:
chain += f",fade=t=in:st={gstart:.3f}:d={fin:.3f}:alpha=1"
if fout:
chain += f",fade=t=out:st={max(gstart, gend - fout):.3f}:d={fout:.3f}:alpha=1"
else:
inputs.append(["-i", asset])
chain += to_yuv
if len(labels) > 1:
chain += f",split={len(labels)}"
chains.append(chain + "".join(f"[{l}]" for l in labels))
pads[key] = labels
cur = base_label
if base_chain:
chains.append(f"[{cur}]{base_chain}null[ebase]")
cur = "ebase"
remaining = {key: list(v) for key, v in pads.items()}
for j, o in enumerate(overlays):
label = remaining[_key(o)].pop(0)
nxt = out_label if j == len(overlays) - 1 else f"eov{j}"
x = o["x"]
x = f"'{x}'" if isinstance(x, str) else x
# No eof_action=pass here: a PNG input is a SINGLE frame at pts 0, and eof_action=pass
# switches off overlay's default "hold the last frame of the secondary input", so the
# asset would be composited on frame 0 only and vanish for the rest of the cue (that is
# exactly what shipped first). eof_action=repeat (the default) holds the still for the
# whole timeline; enable= is what confines it to the cue's window.
chains.append(f"[{cur}][{label}]overlay=x={x}:y={o['y']}:"
f"enable='between(t,{o['start']:.3f},{o['end']:.3f})'[{nxt}]")
cur = nxt
return chains, inputs