Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Record Browser Automation as MP4 Video

Have the agent record what it's doing as video. Playwriter streams JPEG frames with CDP Page.startScreencast and pipes them to ffmpeg. No permission prompt, no extension click, and the recording survives page navigation, also cross-site.
It works in every mode: extension, direct CDP (PLAYWRITER_DIRECT), headless, cloud browsers and remote control.

Requirements

ffmpeg must be installed and on PATH.
# macOS brew install ffmpeg # Debian / Ubuntu sudo apt install ffmpeg

Start recording

recording.start() returns a handle. Keep it in state to use it in later execute calls:
state.video = await recording.start({ page: state.page, outputPath: '/absolute/path/to/recording.mp4', frameRate: 30, })
Recording continues across page navigations. No restart needed:
await state.page.click('a') await state.page.waitForLoadState('domcontentloaded') await state.page.goBack() // Still recording
Static pages are fine too. The last frame is repeated at a constant frame rate, so the video duration matches real time.

Stop and save

state.recordingResult = await state.video.stop() // => { path, duration, size, executionTimestamps }
duration is the media duration in ms, size is the file size in bytes. Save the full result to state because executionTimestamps is needed for createDemoVideo.

Options

ParameterTypeDefaultDescription
pagePagerequiredPage to record. Change it later with setPage()
outputPathstringrequiredAbsolute output path. .mp4, .mov, .mkv or .webm
clock'real' | 'manual''real''manual' records only inside wait(ms); see Manual clock
frameRatenumber30Frames per second, max 60
audiobooleanfalseRecord page audio (see Audio)
maxSizenumber1920Longest output edge in pixels
qualitynumber90JPEG quality of captured frames, 0-100
aspectRatioobject | null{ width: 16, height: 9 }Shrink viewport to this ratio; null to skip
maxDurationMsnumber15 minAuto-stop safety limit; 0 to disable

Output format

The output size is the viewport in device pixels (viewport × devicePixelRatio), with the longest edge capped by maxSize and both dimensions rounded to even numbers.
ExtensionVideoAudio
.mp4, .mov, .mkvH.264AAC
.webmVP8 (realtime)Opus
H.264 uses a hardware encoder when ffmpeg has one (h264_videotoolbox on macOS, NVENC, QSV or AMF on Windows and Linux), else libx264. Any other extension throws.
On 120 Hz or 144 Hz displays Chrome sends more frames than needed, so the recorder asks for every Nth frame to save CPU.

Audio

Pass audio: true to record page audio:
await recording.start({ page: state.page, outputPath: '/absolute/path/to/demo.mp4', audio: true, })
Playwriter injects a Web Audio tap in the page. It captures <audio> and <video> elements (also DRM media) and AudioContexts that play to the speakers, then sends the PCM to ffmpeg.
Limitations:
  • No audio from cross-origin (out-of-process) iframes
  • An AudioContext graph wired before recording.start is missed
  • The page can detect the patched audio APIs while recording

Manual clock

With the default clock: 'real', the video is wall-clock time: every second the agent spends thinking is in the video. Pass clock: 'manual' to record only inside wait(ms). The page keeps running normally; time outside wait() is just not written, so agent latency never shows:
state.video = await recording.start({ page: state.page, outputPath: '/abs/demo.mp4', clock: 'manual' }) // Same execute call: the action and its wait are milliseconds apart await state.page.getByRole('button', { name: 'Open menu' }).click() await state.video.wait(800) // records the next 800ms, menu animation included // Next execute call, after the agent thought for 10s: those 10s are not in the video await state.page.mouse.wheel(0, 400) await state.video.wait(600) await state.video.stop()
execute 1: click() → video.wait(800) ──> 800ms of frames written agent thinks 10s ──> page runs, nothing written execute 2: wheel() → video.wait(600) ──> 600ms of frames written
Put each action and its wait() in the same execute call. An animation that starts in one call and finishes before the next call's wait() is not in the video. Use video.wait(ms) instead of waitForTimeout() whenever the viewer should see the time pass. audio: true is not supported yet with clock: 'manual'.

Record another tab

setPage() moves the recording to another tab. The output size stays the same; frames are scaled and padded to fit:
state.other = await context.newPage() await state.other.goto('https://example.com') await state.video.setPage(state.other)

Other recording commands

state.video.isRecording // false after stop, cancel, page close or max duration state.video.page // tab being recorded await state.video.cancel() // stop without saving
Several pages can record at the same time. Each recording.start() returns its own handle.

Ghost cursor

The extension injects a ghost cursor overlay on every Playwriter-attached tab. It follows mouse actions automatically, making recordings look natural.
// Change cursor style await ghostCursor.show({ page: state.page, style: 'screenstudio' }) // Styles: 'minimal' (default), 'dot', 'screenstudio' // Temporarily hide the cursor await ghostCursor.hide({ page: state.page })
For best-looking recordings, use locator-based interactions (locator.click(), state.page.mouse.move()) instead of goto() to show realistic cursor motion.

Demo video acceleration

After a clock: 'real' recording, use createDemoVideo to speed up idle sections (time between execute calls) while keeping interactions at normal speed. Requires ffmpeg and ffprobe installed. A clock: 'manual' recording has no idle sections, so it does not need this.
// First, stop recording and save the result state.recordingResult = await state.video.stop() // Then in a SEPARATE execute call (with --timeout 120000): const demoPath = await createDemoVideo({ recordingPath: state.recordingResult.path, durationMs: state.recordingResult.duration, executionTimestamps: state.recordingResult.executionTimestamps, speed: 6, // default 6x for idle sections })
This can take 60-120+ seconds. Always pass --timeout 120000 or higher.

Library usage

Record any Playwright page from your own Node.js code:
import { startRecording } from 'playwriter' const rec = await startRecording({ page, outputPath: './demo.mp4', audio: false, frameRate: 30, }) await page.goto('https://example.com') const { path, duration, size } = await rec.stop() // or: await rec.cancel()
startRecording({ clock: 'manual' }) gives the same wait(ms) and setPage(page) methods.

Limitations

  • Ends with the page. The recording is tied to the Playwright page and stops when the page closes or the session is reset.
  • Auto-stops after 15 minutes by default. Override with maxDurationMs.
  • Viewport auto-resizes to 16:9 (it only shrinks). Pass aspectRatio: null to keep the current size.