web-video-presentation

Web Video Presentation

Turn an article or voice-over script into a screen-recordable "video-disguised-as-a-webpage" step by step, with optional voice-over audio synthesis. Output = Vite + React + TS project + per-chapter audio files.

Use Cases

• "I have a script/article, turn it into a video" — script-driven content
• Want a "dynamic PPT"
• 16:9 landscape screen recording, large text, whitespace, every screen with motion
• Teaching / product demo / keynote with cinematic feel
• Bilibili / YouTube / Douyin video content

This skill is methodology + collaboration flow at its core. The scaffold template provides tokens and primitives, but every aesthetic decision (color palette, typography, motion style) should be redesigned for your theme — don't copy blindly.

---

Workflow Overview

Phase 1   Content Writing
   1.1  Identify user input
   1.2  One-shot output: script.md + outline.md
        (voice-over script + development plan)
   ▼
[Checkpoint Plan]      ← Must stop. Align 5 things at once:
                         script / outline / theme / assets / dev mode
   ▼
Phase 2   Web Development
   2.1  Scaffold (with chosen theme)
   2.2  Chapter 1 = main thread + full version (mandatory anchor)
        ▼
        [Hard Node] User approves Chapter 1 ← Cannot skip
        ▼
   2.3  Chapters 2~N (per chosen mode: A chapter-by-chapter / B sequential / C parallel)
   ▼
[Checkpoint Audio]     ← Must stop. Whether to synthesize audio
   ▼
Phase 3   Audio Synthesis (optional)
   ▼
Phase 4   Screen Recording + Post-production

Working directory convention (agent creates/edits in user's current directory):

my-video/
├── article.md          # Required if user provides original text — do not delete! Source of visual details during development
├── script.md           # Required: platform-adapted voice-over script in original language (defines beats)
├── outline.md          # Required: development plan (chapter splits + per-step content + info pool)
└── presentation/       # Scaffolded Vite + React + TS project
    ├── src/chapters/<NN>-<id>/
    │   ├── <Chapter>.tsx     # Visual implementation
    │   ├── <Chapter>.css
    │   └── narrations.ts     # ★ Single source of truth for step count and narration text
    ├── scripts/
    │   ├── extract-narrations.ts   # Scans all narrations.ts → audio-segments.json
    │   ├── synthesize-audio.sh     # Provider-agnostic runner (loops over segments)
    │   └── tts-providers/          # One .sh per provider (2 built-in)
    │       ├── README.md           # Three-function contract + 5 ready code snippets (11labs / edge-tts / say / azure / gcloud)
    │       ├── minimax.sh          # Default provider, uses mmx-cli
    │       └── openai.sh           # Built-in OpenAI TTS (curl + OPENAI_API_KEY)
    ├── audio-segments.json         # Output of extract (review before synthesis)
    └── public/audio/<id>/<N>.mp3   # Optional: synthesized audio

Key: narrations.ts is the single source of truth for step count and audio synthesis.
The maximum N + 1 in if (step === N) in chapter .tsx must equal
narrations.length. This ensures 5 places (script / outline / chapter code /
chapters.ts / audio files) never drift.

---

Mandatory Self-Check Protocol (Throughout This Skill)

For each of the three outputs below, must self-check → fix → then report/proceed:

Output	Self-Check Source
script.md	SCRIPT-STYLE.md three-layer check (form / spirit / read aloud)
outline.md	OUTLINE-FORMAT.md self-check
Single chapter implementation	CHAPTER-CRAFT.md completion self-check

Execution method (descending capability, prefer more isolated approach):

1. Agent Teams (best): Spin up a separate reviewer agent, give it "output file
   path + corresponding checklist + key context", have it check item by item and strictly report conclusions
   (which items pass / which fail + evidence + rewrite suggestions).
2. subAgent (next best): If no Teams capability but subagent is available, use subagent
   with the same process.
3. Self-check (fallback): If neither above is available, strictly check item by item
   yourself — no eyeballing and approving.

Hard rule: After getting conclusions, fix all failing items first, then report to user "done

• self-check results + what was fixed". Reporting raw conclusions without fixing = violation.

---

Phase File Reading Guide

Different phases read different files. In long sessions, the agent tends to forget principles, especially
Phase 2.4 "implement single chapter" which repeats N times — re-read core constraints each time.

Phase	Must Read (every time)	Read Once / On Demand
Phase 1.1-1.2 Content Writing	references/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.md (user original, if any)	——
Checkpoint Plan: Choose Theme	——	themes/*/theme.json (dynamically read all, list + bestFor recommendation + descriptionZh); references/THEMES.md (if user wants to understand theme system)
Phase 2.1 Scaffold	——	SKILL.md this section once
Phase 2.4 Implement Single Chapter (×N times, called by 2.2 / 2.3)	references/CHAPTER-CRAFT.md single entry — Part 0 ten principles / Part 1 five questions to start / Part 2 relation→action decision tree / Part 3 visual toolbox / Part 4 timing reference / Part 5 anti-AI anti-patterns / Part 6 code hard rules (including narrations.ts mandatory constraints) / Part 7 completion self-check / Part 8 feedback quick reference + current theme's themes/<id>/theme.json + current chapter's outline.md paragraph + article.md corresponding paragraph for this chapter + asset list	references/EXAMPLES/ (structural reference, not copy template); references/THEMES.md full token contract
Phase 3 Audio Synthesis	references/AUDIO.md (includes narrations.ts → segments.json → any provider flow, built-in minimax + openai)	templates/scripts/tts-providers/README.md (when switching provider / custom TTS)
Phase 4 Screen Recording + Post-production	references/RECORDING.md (includes ?auto=1 auto recording)	——
Choose / Create / Customize Theme	——	references/THEMES.md

When writing a chapter, only read CHAPTER-CRAFT.md. Ten principles / start self-prompting /
decision tree / anti-AI anti-patterns / completion self-check all merged into this single entry. EXAMPLES/
is not required — design freely based on content first, only refer if stuck (look at structure, not copy).

---

Phase 1 — Content Writing (One-Shot Output)

1.1 Identify User Input

User Provides	What to Do
Original article (written / WeChat article / paper / blog)	One-shot output script.md + outline.md (1.2), go through Checkpoint Plan
Direct voice-over script / video script	Save as script.md, one-shot output outline.md (1.2 simplified), go through Checkpoint Plan
Nothing, just "make a video about X topic"	Ask back: provide some material or outline first. Skill does not generate content for the user

1.2 One-Shot Output: script.md + outline.md

Both outputs completed in one thinking pass:

1. Generate script.md: Following references/SCRIPT-STYLE.md
   rules, convert article into a platform-adapted voice-over script in the original language. Keep article.md — it is
   the detail source for outline info pools and chapter visuals (dual-source principle).
2. Generate outline.md: Following references/OUTLINE-FORMAT.md
   rules, split chapters + steps + extract info pool from each chapter's first paragraph.

Boundaries of outline (key):

Outline Must Write	Outline Must Not Write
Chapter splits / per-chapter step count / estimated time	Specific animation types (blur clear / wipe / spring)
Per-step screen content (hero / data / tagline / list items)	CSS implementation details (filter / SVG / clip-path)
Chapter-level info pool: numbers / quotes / cases / tags extracted from article	Timing values (don't write ~2.5s / 80~120ms)
Step-level relation name prefix ("contrast" / "progressive list" / "quote" etc., optional hint)	Micro-rhythm like continuous micro-motion / staggered timing

Why outline does not write animations: Hardcoding animations turns the chapter agent into a translation machine;
leaving whitespace lets the chapter agent freely design per step using CHAPTER-CRAFT.md's
"content-driven decision tree", achieving true video feel. See
CHAPTER-CRAFT.md Part 0 Principle 7.

After saving, must self-check before entering Checkpoint Plan: Follow the "Mandatory Self-Check Protocol" above for
script.md / outline.md respectively (prefer Agent Teams → subAgent → self-check),
fix according to conclusions, then enter Checkpoint Plan.

---

Checkpoint Plan — Align 5 Things at Once (Hard Node)

After script.md + outline.md are written, must stop. User confirms 5 things at this single node.

Agent's Preparation at This Point

1. Read all themes/*/theme.json to get nameZh / descriptionZh / bestFor
   / mood — do not hardcode the list
2. Based on script.md content type / keywords / tone, proactively pick 2~3
   best-matching recommendations from themes (match bestFor field)
3. Scan the "asset list" section at the end of outline.md

Summary Template (skeleton, agent fills as appropriate)

Content plan complete, output files:
  📄 article.md     {if user provided original, keep}
  📄 script.md      {X} chars / ~{T} min
  📄 outline.md     {N} chapters / {M} steps + per-chapter info pool + asset list at end

Chapter overview:
  1. <id>     <chapter title>    <S> steps ~<T>s
  2. ...

Next, align 5 things at once:

  1. Script (script.md) — any changes?
     Edit the file directly, or tell me the direction verbally.

  2. Development plan (outline.md) — any changes? Focus on:
     - Chapter splits / step count / estimated time reasonable? (reasonable: 30~60s per chapter)
     - Per-step screen content clear?
     - First paragraph of each chapter "info pool" has enough article details for visuals?
     - Asset list at end complete?

  3. Which theme? My recommendations:
     ★ <Recommendation 1: nameZh (id)> — because <bestFor match>; <descriptionZh summary>
     ★ <Recommendation 2 / 3>
     Others available: <remaining themes, nameZh + one-liner>
     Or I can create a new theme for you (see references/THEMES.md).

  4. How to prepare real assets? Rough list of images needed for this video: <rough list>
     a) I pick from <existing asset path>   b) You provide   c) All placeholders

  5. Which development mode?

     **Chapter 1 must be done on main thread + user approved regardless of mode** (mandatory anchor).
     Difference starts from Chapter 2:

     A) Default · Chapter-by-chapter approval (recommended)
        Pause and approve after each chapter → risk controlled / steadiest pace
     B) Sequential after Chapter 1 (no parallel)
        Chapters 2~N done sequentially on main thread, then unified approval → medium speed / suitable if agent doesn't support parallel
     C) Parallel after Chapter 1 (subagent)
        Chapters 2~N done in parallel using subagents → fastest / user controls parallelism (how many at once)
        ⚠️ Style may vary between chapters (expected, theme constraints provide fallback)

After receiving feedback:

• If script/outline needs changes: edit files directly, ping once done (or verbally describe agent changes)
• Theme must be confirmed before entering Phase 2. User says "you pick" → take your first recommendation,
  tell user what you chose and why, give chance to change
• Mode confirmed → enter Phase 2

---

Phase 2 — Web Development

2.1 Scaffold

bash <path-to-web-video-presentation>/scripts/scaffold.sh \
  ./presentation \
  --theme=<user-selected theme id>

bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes

Custom theme → first create a themes/<my-theme>/ following references/THEMES.md
"Create New Theme" flow, then --theme=<my-theme>.

The scaffold includes a 01-example demo. Delete it before writing real content for Chapter 1:

rm -rf presentation/src/chapters/01-example

And remove EXAMPLE_CHAPTER import and array entry from presentation/src/registry/chapters.ts.

2.2 Chapter 1 — Main Thread + Mandatory Approval

Core: Chapter 1 = full version done in one go (pacing + visuals + real assets complete).
No "skeleton version" concept — Chapter 1 must be a sample that user can directly approve.

Why Chapter 1 must be on main thread:

• It is the first application of CHAPTER-CRAFT.md guidance to current
  theme + current subject
• If guidance has blind spots / theme colors / font tokens insufficient, Chapter 1 will expose them —
  human feedback can fix guidance / adjust theme, early fix costs least
• Subsequent chapters (sequential or parallel) will reference Chapter 1's code pattern, so Chapter 1 =
  "style anchor for this project (no need for chapter-to-chapter consistency, but each chapter itself must be convincing)"

After completing Chapter 1, must stop and wait for user approval:

Chapter 1 <id> done, dev server running at localhost:5173.

Approval focus:
  □ Visual tone correct? Matches <theme nameZh> expectations?
  □ Pacing correct? Some steps too fast / too slow / too thin on info?
  □ Content-driven animations in place? Or some steps have mindless entrance animations?
  □ Dual-source principle: Does the screen have details from article that script didn't narrate?
  □ Anti-AI check: Any purple-pink gradients / rounded colored borders / fake illustrations / emoji?

Tell me issues, I'll fix specifically. Say "continue" when OK, I'll proceed with Chapters 2+ per chosen mode.

2.3 Chapters 2~N — Per Chosen Mode

Common rules for all modes: Each chapter independently developed following CHAPTER-CRAFT.md.
Style does not need to be consistent across chapters — theme color / font tokens ensure visual
unity; free variation in animation / pacing / visual demonstration is by design.

Mode A · Default · Chapter-by-Chapter Approval

Chapter 2 done → pause for approval → OK → Chapter 3 → pause → ... → Chapter N. Each chapter
independently approved, issues fixed on the fly, lowest risk, steadiest pace. Default when user doesn't explicitly choose a mode.

Mode B · Sequential After Chapter 1

Chapter 2 → Chapter 3 → ... → Chapter N done sequentially on main thread, then unified approval at end.
Medium speed, suitable for environments where agent doesn't support parallel tasks.

Mode C · Parallel After Chapter 1 (subagent)

Use subagents to complete Chapters 2~N in parallel, max parallelism controlled by user ("4 at once"
/ "2 at once"). Fastest, but style may vary between chapters — this is expected, because:

1. Each subagent cannot see other subagents' output, so cannot mechanically align
2. Chapter code is physically separated (each chapter in its own folder / own CSS prefix), won't
   interfere with each other
3. Theme tokens ensure visual unity (colors / fonts / hero numbers / cards / dividers
   character / decorations), style won't drift
4. Style inconsistency = breathing feel of handcrafted video (multi-voice / multi-perspective)

Parallel subagent prompt must include:

• Current chapter's outline paragraph (including info pool)
• Path to references/CHAPTER-CRAFT.md (single required read — visual demonstration requirements +
  progressive reveal + dual-source principle + anti-AI + code red lines + completion self-check all in this one file)
• Current theme's theme.json descriptionZh / mood / bestFor (for tone reference
  only; animation / timing / font size / emoji are free for chapter agent to decide)
• Chapter 1 code as "code style" reference (not "visual copy target")
• Hard rules: each chapter independent CSS prefix (.cd- / .mg- / .pm- / ...);
  do not modify chapters.ts; after completion run npx tsc --noEmit

Important: Regardless of mode chosen, user can switch modes mid-way at any time. After Chapter 2 is OK,
user can say "parallel for the rest" / "chapter-by-chapter for the rest".

2.4 Implement Single Chapter (Every Chapter Must Follow)

Detailed guidance in references/CHAPTER-CRAFT.md —
single required entry, covering: visual demonstration requirements / progressive reveal / content selection / dual-source principle
/ basic video demonstration aesthetics / anti-AI / code red lines / completion self-check.

Core points (detailed in CHAPTER-CRAFT.md):

• Every chapter must have CSS / SVG / Canvas / JS visual demonstration, no pure-text chapters
• Progressive reveal: Lists / items must be 1 item = 1 step, no showing all at once
• Dual-source principle: Pacing follows script (order cannot be changed), details come from original article (info pool +
  this chapter's article paragraph)
• Go through completion self-check item by item, if not meeting standards, go back and fix — follow the "Mandatory Self-Check Protocol" above
  (prefer Agent Teams → subAgent → self-check), fix before reporting chapter delivery to user

2.5 Bump STORAGE_KEY After Major Changes

After modifying chapters.ts (adding / deleting / reordering chapters, or changing narrations.ts
length in a chapter), bump presentation/src/hooks/useStepper.ts's
STORAGE_KEY (e.g., v4 → v5) to prevent persisted cursor from landing on a non-existent step.

---

Checkpoint Audio — Whether to Synthesize Audio (Hard Node)

After Phase 2 ends, must stop and ask user:

Web pages done, {N} chapters {M} steps, dev server running at localhost:5173.

Synthesize audio for "auto-play recording"?
  ✓ Yes → Scan all chapters' narrations.ts to produce audio-segments.json,
           call TTS provider to synthesize one mp3 per step into public/audio/.
           After synthesis, use ?auto=1 mode for one-take screen recording (audio-video naturally synced).
           Two built-in providers:
             • minimax (mmx-cli)    — default, stable Chinese voice
             • openai  (OPENAI_API_KEY) — curl-based, most already have key
           Other backends (ElevenLabs / edge-tts free / macOS say offline /
           Azure / Google) see ready snippets in scripts/tts-providers/README.md.
  ✗ No → Skip Phase 3, go directly to Phase 4 for manual recording + post-production dubbing.

If yes → Phase 3. If no → directly Phase 4.

---

Phase 3 — Audio Synthesis (Optional)

Detailed flow in references/AUDIO.md. Simplified version:

cd presentation
npm run extract-narrations   # Scan all narrations.ts → audio-segments.json
# Let user glance at audio-segments.json to confirm text is correct
npm run synthesize-audio                       # Default minimax provider, incremental
# Or use built-in openai (requires OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# Or custom: write a scripts/tts-providers/<name>.sh, see README.md in that directory

After synthesis, tell user: output location / total segments / which segments have abnormal duration (too long = that step needs splitting;
too short = text too thin) — give one last chance to calibrate pacing. Then enter Phase 4.

---

Phase 4 — Screen Recording + Post-production

See references/RECORDING.md for details. Two paths:

Scenario	Recommended Path
Phase 3 audio synthesized	Auto mode one-take: Open localhost:5173/?auto=1 in browser → press SPACE → entire video plays automatically → stop recording → trim head/tail → done, no post-production audio syncing needed
Phase 3 skipped	Default Manual mode: click to advance manually → post-production with any editing tool to add voice-over

After Phase 3 / Checkpoint Audio, agent proactively tells user the suitable recording path.

---

Ten Principles (One-Liner Summary)

Full expansion in references/CHAPTER-CRAFT.md
Part 0 — Refer there when writing chapters, below is just an index.

#	Principle	One-Liner
1	16:9 Fixed Stage	Content at 1920×1080 + transform scale, no responsive
2	Global Step Counter	Chapter is a pure function of step, no timers
3	Each Step Fills Screen	if (step === N) return <FullScene />
4	Script Beat = Step	One beat = one step = one focused idea
5	Hidden Corner Controls	Progress bar / page indicator default opacity 0
6	Stage Has No Chrome	No header / footer / page number / brand bar
7	Content-Driven Animation	Find internal action first, fall back to entrance animation only if none; use continuous micro-motion sparingly
8	Multi-Point Progressive Reveal	1 item = 1 step, no synchronous stagger of N items
9	Single Theme for Entire Video	No background color flip between chapters; colors / fonts via tokens, other dimensions free per chapter
10	Dual-Source Principle	Script defines beats, article defines visual density (via info pool)

---

Common User Feedback Quick Reference

Simplified table in references/CHAPTER-CRAFT.md
Part 8 "Common Feedback Quick Reference". Key: First identify which layer (pacing / visual / content
/ code), then fix the smallest slice, do not redo the entire chapter.

---

Related Resources

Labeled by "when to read" to avoid reading everything at once:

File	When to Read	Content
references/SCRIPT-STYLE.md	Phase 1.2 required	Article → script rules, platform variants
references/OUTLINE-FORMAT.md	Phase 1.2 required	outline.md field spec, naming conventions, chapter splitting, info pool
references/CHAPTER-CRAFT.md	Phase 2.4 single required entry per chapter	Part 0 ten principles / Part 1 five questions to start / Part 2 relation→action decision tree / Part 3 visual toolbox / Part 4 timing / Part 5 anti-AI anti-patterns / Part 6 code hard rules / Part 7 completion self-check / Part 8 feedback quick reference
references/EXAMPLES/	Optional — look at structure	Chapter structure examples (hook / list-reveal / case-tech-review); not copy templates
references/THEMES.md	When choosing / creating / customizing theme	Full token contract + built-in theme list + creation flow
references/AUDIO.md	Phase 3 only	Provider-agnostic audio synthesis flow, built-in minimax usage, provider switching path, troubleshooting
templates/scripts/tts-providers/README.md	When switching / adding TTS provider	Three-function contract + 2 built-in (minimax / openai) + 5 ready code snippets (ElevenLabs / edge-tts / macOS say / Azure / Google)
references/RECORDING.md	Phase 4 only	Recording tools + post-production compositing
themes/	Checkpoint Plan / Phase 1.2 browse	Built-in themes (each with theme.json + tokens.css)
scripts/scaffold.sh	Phase 2.1 run once	One-click project scaffold