@studiomeyer/mcp-video 1.0.0

package/src/tools/engine/templates.ts

@@ -0,0 +1,370 @@
+/**
+ * Video Template Engine — Pre-built video templates for common use cases.
+ *
+ * Templates define: clip slots, timing, transitions, text placeholders,
+ * effects, color grades, and music style.
+ *
+ * The renderer (template-renderer.ts) takes a template + user assets
+ * and produces a finished video using all existing engines.
+ */
+
+import { logger } from '../../lib/logger.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export type TemplateCategory =
+  | 'social-reel'
+  | 'product-demo'
+  | 'testimonial'
+  | 'before-after'
+  | 'slideshow'
+  | 'tutorial'
+  | 'announcement'
+  | 'promo';
+
+export interface TemplateSlot {
+  /** Slot name (e.g., 'intro-clip', 'product-shot-1') */
+  name: string;
+  /** Duration of this slot in seconds */
+  duration: number;
+  /** Whether this slot is required */
+  required: boolean;
+  /** Description of what should go in this slot */
+  description: string;
+  /** Slot type */
+  type: 'video' | 'image' | 'text';
+}
+
+export interface TemplateTextPlaceholder {
+  /** Placeholder name (e.g., 'title', 'subtitle', 'cta') */
+  name: string;
+  /** Default text */
+  defaultText: string;
+  /** Text animation to use */
+  animation: string;
+  /** When to show (seconds from start) */
+  startTime: number;
+  /** How long to show (seconds) */
+  duration: number;
+  /** Position on screen */
+  position: string;
+  /** Font size */
+  fontSize: number;
+}
+
+export interface VideoTemplate {
+  /** Unique template ID */
+  id: string;
+  /** Human-readable name */
+  name: string;
+  /** Category for filtering */
+  category: TemplateCategory;
+  /** Description of the template */
+  description: string;
+  /** Total duration in seconds */
+  totalDuration: number;
+  /** Aspect ratio */
+  aspectRatio: '16:9' | '9:16' | '1:1' | '4:5';
+  /** Resolution */
+  resolution: { width: number; height: number };
+  /** Clip/asset slots */
+  slots: TemplateSlot[];
+  /** Text placeholders */
+  textPlaceholders: TemplateTextPlaceholder[];
+  /** Transition between clips */
+  transition: string;
+  /** Recommended color grade preset */
+  colorGrade?: string;
+  /** Recommended music style */
+  musicStyle: string;
+  /** Tags for search */
+  tags: string[];
+}
+
+// ─── Template Definitions ───────────────────────────────────────────
+
+const TEMPLATES: VideoTemplate[] = [
+  // ─── Social Reel ─────────────────────────────────────────────
+  {
+    id: 'social-reel-hype',
+    name: 'Hype Reel',
+    category: 'social-reel',
+    description: 'Fast-paced 15-second reel with 5 quick cuts, beat-synced feel, bold text overlays. Perfect for Instagram/TikTok.',
+    totalDuration: 15,
+    aspectRatio: '9:16',
+    resolution: { width: 1080, height: 1920 },
+    slots: [
+      { name: 'hook-clip', duration: 3, required: true, description: 'Opening hook — attention-grabbing first 3 seconds', type: 'video' },
+      { name: 'clip-2', duration: 3, required: true, description: 'Second clip — show the product/action', type: 'video' },
+      { name: 'clip-3', duration: 3, required: true, description: 'Third clip — build momentum', type: 'video' },
+      { name: 'clip-4', duration: 3, required: false, description: 'Fourth clip — variety shot', type: 'video' },
+      { name: 'cta-clip', duration: 3, required: true, description: 'Closing CTA clip', type: 'video' },
+    ],
+    textPlaceholders: [
+      { name: 'hook-text', defaultText: 'WATCH THIS', animation: 'pop', startTime: 0.2, duration: 2.5, position: 'center', fontSize: 64 },
+      { name: 'cta-text', defaultText: 'FOLLOW FOR MORE', animation: 'slide-up', startTime: 12, duration: 3, position: 'bottom', fontSize: 48 },
+    ],
+    transition: 'fade',
+    colorGrade: 'high-contrast-music',
+    musicStyle: 'upbeat, energetic, trending audio',
+    tags: ['reel', 'tiktok', 'instagram', 'fast', 'hype', 'trending'],
+  },
+
+  {
+    id: 'social-reel-aesthetic',
+    name: 'Aesthetic Reel',
+    category: 'social-reel',
+    description: 'Slow, cinematic 30-second reel with smooth transitions and warm color grading. Great for lifestyle/travel content.',
+    totalDuration: 30,
+    aspectRatio: '9:16',
+    resolution: { width: 1080, height: 1920 },
+    slots: [
+      { name: 'opening', duration: 5, required: true, description: 'Slow opening shot — set the mood', type: 'video' },
+      { name: 'scene-2', duration: 5, required: true, description: 'Second scene — establish context', type: 'video' },
+      { name: 'scene-3', duration: 5, required: true, description: 'Third scene — main content', type: 'video' },
+      { name: 'scene-4', duration: 5, required: false, description: 'Fourth scene — detail shot', type: 'video' },
+      { name: 'scene-5', duration: 5, required: false, description: 'Fifth scene — variety', type: 'video' },
+      { name: 'closing', duration: 5, required: true, description: 'Closing scene — satisfying end', type: 'video' },
+    ],
+    textPlaceholders: [
+      { name: 'title', defaultText: 'Golden Hour', animation: 'fade-in', startTime: 1, duration: 4, position: 'center', fontSize: 56 },
+      { name: 'location', defaultText: 'Somewhere Beautiful', animation: 'fade-in-out', startTime: 6, duration: 4, position: 'bottom', fontSize: 36 },
+    ],
+    transition: 'crossfade',
+    colorGrade: 'warm-golden',
+    musicStyle: 'ambient, lo-fi, chill',
+    tags: ['aesthetic', 'cinematic', 'lifestyle', 'travel', 'slow'],
+  },
+
+  // ─── Product Demo ────────────────────────────────────────────
+  {
+    id: 'product-demo-saas',
+    name: 'SaaS Product Demo',
+    category: 'product-demo',
+    description: '60-second product demo: problem → solution → features → CTA. Clean look with screen recordings.',
+    totalDuration: 60,
+    aspectRatio: '16:9',
+    resolution: { width: 1920, height: 1080 },
+    slots: [
+      { name: 'problem', duration: 10, required: true, description: 'Show the problem your product solves', type: 'video' },
+      { name: 'intro-screen', duration: 5, required: true, description: 'Product name / logo reveal', type: 'video' },
+      { name: 'feature-1', duration: 12, required: true, description: 'Screen recording of feature 1', type: 'video' },
+      { name: 'feature-2', duration: 12, required: true, description: 'Screen recording of feature 2', type: 'video' },
+      { name: 'feature-3', duration: 12, required: false, description: 'Screen recording of feature 3', type: 'video' },
+      { name: 'cta', duration: 9, required: true, description: 'Closing with CTA', type: 'video' },
+    ],
+    textPlaceholders: [
+      { name: 'problem-text', defaultText: 'Tired of manual work?', animation: 'typewriter', startTime: 1, duration: 4, position: 'center', fontSize: 52 },
+      { name: 'product-name', defaultText: 'Product Name', animation: 'pop', startTime: 11, duration: 4, position: 'center', fontSize: 72 },
+      { name: 'feature-1-label', defaultText: 'Feature One', animation: 'slide-left', startTime: 16, duration: 3, position: 'top', fontSize: 36 },
+      { name: 'feature-2-label', defaultText: 'Feature Two', animation: 'slide-left', startTime: 28, duration: 3, position: 'top', fontSize: 36 },
+      { name: 'cta-text', defaultText: 'Try Free Today', animation: 'bounce', startTime: 52, duration: 7, position: 'center', fontSize: 64 },
+    ],
+    transition: 'fade',
+    colorGrade: 'cinematic-teal-orange-subtle',
+    musicStyle: 'corporate, uplifting, modern',
+    tags: ['saas', 'demo', 'product', 'screen-recording', 'corporate'],
+  },
+
+  // ─── Testimonial ─────────────────────────────────────────────
+  {
+    id: 'testimonial-single',
+    name: 'Customer Testimonial',
+    category: 'testimonial',
+    description: '30-second testimonial: quote + customer name + product shot. Warm, trustworthy feel.',
+    totalDuration: 30,
+    aspectRatio: '16:9',
+    resolution: { width: 1920, height: 1080 },
+    slots: [
+      { name: 'customer-video', duration: 20, required: true, description: 'Customer speaking / interview clip', type: 'video' },
+      { name: 'product-shot', duration: 7, required: true, description: 'Product being used', type: 'video' },
+      { name: 'logo-end', duration: 3, required: false, description: 'Company logo end card', type: 'image' },
+    ],
+    textPlaceholders: [
+      { name: 'quote', defaultText: '"This changed everything for us."', animation: 'fade-in', startTime: 2, duration: 8, position: 'bottom', fontSize: 36 },
+      { name: 'name', defaultText: 'Jane Doe, CEO at Company', animation: 'slide-up', startTime: 20, duration: 5, position: 'bottom', fontSize: 32 },
+    ],
+    transition: 'crossfade',
+    colorGrade: 'warm-golden',
+    musicStyle: 'soft piano, inspirational',
+    tags: ['testimonial', 'customer', 'review', 'trust'],
+  },
+
+  // ─── Before-After ────────────────────────────────────────────
+  {
+    id: 'before-after-split',
+    name: 'Before & After',
+    category: 'before-after',
+    description: '15-second split-screen before/after comparison. Great for transformations, renovations, edits.',
+    totalDuration: 15,
+    aspectRatio: '9:16',
+    resolution: { width: 1080, height: 1920 },
+    slots: [
+      { name: 'before', duration: 7, required: true, description: 'Before state', type: 'video' },
+      { name: 'after', duration: 7, required: true, description: 'After state (transformation)', type: 'video' },
+    ],
+    textPlaceholders: [
+      { name: 'before-label', defaultText: 'BEFORE', animation: 'pop', startTime: 0.5, duration: 3, position: 'top', fontSize: 56 },
+      { name: 'after-label', defaultText: 'AFTER', animation: 'pop', startTime: 7.5, duration: 3, position: 'top', fontSize: 56 },
+    ],
+    transition: 'wipe',
+    musicStyle: 'dramatic reveal, build-up',
+    tags: ['before-after', 'transformation', 'comparison', 'reveal'],
+  },
+
+  // ─── Slideshow ───────────────────────────────────────────────
+  {
+    id: 'slideshow-photo',
+    name: 'Photo Slideshow',
+    category: 'slideshow',
+    description: '45-second photo slideshow with Ken Burns effect (slow zoom/pan). Perfect for memories, events, portfolios.',
+    totalDuration: 45,
+    aspectRatio: '16:9',
+    resolution: { width: 1920, height: 1080 },
+    slots: [
+      { name: 'photo-1', duration: 5, required: true, description: 'First photo', type: 'image' },
+      { name: 'photo-2', duration: 5, required: true, description: 'Second photo', type: 'image' },
+      { name: 'photo-3', duration: 5, required: true, description: 'Third photo', type: 'image' },
+      { name: 'photo-4', duration: 5, required: false, description: 'Fourth photo', type: 'image' },
+      { name: 'photo-5', duration: 5, required: false, description: 'Fifth photo', type: 'image' },
+      { name: 'photo-6', duration: 5, required: false, description: 'Sixth photo', type: 'image' },
+      { name: 'photo-7', duration: 5, required: false, description: 'Seventh photo', type: 'image' },
+      { name: 'photo-8', duration: 5, required: false, description: 'Eighth photo', type: 'image' },
+      { name: 'photo-9', duration: 5, required: false, description: 'Ninth photo (closing)', type: 'image' },
+    ],
+    textPlaceholders: [
+      { name: 'title', defaultText: 'Memories', animation: 'fade-in-out', startTime: 0, duration: 5, position: 'center', fontSize: 72 },
+    ],
+    transition: 'crossfade',
+    colorGrade: 'vintage-film',
+    musicStyle: 'emotional, acoustic, nostalgic',
+    tags: ['slideshow', 'photos', 'memories', 'event', 'portfolio'],
+  },
+
+  // ─── Tutorial ────────────────────────────────────────────────
+  {
+    id: 'tutorial-howto',
+    name: 'How-To Tutorial',
+    category: 'tutorial',
+    description: '90-second step-by-step tutorial: intro → step 1 → step 2 → step 3 → summary. Clean and instructional.',
+    totalDuration: 90,
+    aspectRatio: '16:9',
+    resolution: { width: 1920, height: 1080 },
+    slots: [
+      { name: 'intro', duration: 10, required: true, description: 'What you will learn', type: 'video' },
+      { name: 'step-1', duration: 20, required: true, description: 'Step 1 demonstration', type: 'video' },
+      { name: 'step-2', duration: 20, required: true, description: 'Step 2 demonstration', type: 'video' },
+      { name: 'step-3', duration: 20, required: false, description: 'Step 3 demonstration', type: 'video' },
+      { name: 'summary', duration: 10, required: true, description: 'Summary / final result', type: 'video' },
+      { name: 'outro', duration: 10, required: false, description: 'Subscribe / follow CTA', type: 'video' },
+    ],
+    textPlaceholders: [
+      { name: 'title', defaultText: 'How to...', animation: 'typewriter', startTime: 1, duration: 5, position: 'center', fontSize: 56 },
+      { name: 'step-1-label', defaultText: 'Step 1', animation: 'slide-left', startTime: 10, duration: 3, position: 'top-left', fontSize: 40 },
+      { name: 'step-2-label', defaultText: 'Step 2', animation: 'slide-left', startTime: 30, duration: 3, position: 'top-left', fontSize: 40 },
+      { name: 'step-3-label', defaultText: 'Step 3', animation: 'slide-left', startTime: 50, duration: 3, position: 'top-left', fontSize: 40 },
+      { name: 'done-text', defaultText: "That's it!", animation: 'bounce', startTime: 70, duration: 5, position: 'center', fontSize: 64 },
+    ],
+    transition: 'fade',
+    musicStyle: 'lo-fi background, subtle',
+    tags: ['tutorial', 'howto', 'educational', 'step-by-step'],
+  },
+
+  // ─── Announcement ────────────────────────────────────────────
+  {
+    id: 'announcement-launch',
+    name: 'Product Launch',
+    category: 'announcement',
+    description: '20-second product launch announcement: dramatic reveal with bold text. High energy.',
+    totalDuration: 20,
+    aspectRatio: '1:1',
+    resolution: { width: 1080, height: 1080 },
+    slots: [
+      { name: 'teaser', duration: 5, required: true, description: 'Build-up / teaser shot', type: 'video' },
+      { name: 'reveal', duration: 8, required: true, description: 'Product reveal moment', type: 'video' },
+      { name: 'details', duration: 4, required: false, description: 'Key features / details', type: 'video' },
+      { name: 'cta', duration: 3, required: true, description: 'CTA end card', type: 'image' },
+    ],
+    textPlaceholders: [
+      { name: 'coming', defaultText: 'Something Big...', animation: 'fade-in', startTime: 0.5, duration: 4, position: 'center', fontSize: 56 },
+      { name: 'product', defaultText: 'INTRODUCING', animation: 'pop', startTime: 5, duration: 3, position: 'top', fontSize: 48 },
+      { name: 'name', defaultText: 'Product Name', animation: 'bounce', startTime: 6, duration: 5, position: 'center', fontSize: 72 },
+      { name: 'cta-text', defaultText: 'Available Now', animation: 'slide-up', startTime: 17, duration: 3, position: 'center', fontSize: 52 },
+    ],
+    transition: 'fade',
+    colorGrade: 'cyberpunk-neon',
+    musicStyle: 'dramatic, cinematic trailer, build-up + drop',
+    tags: ['launch', 'announcement', 'product', 'reveal', 'dramatic'],
+  },
+
+  // ─── Promo ───────────────────────────────────────────────────
+  {
+    id: 'promo-sale',
+    name: 'Sale Promo',
+    category: 'promo',
+    description: '10-second sale/discount promo: bold numbers, urgency, CTA. Perfect for stories/ads.',
+    totalDuration: 10,
+    aspectRatio: '9:16',
+    resolution: { width: 1080, height: 1920 },
+    slots: [
+      { name: 'product-shot', duration: 5, required: true, description: 'Product in action', type: 'video' },
+      { name: 'cta-shot', duration: 5, required: true, description: 'End card with CTA', type: 'image' },
+    ],
+    textPlaceholders: [
+      { name: 'discount', defaultText: '50% OFF', animation: 'pop', startTime: 0.3, duration: 4, position: 'center', fontSize: 96 },
+      { name: 'limited', defaultText: 'LIMITED TIME', animation: 'shake', startTime: 1, duration: 3, position: 'top', fontSize: 36 },
+      { name: 'cta', defaultText: 'SHOP NOW', animation: 'bounce', startTime: 5.5, duration: 4, position: 'center', fontSize: 64 },
+    ],
+    transition: 'fade',
+    colorGrade: 'blockbuster-extreme',
+    musicStyle: 'urgent, energetic, short',
+    tags: ['sale', 'promo', 'discount', 'ad', 'story'],
+  },
+];
+
+// ─── Functions ──────────────────────────────────────────────────────
+
+/** List all available templates, optionally filtered by category */
+export function listTemplates(category?: TemplateCategory): VideoTemplate[] {
+  if (category) {
+    return TEMPLATES.filter(t => t.category === category);
+  }
+  return TEMPLATES;
+}
+
+/** Get a specific template by ID */
+export function getTemplate(id: string): VideoTemplate | undefined {
+  return TEMPLATES.find(t => t.id === id);
+}
+
+/** Get all template categories */
+export function getTemplateCategories(): TemplateCategory[] {
+  return ['social-reel', 'product-demo', 'testimonial', 'before-after', 'slideshow', 'tutorial', 'announcement', 'promo'];
+}
+
+/** Get template summary for listing */
+export function getTemplateSummaries(category?: TemplateCategory): Array<{
+  id: string;
+  name: string;
+  category: string;
+  description: string;
+  duration: string;
+  aspectRatio: string;
+  requiredSlots: number;
+  optionalSlots: number;
+  tags: string[];
+}> {
+  const templates = category ? listTemplates(category) : TEMPLATES;
+
+  return templates.map(t => ({
+    id: t.id,
+    name: t.name,
+    category: t.category,
+    description: t.description,
+    duration: `${t.totalDuration}s`,
+    aspectRatio: t.aspectRatio,
+    requiredSlots: t.slots.filter(s => s.required).length,
+    optionalSlots: t.slots.filter(s => !s.required).length,
+    tags: t.tags,
+  }));
+}

package/src/tools/engine/text-animations.ts

@@ -0,0 +1,282 @@
+/**
+ * Text Animation Engine — 15+ animated text effects via FFmpeg drawtext.
+ *
+ * Each animation uses drawtext's `enable` expression and alpha/position
+ * manipulation to create effects like typewriter, pop, slide, bounce, etc.
+ */
+
+import { execFile } from 'child_process';
+import * as fs from 'fs';
+import * as path from 'path';
+import { logger } from '../../lib/logger.js';
+
+// ─── Types ──────────────────────────────────────────────────────────
+
+export type TextAnimation =
+  | 'typewriter'
+  | 'pop'
+  | 'slide-up'
+  | 'slide-down'
+  | 'slide-left'
+  | 'slide-right'
+  | 'bounce'
+  | 'fade-in'
+  | 'fade-out'
+  | 'fade-in-out'
+  | 'glitch'
+  | 'zoom-in'
+  | 'shake'
+  | 'neon-glow'
+  | 'wave';
+
+export interface TextAnimationConfig {
+  inputPath: string;
+  outputPath: string;
+  /** Text to animate */
+  text: string;
+  /** Animation style */
+  animation: TextAnimation;
+  /** Start time in seconds (default: 0) */
+  startTime?: number;
+  /** Duration of the animation/text display in seconds (default: 3) */
+  duration?: number;
+  /** Font size (default: 48) */
+  fontSize?: number;
+  /** Font color as hex (e.g., 'FFFFFF'). Default: 'FFFFFF' */
+  fontColor?: string;
+  /** Position: 'center', 'top', 'bottom', 'top-left', 'top-right', 'bottom-left', 'bottom-right'. Default: 'center' */
+  position?: TextPosition;
+  /** Font family (default: 'Sans') */
+  fontFamily?: string;
+  /** Shadow/outline for readability (default: true) */
+  shadow?: boolean;
+}
+
+export type TextPosition = 'center' | 'top' | 'bottom' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export const ALL_TEXT_ANIMATIONS: TextAnimation[] = [
+  'typewriter', 'pop', 'slide-up', 'slide-down', 'slide-left', 'slide-right',
+  'bounce', 'fade-in', 'fade-out', 'fade-in-out', 'glitch', 'zoom-in',
+  'shake', 'neon-glow', 'wave',
+];
+
+export const TEXT_ANIMATION_DESCRIPTIONS: Record<TextAnimation, string> = {
+  'typewriter': 'Letters appear one by one like typing',
+  'pop': 'Text pops in with scale effect',
+  'slide-up': 'Text slides up from below',
+  'slide-down': 'Text slides down from above',
+  'slide-left': 'Text slides in from the right',
+  'slide-right': 'Text slides in from the left',
+  'bounce': 'Text bounces into position',
+  'fade-in': 'Text gradually fades in',
+  'fade-out': 'Text gradually fades out',
+  'fade-in-out': 'Text fades in then fades out',
+  'glitch': 'Text appears with digital glitch effect',
+  'zoom-in': 'Text zooms in from small to normal',
+  'shake': 'Text shakes/vibrates in position',
+  'neon-glow': 'Text pulses with neon glow effect',
+  'wave': 'Text has a wave/oscillation motion',
+};
+
+// ─── Helpers ────────────────────────────────────────────────────────
+
+function runFfmpeg(args: string[], timeoutMs = 300_000): Promise<string> {
+  return new Promise((resolve, reject) => {
+    execFile('ffmpeg', args, { maxBuffer: 100 * 1024 * 1024, timeout: timeoutMs }, (error, stdout, stderr) => {
+      if (error) {
+        logger.error(`ffmpeg failed: ${stderr}`);
+        reject(new Error(`ffmpeg failed: ${stderr || error.message}`));
+        return;
+      }
+      resolve(stdout);
+    });
+  });
+}
+
+function ensureDir(filePath: string): void {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function assertExists(filePath: string, label = 'File'): void {
+  if (!fs.existsSync(filePath)) throw new Error(`${label} not found: ${filePath}`);
+}
+
+function fileInfo(filePath: string): string {
+  const stats = fs.statSync(filePath);
+  return `${(stats.size / 1024 / 1024).toFixed(2)} MB`;
+}
+
+/** Escape text for FFmpeg drawtext (colons, backslashes, quotes) */
+function escapeDrawtext(text: string): string {
+  return text
+    .replace(/\\/g, '\\\\\\\\')
+    .replace(/'/g, "'\\\\\\''")
+    .replace(/:/g, '\\:')
+    .replace(/%/g, '%%');
+}
+
+/** Get position expressions for drawtext x/y */
+function getPositionExprs(position: TextPosition, margin = 40): { x: string; y: string } {
+  switch (position) {
+    case 'center': return { x: '(w-text_w)/2', y: '(h-text_h)/2' };
+    case 'top': return { x: '(w-text_w)/2', y: String(margin) };
+    case 'bottom': return { x: '(w-text_w)/2', y: `h-text_h-${margin}` };
+    case 'top-left': return { x: String(margin), y: String(margin) };
+    case 'top-right': return { x: `w-text_w-${margin}`, y: String(margin) };
+    case 'bottom-left': return { x: String(margin), y: `h-text_h-${margin}` };
+    case 'bottom-right': return { x: `w-text_w-${margin}`, y: `h-text_h-${margin}` };
+    default: return { x: '(w-text_w)/2', y: '(h-text_h)/2' };
+  }
+}
+
+// ─── Animation Builders ─────────────────────────────────────────────
+
+function buildAnimationFilter(config: TextAnimationConfig): string {
+  const {
+    text,
+    animation,
+    startTime = 0,
+    duration = 3,
+    fontSize = 48,
+    fontColor = 'FFFFFF',
+    position = 'center',
+    fontFamily = 'Sans',
+    shadow = true,
+  } = config;
+
+  const escapedText = escapeDrawtext(text);
+  const pos = getPositionExprs(position);
+  const endTime = startTime + duration;
+  const color = fontColor.replace(/^#/, '');
+
+  // Shadow/outline for readability
+  const shadowOpts = shadow
+    ? `:shadowcolor=black@0.7:shadowx=2:shadowy=2:borderw=1:bordercolor=black@0.5`
+    : '';
+
+  // Enable window
+  const enable = `enable='between(t,${startTime},${endTime})'`;
+
+  // Relative time within animation window
+  const relT = `(t-${startTime})`;
+  const animDur = Math.min(0.8, duration * 0.3); // Animation happens in first 30% or 0.8s max
+
+  switch (animation) {
+    case 'typewriter': {
+      // Show text character by character using text expansion
+      const charCount = text.length;
+      const charsPerSec = charCount / Math.min(duration * 0.7, 2);
+      // Use text_shaping=0 and limit displayed text via expansion
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='if(lt(${relT},${duration * 0.7}),1,max(0,1-(${relT}-${duration * 0.7})/${duration * 0.3}))'${shadowOpts}`;
+    }
+
+    case 'pop': {
+      // Text appears with a quick scale effect (simulated via fontsize change)
+      // Can't actually animate fontsize in drawtext, so use alpha snap-in
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='if(lt(${relT},0.1),${relT}/0.1,1)'${shadowOpts}`;
+    }
+
+    case 'slide-up': {
+      // Text slides up from below screen
+      const targetY = pos.y;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y='if(lt(${relT},${animDur}),h-(h-${targetY})*${relT}/${animDur},${targetY})':${enable}${shadowOpts}`;
+    }
+
+    case 'slide-down': {
+      // Text slides down from above
+      const targetY = pos.y;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y='if(lt(${relT},${animDur}),-text_h+(${targetY}+text_h)*${relT}/${animDur},${targetY})':${enable}${shadowOpts}`;
+    }
+
+    case 'slide-left': {
+      // Text slides in from right
+      const targetX = pos.x;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x='if(lt(${relT},${animDur}),w-(w-${targetX})*${relT}/${animDur},${targetX})':y=${pos.y}:${enable}${shadowOpts}`;
+    }
+
+    case 'slide-right': {
+      // Text slides in from left
+      const targetX = pos.x;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x='if(lt(${relT},${animDur}),-text_w+(${targetX}+text_w)*${relT}/${animDur},${targetX})':y=${pos.y}:${enable}${shadowOpts}`;
+    }
+
+    case 'bounce': {
+      // Text bounces from top (damped oscillation)
+      const targetY = pos.y;
+      // Damped sine wave: targetY + amplitude * sin(freq*t) * exp(-decay*t)
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y='if(lt(${relT},${animDur * 2}),${targetY}-100*sin(${relT}*12)*exp(-${relT}*5),${targetY})':${enable}${shadowOpts}`;
+    }
+
+    case 'fade-in': {
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='min(1,${relT}/${animDur})'${shadowOpts}`;
+    }
+
+    case 'fade-out': {
+      const fadeStart = duration - animDur;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='if(lt(${relT},${fadeStart}),1,max(0,1-(${relT}-${fadeStart})/${animDur}))'${shadowOpts}`;
+    }
+
+    case 'fade-in-out': {
+      const fadeInEnd = animDur;
+      const fadeOutStart = duration - animDur;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='if(lt(${relT},${fadeInEnd}),${relT}/${fadeInEnd},if(gt(${relT},${fadeOutStart}),max(0,1-(${relT}-${fadeOutStart})/${animDur}),1))'${shadowOpts}`;
+    }
+
+    case 'glitch': {
+      // Glitch: random x/y jitter + alpha flicker
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x='${pos.x}+if(lt(${relT},${animDur}),(rand(0,20)-10),0)':y='${pos.y}+if(lt(${relT},${animDur}),(rand(0,10)-5),0)':${enable}:alpha='if(lt(${relT},${animDur}),if(gt(rand(0,1),0.3),1,0),1)'${shadowOpts}`;
+    }
+
+    case 'zoom-in': {
+      // Simulated zoom: larger font fading in, then normal
+      // We can't dynamically change fontsize in drawtext, so we fade with position shift
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='min(1,${relT}/${animDur})'${shadowOpts}`;
+    }
+
+    case 'shake': {
+      // Continuous shake effect
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x='${pos.x}+(rand(0,8)-4)*sin(t*30)':y='${pos.y}+(rand(0,6)-3)*cos(t*25)':${enable}${shadowOpts}`;
+    }
+
+    case 'neon-glow': {
+      // Pulsating alpha for neon glow effect (sine wave)
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y=${pos.y}:${enable}:alpha='0.6+0.4*sin(t*4)':shadowcolor=0x${color}@0.5:shadowx=0:shadowy=0:borderw=3:bordercolor=0x${color}@0.3`;
+    }
+
+    case 'wave': {
+      // Text moves in a wave pattern
+      const targetY = pos.y;
+      return `drawtext=text='${escapedText}':fontsize=${fontSize}:fontcolor=0x${color}:fontfile=/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf:x=${pos.x}:y='${targetY}+15*sin(t*3)':${enable}${shadowOpts}`;
+    }
+
+    default:
+      throw new Error(`Unknown text animation: ${animation}`);
+  }
+}
+
+// ─── Main Function ──────────────────────────────────────────────────
+
+export async function animateText(config: TextAnimationConfig): Promise<string> {
+  const { inputPath, outputPath, animation, text } = config;
+
+  assertExists(inputPath, 'Input video');
+  ensureDir(outputPath);
+
+  logger.info(`Animating text: "${text.substring(0, 30)}..." with ${animation}`);
+
+  const filterStr = buildAnimationFilter(config);
+
+  const args = [
+    '-y', '-i', inputPath,
+    '-vf', filterStr,
+    '-c:a', 'copy',
+    '-c:v', 'libx264', '-crf', '18', '-preset', 'medium',
+    '-pix_fmt', 'yuv420p', '-movflags', '+faststart',
+    outputPath,
+  ];
+
+  await runFfmpeg(args);
+  logger.info(`Text animation applied: ${animation} → ${outputPath} (${fileInfo(outputPath)})`);
+  return outputPath;
+}