TikTok Text Overlay

---

name: tiktok-overlay version: 1.1.0 description: Adds TikTok-style text overlays to images and videos with styled fonts, backgrounds, strokes, and timed animations. user-invocable: true metadata: {"openclaw": {"emoji": "🎵", "requires": {"bins": ["python3"]}, "install": [{"type": "uv", "packages": ["Pillow", "moviepy"]}]}}

---

TikTok Text Overlay Skill

You are a TikTok-style text overlay tool. You add styled text overlays to images and videos, replicating the look and feel of TikTok's built-in text editor.

Setup

The overlay scripts live in {baseDir}:

{baseDir}/tiktok_overlay.py — image overlay engine

{baseDir}/tiktok_video_overlay.py — video overlay engine (uses moviepy)

Before using, ensure dependencies are installed:

pip3 install Pillow moviepy

Available Styles

| Style | Value | Description | |---------------|----------------|--------------------------------------| | Classic | classic | Clean bold sans-serif (Arial Bold) | | Typewriter | typewriter | Monospace typewriter look | | Handwriting | handwriting | Casual handwriting font | | Neon | neon | Rounded bold with glow effect | | Serif | serif | Traditional serif (Georgia) | | Strong | strong | Extra bold impact style | | Comic | comic | Playful comic sans style |

Background Styles

| Style | Value | Description | |-------------|--------------|------------------------------------------| | None | none | No background, text only | | Highlight | highlight | Per-line rounded highlight (TikTok default) | | Full BG | full_bg | Single rounded rectangle behind all text | | Letter | letter | Per-line tight highlight |

Image Overlay

Use {baseDir}/tiktok_overlay.py for images:

import sys
sys.path.insert(0, "{baseDir}")
from tiktok_overlay import overlay_text, overlay_texts, TextOverlay
Single text — save to file
overlay_text("input.jpg", "Your text here", "output.jpg",
    style="classic", font_size=48, stroke_width=5, bg_style="none")
Single text — return PIL Image (omit output_path)
result = overlay_text("input.jpg", "Your text here",
    style="strong", font_size="large", text_color="coral")
Multiple overlays — TextOverlay objects
overlay_texts("input.jpg", [
    TextOverlay("Top text", position="top", style="classic", stroke_width=4),
    TextOverlay("Bottom", position="bottom", text_color="red"),
], "output.jpg")
Multiple overlays — dicts (no import needed)
overlay_texts("input.jpg", [
    {"text": "Top text", "position": "top", "style": "strong", "stroke_width": 5},
    {"text": "Bottom", "position": "bottom", "text_color": "coral"},
], "output.jpg")
Multiple overlays — (text, kwargs) tuples
overlay_texts("input.jpg", [
    ("Top text", {"position": "top", "stroke_width": 5}),
    ("Bottom", {"position": "bottom", "text_color": "red"}),
], "output.jpg")

Flexible Inputs

All parameters accept multiple formats:

Input source — file path, PIL Image, numpy array, or bytes:

overlay_text("photo.jpg", "Hello", "out.jpg")          # path
overlay_text(pil_image, "Hello", "out.jpg")             # PIL Image
overlay_text(numpy_array, "Hello", "out.jpg")           # numpy
overlay_text(image_bytes, "Hello", "out.jpg")           # bytes

Output — file path to save, or None to return PIL Image:

overlay_text("photo.jpg", "Hello", "out.jpg")           # saves file
result = overlay_text("photo.jpg", "Hello")             # returns PIL Image

Colors — hex, short hex, hex+alpha, named, RGB tuple, RGBA tuple:

text_color="#FF0000"          # hex
text_color="#F00"             # short hex
text_color="#FF000080"        # hex with alpha
text_color="red"              # named (all CSS/PIL colors)
text_color=(255, 0, 0)        # RGB tuple
text_color=(255, 0, 0, 128)   # RGBA tuple

Font size — int pixels, string with unit, or named size:

font_size=48                  # pixels
font_size="48px"              # string with unit
font_size="small"             # 32px
font_size="medium"            # 48px
font_size="large"             # 64px
font_size="xl"                # 80px
font_size="title"             # 72px
font_size="caption"           # 28px

Style — string or enum:

style="classic"               # string
style="strong"
from tiktok_overlay import TikTokStyle
style=TikTokStyle.CLASSIC     # enum

Position — named, compound, pixel, percentage, or dict:

position="top"                # named
position="bottom-left"        # compound
position=(100, 200)           # pixel coordinates
position=("50%", "80%")       # percentage of image size
position={"x": "10%", "y": "top"}  # dict with mixed

Opacity — float, int, or percentage string:

bg_opacity=0.6                # float 0-1
bg_opacity=153                # int 0-255
bg_opacity="60%"              # percentage string

Max width ratio — float or percentage string:

max_width_ratio=0.85          # float
max_width_ratio="85%"         # percentage string

CLI

python3 {baseDir}/tiktok_overlay.py  "" [output_image] [style]

Output path is optional — defaults to input_overlay.ext.

Video Overlay

Use {baseDir}/tiktok_video_overlay.py for videos. Supports timed text and fade in/out:

import sys
sys.path.insert(0, "{baseDir}")
from tiktok_video_overlay import overlay_video_text, overlay_video_texts, VideoTextOverlay
Single text on entire video
overlay_video_text("input.mp4", "Hello!", "output.mp4",
    style="classic", font_size=52, stroke_width=5)
Multiple timed texts
overlay_video_texts("input.mp4", [
    VideoTextOverlay("Appears 0-3s", t_start=0, t_end=3,
        fade_in=0.5, fade_out=0.5,
        style="classic", position="top", font_size=48, stroke_width=4),
    VideoTextOverlay("Appears 2-5s", t_start=2, t_end=5,
        style="strong", position="center", font_size=56,
        text_color="tomato", stroke_width=5, bg_style="none"),
    VideoTextOverlay("Always visible",
        position="bottom", font_size=40, bg_style="highlight"),
], "output.mp4")

CLI

python3 {baseDir}/tiktok_video_overlay.py  ""  [style]

Key Parameters

| Parameter | Accepts | Default | Description | |--------------------|------------------------------------------------|--------------|------------------------------------------| | input_source | path, PIL Image, numpy array, bytes | — | Image to overlay | | text | str | — | The text to overlay | | output_path | path or None | None | Save path; None returns PIL Image | | style | str, TikTokStyle, None | classic | Font style | | font_size | int, str ("48px", "large") | 48 | Font size | | text_color | hex, named, rgb/rgba tuple | #FFFFFF | Text color | | bg_style | str | highlight | Background style | | bg_color | hex, named, rgb/rgba tuple | #000000 | Background color | | bg_opacity | float 0-1, int 0-255, str "60%" | 0.6 | Background opacity | | position | str, (x,y), ("x%","y%"), dict | center | Position | | alignment | str | center | Text alignment: left/center/right | | stroke_width | int | 0 | Outline thickness (4-6 for TikTok look) | | stroke_color | hex, named, rgb/rgba tuple | #000000 | Outline color | | max_width_ratio | float or str "85%" | 0.85 | Max text width as ratio of image width |

Video-only Parameters

| Parameter | Type | Default | Description | |-------------|----------------|---------|--------------------------------| | t_start | float or None | None | Start time in seconds | | t_end | float or None | None | End time in seconds | | fade_in | float | 0.0 | Fade in duration (seconds) | | fade_out | float | 0.0 | Fade out duration (seconds) |

Tips

For the classic TikTok outlined text look, use bg_style="none" with stroke_width=5.

For the TikTok highlight look, use bg_style="highlight" with bg_opacity=0.6.

Word wrapping is automatic based on max_width_ratio.

Compound positions like "top-left" and "bottom-right" are supported.

All CSS/PIL named colors work: "red", "coral", "dodgerblue", "gold", etc.

Uses macOS system fonts as TikTok-style substitutes. Works out of the box on macOS.

The overlay scripts live in {baseDir}:

{baseDir}/tiktok_overlay.py — image overlay engine

{baseDir}/tiktok_video_overlay.py — video overlay engine (uses moviepy)

Before using, ensure dependencies are installed:

pip3 install Pillow moviepy

For the classic TikTok outlined text look, use bg_style="none" with stroke_width=5.

For the TikTok highlight look, use bg_style="highlight" with bg_opacity=0.6.

Word wrapping is automatic based on max_width_ratio.

Compound positions like "top-left" and "bottom-right" are supported.

All CSS/PIL named colors work: "red", "coral", "dodgerblue", "gold", etc.

Uses macOS system fonts as TikTok-style substitutes. Works out of the box on macOS.