webreel

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

webreel

webreel records scripted browser demos as MP4, GIF, or WebM with cursor animation, keystroke overlays, and sound effects. You define steps in a JSON config, and webreel drives headless Chrome, captures frames, and encodes with ffmpeg.

webreel 可将脚本化的浏览器演示录制为 MP4、GIF 或 WebM 格式，自带光标动画、按键输入叠加层和音效。你可以在 JSON 配置中定义操作步骤，webreel 会驱动 headless Chrome、捕获帧画面并通过 ffmpeg 编码生成视频。

Installation

安装

Install webreel as a project dependency so the version is pinned in the lockfile. This ensures deterministic recordings across machines and CI.

bash

npm install webreel

If the project already has webreel in its dependencies, skip this step.

将 webreel 安装为项目依赖，这样版本会被锁定在 lockfile 中，确保在不同机器和 CI 环境下的录制结果一致。

bash

npm install webreel

如果项目依赖中已经包含 webreel，可跳过此步骤。

Quick start

快速开始

bash

undefined

bash

undefined

Scaffold a config

生成配置脚手架

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

Edit webreel.config.json with your steps

编辑 webreel.config.json 填写你的操作步骤

Preview in a visible browser (no recording)

在可视化浏览器中预览（不录制）

npx webreel preview my-demo

Record the video

录制视频

npx webreel record my-demo


`npx` resolves to the locally installed version when webreel is in `devDependencies`. Output lands in `videos/` by default (configurable via `outDir`).

npx webreel record my-demo


当 webreel 位于 `devDependencies` 中时，`npx` 会自动解析为本地安装的版本。输出文件默认存放在 `videos/` 目录下（可通过 `outDir` 配置修改）。

CLI commands

CLI 命令

init

Scaffold a new

webreel.config.json

bash

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

Flags:

--name

(video name),

--url

(starting URL),

-o, --output

(output file path).

生成新的

webreel.config.json

脚手架。

bash

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

参数：

--name

（视频名称）、

--url

（起始URL）、

-o, --output

（输出文件路径）。

record

Record one or more videos.

bash

webreel record                        # all videos in config
webreel record hero login             # specific videos by name
webreel record -c custom.config.json  # custom config path
webreel record --watch                # re-record on config change
webreel record --verbose              # log each step
webreel record --dry-run              # print resolved config only
webreel record --frames               # save raw JPEGs to .webreel/frames/

录制单个或多个视频。

bash

webreel record                        # 录制配置中的所有视频
webreel record hero login             # 按名称录制指定视频
webreel record -c custom.config.json  # 指定自定义配置文件路径
webreel record --watch                # 配置变更时自动重新录制
webreel record --verbose              # 打印每个步骤的执行日志
webreel record --dry-run              # 仅打印解析完成的配置
webreel record --frames               # 将原始JPEG帧保存到 .webreel/frames/ 目录

preview

Run steps in a visible browser without recording.

bash

webreel preview
webreel preview hero --verbose

在可视化浏览器中运行步骤，不进行录制。

bash

webreel preview
webreel preview hero --verbose

composite

Re-apply overlays (cursor, HUD, sfx) to existing raw video without re-recording. Useful for tweaking theme settings.

bash

webreel composite
webreel composite hero

为已有的原始视频重新应用叠加层（光标、HUD、音效），无需重新录制。适合调整主题配置时使用。

bash

webreel composite
webreel composite hero

validate

Check config for errors without running anything.

bash

webreel validate
webreel validate -c custom.config.json

检查配置是否存在错误，不执行任何操作。

bash

webreel validate
webreel validate -c custom.config.json

Config structure

配置结构

Config files are auto-discovered as

webreel.config.json

(or

.ts

.mts

.js

.mjs

). Use

-c

to specify a custom path.

配置文件会自动识别为

webreel.config.json

（或

.ts

、

.mts

、

.js

、

.mjs

）。可使用

-c

参数指定自定义路径。

Top-level fields

顶级配置项

Field	Default	Description
`$schema`	-	`"https://webreel.dev/schema/v1.json"`
`outDir`	`"videos/"`	Output directory for rendered videos
`baseUrl`	`""`	Base URL prepended to relative video URLs
`viewport`	`1080x1080`	Default viewport `{ width, height }`
`theme`	-	Cursor and HUD overlay theme
`sfx`	-	Sound effect settings
`include`	-	Array of step file paths prepended to all videos
`defaultDelay`	-	Default delay (ms) appended after each step
`clickDwell`	-	Cursor dwell time (ms) before a click

字段名	默认值	说明
`$schema`	-	`"https://webreel.dev/schema/v1.json"`
`outDir`	`"videos/"`	渲染后视频的输出目录
`baseUrl`	`""`	相对视频URL的前缀地址
`viewport`	`1080x1080`	默认视口尺寸 `{ width, height }`
`theme`	-	光标和HUD叠加层主题
`sfx`	-	音效配置
`include`	-	所有视频都会前置引入的步骤文件路径数组
`defaultDelay`	-	每个步骤执行后追加的默认延迟（毫秒）
`clickDwell`	-	点击前光标停留的时间（毫秒）

Per-video fields

单视频配置项

Each entry in the

videos

map supports:

Field	Default	Description
`url`	required	URL to open (absolute or relative to `baseUrl` )
`viewport`	inherited	Override viewport `{ width, height }`
`zoom`	-	CSS zoom factor
`waitFor`	-	Selector or text to wait for before starting steps
`output`	`"<name>.mp4"`	Output path ( `.mp4` , `.gif` , `.webm` )
`thumbnail`	`{ time: 0 }`	Thumbnail config, or `{ enabled: false }`
`include`	inherited	Step files to prepend
`theme`	inherited	Override theme
`sfx`	inherited	Override sound effects
`defaultDelay`	inherited	Override default delay
`clickDwell`	inherited	Override click dwell
`fps`	`60`	Frame rate
`quality`	`80`	Encoding quality (1-100)
`steps`	required	Array of step objects

videos

映射中的每个条目支持以下配置：

字段名	默认值	说明
`url`	必填项	要打开的URL（绝对路径或相对于 `baseUrl` 的相对路径）
`viewport`	继承自顶级配置	覆盖视口尺寸 `{ width, height }`
`zoom`	-	CSS 缩放比例
`waitFor`	-	开始执行步骤前等待的选择器或文本内容
`output`	`"<name>.mp4"`	输出路径（支持 `.mp4` 、 `.gif` 、 `.webm` ）
`thumbnail`	`{ time: 0 }`	缩略图配置，或设置为 `{ enabled: false }` 关闭缩略图
`include`	继承自顶级配置	要前置引入的步骤文件
`theme`	继承自顶级配置	覆盖主题配置
`sfx`	继承自顶级配置	覆盖音效配置
`defaultDelay`	继承自顶级配置	覆盖默认延迟
`clickDwell`	继承自顶级配置	覆盖点击停留时间
`fps`	`60`	帧率
`quality`	`80`	编码质量（1-100）
`steps`	必填项	步骤对象数组

Videos map

视频映射

Videos are keyed by name in the config:

json

{
  "videos": {
    "hero": { "url": "...", "steps": [...] },
    "login": { "url": "...", "steps": [...] }
  }
}

Record specific videos by name:

webreel record hero login

配置中的视频通过名称作为键进行定义：

json

{
  "videos": {
    "hero": { "url": "...", "steps": [...] },
    "login": { "url": "...", "steps": [...] }
  }
}

可通过名称录制指定视频：

webreel record hero login

。

Step types

步骤类型

Each step has an

action

field. Most steps accept optional

label

delay

(ms after step), and

description

fields.

Action	Key fields	Purpose
`pause`	`ms`	Wait for a duration
`click`	`text` or `selector` , `within` , `modifiers`	Click an element
`type`	`text` , `selector` , `within` , `charDelay`	Type text into an input
`key`	`key` , `target`	Press a key combo (e.g. `"cmd+s"` )
`drag`	`from` , `to` (element targets)	Drag between two elements
`scroll`	`x` , `y` , `selector`	Scroll the page or an element
`wait`	`selector` or `text` , `timeout`	Wait for an element to appear
`moveTo`	`text` or `selector` , `within`	Move cursor to an element
`navigate`	`url`	Navigate to a new URL
`hover`	`text` or `selector` , `within`	Hover over an element
`select`	`selector` , `value`	Select a dropdown value
`screenshot`	`output`	Capture a PNG screenshot

For full field details on every step type, see steps-reference.md.

每个步骤都包含

action

字段。大部分步骤支持可选的

label

、

delay

（步骤完成后的延迟毫秒数）和

description

字段。

Action	关键字段	用途
`pause`	`ms`	等待指定时长
`click`	`text` 或 `selector` 、 `within` 、 `modifiers`	点击某个元素
`type`	`text` 、 `selector` 、 `within` 、 `charDelay`	在输入框中输入文本
`key`	`key` 、 `target`	按下组合键（例如 `"cmd+s"` ）
`drag`	`from` 、 `to` （元素目标）	在两个元素之间拖拽
`scroll`	`x` 、 `y` 、 `selector`	滚动页面或某个元素
`wait`	`selector` 或 `text` 、 `timeout`	等待某个元素出现
`moveTo`	`text` 或 `selector` 、 `within`	将光标移动到某个元素上
`navigate`	`url`	跳转到新的URL
`hover`	`text` 或 `selector` 、 `within`	悬停在某个元素上
`select`	`selector` 、 `value`	选择下拉框选项
`screenshot`	`output`	捕获PNG格式截图

如需查看所有步骤类型的完整字段说明，请参阅 steps-reference.md。

Element targeting

元素定位

Many steps target elements using these fields:

```
text
```
- match by visible text content
```
selector
```
- match by CSS selector
```
within
```
- narrow the search to a parent matching this CSS selector

You can use

text

selector

(not both).

within

is optional and scopes the search.

json

{ "action": "click", "text": "Submit" }
{ "action": "click", "selector": "#submit-btn" }
{ "action": "click", "text": "Submit", "within": ".modal" }

很多步骤通过以下字段定位元素：

```
text
```
- 按可见文本内容匹配
```
selector
```
- 按CSS选择器匹配
```
within
```
- 将搜索范围缩小到匹配该CSS选择器的父元素内

你可以使用

text

或

selector

（不可同时使用）。

within

是可选参数，用于限定搜索范围。

json

{ "action": "click", "text": "Submit" }
{ "action": "click", "selector": "#submit-btn" }
{ "action": "click", "text": "Submit", "within": ".modal" }

Viewport presets

视口预设

Use preset names as string values for

viewport

, or specify

{ width, height }

desktop

(1920x1080),

desktop-hd

(2560x1440),

laptop

(1366x768),

macbook-air

(1440x900),

macbook-pro

(1512x982),

ipad

(1024x1366),

ipad-pro

(834x1194),

ipad-mini

(768x1024),

iphone-15

(393x852),

iphone-15-pro-max

(430x932),

iphone-se

(375x667),

pixel-8

(412x915),

galaxy-s24

(360x780).

你可以为

viewport

使用预设名称作为字符串值，也可以自定义

{ width, height }

：

预设包括：

desktop

(1920x1080)、

desktop-hd

(2560x1440)、

laptop

(1366x768)、

macbook-air

(1440x900)、

macbook-pro

(1512x982)、

ipad

(1024x1366)、

ipad-pro

(834x1194)、

ipad-mini

(768x1024)、

iphone-15

(393x852)、

iphone-15-pro-max

(430x932)、

iphone-se

(375x667)、

pixel-8

(412x915)、

galaxy-s24

(360x780)。

Theme

主题配置

Customize cursor appearance and keystroke HUD:

json

{
  "theme": {
    "cursor": {
      "image": "./cursor.svg",
      "size": 32,
      "hotspot": "center"
    },
    "hud": {
      "background": "rgba(30, 41, 59, 0.85)",
      "color": "#e2e8f0",
      "fontSize": 48,
      "fontFamily": "\"SF Mono\", monospace",
      "borderRadius": 12,
      "position": "top"
    }
  }
}

```
cursor.image
```
- path to a custom cursor SVG or PNG
```
cursor.size
```
- cursor size in pixels
```
cursor.hotspot
```
-
```
"top-left"
```
(default) or
```
"center"
```
```
hud.position
```
-
```
"top"
```
or
```
"bottom"
```

你可以自定义光标外观和按键HUD样式：

json

{
  "theme": {
    "cursor": {
      "image": "./cursor.svg",
      "size": 32,
      "hotspot": "center"
    },
    "hud": {
      "background": "rgba(30, 41, 59, 0.85)",
      "color": "#e2e8f0",
      "fontSize": 48,
      "fontFamily": "\"SF Mono\", monospace",
      "borderRadius": 12,
      "position": "top"
    }
  }
}

```
cursor.image
```
- 自定义光标SVG或PNG的路径
```
cursor.size
```
- 光标尺寸（单位：像素）
```
cursor.hotspot
```
- 光标热点位置，可选
```
"top-left"
```
（默认）或
```
"center"
```
```
hud.position
```
- HUD位置，可选
```
"top"
```
或
```
"bottom"
```

Common patterns

常见使用模式

Shared steps via include

通过include共享步骤

Factor out reusable step sequences (e.g. dismissing a cookie banner) into JSON files:

json

// steps/dismiss-banner.json
{
  "steps": [
    { "action": "wait", "selector": ".cookie-banner", "timeout": 5000 },
    { "action": "click", "selector": ".accept-btn", "delay": 300 }
  ]
}

Reference them in the config:

json

{
  "include": ["./steps/dismiss-banner.json"],
  "videos": { ... }
}

将可复用的步骤序列（例如关闭Cookie弹窗）提取为独立JSON文件：

json

// steps/dismiss-banner.json
{
  "steps": [
    { "action": "wait", "selector": ".cookie-banner", "timeout": 5000 },
    { "action": "click", "selector": ".accept-btn", "delay": 300 }
  ]
}

在配置中引用即可：

json

{
  "include": ["./steps/dismiss-banner.json"],
  "videos": { ... }
}

Multiple videos in one config

单配置多视频

Define several videos in the

videos

map. Shared settings (

viewport

theme

defaultDelay

) are inherited from the top level.

在

videos

映射中定义多个视频，共享的配置（

viewport

、

theme

、

defaultDelay

）会从顶级配置继承。

Environment variables

环境变量

Config values support

$VAR

and

${VAR}

substitution from the environment.

配置值支持从环境变量读取

$VAR

和

${VAR}

格式的变量。

Output formats

输出格式

Set the

output

extension to control format:

.mp4

(default),

.gif

.webm

json

{ "output": "demo.gif" }

通过设置

output

的扩展名控制输出格式：

.mp4

（默认）、

.gif

、

.webm

。

json

{ "output": "demo.gif" }

Tips

使用提示

Always set
```
waitFor
```
on a video to ensure the page is ready before steps run.
Use
```
delay
```
on individual steps to control pacing between actions.
Use
```
--watch
```
during development for automatic re-recording on config changes.
Use
```
composite
```
to iterate on theme/overlay settings without re-recording.
Use
```
--verbose
```
to debug step execution.
Use
```
--dry-run
```
to inspect the fully resolved config (includes, env vars, defaults).
Use
```
zoom
```
to scale up small UIs for readability in the recording.
Start with
```
preview
```
to verify steps work before committing to a full recording.

始终为视频设置
```
waitFor
```
配置，确保步骤执行前页面已加载完成。
为单个步骤设置
```
delay
```
控制操作之间的节奏。
开发过程中使用
```
--watch
```
参数，配置变更时自动重新录制。
使用
```
composite
```
命令调整主题/叠加层配置，无需重新录制。
使用
```
--verbose
```
参数调试步骤执行过程。
使用
```
--dry-run
```
参数查看完全解析后的配置（包括引入文件、环境变量、默认值）。
使用
```
zoom
```
缩放较小的UI，提升录制内容的可读性。
正式录制前先使用
```
preview
```
验证步骤运行正常。

Reference files

参考文件

steps-reference.md - detailed docs for all 12 step types
examples.md - annotated config examples for common use cases

steps-reference.md - 所有12种步骤类型的详细文档
examples.md - 常见使用场景的带注释配置示例