OverlayController

OverlayController = Promise<void>

An overlay controller.

Calling it shows the overlay over a frozen frame for a fixed duration (blocking). Use start()/end() to keep the overlay on screen while the page is driven underneath.

For an overlay with an intrinsic length (a .mp4 video, an embedded video dependency, or an animated HTML/React clip), end() lets the clip finish: if the media outlasts the live window, the remainder plays out over a frozen frame before the timeline continues, rather than being cut. To show less of such a clip, trim it (start/end/speed/time, or selected(..., { end })) rather than ending early. Length-less overlays (image, inline html, React) end exactly at end().

Overlays may overlap: several can be live at once (interleaved, not just nested), and a blocking overlay can run while others stay live. Each overlay you start() must be end()ed before the video function returns, and the same overlay cannot be started twice without ending it in between.

Example

// Blocking: hold the overlay for 1.2s, then continue.
await overlays.logo(1200)

// Live: keep the overlay up while interacting with the page.
await overlays.badge.start()
await page.click('#next')
await overlays.badge.end()

// Overlapping: two overlays live at the same time, ended independently.
await overlays.badge.start()
await overlays.logo.start()
await page.click('#next')
await overlays.badge.end()
await overlays.logo.end()

OverlayController(): Promise<void>

Hold the overlay for its natural length. Valid only for a source with an intrinsic length (a .mp4 video, or an embedded video dependency). Image, inline html, and React overlays have no natural length: use .for(...), .until(...), or drive them with start()/end().

Returns

Promise<void>

Methods

end()

end(): Promise<void>

Defined in: asset.ts:757

Stop a live overlay. For a length-less overlay (image/HTML/React) it ends immediately. For an overlay with an intrinsic length (video / dependency / animated) whose media has not finished, the clip plays out to its natural end over a frozen frame before the timeline continues; trim the source to show less instead of ending early.

Returns

Promise<void>

for()

for(duration): Promise<void>

Defined in: asset.ts:739

Hold the overlay for a relative length in milliseconds, e.g. .for(2000). A percentage is rejected (a relative length has nothing to take a percentage of). Not for .mp4/animated overlays, whose length is fixed.

Parameters

duration

number

Returns

Promise<void>

start()

start(): Promise<void>

Defined in: asset.ts:749

Show the overlay live over the recording (non-blocking); pair with end().

Returns

Promise<void>

until()

until(position): Promise<void>

Defined in: asset.ts:747

Keep the overlay visible until this absolute point in the final video (a '<n>s'/timecode position, or a '<n>%' fraction). Supported for image, HTML/React (static), and embedded-render overlays; not for .mp4 or animated overlays, whose length is fixed. Successive .until(...) targets must be monotonic (each at or after the previous timeline point).

Parameters

position

TimelineOffset

Returns

Promise<void>