generate-video

Generate TikTok-style videos with voice, captions, avatar, and code overlays — one command.

Free TTS, animated captions, lip-synced avatar, preview intro, built-in script bank. No API key needed.

Quick Start

npx generate-video "JavaScript closures explained in 30 seconds"

Features

• Voice — 400+ TTS voices via edge-tts (free, unlimited)
• Captions — word-synced animated captions with outline
• Avatar — lip-synced cartoon avatar (amplitude analysis)
• Preview — branded 1.5s intro frame
• Code overlay — syntax-highlighted code box
• Title overlay — centered, word-wrapped
• Logo — custom PNG in top-left
• Script bank — 12 built-in topics (RAG, JS, etc.)
• Custom colors — background, accent
• Custom dimensions — vertical, landscape, square

Prerequisites

• Node.js >= 14
• Python 3 with pip (auto-installs edge-tts + Pillow)
• FFmpeg (brew install ffmpeg / apt install ffmpeg)

Usage

Basic video

npx generate-video "Your script text here"

With all features

npx generate-video "Your text" \
  --title "My Video" \
  --code "const x = 42;" \
  --avatar \
  --preview \
  --logo ./logo.png

Built-in topics

# List all topics
npx generate-video --topics

# Generate from a built-in topic
npx generate-video --topic 0
npx generate-video --topic 5 --avatar --preview

Avatar (lip-sync)

npx generate-video "Your text" --avatar

Generates a cartoon avatar with 4 mouth positions synced to audio amplitude.

Preview intro frame

npx generate-video "Your text" --title "My Video" --preview
npx generate-video "Your text" --preview --preview-bg ./background.png
npx generate-video "Your text" --preview --preview-duration 2.0

Adds a branded intro frame before the main content. Audio is delayed to sync.

Voice options

npx generate-video "Bonjour" --voice fr-FR-HenriNeural
npx generate-video "Fast speech" --rate "+30%"
npx generate-video "Deep voice" --pitch "-5Hz"
npx generate-video --voices --lang en

Custom look

npx generate-video "Your text" --bg-color 1a1a2e --accent-color e94560
npx generate-video "Your text" --width 1920 --height 1080   # Landscape
npx generate-video "Your text" --width 1080 --height 1080   # Square

Use existing audio

npx generate-video "Caption text" --audio ./voiceover.mp3

Preview without generating

npx generate-video "Your text" --dry-run

Options

Flag	Description	Default
-v, --voice <name>	TTS voice	en-US-GuyNeural
-o, --output <file>	Output path	Auto-generated
-t, --title <text>	Title overlay	—
-c, --code <text>	Code box overlay	—
--logo <path>	Logo image (PNG)	—
--audio <path>	Existing audio file	—
-r, --rate <rate>	Speech rate	Normal
-p, --pitch <pitch>	Voice pitch	Normal
--avatar	Enable lip-synced avatar	off
--preview	Add preview intro frame	off
--preview-bg <path>	Preview background image	—
--preview-duration <s>	Preview duration	1.5
--topic <index>	Use built-in topic	—
--topics	List built-in topics	—
--width <px>	Video width	720
--height <px>	Video height	1280
--fps <n>	Frames per second	30
--bg-color <hex>	Background color	0f172a
--accent-color <hex>	Accent color	7c3aed
--no-captions	Disable captions	—
--voices	List TTS voices	—
-l, --lang <code>	Filter voices	—
--dry-run	Preview only	—

How It Works

1. edge-tts generates voice audio with word-level timestamps (free)
2. Pillow renders background frame with title, code box, logo
3. Pillow renders animated caption frames synced to word timings
4. Pillow generates avatar with 4 mouth states (closed, small, medium, wide)
5. FFmpeg analyzes audio amplitude for lip-sync
6. FFmpeg composites frames + audio into final video

License

MIT