Skip to main content
The Recorder class handles video capture from a Chrome DevTools Protocol (CDP) client. It manages frame capture, encoding, and output generation.

​
Constructor

new Recorder(
  outputWidth?: number,
  outputHeight?: number,
  options?: {
    sfx?: SfxConfig;
    fps?: number;
    crf?: number;
    framesDir?: string;
  }
)
​
outputWidth
number
default:"1080"
Width of the output video in pixels
​
outputHeight
number
default:"1080"
Height of the output video in pixels
​
options.sfx
SfxConfig
Sound effects configuration for click and key events
interface SfxConfig {
  click?: 1 | 2 | 3 | 4 | string; // Built-in sound or custom path
  key?: 1 | 2 | 3 | 4 | string;
}
​
options.fps
number
default:"60"
Target frames per second for recording
​
options.crf
number
default:"18"
Constant Rate Factor for video encoding quality (0-51, lower is better)
​
options.framesDir
string
Optional directory to save individual frame images during recording

​
Methods

​
start()

Begin recording from a CDP client. 
await recorder.start(client, outputPath, ctx?)
​
client
CDPClient
required
Chrome DevTools Protocol client instance
​
outputPath
string
required
Path where the video will be saved (.mp4, .webm, or .gif)
​
ctx
RecordingContext
Optional recording context for tracking cursor and interactions

​
stop()

Stop recording and finalize the output video. 
await recorder.stop()
This method:
  • Stops frame capture
  • Closes the ffmpeg encoding process
  • Applies sound effects if configured
  • Finalizes the output file in the requested format
  • Cleans up temporary files

​
setTimeline()

Attach an interaction timeline to the recorder. 
recorder.setTimeline(timeline)
​
timeline
InteractionTimeline
required
Timeline instance to track cursor movements and events

​
getTimeline()

Retrieve the currently attached timeline. 
const timeline = recorder.getTimeline()
​
timeline
InteractionTimeline | null
The attached timeline, or null if none is set

​
getTimelineData()

Get the timeline data as a serializable JSON object. 
const data = recorder.getTimelineData()
​
data
TimelineData | null
Timeline data including frames, events, and theme configuration

​
addEvent()

Manually add a sound event to the recording. 
recorder.addEvent(type)
​
type
'click' | 'key'
required
Type of interaction event

​
getTempVideoPath()

Get the path to the temporary video file being created. 
const path = recorder.getTempVideoPath()
​
path
string
Absolute path to the temporary video file

​
Usage Example

import { Recorder, connectCDP } from '@webreel/core';

// Connect to Chrome
const client = await connectCDP('http://localhost:9222');

// Create recorder
const recorder = new Recorder(1920, 1080, {
  fps: 60,
  sfx: {
    click: 1,
    key: 2
  }
});

// Start recording
await recorder.start(client, './output.mp4');

// ... perform browser interactions ...

// Stop and save
await recorder.stop();
await client.close();

​
Advanced: Timeline-Based Recording

For precise control over cursor animations and overlays, use a timeline: 
import { Recorder, InteractionTimeline, RecordingContext } from '@webreel/core';

const timeline = new InteractionTimeline(1920, 1080, {
  fps: 60,
  cursorSvg: customCursorSvg,
  hud: {
    background: 'rgba(0,0,0,0.7)',
    fontSize: 48
  }
});

const ctx = new RecordingContext();
ctx.setTimeline(timeline);
ctx.setMode('record');

const recorder = new Recorder(1920, 1080);
recorder.setTimeline(timeline);

await recorder.start(client, './temp.mp4', ctx);

// The recorder will capture clean video without overlays
// Timeline stores cursor/HUD data separately

await recorder.stop();

// Save timeline for later compositing
timeline.save('./timeline.json');

​
Output Formats

The recorder supports multiple output formats based on file extension:
  • .mp4 - H.264 video with optional audio (recommended)
  • .webm - VP9 video with optional audio
  • .gif - Animated GIF (no audio)
Audio is automatically added when sfx is configured and interaction events are recorded.

Build docs developers (and LLMs) love

Get started for freeTalk to us