The RecordingContext class tracks the state of a recording session, including cursor position, recording mode, and timeline integration.
Constructor
const ctx = new RecordingContext()
Properties
mode
The current recording mode.
ctx.mode // 'record' | 'preview'
'record' - Timeline-based recording with cursor tracking'preview' - Real-time overlay rendering without timeline
timeline
The attached interaction timeline.
ctx.timeline // InteractionTimeline | null
timeline
InteractionTimeline | null
Timeline instance for tracking cursor movements and events
cursorX
Current horizontal cursor position in pixels.
cursorY
Current vertical cursor position in pixels.
isRecording
Whether the context is actively recording to a timeline.
ctx.isRecording // boolean
true when mode is 'record' and a timeline is set.
Methods
setMode()
Set the recording mode.
mode
'record' | 'preview'
required
Recording mode to use
setTimeline()
Attach or detach an interaction timeline.
ctx.setTimeline(timeline)
timeline
InteractionTimeline | null
required
Timeline to attach, or null to detach
setRecorder()
Attach or detach a recorder instance.
ctx.setRecorder(recorder)
recorder
{ addEvent: (type: 'click' | 'key') => void } | null
required
Recorder instance to attach, or null to detach
setCursorPosition()
Update the cursor position.
ctx.setCursorPosition(x, y)
Horizontal position in pixels
Vertical position in pixels
getCursorPosition()
Get the current cursor position.
const pos = ctx.getCursorPosition()
Current cursor coordinates
resetCursorPosition()
Reset cursor to a random position along the viewport edge.
ctx.resetCursorPosition(cssWidth?, cssHeight?)
Viewport height in pixels
setClickDwell()
Set the dwell time before clicks.
ms
number | undefined
required
Dwell time in milliseconds, or undefined for random (80-180ms)
getClickDwellMs()
Get the current click dwell time.
const dwell = ctx.getClickDwellMs()
Dwell time in milliseconds
markEvent()
Record an interaction event.
Type of interaction event
- Adds the event to the timeline if recording
- Notifies the attached recorder for sound effects
Usage Example
Preview Mode
For real-time overlay rendering during recording:
import { Recorder, RecordingContext, clickAt } from '@webreel/core';
const ctx = new RecordingContext();
ctx.setMode('preview');
const recorder = new Recorder(1920, 1080);
await recorder.start(client, './output.mp4', ctx);
// Action functions use the context
await clickAt(ctx, client, 500, 300);
await recorder.stop();
Record Mode
For timeline-based recording with separate composition:
import {
Recorder,
RecordingContext,
InteractionTimeline,
clickAt
} from '@webreel/core';
const timeline = new InteractionTimeline(1920, 1080);
const ctx = new RecordingContext();
ctx.setMode('record');
ctx.setTimeline(timeline);
const recorder = new Recorder(1920, 1080);
recorder.setTimeline(timeline);
await recorder.start(client, './clean.mp4', ctx);
// Cursor movements are tracked in timeline
await clickAt(ctx, client, 500, 300);
await recorder.stop();
// Timeline contains all cursor/HUD data
timeline.save('./timeline.json');
Workflow Integration
The context is designed to work seamlessly with action functions:
import {
RecordingContext,
navigate,
clickAt,
typeText,
pressKey
} from '@webreel/core';
const ctx = new RecordingContext();
ctx.setMode('preview');
// All actions accept the context as first parameter
await navigate(client, 'https://example.com');
await clickAt(ctx, client, 400, 200);
await typeText(ctx, client, 'Hello World');
await pressKey(ctx, client, 'Enter');
- Tracks cursor position across actions
- Records events for sound effects
- Coordinates with timeline when in record mode
- Manages HUD visibility for keyboard shortcuts