Skip to content

fix(api): migrate Screencast from events to onFrame callback #39714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pavelfeldman merged 1 commit into from
Mar 18, 2026
+64 −295
Merged

fix(api): migrate Screencast from events to onFrame callback #39714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 13 additions & 27 deletions docs/src/api/class-screencast.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,28 @@

Interface for capturing screencast frames from a page.

## event: Screencast.screencastFrame
## async method: Screencast.start
* since: v1.59
- argument: <[Object]>
- `data` <[Buffer]> JPEG-encoded frame data.
- returns: <[Disposable]>

Emitted for each captured JPEG screencast frame while the screencast is running.
Starts capturing screencast frames.

**Usage**

```js
const screencast = page.screencast;
screencast.on('screencastframe', ({ data, width, height }) => {
console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
require('fs').writeFileSync('frame.jpg', data);
});
await screencast.start({ maxSize: { width: 1200, height: 800 } });
await page.screencast.start(buffer => {
console.log(`frame size: ${buffer.length}`);
}, { maxSize: { width: 800, height: 600 } });
// ... perform actions ...
await screencast.stop();
await page.screencast.stop();
```

## async method: Screencast.start
### param: Screencast.start.onFrame
* since: v1.59
- returns: <[Disposable]>

Starts capturing screencast frames. Frames are emitted as [`event: Screencast.screencastFrame`] events.

**Usage**
* langs: js
- `onFrame` <[function]\([Buffer]\): [Promise<any>|any]>

```js
const screencast = page.screencast;
screencast.on('screencastframe', ({ data, width, height }) => {
console.log(`frame ${width}x${height}, size: ${data.length}`);
});
await screencast.start({ maxSize: { width: 800, height: 600 } });
// ... perform actions ...
await screencast.stop();
```
Callback that receives JPEG-encoded frame data.

### option: Screencast.start.maxSize
* since: v1.59
Expand All @@ -50,6 +35,7 @@ await screencast.stop();

Maximum screencast frame dimensions. The output frame may be smaller to preserve the page aspect ratio. Defaults to 800×800.


## async method: Screencast.stop
* since: v1.59

Expand All @@ -58,7 +44,7 @@ Stops the screencast started with [`method: Screencast.start`].
**Usage**

```js
await screencast.start();
await screencast.start(buffer => { /* handle frame */ });
// ... perform actions ...
await screencast.stop();
```
123 changes: 9 additions & 114 deletions packages/playwright-client/types/types.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21664,127 +21664,22 @@ export interface Route {
*/
export interface Screencast {
/**
* Emitted for each captured JPEG screencast frame while the screencast is running.
* Starts capturing screencast frames.
*
* **Usage**
*
* ```js
* const screencast = page.screencast;
* screencast.on('screencastframe', ({ data, width, height }) => {
* console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
* require('fs').writeFileSync('frame.jpg', data);
* });
* await screencast.start({ maxSize: { width: 1200, height: 800 } });
* // ... perform actions ...
* await screencast.stop();
* ```
*
*/
on(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Adds an event listener that will be automatically removed after it is triggered once. See `addListener` for more information about this event.
*/
once(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Emitted for each captured JPEG screencast frame while the screencast is running.
*
* **Usage**
*
* ```js
* const screencast = page.screencast;
* screencast.on('screencastframe', ({ data, width, height }) => {
* console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
* require('fs').writeFileSync('frame.jpg', data);
* });
* await screencast.start({ maxSize: { width: 1200, height: 800 } });
* await page.screencast.start(buffer => {
* console.log(`frame size: ${buffer.length}`);
* }, { maxSize: { width: 800, height: 600 } });
* // ... perform actions ...
* await screencast.stop();
* ```
*
*/
addListener(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Removes an event listener added by `on` or `addListener`.
*/
removeListener(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Removes an event listener added by `on` or `addListener`.
*/
off(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Emitted for each captured JPEG screencast frame while the screencast is running.
*
* **Usage**
*
* ```js
* const screencast = page.screencast;
* screencast.on('screencastframe', ({ data, width, height }) => {
* console.log(`frame ${width}x${height}, jpeg size: ${data.length}`);
* require('fs').writeFileSync('frame.jpg', data);
* });
* await screencast.start({ maxSize: { width: 1200, height: 800 } });
* // ... perform actions ...
* await screencast.stop();
* ```
*
*/
prependListener(event: 'screencastframe', listener: (data: {
/**
* JPEG-encoded frame data.
*/
data: Buffer;
}) => any): this;

/**
* Starts capturing screencast frames. Frames are emitted as
* [screencast.on('screencastframe')](https://playwright.dev/docs/api/class-screencast#screencast-event-screencast-frame)
* events.
*
* **Usage**
*
* ```js
* const screencast = page.screencast;
* screencast.on('screencastframe', ({ data, width, height }) => {
* console.log(`frame ${width}x${height}, size: ${data.length}`);
* });
* await screencast.start({ maxSize: { width: 800, height: 600 } });
* // ... perform actions ...
* await screencast.stop();
* await page.screencast.stop();
* ```
*
* @param onFrame Callback that receives JPEG-encoded frame data.
* @param options
*/
start(options?: {
start(onFrame: ((buffer: Buffer) => Promise<any>|any), options?: {
/**
* Maximum screencast frame dimensions. The output frame may be smaller to preserve the page aspect ratio. Defaults to
* 800×800.
Expand All @@ -21804,12 +21699,12 @@ export interface Screencast {

/**
* Stops the screencast started with
* [screencast.start([options])](https://playwright.dev/docs/api/class-screencast#screencast-start).
* [screencast.start(onFrame[, options])](https://playwright.dev/docs/api/class-screencast#screencast-start).
*
* **Usage**
*
* ```js
* await screencast.start();
* await screencast.start(buffer => { /* handle frame *\/ });
* // ... perform actions ...
* await screencast.stop();
* ```
Expand Down
13 changes: 8 additions & 5 deletions packages/playwright-core/src/client/screencast.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,26 +15,29 @@
*/

import { DisposableStub } from './disposable';
import { EventEmitter } from './eventEmitter';

import type * as api from '../../types/types';
import type { Page } from './page';

export class Screencast extends EventEmitter implements api.Screencast {
export class Screencast implements api.Screencast {
private readonly _page: Page;
private _onFrame: ((buffer: Buffer) => any) | null = null;

constructor(page: Page) {
super(page._platform);
this._page = page;
this._page._channel.on('screencastFrame', ({ data }) => this.emit('screencastframe', { data }));
this._page._channel.on('screencastFrame', ({ data }) => {
this._onFrame?.(data);
});
}

async start(options: { maxSize?: { width: number, height: number } } = {}) {
async start(onFrame: (buffer: Buffer) => any, options: { maxSize?: { width: number, height: number } } = {}): Promise<DisposableStub> {
this._onFrame = onFrame;
Copy link
Member

@yury-s yury-s Mar 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

throw if non-null?

await this._page._channel.startScreencast(options);
return new DisposableStub(() => this.stop());
}

async stop(): Promise<void> {
this._onFrame = null;
await this._page._channel.stopScreencast();
}
}
6 changes: 4 additions & 2 deletions packages/playwright-core/src/tools/dashboard/dashboardController.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,11 +199,13 @@ export class DashboardConnection implements Transport, DashboardChannel {
if (frame === page.mainFrame())
this._sendTabList();
}),
eventsHelper.addEventListener(page.screencast, 'screencastframe', ({ data }) => this._writeFrame(data, page.viewportSize()?.width ?? 0, page.viewportSize()?.height ?? 0))
);

const maxSize = { width: 1280, height: 800 };
await page.screencast.start({ maxSize });
await page.screencast.start(
data => this._writeFrame(data, page.viewportSize()?.width ?? 0, page.viewportSize()?.height ?? 0),
{ maxSize },
);
}

private _deselectPage() {
Expand Down
Loading
Loading