walter-io/vibecoding-remotion

Remotion Story Video

Turn "a story" into a 1080p video performance: read the story → extract the theme's personality → design a unique visual language for this theme → break it into "segments (chapters) → shots (scene beats)" → design scene animations shot by shot that match the plot's emotion → text beat-sync performance → render → spot-check.

First Principle: Style Serves the Theme, No Fixed Template

The pipeline and methodology are universal; the visual style must be redesigned per theme.

• For each new story, start with a "theme personality analysis": What are the keywords of this story (nostalgia? passion? suspense? fairy tale? technology?) → derive the color palette, font personality, motion rhythm, and scene art style
• Examples (for reference only, not rules): Warm nostalgia → serif Song typeface + cream white/gold + slow gentle light; Passionate sports → bold sans-serif + high-saturation red/black + fast cuts with heavy beats; Sci-fi → cool colors + monospace + glitch/scan-line effects; Fairy tale → rounded fonts + macaron colors + bouncy spring animations
• Do not carry the style of the previous project into the next; when the user does not specify, first provide 1-2 style options for them to choose from

Core Philosophy

• Scene tells the story: Every shot's visual must match the emotion and action of its corresponding sentence (earthquake sentence → shaking classroom, cheer sentence → flag-waving crowd, queue sentence → barrier lines) — mismatching (sad line with festive visuals) is the biggest taboo
• Scenes use programmatic animations (silhouettes / geometric shapes + sine-phase-staggered motion, driven frame-by-frame), not static images; animation density is determined by the theme (soft themes: sparse and slow, energetic themes: dense and fast)
• Typography is part of the performance: font personality, text hierarchy, and keyword highlight colors are all derived from the theme

Pipeline (Five Steps, Fixed Order)

1. Style Derivation: Theme keywords → color palette / font personality / motion rhythm / scene art style → (if not specified, present options to the user)
2. Story Decomposition: Split by plot arc into segments (chapters) → shots (1-2 lines per shot); distill a short golden sentence at the end of each segment for a summary card; clean trailing punctuation at line ends (universal clean_tail() function)
3. Timeline gen_assets.py → timeline.json (shot start/end, layout, beat points; default MIN_SHOT 3.5s for slow cuts, adjustable per theme)
4. Assertion Audit + Sync check_views.py (mapping coverage/out-of-bounds) + verify_timeline.py (line-end punctuation = 0 / minimum shot length >= 3.0s / summary card duration / age label — thresholds adjustable per theme) — any failure blocks rendering → sync-timeline.mjs
5. Render + Spot Check npx remotion render → ffmpeg extract keyframes for review (scene emotion / text hierarchy / animation timing)

Hard Rules (Theme-Independent, Always Valid)

• No punctuation at line ends (including em-dashes): universal cleanup function + assertion = 0
• Visuals must strictly match dialogue emotions; if SHOT_VIEW mapping table is changed for different shot splits, re-run the audit
• Animation origin for nested sub-components within a Sequence = the start frame of their containing shot (pass startFrame); otherwise entry animations are silently skipped
• Political symbols must conform to standard specifications (e.g., national flag = red background + one large and four small stars); any approximate graffiti is forbidden
• To swap in a real human voiceover: place the WAV file and re-run gen_assets to automatically rebuild the timeline

Existing Assets (Reference Implementations, Reusable and Adaptable)

templates/ comes from a finished project "90s Era Chronicle" (warm nostalgia theme: serif Song typeface + cream white/gold + slow rhythm + crowd silhouette group shots) — this is one example of theme derivation, not the default style:

• Reusable skeleton: gen_assets.py (copy → timeline structure) / check_views.py (mapping audit) / verify_timeline.py (comprehensive assertions) / sync-timeline.mjs / fit.ts (line wrapping) / beat.ts (beat points)
• Visual layer to redesign per theme: theme.ts (color palette / font sizes) / serif.ts (font) / scenes.tsx (scene animations) / TitleCard.tsx / Era.tsx / Intro.tsx (layouts)
• 8 silhouette animation techniques can be migrated: crowd waving flags, watching TV around, earthquake classroom, queue, masked pedestrians, chasing a child to feed, fireworks, lanterns (change color palette and art style to create new scenes)

Detailed Parameters

references/spec.md: Contains the complete parameters of the reference implementation (5 font sizes, 4 entry directions, depth of field, slow fade-in duration, silhouette color scales). New themes can adjust the magnitude for reference, without copying values literally.