skindhu/educational-video-creator

Educational Video Creator

Create professional educational videos with Kurzgesagt/回形针 visual style using Remotion.

Prerequisites

This skill requires remotion-best-practices for Remotion technical implementation.

Check and install (MUST complete before Phase 1):

# Check if already installed, install if not
npx skills list 2>/dev/null | grep remotion-best-practices || npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices

Once installed, read the remotion-best-practices skill to load Remotion API details into context. This is essential — without it, Phase 4 code will have incorrect Remotion API usage.

External dependencies (needed for Phase 4.5 audio generation):

# ffmpeg (provides ffprobe for audio duration measurement)
brew install ffmpeg        # macOS
# apt install ffmpeg       # Linux

# edge-tts (Python TTS engine for narration generation)
pip install edge-tts

Project Setup

This skill creates videos in a dedicated remotion_video subdirectory within the current workspace.

First-time setup (recommended — non-interactive):

# Create video project directory
mkdir -p remotion_video
cd remotion_video

# Initialize without interactive prompts
npm init -y
npm install remotion @remotion/cli @remotion/google-fonts @remotion/transitions react react-dom
npm install -D typescript @types/react

# Create minimal project structure
mkdir -p src public/audio/narration

Then create the required entry files:

• src/Root.tsx — Main composition registry
• src/index.ts — Remotion entry point with registerRoot(Root)
• remotion.config.ts — Remotion configuration
• tsconfig.json — TypeScript config

Alternative (interactive — may block in automated environments):

mkdir -p remotion_video && cd remotion_video
npx create-video@latest --blank
npm install

Note: npx create-video may prompt for project name, package manager, etc. In CLI/automation contexts, use the non-interactive method above to avoid blocking.

Existing project:

cd remotion_video
npm install  # Ensure dependencies are installed

Project structure:

your-workspace/
├── remotion_video/           # Video project root
│   ├── src/
│   │   ├── Root.tsx          # Main composition registry
│   │   └── YourVideo/        # Video-specific components
│   │       ├── index.tsx
│   │       ├── scenes/
│   │       └── components/
│   ├── public/               # Static assets
│   └── package.json
└── ... (other workspace files)

Quick Start

1. Setup project → create remotion_video directory if needed
2. Gather requirements → confirm topic, audience, duration
3. Write script → complete narrative with story arc and pacing
4. Create storyboard → break script into visual scenes with animation specs
5. Design visuals → apply style guide, create SVG components
6. Implement animations → code scenes in Remotion
7. Quality assurance → auto-check, auto-fix, auto-start preview

⚠️ Context Recovery Protocol

Every conversation turn may follow a context loss (compaction, new session). Before doing ANY work:

1. Check if remotion_video/PROGRESS.md exists
   • If YES → Read it completely to determine current phase and last completed step
   • If NO → This is a new project, proceed to Phase 1
2. Read supporting files referenced in PROGRESS.md (only if that phase is marked complete):
   • remotion_video/script.md (if Phase 1.5+ completed)
   • remotion_video/storyboard.md (if Phase 2+ completed)
   • src/<Composition>/constants.ts (if Phase 3+ completed — contains COLORS, SCENES, NARRATION, AUDIO_SEGMENTS)
3. Verify files listed in "Files Created" section actually exist on disk
4. Resume from the first unchecked item in the current phase

Skipping this protocol causes repeated work or file corruption. Always run it first.

Progress Tracking — Mandatory Protocol

⚠️ This protocol is NON-NEGOTIABLE. Skipping updates causes context loss and repeated work.

Maintain remotion_video/PROGRESS.md using progress-template.md. Create it at Phase 1 start. Log decisions in the Decisions table and add every created file to "Files Created".

Checkpoint Rule

Every time you complete a checkbox item in PROGRESS.md, you MUST immediately:

1. Mark the item [x] and add brief notes
2. Update the "Current State" section (Current Phase + Current Step)
3. Then — and only then — proceed to the next item

Do NOT batch multiple items. One item done → one update → next item.

Phase Transition Gate

Before starting any new Phase, you MUST:

1. Read PROGRESS.md and verify ALL items in the previous phase are [x]
2. Update "Current Phase" to the new phase
3. If any previous item is unchecked, complete it first

Workflow

Phase 1: Requirements Gathering

⚠️ First: Complete the Prerequisites section (install remotion-best-practices skill and read it). Then create remotion_video/PROGRESS.md from progress-template.md and fill in Project Info.

Before starting, confirm these essential details with the user:

• Topic: What concept/subject to explain?
• Audience: Who is watching? (children/adults, beginners/experts)
• Language: Chinese/English/other?
• Duration: Short (1-3min), Medium (3-5min), or Long (5-10min)?
• Key points: What must the viewer learn?

For detailed question templates, see requirements-guide.md.

Phase 1.5: Script Writing

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.

Write a complete narrative script before designing the storyboard. This phase focuses purely on storytelling — what to say and how to say it well — without worrying about visual specs, frame numbers, or animation parameters.

IMPORTANT: Write the FULL narration text — every word that will be spoken. Do NOT write summaries, bullet points, or placeholders. The script is the final spoken content.

The script must include:

1. Core message — one-line summary, learning objectives
2. Narrative strategy — apply techniques from script-and-narration.md:
   • Entry angle (question / scenario / challenge / story)
   • Core metaphor that runs through the entire video
   • Knowledge scaffolding order (what depends on what)
   • Emotional curve (curiosity → understanding → wonder → satisfaction)
3. Full narration text — complete word-for-word script for every chapter:
   • Include emphasis markers (bold for stress, italic for softer tone)
   • Mark pauses with [.] (short), [..] (medium), [...] (long), [PAUSE] or [BEAT] (dramatic) — see script-and-narration.md Part 3 for duration semantics
   • Add visual intents after each chapter (1-2 sentences describing what viewers should see — enough for Phase 2 to design scenes, but no animation specs)
4. Pacing notes — where to speed up, slow down, and pause
5. Self-review — run through the checklist in script-and-narration.md before presenting to user

Quality gate: Present the complete script to the user for approval. Do NOT proceed to Phase 2 until the user explicitly approves the narrative.

Why script first:

• Separates "what to tell" from "how to show" — two different creative activities
• LLM produces better narratives when not simultaneously calculating frame ranges
• Pure text is cheap to iterate; storyboard with animation specs is expensive to revise
• Users can easily review "is the story good?" without wading through technical details

Output: Save the approved script as remotion_video/script.md

See script-and-narration.md for video structure templates, narrative techniques, writing techniques, and TTS notes.

Phase 2: Storyboard Design

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.

Convert the approved script into a production-ready storyboard. The script provides what to say; the storyboard defines how to show it.

Input: Completed script (approved in Phase 1.5)

Tasks:

1. Break script chapters into visual scenes (5-15 scenes)
2. Assign narration text from the script to each scene
3. Design visual layers for each scene (background / midground / foreground / UI)
4. Add frame-level animation specifications (spring, easing, timing)
5. Define visual-narration sync points
6. Plan the asset inventory (SVG components, colors, typography)

The cognitive load is much lower than creating everything from scratch — the narrative is already decided, so you only need to focus on visual execution.

Output: Save the completed storyboard as remotion_video/storyboard.md for design traceability and iteration reference.

See storyboard-template.md for templates. See script-and-narration.md Part 4 for subtitle formatting and TTS notes.

Phase 3: Visual Design

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.

Apply the Kurzgesagt/回形针 style. Concrete steps:

1. Choose color palette — Select from design-tokens.ts Section 1 or create a custom palette matching the topic
2. Create constants.ts — Define COLORS, TYPOGRAPHY, SCENES, NARRATION, and estimated AUDIO_SEGMENTS following design-tokens.ts Section 3
3. Set up fonts — Use Remotion's loadFont() from @remotion/google-fonts (see design-tokens.ts Section 2 for reference)
4. Create shared SVG components — Build reusable visual elements (icons, illustrations, decorative elements) following svg-components.md
5. Design scene layouts — Plan visual layers (background / midground / foreground / UI) per scene following visual-principles.md

Style principles:

• Flat design with subtle gradients
• Bold, saturated color palette
• Geometric shapes with rounded corners (rx/ry)
• Clean sans-serif typography

See style-guide.md for complete visual standards. See visual-principles.md for composition and layout.

Phase 4: Animation Production

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates. Log key file paths in "Files Created".

Implement scenes using Remotion:

1. Create SVG components for visual elements
2. Use useCurrentFrame() for all animations
3. Apply appropriate easing (spring for natural motion)
4. Add scene transitions

Subtitle & narration rules (critical for Phase 4.5 compatibility):

• All narration text must be stored in the NARRATION object in constants.ts — never hardcode text directly in scene TSX files
• Create an estimated AUDIO_SEGMENTS in constants.ts with approximate timing. Phase 4.5 will overwrite it with real audio-based timing
• Subtitle components must reference AUDIO_SEGMENTS.sceneKey — never use inline segment arrays with hardcoded frame numbers
• AUDIO_SEGMENTS 中的 startFrame/endFrame 必须使用场景本地帧号（每个场景从 SCENE_PAD=15 开始），不是全局帧号。因为 AudioLayer 和 SubtitleSequence 都在场景的 <Sequence> 内部运行，useCurrentFrame() 返回的是本地帧号。如果使用全局帧号，后续场景的字幕会延迟或完全不显示
• This ensures rebuild-timeline.ts --write in Phase 4.5 can update timing without modifying any scene files

Visual-narration alignment rules (prevents animation-subtitle desync):

• 每个与旁白内容对应的视觉元素（图标出现、箭头展开、图表绘制等），其 startFrame 必须从 AUDIO_SEGMENTS 对应段的 startFrame 派生，不能凭"视觉节奏"硬编码
• 正确模式：const liftArrowStart = AUDIO_SEGMENTS.forces[0].startFrame;（升力箭头在旁白说"升力"时出现）
• 错误模式：const liftArrowStart = 30;（凭感觉写的帧数，和旁白无关）
• 纯装饰性动画（背景粒子、环境氛围）不受此约束，可以自由定时
• Phase 4 使用估算 AUDIO_SEGMENTS；Phase 4.5 rebuild-timeline 更新真实时间后，因为代码引用的是变量而非硬编码数字，视觉动画会自动同步
• 参考 animation-guide.md "Narration-Synced Animation" 章节的实现模式

Element sizing rules (prevents "Thumbnail Syndrome" — tiny elements on a large canvas):

• 参考 visual-principles.md "Content Area Utilization" 确保内容填充画布（核心内容 ≥ 安全区 60%）
• 组件默认尺寸参考 svg-components.md（图标 ≥96px，流程节点 ≥160px 高，标签 ≥40px）
• 图表/流程图应占据内容区域大部分面积，避免在 1920×1080 画布上缩成缩略图

Background rules (prevents transparent/checkerboard frames during transitions):

• The main composition must have a persistent <AbsoluteFill> background layer (using COLORS.background) that sits behind all scenes and never participates in transitions
• Each scene component must also have its own solid background as the first child element
• During fade() transitions, both scenes have reduced opacity — without a persistent background, transparent frames appear as a checkerboard pattern in preview and black in renders
• See animation-guide.md "Preventing Transparent Frames" for the implementation pattern

Visual richness rules (prevents PPT-like output):

• 每个场景必须有至少一个 非文字的视觉主体元素（SVG 插画、图表、动画图形等）。纯文字标签 + 方块不是合格的视觉内容
• 流程图/因果链必须用 图标或插画 配合文字，不能只用纯色方块装文字。参考 svg-components.md "Illustrated Flow Node" 模式
• 每个场景应有 环境氛围层（粒子、光晕、纹理等），参考 style-guide.md Ambient Effects 章节
• SVG 插画应体现 Kurzgesagt 风格：圆角几何形状（rx/ry）、扁平化但有层次（多 path 叠加）、柔和渐变（linearGradient/radialGradient）、适当描边
• 参考 visual-principles.md "Show, Don't Tell" 原则：能用图示表达的概念不要用文字方块
• 参考 scene-template.tsx 中 ForceDiagramScene 的 SVG 飞机插画作为具象插画的最低质量标准

Color rules (critical for Phase 5 style-scan compliance):

• All colors must be referenced via the COLORS object from constants.ts (e.g., COLORS.accent.rose) — never write hex values directly in TSX files
• The only exception is rgba() for opacity variations (e.g., rgba(0, 0, 0, 0.7) for subtitle backgrounds)
• This prevents the common issue where style-scan reports dozens of "color not in approved palette" warnings

See design-tokens.ts Section 3 for the complete constants.ts structure (COLORS, SCENES, NARRATION, AUDIO_SEGMENTS, font loading). See svg-components.md for component patterns. See animation-guide.md for timing and easing.

Phase 4.5: Audio Generation

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.

完成动画编码后，生成视频音频并同步时间线：

1. 生成 TTS 音频 — 用 generate-tts.ts 从 NARRATION 提取文本生成 mp3
2. 重建时间线 — 用 rebuild-timeline.ts --write 根据实际音频时长更新 constants.ts
3. 调整动画关键帧 — 按 newDuration / oldDuration 比例缩放
4. 添加背景音乐 — 免版税 BGM 到 public/audio/bgm.mp3
5. 创建 AudioLayer — 播放旁白 + BGM 的组件
6. 集成并验证 — AudioLayer 必须在 TransitionSeries 外部

详细步骤、命令参数、AudioLayer 模板见 audio-guide.md。

Phase 5: Quality Assurance

⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.

完成编码后，执行自动质量检查流程：

1. 代码扫描 → 检查样式合规性（字号、颜色、安全区域等）
2. 截图审查 → 渲染关键帧，视觉检查
3. 自动修复 → 根据检查报告修复问题，循环直到通过
4. 启动项目 → 所有检查通过后，自动启动 Remotion 预览

详细检查步骤和规则见 quality-checklist.md。

Phase 6: Final Export

After preview looks correct, render the final video:

cd remotion_video
npx remotion render src/index.ts <CompositionName> out/video.mp4

Options:

• --codec h264 (default) or --codec h265 for smaller file size
• --quality 80 to 100 (default: 80)
• --scale 1 (1080p) — use --scale 2 for 4K if source assets support it
• Add --log verbose if debugging render issues

The output file will be at remotion_video/out/video.mp4.

Video Structure

Standard educational video structure:

1. Hook (5-10s)      - Attention-grabbing question or statement
2. Intro (10-20s)    - Topic introduction
3. Content (main)    - Core explanation, broken into segments
4. Summary (10-20s)  - Key takeaways
5. Outro (5-10s)     - Call to action or closing

See script-and-narration.md Part 1 for detailed structure templates.

Key Principles

Content Clarity

• One concept per scene
• Build complexity gradually
• Use visual metaphors for abstract ideas

Visual Simplicity

• Minimal elements on screen
• Clear visual hierarchy
• Consistent style throughout

Animation Purpose

• Every animation serves understanding
• Avoid decorative motion
• Sync with narration pace

Reference Files

| File | When to Use | |------|-------------| | requirements-guide.md | Starting a new video project (Phase 1) | | script-and-narration.md | Video structure, script writing, narration, subtitle/TTS (Phase 1.5 + 2) | | storyboard-template.md | Converting script into visual scenes (Phase 2) | | style-guide.md | Designing visual elements (Phase 3 + 4) | | visual-principles.md | Layout and composition decisions (Phase 3 + 4) | | animation-guide.md | Implementing animations (Phase 4) | | svg-components.md | Creating reusable components (Phase 4) | | audio-guide.md | TTS 生成、时间线重建、AudioLayer 集成详细步骤 (Phase 4.5) | | quality-checklist.md | Quality assurance + style check rules (Phase 5) | | design-tokens.ts | Color palettes, typography presets, constants.ts template (Phase 3) | | progress-template.md | 执行进度跟踪模板 (全流程) | | scene-template.tsx | 场景组件模板 (Phase 4) | | subtitle-sequence-template.tsx | 字幕序列组件模板 (Phase 4) | | common-icons.tsx | 通用 SVG 图标组件 (Phase 4) | | generate-tts.ts | 字幕提取 + TTS 音频生成脚本 (Phase 4.5) | | rebuild-timeline.ts | 音频时长测量 + 时间线重建脚本 (Phase 4.5) | | style-scan.ts | 代码样式扫描脚本 (Phase 5) | | render-keyframes.ts | 关键帧批量截图脚本 (Phase 5) | | shared.ts | 脚本共享函数（内部依赖，无需直接调用） |