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 <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:
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 <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.
