Overview
The record command is the core command of webreel. It executes the steps defined in your configuration file, drives a headless Chrome instance, captures screenshots at 60fps, and encodes the result using ffmpeg.
Syntax
webreel record [videos...] [options]
Arguments
| Argument | Type | Description |
|---|
videos | string[] | Optional. Specific video names to record. If omitted, all videos in the config are recorded. |
Options
| Option | Type | Default | Description |
|---|
-c, --config <path> | string | webreel.config.json | Path to the configuration file |
--verbose | boolean | false | Log each step as it executes during recording |
--watch | boolean | false | Re-record automatically when config files change |
--dry-run | boolean | false | Print the resolved configuration and step list without recording |
--frames | boolean | false | Save raw frames as JPEGs in .webreel/frames/ for debugging |
Usage Examples
Record all videos
Record all videos defined in your webreel.config.json:
Record specific videos
Record only the videos named hero and login:
webreel record hero login
Use a custom config file
Specify a different configuration file:
webreel record -c custom.config.json
Watch mode for development
Automatically re-record when your configuration changes:
This watches both the main config file and any included step files. The command debounces changes with a 300ms delay.
Verbose output
See detailed logging of each step as it executes:
Dry run
Preview the resolved configuration without recording:
Output example:
Resolved configuration:
outDir: videos/
viewport: 1920x1080
defaultDelay: 500ms
1 video(s):
hello-world
url: https://example.com
viewport: 1920x1080
steps: 3 step(s)
0: pause 500ms
1: click text="Get Started"
2: key "cmd+a" delay: 1000ms
Save debug frames
Save raw JPEG frames during recording for debugging:
Frames are saved to .webreel/frames/<video-name>/.
Combine options
Combine multiple options for a specific workflow:
webreel record hero --verbose --watch
Output
By default, videos are saved to:
videos/<video-name>.mp4 (or the path specified in outDir)- Thumbnail:
videos/<video-name>.jpg (if thumbnail generation is enabled)
Raw recordings and timeline data are stored in:
.webreel/raw/<video-name>.mp4.webreel/timelines/<video-name>.timeline.json
These raw files allow you to re-composite videos later using the composite command without re-recording.
When to Use
Use record when you:
- Want to generate final video output from your configuration
- Need to capture all browser interactions and animations
- Are creating marketing videos, demos, or documentation
- Want to iterate on your video with
--watch mode
Use --dry-run before recording to verify your configuration is correct. This saves time by catching errors early.
Chrome and ffmpeg are automatically downloaded to ~/.webreel on first use if not already installed. Use webreel install to pre-install them.