webreel

webreel

webreel は、カーソルアニメーション、キー入力オーバーレイ、効果音を付けて、スクリプト化されたブラウザデモを MP4、GIF、または WebM として録画します。JSON 設定でステップを定義すると、webreel がヘッドレス Chrome を操作し、フレームをキャプチャして、ffmpeg でエンコードします。

インストール

バージョンをロックファイルに固定できるよう、webreel をプロジェクトの依存関係としてインストールしてください。これにより、マシンや CI 環境が異なっても、決定論的な録画ができます。

npm install webreel

プロジェクトの依存関係に webreel がすでに含まれている場合は、この手順を省略してください。

前提条件

webreel には Chrome と ffmpeg が必要ですが、手動でインストールする必要はありません。どちらも、まだ存在しない場合は初回実行時に ~/.webreel へ自動的にダウンロードされます。puppeteer、playwright、その他のツールを使って Chrome や Chromium をインストールしないでください。webreel は独自のブラウザーを管理します。

依存関係を明示的にダウンロードする場合、または破損したバイナリを修復する場合：

npx webreel install
npx webreel install --force   # delete cached binaries and re-download

自動ダウンロードされたバイナリを上書きするには、次の環境変数を設定します。

• CHROME_PATH - Chrome または Chromium バイナリへのパス（プレビューに使用）
• CHROME_HEADLESS_PATH - chrome-headless-shell バイナリへのパス（録画に使用）
• FFMPEG_PATH - ffmpeg バイナリへのパス

録画が「No inspectable targets」などのブラウザーエラーで失敗する場合、原因はほぼ間違いなく webreel の設定（waitFor の誤り、要素の欠落、タイミングなど）であり、ブラウザーがないことではありません。設定を確認し、--verbose を使ってデバッグしてください。

.gitignore

録画中にプロジェクトのルートに .webreel ディレクトリ（フレーム、中間ファイル）が作成されます。これを .gitignore に追加してください。

.webreel

クイックスタート

# Scaffold a config
npx webreel init --name my-demo --url https://example.com

# Edit webreel.config.json with your steps

# Preview in a visible browser (no recording)
npx webreel preview my-demo

# Record the video
npx webreel record my-demo

webreel が devDependencies に含まれている場合、npx はローカルにインストールされたバージョンを解決します。デフォルトでは出力は videos/ に保存されます（outDir で設定可能です）。

CLI コマンド

init

新しい webreel.config.json をひな形から作成します。

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

1 本以上の動画を録画します。

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/

preview

録画せずに、表示されたブラウザーでステップを実行します。

webreel preview
webreel preview hero --verbose

composite

録画し直さずに、既存の生動画にオーバーレイ（カーソル、HUD、効果音）を再適用します。テーマ設定の調整に便利です。

webreel composite
webreel composite hero

install

Chrome と ffmpeg を ~/.webreel にダウンロードします。破損したバイナリや動作しないバイナリを修復する場合にも使用します。

webreel install
webreel install --force  # delete cached binaries and re-download

validate

何も実行せずに、設定にエラーがないか確認します。

webreel validate
webreel validate -c custom.config.json

設定の構造

設定ファイルは webreel.config.json（または .ts、.mts、.js、.mjs）として自動検出されます。カスタムパスを指定するには -c を使います。

トップレベルのフィールド

フィールド	デフォルト	説明
$schema	-	"https://webreel.dev/schema/v1.json"
outDir	"videos/"	レンダリングした動画の出力ディレクトリ
baseUrl	""	相対動画 URL の先頭に追加するベース URL
viewport	1080x1080	デフォルトのビューポート { width, height }
theme	-	カーソルと HUD のオーバーレイテーマ
sfx	-	効果音の設定
include	-	すべての動画の先頭に追加するステップファイルパスの配列
defaultDelay	-	各ステップの後に追加するデフォルトの遅延時間（ms）
clickDwell	-	クリック前にカーソルを停止させる時間（ms）

動画ごとのフィールド

videos マップの各エントリでは、次のフィールドを使用できます。

フィールド	デフォルト	説明
url	必須	開く URL（絶対 URL または baseUrl からの相対 URL）
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": {
    "hero": { "url": "...", "steps": [...] },
    "login": { "url": "...", "steps": [...] }
  }
}

名前を指定して特定の動画を記録します：webreel record hero login。

ステップの種類

各ステップには action フィールドがあります。ほとんどのステップでは、オプションの label、delay（ステップ後の遅延時間、ミリ秒）、description フィールドを指定できます。

アクション	主なフィールド	目的
pause	ms	指定した時間だけ待機します
click	text または selector、within、modifiers	要素をクリックします
type	text、selector、within、charDelay	入力欄にテキストを入力します
key	key、target	キーの組み合わせを押します（例："cmd+s"）
drag	from、to（要素のターゲット）	2 つの要素間でドラッグします
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 を参照してください。

要素のターゲット指定

多くのステップでは、次のフィールドを使って要素をターゲットにします。

• text - 表示テキストの内容で一致させます
• selector - CSS セレクターで一致させます
• within - この CSS セレクターに一致する親要素に検索範囲を絞ります

text または selector のどちらか一方を使用できます（両方は指定できません）。within は任意で、検索範囲を限定します。

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

ビューポートのプリセット

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）。

テーマ

カーソルの外観とキーストローク HUD をカスタマイズします。

{
  "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 - "top" または "bottom"

よくあるパターン

include を使ったステップの共有

再利用可能なステップのシーケンス（例：Cookie バナーを閉じる処理）を JSON ファイルに切り出します。

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

設定で参照します。

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

1 つの設定で複数の動画を作成する

videos マップで複数の動画を定義します。共有設定（viewport、theme、defaultDelay）はトップレベルから継承されます。

環境変数

設定値では、環境変数からの $VAR および ${VAR} の置換に対応しています。

出力形式

output の拡張子を設定して、形式を指定します：.mp4（デフォルト）、.gif、.webm。

{ "output": "demo.gif" }

ヒント

• ステップの実行前にページの準備が整うよう、動画には必ず waitFor を設定してください。
• 個々のステップで delay を使い、アクション間のペースを調整してください。
• 開発中は --watch を使うと、設定が変更されたときに自動で再録画されます。
• 再録画せずにテーマやオーバーレイの設定を調整するには、composite を使ってください。
• ステップの実行をデバッグするには --verbose を使ってください。
• 解決済みの設定全体（include、環境変数、デフォルト値を含む）を確認するには、--dry-run を使ってください。
• 録画で小さな UI を読みやすく拡大するには、zoom を使ってください。
• 本格的に録画する前に preview を使い、ステップが正しく動作することを確認してください。

リファレンスファイル

• steps-reference.md - 12 種類すべてのステップタイプに関する詳細なドキュメント
• examples.md - よくある用途向けの注釈付き設定例