11 KiB
Video.js Options Reference
Note: This document is only a reference for available options. To learn about passing options to Video.js, see the setup guide.
Table of Contents
Standard <video> Element Options
Each of these options is also available as a standard <video> element attribute; so, they can be defined in all three manners outlined in the setup guide. Typically, defaults are not listed as this is left to browser vendors.
autoplay
Type:
boolean
If true/present as an attribute, begins playback when the player is ready.
Note: As of iOS 10, Apple offers
autoplaysupport in Safari. For details, refer to "New .
controls
Type:
boolean
Determines whether or not the player has controls that the user can interact with. Without controls the only way to start the video playing is with the autoplay attribute or through the Player API.
height
Type:
string|number
Sets the display height of the video player in pixels.
loop
Type:
boolean
Causes the video to start over as soon as it ends.
muted
Type:
boolean
Will silence any audio by default.
poster
Type:
string
A URL to an image that displays before the video begins playing. This is often a frame of the video or a custom title screen. As soon as the user hits "play" the image will go away.
preload
Type:
string
Suggests to the browser whether or not the video data should begin downloading as soon as the <video> element is loaded. Supported values are:
'auto'
Start loading the video immediately (if the browser supports it). Some mobile devices will not preload the video in order to protect their users' bandwidth/data usage. This is why the value is called 'auto' and not something more conclusive like 'true'.
This tends to be the most common and recommended value as it allows the browser to choose the best behavior.
'metadata'
Load only the meta data of the video, which includes information like the duration and dimensions of the video. Sometimes, the meta data will be loaded by downloading a few frames of video.
'none'
Don't preload any data. The browser will wait until the user hits "play" to begin downloading.
src
Type:
string
The source URL to a video source to embed.
width
Type:
string|number
Sets the display height of the video player in pixels.
Video.js-specific Options
Each option is undefined by default unless otherwise specified.
aspectRatio
Type:
string
Puts the player in fluid mode and the value is used when calculating the dynamic size of the player. The value should represent a ratio - two numbers separated by a colon (e.g. "16:9" or "4:3").
children
Type:
Array|Object
This option is inherited from the Component base class.
fluid
Type:
boolean
When true, the Video.js player will have a fluid size. In other words, it will scale to fit its container.
Also, if the <video> element has the "vjs-fluid", this option is automatically set to true.
inactivityTimeout
Type:
number
Video.js indicates that the user is interacting with the player by way of the "vjs-user-active" and "vjs-user-inactive" classes and the "useractive" event.
The inactivityTimeout determines how many milliseconds of inactivity is required before declaring the user inactive. A value of 0 indicates that there is no inactivityTimeout and the user will never be considered inactive.
language
Type:
string, Default: browser default or'en'
A language code matching one of the available languages in the player. This sets the initial language for a player, but it can always be changed.
Learn more about languages in Video.js.
languages
Type:
Object
Customize which languages are available in a player. The keys of this object will be language codes and the values will be objects with English keys and translated values.
Learn more about languages in Video.js
Note
: Generally, this option is not needed and it would be better to pass your custom languages to
videojs.addLanguage(), so they are available in all players!
nativeControlsForTouch
Type:
boolean
Explicitly set a default value for the associated tech option.
notSupportedMessage
Type:
string
Allows overriding the default message that is displayed when Video.js cannot play back a media source.
plugins
Type:
Object
This supports having plugins be initialized automatically with custom options when the player is initialized - rather than requiring you to initialize them manually.
videojs('my-player', {
plugins: {
foo: {bar: true},
boo: {baz: false}
}
});
The above is roughly equivalent to:
var player = videojs('my-player');
player.foo({bar: true});
player.boo({baz: false});
Although, since the plugins option is an object, the order of initialization is not guaranteed!
See the plugins guide for more information on Video.js plugins.
sources
Type:
Array
An array of objects that mirror the native <video> element's capability to have a series of child <source> elements. This should be an array of objects with the src and type properties. For example:
videojs('my-player', {
sources: [{
src: '//path/to/video.mp4',
type: 'video/mp4'
}, {
src: '//path/to/video.webm',
type: 'video/webm'
}]
});
Using <source> elements will have the same effect:
<video ...>
<source src="//path/to/video.mp4" type="video/mp4">
<source src="//path/to/video.webm" type="video/webm">
</video>
techOrder
Type:
Array, Default:['html5']
Defines the order in which Video.js techs are preferred. By default, this means that the Html5 tech is preferred. Other regisetered techs will be added after this tech in the order in which they are registered.
vtt.js
Type:
string
Allows overriding the default URL to vtt.js, which may be loaded asynchronously to polyfill support for WebVTT.
This option will be used in the "novtt" build of Video.js (i.e. video.novtt.js). Otherwise, vtt.js is bundled with Video.js.
Component Options
The Video.js player is a component. Like all components, you can define what children it includes, what order they appear in, and what options are passed to them.
This is meant to be a quick reference; so, for more detailed information on components in Video.js, check out the components guide.
children
Type:
Array|Object
If an Array - which is the default - this is used to determine which children (by component name) and in which order they are created on a player (or other component):
// The following code creates a player with ONLY bigPlayButton and
// controlBar child components.
videojs('my-player', {
children: [
'bigPlayButton',
'controlBar'
]
});
The children options can also be passed as an Object. In this case, it is used to provide options for any/all children, including disabling them with false:
// This player's ONLY child will be the controlBar. Clearly, this is not the
// ideal method for disabling a grandchild!
videojs('my-player', {
children: {
controlBar: {
fullscreenToggle: false
}
}
});
${componentName}
Type:
Object
Components can be given custom options via the lower-camel-case variant of the component name (e.g. controlBar for ControlBar). These can be nested in a representation of grandchild relationships. For example, to disable the fullscreen control:
videojs('my-player', {
controlBar: {
fullscreenToggle: false
}
});
Tech Options
${techName}
Type:
Object
Video.js playback technologies (i.e. "techs") can be given custom options as part of the options passed to the videojs function. They should be passed under the lower-case variant of the tech name (e.g. "flash" or "html5").
flash
swf
Specifies where the Video.js SWF file is located for the Flash tech:
videojs('my-player', {
flash: {
swf: '//path/to/videojs.swf'
}
});
However, changing the global defaults is generally more appropriate:
videojs.options.flash.swf = '//path/to/videojs.swf'
html5
nativeControlsForTouch
Type:
boolean
Only supported by the Html5 tech, this option can be set to true to force native controls for touch devices.
nativeAudioTracks
Type:
boolean
Can be set to false to disable native audio track support. Most commonly used with videojs-contrib-hls.
nativeTextTracks
Type:
boolean
Can be set to false to force emulation of text tracks instead of native support. The nativeCaptions option also exists, but is simply an alias to nativeTextTracks.
nativeVideoTracks
Type:
boolean
Can be set to false to disable native video track support. Most commonly used with videojs-contrib-hls.