Skip to content

Module: src/ui/Overlays

The Overlays component displays layered visual elements—such as logos or posters—on top of the player viewport. It supports various positioning, scaling and timing modes. Overlays can be added dynamically or defined as part of the media data. An Overlay could be any DOM construct, but for now, only images are supported.

Version
1.2.1
Author
Frank Kudermann - alphanull
License
MIT
Requires
DomSmith
convertTime
Source
Overlays.js, line 17

Constructor

new Overlays(player, parent, optionsopt)

Creates an instance of the Overlays component.

Parameters:
Name Type Attributes Description
player Player

Reference to the VisionPlayer instance.
parent Controller

Reference to the parent instance.
options Object optional

Additional options.

Parameters:
Name Type Attributes Description
apiKey symbol optional

Token for extended access to the player API.

Members

Holds the instance configuration for this component.

Properties
Name Type Attributes Default Description
adaptLayout boolean optional true

Aligns overlay positioning with controller and title visibility state.
sanitizeHTML boolean optional false

Sanitizes the HTML of the overlay to prevent XSS attacks.
Type
Object
Source
Overlays.js, line 25

Reference to the main player instance.

Type
Player
Source
Overlays.js, line 34

Holds tokens of subscriptions to player events, for later unsubscribe.

Type
Array<number>
Source
Overlays.js, line 40

A DomSmith instance containing the overlay containers.

Type
DomSmith
Source
Overlays.js, line 46

This array contains overlay data and elements.

Type
Array<Overlays~overlayItem>
Source
Overlays.js, line 52

Methods

private #onDataReady(mediaItem)

Called when the media data is ready. Extracts overlay definitions and sets them up.

Parameters:
Name Type Description
mediaItem Data~mediaItem

Object containing media type info.

Parameters:
Name Type Attributes Description
overlays Array<Data~mediaItem_overlay> optional

The array of overlays from the media data.
Listens
data/ready
Source
Overlays.js, line 106

addOverlay(overlay)

Creates and adds a single overlay item to the DOM.

Parameters:
Name Type Description
overlay Data~mediaItem_overlay

The overlay definition from the media data.
Source
Overlays.js, line 128

private #onLoad(event)

Called when an overlay image loads successfully.

Parameters:
Name Type Description
event Event

Original onload event.
Source
Overlays.js, line 237

private #update(data, topic)

Updates the visibility of overlays based on the current playback time and status.

Parameters:
Name Type Description
data Object

Event data (unused).
topic string

Event topic (checks for "ended" to handle "poster-end" posters).
Listens
media/timeupdate
media/seeked
media/ended
Source
Overlays.js, line 262

private #enable()

Enables the next / prev button functionality. This method listens to canplay events in order to restore a usable state again when the player recovered from a media error (for example by loading another file).

Listens
media/canplay
Source
Overlays.js, line 298

private #disable()

Disables the next / prev button functionality. This method listens to media error events which cause the button to be disabled.

Listens
media/error
data/nomedia
Source
Overlays.js, line 309

private #removeOverlays()

Helper function which removes all overlays.

Source
Overlays.js, line 318

destroy()

This method removes all events, subscriptions and DOM nodes created by this component.

Source
Overlays.js, line 331

Type Definitions

Represents a single overlay item with its own DOM element and display rules.

Properties
Name Type Attributes Default Description
ele HTMLElement

The DOM element containing the overlay.
type string

Overlay type (e.g. 'image', 'poster', 'poster-end').
src string

Source URL of the overlay image (if applicable).
show string optional

Controls when the overlay should be displayed, e.g. 'begin', 'end', 'pause', 'play'.
className string optional ""

Additional CSS classes to apply to the overlay element.
scale string optional

Determines how to scale the overlay, e.g. 'cover" or 'contain'. If undefined, no scaling is applied.
placement string optional 'center'

Controls overlay placement, e.g. 'top', 'bottom-right', etc.
margin number optional 0

Margin (in px) around the overlay content.
cueIn number optional 0

Start time in seconds when this overlay should appear.
cueOut number optional Infinity

End time in seconds when this overlay should disappear.
visible boolean

Whether the overlay is currently visible or not.
background boolean optional

True if the overlay uses a background image (for 'cover' / 'contain' scaling).
opaque boolean optional

True if the overlay background is opaque (e.g. For a poster).
loaded boolean optional

True if the overlay image has finished loading.
img HTMLImageElement optional

The underlying element if used for 'cover' / 'contain'.
Type
Object
Source
Overlays.js, line 342