narrec

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


---

Demo

``bash
$ 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

`bash
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:

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

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

`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:

`bash
narrec record demo.narrec.yaml
`

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

Commands

`bash


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

$3

`yaml
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
`

$3

| 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" |

$3

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

$3

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

$3

`yaml
- type:
selector: "input[name=email]"
text: "user@example.com"
delay: 50ms # Typing speed (ms between keystrokes)
clear: true # Clear field before typing
`

Voice Providers

$3

Uses the built-in say command. Available voices:
- daniel - British English male
- samantha - American English female
- alex - American English male
- karen - Australian English female

`bash


List all macOS voices


say -v '?'
`

$3

Set OPENAI_API_KEY environment variable:

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

$3

Set ELEVENLABS_API_KEY environment variable:

`yaml
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.

$3

`bash


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
`

$3

| 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 |

$3

Automatically fix quality issues with safety levels:

`bash


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

$3

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

$3

`bash


JSON report

narrec quality demo.mp4 --json report.json

Markdown report

narrec quality demo.mp4 --markdown report.md
`

$3

`bash


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

`typescript
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.

`bash


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.