🎬 PKP Docu-Animator (pkp-docu-animator) v1.0.3

Standalone Remotion-based 2D/3D Animated Cricket Documentary & Shorts Video Generator Engine.

Built with SOLID Principles, a modular Base Engine Core, specialized domain engines, and end-to-end Full Video Flow Templates. Convert structured JSON scripts or TS flow templates into 4K/HD 2D Animated videos (1920x1080 long-form or 1080x1920 vertical Shorts) with voiceover sync, pitch Hawkeye ball tracking, polar wagon wheels, head-to-head VS cards, karaoke subtitles, and cinematic camera VFX.

🏛️ SOLID Architecture & Engine Ecosystem

The engine is decoupled into domain-specific modules adhering to Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion principles:

| Engine | Responsibility | Key Visual Capabilities | | :--- | :--- | :--- | | BaseEngine | Core Animation Math & Physics | Normalized progress (0.0 - 1.0), spring physics, cubic bezier, overshoot bounce, lifecycle hooks | | StatsDataEngine | Cricket Match Statistics | Polar Wagon Wheel shot distribution (angleInDegrees), career bar metrics, stats comparison grids | | PitchVisualizerEngine | 2D Pitch & Hawkeye Motion | Ball trajectory delivery curve (seam/spin), bounce point pulse marker, delivery speed gauge | | PlayerCardEngine | Player Battles & Spotlight | Split-screen head-to-head VS duels, player attribute spotlight cards | | KineticTypographyEngine | Motion Text & Quotes | Letter-staggered kinetic title reveals, quote animations with glowing spring physics | | RetroArchiveEngine | Vintage 1990s Aesthetics | Vintage newspaper cutouts, polaroids, dressing room secret quotes | | VfxCameraEngine | Camera Physics & VFX | Camera zoom/pan, pseudo-random camera shake physics during drama moments, film grain | | AudioSyncEngine | Multi-Track Audio Sync | Voiceover audio, background music auto-ducking during speech, timed SFX cues | | SubtitleEngine | Subtitles & Karaoke | High-visibility active word karaoke captions synced to voiceover timestamps | | OrchestratorEngine | Master Video Pipeline | Coordinates sub-engines, builds Remotion sequence timelines, parses documentary scripts |

🎬 Dedicated Full Video Flow Templates

Templates are organized into clean, dedicated directories (src/templates/) that orchestrate complete end-to-end documentary video flows from Scene 1 to Scene N:

src/templates/
├── HistoricalRivalry/              # Complete 5-Scene Match Rivalry Flow
│   ├── index.tsx                   # Flow Component & Config Builder
│   ├── Scene1_NewspaperHeadline.tsx
│   ├── Scene2_DressingRoomQuote.tsx
│   ├── Scene3_VersusClash.tsx
│   ├── Scene4_PitchHawkeye.tsx
│   └── Scene5_WagonWheelStats.tsx
├── ControversialDrama/             # Complete 4-Scene Controversy & Secret Drama Flow
│   ├── index.tsx                   # Flow Component & Config Builder
│   ├── Scene1_KineticHook.tsx
│   ├── Scene2_SecretQuote.tsx
│   ├── Scene3_TweetReaction.tsx
│   └── Scene4_PressStatement.tsx
└── PlayerComparison/              # Complete 3-Scene Legend Head-to-Head Comparison Flow
    ├── index.tsx                   # Flow Component & Config Builder
    ├── Scene1_PlayerSpotlight.tsx
    ├── Scene2_CareerStatsGrid.tsx
    └── Scene3_LegendQuoteOutro.tsx

🚀 Quick Start & Usage

1. Render a Full Video Flow Template (TypeScript / Node.js)

import { HistoricalRivalry, renderDocuVideo } from 'pkp-docu-animator';

// 1. Generate Full Video Flow Configuration with persistent UUIDs
const docuConfig = HistoricalRivalry.buildHistoricalRivalryConfig({
  headline: 'SACHIN HEROIC 136 IN TEAR GAS NIGHT',
  dressingRoomQuote: 'Dressing room mein tear gas ki boo thi... aur Sachin back pain mein ro rahe the.',
  player1Name: 'Sachin Tendulkar',
  player2Name: 'Wasim Akram',
  bowlerName: 'Saqlain Mushtaq',
  speedKmph: 88,
  wagonWheelStats: [
    { label: 'Cover Drive', value: '34 Runs', angleInDegrees: 310, distanceRatio: 0.9, color: '#38bdf8' },
    { label: 'Straight Drive', value: '28 Runs', angleInDegrees: 270, distanceRatio: 0.95, color: '#4ade80' },
  ],
});

// 2. Render to MP4
const result = await renderDocuVideo({
  config: docuConfig,
  outputFilename: 'chennai_test_1999.mp4',
});

console.log('✅ Documentary Video Saved to:', result.outputPath);

2. React / Remotion Direct Flow Component

import { HistoricalRivalry } from 'pkp-docu-animator';

export const MyComposition = () => (
  <HistoricalRivalry.HistoricalRivalryFlow
    headline="THE CHENNAI TEST 1999"
    dressingRoomQuote="Dressing room secret quote..."
    player1Name="Sachin Tendulkar"
    player2Name="Wasim Akram"
    bowlerName="Saqlain Mushtaq"
    speedKmph={88}
  />
);

🔑 Key Policies & Guarantees

• Zero Hardcoded Text Fallbacks: If a title, quote, or headline prop is omitted, it strictly evaluates to '' or null, ensuring no dummy text leaks onto the video output.
• Persistent UUID v4 Scene Identifiers: Scene IDs are generated persistently via generateUUID() (crypto.randomUUID()) per flow run rather than on every render frame.
• Dynamic Plugin System: Extend new engines via EngineRegistry.getInstance().registerEngine(...) or templates via TemplateManager.getInstance().registerTemplate(...).