video-script-structure

---

name: video-script-structure description: Video script YAML schema V3 with beats[], storyboard[] sentence-level sync, progressive reveals, annotated images, screen mockups, and word-level subtitles for the Remotion video engine. Use when creating video scripts or converting blog content to video format. allowed-tools:

• Read
• Write
• Glob
• Grep

---

Video Script Structure Skill V3

Purpose

Defines the structure and conventions for creating video scripts with multi-beat visual cuts that render in the Royalti Remotion video engine. Scripts are YAML files consumed by BlogExplainerVideo composition.

---

Fireship.io Style Principles

1. Rapid-fire delivery — Dense information, no filler
2. Visual-first — Every concept gets multiple visual beats, never static for >4 seconds
3. Humor and personality — Not dry or corporate
4. Time-constrained — 3-8 minutes for educational content
5. Fast cuts — Average shot length 2-4 seconds, alternating visual types

Timing Conventions

Section Type	Duration	Beats
Hook	10-15 seconds	1 visual (short, impactful)
Main Section	30-60 seconds	5-6 beats (cut every 3-5s)
CTA	10-20 seconds	1 visual (end_screen)

---

YAML Schema V2

Canonical Field Names

• narration — Voiceover text (NOT script)
• beats — Array of visual beats per section (NOT singular visual)
• Hook and CTA keep single visual (they're short enough)

Root Structure

video:
  title: string          # Video title (60 chars max for YouTube)
  slug: string           # URL-friendly identifier
  duration: string       # "M:SS" format (informational)
  style: string          # "educational" | "tutorial" | "explainer"

hook:
  narration: string      # Spoken content (multiline)
  visual: Visual         # ONE visual for the hook
  duration: number       # Optional, in seconds

sections:
  - id: string           # Unique section identifier
    title: string        # Section heading (shown as LowerThird)
    narration: string    # Spoken content for the full section
    beats:               # Array of visual beats (REQUIRED, min 1)
      - visual: Visual
        duration: number     # Seconds (2-8). Optional, auto-distributed if omitted.
        transition: string   # See Beat Transitions below. Default: "cut"
        emphasis: boolean    # Extra visual punch. Default: false
    duration: number     # Optional total section duration override

cta:
  narration: string
  visual: Visual         # Should be type: end_screen
  duration: number       # Optional

metadata:               # Optional
  source: string
  date: string
  tags: string[]