/video-script Command

The /video-script command generates a complete beat-by-beat video script with narration, terminal commands, timing, and visual cues.

Overview

This is the core creative command that transforms a video topic into a production-ready beat sheet. The output is a detailed script that serves as the blueprint for your entire video.

Command: /video-script <topic>

Allowed Tools: Read, Glob, Grep, Write

What It Does

1. Analyzes Topic Requirements

   • Reads relevant documentation
   • Identifies key concepts to cover
   • Determines logical flow

2. Creates Beat-by-Beat Structure

   • Introduction beat
   • Main content beats (typically 5-8 beats)
   • Conclusion beat

3. Generates Detailed Beat Information

   • Duration estimate per beat
   • Narration text (what to say)
   • Terminal commands (what to type)
   • Browser actions (what to click)
   • Visual notes (what to highlight)

Usage

/video-script <topic>

Parameters:

• <topic>: The video topic name (from /video-topics or your own)

Example:

/video-script installation-and-setup

Beat Sheet Structure

Each generated beat includes:

## Beat N: [Beat Name]
**Duration**: [X] seconds
**Visual**: [Terminal/Browser/Split]
**Browser Tab**: [URL or N/A]

**Narration**:
"[Exact text to speak in the video]"

**Terminal Commands**:
```bash
command --to-execute

Browser Actions:

• [Specific actions to perform]

Visual Notes:

• [Highlighting, pauses, speed adjustments]

## Example Output

See the complete example: [Sample Beat Sheet](../examples/sample-video.md)

Quick preview:

```markdown
# Video: Installation and Setup

**Duration**: 5 minutes
**Target Audience**: Beginner
**Prerequisites**: macOS, Linux, or Windows computer

---

## Beat 1: Introduction
**Duration**: 15 seconds
**Visual**: Terminal - Clean iTerm2 window
**Browser Tab**: N/A

**Narration**:
"Welcome to MyProject! In this video, we'll walk through the complete
installation and setup process. By the end, you'll have MyProject up
and running on your machine. Let's get started!"

**Terminal Commands**:
```bash
# No commands in intro

Visual Notes:

• Show clean terminal
• Display project logo or name

## Best Practices

### Narration Writing

1. **Conversational Tone**: Write like you're teaching a friend
   - ✅ "Great! Now let's create a directory for our project"
   - ❌ "The next step requires directory creation"

2. **Clear Instructions**: Be explicit about what's happening
   - ✅ "We'll use npm to install globally, which makes it available anywhere"
   - ❌ "Install the package"

3. **Appropriate Pacing**: Match narration to action duration
   - For quick commands: Brief narration
   - For long operations: More explanation

4. **Helpful Context**: Explain why, not just what
   - ✅ "Let's verify you have Node 18+, which MyProject requires"
   - ❌ "Check your Node version"

### Terminal Commands

1. **Executable Commands**: Every command should actually work
2. **Safe Commands**: No destructive operations without warnings
3. **Realistic Output**: Consider what output will appear
4. **Proper Sequencing**: Commands in logical order

### Visual Notes

1. **Highlight Important Output**: Draw attention to key information
2. **Pause for Comprehension**: Give viewers time to read output
3. **Speed Adjustments**: Note when to speed up boring parts
4. **Scene Transitions**: Smooth switches between terminal and browser

## Configuration

Customize beat sheet generation in `.training-video-generator/config.json`:

```json
{
  "videoSettings": {
    "defaultDuration": 7,
    "introDuration": 15,
    "conclusionDuration": 20,
    "beatDurationRange": [20, 60]
  },
  "narrationStyle": "conversational",
  "visualStyle": "clean-terminal",
  "includePostProduction": true
}

Output Location

Beat sheets are saved to:

scripts/video-scripts/[topic]-beat-sheet.md

When to Use

• After identifying a topic with /video-topics
• When you want to script a video manually
• Before recording to ensure proper flow
• When planning multi-video series

Tips

1. Review and Edit: Generated scripts are starting points - refine them
2. Test Commands: Verify all commands work in a clean environment
3. Time It Out: Read narration aloud to check pacing
4. Consider Audience: Adjust complexity based on target viewers
5. Plan B-Roll: Note opportunities for overlays or graphics

Post-Production Notes

Beat sheets include a section for post-production guidance:

## Post-Production Notes

**Editing**:
- Speed up Beat 4 (npm install) to 2x speed
- Trim any long pauses between beats

**B-Roll Suggestions**:
- Project logo during introduction
- Architecture diagram during initialization

**Music** (optional):
- Light, upbeat background music at 10% volume during intro/outro
- No music during technical steps

**Captions/Subtitles**:
- Add subtitles for all narration
- Highlight terminal commands in monospace font

Troubleshooting

"Beat sheet seems rushed"

Problem: Narration is too brief or beats are too short

Solution:

• Increase defaultDuration in config
• Manually adjust beat durations in the generated file
• Add more explanatory narration

"Commands don't work together"

Problem: Commands assume state from previous beats

Solution:

• Review beat sequence for logic
• Add setup commands to earlier beats
• Include verification commands between steps

"Narration sounds robotic"

Problem: Text is too formal or technical

Solution:

• Rewrite in conversational style
• Read aloud to check naturalness
• Add transitions and connective phrases

"Missing visual cues"

Problem: Visual notes section is sparse

Solution:

• Think about what viewers need to see
• Add highlights for important output
• Note when to pause or speed up
• Include scene transition guidance

Next Steps

After generating and reviewing your beat sheet:

1. Edit the beat sheet: Refine narration, adjust timing
2. Run /video-automate: Generate automation scripts
3. Run /video-narrate: Create TTS audio files
4. Record the video: Follow the beat sheet timing
5. Run /video-merge: Combine recording with audio

Related Commands

• /video-topics - Discover video topics
• /video-automate - Generate automation scripts
• /video-narrate - Create TTS narration
• Beat Sheet Guide - Writing effective beat sheets