@browserless/capture 10.11.3 → 10.11.4

package/README.md

@@ -56,6 +56,8 @@ const capture = createCapture({ goto: browserless.goto })
 const video = await capture(page)('https://example.com', {
   duration: 5000,
   type: 'mp4',
+  codec: 'avc1.4D401F',
+  quality: 'high',
   path: '/tmp/demo.mp4'
 })
 
@@ -84,7 +86,9 @@ Returns a `Buffer` and writes to `opts.path` when provided.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `type` | `'webm' \| 'mp4'` | `'webm'` | Output type selector mapped to MediaRecorder mime type. |
+| `type` | `'webm' \| 'mp4'` | `'mp4'` | Output type selector mapped to MediaRecorder mime type. |
+| `codec` | `string` | Depends on `type` | MediaRecorder codec override. Defaults: `webm -> vp9`, `mp4 -> avc1.4D401F`. |
+| `quality` | `'extra-high' \| 'high' \| 'medium' \| 'low' \| 'extra-low'` | `'high'` | Video quality hint mapped to `MediaRecorder.videoBitsPerSecond`. |
 | `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. |
@@ -95,15 +99,26 @@ Returns a `Buffer` and writes to `opts.path` when provided.
 - `capture.extensionPath`: Absolute path to the bundled extension.
 - `capture.extensionId`: Extension ID used by the package.
 - `capture.types`: Supported values for `type`.
+- `capture.qualities`: Supported values for `quality`.
 
 `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.
+Capture always enforces `videoConstraints.mandatory.maxFrameRate = 120`.
+`quality` maps to bitrate presets (`extra-high`: 20Mbps, `high`: 8Mbps, `medium`: 5Mbps, `low`: 2.5Mbps, `extra-low`: 1Mbps).
 MediaRecorder chunk size is internal and fixed at `250ms`.
-`type` is mapped internally to the MediaRecorder mime type.
+`type` is mapped internally to the MediaRecorder mime type, and `codec` is appended as `;codecs=...`.
+Default codecs are `vp9` for `webm` and `avc1.4D401F` for `mp4`.
+You can override codec per request using `opts.codec`.
+For example:
+
+```js
+await capture(page)(url, { type: 'webm', codec: 'vp8' })
+await capture(page)(url, { type: 'mp4', codec: 'avc1.640033' })
+```
+
 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`.
 

package/extension/offscreen.js

@@ -78,6 +78,7 @@ const START_RECORDING = async ({
   audio,
   frameSize,
   mimeType,
+  recorderOptions,
   videoConstraints,
   audioConstraints
 }) => {
@@ -124,7 +125,7 @@ const START_RECORDING = async ({
     throw error
   }
 
-  const recorder = new MediaRecorder(stream, { mimeType })
+  const recorder = new MediaRecorder(stream, { mimeType, ...recorderOptions })
 
   const pending = new Set()
 

package/package.json

@@ -2,7 +2,7 @@
   "name": "@browserless/capture",
   "description": "Record a Puppeteer page using tabCapture API",
   "homepage": "https://browserless.js.org/#/?id=capturepage-options",
-  "version": "10.11.3",
+  "version": "10.11.4",
   "main": "src/index.js",
   "author": {
     "email": "hello@microlink.io",
@@ -30,7 +30,7 @@
     "webm"
   ],
   "dependencies": {
-    "@browserless/goto": "^10.11.3",
+    "@browserless/goto": "^10.11.4",
     "debug-logfmt": "~1.4.8",
     "ws": "~8.19.0"
   },
@@ -45,7 +45,6 @@
     "src"
   ],
   "scripts": {
-    "bench:runtime": "node benchmarks/runtime-startup.js",
     "coverage": "exit 0",
     "test": "ava"
   },
@@ -55,5 +54,5 @@
     "timeout": "2m",
     "workerThreads": false
   },
-  "gitHead": "2f86ba8d35c9b92c3c19e310282a3d24d0e0c7e0"
+  "gitHead": "9ff2a0f0dad20d64a5c47a04a989ee77d1ee5ae8"
 }

package/src/capture.js

@@ -7,7 +7,15 @@ const debug = require('debug-logfmt')('browserless:capture')
 const { closeServer, createWebSocketServer } = require('./util')
 const extension = require('./extension')
 
-const { DEFAULT, INTERNAL_FRAME_SIZE, NOOP } = require('./constants')
+const {
+  DEFAULT,
+  DEFAULT_CODEC_BY_TYPE,
+  INTERNAL_FRAME_SIZE,
+  MAX_FRAME_RATE,
+  NOOP,
+  QUALITIES,
+  VIDEO_BITS_PER_SECOND_BY_QUALITY
+} = require('./constants')
 
 let currentIndex = 0
 
@@ -63,19 +71,48 @@ const createRecordingSession = ({ wss, index }) => {
 }
 
 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'
-  })
+  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 getQuality = quality => {
+  const normalizedQuality =
+    quality === undefined || quality === null
+      ? DEFAULT.quality
+      : String(quality)
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, '-')
+
+  if (!QUALITIES.includes(normalizedQuality)) {
+    throw new TypeError(
+      `Unsupported \`quality\` "${quality}". Supported qualities: ${QUALITIES.join(', ')}.`
+    )
+  }
+
+  return normalizedQuality
+}
+
+const getCodec = ({ codec, type, video }) => {
+  if (codec === undefined || codec === null) {
+    return video ? DEFAULT_CODEC_BY_TYPE[type] : undefined
+  }
+
+  if (typeof codec !== 'string') {
+    throw new TypeError(`Expected \`codec\` to be a string. Received ${typeof codec}.`)
+  }
+
+  const normalizedCodec = codec.trim()
+  if (!normalizedCodec) {
+    throw new TypeError('Expected `codec` to be a non-empty string.')
+  }
+
+  return normalizedCodec
+}
+
+const getMimeType = ({ type, audio, video, codec }) => {
   const normalizedType =
     type === undefined || type === null
       ? DEFAULT.type
@@ -89,24 +126,42 @@ const getMimeType = ({ type, audio, video }) => {
     )
   }
 
-  return audio && !video ? mimeTypes.audio : mimeTypes.video
+  const streamMimeType = audio && !video ? mimeTypes.audio : mimeTypes.video
+  const resolvedCodec = getCodec({ codec, type: normalizedType, video })
+
+  return resolvedCodec ? `${streamMimeType};codecs=${resolvedCodec}` : streamMimeType
 }
 
 const getVideoConstraints = (videoConstraints, viewport) => {
-  if (videoConstraints) return videoConstraints
+  const withMaxFrameRate = 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,
+        maxFrameRate: MAX_FRAME_RATE
+      }
+    }
+  }
+
+  if (videoConstraints) return withMaxFrameRate(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 {
+  return withMaxFrameRate({
     mandatory: {
       minWidth: width,
       minHeight: height,
       maxWidth: width,
       maxHeight: height
     }
-  }
+  })
 }
 
 const isTrackObject = value => value && typeof value === 'object' && !Array.isArray(value)
@@ -160,7 +215,7 @@ const getTargetId = async page => {
 }
 
 module.exports = async (page, opts, viewport) => {
-  const { path: outputPath, duration = DEFAULT.duration, audio, video, type } = opts
+  const { path: outputPath, duration = DEFAULT.duration, audio, video, type, quality, codec } = opts
 
   const audioOpts = getOpts(audio, false, 'audio')
   const videoOpts = getOpts(video, true, 'video')
@@ -174,10 +229,16 @@ module.exports = async (page, opts, viewport) => {
 
   const streamMimeType = getMimeType({
     type,
+    codec,
     audio: audioOpts.enabled,
     video: videoOpts.enabled
   })
 
+  const resolvedQuality = getQuality(quality)
+  const recorderOptions = videoOpts.enabled
+    ? { videoBitsPerSecond: VIDEO_BITS_PER_SECOND_BY_QUALITY[resolvedQuality] }
+    : undefined
+
   const resolvedVideoConstraints = getVideoConstraints(videoOpts.constraints, viewport)
 
   let worker
@@ -235,6 +296,7 @@ module.exports = async (page, opts, viewport) => {
             audio: audioOpts.enabled,
             frameSize: INTERNAL_FRAME_SIZE,
             mimeType: streamMimeType,
+            recorderOptions,
             videoConstraints: resolvedVideoConstraints,
             audioConstraints: audioOpts.constraints
           }

package/src/constants.js

@@ -3,10 +3,23 @@
 const path = require('path')
 
 module.exports = {
-  DEFAULT: Object.freeze({ duration: 3000, type: 'webm' }),
+  MAX_FRAME_RATE: 120,
+  DEFAULT: Object.freeze({ duration: 3000, type: 'mp4', quality: 'high' }),
+  DEFAULT_CODEC_BY_TYPE: Object.freeze({
+    webm: 'vp9',
+    mp4: 'avc1.4D401F'
+  }),
   EXTENSION_ID: 'jjndjgheafjngoipoacpjgeicjeomjli',
   EXTENSION_PATH: path.join(__dirname, '..', 'extension'),
   TYPES: Object.freeze(['webm', 'mp4']),
+  QUALITIES: Object.freeze(['extra-high', 'high', 'medium', 'low', 'extra-low']),
+  VIDEO_BITS_PER_SECOND_BY_QUALITY: Object.freeze({
+    'extra-high': 20_000_000,
+    high: 8_000_000,
+    medium: 5_000_000,
+    low: 2_500_000,
+    'extra-low': 1_000_000
+  }),
   INTERNAL_FRAME_SIZE: 250,
   NOOP: () => {}
 }

package/src/index.js

@@ -3,7 +3,7 @@
 const debug = require('debug-logfmt')('browserless:capture')
 const createGoto = require('@browserless/goto')
 
-const { DEFAULT, EXTENSION_ID, EXTENSION_PATH, TYPES } = require('./constants')
+const { DEFAULT, EXTENSION_ID, EXTENSION_PATH, QUALITIES, TYPES } = require('./constants')
 const runCapture = require('./capture')
 
 module.exports = ({ goto, ...gotoOpts } = {}) => {
@@ -22,4 +22,5 @@ module.exports = ({ goto, ...gotoOpts } = {}) => {
 module.exports.extensionPath = EXTENSION_PATH
 module.exports.extensionId = EXTENSION_ID
 module.exports.types = TYPES
+module.exports.qualities = QUALITIES
 module.exports.DEFAULT = DEFAULT