## options

# 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
  - autoplay
  - controls
  - height
  - loop
  - muted
  - poster
  - preload
    - 'auto'
    - 'metadata'
    - 'none'
  - src
  - width
- Video.js-specific Options
  - aspectRatio
  - children
  - fluid
  - inactivityTimeout
  - language
  - languages
  - nativeControlsForTouch
  - notSupportedMessage
  - playbackRates
  - plugins
  - sourceOrder
  - sources
  - techOrder
  - vtt.js
- Component Options
  - children
  - ${componentName}
- Tech Options
  - ${techName}
  - flash
    - swf
  - html5
    - nativeControlsForTouch
    - nativeAudioTracks
    - nativeTextTracks
    - nativeVideoTracks

## 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 `autoplay` support in Safari. For details, refer to "New Policies for iOS".

### `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.

### `playbackRates`

> Type: `Array`

An array of numbers strictly greater than 0, where 1 means regular speed (100%), 0.5 means half-speed (50%), 2 means double-speed (200%), etc. If specified, Video.js displays a control (of class `vjs-playback-rate`) allowing the user to choose playback speed from among the array of choices. The choices are presented in the specified order from bottom to top.

For example:

    videojs('my-player', {
      playbackRates: [0.5, 1, 1.5, 2]
    });

### `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.