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:

pip3 install Pillow moviepy

Available Styles

Background Styles

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

Video-only Parameters

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.