viral-video-animated-captions

## CRITICAL GUIDELINES

### Windows File Path Requirements

**MANDATORY: Always Use Backslashes on Windows for File Paths**

When using Edit or Write tools on Windows, you MUST use backslashes (`\`) in file paths, NOT forward slashes (`/`).

### Documentation Guidelines

**NEVER create new documentation files unless explicitly requested by the user.**

---

# CapCut-Style Animated Captions (2025-2026)

## Why Animated Captions Matter

- **80% engagement boost** when captions are present
- **85% of social video** is watched without sound
- **Animated word highlighting** increases retention by 25-40%
- CapCut-style captions are now **expected** by viewers

---

## Quick Reference

| Style | Effect | Best For |
|-------|--------|----------|
| Word Pop | Words bounce in one at a time | High energy, Gen Z |
| Highlight Sweep | Color sweeps across words | Professional, educational |
| Karaoke | Words light up with audio timing | Music, voiceover |
| Typewriter | Characters appear sequentially | Storytelling, dramatic |
| Scale Pulse | Words pulse larger on appear | Emphasis, key points |

---

## Caption Workflow Overview

### Standard Workflow

1. **Generate transcript** with word-level timestamps (Whisper)
2. **Convert to ASS format** with animation styles
3. **Burn captions** into video with FFmpeg

---

## Step 1: Generate Word-Level Timestamps

### Using Whisper (FFmpeg 8.0+)

```bash
# Generate JSON with word-level timestamps
ffmpeg -i input.mp4 -vn \
  -af "whisper=model=ggml-base.bin:language=auto:format=json" \
  transcript.json
```

### Using whisper.cpp Directly (More Control)

```bash
# Generate word-level JSON
whisper.cpp/main -m ggml-base.bin -f audio.wav -ojf -ml 1

# Output: audio.wav.json with word timings
```

### Using OpenAI Whisper API

```python
import whisper

model = whisper.load_model("base")
result = model.transcribe("audio.mp3", word_timestamps=True)

# Access word-level timing
for segment in result["segments"]:
    for word in segment["words"]: