Skip to main content

​
Configuration File Structure

Webreel uses a webreel.config.json file to define video recordings. The config includes global defaults and a videos object mapping video names to their configurations.

​
JSON Schema Support

Include a $schema field for IDE autocompletion and validation: 
{
  "$schema": "https://webreel.dev/schema/v1.json",
  "videos": {
    "my-video": {
      "url": "https://example.com",
      "steps": []
    }
  }
}

​
Top-Level Fields

​
$schema
string
JSON Schema URL for IDE autocompletion. Use https://webreel.dev/schema/v1.json.
​
outDir
string
default:"videos/"
Default output directory for all videos. Can be overridden per-video with the output field.
​
baseUrl
string
default:""
Prepended to relative video URLs. Useful for recording multiple pages on the same domain.
{
  "baseUrl": "https://myapp.com",
  "videos": {
    "login": { "url": "/login", "steps": [] },
    "dashboard": { "url": "/dashboard", "steps": [] }
  }
}
​
viewport
object | string
default:"{ width: 1080, height: 1080 }"
Default browser viewport dimensions. Accepts an object with width and height, or a preset name.
​
theme
ThemeConfig
Default cursor and HUD overlay customization. See Theme Customization.
​
sfx
SfxConfig
Sound effects configuration for click and key events.
{
  "sfx": {
    "click": 2,
    "key": "./assets/mechanical-key.mp3"
  }
}
​
include
string[]
Array of paths to JSON files containing steps. These steps are prepended to all videos.
{
  "include": ["./steps/dismiss-cookie-banner.json"],
  "videos": {
    "demo": {
      "url": "https://example.com",
      "steps": [
        { "action": "click", "text": "Get Started" }
      ]
    }
  }
}
Example steps/dismiss-cookie-banner.json:
[
  { "action": "wait", "selector": ".cookie-banner" },
  { "action": "click", "text": "Accept" }
]
​
defaultDelay
number
default:"undefined"
Default delay in milliseconds to wait after each step (except pause). Can be overridden per-video or per-step.
​
clickDwell
number
default:"100"
Milliseconds to pause between mouse-down and mouse-up during clicks. Affects visual timing of click animations.
​
videos
object
required
Object mapping video names to their configurations. See Video Options.
{
  "videos": {
    "hero-demo": {
      "url": "https://example.com",
      "steps": []
    },
    "feature-tour": {
      "url": "https://example.com/features",
      "steps": []
    }
  }
}

​
Configuration Inheritance

Per-video fields inherit from top-level defaults:
  • baseUrl - Videos use top-level baseUrl unless they define their own
  • viewport - Videos use top-level viewport unless they define their own
  • theme - Videos use top-level theme unless they define their own
  • sfx - Videos use top-level sfx unless they define their own
  • defaultDelay - Videos use top-level defaultDelay unless they define their own
  • clickDwell - Videos use top-level clickDwell unless they define their own
  • include - Videos use top-level include unless they define their own

​
Complete Example

{
  "$schema": "https://webreel.dev/schema/v1.json",
  "outDir": "recordings/",
  "baseUrl": "https://myapp.com",
  "viewport": { "width": 1920, "height": 1080 },
  "defaultDelay": 500,
  "theme": {
    "cursor": {
      "size": 32,
      "hotspot": "center"
    },
    "hud": {
      "background": "rgba(0, 0, 0, 0.8)",
      "fontSize": 48,
      "position": "bottom"
    }
  },
  "sfx": {
    "click": 2,
    "key": 3
  },
  "include": ["./steps/setup.json"],
  "videos": {
    "homepage": {
      "url": "/",
      "steps": [
        { "action": "pause", "ms": 500 },
        { "action": "click", "text": "Get Started", "delay": 1000 }
      ]
    },
    "dashboard": {
      "url": "/dashboard",
      "viewport": { "width": 1366, "height": 768 },
      "steps": [
        { "action": "pause", "ms": 500 },
        { "action": "click", "selector": ".profile-menu" }
      ]
    }
  }
}

​
Creating a Config File

Use the init command to scaffold a new config: 
webreel init
webreel init --name login-flow --url https://myapp.com/login
webreel init --name hero -o hero.config.json

Build docs developers (and LLMs) love

Get started for freeTalk to us