limestone/VideoPlayer

Provides Limestone-themed video player components.

Import Usage

import VideoPlayer from '@enact/limestone/VideoPlayer';

Members

VideoPlayer   Component

A standard HTML5 video player for Limestone. It behaves, responds to, and operates like a <video> tag in its support for <source>. It also accepts custom tags such as <infoComponents> for displaying additional information in the title area and <MediaControls> for handling media playback controls and adding more controls.

Example usage:

<VideoPlayer title="Hilarious Cat Video" poster="https://my.cat.videos/boots-poster.jpg">
	<source src="https://my.cat.videos/boots.mp4" type="video/mp4" />
	<infoComponents>A video about my cat Boots, wearing boots.</infoComponents>
	<MediaControls>
		<leftComponents><Button backgroundOpacity="translucent" icon="star" /></leftComponents>
		<rightComponents><Button backgroundOpacity="translucent" icon="notification" /></rightComponents>

		<Button backgroundOpacity="translucent">Add To Favorites</Button>
		<Button backgroundOpacity="translucent" icon="search" />
	</MediaControls>
</VideoPlayer>

To invoke methods (e.g.: fastForward()) or get the current state (getMediaState()), store a ref to the VideoPlayer within your component:

	...

	setVideoPlayer = (node) => {
		this.videoPlayer = node;
	}

	play () {
		this.videoPlayer.play();
	}

	render () {
		return (
			<VideoPlayer ref={this.setVideoPlayer} />
		);
	}

Import Usage

import VideoPlayer from '@enact/limestone/VideoPlayer';

Wrapped with: ui/Slottableui/Slottable.Slottable

Video   Component

Provides support for more advanced video configurations for VideoPlayer.

Custom Video Tag

<VideoPlayer>
  <Video mediaComponent="custom-video-element">
    <source src="path/to/source.mp4" />
  </Video>
</VideoPlayer>

Preload Video Source

<VideoPlayer>
  <Video>
    <source src="path/to/source.mp4" />
    <source src="path/to/preload-source.mp4" slot="preloadSource" />
  </Video>
</VideoPlayer>

Import Usage

import {Video} from '@enact/limestone/VideoPlayer';

Wrapped with: ui/Slottableui/Slottable.Slottable

Properties

autoPlay

Boolean

Video plays automatically.

Default: false

---

mediaComponent

StringComponentElement

Video component to use.

The default ('video') renders an HTMLVideoElement. Custom video components must have a similar API structure, exposing the following APIs:

Properties:

• currentTime {Number} - Playback index of the media in seconds

• duration {Number} - Media's entire duration in seconds

• error {Boolean} - true if video playback has errored.

• loading {Boolean} - true if video playback is loading.

• paused {Boolean} - Playing vs paused state. true means the media is paused

• playbackRate {Number} - Current playback rate, as a number

• proportionLoaded {Number} - A value between 0 and 1 representing the proportion of the media that has loaded

• proportionPlayed {Number} - A value between 0 and 1 representing the proportion of the media that has already been shown

Events:

• onLoadStart - Called when the video starts to load

• onPlay - Sent when playback of the media starts after having been paused

• onUpdate - Sent when any of the properties were updated

Methods:

• play() - play video

• pause() - pause video

• load() - load video

The limestone/VideoPlayerlimestone/VideoPlayer.Video.source property is passed to the video component as a child node.

Default: 'video'

---

preloadSource

Node

The video source to be preloaded. Expects a <source> node.

---

source

StringNode

The video source to be played.

Any children <source> elements will be sent directly to the mediaComponent as video sources.

See: https://developerhttps://developer.mozilla.org/en-US/docs/Web/HTML/Element/source

VideoPlayerBase   Component

A player for video limestone/VideoPlayerlimestone/VideoPlayer.VideoPlayerBase.

Import Usage

import {VideoPlayerBase} from '@enact/limestone/VideoPlayer';

Properties

autoCloseTimeout

Number

The time (in milliseconds) before the control buttons will hide.

Setting this to 0 or null disables closing, requiring user input to open and close.

Default: 5000

---

backButtonAriaLabel

String

Sets the hint string read when focusing the back button.

Default: 'go to previous'

---

disabled

Boolean

Removes interactive capability from this component. This includes, but is not limited to, key-press events, most clickable buttons, and prevents the showing of the controls.

---

feedbackHideDelay

Number

Amount of time (in milliseconds) after which the feedback text/icon part of the slider's tooltip will automatically hidden after the last action. Setting this to 0 or null disables feedbackHideDelay; feedback will always be present.

Default: 3000

---

includeTimeHour

Boolean

Checks if current time and total time should include the hour.

Default: false

---

infoComponents

Node

Components placed below the title.

Typically, these will be media descriptor icons, like how many audio channels, what codec the video uses, but can also be a description for the video or anything else that seems appropriate to provide information about the video to the user.

---

initialJumpDelay

Number

The number of milliseconds that the player will pause before firing the first jump event on a right or left pulse.

Default: 400

---

jumpBy

Number

The number of seconds the player should skip forward or backward when a "jump" button is pressed.

Default: 30

---

jumpDelay

Number

The number of milliseconds that the player will throttle before firing a jump event on a right or left pulse.

Default: 200

---

loading

Boolean

Manually set the loading state of the media, in case you have information that VideoPlayer does not have.

---

locale

String

The current locale as a https://toolshttps://tools.ietf.org/html/rfc5646.

---

mediaControlsComponent

ComponentElement

Overrides the default media control component to support customized behaviors.

The provided component will receive the following props from VideoPlayer:

• initialJumpDelay - Time (in ms) to wait before starting a jump

• jumpDelay - - Time (in ms) to wait between jumps

• mediaDisabled - true when the media controls are not interactive

• no5WayJump - true when 5-way jumping is disabled

• onClose - Called when cancel key is pressed when the media controls are visible

• onFastForward - Called when the media is fast forwarded via a key event

• onJump - Called when the media jumps either forward or backward

• onJumpBackwardButtonClick - Called when the jump backward button is pressed

• onJumpForwardButtonClick - Called when the jump forward button is pressed

• onKeyDown - Called when a key is pressed

• onNextButtonClick - Called when the next button is pressed

• onPause - Called when the media is paused via a key event

• onPlay - Called when the media is played via a key event

• onPreviousButtonClick - Called when the previous button is pressed

• onRewind - Called when the media is rewound via a key event

• onToggleMore - Called when the more components are hidden or shown

• paused - true when the media is paused

• spotlightId - The spotlight container Id for the media controls

• spotlightDisabled - true when spotlight is disabled for the media controls

• visible - true when the media controls should be displayed

Default: limestone/MediaPlayer.MediaControls

---

miniFeedbackHideDelay

Number

Amount of time (in milliseconds), after the last user action, that the miniFeedback will automatically hide. Setting this to 0 or null disables miniFeedbackHideDelay; miniFeedback will always be present.

Default: 2000

---

muted

Boolean

Disable audio for this video.

In a TV context, this is handled by the remote control, not programmatically in the VideoPlayer API.

Default: false

---

no5WayJump

Boolean

Prevents the default behavior of using left and right keys for seeking.

---

noAutoPlay

Boolean

Prevents the default behavior of playing a video immediately after it's loaded.

Default: false

---

noAutoShowMediaControls

Boolean

Prevents the default behavior of showing media controls immediately after it's loaded.

Default: false

---

noMediaSliderFeedback

Boolean

Hides media slider feedback when fast-forward or rewind while media controls are hidden.

Default: false

---

noMiniFeedback

Boolean

Removes the mini feedback.

Default: false

---

noSlider

Boolean

Removes the media slider.

Default: false

---

noSpinner

Boolean

Removes spinner while loading.

---

onBack

Function

Called when the back button is clicked.

---

onControlsAvailable

Function

Called when the player's controls change availability, whether they are shown or hidden.

The current status is sent as the first argument in an object with a key available which will be either true or false. (e.g.: onControlsAvailable({available: true}))

---

onFastForward

Function

Called when the video has been fast forwarded.

---

onJumpBackward

Function

Called when the user clicks the JumpBackward button.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onJumpForward

Function

Called when the user clicks the JumpForward button.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onNext

Function

Called when the user clicks the next button.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onPause

Function

Called when the video has been paused.

---

onPlay

Function

Called when the video has been played.

---

onPrevious

Function

Called when the user clicks the previous button.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onRewind

Function

Called when the video has been rewound.

---

onScrub

Function

Called when the user is moving the VideoPlayer's Slider knob independently of the current playback position.

It is passed an object with a seconds key (float value) to indicate the current time index. It can be used to update the thumbnailSrc to reflect the current scrub position.

---

onSeekFailed

Function

Called when seek is attempted while seekDisabled is true.

---

onSeekOutsideSelection

Function

Called when seeking outside of the current selection range.

By default, the seek will still be performed. Calling preventDefault() on the event will prevent the seek operation.

---

onToggleMore

Function

Called when the visibility of more components is changed

Event payload includes:

• type - Type of event, 'onToggleMore'

• showMoreComponents - true when the components are visible`

• liftDistance - The distance, in pixels, the component animates `

---

onWillFastForward

Function

Called once before the video is forwarded.

---

onWillJumpBackward

Function

Called once before the video is jump backwarded.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onWillJumpForward

Function

Called once before the video is jump forwarded.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onWillNext

Function

Called once before playing the next video in the playlist.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onWillPause

Function

Called once before the video is paused.

---

onWillPlay

Function

Called once before the video is played

---

onWillPrevious

Function

Called once before playing the previous video in the playlist.

Is passed a limestone/VideoPlayerlimestone/VideoPlayer.videoStatus as the first argument.

---

onWillRewind

Function

Called once before the video is rewound.

---

pauseAtEnd

Boolean

Pauses the video when it reaches either the start or the end of the video during rewind, slow rewind, fast-forward, or slow forward.

Default: false

---

playbackRateHash

limestone/VideoPlayer.playbackRateHash

Mapping of playback rate names to playback rate values that may be set.

Default: { fastForward: ['2', '4', '8', '16'], rewind: ['-2', '-4', '-8', '-16'], slowForward: ['1/4', '1/2'], slowRewind: ['-1/2', '-1'] }

---

seekDisabled

Boolean

Disables seek function.

Note that jump by arrow keys will also be disabled when true.

---

selection

Array(Number)

A range of the video to display as selected.

The value of selection may either be:

• null or undefined for no selection,

• a single-element array with the start time of the selection

• a two-element array containing both the start and end time of the selection in seconds

When the start time is specified, the media slider will show filled starting at that time to the current time.

When the end time is specified, the slider's background will be filled between the two times.

---

source

Node

The video source.

Any children <source> tag elements of limestone/VideoPlayerlimestone/VideoPlayer will be sent directly to the videoComponent as video sources.

See: https://developerhttps://developer.mozilla.org/en-US/docs/Web/HTML/Element/source

---

spotlightDisabled

Boolean

Disables spotlight navigation into the component.

---

spotlightId

String

The spotlight container ID for the player.

Default: 'videoPlayer'

---

thumbnailComponent

StringComponentElement

The thumbnail component to be used instead of the built-in version.

The internal thumbnail style will not be applied to this component. This component follows the same rules as the built-in version.

---

thumbnailSrc

StringObject

Thumbnail image source to show on the slider knob.

This is a standard limestone/Imagelimestone/Image component so it supports all the same options for the src property. If no thumbnailComponent and no thumbnailSrc is set, no tooltip will display.

---

thumbnailUnavailable

Boolean

Enables the thumbnail transition from opaque to translucent.

---

title

StringNode

Title for the video being played.

---

titleHideDelay

Number

The time (in milliseconds) before the title disappears from the controls.

Setting this to 0 disables hiding.

Default: 5000

---

videoComponent

ComponentElement

Video component to use.

The default renders an HTMLVideoElement. Custom video components must have a similar API structure, exposing the following APIs:

Properties:

• currentTime {Number} - Playback index of the media in seconds

• duration {Number} - Media's entire duration in seconds

• error {Boolean} - true if video playback has errored.

• loading {Boolean} - true if video playback is loading.

• paused {Boolean} - Playing vs paused state. true means the media is paused

• playbackRate {Number} - Current playback rate, as a number

• proportionLoaded {Number} - A value between 0 and 1 representing the proportion of the media that has loaded

• proportionPlayed {Number} - A value between 0 and 1 representing the proportion of the media that has already been shown

Events:

• onLoadStart - Called when the video starts to load

• onUpdate - Sent when any of the properties were updated

Methods:

• play() - play video

• pause() - pause video

• load() - load video

The limestone/VideoPlayerlimestone/VideoPlayer.Video.source property is passed to the video component as a child node.

Default: {@link ui/Media.Media}

---

showControls

any

Shows media controls.

---

hideControls

any

Hides media controls.

---

toggleControls

any

Toggles the media controls.

---

getMediaState

any

Returns an object with the current state of the media including currentTime, duration, paused, playbackRate, proportionLoaded, and proportionPlayed.

---

play

any

Programmatically plays the current media. If you call this function during fast forwarding or rewinding, the playback speed will be set to normal.

---

pause

any

Programmatically pauses the current media. If you call this function during fast forwarding or rewinding, the playback speed will be set to normal.

---

seek

any

Sets the media playback time index.

---

jump

any

Step a given amount of time away from the current playback position. Like limestone/VideoPlayerlimestone/VideoPlayer.VideoPlayerBase.seek but relative.

---

fastForward

any

Fast forwards the current media for seeking. This function changes the playback rate. If you call play or pause during fast forwarding, the playback speed will be set to normal.

---

rewind

any

Rewinds the current media for seeking. This function changes the playback rate. If you call play or pause during rewinding, the playback speed will be set to normal.

---

setPlaybackSpeed

any

Sets the playback speed.

See: MDN playbackRate propertyMDN playbackRate property

---

getVideoNode

any

Returns a proxy to the underlying <video> node currently used by the VideoPlayer

Type Definitions

playbackRateHash   Object

A set of playback rates when media fast forwards, rewinds, slow-forwards, or slow-rewinds.

The number used for each operation is proportional to the normal playing speed, 1. If the rate is less than 1, it will play slower than normal speed, and, if it is larger than 1, it will play faster. If it is negative, it will play backward.

The order of numbers represents the incremental order of rates that will be used for each operation. Note that rates can be expressed as decimals, strings, and fractions. (e.g.: 0.5, '0.5', '1/2').

Required Property • fastForward

any[]

An array of playback rates when media fast forwards

---

Required Property • rewind

any[]

An array of playback rates when media rewinds

---

Required Property • slowForward

any[]

An array of playback rates when media slow-forwards

---

Required Property • slowRewind

any[]

An array of playback rates when media slow-rewinds

videoStatus   Object

Every callback sent by limestone/VideoPlayerlimestone/VideoPlayer receives a status package, which includes an object with the following key/value pairs as the first argument:

Required Property • type

String

Type of event that triggered this callback

---

Required Property • currentTime

Number

Playback index of the media in seconds

---

Required Property • duration

Number

Media's entire duration in seconds

---

Required Property • paused

Boolean

Playing vs paused state. true means the media is paused

---

Required Property • playbackRate

Number

Current playback rate, as a number

---

Required Property • proportionLoaded

Number

A value between 0 and 1 representing the proportion of the media that has loaded

---

Required Property • proportionPlayed

Number

A value between 0 and 1 representing the proportion of the media that has already been shown