@browserless/capture 10.11.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright © 2019 Microlink <hello@microlink.io> (microlink.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+<div align="center">
+  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner.png#gh-light-mode-only" alt="browserless">
+  <img style="width: 500px; margin:3rem 0 1.5rem;" src="https://github.com/microlinkhq/browserless/raw/master/static/logo-banner-light.png#gh-dark-mode-only" alt="browserless">
+  <br><br>
+  <a href="https://microlink.io"><img src="https://img.shields.io/badge/powered_by-microlink.io-blue?style=flat-square&color=%23EA407B" alt="Powered by microlink.io"></a>
+  <img src="https://img.shields.io/github/tag/microlinkhq/browserless.svg?style=flat-square" alt="Last version">
+  <a href="https://coveralls.io/github/microlinkhq/browserless"><img src="https://img.shields.io/coveralls/microlinkhq/browserless.svg?style=flat-square" alt="Coverage Status"></a>
+  <a href="https://www.npmjs.org/package/@browserless/capture"><img src="https://img.shields.io/npm/dm/@browserless/capture.svg?style=flat-square" alt="NPM Status"></a>
+  <br><br>
+</div>
+
+> @browserless/capture: Record a Puppeteer page using the extension + `tabCapture` approach.
+
+## Install
+
+```sh
+npm install @browserless/capture --save
+```
+
+## Usage
+
+```js
+const createBrowser = require('browserless')
+const createCapture = require('@browserless/capture')
+
+const browser = createBrowser({
+  headless: 'new',
+  ignoreDefaultArgs: ['--disable-extensions'],
+  args: [
+    '--screen-info={2560x1600 devicePixelRatio=2}',
+    `--allowlisted-extension-id=${createCapture.extensionId}`,
+    `--disable-extensions-except=${createCapture.extensionPath}`,
+    `--load-extension=${createCapture.extensionPath}`
+  ]
+})
+
+const browserless = await browser.createContext()
+const page = await browserless.page()
+const capture = createCapture({ goto: browserless.goto })
+
+const video = await capture(page)('https://example.com', {
+  duration: 5000,
+  type: 'mp4',
+  path: '/tmp/demo.mp4'
+})
+```
+
+API shape is intentionally simple, similar to `page.screenshot()`/`page.pdf()`:
+
+```js
+const capture = createCapture({ goto })
+await capture(page)(url, opts)
+```
+
+Returns a `Buffer` and writes to `opts.path` when provided.
+
+## Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `'webm' \| 'mp4'` | `'webm'` | Output type selector mapped to MediaRecorder mime type. |
+| `path` | `string` | `undefined` | Write the captured media to disk. |
+| `duration` | `number` | `3000` | Capture duration in milliseconds. |
+| `audio` | `boolean \| object` | `false` | Capture audio. When object, it is used as audio track constraints. |
+| `video` | `boolean \| object` | `true` | Capture video. When object, it is used as video track constraints. |
+
+## Exports
+
+- `capture.extensionPath`: Absolute path to the bundled extension.
+- `capture.extensionId`: Extension ID used by the package.
+- `capture.types`: Supported values for `type`.
+
+`capture` uses `goto(...).device.viewport` as the capture viewport source.
+When `video` is `true` or omitted, video constraints are inferred from that viewport to keep capture framing aligned with screenshot/pdf rendering.
+When `video` is an object, that object is used as the video constraints.
+When `audio` is an object, that object is used as the audio constraints.
+The inferred constraints also account for `deviceScaleFactor`, so output video pixels match screenshot pixel density.
+Bitrate hints are not configurable; capture uses Chrome MediaRecorder defaults.
+MediaRecorder chunk size is internal and fixed at `250ms`.
+`type` is mapped internally to the MediaRecorder mime type.
+When `type` is `'mp4'`, the running Chromium build must support MP4 MediaRecorder output.
+For strict screenshot/poster parity in headless mode, launch Chrome with matching `--screen-info`.
+
+## License
+
+**@browserless/capture** © [Microlink](https://microlink.io), released under the [MIT](https://github.com/microlinkhq/browserless/blob/master/LICENSE.md) License.

package/extension/background.js

@@ -0,0 +1,115 @@
+/* global chrome */
+
+const MESSAGE_KEY = '__browserless_capture__'
+const OFFSCREEN_PATH = 'offscreen.html'
+const MESSAGE_TIMEOUT = 10_000
+const OFFSCREEN_ALREADY_EXISTS_RE = /already exists|single offscreen document/i
+
+let offscreenDocumentPromise
+
+const sendToOffscreen = payload =>
+  new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new Error(`Timed out waiting for offscreen response after ${MESSAGE_TIMEOUT}ms`))
+    }, MESSAGE_TIMEOUT)
+
+    const done = callback => value => {
+      clearTimeout(timer)
+      callback(value)
+    }
+
+    chrome.runtime.sendMessage(
+      {
+        [MESSAGE_KEY]: true,
+        ...payload
+      },
+      done(response => {
+        if (chrome.runtime.lastError) {
+          return reject(new Error(chrome.runtime.lastError.message))
+        }
+
+        if (!response || !response.ok) {
+          return reject(new Error((response && response.error) || 'No response from offscreen.'))
+        }
+
+        resolve(response.value)
+      })
+    )
+  })
+
+const getMediaStreamId = tabId =>
+  new Promise((resolve, reject) => {
+    if (!Number.isInteger(tabId)) {
+      reject(new TypeError('Missing tab id for recording session.'))
+      return
+    }
+
+    chrome.tabCapture.getMediaStreamId({ targetTabId: tabId }, streamId => {
+      if (chrome.runtime.lastError || !streamId) {
+        return reject(
+          new Error(chrome.runtime.lastError?.message || 'Unable to obtain tab media stream id')
+        )
+      }
+
+      resolve(streamId)
+    })
+  })
+
+const getOffscreenContexts = async offscreenUrl => {
+  if (typeof chrome.runtime.getContexts !== 'function') return []
+  return chrome.runtime
+    .getContexts({
+      contextTypes: ['OFFSCREEN_DOCUMENT'],
+      documentUrls: [offscreenUrl]
+    })
+    .catch(() => [])
+}
+
+const ensureOffscreenDocument = async () => {
+  if (!chrome.offscreen || typeof chrome.offscreen.createDocument !== 'function') return
+  if (offscreenDocumentPromise) return offscreenDocumentPromise
+
+  offscreenDocumentPromise = (async () => {
+    const offscreenUrl = chrome.runtime.getURL(OFFSCREEN_PATH)
+    const contexts = await getOffscreenContexts(offscreenUrl)
+    if (contexts.length > 0) return
+
+    try {
+      await chrome.offscreen.createDocument({
+        url: OFFSCREEN_PATH,
+        reasons: ['USER_MEDIA'],
+        justification: 'Record tab media without opening a visible extension tab.'
+      })
+    } catch (error) {
+      if (OFFSCREEN_ALREADY_EXISTS_RE.test(error?.message || '')) return
+
+      const refreshedContexts = await getOffscreenContexts(offscreenUrl)
+      if (refreshedContexts.length > 0) return
+
+      throw error
+    }
+  })()
+
+  try {
+    await offscreenDocumentPromise
+  } finally {
+    offscreenDocumentPromise = undefined
+  }
+}
+
+globalThis.START_RECORDING = async settings => {
+  const [streamId] = await Promise.all([
+    getMediaStreamId(settings && settings.tabId),
+    ensureOffscreenDocument()
+  ])
+  return sendToOffscreen({
+    action: 'START_RECORDING',
+    settings: { ...settings, streamId }
+  })
+}
+
+globalThis.STOP_RECORDING = async index => {
+  try {
+    await sendToOffscreen({ action: 'STOP_RECORDING', index })
+  } catch (error) {}
+}

package/extension/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "Browserless Capture",
+  "version": "0.1.0",
+  "key": "ackedhmjjinfocdcekpnbdocpmiffaac",
+  "manifest_version": 3,
+  "permissions": ["tabs", "tabCapture", "offscreen", "debugger"],
+  "background": { "service_worker": "background.js" }
+}

package/extension/offscreen.html

@@ -0,0 +1 @@
+<script src="offscreen.js"></script>

package/extension/offscreen.js

@@ -0,0 +1,185 @@
+/* global chrome, WebSocket, MediaRecorder, navigator */
+
+const MESSAGE_KEY = '__browserless_capture__'
+const SOCKET_CONNECT_TIMEOUT = 10_000
+const recorders = {}
+const NOOP = () => {}
+
+const toErrorMessage = error => {
+  if (typeof error === 'string') return error
+  if (error && typeof error.message === 'string') return error.message
+  return 'Unknown extension error'
+}
+
+const waitForSocketOpen = client =>
+  new Promise((resolve, reject) => {
+    if (client.readyState === WebSocket.OPEN) return resolve()
+
+    const timer = setTimeout(() => {
+      cleanup()
+      reject(new Error(`Timed out opening websocket after ${SOCKET_CONNECT_TIMEOUT}ms`))
+    }, SOCKET_CONNECT_TIMEOUT)
+
+    const cleanup = () => {
+      clearTimeout(timer)
+      client.removeEventListener('open', onOpen)
+      client.removeEventListener('error', onError)
+      client.removeEventListener('close', onClose)
+    }
+
+    const onOpen = () => {
+      cleanup()
+      resolve()
+    }
+
+    const onError = () => {
+      cleanup()
+      reject(new Error('Unable to connect to websocket recorder endpoint'))
+    }
+
+    const onClose = () => {
+      cleanup()
+      reject(new Error('Websocket recorder endpoint closed before opening'))
+    }
+
+    client.addEventListener('open', onOpen, { once: true })
+    client.addEventListener('error', onError, { once: true })
+    client.addEventListener('close', onClose, { once: true })
+  })
+
+const buildTrackConstraints = ({ streamId, constraints }) => {
+  const source = constraints && typeof constraints === 'object' ? constraints : {}
+  const mandatory = source.mandatory && typeof source.mandatory === 'object' ? source.mandatory : {}
+  const { mandatory: _mandatory, ...rest } = source
+
+  return {
+    ...rest,
+    mandatory: {
+      ...mandatory,
+      chromeMediaSource: 'tab',
+      chromeMediaSourceId: streamId
+    }
+  }
+}
+
+const assertMimeTypeSupported = mimeType => {
+  if (!mimeType) return
+  if (typeof MediaRecorder.isTypeSupported !== 'function') return
+  if (MediaRecorder.isTypeSupported(mimeType)) return
+
+  throw new Error(`Unsupported MediaRecorder mimeType "${mimeType}" in this Chromium build.`)
+}
+
+const START_RECORDING = async ({
+  index,
+  port,
+  streamId,
+  video,
+  audio,
+  frameSize,
+  mimeType,
+  videoConstraints,
+  audioConstraints
+}) => {
+  if (!port) throw new Error('Missing websocket port for recording session.')
+  if (!streamId) throw new Error('Missing tab media stream id for recording session.')
+  assertMimeTypeSupported(mimeType)
+
+  const client = new WebSocket(`ws://127.0.0.1:${port}/?index=${index}`, [])
+
+  let audioStreamConstraints = false
+  let videoStreamConstraints = false
+
+  if (audio) {
+    audioStreamConstraints = buildTrackConstraints({
+      streamId,
+      constraints: audioConstraints
+    })
+  }
+
+  if (video) {
+    videoStreamConstraints = buildTrackConstraints({
+      streamId,
+      constraints: videoConstraints
+    })
+  }
+
+  const mediaStreamPromise = navigator.mediaDevices.getUserMedia({
+    audio: audioStreamConstraints,
+    video: videoStreamConstraints
+  })
+
+  let stream
+  try {
+    ;[stream] = await Promise.all([mediaStreamPromise, waitForSocketOpen(client)])
+  } catch (error) {
+    mediaStreamPromise
+      .then(openedStream => openedStream.getTracks().forEach(track => track.stop()))
+      .catch(NOOP)
+
+    if (client.readyState === WebSocket.CONNECTING || client.readyState === WebSocket.OPEN) {
+      client.close()
+    }
+
+    throw error
+  }
+
+  const recorder = new MediaRecorder(stream, { mimeType })
+
+  const pending = new Set()
+
+  recorder.ondataavailable = event => {
+    if (!event.data.size) return
+
+    const task = (async () => {
+      const buffer = await event.data.arrayBuffer()
+      if (client.readyState === WebSocket.OPEN) client.send(buffer)
+    })()
+
+    pending.add(task)
+    task.finally(() => pending.delete(task))
+  }
+
+  recorder.onerror = () => recorder.stop()
+
+  recorder.onstop = async () => {
+    await Promise.allSettled(pending)
+    stream.getTracks().forEach(track => track.stop())
+    if (client.readyState === WebSocket.OPEN) client.close()
+    delete recorders[index]
+  }
+
+  stream.onremovetrack = () => {
+    try {
+      recorder.stop()
+    } catch (error) {}
+  }
+
+  recorders[index] = recorder
+  recorder.start(frameSize)
+}
+
+const STOP_RECORDING = index => {
+  const recorder = recorders[index]
+  if (!recorder || recorder.state === 'inactive') return
+  recorder.stop()
+}
+
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (!message || !message[MESSAGE_KEY]) return
+
+  if (message.action === 'START_RECORDING') {
+    START_RECORDING(message.settings)
+      .then(value => sendResponse({ ok: true, value }))
+      .catch(error => sendResponse({ ok: false, error: toErrorMessage(error) }))
+    return true
+  }
+
+  if (message.action === 'STOP_RECORDING') {
+    Promise.resolve()
+      .then(() => STOP_RECORDING(message.index))
+      .then(() => sendResponse({ ok: true }))
+      .catch(error => sendResponse({ ok: false, error: toErrorMessage(error) }))
+    return true
+  }
+})

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@browserless/capture",
+  "description": "Record browser pages as videos with browserless-style API: createCapture({ goto })(page)(url, opts).",
+  "homepage": "https://browserless.js.org/#/?id=capturepage-options",
+  "version": "10.11.0",
+  "main": "src/index.js",
+  "author": {
+    "email": "hello@microlink.io",
+    "name": "microlink.io",
+    "url": "https://microlink.io"
+  },
+  "repository": {
+    "directory": "packages/capture",
+    "type": "git",
+    "url": "git+https://github.com/microlinkhq/browserless.git#master"
+  },
+  "bugs": {
+    "url": "https://github.com/microlinkhq/browserless/issues"
+  },
+  "keywords": [
+    "browserless",
+    "capture",
+    "video",
+    "recording",
+    "webm",
+    "mp4",
+    "headless",
+    "chrome",
+    "puppeteer",
+    "automation"
+  ],
+  "dependencies": {
+    "@browserless/goto": "^10.11.0",
+    "debug-logfmt": "~1.4.8",
+    "ws": "~8.18.3"
+  },
+  "devDependencies": {
+    "ava": "5"
+  },
+  "engines": {
+    "node": ">= 12"
+  },
+  "files": [
+    "extension",
+    "src"
+  ],
+  "license": "MIT",
+  "ava": {
+    "serial": true,
+    "timeout": "2m",
+    "workerThreads": false
+  },
+  "scripts": {
+    "bench:runtime": "node benchmarks/runtime-startup.js",
+    "coverage": "exit 0",
+    "test": "ava"
+  }
+}

package/src/capture.js

@@ -0,0 +1,303 @@
+'use strict'
+
+const { setTimeout } = require('timers/promises')
+const fs = require('fs/promises')
+const debug = require('debug-logfmt')('browserless:capture')
+
+const { closeServer, createWebSocketServer } = require('./util')
+const extension = require('./extension')
+
+const { INTERNAL_FRAME_SIZE, NOOP } = require('./constants')
+
+let currentIndex = 0
+
+const runWithDuration = async (label, fn, fields) => {
+  const duration = debug.duration(label)
+
+  try {
+    const value = await fn()
+    duration(fields)
+    return value
+  } catch (error) {
+    duration({
+      ...(fields || {}),
+      error: error && error.message
+    })
+    throw error
+  }
+}
+
+const createRecordingSession = ({ wss, index }) => {
+  const { promise, resolve, reject } = Promise.withResolvers()
+  let socket
+  let isSettled = false
+
+  const chunks = []
+
+  const done = (error, value) => {
+    if (isSettled) return
+    isSettled = true
+    wss.removeListener('connection', onConnection)
+
+    if (socket) {
+      socket.removeAllListeners('message').removeAllListeners('close').removeAllListeners('error')
+    }
+
+    if (error) return reject(error)
+    resolve(value)
+  }
+
+  const onConnection = (ws, req) => {
+    const url = new URL(req.url, 'ws://127.0.0.1')
+    if (url.searchParams.get('index') !== String(index)) return
+    socket = ws
+    socket
+      .on('message', buffer => chunks.push(buffer))
+      .once('error', error => done(error))
+      .once('close', () => done(null, Buffer.concat(chunks)))
+  }
+
+  wss.on('connection', onConnection)
+
+  return promise
+}
+
+const MIME_TYPES_BY_TYPE = Object.freeze({
+  webm: Object.freeze({
+    video: 'video/webm',
+    audio: 'audio/webm'
+  }),
+  mp4: Object.freeze({
+    video: 'video/mp4',
+    audio: 'audio/mp4'
+  })
+})
+
+const SUPPORTED_TYPES = Object.freeze(Object.keys(MIME_TYPES_BY_TYPE))
+
+const getMimeType = ({ type, audio, video }) => {
+  const normalizedType =
+    type === undefined || type === null
+      ? 'webm'
+      : String(type).trim().toLowerCase().replace(/^\./, '')
+
+  const mimeTypes = MIME_TYPES_BY_TYPE[normalizedType]
+
+  if (!mimeTypes) {
+    throw new TypeError(
+      `Unsupported \`type\` "${type}". Supported types: ${SUPPORTED_TYPES.join(', ')}.`
+    )
+  }
+
+  return audio && !video ? mimeTypes.audio : mimeTypes.video
+}
+
+const getVideoConstraints = (videoConstraints, viewport) => {
+  if (videoConstraints) return videoConstraints
+
+  const dpr = Math.max(Number(viewport.deviceScaleFactor) || 1, 1)
+  const width = Math.round(viewport.width * dpr)
+  const height = Math.round(viewport.height * dpr)
+
+  return {
+    mandatory: {
+      minWidth: width,
+      minHeight: height,
+      maxWidth: width,
+      maxHeight: height
+    }
+  }
+}
+
+const isTrackObject = value => value && typeof value === 'object' && !Array.isArray(value)
+
+const getOpts = (value, defaultValue, name) => {
+  const resolvedValue = value === undefined ? defaultValue : value
+
+  if (typeof resolvedValue === 'boolean') {
+    return {
+      enabled: resolvedValue,
+      constraints: undefined
+    }
+  }
+
+  if (isTrackObject(resolvedValue)) {
+    const constraints =
+      Object.keys(resolvedValue).length === 0
+        ? undefined
+        : resolvedValue.constraints !== undefined
+          ? resolvedValue.constraints
+          : resolvedValue
+
+    if (constraints !== undefined && !isTrackObject(constraints)) {
+      throw new TypeError(`Expected \`${name}.constraints\` to be an object`)
+    }
+
+    return {
+      enabled: true,
+      constraints
+    }
+  }
+
+  throw new TypeError(`Expected \`${name}\` to be a boolean or an object`)
+}
+
+const getTargetId = async page => {
+  if (!page || typeof page.target !== 'function') return
+
+  const target = page.target()
+  if (!target || typeof target.createCDPSession !== 'function') return
+
+  const session = await target.createCDPSession().catch(NOOP)
+  if (!session) return
+
+  try {
+    const result = await session.send('Target.getTargetInfo').catch(NOOP)
+    return result && result.targetInfo && result.targetInfo.targetId
+  } finally {
+    await session.detach().catch(NOOP)
+  }
+}
+
+module.exports = async (page, opts, viewport) => {
+  const { path: outputPath, duration = 3000, audio, video, type } = opts
+
+  const audioOpts = getOpts(audio, false, 'audio')
+  const videoOpts = getOpts(video, true, 'video')
+
+  if (!audioOpts.enabled && !videoOpts.enabled) {
+    throw new TypeError('At least one of `audio` or `video` must be true')
+  }
+
+  const browser = page.browser()
+  const index = currentIndex++
+
+  const streamMimeType = getMimeType({
+    type,
+    audio: audioOpts.enabled,
+    video: videoOpts.enabled
+  })
+
+  const resolvedVideoConstraints = getVideoConstraints(videoOpts.constraints, viewport)
+
+  let worker
+  let workerPromise
+  let wsServerPromise
+  let wss
+  let port
+  let recordingPromise
+  let isRecordingStarted = false
+  let captureError
+  let buffer = Buffer.alloc(0)
+  let targetId
+
+  try {
+    const targetIdPromise = runWithDuration('getPageTargetId', () => getTargetId(page))
+    workerPromise = runWithDuration('extension.open', () => extension.open({ browser }))
+    wsServerPromise = runWithDuration('createWebSocketServer', () => createWebSocketServer())
+
+    const [_targetId, _worker, wsServer] = await Promise.all([
+      targetIdPromise,
+      workerPromise,
+      wsServerPromise
+    ])
+
+    targetId = _targetId
+    worker = _worker
+    ;({ wss, port } = wsServer)
+    if (!targetId) throw new Error('Cannot resolve page target id.')
+
+    recordingPromise = createRecordingSession({ wss, index })
+
+    const tabId = await runWithDuration(
+      'extension.getTabIdFromTargetId',
+      () =>
+        extension.getTabIdFromTargetId({
+          worker,
+          targetId
+        }),
+      { targetId }
+    )
+    if (!Number.isInteger(tabId)) {
+      throw new Error('Cannot resolve tab id for the current page target.')
+    }
+
+    await runWithDuration(
+      'extension.startRecording',
+      () =>
+        extension.startRecording({
+          extension: worker,
+          settings: {
+            index,
+            port,
+            tabId,
+            video: videoOpts.enabled,
+            audio: audioOpts.enabled,
+            frameSize: INTERNAL_FRAME_SIZE,
+            mimeType: streamMimeType,
+            videoConstraints: resolvedVideoConstraints,
+            audioConstraints: audioOpts.constraints
+          }
+        }),
+      { index, tabId }
+    )
+    isRecordingStarted = true
+    await runWithDuration('durationwait', () => setTimeout(duration), { duration })
+  } catch (error) {
+    if (!worker && workerPromise) {
+      worker = await runWithDuration('awaitWorkerAfterError', () => workerPromise.catch(NOOP))
+    }
+    if (!wss && wsServerPromise) {
+      ;({ wss, port } =
+        (await runWithDuration('awaitWebSocketServerAfterError', () =>
+          wsServerPromise.catch(NOOP)
+        )) || {})
+    }
+    captureError = error
+  } finally {
+    const stopPromise = worker
+      ? runWithDuration(
+        'extension.stopRecording',
+        () => extension.stopRecording({ extension: worker, index }).catch(NOOP),
+        { index }
+      )
+      : Promise.resolve()
+
+    if (recordingPromise) {
+      if (isRecordingStarted) {
+        const recordingResultPromise = recordingPromise.catch(error => {
+          if (!captureError) throw error
+          return Buffer.alloc(0)
+        })
+        const [, recordingResult] = await runWithDuration('stop+recordingPromise', () =>
+          Promise.all([stopPromise, recordingResultPromise])
+        )
+        buffer = recordingResult
+      } else {
+        recordingPromise.catch(NOOP)
+        await runWithDuration('stopWithoutRecording', () => stopPromise)
+      }
+    } else {
+      await runWithDuration('stopWithoutPromise', () => stopPromise)
+    }
+
+    await runWithDuration('closeServer', () => closeServer(wss))
+  }
+
+  if (captureError) throw captureError
+
+  if (buffer.length === 0) {
+    throw new Error(
+      'No video data was captured. Increase `duration` or verify playback in the tab.'
+    )
+  }
+
+  if (outputPath) {
+    await runWithDuration('writeFile', () => fs.writeFile(outputPath, buffer), {
+      outputPath,
+      bytes: buffer.length
+    })
+  }
+
+  return buffer
+}

package/src/constants.js

@@ -0,0 +1,19 @@
+'use strict'
+
+const path = require('path')
+
+const EXTENSION_ID = 'jjndjgheafjngoipoacpjgeicjeomjli'
+
+const EXTENSION_PATH = path.join(__dirname, '..', 'extension')
+
+const TYPES = Object.freeze(['webm', 'mp4'])
+const INTERNAL_FRAME_SIZE = 250
+const NOOP = () => {}
+
+module.exports = {
+  EXTENSION_ID,
+  EXTENSION_PATH,
+  TYPES,
+  INTERNAL_FRAME_SIZE,
+  NOOP
+}

package/src/extension.js

@@ -0,0 +1,117 @@
+'use strict'
+
+const { EXTENSION_ID, EXTENSION_PATH, NOOP } = require('./constants')
+
+const BACKGROUND_PATH = `chrome-extension://${EXTENSION_ID}/background.js`
+const workerRuntimes = new WeakMap()
+const openingWorkerRuntimes = new WeakMap()
+
+const isCacheableBrowser = browser =>
+  browser && (typeof browser === 'object' || typeof browser === 'function')
+
+const createWorkerRuntime = browser => {
+  const findWorkerTarget = () => {
+    if (!browser || typeof browser.targets !== 'function') return
+    return browser
+      .targets()
+      .find(target => target.type() === 'service_worker' && target.url() === BACKGROUND_PATH)
+  }
+
+  const getWorker = async () => {
+    let target = findWorkerTarget()
+
+    if (!target && typeof browser.waitForTarget === 'function') {
+      target = await browser
+        .waitForTarget(
+          target => target.type() === 'service_worker' && target.url() === BACKGROUND_PATH,
+          { timeout: 1000 }
+        )
+        .catch(NOOP)
+    }
+
+    if (!target || typeof target.worker !== 'function') return
+    return target.worker().catch(NOOP)
+  }
+
+  const evaluate = async (fn, arg) => {
+    const worker = await getWorker()
+    if (!worker || typeof worker.evaluate !== 'function') {
+      throw new Error('Unable to access capture extension service worker runtime.')
+    }
+    return worker.evaluate(fn, arg)
+  }
+
+  return {
+    evaluate
+  }
+}
+
+const open = async ({ browser }) => {
+  if (isCacheableBrowser(browser)) {
+    const cachedRuntime = workerRuntimes.get(browser)
+    if (cachedRuntime) return cachedRuntime
+
+    const cachedOpening = openingWorkerRuntimes.get(browser)
+    if (cachedOpening) return cachedOpening
+  }
+
+  const openPromise = (async () => {
+    const workerRuntime = createWorkerRuntime(browser)
+    const isWorkerReady = await workerRuntime
+      .evaluate(
+        () =>
+          typeof globalThis.START_RECORDING === 'function' &&
+          typeof globalThis.STOP_RECORDING === 'function'
+      )
+      .catch(() => false)
+
+    if (!isWorkerReady) {
+      throw new Error(
+        `Unable to connect to capture extension service worker. Launch Chromium with extension support using \`${EXTENSION_PATH}\`.`
+      )
+    }
+
+    if (isCacheableBrowser(browser)) workerRuntimes.set(browser, workerRuntime)
+    return workerRuntime
+  })()
+
+  if (isCacheableBrowser(browser)) {
+    openingWorkerRuntimes.set(browser, openPromise)
+  }
+
+  try {
+    return await openPromise
+  } finally {
+    if (isCacheableBrowser(browser)) openingWorkerRuntimes.delete(browser)
+  }
+}
+
+const getTabIdFromTargetId = async ({ worker, targetId }) => {
+  try {
+    return worker.evaluate(async targetId => {
+      if (
+        !globalThis.chrome.debugger ||
+        typeof globalThis.chrome.debugger.getTargets !== 'function'
+      ) {
+        return
+      }
+
+      const targets = await globalThis.chrome.debugger.getTargets()
+      const target = targets.find(target => target && target.id === targetId)
+      return Number.isInteger(target && target.tabId) ? target.tabId : undefined
+    }, targetId)
+  } catch (_) {}
+}
+
+const startRecording = async ({ extension, settings }) =>
+  extension.evaluate(settings => globalThis.START_RECORDING(settings), settings)
+
+const stopRecording = async ({ extension, index }) =>
+  extension.evaluate(index => globalThis.STOP_RECORDING(index), index)
+
+module.exports = {
+  open,
+  getTabIdFromTargetId,
+  startRecording,
+  stopRecording
+}

package/src/index.js

@@ -0,0 +1,24 @@
+'use strict'
+
+const debug = require('debug-logfmt')('browserless:capture')
+const createGoto = require('@browserless/goto')
+
+const { EXTENSION_ID, EXTENSION_PATH, TYPES } = require('./constants')
+const runCapture = require('./capture')
+
+module.exports = ({ goto, ...gotoOpts } = {}) => {
+  goto = goto || createGoto(gotoOpts)
+  return function capture (page) {
+    return async (url, opts = {}) => {
+      const duration = debug.duration({ url }, opts)
+      const { device } = await goto(page, { ...opts, url })
+      const result = await runCapture(page, opts, device.viewport)
+      duration.info()
+      return result
+    }
+  }
+}
+
+module.exports.extensionPath = EXTENSION_PATH
+module.exports.extensionId = EXTENSION_ID
+module.exports.types = TYPES

package/src/util.js

@@ -0,0 +1,49 @@
+'use strict'
+
+const { WebSocketServer } = require('ws')
+
+const closeServer = wss => {
+  const { promise, resolve } = Promise.withResolvers()
+
+  if (!wss) {
+    resolve()
+    return promise
+  }
+
+  try {
+    wss.close(() => resolve())
+  } catch (error) {
+    resolve()
+  }
+
+  return promise
+}
+
+const createWebSocketServer = () => {
+  const { promise, resolve, reject } = Promise.withResolvers()
+  const wss = new WebSocketServer({ host: '127.0.0.1', port: 0 })
+
+  const onListening = () => {
+    cleanup()
+    const { port } = wss.address()
+    resolve({ wss, port })
+  }
+
+  const onError = error => {
+    cleanup()
+    reject(error)
+  }
+
+  const cleanup = () => {
+    wss.removeListener('listening', onListening).removeListener('error', onError)
+  }
+
+  wss.once('listening', onListening).once('error', onError)
+
+  return promise
+}
+
+module.exports = {
+  closeServer,
+  createWebSocketServer
+}