Skip to main content

Interface: PlayerOptions

Options for EvePlayer's constructor. Every field is optional; the defaults produce a controlled, non-autoplaying, responsive player.

Properties​

autoplay?​

optional autoplay?: boolean

Start playback automatically once a source is loaded. Default: false.

background?​

optional background?: boolean

Decorative "background video" mode, for using the player as a backdrop behind other UI rather than something a viewer interacts with. Implies hideControls; also defaults autoplay/muted/loop to true (only for values not explicitly set), hides the loading spinner and error overlay, disables the native right-click context menu, and marks the container aria-hidden. Default: false.

captionSettings?​

optional captionSettings?: boolean

Show the "captions settings" entry inside the subtitles/CC menu: the native Video.js text-track styling dialog (font, colour, background, edge style…). Default: true. Set to false to drop both the menu entry and the dialog (passes textTrackSettings: false to Video.js).

chapterMarkers?​

optional chapterMarkers?: boolean

Split the progress bar into one segment per chapter, with a small gap at each chapter boundary, and show the chapter title above the time while the mouse hovers the bar. Default: true. Like the chapters button, it only shows when the current source has a kind: 'chapters' text track with cues, and it is skipped on live streams. Independent of PlayerOptions.chapters: either can be turned off without the other. The gap width is the --eve-chapter-gap CSS variable (default 2px).

chapters?​

optional chapters?: boolean

Show the chapters button in the control bar (the list icon, sitting with the audio/subtitles menus). Default: true. The button only appears when the current source actually has a kind: 'chapters' text track with cues; set to false to remove it even then.

fluid?​

optional fluid?: boolean

Video.js fluid mode: the player takes the container's full width and derives its height from the media's aspect ratio (16:9 until the media's dimensions are known), so the box follows the video. With false, the player is laid out at the media's intrinsic pixel size, and sizing it is up to your CSS (e.g. .my-player .video-js { width: 100%; height: 100%; }). Ignored for the box size when widescreen is set, since the 16:9 frame wins. Default: true.

hideControls?​

optional hideControls?: boolean

Hide the Video.js control bar entirely. Default: false.

hidePlayButton?​

optional hidePlayButton?: boolean

Hide the large centre play-button overlay (the poster stays visible). Default: false.

hideSpeed?​

optional hideSpeed?: boolean

Hide the "Playback speed" section from the settings menu. Default: false.

labels?​

optional labels?: LanguageDictionary

Per-player overrides for UI labels, keyed by the English text of the label (the same keys as the dictionaries passed to EvePlayer.addLanguage, listed in the package's lang/en.json), e.g. { 'Settings': 'Options' }. They win over any registered dictionary, whatever the active language, and apply to every label: the player's own and the ones it inherits from Video.js ('Play', 'Mute', …). Change them later with EvePlayer.setLabels.

language?​

optional language?: string

BCP-47 language code for the player's built-in UI labels (e.g. it, fr). Default: the browser's preferred language. The labels are translated only if a dictionary for that language was registered with EvePlayer.addLanguage; a regional code (it-CH) falls back to its base language (it), and anything still missing stays in English.

loop?​

optional loop?: boolean

Loop playback when it reaches the end. Default: false.

maxBandwidth?​

optional maxBandwidth?: number

Ceiling, in bits per second, for the same bandwidth estimate — useful to cap network/CDN usage on kiosk or embedded deployments. Same validation as minBandwidth. Default: unset (no ceiling).

minBandwidth?​

optional minBandwidth?: number

Floor, in bits per second, for the bandwidth estimate the "Auto" quality selector (see docs/adr/0001) uses to pick a rendition — never a hard filter on which renditions exist. Useful to guarantee a minimum quality even if the network estimate dips. Must be a finite number > 0, and minBandwidth <= maxBandwidth when both are set; an invalid value is ignored (with a console.warn), same as an unset one. Default: unset (no floor).

muted?​

optional muted?: boolean

Start muted. Default: false.

This is the initial state only, not a standing instruction: once the viewer (or the app) unmutes, the player never re-mutes itself, not even across a source swap or a reset() that rebuilds the underlying tech. Typically set to true alongside autoplay so browsers allow unattended playback, then cleared by an unmute control.

pip?​

optional pip?: boolean

Show the custom CSS Picture-in-Picture button in the control bar. Default: true.

pipPlaceholderText?​

optional pipPlaceholderText?: string

Text shown in the in-flow placeholder that holds the player's original space while PiP is active (the player itself floats away as the PiP window). The placeholder matches the player's size at the moment PiP is activated, so surrounding page content doesn't jump. Default: 'Video is playing in picture-in-picture', translated like any other label (see PlayerOptions.labels). A value set here is used as is and wins over any translation. Pass an empty string for a blank placeholder that still reserves the space.

playbackRates?​

optional playbackRates?: number[]

Playback-speed steps offered in the settings menu. Default: [0.5, 0.75, 1, 1.25, 1.5, 2].

quality?​

optional quality?: boolean

Show the "Quality" section inside the settings menu. Default: true (the section itself is still hidden when fewer than 2 quality levels exist).

settings?​

optional settings?: boolean

Show the settings (gear) menu in the control bar. Default: true. The gear is hidden automatically per source unless it has something to offer: i.e. at least 2 quality levels, or the "Playback speed" section (see hideSpeed). Set to false to remove it entirely.

showProgressDot?​

optional showProgressDot?: boolean

Show the scrubber dot at the head of the played portion of the progress bar. Default: false.

showVolumeDot?​

optional showVolumeDot?: boolean

Show the handle dot at the head of the filled portion of the volume bar. Default: false.

thumbnails?​

optional thumbnails?: boolean

Show a thumbnail-preview popup on progress-bar hover, when the manifest provides a thumbnail-tile track: DASH (dashif.org "thumbnail_tile" convention) or HLS (EXT-X-IMAGE-STREAM-INF/EXT-X-TILES). Default: true.

widescreen?​

optional widescreen?: boolean

Give the container a fixed 16:9 frame (aspect-ratio: 16 / 9; width: 100%, via the vjsp-widescreen class) and make the player fill it. A video of any other aspect ratio is letterboxed or pillarboxed in black inside the frame, so the box never changes size with the media. Useful when the space must be known before the media loads (a server-rendered placeholder carrying the same class, a grid or carousel of equal tiles). To use a different frame, keep this option and override the container's aspect-ratio or height in your own CSS. Audio-only sources collapse the frame to the control bar. Default: false.