wordartfx 0.3.0

CapCut-style animated text effects for video — 38 effects with metallic gradients, shimmer, and composable glow, shadow, stroke, and fade

wordartfx

CapCut-style animated text effects for video. FFmpeg + Pillow hybrid engine.

Add animated text overlays to any video with a clean Python API: bounce, typewriter, glitch, neon glow, per-character wave, metallic gradients with shimmer, and 30+ more effects. Composable properties let you layer glow, shadow, stroke, and fade on any animation.

Features

• 38 effects — 18 FFmpeg-native (fast, single-pass) + 20 Pillow-rendered (per-character, complex)
• Metallic gradients — gold, silver, bronze, copper, chrome presets + custom color stops
• Shimmer — animated diagonal highlight sweep across text
• Composable properties — stroke, glow, shadow, fade work with every effect
• 8 easing curves — linear, ease_in, ease_out, ease_in_out, bounce, elastic, spring, back
• 7 named positions + custom coordinate expressions
• Compound effects — layer multiple animations via modifiers
• Cross-platform fonts — auto-resolves fonts on Linux, macOS, and Windows

Install

pip install wordartfx

Requires FFmpeg on your PATH and Python 3.10+.

Quick Start

from wordartfx import TextEffect, apply_effects

effects = [
    TextEffect("Hello World", start=0, end=3, effect="fade_in", font_size=72),
    TextEffect("Subscribe!", start=3, end=6, effect="bounce",
               position="bottom-center", color="#FF4500"),
]
apply_effects("input.mp4", "output.mp4", effects)

38 Effects

FFmpeg-native (18 effects — fast, single-pass)

Effect	Description
none	Static text, no animation
fade_in	Alpha 0 to 1 with easing
fade_out	Alpha 1 to 0 with easing
slide_in_left	Slide in from left edge
slide_in_right	Slide in from right edge
slide_in_top	Slide in from top edge
slide_in_bottom	Slide in from bottom edge
typewriter	Characters appear one at a time
bounce	Bounce-in with overshoot
scale_in	Scale from 0 to full size
scale_out	Scale from full size to 0
shake	Pseudo-random x/y jitter
pulse	Font size oscillates +/-10%
stomp	Text slams in oversized then snaps to target
zoom_in	Smooth camera-style zoom in
zoom_out	Smooth camera-style zoom out
breathing	Smooth subtle scale oscillation
flicker	Random alpha dropout like a bad neon sign

Pillow-rendered (20 effects — per-character, complex)

Effect	Description
neon_glow	Multi-layer glow with pulsing alpha
glitch	RGB separation + horizontal slice displacement
wave	Per-character vertical sine wave
pop_in	Per-character scale-in with stagger
color_wave	Per-character HSV color cycling
shadow_zoom	Dynamic oscillating drop shadow
rotate_in	3 full spins decelerating to rest
drop_bounce	Per-character drop from top with bounce landing
blur_in	Text sharpens from blurred to focused
blur_out	Text blurs from focused to unreadable
tracking_in	Smooth horizontal scale compress from wide to normal
spacing_in	Per-character letter spacing compresses from wide to normal
wiggle	Per-character random organic jitter
highlight	Background color box sweeps behind text
flip_in	3D card flip on Y-axis to reveal text
swing	Text swings in like a pendulum from top
split	Text splits apart from center then reassembles
expand	Text reveals from center outward like a mask
3d_rotate	Pseudo-3D rotation with perspective transform
rainbow	Uniform HSV color cycling across whole text

Metallic Gradients

Fill text with metallic color gradients using the fill parameter:

TextEffect("PREMIUM", start=0, end=5, effect="fade_in",
           font_size=96, fill="gold")

Presets

Preset	Colors	Look
gold	#B8860B → #FFD700 → #FFF8DC → #FFD700 → #B8860B	Classic gold metallic
silver	#808080 → #C0C0C0 → #F5F5F5 → #C0C0C0 → #808080	Polished silver
bronze	#804A00 → #CD7F32 → #DAA06D → #CD7F32 → #804A00	Warm bronze
copper	#6E3B1A → #B87333 → #DA8A67 → #B87333 → #6E3B1A	Rich copper
chrome	#404040 → #A0A0A0 → #F0F0F0 → #A0A0A0 → #404040	Cool chrome

Custom Gradients

Pass any list of color stops with gradient_colors:

TextEffect("FIRE", start=0, end=5, effect="scale_in",
           font_size=80, gradient_colors=["#FF0000", "#FF8C00", "#FFD700"])

Shimmer

Add an animated diagonal highlight sweep that glides across the text:

TextEffect("LUXURY", start=0, end=5, effect="fade_in",
           font_size=96, fill="gold", shimmer=True)

The shimmer band sweeps left-to-right over the effect's full duration. It works with any gradient (preset or custom) and respects the text's alpha channel.

Composable Properties

Every property works with every animation:

TextEffect(
    "EPIC TEXT", start=0, end=5,
    effect="drop_bounce",            # animation
    font_size=80,                    # typography
    color="cyan",
    font_path="/path/to/font.ttf",
    stroke_width=3,                  # outline
    stroke_color="white",
    glow_color="cyan",               # glow halo
    glow_radius=15,
    shadow_x=4, shadow_y=4,          # drop shadow
    shadow_color="black@0.6",
    fade_in=0.3, fade_out=0.5,       # auto-fade (seconds)
    easing="elastic",                # easing curve
    modifiers=["slide_in_bottom"],   # compound animations
)

Positions

7 named positions + custom coordinate expressions:

Position	Placement
center	Centered both axes
top-center	Top middle (8% from top)
top-left	Top-left corner
top-right	Top-right corner
bottom-center	Bottom middle (85% down)
bottom-left	Bottom-left corner
bottom-right	Bottom-right corner

Custom positions use FFmpeg expressions: position=("w*0.5-tw/2", "h*0.3")

Easings

8 easing curves control animation timing:

Easing	Behavior
linear	Constant speed, no acceleration
ease_in	Starts slow, accelerates (quadratic)
ease_out	Starts fast, decelerates (quadratic)
ease_in_out	Slow start and end (smoothstep)
bounce	Dampened sine wave, slight overshoot
elastic	Rubber band snap with pronounced overshoot
spring	2-3 oscillations settling to rest
back	CSS-style overshoot then settle

Compound Effects

Layer multiple animations using modifiers:

# Bounce in from bottom with fade
TextEffect("WOW", start=0, end=3, effect="bounce",
           modifiers=["fade_in", "slide_in_bottom"])

Modifiers are applied on top of the primary effect. Any effect name can be used as a modifier.

How It Works

wordartfx uses a hybrid rendering engine:

• FFmpeg effects (fast): Built as drawtext filter expressions with animated parameters. Single-pass, no temp files.
• Pillow effects (complex): Rendered as RGBA PNG frame sequences, then composited via FFmpeg overlay filter. Enables per-character animation, rotation, RGB manipulation.

Both types support all composable properties (glow, shadow, stroke, fade) and can be mixed in the same video. Effects using gradient_colors or shimmer are automatically promoted to Pillow rendering.

Documentation

• API Reference — complete field-by-field reference for TextEffect, apply_effects, list_effects, and all constants
• Examples Cookbook — 8 ready-to-use recipes from basic overlay to kitchen-sink

Development

git clone https://github.com/mikelugo/wordartfx.git
cd wordartfx
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

License

MIT