## setup

# Video.js Setup

## Table of Contents

- Getting Video.js
- Creating a Player
  - Automatic Setup
  - Manual Setup
- Options
  - Global Defaults
  - A Note on <video> Tag Attributes
- Player Readiness
- Advanced Player Workflows

## Getting Video.js

Video.js is officially available via CDN and npm.

Video.js works out of the box with not only HTML `<script>` and `<link>` tags, but also all major bundlers/packagers/builders, such as Browserify, Node, WebPack, etc.

Please refer to the Getting Started document for details.

## Creating a Player

> Note: Video.js works with `<video>` and `<audio>` elements, but for simplicity we'll refer only to `<video>` elements going forward.

Once you have Video.js loaded on your page, you're ready to create a player!

The core strength of Video.js is that it decorates a standard `<video>` element and emulates its associated events and APIs, while providing a customizable DOM-based UI.

Video.js supports all attributes of the `<video>` element (such as `controls`, `preload`, etc), but it also supports its own options. There are two ways to create a Video.js player and pass it options, but they both start with a standard `<video>` element with the attribute `class="video-js"`:

    <video class="video-js">
      <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
      <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
    </video>

### Automatic Setup

By default, when your web page finishes loading, Video.js will scan for media elements that have the `data-setup` attribute. The `data-setup` attribute is used to pass options to Video.js. A minimal example looks like this:

    <video class="video-js" data-setup='{}'>
      <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
      <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
    </video>

> Note: You must use single-quotes with `data-setup` as it is expected to contain JSON.

### Manual Setup

On the modern web, a `<video>` element often does not exist when the page finishes loading. In these cases, automatic setup is not possible, but manual setup is available via the `videojs` function.

One way to call this function is by providing it a string matching a `<video>` element's `id` attribute:

    <video id="my-player" class="video-js">
      <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
      <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
    </video>

    videojs('my-player');

However, using an `id` attribute isn't always practical; so, the `videojs` function accepts a DOM element instead:

    <video class="video-js">
      <source src="//vjs.zencdn.net/v/oceans.mp4" type="video/mp4">
      <source src="//vjs.zencdn.net/v/oceans.webm" type="video/webm">
    </video>

    videojs(document.querySelector('.video-js'));

## Options

> Note: This guide only covers how to pass options during player setup. For a complete reference on all available options, see the options guide.

There are three ways to pass options to Video.js. Because Video.js decorates an HTML5 `<video>` element, many of the options available are also available as standard `<video>` tag attributes:

    <video controls autoplay preload="auto" ...>

Alternatively, you can use the `data-setup` attribute to pass options as JSON. This is also how you would set options that aren't standard to the `<video>` element:

    <video data-setup='{"controls": true, "autoplay": false, "preload": "auto"}'...>

Finally, if you're not using the `data-setup` attribute to trigger the player setup, you can pass in an object of player options as the second argument to the `videojs` function:

    videojs('my-player', {
      controls: true,
      autoplay: false,
      preload: 'auto'
    });

### Global Defaults

Default options for all players can be found at `videojs.options` and can be changed directly. For example, to set `{autoplay: true}` for all future players:

    videojs.options.autoplay = true;

### A Note on `<video>` Tag Attributes

Many attributes are so-called boolean attributes. This means they are either on or off. In these cases, the attribute should have no value (or should have its name as its value) - its presence implies a true value and its absence implies a false value.

These are incorrect:

    <video controls="true" ...>
    <video loop="true" ...>
    <video controls="false" ...>

> Note: The example with `controls="false"` can be a point of confusion for new developers - it will actually turn controls on!

These are correct:

    <video controls ...>
    <video loop="loop" ...>
    <video ...>

## Player Readiness

Because Video.js techs have the potential to be loaded asynchronously, it isn't always safe to interact with a player immediately upon setup. For this reason, Video.js players have a concept of "readiness" which will be familiar to anyone who has used jQuery before.

Essentially, any number of ready callbacks can be defined for a Video.js player. There are three ways to pass these callbacks. In each example, we'll add an identical class to the player:

Pass a callback to the `videojs()` function as a third argument:

    // Passing `null` for the options argument.
    videojs('my-player', null, function() {
      this.addClass('my-example');
    });

Pass a callback to a player's `ready()` method:

    var player = videojs('my-player');

    player.ready(function() {
      this.addClass('my-example');
    });

Listen for the player's `"ready"` event:

    var player = videojs('my-player');

    player.on('ready', function() {
      this.addClass('my-example');
    });

In each case, the callback is called asynchronously - even if the player is already ready!

## Advanced Player Workflows

For a discussion of more advanced player workflows, see the player workflows guide.