RecordOptions

RecordOptions = object

Configuration options for video recording.

Example:

const options: RecordOptions = {
  aspectRatio: '16:9',
  quality: '1080p',
  fps: 60,
}

Properties

aspectRatio?

optional aspectRatio?: AspectRatio

Defined in: types.ts:358

Aspect ratio used when capturing the screen.

Together with quality this determines the browser viewport and ffmpeg input dimensions. See AspectRatio for all supported ratios and their pixel sizes.

Default

'16:9'

captureAudio?

optional captureAudio?: boolean | { gain: number; }

Defined in: types.ts:455

Capture system audio alongside the screen recording and mix it into the output video.

Set to true to capture at unity gain, or pass { gain } for a custom linear gain:

true: capture at unity gain (natural level).
{ gain: 0.5 }: capture at half volume.
{ gain: 2 }: boost to twice the natural level.

Audio is captured via ffmpeg from the platform default audio input and mixed into the rendered video. While capture is enabled the browser plays the page audio out loud on the host so the recorder can tap it. Each OS requires a one-time loopback source setup to capture system audio rather than the microphone. See the per-OS guide: https://screenci.com/docs/guides/screen-audio

Default

false

deviceScaleFactor?

optional deviceScaleFactor?: number

Defined in: types.ts:434

Device scale factor (DPR) used when capturing.

Screenshots multiply the viewport by this for a higher-DPI still: 2 doubles the pixel density. This is the easy way to ask for a sharper screenshot. It does not apply to video recording (the screencast stays at the viewport resolution).

Default

2 for screenshots, ignored for video

disableAnimations?

optional disableAnimations?: boolean

Defined in: types.ts:503

Neutralize CSS animations and transitions while the page is driven, so every interaction lands on its element’s end state instead of waiting for an animation to settle.

When unset this defaults to true for screenshots and false for video. A still has no timeline, so animating the UI only slows the interactions that drive the page into position (each Playwright action waits for its target to stop moving). Video is left animated because motion is usually the point.

Override it to opt back in or out: set false on a screenshot that needs a mid-animation state, or true on a video to strip animations.

Default

true for screenshots, false for video

encoder?

optional encoder?: VideoEncoderPreset

Defined in: types.ts:422

Encoder used for the realtime screen capture.

'sharp' - tuned for text-heavy UI (low CRF + still-image tune) so glyph edges stay crisp. Uses a little more CPU; on most machines it still encodes comfortably above realtime.
'fast' - the lightest possible encode (ultrafast preset). Use this on resource-constrained CI where 'sharp' cannot keep up with the capture stream (falling behind drops frames and shortens the recording).

Defaults to 'fast' as the safe baseline. The init-scaffolded config sets process.env.CI ? 'fast' : 'sharp' so new projects get crisp text locally.

Default

'fast'

fps?

optional fps?: FPS

Defined in: types.ts:376

Frames per second for video recording.

Default

implicitEditable?

optional implicitEditable?: boolean

Defined in: types.ts:388

Make actions that use default values in code editable from the web editor. When enabled (the default), every interaction called without explicit ScreenCI options (cursor timing, zoom options) is stamped as web-editable, so its timings can be adjusted from the web timeline and applied on the next record. An action with any explicit option set in code is locked as a whole (there are no partially editable actions).

Default

true

performance?

optional performance?: PerformanceOption

Defined in: types.ts:405

Tunes how many output frames screenci skips between cursor and scroll dispatches while recording. Dispatching less often keeps interactions responsive on busy pages / slow CI (each dispatch queues behind the page’s own work).

Pass an object of frame-skip counts to tune each stream independently (0 = every frame).

By default the cursor skips 5 frames (it is re-drawn at render time, so this is free) and the scroll skips none (it is real footage, so it stays smooth). Intervals are derived from the recording fps.

Example

{ mouseFrameSkip: 5, scrollFrameSkip: 0 }

quality?

optional quality?: Quality

Defined in: types.ts:369

Resolution quality preset used when capturing the screen.

Together with aspectRatio this determines the browser viewport and ffmpeg input dimensions. See Quality for the full dimension table.

Default

'1080p'

redact?

optional redact?: string[]

Defined in: types.ts:469

CSS selectors whose matching elements are masked from the very first frame, before any page script runs. Use this for elements that are always secret (API keys, account numbers) so there is no window where they could be captured in the clear.

The mask is applied client side in the live DOM, so the obscured pixels never enter recording.mp4 and are never uploaded. For masking that starts at a specific moment, use the redact() helper instead.

Example

['.api-key', '[data-sensitive]']

scrollCentering?

optional scrollCentering?: number

Defined in: types.ts:486

Vertical framing bias (0–1) used when a plain interaction (a click(), fill(), scrollIntoViewIfNeeded(), etc. that is not zooming) scrolls its target into view.

0 reveals the target just inside the top edge, 1 places it dead center, and the default 0.2 frames it gently toward the upper third so already-visible elements are not yanked to the center on every click.

This only affects plain scroll reveals. Zooming (zoomTo/autoZoom) keeps its tight centering, and an explicit per-call centering (via autoZoomOptions or scrollIntoViewIfNeeded({ centering })) always wins.

Default

0.2