Page.startScreencast and pipes them to ffmpeg. No permission prompt, no extension click, and the recording survives page navigation, also cross-site.PLAYWRITER_DIRECT), headless, cloud browsers and remote control.ffmpeg must be installed and on PATH.# macOS brew install ffmpeg # Debian / Ubuntu sudo apt install ffmpeg
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, })
await state.page.click('a') await state.page.waitForLoadState('domcontentloaded') await state.page.goBack() // Still recording
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.| Parameter | Type | Default | Description |
page | Page | required | Page to record. Change it later with setPage() |
outputPath | string | required | Absolute output path. .mp4, .mov, .mkv or .webm |
clock | 'real' | 'manual' | 'real' | 'manual' records only inside wait(ms); see Manual clock |
frameRate | number | 30 | Frames per second, max 60 |
audio | boolean | false | Record page audio (see Audio) |
maxSize | number | 1920 | Longest output edge in pixels |
quality | number | 90 | JPEG quality of captured frames, 0-100 |
aspectRatio | object | null | { width: 16, height: 9 } | Shrink viewport to this ratio; null to skip |
maxDurationMs | number | 15 min | Auto-stop safety limit; 0 to disable |
devicePixelRatio), with the longest edge capped by maxSize and both dimensions rounded to even numbers.| Extension | Video | Audio |
.mp4, .mov, .mkv | H.264 | AAC |
.webm | VP8 (realtime) | Opus |
h264_videotoolbox on macOS, NVENC, QSV or AMF on Windows and Linux), else libx264. Any other extension throws.audio: true to record page audio:await recording.start({ page: state.page, outputPath: '/absolute/path/to/demo.mp4', audio: true, })
<audio> and <video> elements (also DRM media) and AudioContexts that play to the speakers, then sends the PCM to ffmpeg.recording.start is missedclock: '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
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'.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)
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
recording.start() returns its own handle.// 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 })
locator.click(), state.page.mouse.move()) instead of goto() to show realistic cursor motion.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 })
--timeout 120000 or higher.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.maxDurationMs.aspectRatio: null to keep the current size.