Find a single DOM element matching a selector. This can be within the Components
contentEl() or another custom context.
Name
Type
Default
Description
selector
string
A valid CSS selector, which will be passed to querySelector.
context
Element
|
string
this.contentEl()
optional
A DOM element within which to query. Can also be a selector string in
which case the first matching element will get used as context. If
missing this.contentEl() gets used. If this.contentEl() returns
nothing it falls back to document.
Finds all DOM element matching a selector. This can be within the Components
contentEl() or another custom context.
Name
Type
Default
Description
selector
string
A valid CSS selector, which will be passed to querySelectorAll.
context
Element
|
string
this.contentEl()
optional
A DOM element within which to query. Can also be a selector string in
which case the first matching element will get used as context. If
missing this.contentEl() gets used. If this.contentEl() returns
nothing it falls back to document.
Get or set the autoplay option. When this is a boolean it will
modify the attribute on the tech. When this is a string the attribute on
the tech will be removed and Player will handle autoplay on loadstarts.
Name
Type
Description
value
boolean
|
'play'
|
'muted'
|
'any'
optional
true: autoplay using the browser behavior
- false: do not autoplay
- 'play': call play() on every loadstart
- 'muted': call muted() then play() on every loadstart
- 'any': call play() on every loadstart. if that fails call muted() then play().
- *: values other than those listed here will be set autoplay to true
Returns:
Type
Description
boolean
|
string
|
undefined
The current value of autoplay when getting
- Nothing when setting
Calling this method with an object or true will remove any previous
custom breakpoints and start from the defaults again.
Name
Type
Description
breakpoints
Object
|
boolean
optional
If an object is given, it can be used to provide custom
breakpoints. If true is given, will set default breakpoints.
If this argument is not given, will simply return the current
breakpoints.
Name
Type
Description
tiny
number
optional
The maximum width for the "vjs-layout-tiny" class.
xsmall
number
optional
The maximum width for the "vjs-layout-x-small" class.
small
number
optional
The maximum width for the "vjs-layout-small" class.
medium
number
optional
The maximum width for the "vjs-layout-medium" class.
large
number
optional
The maximum width for the "vjs-layout-large" class.
xlarge
number
optional
The maximum width for the "vjs-layout-x-large" class.
huge
number
optional
The maximum width for the "vjs-layout-huge" class.
Returns:
Type
Description
Object
An object mapping breakpoint names to maximum width values.
buffered(){TimeRange}
Get a TimeRange object with an array of the times of the video
that have been downloaded. If you just want the percent of the
video that's been downloaded, use bufferedPercent.
If you queue an rAF callback via Component#requestAnimationFrame,
use this function instead of window.cancelAnimationFrame. If you don't,
your dispose listener will not get cleaned up until Component#dispose!
Clears an interval that gets created via window.setInterval or
Component#setInterval. If you set an interval via Component#setInterval
use this function instead of window.clearInterval. If you don't your dispose
listener will not get cleaned up until Component#dispose!
Name
Type
Description
intervalId
number
The id of the interval to clear. The return value of
Component#setInterval or window.setInterval.
Clears a timeout that gets created via window.setTimeout or
Component#setTimeout. If you set a timeout via Component#setTimeout
use this function instead of window.clearTimout. If you don't your dispose
listener will not get cleaned up until Component#dispose!
Name
Type
Description
timeoutId
number
The id of the timeout to clear. The return value of
Component#setTimeout or window.setTimeout.
Creates a simple modal dialog (an instance of the ModalDialog
component) that immediately overlays the player with arbitrary
content and removes itself when closed.
Name
Type
Description
content
string
|
function
|
Element
|
Array
|
null
Same as ModalDialog#content's param of the same name.
The most straight-forward usage is to provide a string or DOM
element.
options
Object
optional
Extra options which will be passed on to the ModalDialog.
Get the computed height of the component's element.
Uses window.getComputedStyle.
Returns:
Type
Description
number
The computed height of the component's element.
currentSource(){Tech~SourceObject}
Returns the current source object.
Returns:
Type
Description
Tech~SourceObject
The current source object
currentSources(){Array.<Tech~SourceObject>}
Returns all of the current source objects.
Returns:
Type
Description
Array.<Tech~SourceObject>
The current source objects
currentSrc(){string}
Returns the fully qualified URL of the current source value e.g. http://mysite.com/video.mp4
Can be used in conjunction with currentType to assist in rebuilding the current source object.
Returns:
Type
Description
string
The current source
currentTime(seconds){number|undefined}
Get or set the current time (in seconds)
Name
Type
Description
seconds
number
|
string
optional
The time to seek to in seconds
Returns:
Type
Description
number
|
undefined
the current time in seconds when getting
- Nothing when setting
currentType(){string}
Get the current source type e.g. video/mp4
This can allow you rebuild the current source object so that you could load the same
source and tech later
Get the computed width of the component's element.
Uses window.getComputedStyle.
Returns:
Type
Description
number
The computed width of the component's element.
debug(enabled){boolean|undefined}
Set debug mode to enable/disable logs at info level.
Name
Type
Description
enabled
boolean
Fires:
Player#event:debugon
Player#event:debugoff
Returns:
Type
Description
boolean
|
undefined
defaultMuted(defaultMuted){boolean|undefined}
Get the current defaultMuted state, or turn defaultMuted on or off. defaultMuted
indicates the state of muted on initial playback.
var myPlayer = videojs('some-player-id');
myPlayer.src("http://www.example.com/path/to/video.mp4");
// get, should be false
console.log(myPlayer.defaultMuted());
// set to true
myPlayer.defaultMuted(true);
// get should be true
console.log(myPlayer.defaultMuted());
Name
Type
Description
defaultMuted
boolean
optional
true to mute
- false to unmute
Returns:
Type
Description
boolean
|
undefined
true if defaultMuted is on and getting
- false if defaultMuted is off and getting
- Nothing when setting
defaultPlaybackRate(rate){number|undefined}
Gets or sets the current default playback rate. A default playback rate of
1.0 represents normal speed and 0.5 would indicate half-speed playback, for instance.
defaultPlaybackRate will only represent what the initial playbackRate of a video was, not
not the current playbackRate.
when the document fschange event triggers it calls this
duration(seconds){number|undefined}
Normally gets the length in time of the video in seconds;
in all but the rarest use cases an argument will NOT be passed to the method
NOTE: The video must have started loading before the duration can be
known, and depending on preload behaviour may not be known until the video starts
playing.
Emit a 'tap' events when touch event support gets detected. This gets used to
support toggling the controls through a tap on the video. They get enabled
because every sub-component would have extra overhead otherwise.
This function reports user activity whenever touch events happen. This can get
turned off by any sub-components that wants touch events to act another way.
Report user touch activity when touch events occur. User activity gets used to
determine when controls should show/hide. It is simple when it comes to mouse
events, because any mouse event should show the controls. So we capture mouse
events that bubble up to the player and report activity when that happens.
With touch events it isn't as easy as touchstart and touchend toggle player
controls. So touch events can't help us at the player level either.
User activity gets checked asynchronously. So what could happen is a tap event
on the video turns the controls off. Then the touchend event bubbles up to
the player. Which, if it reported user activity, would turn the controls right
back on. We also don't want to completely block touch events from bubbling up.
Furthermore a touchmove event and anything other than a tap, should not turn
controls back on.
Listens to Events:
Component#event:touchstart
Component#event:touchmove
Component#event:touchend
Component#event:touchcancel
ended(){boolean}
Returns whether the player is in the "ended" state.
Returns:
Type
Description
boolean
True if the player is in the ended state, false if not.
enterFullWindow()
When fullscreen isn't supported we can stretch the
video container to as wide as the browser will let us.
The value of the attribute that was asked for.
- Can be an empty string on some browsers if the attribute does not exist
or has no value
- Most browsers will return null if the attribute does not exist or has
no value.
Returns the descendant Component following the givent
descendant names. For instance ['foo', 'bar', 'baz'] would
try to get 'foo' on the current component, 'bar' on the 'foo'
component and 'baz' on the 'bar' component and return undefined
if any of those don't exist.
Retrieves the position and size information of the component's element.
Returns:
Type
Description
Object
An object with boundingClientRect and center properties.
- boundingClientRect: An object with properties x, y, width,
height, top, right, bottom, and left, representing
the bounding rectangle of the element.
- center: An object with properties x and y, representing
the center point of the element. width and height are set to 0.
getVideoPlaybackQuality(){Object|undefined}
Gets available media playback quality metrics as specified by the W3C's Media
Playback Quality API.
Called when this Player has focus and a key gets pressed down, or when
any Component of this player receives a key press that it doesn't handle.
This allows player-wide hotkeys (either as defined below, or optionally
by an external function).
Name
Type
Description
event
KeyboardEvent
The keydown event that caused this function to be called.
Many components used to have a handleKeyPress method, which was poorly
named because it listened to a keydown event. This method name now
delegates to handleKeyDown. This means anyone calling handleKeyPress
will not see their method calls stop working.
A SourceObject, an array of SourceObjects, or a string referencing
a URL to a media source. It is highly recommended that an object
or array of objects is used here, so that source selection
algorithms can take the type into account.
If not provided, this method acts as a getter.
isRetry
boolean
optional
Indicates whether this is being called internally as a result of a retry
Returns:
Type
Description
string
|
undefined
If the source argument is missing, returns the current source
URL. Otherwise, returns nothing/undefined.
Determine whether or not this component has been disposed.
Returns:
Type
Description
boolean
If the component has been disposed, will be true. Otherwise, false.
isFullscreen(isFS){boolean|undefined}
Check if the player is in fullscreen mode or tell the player that it
is or is not in fullscreen mode.
NOTE: As of the latest HTML5 spec, isFullscreen is no longer an official
property and instead document.fullscreenElement is used. But isFullscreen is
still a valuable property for internal player workings.
Name
Type
Description
isFS
boolean
optional
Set the players current fullscreen state
Returns:
Type
Description
boolean
|
undefined
true if fullscreen is on and getting
- false if fullscreen is off and getting
- Nothing when setting
isInPictureInPicture(isPiP){boolean|undefined}
Check if the player is in Picture-in-Picture mode or tell the player that it
is or is not in Picture-in-Picture mode.
Name
Type
Description
isPiP
boolean
optional
Set the players current Picture-in-Picture state
Returns:
Type
Description
boolean
|
undefined
true if Picture-in-Picture is on and getting
- false if Picture-in-Picture is off and getting
- nothing if setting
language(code){string|undefined}
Set or get the player's language code.
Changing the language will trigger
languagechange
which Components can use to update control text.
ClickableComponent will update its control text by default on
languagechange.
The current language code when getting
- Nothing when setting
languages(){Array}
Get the player's language dictionary
Merge every time, because a newly added plugin might call videojs.addLanguage() at any time
Languages specified directly in the player options have precedence
If tokens are provided, it'll try and run a simple token replacement on the provided string.
The tokens it looks for look like {1} with the index being 1-indexed into the tokens array.
If a defaultValue is provided, it'll use that over string,
if a value isn't found in provided language files.
This is useful if you want to have a descriptive key for token replacement
but have a succinct localized string and not require en.json to be included.
Currently, it is used for the progress bar timing.
{
"progress bar timing: currentTime={1} duration={2}": "{1} of {2}"
}
It is then used like so:
this.localize('progress bar timing: currentTime={1} duration{2}',
[this.player_.currentTime(), this.player_.duration()],
'{1} of {2}');
Which outputs something like: 01:23 of 24:56.
Name
Type
Description
string
string
The string to localize and the key to lookup in the language files.
tokens
Array.<string>
optional
If the current item has token replacements, provide the tokens here.
defaultValue
string
optional
Defaults to string. Can be a default value to use for token replacement
if the lookup key is needed to be separate.
Returns:
Type
Description
string
The localized string or if no localization exists the english string.
loop(value){boolean|undefined}
Get or set the loop attribute on the video element.
Name
Type
Description
value
boolean
optional
true means that we should loop the video
- false means that we should not loop the video
Returns:
Type
Description
boolean
|
undefined
The current value of loop when getting
- Nothing when setting
manualAutoplay_()
Handle autoplay string values, rather than the typical boolean
values that should be handled by the tech. Note that this is not
part of any specification. Valid values and what they do can be
found on the autoplay getter at Player#autoplay()
muted(muted){boolean|undefined}
Get the current muted state, or turn mute on or off
Name
Type
Description
muted
boolean
optional
true to mute
- false to unmute
Returns:
Type
Description
boolean
|
undefined
true if mute is on and getting
- false if mute is off and getting
- nothing if setting
Get the Components name. The name gets used to reference the Component
and is set during registration.
Returns:
Type
Description
string
The name of this Component.
networkState(){number}
Returns the current state of network activity for the element, from
the codes in the list below.
NETWORK_EMPTY (numeric value 0)
The element has not yet been initialised. All attributes are in
their initial states.
NETWORK_IDLE (numeric value 1)
The element's resource selection algorithm is active and has
selected a resource, but it is not actually using the network at
this time.
NETWORK_LOADING (numeric value 2)
The user agent is actively trying to download data.
NETWORK_NO_SOURCE (numeric value 3)
The element's resource selection algorithm is active, but it has
not yet found a resource to use.
Note: When both obj and options contain properties whose values are objects.
The two properties get merged using module:obj.merge
Name
Type
Description
obj
Object
The object that contains new options.
Returns:
Type
Description
Object
A new object of this.options_ and obj merged together.
pause()
Pause the video playback
paused(){boolean}
Check if the player is paused or has yet to play
Returns:
Type
Description
boolean
false: if the media is currently playing
- true: if media is not currently playing
play(){Promise|undefined}
Attempt to begin playback at the first opportunity.
Returns:
Type
Description
Promise
|
undefined
Returns a promise if the browser supports Promises (or one
was passed in as an option). This promise will be resolved on
the return value of play. If this is undefined it will fulfill the
promise chain otherwise the promise chain will be fulfilled when
the promise from play is fulfilled.
playbackRate(rate){number|undefined}
Gets or sets the current playback rate. A playback rate of
1.0 represents normal speed and 0.5 would indicate half-speed
playback, for instance.
The current playback rate when getting or 1.0
- Nothing when setting
playbackRates(newRates){Array.<number>}
Set or get current playback rates.
Takes an array and updates the playback rates menu with the new items.
Pass in an empty array to hide the menu.
Values other than arrays are ignored.
Name
Type
Description
newRates
Array.<number>
optional
The new rates that the playback rates menu should update to.
An empty array will hide the menu
Set or unset the playsinline attribute.
Playsinline tells the browser that non-fullscreen playback is preferred.
Name
Type
Description
value
boolean
optional
true means that we should try to play inline by default
- false means that we should use the browser's default playback mode,
which in most cases is inline. iOS Safari is a notable exception
and plays fullscreen by default.
Bind a listener to the component's ready state.
Different from event listeners in that if the ready event has already happened
it will trigger the function immediately.
Function that gets called when the Component is ready.
readyState(){number}
Returns a value that expresses the current state of the element
with respect to rendering the current playback position, from the
codes in the list below.
HAVE_NOTHING (numeric value 0)
No information regarding the media resource is available.
HAVE_METADATA (numeric value 1)
Enough of the resource has been obtained that the duration of the
resource is available.
HAVE_CURRENT_DATA (numeric value 2)
Data for the immediate current playback position is available.
HAVE_FUTURE_DATA (numeric value 3)
Data for the immediate current playback position is available, as
well as enough data for the user agent to advance the current
playback position in the direction of playback.
HAVE_ENOUGH_DATA (numeric value 4)
The user agent estimates that enough data is available for
playback to proceed uninterrupted.
Returns an rAF ID that gets used to identify the timeout. It can
also be used in Component#cancelAnimationFrame to cancel
the animation frame callback.
requestFullscreen(fullscreenOptions)
Increase the size of the video to full screen
In some browsers, full screen is not supported natively, so it enters
"full window mode", where the video fills the browser window.
In browsers and devices that support native full screen, sometimes the
browser's default controls will be shown, and not the Video.js custom skin.
This includes most mobile devices (iOS, Android) and older versions of
Safari.
A function that will be bound to this component and executed just
before the browser's next repaint.
requestPictureInPicture(){Promise}
Create a floating video window always on top of other windows so that users may
continue consuming media while they interact with other content sites, or
applications on their device.
This can use document picture-in-picture or element picture in picture
Set enableDocumentPictureInPicture to true to use docPiP on a supported browser
Else set disablePictureInPicture to false to disable elPiP on a supported browser
Reset the player. Loads the first tech in the techOrder,
removes all the text tracks in the existing tech,
and calls reset on the tech.
resetControlBarUI_()
Reset Control Bar's UI by calling sub-methods that reset
all of Control Bar's components
resetPlaybackRate_()
Reset Playback ratio
resetProgressBar_()
Reset tech's progress so progress bar is reset in the UI
resetVolumeBar_()
Reset Volume bar
responsive(value){boolean|undefined}
Get or set a flag indicating whether or not this player should adjust
its UI based on its dimensions.
Name
Type
Description
value
boolean
optional
Should be true if the player should adjust its UI based on its
dimensions; otherwise, should be false.
Returns:
Type
Description
boolean
|
undefined
Will be true if this player should adjust its UI based on its
dimensions; otherwise, will be false.
Nothing if setting
runPlayCallbacks_(val)
When a callback to play is delayed we have to run these
callbacks when play is actually called on the tech. This function
runs the callbacks that were delayed and accepts the return value
from the tech.
Name
Type
Description
val
undefined
|
Promise
The return value from the tech.
runPlayTerminatedQueue_()
These functions will be run when if play is terminated. If play
runPlayCallbacks_ is run these function will not be run. This allows us
to differentiate between a terminated play and an actual call to play.
scrubbing(isScrubbing){boolean|undefined}
Sets or returns whether or not the user is "scrubbing". Scrubbing is
when the user has clicked the progress bar handle and is
dragging it along the progress bar.
Name
Type
Description
isScrubbing
boolean
optional
whether the user is or is not scrubbing
Returns:
Type
Description
boolean
|
undefined
The value of scrubbing when getting
- Nothing when setting
seekable(){TimeRange}
Get the TimeRanges of the media that are currently available
for seeking to.
Returns whether the player is in the "seeking" state.
Returns:
Type
Description
boolean
True if the player is in the seeking state, false if not.
selectSource(sources){Object|boolean}
Select source based on tech-order or source-order
Uses source-order selection if options.sourceOrder is truthy. Otherwise,
defaults to tech-order selection
Creates a function that gets run every x milliseconds. This function is a wrapper
around window.setInterval. There are a few reasons to use this one instead though.
Creates a function that runs after an x millisecond timeout. This function is a
wrapper around window.setTimeout. There are a few reasons to use this one
instead though:
Note: You can't use window.clearTimeout on the id returned by this function. This
will cause its dispose listener not to get cleaned up! Please use
Component#clearTimeout or Component#dispose instead.
A SourceObject, an array of SourceObjects, or a string referencing
a URL to a media source. It is highly recommended that an object
or array of objects is used here, so that source selection
algorithms can take the type into account.
If not provided, this method acts as a getter.
Returns:
Type
Description
string
|
undefined
If the source argument is missing, returns the current source
URL. Otherwise, returns nothing/undefined.
supportsFullScreen(){boolean}
Check if current tech can support native fullscreen
(e.g. with built in controls like iOS)
Return a reference to the current Tech.
It will print a warning by default about the danger of using the tech directly
but any argument that is passed in will silence the warning.
The current value of userActive when getting
- Nothing when setting
usingNativeControls(bool){boolean|undefined}
Toggle native controls on/off. Native controls are the controls built into
devices (e.g. default iPhone controls) or other techs
(e.g. Vimeo Controls)
This should only be set by the current tech, because only the tech knows
if it can support native controls
Name
Type
Description
bool
boolean
optional
true to turn native controls on
- false to turn native controls off
A single source object, an array of source objects, or a string
referencing a URL to a media source. It is highly recommended
that an object or array of objects is used here, so that source
selection algorithms can take the type into account.
title
string
<optional>
Unused, except if this object is passed to the MediaSession
API.
textTracks
Array.<Object>
<optional>
An array of objects to be used to create text tracks, following
the native track element format.
For ease of removal, these will be created as "remote" text
tracks and set to automatically clean up on source changes.
These objects may have properties like `src`, `kind`, `label`,
and `language`, see Tech#createRemoteTextTrack.
EXPERIMENTAL Fired when the source is set or changed on the Tech
causing the media element to reload.
It will fire for the initial source and each subsequent source.
This event is a custom event from Video.js and is triggered by the Tech.
The event object for this event contains a src property that will contain the source
that was available when the event was triggered. This is generally only necessary if Video.js
is switching techs while the source was being changed.
It is also fired when load is called on the player (or media element)
because the specification for load
says that the resource selection algorithm needs to be aborted and restarted.
In this case, it is very likely that the src property will be set to the
empty string "" to indicate we do not know what the source will be but
that it is changing.
This event is currently still experimental and may change in minor releases.To use this, pass enableSourceset option to the player.
The source url available when the sourceset was triggered.
It will be an empty string if we cannot know what the source is
but know that the source will change.
stalled
Fires when the browser is trying to get media data, but data is not available.
Fired when the current playback position has changed *
During playback this is fired every 15-250 milliseconds, depending on the
playback technology in use.