feat(video): start/stop

docs/src/api/class-page.md

@@ -4365,9 +4365,10 @@ Optional handler function to route the request.
 
 ## method: Page.video
 * since: v1.8
-- returns: <[null]|[Video]>
+- returns: <[Video]>
 
-Video object associated with this page.
+Video object associated with this page. Can be used to control video recording with [`method: Video.start`]
+and [`method: Video.stop`], or to access the video file when using the `recordVideo` context option.
 
 ## method: Page.viewportSize
 * since: v1.8

docs/src/api/class-video.md

@@ -23,6 +23,38 @@ print(page.video.path())
 Console.WriteLine(await page.Video.GetPathAsync());
 ```
 
+Alternatively, you can use [`method: Video.start`] and [`method: Video.stop`] to record video manually. This approach is mutually exclusive with the `recordVideo` option.
+
+```js
+await page.video().start();
+// ... perform actions ...
+await page.video().stop({ path: 'video.webm' });
+```
+
+```java
+page.video().start();
+// ... perform actions ...
+page.video().stop(new Video.StopOptions().setPath(Paths.get("video.webm")));
+```
+
+```python async
+await page.video.start()
+# ... perform actions ...
+await page.video.stop(path="video.webm")
+```
+
+```python sync
+page.video.start()
+# ... perform actions ...
+page.video.stop(path="video.webm")
+```
+
+```csharp
+await page.Video.StartAsync();
+// ... perform actions ...
+await page.Video.StopAsync(new() { Path = "video.webm" });
+```
+
 ## async method: Video.delete
 * since: v1.11
 
@@ -58,3 +90,60 @@ Saves the video to a user-specified path. If using the sync API, this must be ca
 - `path` <[path]>
 
 Path where the video should be saved.
+
+
+## async method: Video.start
+* since: v1.59
+
+Starts video recording. This method is mutually exclusive with the `recordVideo` context option.
+
+**Usage**
+
+```js
+await page.video().start();
+// ... perform actions ...
+await page.video().stop({ path: 'video.webm' });
+```
+
+```java
+page.video().start();
+// ... perform actions ...
+page.video().stop(new Video.StopOptions().setPath(Paths.get("video.webm")));
+```
+
+```python async
+await page.video.start()
+# ... perform actions ...
+await page.video.stop(path="video.webm")
+```
+
+```python sync
+page.video.start()
+# ... perform actions ...
+page.video.stop(path="video.webm")
+```
+
+```csharp
+await page.Video.StartAsync();
+// ... perform actions ...
+await page.Video.StopAsync(new() { Path = "video.webm" });
+```
+
+### option: Video.start.size
+* since: v1.59
+- `size` ?<[Object]>
+  - `width` <[int]> Video frame width.
+  - `height` <[int]> Video frame height.
+
+Optional dimensions of the recorded video. If not specified the size will be equal to page viewport scaled down to fit into 800x800. Actual picture of the page will be scaled down if necessary to fit the specified size.
+
+## async method: Video.stop
+* since: v1.59
+
+Stops video recording started with [`method: Video.start`] and either saves or discards the video file.
+
+### option: Video.stop.path
+* since: v1.59
+- `path` <[path]>
+
+Path where the video should be saved.

packages/playwright-client/types/types.d.ts

@@ -4802,9 +4802,12 @@ export interface Page {
   url(): string;
 
   /**
-   * Video object associated with this page.
+   * Video object associated with this page. Can be used to control video recording with
+   * [video.start([options])](https://playwright.dev/docs/api/class-video#video-start) and
+   * [video.stop([options])](https://playwright.dev/docs/api/class-video#video-stop), or to access the video file when
+   * using the `recordVideo` context option.
    */
-  video(): null|Video;
+  video(): Video;
 
   viewportSize(): null|{
     /**
@@ -21757,6 +21760,16 @@ export interface Tracing {
  * console.log(await page.video().path());
  * ```
  *
+ * Alternatively, you can use [video.start([options])](https://playwright.dev/docs/api/class-video#video-start) and
+ * [video.stop([options])](https://playwright.dev/docs/api/class-video#video-stop) to record video manually. This
+ * approach is mutually exclusive with the `recordVideo` option.
+ *
+ * ```js
+ * await page.video().start();
+ * // ... perform actions ...
+ * await page.video().stop({ path: 'video.webm' });
+ * ```
+ *
  */
 export interface Video {
   /**
@@ -21776,6 +21789,50 @@ export interface Video {
    * @param path Path where the video should be saved.
    */
   saveAs(path: string): Promise<void>;
+
+  /**
+   * Starts video recording. This method is mutually exclusive with the `recordVideo` context option.
+   *
+   * **Usage**
+   *
+   * ```js
+   * await page.video().start();
+   * // ... perform actions ...
+   * await page.video().stop({ path: 'video.webm' });
+   * ```
+   *
+   * @param options
+   */
+  start(options?: {
+    /**
+     * Optional dimensions of the recorded video. If not specified the size will be equal to page viewport scaled down to
+     * fit into 800x800. Actual picture of the page will be scaled down if necessary to fit the specified size.
+     */
+    size?: {
+      /**
+       * Video frame width.
+       */
+      width: number;
+
+      /**
+       * Video frame height.
+       */
+      height: number;
+    };
+  }): Promise<void>;
+
+  /**
+   * Stops video recording started with
+   * [video.start([options])](https://playwright.dev/docs/api/class-video#video-start) and either saves or discards the
+   * video file.
+   * @param options
+   */
+  stop(options?: {
+    /**
+     * Path where the video should be saved.
+     */
+    path?: string;
+  }): Promise<void>;
 }
 
 /**

packages/playwright-core/src/client/page.ts

@@ -288,12 +288,10 @@ export class Page extends ChannelOwner<channels.PageChannel> implements api.Page
     return this._video;
   }
 
-  video(): Video | null {
+  video(): Video {
     // Note: we are creating Video object lazily, because we do not know
     // BrowserContextOptions when constructing the page - it is assigned
     // too late during launchPersistentContext.
-    if (!this._browserContext._options.recordVideo)
-      return null;
     return this._forceVideo();
   }
 

packages/playwright-core/src/client/video.ts

@@ -15,26 +15,43 @@
  */
 
 import { ManualPromise } from '../utils/isomorphic/manualPromise';
+import { Artifact } from './artifact';
 
-import type { Artifact } from './artifact';
 import type { Connection } from './connection';
 import type { Page } from './page';
 import type * as api from '../../types/types';
 
 export class Video implements api.Video {
   private _artifact: Promise<Artifact | null> | null = null;
-  private _artifactReadyPromise = new ManualPromise<Artifact>();
+  private _artifactReadyPromise: ManualPromise<Artifact>;
   private _isRemote = false;
+  private _page: Page;
 
   constructor(page: Page, connection: Connection) {
+    this._page = page;
     this._isRemote = connection.isRemote();
+    this._artifactReadyPromise = new ManualPromise<Artifact>();
     this._artifact = page._closedOrCrashedScope.safeRace(this._artifactReadyPromise);
   }
 
   _artifactReady(artifact: Artifact) {
     this._artifactReadyPromise.resolve(artifact);
   }
 
+  async start(options: { size?: { width: number, height: number } } = {}): Promise<void> {
+    await this._page._channel.videoStart(options);
+    this._artifactReadyPromise = new ManualPromise<Artifact>();
+    this._artifact = this._page._closedOrCrashedScope.safeRace(this._artifactReadyPromise);
+  }
+
+  async stop(options: { path?: string } = {}): Promise<void> {
+    await this._page._wrapApiCall(async () => {
+      await this._page._channel.videoStop();
+      if (options.path)
+        await this.saveAs(options.path);
+    });
+  }
+
   async path(): Promise<string> {
     if (this._isRemote)
       throw new Error(`Path is not available when connecting remotely. Use saveAs() to save a local copy.`);

packages/playwright-core/src/protocol/validator.ts

@@ -1482,6 +1482,15 @@ scheme.PageStopCSSCoverageResult = tObject({
 });
 scheme.PageBringToFrontParams = tOptional(tObject({}));
 scheme.PageBringToFrontResult = tOptional(tObject({}));
+scheme.PageVideoStartParams = tObject({
+  size: tOptional(tObject({
+    width: tInt,
+    height: tInt,
+  })),
+});
+scheme.PageVideoStartResult = tOptional(tObject({}));
+scheme.PageVideoStopParams = tOptional(tObject({}));
+scheme.PageVideoStopResult = tOptional(tObject({}));
 scheme.PageUpdateSubscriptionParams = tObject({
   event: tEnum(['console', 'dialog', 'fileChooser', 'request', 'response', 'requestFinished', 'requestFailed']),
   enabled: tBoolean,

packages/playwright-core/src/server/browserContext.ts

@@ -745,28 +745,29 @@ export function validateBrowserContextOptions(options: types.BrowserContextOptio
     options.acceptDownloads = 'internal-browser-default';
   if (!options.viewport && !options.noDefaultViewport)
     options.viewport = { width: 1280, height: 720 };
-  if (options.recordVideo) {
-    if (!options.recordVideo.size) {
-      if (options.noDefaultViewport) {
-        options.recordVideo.size = { width: 800, height: 600 };
-      } else {
-        const size = options.viewport!;
-        const scale = Math.min(1, 800 / Math.max(size.width, size.height));
-        options.recordVideo.size = {
-          width: Math.floor(size.width * scale),
-          height: Math.floor(size.height * scale)
-        };
-      }
-    }
-    // Make sure both dimensions are odd, this is required for vp8
-    options.recordVideo.size!.width &= ~1;
-    options.recordVideo.size!.height &= ~1;
-  }
+  if (options.recordVideo)
+    options.recordVideo.size = validateVideoSize(options.recordVideo.size, options.viewport);
   if (options.proxy)
     options.proxy = normalizeProxySettings(options.proxy);
   verifyGeolocation(options.geolocation);
 }
 
+export function validateVideoSize(size: types.Size | undefined, viewport: types.Size | undefined): types.Size {
+  if (!size) {
+    viewport ??= { width: 800, height: 600 };
+    const scale = Math.min(1, 800 / Math.max(viewport.width, viewport.height));
+    size = {
+      width: Math.floor(viewport.width * scale),
+      height: Math.floor(viewport.height * scale)
+    };
+  }
+  // Make sure both dimensions are odd, this is required for vp8
+  return {
+    width: size.width & ~1,
+    height: size.height & ~1
+  };
+}
+
 export function verifyGeolocation(geolocation?: types.Geolocation): asserts geolocation is types.Geolocation {
   if (!geolocation)
     return;

packages/playwright-core/src/server/chromium/crPage.ts

@@ -439,7 +439,7 @@ class FrameSession {
 
     let videoOptions: types.VideoOptions | undefined;
     if (!this._page.isStorageStatePage && this._isMainFrame() && hasUIWindow)
-      videoOptions = this._crPage._page.screencast.launchVideoRecorder();
+      videoOptions = this._crPage._page.screencast.launchAutomaticVideoRecorder();
 
     let lifecycleEventsEnabled: Promise<any>;
     if (!this._isMainFrame())

packages/playwright-core/src/server/dispatchers/pageDispatcher.ts

@@ -337,6 +337,14 @@ export class PageDispatcher extends Dispatcher<Page, channels.PageChannel, Brows
     await progress.race(this._page.bringToFront());
   }
 
+  async videoStart(params: channels.PageVideoStartParams, progress: Progress): Promise<void> {
+    await this._page.screencast.startExplicitVideoRecording(params);
+  }
+
+  async videoStop(params: channels.PageVideoStopParams, progress: Progress): Promise<channels.PageVideoStopResult> {
+    await this._page.screencast.stopVideoRecording();
+  }
+
   async startJSCoverage(params: channels.PageStartJSCoverageParams, progress: Progress): Promise<void> {
     const coverage = this._page.coverage as CRCoverage;
     await coverage.startJSCoverage(progress, params);

packages/playwright-core/src/server/firefox/ffPage.ts

@@ -99,7 +99,7 @@ export class FFPage implements PageDelegate {
     ];
 
     const screencast = this._page.screencast;
-    const videoOptions = screencast.launchVideoRecorder();
+    const videoOptions = screencast.launchAutomaticVideoRecorder();
     if (videoOptions)
       screencast.startVideoRecording(videoOptions).catch(e => debugLogger.log('error', e));