Metadata-Version: 2.1
Name: wordartfx
Version: 0.3.0
Summary: CapCut-style animated text effects for video — 38 effects with metallic gradients, shimmer, and composable glow, shadow, stroke, and fade
Author: Mike Lugo
License: MIT
Project-URL: Homepage, https://github.com/mikelugo/wordartfx
Project-URL: Repository, https://github.com/mikelugo/wordartfx
Keywords: video,text,effects,animation,ffmpeg,captions,pillow,glow,bounce,typewriter,gradient,shimmer,metallic
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Pillow>=10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# wordartfx

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

![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)
![License MIT](https://img.shields.io/badge/license-MIT-green)
![Version 0.3.0](https://img.shields.io/badge/version-0.3.0-orange)

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

```bash
pip install wordartfx
```

Requires **FFmpeg** on your PATH and **Python 3.10+**.

## Quick Start

```python
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:

```python
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`:

```python
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:

```python
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:

```python
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`:

```python
# 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](docs/api.md)** — complete field-by-field reference for TextEffect, apply_effects, list_effects, and all constants
- **[Examples Cookbook](docs/examples.md)** — 8 ready-to-use recipes from basic overlay to kitchen-sink

## Development

```bash
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
