Overview
The composite command rebuilds final video output from previously recorded raw footage and timeline data. This lets you change visual overlays, sound effects, or output format without re-recording the browser automation.
Syntax
webreel composite [videos...] [options]
Arguments
| Argument | Type | Description |
|---|
videos | string[] | Optional. Specific video names to composite. If omitted, all videos are composited. |
Options
| Option | Type | Default | Description |
|---|
-c, --config <path> | string | webreel.config.json | Path to the configuration file |
How It Works
When you run webreel record, webreel stores:
- Raw recording -
.webreel/raw/<video-name>.mp4 - the unprocessed screen capture
- Timeline data -
.webreel/timelines/<video-name>.timeline.json - cursor movements, clicks, keystrokes, and timing
The composite command reads these files and generates the final output with:
- Cursor overlays and animations
- Keystroke HUD display
- Sound effects (if configured)
- Custom theme styling
Usage Examples
Composite all videos
Rebuild all videos from stored data:
Composite specific videos
Rebuild only the hero video:
Rebuild multiple specific videos:
webreel composite hero login signup
Use a custom config file
Composite videos using a different config:
webreel composite -c custom.config.json
Output
Composited videos are saved to the same location as webreel record:
- Default:
videos/<video-name>.mp4
- Custom: path specified in the
output field of your config
Thumbnails are also regenerated if thumbnail generation is configured.
When to Use
Use composite when you want to:
Change visual styling
Update cursor appearance, HUD colors, or theme without re-recording:
{
"videos": {
"demo": {
"theme": {
"cursor": {
"color": "#3b82f6",
"size": 48
},
"hud": {
"backgroundColor": "rgba(0, 0, 0, 0.8)"
}
}
}
}
}
Toggle sound effects
Add or remove sound effects:
{
"videos": {
"demo": {
"sfx": {
"enabled": true,
"click": "path/to/click.wav",
"keypress": "path/to/keypress.wav"
}
}
}
}
{
"videos": {
"demo": {
"output": "demo.gif"
}
}
}
.mp4, .gif, .webm
Faster iteration
Compositing is much faster than re-recording because:
- No browser automation needed
- No waiting for page loads or animations
- Only ffmpeg encoding runs
Typical composite times: 5-15 seconds vs 30-120 seconds for recording.
Error Handling
Raw video not found
If you see:
Error: Raw video not found: .webreel/raw/hero.mp4. Run "webreel record" first.
Timeline not found
If you see:
Error: Timeline not found: .webreel/timelines/hero.timeline.json. Run "webreel record" first.
Invalid timeline file
If the timeline JSON is corrupted:
Error: Invalid timeline file: .webreel/timelines/hero.timeline.json
Workflow Example
A typical workflow using composite:
# Initial recording (takes 60 seconds)
webreel record hero
# Tweak cursor color in config
# Edit webreel.config.json
# Fast re-composite (takes 10 seconds)
webreel composite hero
# Adjust HUD position
# Edit webreel.config.json again
# Fast re-composite again
webreel composite hero
Use composite to rapidly iterate on visual styling. Record once, then tweak appearance and re-composite as many times as needed.
Composite uses the current config file to determine theme, sfx, and output settings. Make sure your config changes are saved before running composite.
What Cannot Be Changed
Composite cannot change:
- The actual browser automation steps
- Page content or interactions
- Viewport dimensions
- Video duration or frame timing
To change these, you must re-record with webreel record.