feat: implement screencasting (#11084)

.github/workflows/ci.yml

@@ -171,6 +171,8 @@ jobs:
         with:
           cache: npm
           node-version: lts/*
+      - name: Set up FFmpeg
+        uses: FedericoCarboni/setup-ffmpeg@5058c9851b649ced05c3e73a4fb5ef2995a89127 # v2.0.0
       - name: Install dependencies
         run: npm ci
         env:
@@ -261,6 +263,8 @@ jobs:
         with:
           cache: npm
           node-version: lts/*
+      - name: Set up FFmpeg
+        uses: FedericoCarboni/setup-ffmpeg@5058c9851b649ced05c3e73a4fb5ef2995a89127 # v2.0.0
       - name: Install dependencies
         run: npm ci
         env:

docs/api/index.md

@@ -36,6 +36,7 @@ sidebar_label: API
 | [ProtocolError](./puppeteer.protocolerror.md)                         | ProtocolError is emitted whenever there is an error from the protocol.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
 | [Puppeteer](./puppeteer.puppeteer.md)                                 | <p>The main Puppeteer class.</p><p>IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [PuppeteerNode](./puppeteer.puppeteernode.md)                         | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| [ScreenRecorder](./puppeteer.screenrecorder.md)                       |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | [SecurityDetails](./puppeteer.securitydetails.md)                     | The SecurityDetails class represents the security details of a response that was received over a secure connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | [Target](./puppeteer.target.md)                                       | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [TimeoutError](./puppeteer.timeouterror.md)                           | TimeoutError is emitted whenever certain operations are terminated due to timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
@@ -124,6 +125,7 @@ sidebar_label: API
 | [PuppeteerLaunchOptions](./puppeteer.puppeteerlaunchoptions.md)             |                                                                                                                                                                                     |
 | [RemoteAddress](./puppeteer.remoteaddress.md)                               |                                                                                                                                                                                     |
 | [ResponseForRequest](./puppeteer.responseforrequest.md)                     | Required response data to fulfill a request with.                                                                                                                                   |
+| [ScreencastOptions](./puppeteer.screencastoptions.md)                       |                                                                                                                                                                                     |
 | [ScreenshotClip](./puppeteer.screenshotclip.md)                             |                                                                                                                                                                                     |
 | [ScreenshotOptions](./puppeteer.screenshotoptions.md)                       |                                                                                                                                                                                     |
 | [SerializedAXNode](./puppeteer.serializedaxnode.md)                         | Represents a Node and the properties of it that are relevant to Accessibility.                                                                                                      |

docs/api/puppeteer.page.md

@@ -127,6 +127,7 @@ page.off('request', logRequest);
 | [reload(options)](./puppeteer.page.reload.md)                                                              |           | Reloads the page.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | [removeExposedFunction(name)](./puppeteer.page.removeexposedfunction.md)                                   |           | The method removes a previously added function via $[Page.exposeFunction()](./puppeteer.page.exposefunction.md) called <code>name</code> from the page's <code>window</code> object.                                                                                                                                                                                                                                                                                                                                                                                                                    |
 | [removeScriptToEvaluateOnNewDocument(identifier)](./puppeteer.page.removescripttoevaluateonnewdocument.md) |           | Removes script that injected into page by Page.evaluateOnNewDocument.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| [screencast(options)](./puppeteer.page.screencast.md)                                                      |           | Captures a screencast of this [page](./puppeteer.page.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | [screenshot(options)](./puppeteer.page.screenshot.md)                                                      |           | Captures a screenshot of this [page](./puppeteer.page.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 | [screenshot(options)](./puppeteer.page.screenshot_1.md)                                                    |           |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | [select(selector, values)](./puppeteer.page.select.md)                                                     |           | Triggers a <code>change</code> and <code>input</code> event once all the provided options have been selected. If there's no <code>&lt;select&gt;</code> element matching <code>selector</code>, the method throws an error.                                                                                                                                                                                                                                                                                                                                                                             |

docs/api/puppeteer.page.screencast.md

@@ -0,0 +1,58 @@
+---
+sidebar_label: Page.screencast
+---
+
+# Page.screencast() method
+
+Captures a screencast of this [page](./puppeteer.page.md).
+
+#### Signature:
+
+```typescript
+class Page {
+  screencast(options?: Readonly<ScreencastOptions>): Promise<ScreenRecorder>;
+}
+```
+
+## Parameters
+
+| Parameter | Type                                                                  | Description                                  |
+| --------- | --------------------------------------------------------------------- | -------------------------------------------- |
+| options   | Readonly&lt;[ScreencastOptions](./puppeteer.screencastoptions.md)&gt; | _(Optional)_ Configures screencast behavior. |
+
+**Returns:**
+
+Promise&lt;[ScreenRecorder](./puppeteer.screenrecorder.md)&gt;
+
+## Remarks
+
+All recordings will be \[WebM\](https://www.webmproject.org/) format using the \[VP9\](https://www.webmproject.org/vp9/) video codec. The FPS is 30.
+
+You must have \[ffmpeg\](https://ffmpeg.org/) installed on your system.
+
+## Example
+
+Recording a [page](./puppeteer.page.md):
+
+```
+import puppeteer from 'puppeteer';
+
+// Launch a browser
+const browser = await puppeteer.launch();
+
+// Create a new page
+const page = await browser.newPage();
+
+// Go to your site.
+await page.goto("https://www.example.com");
+
+// Start recording.
+const recorder = await page.screencast({path: 'recording.webm'});
+
+// Do something.
+
+// Stop recording.
+await recorder.stop();
+
+browser.close();
+```

docs/api/puppeteer.screencastoptions.md

@@ -0,0 +1,21 @@
+---
+sidebar_label: ScreencastOptions
+---
+
+# ScreencastOptions interface
+
+#### Signature:
+
+```typescript
+export interface ScreencastOptions
+```
+
+## Properties
+
+| Property   | Modifiers             | Type                                      | Description                                                                                                                                                                                            | Default        |
+| ---------- | --------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
+| crop       | <code>optional</code> | [BoundingBox](./puppeteer.boundingbox.md) | Specifies the region of the viewport to crop.                                                                                                                                                          |                |
+| ffmpegPath | <code>optional</code> | string                                    | <p>Path to the \[ffmpeg\](https://ffmpeg.org/).</p><p>Required if <code>ffmpeg</code> is not in your PATH.</p>                                                                                         |                |
+| path       | <code>optional</code> | \`${string}.webm\`                        | File path to save the screencast to.                                                                                                                                                                   |                |
+| scale      | <code>optional</code> | number                                    | <p>Scales the output video.</p><p>For example, <code>0.5</code> will shrink the width and height of the output video by half. <code>2</code> will double the width and height of the output video.</p> | <code>1</code> |
+| speed      | <code>optional</code> | number                                    | <p>Specifies the speed to record at.</p><p>For example, <code>0.5</code> will slowdown the output video by 50%. <code>2</code> will double the speed of the output video.</p>                          | <code>1</code> |

docs/api/puppeteer.screenrecorder.md

@@ -0,0 +1,23 @@
+---
+sidebar_label: ScreenRecorder
+---
+
+# ScreenRecorder class
+
+#### Signature:
+
+```typescript
+export declare class ScreenRecorder extends PassThrough
+```
+
+**Extends:** PassThrough
+
+## Remarks
+
+The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ScreenRecorder` class.
+
+## Methods
+
+| Method                                       | Modifiers | Description         |
+| -------------------------------------------- | --------- | ------------------- |
+| [stop()](./puppeteer.screenrecorder.stop.md) |           | Stops the recorder. |

docs/api/puppeteer.screenrecorder.stop.md

@@ -0,0 +1,19 @@
+---
+sidebar_label: ScreenRecorder.stop
+---
+
+# ScreenRecorder.stop() method
+
+Stops the recorder.
+
+#### Signature:
+
+```typescript
+class ScreenRecorder {
+  stop(): Promise<void>;
+}
+```
+
+**Returns:**
+
+Promise&lt;void&gt;

docs/api/puppeteer.screenshotclip.md

@@ -7,15 +7,13 @@ sidebar_label: ScreenshotClip
 #### Signature:
 
 ```typescript
-export interface ScreenshotClip
+export interface ScreenshotClip extends BoundingBox
 ```
 
+**Extends:** [BoundingBox](./puppeteer.boundingbox.md)
+
 ## Properties
 
 | Property | Modifiers             | Type   | Description | Default        |
 | -------- | --------------------- | ------ | ----------- | -------------- |
-| height   |                       | number |             |                |
 | scale    | <code>optional</code> | number |             | <code>1</code> |
-| width    |                       | number |             |                |
-| x        |                       | number |             |                |
-| y        |                       | number |             |                |