Animation Engine MVP

Deterministic, code-only vertical video engine built with Next.js + TypeScript + Remotion. No AI image generation is used. All visuals are generated via code (typography, geometry, particles, comic panels, and data visuals).

Product Demo Video

GitHub inline preview uses a lightweight web version:

• Watch web preview demo
• Download full-quality demo

Core Features

• JSON-driven project input: meta, theme, audio, scenes[]
• 9:16 MP4 rendering pipeline via Remotion
• In-app preview with Remotion Player
• 5 reusable scene templates:
  • kinetic-text
  • geometric-motion
  • particle-flow
  • comic-panel
  • data-pulse
• Theme engine tokens:
  • palette, font, background mode, motion preset, line thickness, glow intensity
• Timing engine:
  • frame-safe start/duration handling + transitions
• Motion presets:
  • snappy, cinematic, elastic
• Subtitle + voiceover + BGM support
• Dynamic visual layer:
  • keyword-to-SVG/icon mapping
  • stick-figure choreography
  • custom SVG upload and scene-level reuse
  • auto-crawl SVG library from public icon sources
• Auto generation library:
  • auto-save project/storyboard/transcript after agent pipeline
  • auto-attach rendered MP4 after export
  • keeps newest 100 items (older items are pruned automatically)
  • download-ready URLs for project JSON, transcript, and final video
• Cloud concurrency guard:
  • in cloud mode, heavy endpoints are capped to 5 concurrent jobs by default
  • overflow requests are queued briefly, then return 429 with Retry-After
• Audio-duration alignment:
  • scene timeline is stretched/compressed to match input audio duration
  • each scene remains capped at 5 seconds
  • optional transition mode: smooth or none
• Minimal editor UI:
  • JSON panel, script compiler panel, preview player, preset selector, render trigger

Scriptimate-Inspired Extensions

After researching devforth/scriptimate, two patterns were applied:

1. Script-to-timeline workflow

• Added a lightweight scene DSL compiler (compileSceneScriptToProject) inspired by Scriptimate’s script-first animation flow.
• You can write scene lines and compile directly into project JSON.

2. Deterministic render cache

• Added project-hash based render caching (hashProject) so repeated renders of identical input reuse existing MP4 output.

Architecture

src/
  data/
    demo-project.json
  lib/
    schema/
      index.ts
      project-schema.ts
  remotion/
    index.ts
    Root.tsx
    compositions/
      AnimationEngineComposition.tsx
      AnimationVideo.tsx
      RemotionRoot.tsx
      scenes/
        KineticTextScene.tsx
        GeometricMotionScene.tsx
        ParticleFlowScene.tsx
        ComicPanelScene.tsx
        DataPulseScene.tsx
    components/
      AnimationEditor.tsx
      AudioLayers.tsx
      BackgroundLayer.tsx
      SceneContainer.tsx
      SceneTitleBlock.tsx
      SubtitlesLayer.tsx
    engine/
      constants.ts
      motion-presets.ts
      project-hash.ts
      render-video.ts
      scene-factory.tsx
      script-compiler.ts
      theme-engine.ts
      timing.ts
      types.ts
    styles/
      backgrounds.ts
      theme-presets.ts

app/
  page.tsx
  animation-engine/page.tsx
  api/render/route.ts
  api/animation-engine/render/route.ts

Run Locally

npm install
npm run dev

Open:

• http://localhost:3000 (main editor)
• http://localhost:3000/animation-engine (legacy-compatible editor path)

Build

npm run build -- --webpack

Deploy To Cloud (Phone-Ready)

Recommended for this app: Railway or Render using Docker (stable for Remotion MP4 rendering).

1) Push code to GitHub

git add .
git commit -m "prepare cloud deployment"
git push

2) Create a cloud service from the repo

• Railway: New Project -> Deploy from GitHub repo
• Render: New Web Service -> Connect GitHub repo -> choose Docker

3) Set environment variables

Required:

• OPENAI_API_KEY

Optional:

• OPENAI_MODEL (default: gpt-4o-mini)
• OPENAI_TRANSCRIBE_MODEL (default: gpt-4o-mini-transcribe)
• SVG_AUTO_SYNC_ON_LIST (1 by default; set 0 to disable auto-crawl on library refresh)
• SVG_AUTO_SYNC_MINUTES (default 180, minimum 5)
• ANIMATION_ENGINE_MAX_CONCURRENT_USERS (default 5)
• ANIMATION_ENGINE_MAX_QUEUE_SIZE (default 20)
• ANIMATION_ENGINE_QUEUE_TIMEOUT_MS (default 25000)
• ANIMATION_ENGINE_CONCURRENCY_LIMIT_FORCE (1 to enforce limit on localhost too)

4) Runtime settings

• Port: platform default ($PORT) is already supported
• Memory: use at least 2 GB (recommended 4 GB) for smoother video rendering
• Instance: keep at least 1 instance always on (avoid cold starts for mobile usage)
• To keep a strict shared cap of 5 active users, run a single app instance with ANIMATION_ENGINE_MAX_CONCURRENT_USERS=5

5) Use on phone

• Open the generated HTTPS URL from Railway/Render
• Go to /animation-engine
• Add to Home Screen on iOS/Android for app-like access

Preview + Render

1. Edit script or JSON in the editor.
2. Click Compile Script (optional) then Validate + Apply.
3. Preview updates in Remotion Player.
4. Click Render MP4.

Routes:

• POST /api/render (JSON response with output URL)
• POST /api/animation-engine/render (returns MP4 file stream)
• GET/POST /api/animation-engine/svg-assets (list/upload custom SVG assets)
• POST /api/animation-engine/svg-assets/sync (manual crawler sync)
• POST /api/animation-engine/agent-pipeline supports:
  • audioDurationMs for duration matching
  • transitionMode (smooth / none)
  • audio upload saved to /public/uploads and injected as voiceover source
• GET/POST /api/animation-engine/library
  • list and save generation library entries
  • auto-prunes old entries beyond 100 newest items
  • storage path: /public/generation-library/<item-id>/...

Remotion Commands

npm run remotion:studio
npm run render:demo

How To Add A New Scene Type

1. Add scene component in src/remotion/compositions/scenes.
2. Extend sceneTypeSchema in src/lib/schema/project-schema.ts.
3. Register in src/remotion/engine/scene-factory.tsx.
4. Add optional scene data fields in sceneDataSchema.
5. Add sample usage in src/data/demo-project.json.

How To Add A New Style Preset

1. Add preset to src/remotion/styles/theme-presets.ts.
2. Update ThemePresetId union there.
3. Preset selector auto-loads from THEME_PRESET_IDS.

Determinism Notes

• Motion state is frame-based and deterministic.
• Render cache key is computed from stable project JSON hash.
• Same project input yields consistent output.

MVP Scope

• Local JSON + script workflow
• No database
• No authentication
• Single-job render trigger from UI/API

Security Note

• Never commit API keys into source code.
• If an API key was shared in chat/logs, rotate it immediately in OpenAI dashboard.