narrec

Narrated recordings as code. Automated web app demos with voiceover.

Demo

$ narrec init my-demo.narrec.yaml
✓ Created my-demo.narrec.yaml

$ narrec record my-demo.narrec.yaml
✓ Dependencies OK
✓ Parsed narrec file
✓ Generated voiceover (3 segments, 12s total)
✓ Recorded demo (8 steps)
✓ Created output.mp4

✓ Demo recording complete!

What is narrec?

narrec lets you create professional demo videos by writing YAML scripts. It combines:

• Browser automation (Playwright) - automate clicks, typing, navigation
• Screen recording (ffmpeg) - capture high-quality video
• Text-to-speech - generate natural voiceover narration

No more:

• Re-recording demos when your UI changes
• Awkward pauses and typos in live recordings
• Hiring voice actors or recording your own voice

Just write a script, run narrec record, and get a polished demo video.

Installation

npm install -g narrec

Requirements:

• Node.js 18+
• ffmpeg (for video processing)
• macOS (for say TTS) or OpenAI API key

Quick Start

1. Create a starter template:

narrec init demo.narrec.yaml --url https://myapp.com

2. Edit the generated script (demo.narrec.yaml):

name: "My Product Demo"
output: demo.mp4

settings:
  viewport: { width: 1280, height: 720 }
  voice: moira

steps:
  - navigate: "https://myapp.com"
    wait: networkidle

  - narrate: "Welcome to our product demo."
    duration: 2s

  - narrate: "Let me show you how to create a project."

  - click: "button.new-project"
    highlight: true

  - type:
      selector: "input[name=name]"
      text: "My Project"
      delay: 50ms

  - narrate: "And that's it! Your project is ready."

3. Record the demo:

narrec record demo.narrec.yaml

4. Done! You now have demo.mp4 with automated browser actions and voiceover.

Commands

# Create a starter template
narrec init demo.narrec.yaml

# Record a demo video
narrec record demo.narrec.yaml

# Preview without recording (opens browser)
narrec preview demo.narrec.yaml

# Generate voiceover audio only
narrec voiceover demo.narrec.yaml -o audio.mp3

# List available voices (with audio preview)
narrec voices
narrec voices --preview moira

# Validate a script
narrec validate demo.narrec.yaml

# Check video quality
narrec quality output.mp4 --preset strict

# Auto-fix quality issues
narrec quality output.mp4 --fix --iterate

Script Reference

Settings

settings:
  viewport:
    width: 1280
    height: 720
  browser: chromium  # chromium, firefox, webkit
  voice: moira       # macOS voice or OpenAI voice (default: moira)
  voiceProvider: macos  # macos, openai, elevenlabs
  fps: 30

Step Types

| Step | Description | Example | |------|-------------|---------| | narrate | Speak text with TTS | narrate: "Hello world" | | navigate | Go to a URL | navigate: "https://example.com" | | click | Click an element | click: "button.submit" | | type | Type text into input | type: { selector: "input", text: "hello" } | | wait | Pause for duration | wait: 2s | | screenshot | Capture screenshot | screenshot: state.png | | scroll | Scroll page/element | scroll: { y: 500 } | | hover | Hover over element | hover: ".menu-item" |

Narrate Options

- narrate: "This is spoken text"
  duration: 3s  # Optional: override auto-calculated duration

Click Options

- click: "button.submit"
  highlight: true  # Show visual indicator before clicking

Type Options

- type:
    selector: "input[name=email]"
    text: "[email protected]"
    delay: 50ms   # Typing speed (ms between keystrokes)
    clear: true   # Clear field before typing

Voice Providers

macOS (default)

Uses the built-in say command. Available voices:

• daniel - British English male
• samantha - American English female
• alex - American English male
• karen - Australian English female

# List all macOS voices
say -v '?'

OpenAI

Set OPENAI_API_KEY environment variable:

settings:
  voiceProvider: openai
  voice: alloy  # alloy, echo, fable, onyx, nova, shimmer

ElevenLabs

Set ELEVENLABS_API_KEY environment variable:

settings:
  voiceProvider: elevenlabs
  voice: rachel

Video Quality Validation

narrec includes a comprehensive quality validation system that checks your videos and can automatically fix common issues.

Quick Check

# Validate a video
narrec quality demo.mp4

# Use strict preset for professional demos
narrec quality demo.mp4 --preset strict

# Verbose output with details
narrec quality demo.mp4 -v

Quality Presets

| Preset | Resolution | FPS | Score Threshold | Use Case | |--------|------------|-----|-----------------|----------| | strict | 1920×1080 | 30+ | 85+ | Professional demos | | relaxed | 854×480 | 15+ | 60+ | Quick drafts | | mobile | 720×1280 | 24+ | 70+ | Vertical video | | gif | 640×360 | 10-15 | 70+ | Animated GIFs |

Auto-Fix

Automatically fix quality issues with safety levels:

# Safe fixes only (audio normalization, trimming)
narrec quality demo.mp4 --fix

# Include moderate fixes (codec conversion, black frame removal)
narrec quality demo.mp4 --fix --fix-level moderate

# Iterative improvement (keep fixing until quality passes)
narrec quality demo.mp4 --fix --iterate --max-iterations 3

Safety Levels:

• safe - Audio normalization, silence trimming, FPS reduction
• moderate - Codec conversion, black frame removal, duration trim
• risky - Resolution upscale, bitrate re-encode

What Gets Checked

Technical:

• Resolution, frame rate, bitrate
• Video/audio codecs
• Audio levels (clipping, too quiet)
• File integrity

Creative:

• Black frames at start/end
• Freeze frames
• Audio/video sync
• Dead air (silence)
• Pacing

Reports

# JSON report
narrec quality demo.mp4 --json report.json

# Markdown report
narrec quality demo.mp4 --markdown report.md

Integrate with Recording

# Record with automatic quality check
narrec record demo.narrec.yaml --quality-check --quality-preset strict

Examples

See the examples directory for complete demo scripts.

Programmatic API

import { parseNarrecFile, NarrecRunner, VoiceoverGenerator, VideoComposer } from 'narrec';

const config = await parseNarrecFile('demo.narrec.yaml');

// Generate voiceover
const voiceover = new VoiceoverGenerator('daniel');
const audioPath = await voiceover.generateFromSteps(config.steps);

// Run browser automation and record
const runner = new NarrecRunner({ headless: false });
const videoPath = await runner.run(config);

// Compose final video
const composer = new VideoComposer();
await composer.compose(videoPath, audioPath, 'output.mp4');

Why narrec?

| Feature | narrec | Loom | Arcade | VHS | |---------|--------|------|--------|-----| | Automated browser actions | ✅ | ❌ | ❌ | ❌ | | TTS voiceover | ✅ | ❌ | ❌ | ❌ | | Code-based (version control) | ✅ | ❌ | ❌ | ✅ | | Terminal recording | ❌ | ❌ | ❌ | ✅ | | Free & open source | ✅ | ❌ | ❌ | ✅ |

Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Clone the repo
git clone https://github.com/tn-pisama/narrec.git
cd narrec

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start -- record examples/simple.narrec.yaml

Roadmap

• [x] Video quality validation with auto-fix
• [ ] Terminal recording support (like VHS)
• [ ] AI-generated scripts from product docs
• [ ] Cloud rendering service
• [ ] More TTS providers
• [ ] GIF output optimization
• [ ] Visual callouts and annotations

License

MIT - see LICENSE

Support

• GitHub Issues
• GitHub Sponsors

Made with love for DevRel teams everywhere.