TikTok Text Overlay

Adds TikTok-style text overlays to images and videos with styled fonts, backgrounds, strokes, and timed animations.

Install

openclaw skills install @xmuweili/tiktok-overlay

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:

bash

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:

python

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:

python

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:

python

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:

python

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:

python

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:

python

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

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

python

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:

python

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:

python

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

CLI

bash

python3 {baseDir}/tiktok_overlay.py <input_image> "<text>" [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:

python

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

bash

python3 {baseDir}/tiktok_video_overlay.py <input_video> "<text>" <output_video> [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.