How to Use the web-video-presentation Skill to Create Cinematic Web Presentations

The web-video-presentation skill transforms written scripts into 16:9, click-driven web presentations using a Vite-powered React and TypeScript framework that automatically scales content to the viewport.

This open-source skill, part of the ConardLi/garden-skills repository, provides a complete toolchain for building slideless, video-style presentations where each click or arrow key advances a global step cursor. Unlike traditional slide decks, it renders every step as a full-screen scene within a fixed 1920×1080 coordinate system.

Architecture of the Presentation Framework

The skill is organized into three distinct architectural layers that separate project generation from runtime behavior and content authoring.

Scaffold and Project Generation

The scaffold layer handles project initialization through scripts/scaffold.sh. This CLI script generates a production-ready Vite application, installs dependencies, and injects design tokens from your chosen theme into src/styles/tokens.css. It copies the entire presentation skeleton, including the runtime engine and placeholder chapters, resulting in a runnable project at your specified directory.

Runtime and Presentation Engine

The runtime layer provides the stage canvas and state management. Located in src/hooks/, src/components/, and src/registry/, this engine includes:

• A global step cursor that tracks the current (chapter, step) pair
• Viewport scaling logic that preserves the 16:9 aspect ratio
• Reusable components like Stage, ProgressBar, and AutoToggle
• Keyboard and click handlers for navigation

The runtime persists the cursor position locally, ensuring users resume at the correct step when refreshing the browser.

Content and Chapter Structure

The content layer consists of individual chapters stored in src/chapters/<id>/. Each chapter exports a React component and a narrations.ts file. The narrations array defines the total step count for that chapter—each string represents one visual beat. This strict one-step-per-idea approach eliminates slide bullet accumulation and enforces cinematic pacing.

Getting Started: Scaffolding Your First Presentation

To begin, copy the skill into a directory accessible by your agent or local environment. Generate a new project using the scaffold script with your preferred theme:

# Create a project named "presentation" using the paper-press theme

bash skills/web-video-presentation/scripts/scaffold.sh ./presentation --theme=paper-press

The script automatically:

1. Copies the Vite/React/TypeScript template from skills/web-video-presentation/templates/
2. Installs npm dependencies
3. Writes the selected theme's CSS tokens to src/styles/tokens.css

Navigate into the generated directory and launch the development server:

cd presentation
npm run dev

The presentation serves at http://localhost:5174 with hot module replacement enabled.

Creating Content: Chapters and Narrations

Content authoring follows a file-based routing convention. Each visual beat requires two files within a chapter directory.

Chapter Component Structure

Create a new folder under src/chapters/02-intro/ containing the visual component:

// src/chapters/02-intro/Intro.tsx
export const Intro = () => (
  <Stage>
    <h1>Hello, world!</h1>
    <p>Welcome to the video-style presentation.</p>
  </Stage>
);

The Stage component centers your content within the 1920×1080 coordinate space and handles responsive scaling.

Narration Scripts

Define the step sequence in narrations.ts. The array length determines how many times the user must click to advance past this chapter:

// src/chapters/02-intro/narrations.ts
export const narrations = [
  "Hello, world!",                           // step 1
  "Welcome to the video-style presentation." // step 2
];

Finally, register the chapter in the global registry:

// src/registry/chapters.ts
import { Intro } from '../chapters/02-intro/Intro';
import { narrations as introNarrations } from '../chapters/02-intro/narrations';

export const chapters = [
  {
    id: 'intro',
    component: Intro,
    narrations: introNarrations
  }
];

Adding Audio with Text-to-Speech

The skill includes a pluggable audio pipeline that synthesizes narration files. After defining all narrations.ts files, extract the text and generate audio:

# Compiles all narration strings into audio-segments.json

npm run extract-narrations

# Generates MP3 files using the default MiniMax provider

npm run synthesize-audio

Audio providers reside in skills/web-video-presentation/scripts/tts-providers/ and support MiniMax, OpenAI, or custom implementations. The runtime automatically synchronizes audio playback with the global step cursor when you append ?audio=1 to the URL.

Recording and Playback Modes

The presentation engine offers three interaction modes optimized for different recording scenarios:

• Manual Mode: Click or use arrow keys to advance steps. Controls appear only on hover, keeping the UI clean for screen recordings.
• Semi-Automatic: Add ?audio=1 to the URL. The presentation advances automatically when audio segments finish playing.
• Fully Automatic: Add ?auto=1 to enable timed auto-advance without requiring clicks.

Record the presentation using any screen-capture tool targeting the 16:9 canvas. The fixed aspect ratio ensures consistent output across different display resolutions.

Customizing Themes

The skill ships with 23 built-in themes located in skills/web-video-presentation/themes/. Each theme contains tokens.css (design tokens) and theme.json (metadata describing mood and use cases).

To switch themes after scaffolding, copy the desired tokens file:

cp skills/web-video-presentation/themes/midnight-press/tokens.css src/styles/tokens.css

Available themes include paper-press, midnight-press, and warm-keynote. Theme tokens control typography, color palettes, and spacing values throughout the presentation.

Summary

• The web-video-presentation skill generates Vite/React projects via scripts/scaffold.sh with configurable themes
• Content lives in chapter directories (src/chapters/<id>/) with paired React components and narrations.ts arrays
• The global step cursor enforces one-idea-per-click pacing across a fixed 16:9 canvas
• Audio synthesis integrates through npm run extract-narrations and npm run synthesize-audio
• Three playback modes (manual, ?audio=1, ?auto=1) support different recording workflows
• Theme customization requires only swapping the tokens.css file from the 23 available options

Frequently Asked Questions

What file structure is required for a new chapter?

Create a directory under src/chapters/<id>/ containing a React component file and narrations.ts. The component exports the visual layout, while the narrations file exports an array of strings where each element represents one step. Register both in src/registry/chapters.ts to activate the chapter.

How does the presentation handle different screen sizes?

All components render within a fixed 1920×1080 coordinate system defined by the Stage component. The runtime automatically scales this canvas to fit the viewport while preserving the 16:9 aspect ratio, ensuring consistent typography and positioning across devices.

Can I use a different text-to-speech provider?

Yes. The audio pipeline in scripts/tts-providers/ supports pluggable back-ends. The default implementation uses MiniMax, but you can add custom providers following the interface defined in the scripts directory. Run npm run synthesize-audio after implementing your provider to generate MP3 files.

How do I resume recording from a specific step?

The runtime persists the current (chapter, step) pair to local storage. When you reload the browser, the presentation automatically resumes at the last viewed step. For recording specific segments, manually navigate to the desired step using arrow keys—the persistence ensures you start exactly where intended.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}