webreel

webreel

CLI that records scripted browser videos as MP4, GIF, or WebM files from JSON configs.

Define steps (clicks, key presses, drags, pauses) and webreel drives a headless Chrome instance, captures screenshots at ~60fps, adds cursor animation, keystroke overlays, and sound effects, and encodes the result with ffmpeg.

Installation

npm install webreel

Quick Start

npx webreel init --name my-video --url https://example.com
npx webreel record

Examples

custom-theme - Demonstrates fully customizing the cursor overlay and keystroke HUD appearance using a code editor page.

drag-and-drop - Demonstrates dragging elements between positions on a kanban board.

form-filling - Demonstrates typing into form fields and clicking a submit button, simulating a login flow.

gif-output - Demonstrates outputting the recording as an animated GIF instead of the default MP4.

hello-world - The simplest possible webreel example. Opens a landing page and clicks the call-to-action button.

keyboard-shortcuts - Demonstrates pressing key combos and displaying them in the keystroke HUD overlay. Uses a code editor page as the target.

mobile-viewport - Demonstrates recording at mobile device dimensions using a finance app interface.

modifier-clicks - Demonstrates clicking elements with modifier keys held down, simulating multi-select in a file manager.

multi-demo - Demonstrates defining multiple videos in a single config file, each producing its own output from the same page.

page-scrolling - Demonstrates scrolling the page and scrolling within a specific container element on a blog post layout.

screenshots - Demonstrates capturing PNG screenshots at specific points during a recording. Useful for generating static marketing assets or documentation images alongside videos.

shared-steps - Demonstrates using include to share common setup steps across videos. The shared steps dismiss a cookie consent banner before the main video steps run.

webm-output - Demonstrates outputting the recording as a WebM video using VP9 encoding.

Commands

webreel init

Scaffold a new config file.

webreel init
webreel init --name login-flow --url https://myapp.com
webreel init --name hero -o hero.config.json

Option	Default	Description
--name <name>	my-video	Video name
--url <url>	https://example.com	Starting URL
-o, --output <file>	<name>.json	Output file path

webreel record

Record videos.

webreel record
webreel record hero login
webreel record -c custom.config.json

When run without arguments, webreel reads webreel.config.json from the current directory and records all videos. Provide video names to record specific videos only.

webreel preview

Run a video in a visible browser window without recording.

webreel preview
webreel preview hero

webreel validate

Check config files for errors without running them.

webreel validate
webreel validate -c custom.config.json

webreel composite

Re-composite videos from stored raw recordings and timelines without re-recording.

webreel composite
webreel composite hero login

Raw video and timeline data are saved in .webreel/raw/ and .webreel/timelines/ during webreel record. Use composite to re-apply cursor overlays, HUD, and sound effects without re-running the browser.

Config format

{
  "$schema": "https://webreel.dev/schema/v1.json",
  "videos": {
    "my-video": {
      "url": "https://example.com",
      "viewport": { "width": 1080, "height": 1080 },
      "defaultDelay": 500,
      "steps": [
        { "action": "pause", "ms": 500 },
        { "action": "click", "text": "Get Started" },
        { "action": "key", "key": "cmd+a", "delay": 1000 }
      ]
    }
  }
}

Config options

Field	Default	Description
url	required	URL to navigate to
baseUrl	""	Prepended to relative URLs
viewport	1080x1080	Browser viewport dimensions
zoom	-	CSS zoom level applied to the page
waitFor	-	CSS selector to wait for before starting
output	<name>.mp4	Output file path (.mp4, .gif, or .webm)
thumbnail	{ time: 0 }	Object with time (seconds) or enabled: false
theme	-	Overlay theme (cursor: { image, size, hotspot }, hud)
include	-	Array of JSON file paths whose steps are prepended
defaultDelay	-	Default delay (ms) after each step

Actions

Action	Fields	Description
pause	ms	Wait for a duration
click	text or selector, optional within, modifiers	Move cursor to an element and click
key	key (e.g. "cmd+z"), optional label, target	Press a key or key combo
type	text, optional target, charDelay	Type text character by character
drag	from and to (each with text/selector/within)	Drag from one element to another
scroll	optional x, y, selector	Scroll the page or a container
wait	selector or text, optional timeout	Wait for an element or text to appear
moveTo	text or selector, optional within	Move cursor to an element
screenshot	output	Save a PNG screenshot
navigate	url	Navigate to a new URL mid-video
hover	text or selector, optional within	Hover over an element (triggers CSS)
select	selector, value	Select a value in a dropdown

All steps (except pause) accept an optional delay field (ms to wait after the step). Use defaultDelay at the top-level or per-video to set a default.

License

Apache-2.0