web/video.js
1
0
Fork 0
mirror of https://github.com/videojs/video.js.git synced 2024-12-29 02:57:21 +02:00
Code Releases Activity
ec61386f47
video.js/docs/api/vjs.Player.md
Steve Heffernan 7baa40220f Release 4.7.2
2014-08-14 16:31:27 -07:00

31 KiB
Raw Blame History

vjs.Player

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').

INDEX

METHODS

addChild( child, [options] )

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
    }
  }
});
PARAMETERS:
  • 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.
RETURNS:
  • vjs.Component The child component (created by this process if a string was used)

inherited from: src/js/component.js#L356

addClass( classToAdd )

Add a CSS class name to the component's element

PARAMETERS:
  • classToAdd String Classname to add
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L672

buffered()

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;
RETURNS:
  • Object A mock TimeRange object (following HTML spec)

defined in: src/js/player.js#L743

bufferedEnd()

Get the ending time of the last buffered time range

This is used in the progress bar to encapsulate all time ranges.

RETURNS:
  • Number The end of the last buffered time range

defined in: src/js/player.js#L794

bufferedPercent()

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)

RETURNS:
  • Number A decimal between 0 and 1 representing the percent

defined in: src/js/player.js#L763

buildCSSClass()

Allows sub components to stack CSS class names

RETURNS:
  • String The constructed class name

inherited from: src/js/component.js#L515

cancelFullScreen()

Old naming for exitFullscreen Deprecated true

defined in: src/js/player.js#L999

children()

Get an array of all child components

var kids = myComponent.children();
RETURNS:
  • Array The children

inherited from: src/js/component.js#L290

contentEl()

Return the component's DOM element for embedding content. Will either be el_ or a new element defined in createEl.

RETURNS:
  • Element

inherited from: src/js/component.js#L233

controls( controls )

Get or set whether or not the controls are showing.

PARAMETERS:
  • controls Boolean Set controls to showing or not
RETURNS:
  • Boolean Controls are showing

defined in: src/js/player.js#L1274

createEl( [tagName], [attributes] )

Create the component's DOM element

PARAMETERS:
  • 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
RETURNS:
  • Element

inherited from: src/js/component.js#L194

currentTime( [seconds] )

Get or set the current time (in seconds)

// get
var whereYouAt = myPlayer.currentTime();

// set
myPlayer.currentTime(120); // 2 minutes into the video
PARAMETERS:
  • seconds Number|String (OPTIONAL) The time to seek to
RETURNS:
  • Number The time in seconds, when not setting
  • vjs.Player self, when the current time is set

defined in: src/js/player.js#L670

currentType()

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

RETURNS:
  • String The source MIME type

defined in: src/js/player.js#L1195

dimensions( width, height )

Set both width and height at the same time

PARAMETERS:
  • width Number|String
  • height Number|String
RETURNS:
  • vjs.Component The component

inherited from: src/js/component.js#L784

dispose()

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#L156

duration( seconds )

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.

PARAMETERS:
  • seconds
RETURNS:
  • Number The duration of the video in seconds

defined in: src/js/player.js#L698

el()

Get the component's DOM element

var domEl = myComponent.el();
RETURNS:
  • Element

inherited from: src/js/component.js#L214

enableTouchActivity()

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#L963

error( err )

Set or get the current MediaError

PARAMETERS:
  • err * A MediaError or a String/Number to be turned into a MediaError
RETURNS:
  • vjs.MediaError|null when getting
  • vjs.Player when setting

defined in: src/js/player.js#L1359

exitFullscreen()

Return the video to its normal size after having been in full screen mode

myPlayer.exitFullscreen();
RETURNS:
  • vjs.Player self

defined in: src/js/player.js#L978

getChild( name )

Returns a child component with the provided name

PARAMETERS:
  • name
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L324

getChildById( id )

Returns a child component with the provided ID

PARAMETERS:
  • id
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L307

height( [num], [skipListeners] )

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.

PARAMETERS:
  • num Number|String (OPTIONAL) New component height
  • skipListeners Boolean (OPTIONAL) Skip the resize event trigger
RETURNS:
  • vjs.Component This component, when setting the height
  • Number|String The height, when getting

inherited from: src/js/component.js#L773

hide()

Hide the component element if currently showing

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L703

id()

Get the component's ID

var id = myComponent.id();
RETURNS:
  • String

inherited from: src/js/component.js#L252

init( tag, [options], [ready] )

player's constructor function

PARAMETERS:
  • 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

initChildren()

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#L475

isFullScreen( isFS )

Old naming for isFullscreen() Deprecated true

PARAMETERS:
  • isFS

defined in: src/js/player.js#L901

isFullscreen( [isFS] )

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.

PARAMETERS:
  • isFS Boolean (OPTIONAL) Update the player's fullscreen state
RETURNS:
  • Boolean true if fullscreen, false if not
  • vjs.Player self, when setting

defined in: src/js/player.js#L889

language( languageCode )

The player's language code

PARAMETERS:
  • languageCode String The locale string
RETURNS:
  • String The locale string when getting
  • vjs.Player self, when setting

defined in: src/js/player.js#L116

muted( [muted] )

Get the current muted state, or turn mute on or off

// get
var isVolumeMuted = myPlayer.muted();

// set
myPlayer.muted(true); // mute the volume
PARAMETERS:
  • muted Boolean (OPTIONAL) True to mute, false to unmute
RETURNS:
  • Boolean True if mute is on, false if not, when getting
  • vjs.Player self, when setting mute

defined in: src/js/player.js#L851

name()

Get the component's name. The name is often used to reference the component.

var name = myComponent.name();
RETURNS:
  • String

inherited from: src/js/component.js#L271

off( [type], [fn] )

Remove an event listener from the component's element

myComponent.off("eventName", myFunc);
PARAMETERS:
  • type String (OPTIONAL) Event type. Without type it will remove all listeners.
  • fn Function (OPTIONAL) Event listener. Without fn it will remove all listeners for a type.
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L554

on( type, fn )

Add an event listener to this component's element

var myFunc = function(){
  var myPlayer = this;
  // Do something when the event is fired
};

myPlayer.on("eventName", myFunc);

The context will be the component.

PARAMETERS:
  • type String The event type e.g. 'click'
  • fn Function The event listener
RETURNS:
  • vjs.Component self

inherited from: src/js/component.js#L540

onWaitEnd()

A handler for events that signal that waiting has eneded which is not consistent between browsers. See #1351

defined in: src/js/player.js#L439

one( type, fn )

Add an event listener to be triggered only once and then removed

PARAMETERS:
  • type String Event type
  • fn Function Event listener
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L566

options( obj )

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': {}
  }
}
PARAMETERS:
  • obj Object Object of new option values
RETURNS:
  • Object A NEW object of this.options_ and obj merged

inherited from: src/js/component.js#L173

pause()

Pause the video playback

myPlayer.pause();
RETURNS:
  • vjs.Player self

defined in: src/js/player.js#L639

paused()

Check if the player is paused

var isPaused = myPlayer.paused();
var isPlaying = !myPlayer.paused();
RETURNS:
  • Boolean false if the media is currently playing, or true otherwise

defined in: src/js/player.js#L652

play()

start media playback

myPlayer.play();
RETURNS:
  • vjs.Player self

defined in: src/js/player.js#L627

player()

Return the component's player

RETURNS:
  • vjs.Player

inherited from: src/js/component.js#L120

poster( [src] )

get or set the poster image source url

EXAMPLE:
// getting
var currentPoster = myPlayer.poster();

// setting
myPlayer.poster('http://example.com/myImage.jpg');
PARAMETERS:
  • src String (OPTIONAL) Poster image source URL
RETURNS:
  • String poster URL when getting
  • vjs.Player self when setting

defined in: src/js/player.js#L1247

ready( fn )

Bind a listener to the component's ready state

Different from event listeners in that if the ready event has already happend it will trigger the function immediately.

PARAMETERS:
  • fn Function Ready listener
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L625

removeChild( component )

Remove a child component from this component's list of children, and the child component's element from this component's element

PARAMETERS:
  • component vjs.Component Component to remove

inherited from: src/js/component.js#L414

removeClass( classToRemove )

Remove a CSS class name from the component's element

PARAMETERS:
  • classToRemove String Classname to remove
RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L683

requestFullScreen()

Old naming for requestFullscreen Deprecated true

defined in: src/js/player.js#L965

requestFullscreen()

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.

RETURNS:
  • vjs.Player self

defined in: src/js/player.js#L920

show()

Show the component element if hidden

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L693

src( [source] )

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" }
]);
PARAMETERS:
  • source String|Object|Array (OPTIONAL) The source URL, object, or array of sources
RETURNS:
  • String The current video source when getting
  • String The player when setting

defined in: src/js/player.js#L1109

trigger( event )

Trigger an event on an element

myComponent.trigger('eventName');
myComponent.trigger({'type':'eventName'});
PARAMETERS:
  • event Event|Object|String A string (the type) or an event object with a type attribute
RETURNS:
  • vjs.Component self

inherited from: src/js/component.js#L580

triggerReady()

Trigger the ready listeners

RETURNS:
  • vjs.Component

inherited from: src/js/component.js#L644

volume( percentAsDecimal )

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.

PARAMETERS:
  • percentAsDecimal Number The new volume as a decimal percent
RETURNS:
  • Number The current volume, when getting
  • vjs.Player self, when setting

defined in: src/js/player.js#L821

width( [num], skipListeners )

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.

PARAMETERS:
  • num Number|String (OPTIONAL) Optional width number
  • skipListeners Boolean Skip the 'resize' event trigger
RETURNS:
  • vjs.Component This component, when setting the width
  • Number|String The width, when getting

inherited from: src/js/component.js#L756

EVENTS

durationchange EVENT

Fired when the duration of the media resource is first known or changed

defined in: src/js/player.js#L522

ended EVENT

Fired when the end of the media resource is reached (currentTime == duration)

defined in: src/js/player.js#L511

firstplay EVENT

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#L468

fullscreenchange EVENT

Fired when the player switches in or out of fullscreen mode

defined in: src/js/player.js#L551

loadedalldata EVENT

Fired when the player has finished downloading the source data

defined in: src/js/player.js#L416

loadeddata EVENT

Fired when the player has downloaded data at the current playback position

defined in: src/js/player.js#L410

loadedmetadata EVENT

Fired when the player has initial duration and dimension information

defined in: src/js/player.js#L404

loadstart EVENT

Fired when the user agent begins looking for media data

defined in: src/js/player.js#L360

pause EVENT

Fired whenever the media has been paused

defined in: src/js/player.js#L482

play EVENT

Fired whenever the media begins or resumes playback

defined in: src/js/player.js#L422

progress EVENT

Fired while the user agent is downloading media data

defined in: src/js/player.js#L500

resize EVENT

Fired when the width and/or height of the component changes

inherited from: src/js/component.js#L863

seeked EVENT

Fired when the player has finished jumping to a new time

defined in: src/js/player.js#L455

seeking EVENT

Fired whenever the player is jumping to a new time

defined in: src/js/player.js#L447

timeupdate EVENT

Fired when the current playback position has changed

During playback this is fired every 15-250 milliseconds, depnding on the playback technology in use.

defined in: src/js/player.js#L494

volumechange EVENT

Fired when the volume changes

defined in: src/js/player.js#L545

waiting EVENT

Fired whenever the media begins wating

defined in: src/js/player.js#L431