EXTENDS: vjs.Component
DEFINED IN: src/js/player.js#L21
An instance of the vjs.Player
class is created when any of the Video.js setup methods are used to initialize a video.
var myPlayer = videojs('example_video_1');
In the following example, the data-setup
attribute tells the Video.js library to create a player instance when the library is ready.
<video id="example_video_1" data-setup='{}' controls>
<source src="my-source.mp4" type="video/mp4">
</video>
After an instance has been created it can be accessed globally using Video('example_video_1')
.
-
- addTextTrack
- autoplay
- buffered
- bufferedEnd
- bufferedPercent
- cancelFullScreen
deprecated
- controls
- currentSrc
- currentTime
- currentType
- dispose
- duration
- ended
- error
- exitFullscreen
- init
- isFullScreen
deprecated
- isFullscreen
- language
- load
- loop
- muted
- networkState
- pause
- paused
- play
- playbackRate
- poster
- preload
- readyState
- remainingTime
- requestFullScreen
deprecated
- requestFullscreen
- seekable
- seeking
- src
- textTracks
- volume
- addChild
inherited
- addClass
inherited
- buildCSSClass
inherited
- children
inherited
- clearInterval
inherited
- clearTimeout
inherited
- contentEl
inherited
- createEl
inherited
- dimensions
inherited
- el
inherited
- enableTouchActivity
inherited
- getChild
inherited
- getChildById
inherited
- hasClass
inherited
- height
inherited
- hide
inherited
- id
inherited
- initChildren
inherited
- name
inherited
- off
inherited
- on
inherited
- one
inherited
- options
inherited
- player
inherited
- ready
inherited
- removeChild
inherited
- removeClass
inherited
- setInterval
inherited
- setTimeout
inherited
- show
inherited
- trigger
inherited
- triggerReady
inherited
- width
inherited
Adds a child component inside this component
myComponent.el(); // -> <div class='my-component'></div> myComonent.children(); // [empty array] var myButton = myComponent.addChild('MyButton'); // -> <div class='my-component'><div class="my-button">myButton<div></div> // -> myButton === myComonent.children()[0];
Pass in options for child constructors and options for children of the child
var myButton = myComponent.addChild('MyButton', { text: 'Press Me', children: { buttonChildExample: { buttonChildOption: true } } });
- child
String|vjs.Component
The class name or instance of a child to add - options
Object
(OPTIONAL) Options, including options to be passed to children of the child.
vjs.Component
The child component (created by this process if a string was used)
inherited from: src/js/component.js#L362
Add a CSS class name to the component's element
- classToAdd
String
Classname to add
vjs.Component
inherited from: src/js/component.js#L826
Add a text track In addition to the W3C settings we allow adding additional info through options. http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#dom-media-addtexttrack
- kind
String
Captions, subtitles, chapters, descriptions, or metadata - label
String
(OPTIONAL) Optional label - language
String
(OPTIONAL) Optional language
defined in: src/js/player.js#L1729
Get or set the autoplay attribute.
- value
String
The autoplay attribute value when gettingvjs.Player
Returns the player when setting
defined in: src/js/player.js#L1263
Get a TimeRange object with the times of the video that have been downloaded
If you just want the percent of the video that's been downloaded, use bufferedPercent.
// Number of different ranges of time have been buffered. Usually 1. numberOfRanges = bufferedTimeRange.length, // Time in seconds when the first range starts. Usually 0. firstRangeStart = bufferedTimeRange.start(0), // Time in seconds when the first range ends firstRangeEnd = bufferedTimeRange.end(0), // Length in seconds of the first time range firstRangeLength = firstRangeEnd - firstRangeStart;
Object
A mock TimeRange object (following HTML spec)
defined in: src/js/player.js#L770
Get the ending time of the last buffered time range
This is used in the progress bar to encapsulate all time ranges.
Number
The end of the last buffered time range
defined in: src/js/player.js#L821
Get the percent (as a decimal) of the video that's been downloaded
var howMuchIsDownloaded = myPlayer.bufferedPercent();
0 means none, 1 means all. (This method isn't in the HTML5 spec, but it's very convenient)
Number
A decimal between 0 and 1 representing the percent
defined in: src/js/player.js#L790
Allows sub components to stack CSS class names
String
The constructed class name
inherited from: src/js/component.js#L536
Old naming for exitFullscreen Deprecated true
defined in: src/js/player.js#L1026
Get an array of all child components
var kids = myComponent.children();
Array
The children
inherited from: src/js/component.js#L296
Clears an interval and removes the associated dispose listener
- intervalId
Number
The id of the interval to clear
Number
Returns the interval ID
inherited from: src/js/component.js#L1223
Clears a timeout and removes the associated dispose listener
- timeoutId
Number
The id of the timeout to clear
Number
Returns the timeout ID
inherited from: src/js/component.js#L1185
Return the component's DOM element for embedding content. Will either be el_ or a new element defined in createEl.
Element
inherited from: src/js/component.js#L239
Get or set whether or not the controls are showing.
- controls
Boolean
Set controls to showing or not
Boolean
Controls are showing
defined in: src/js/player.js#L1343
Create the component's DOM element
- tagName
String
(OPTIONAL) Element's node type. e.g. 'div' - attributes
Object
(OPTIONAL) An object of element attributes that should be set on the element
Element
inherited from: src/js/component.js#L200
Returns the fully qualified URL of the current source value e.g. http://mysite.com/video.mp4 Can be used in conjuction with
currentType
to assist in rebuilding the current source object.
String
The current source
defined in: src/js/player.js#L1230
Get or set the current time (in seconds)
// get var whereYouAt = myPlayer.currentTime(); // set myPlayer.currentTime(120); // 2 minutes into the video
- seconds
Number|String
(OPTIONAL) The time to seek to
Number
The time in seconds, when not settingvjs.Player
self, when the current time is set
defined in: src/js/player.js#L690
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
String
The source MIME type
defined in: src/js/player.js#L1240
Set both width and height at the same time
- width
Number|String
- height
Number|String
vjs.Component
The component
inherited from: src/js/component.js#L938
Destroys the video player and does any necessary cleanup
myPlayer.dispose();
This is especially helpful if you are dynamically adding and removing videos to/from the DOM.
defined in: src/js/player.js#L164
Get the length in time of the video in seconds
var lengthOfVideo = myPlayer.duration();
NOTE: The video must have started loading before the duration can be known, and in the case of Flash, may not be known until the video starts playing.
- seconds
Number
The duration of the video in seconds
defined in: src/js/player.js#L718
Get the component's DOM element
var domEl = myComponent.el();
Element
inherited from: src/js/component.js#L220
Report user touch activity when touch events occur
User activity is used to determine when controls should show/hide. It's relatively 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. We can't rely on touch events at the player level, because a tap (touchstart + touchend) on the video itself on mobile devices is meant to turn controls off (and on). User activity is 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)
Also a touchmove, touch+hold, and anything other than a tap is not supposed to turn the controls back on on a mobile device.
Here we're setting the default component behavior to report user activity whenever touch events happen, and this can be turned off by components that want touch events to act differently.
inherited from: src/js/component.js#L1124
Returns whether or not the player is in the "ended" state.
Boolean
True if the player is in the ended state, false if not.
defined in: src/js/player.js#L1464
Set or get the current MediaError
- err
*
A MediaError or a String/Number to be turned into a MediaError
vjs.MediaError|null
when gettingvjs.Player
when setting
defined in: src/js/player.js#L1428
Return the video to its normal size after having been in full screen mode
myPlayer.exitFullscreen();
vjs.Player
self
defined in: src/js/player.js#L1005
Returns a child component with the provided name
- name
vjs.Component
inherited from: src/js/component.js#L330
Returns a child component with the provided ID
- id
vjs.Component
inherited from: src/js/component.js#L313
Check if a component's element has a CSS class name
- classToCheck
String
Classname to check
vjs.Component
inherited from: src/js/component.js#L816
Get or set the height of the component (CSS values)
Setting the video tag dimension values only works with values in pixels. Percent values will not work. Some percents can be used, but width()/height() will return the number + %, not the actual computed width/height.
- num
Number|String
(OPTIONAL) New component height - skipListeners
Boolean
(OPTIONAL) Skip the resize event trigger
vjs.Component
This component, when setting the heightNumber|String
The height, when getting
inherited from: src/js/component.js#L927
Hide the component element if currently showing
vjs.Component
inherited from: src/js/component.js#L857
Get the component's ID
var id = myComponent.id();
String
inherited from: src/js/component.js#L258
player's constructor function
- tag
Element
The original video tag used for configuring options - options
Object
(OPTIONAL) Player options - ready
Function
(OPTIONAL) Ready callback function
defined in: src/js/player.js#L32
Add and initialize default child components from options
// when an instance of MyComponent is created, all children in options // will be added to the instance by their name strings and options MyComponent.prototype.options_.children = { myChildComponent: { myChildOption: true } } // Or when creating the component var myComp = new MyComponent(player, { children: { myChildComponent: { myChildOption: true } } });
The children option can also be an Array of child names or child options objects (that also include a 'name' key).
var myComp = new MyComponent(player, { children: [ 'button', { name: 'button', someOtherOption: true } ] });
inherited from: src/js/component.js#L481
Old naming for isFullscreen() Deprecated true
- isFS
defined in: src/js/player.js#L928
Check if the player is in fullscreen mode
// get var fullscreenOrNot = myPlayer.isFullscreen(); // set myPlayer.isFullscreen(true); // tell the player it's in fullscreen
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.
- isFS
Boolean
(OPTIONAL) Update the player's fullscreen state
Boolean
true if fullscreen, false if notvjs.Player
self, when setting
defined in: src/js/player.js#L916
The player's language code
- languageCode
String
The locale string
String
The locale string when gettingvjs.Player
self, when setting
defined in: src/js/player.js#L124
Begin loading the src data.
vjs.Player
Returns the player
defined in: src/js/player.js#L1220
Get or set the loop attribute on the video element.
- value
String
The loop attribute value when gettingvjs.Player
Returns the player when setting
defined in: src/js/player.js#L1277
Get the current muted state, or turn mute on or off
// get var isVolumeMuted = myPlayer.muted(); // set myPlayer.muted(true); // mute the volume
- muted
Boolean
(OPTIONAL) True to mute, false to unmute
Boolean
True if mute is on, false if not, when gettingvjs.Player
self, when setting mute
defined in: src/js/player.js#L878
Get the component's name. The name is often used to reference the component.
var name = myComponent.name();
String
inherited from: src/js/component.js#L277
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.
Number
the current network activity state
defined in: src/js/player.js#L1669
Remove an event listener from this component's element
myComponent.off('eventType', myFunc);
If myFunc is excluded, ALL listeners for the event type will be removed. If eventType is excluded, ALL listeners will be removed from the component.
Alternatively you can use
off
to remove listeners that were added to other elements or components usingmyComponent.on(otherComponent...
. In this case both the event type and listener function are REQUIRED.myComponent.off(otherElement, 'eventType', myFunc); myComponent.off(otherComponent, 'eventType', myFunc);
- first
String|vjs.Component
(OPTIONAL) The event type or other component - second
Function|String
(OPTIONAL) The listener function or event type - third
Function
(OPTIONAL) The listener for other component
vjs.Component
inherited from: src/js/component.js#L646
Add an event listener to this component's element
var myFunc = function(){ var myComponent = this; // Do something when the event is fired }; myComponent.on('eventType', myFunc);
The context of myFunc will be myComponent unless previously bound.
Alternatively, you can add a listener to another element or component.
myComponent.on(otherElement, 'eventName', myFunc); myComponent.on(otherComponent, 'eventName', myFunc);
The benefit of using this over
vjs.on(otherElement, 'eventName', myFunc)
andotherComponent.on('eventName', myFunc)
is that this way the listeners will be automatically cleaned up when either component is disposed. It will also bind myComponent as the context of myFunc.NOTE: When using this on elements in the page other than window and document (both permanent), if you remove the element from the DOM you need to call
vjs.trigger(el, 'dispose')
on it to clean up references to it and allow the browser to garbage collect it.
- first
String|vjs.Component
The event type or other component - second
Function|String
The event handler or event type - third
Function
The event handler
vjs.Component
self
inherited from: src/js/component.js#L577
Add an event listener to be triggered only once and then removed
myComponent.one('eventName', myFunc);
Alternatively you can add a listener to another element or component that will be triggered only once.
myComponent.one(otherElement, 'eventName', myFunc); myComponent.one(otherComponent, 'eventName', myFunc);
- first
String|vjs.Component
The event type or other component - second
Function|String
The listener function or event type - third
Function
(OPTIONAL) The listener function for other component
vjs.Component
inherited from: src/js/component.js#L691
Deep merge of options objects
Whenever a property is an object on both options objects the two properties will be merged using vjs.obj.deepMerge.
This is used for merging options for child components. We want it to be easy to override individual options on a child component without having to rewrite all the other default options.
Parent.prototype.options_ = { children: { 'childOne': { 'foo': 'bar', 'asdf': 'fdsa' }, 'childTwo': {}, 'childThree': {} } } newOptions = { children: { 'childOne': { 'foo': 'baz', 'abc': '123' } 'childTwo': null, 'childFour': {} } } this.options(newOptions);
RESULT
{ children: { 'childOne': { 'foo': 'baz', 'asdf': 'fdsa', 'abc': '123' }, 'childTwo': null, // Disabled. Won't be initialized. 'childThree': {}, 'childFour': {} } }
- obj
Object
Object of new option values
Object
A NEW object of this.options_ and obj merged
inherited from: src/js/component.js#L179
Pause the video playback
myPlayer.pause();
vjs.Player
self
defined in: src/js/player.js#L659
Check if the player is paused
var isPaused = myPlayer.paused(); var isPlaying = !myPlayer.paused();
Boolean
false if the media is currently playing, or true otherwise
defined in: src/js/player.js#L672
start media playback
myPlayer.play();
vjs.Player
self
defined in: src/js/player.js#L647
Gets or sets the current playback rate.
- rate
Boolean
New playback rate to set.
Number
Returns the new playback rate when settingNumber
Returns the current playback rate when getting
defined in: src/js/player.js#L1613
Return the component's player
vjs.Player
inherited from: src/js/component.js#L126
get or set the poster image source url
// getting var currentPoster = myPlayer.poster(); // setting myPlayer.poster('http://example.com/myImage.jpg');
- src
String
(OPTIONAL) Poster image source URL
String
poster URL when gettingvjs.Player
self when setting
defined in: src/js/player.js#L1308
Get or set the preload attribute.
- value
String
The preload attribute value when gettingvjs.Player
Returns the player when setting
defined in: src/js/player.js#L1249
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.
- fn
Function
Ready listener
vjs.Component
inherited from: src/js/component.js#L769
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.
Number
the current playback rendering state
defined in: src/js/player.js#L1694
Calculates how much time is left.
var timeLeft = myPlayer.remainingTime();
Not a native video element function, but useful
Number
The time remaining in seconds
defined in: src/js/player.js#L742
Remove a child component from this component's list of children, and the child component's element from this component's element
- component
vjs.Component
Component to remove
inherited from: src/js/component.js#L420
Remove a CSS class name from the component's element
- classToRemove
String
Classname to remove
vjs.Component
inherited from: src/js/component.js#L837
Old naming for requestFullscreen Deprecated true
defined in: src/js/player.js#L992
Increase the size of the video to full screen
myPlayer.requestFullscreen();
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.
vjs.Player
self
defined in: src/js/player.js#L947
Returns the TimeRanges of the media that are currently available for seeking to.
TimeRanges
the seekable intervals of the media timeline
defined in: src/js/player.js#L1477
Returns whether or not the player is in the "seeking" state.
Boolean
True if the player is in the seeking state, false if not.
defined in: src/js/player.js#L1470
Creates an interval and sets up disposal automatically.
- fn
Function
The function to run every N seconds. - interval
Number
Number of ms to delay before executing specified function.
Number
Returns the interval ID
inherited from: src/js/component.js#L1202
Creates timeout and sets up disposal automatically.
- fn
Function
The function to run after the timeout. - timeout
Number
Number of ms to delay before executing specified function.
Number
Returns the timeout ID
inherited from: src/js/component.js#L1162
Show the component element if hidden
vjs.Component
inherited from: src/js/component.js#L847
The source function updates the video source
There are three types of variables you can pass as the argument.
URL String: A URL to the the video file. Use this method if you are sure the current playback technology (HTML5/Flash) can support the source you provide. Currently only MP4 files can be used in both HTML5 and Flash.
myPlayer.src("http://www.example.com/path/to/video.mp4");
Source Object (or element): A javascript object containing information about the source file. Use this method if you want the player to determine if it can support the file using the type information.
myPlayer.src({ type: "video/mp4", src: "http://www.example.com/path/to/video.mp4" });
Array of Source Objects: To provide multiple versions of the source so that it can be played using HTML5 across browsers you can use an array of source objects. Video.js will detect which version is supported and load that file.
myPlayer.src([ { type: "video/mp4", src: "http://www.example.com/path/to/video.mp4" }, { type: "video/webm", src: "http://www.example.com/path/to/video.webm" }, { type: "video/ogg", src: "http://www.example.com/path/to/video.ogv" } ]);
- source
String|Object|Array
(OPTIONAL) The source URL, object, or array of sources
String
The current video source when gettingString
The player when setting
defined in: src/js/player.js#L1135
Get an array of associated text tracks. captions, subtitles, chapters, descriptions http://www.w3.org/html/wg/drafts/html/master/embedded-content-0.html#dom-media-texttracks
Array
Array of track objects
defined in: src/js/player.js#L1711
Trigger an event on an element
myComponent.trigger('eventName'); myComponent.trigger({'type':'eventName'});
- event
Event|Object|String
A string (the type) or an event object with a type attribute
vjs.Component
self
inherited from: src/js/component.js#L724
Trigger the ready listeners
vjs.Component
inherited from: src/js/component.js#L788
Get or set the current volume of the media
// get var howLoudIsIt = myPlayer.volume(); // set myPlayer.volume(0.5); // Set volume to half
0 is off (muted), 1.0 is all the way up, 0.5 is half way.
- percentAsDecimal
Number
The new volume as a decimal percent
Number
The current volume, when gettingvjs.Player
self, when setting
defined in: src/js/player.js#L848
Set or get the width of the component (CSS values)
Setting the video tag dimension values only works with values in pixels. Percent values will not work. Some percents can be used, but width()/height() will return the number + %, not the actual computed width/height.
- num
Number|String
(OPTIONAL) Optional width number - skipListeners
Boolean
Skip the 'resize' event trigger
vjs.Component
This component, when setting the widthNumber|String
The width, when getting
inherited from: src/js/component.js#L910
Fired when the duration of the media resource is first known or changed
defined in: src/js/player.js#L536
Fired when the end of the media resource is reached (currentTime == duration)
defined in: src/js/player.js#L522
Fired when an error occurs
defined in: src/js/player.js#L577
Fired the first time a video is played
Not part of the HLS spec, and we're not sure if this is the best implementation yet, so use sparingly. If you don't have a reason to prevent playback, use
myPlayer.one('play');
instead.
defined in: src/js/player.js#L479
Fired when the player switches in or out of fullscreen mode
defined in: src/js/player.js#L565
Fired when the player has finished downloading the source data
defined in: src/js/player.js#L421
Fired when the player has downloaded data at the current playback position
defined in: src/js/player.js#L415
Fired when the player has initial duration and dimension information
defined in: src/js/player.js#L409
Fired when the user agent begins looking for media data
defined in: src/js/player.js#L366
Fired whenever the media has been paused
defined in: src/js/player.js#L493
Fired whenever the media begins or resumes playback
defined in: src/js/player.js#L427
Fired while the user agent is downloading media data
defined in: src/js/player.js#L511
Fired when the width and/or height of the component changes
inherited from: src/js/component.js#L1020
Fired when the player has finished jumping to a new time
defined in: src/js/player.js#L466
Fired whenever the player is jumping to a new time
defined in: src/js/player.js#L458
Fired when the current playback position has changed
During playback this is fired every 15-250 milliseconds, depending on the playback technology in use.
defined in: src/js/player.js#L505
Fired when the volume changes
defined in: src/js/player.js#L559
Fired whenever the media begins waiting
defined in: src/js/player.js#L441