videojs~videojs

The videojs() function doubles as the main function for users to create a Player instance as well as the main library namespace.

It can also be used as a getter for a pre-existing Player instance. However, we strongly recommend using videojs.getPlayer() for this purpose because it avoids any potential for unintended initialization.

Due to limitations of our JSDoc template, we cannot properly document this as both a function and a namespace, so its function signature is documented here.

Arguments

id

string|Element, required

Video element or video element ID.

options

Object, optional

Options object for providing settings. See: Options Guide.

ready

Component~ReadyCallback, optional

A function to be called when the Player and Tech are ready.

Return Value

The videojs() function returns a Player instance.

Classes

AudioTrack

EventTarget

TextTrack

VideoTrack

Members

static browser :Object

A reference to the browser utility module as an object.

See:

static dom :Object

A reference to the DOM utility module as an object.

See:

static log :function

A reference to the log utility module as an object.

See:

static options :Object

The global options object. These are the settings that take effect if no overrides are specified when the player is created.

static players :Object

Global enumeration of players.

The keys are the player IDs and the values are either the Player instance or null for disposed players.

static TOUCH_ENABLED :boolean

Use browser.TOUCH_ENABLED instead; only included for backward-compatibility with 4.x.

Deprecated:

static url :Object

A reference to the URL utility module as an object.

See:

static VERSION :string

Current Video.js version. Follows semantic versioning.

Methods

static addLanguage(code, data) → {Object

Adding languages so that they're available to all players. Example: videojs.addLanguage('es', { 'Hello': 'Hola' });

Parameters:
Name Type Description
code string

The language code or dictionary property

data Object

The data values to be translated

Returns:
Object -

The resulting language dictionary object

static bind(context, fn, uidopt) → {function}

Bind (a.k.a proxy or context). A simple method for changing the context of a function.

It also stores a unique id on the function so it can be easily removed from events.

Parameters:
Name Type Attributes Description
context Mixed

The object to bind as scope.

fn function

The function to be bound to a scope.

uid number <optional>

An optional unique ID for the function to be set

Returns:
function -

The new function that will be bound into the context given

static computedStyle(el, prop)

A safe getComputedStyle.

This is needed because in Firefox, if the player is loaded in an iframe with display:none, then getComputedStyle returns null, so, we do a null-check to make sure that the player doesn't break in these cases.

Parameters:
Name Type Description
el Element

The element you want the computed style of

prop string

The property name you want

See:

static createTimeRange(start, end)

Create a TimeRange object which mimics an HTML5 TimeRanges instance.

Parameters:
Name Type Description
start number | Array.<Array>

The start of a single range (a number) or an array of ranges (an array of arrays of two numbers each).

end number

The end of a single range. Cannot be used with the array form of the start argument.

static createTimeRanges(start, end)

Create a TimeRange object which mimics an HTML5 TimeRanges instance.

Parameters:
Name Type Description
start number | Array.<Array>

The start of a single range (a number) or an array of ranges (an array of arrays of two numbers each).

end number

The end of a single range. Cannot be used with the array form of the start argument.

static deregisterPlugin(name)

De-register a Video.js plugin.

Parameters:
Name Type Description
name string

The name of the plugin to be de-registered. Must be a string that matches an existing plugin.

Throws:

If an attempt is made to de-register the base plugin.

Type
Error

static extend(superClass, subClassMethodsopt) → {function}

Used to subclass an existing class by emulating ES subclassing using the extends keyword.

Parameters:
Name Type Attributes Default Description
superClass function

The class to inherit from

subClassMethods Object <optional>
{}

Methods of the new class

Returns:
function -

The new class with subClassMethods that inherited superClass.

Example
var MyComponent = videojs.extend(videojs.getComponent('Component'), {
  myCustomMethod: function() {
    // Do things in my method.
  }
});

static formatTime(seconds, guide) → {string}

Delegates to either the default time formatting function or a custom function supplied via setFormatTime.

Formats seconds as a time string (H:MM:SS or M:SS). Supplying a guide (in seconds) will force a number of leading zeros to cover the length of the guide.

Parameters:
Name Type Description
seconds number

Number of seconds to be turned into a string

guide number

Number (in seconds) to model the string after

Returns:
string -

Time formatted as H:MM:SS or M:SS

Example
formatTime(125, 600) === "02:05"

static getAllPlayers() → {Array}

Returns an array of all current players.

Returns:
Array -

An array of all players. The array will be in the order that Object.keys provides, which could potentially vary between JavaScript engines.

static getComponent(name) → {Component}

Get a Component based on the name it was registered with.

Parameters:
Name Type Description
name string

The Name of the component to get.

Returns:
Component -

The Component that got registered under the given name.

static getPlayer(id) → {Player|undefined}

Get a single player based on an ID or DOM element.

This is useful if you want to check if an element or ID has an associated Video.js player, but not create one if it doesn't.

Parameters:
Name Type Description
id string | Element

An HTML element - <video>, <audio>, or <video-js> - or a string matching the id of such an element.

Returns:
Player | undefined -

A player instance or undefined if there is no player instance matching the argument.

static getPlayers() → {Object}

Get an object with the currently created players, keyed by player ID

Returns:
Object -

The created players

static getPlugin(name) → {function|undefined}

Gets a plugin by name if it exists.

Parameters:
Name Type Description
name string

The name of a plugin.

Returns:
function | undefined -

The plugin (or undefined).

static getPlugins(namesopt) → {Object|undefined}

Gets an object containing multiple Video.js plugins.

Parameters:
Name Type Attributes Description
names Array <optional>

If provided, should be an array of plugin names. Defaults to all plugin names.

Returns:
Object | undefined -

An object containing plugin(s) associated with their name(s) or undefined if no matching plugins exist).

static getPluginVersion(name) → {string}

Gets a plugin's version, if available

Parameters:
Name Type Description
name string

The name of a plugin.

Returns:
string -

The plugin's version or an empty string.

static getTech(name) → {Tech|undefined}

Get a Tech from the shared list by name.

Parameters:
Name Type Description
name string

camelCase or TitleCase name of the Tech to get

Returns:
Tech | undefined -

The Tech or undefined if there was no tech with the name requested.

static isCrossOrigin(url, winLocopt) → {boolean}

Returns whether the url passed is a cross domain request or not.

Parameters:
Name Type Attributes Description
url string

The url to check.

winLoc Object <optional>

the domain to check the url against, defaults to window.location

Properties
Name Type Attributes Description
protocol string <optional>

The window location protocol defaults to window.location.protocol

host string <optional>

The window location host defaults to window.location.host

Returns:
boolean -

Whether it is a cross domain request or not.

static mergeOptions(…sources) → {Object}

Merge two objects recursively.

Performs a deep merge like lodash.merge, but only merges plain objects (not arrays, elements, or anything else).

Non-plain object values will be copied directly from the right-most argument.

Parameters:
Name Type Attributes Description
sources Array.<Object> <repeatable>

One or more objects to merge into a new object.

Returns:
Object -

A new object that is the merged result of all sources.

static off(elem, typeopt, fnopt)

Removes event listeners from an element

Parameters:
Name Type Attributes Description
elem Element | Object

Object to remove listeners from.

type string | Array.<string> <optional>

Type of listener to remove. Don't include to remove all events from element.

fn EventTarget~EventListener <optional>

Specific listener to remove. Don't include to remove listeners for an event type.

static on(elem, type, fn)

Add an event listener to element It stores the handler function in a separate cache object and adds a generic handler to the element's event, along with a unique id (guid) to the element.

Parameters:
Name Type Description
elem Element | Object

Element or object to bind listeners to

type string | Array.<string>

Type of event to bind to.

fn EventTarget~EventListener

Event listener.

static one(elem, type, fn)

Trigger a listener only once for an event.

Parameters:
Name Type Description
elem Element | Object

Element or object to bind to.

type string | Array.<string>

Name/type of event

fn Event~EventListener

Event listener function

static parseUrl(url) → {url:URLObject}

Resolve and parse the elements of a URL.

Parameters:
Name Type Description
url String

The url to parse

Returns:
url:URLObject -

An object of url details

static plugin(name, plugin)

Deprecated method to register a plugin with Video.js

Parameters:
Name Type Description
name string

The plugin name

plugin Plugin | function

The plugin sub-class or function

Deprecated:
  • videojs.plugin() is deprecated; use videojs.registerPlugin() instead

static registerComponent(name, comp) → {Component}

Register a component so it can referred to by name. Used when adding to other components, either through addChild component.addChild('myComponent') or through default children options { children: ['myComponent'] }.

NOTE: You could also just initialize the component before adding. component.addChild(new MyComponent());

Parameters:
Name Type Description
name string

The class name of the component

comp Component

The component class

Returns:
Component -

The newly registered component

static registerPlugin(name, plugin) → {function}

Register a Video.js plugin.

Parameters:
Name Type Description
name string

The name of the plugin to be registered. Must be a string and must not match an existing plugin or a method on the Player prototype.

plugin function

A sub-class of Plugin or a function for basic plugins.

Returns:
function -

For advanced plugins, a factory function for that plugin. For basic plugins, a wrapper function that initializes the plugin.

static registerTech(name, tech)

Registers a Tech into a shared list for videojs.

Parameters:
Name Type Description
name string

Name of the Tech to register.

tech Object

The Tech class to register.

static resetFormatTime()

Resets formatTime to the default implementation.

static setFormatTime(customImplementation)

Replaces the default formatTime implementation with a custom implementation.

Parameters:
Name Type Description
customImplementation function

A function which will be used in place of the default formatTime implementation. Will receive the current time in seconds and the guide (in seconds) as arguments.

static trigger(elem, event, hashopt) → {boolean|undefined}

Trigger an event for an element

Parameters:
Name Type Attributes Description
elem Element | Object

Element to trigger an event on

event EventTarget~Event | string

A string (the type) or an event object with a type attribute

hash Object <optional>

data hash to pass along with the event

Returns:
boolean | undefined -

Returns the opposite of defaultPrevented if default was prevented. Otherwise, returns undefined

static use(type, middleware)

Define a middleware that the player should use by way of a factory function that returns a middleware object.

Parameters:
Name Type Description
type string

The MIME type to match or "*" for all MIME types.

middleware MiddlewareFactory

A middleware factory function that will be executed for matching types.

static xhr(options) → {XMLHttpRequest|XDomainRequest}

A cross-browser XMLHttpRequest wrapper.

Parameters:
Name Type Description
options Object

Settings for the request.

Returns:
XMLHttpRequest | XDomainRequest -

The request object.

See: