Getting Started

An overview of how to get started using Video.js, from basic CDN usage to Browserify, along with examples.

There are a few ways to get started using Video.js (currently v5.0.0), but you should select the one that best fits your particular use case.

There are a few common things you should keep in mind regardless of which way you end up including Video.js in your project. The core codebase uses a few modern features of Javascript (ES5), so if you'd like to support IE8 you'll need to include an ES5 shim. To make things easier, we created a single file you can include for IE8 support. No matter where the core Video.js library is placed, this file needs to be located in the <head> of the document.

Video.js CDN

Our friends at Fastly are nice enough to provide hosting for all the necessary files for Video.js on their content delivery network. Using these hosted files is probably the easiest way to get started using Video.js, you simply need to include the following links in your page.

<head>
  <link href="http://vjs.zencdn.net/vjs-version/video-js.css" rel="stylesheet">

  <!-- If you'd like to support IE8 -->
  <script src="http://vjs.zencdn.net/ie8/ie8-version/videojs-ie8.min.js"></script>
</head>

<body>
  <video id="my-video" class="video-js" controls preload="auto" width="640" height="264"
  poster="MY_VIDEO_POSTER.jpg" data-setup="{}">
    <source src="MY_VIDEO.mp4" type='video/mp4'>
    <source src="MY_VIDEO.webm" type='video/webm'>
    <p class="vjs-no-js">
      To view this video please enable JavaScript, and consider upgrading to a web browser that
      <a href="http://videojs.com/html5-video-support/" target="_blank">supports HTML5 video</a>
    </p>
  </video>

  <script src="http://vjs.zencdn.net/vjs-version/video.js"></script>
</body>

Google Analytics

We include a stripped down Google Analytics pixel that tracks a random percentage (currently 1%) of players loaded from the CDN. This allows us to see (roughly) what browsers are in use in the wild, along with other useful metrics such as OS and device. If you'd like to disable analytics, you can simply include the following global before including Video.js via the free CDN:

window.HELP_IMPROVE_VIDEOJS = false;

Install via npm

For more advanced workflows, installing via npm is recommended

$ npm install --save-dev video.js

Install via Bower

Video.js is also available on Bower.io.

$ bower install video.js

If you've downloaded one of the releases or installed via a package manager, you've probably noticed that the contents are slightly different from the source code available on Github. The former includes just the compiled files necessary to use Video.js, and the other includes the source used to create those files.

Distributions

A Video.js distribution is what you'll find if you've downloaded a release or installed via a package manager.

video.js/
├── alt
│   ├── video.novtt.js
│   ├── video.novtt.min.js
│   └── video.novtt.min.js.map
├── examples/
├── font
│   ├── VideoJS.eot
│   ├── VideoJS.svg
│   ├── VideoJS.ttf
│   └── VideoJS.woff
├── ie8
│   ├── videojs-ie8.js
│   └── videojs-ie8.min.js
├── lang/
├── video-js-5.0.0.zip
├── video-js.css
├── video-js.min.css
├── video-js.swf
├── video.js
├── video.js.map
├── video.min.js
└── video.min.js.map

This package includes everything you'll need to use Video.js on a production site. By default, we bundle Video.js with Mozilla's excellent VTT.js. If you don't need VTT.js functionality for whatever reason, you can use one of the Video.js copies that don't include VTT.js. These have novtt in the name and can be found in the alt/ directory. font/ includes all the generated icon font files from the Videojs Font project. ie8/ contains the shim required to support IE8, and lang/ contains all the generated translation files.

Source Code

The source code is everything you'll find when checking out the Video.js git repository. This includes all the source files and any tooling necessary to build a production ready version of Video.js, as well as useful development tools such as sandboxed examples.

video.js/
├── CHANGELOG.md
├── CONTRIBUTING.md
├── Gruntfile.js
├── LICENSE
├── README.md
├── bower.json
├── build/
├── component.json
├── composer.json
├── contrib.json
├── dist/
├── docs/
├── lang/
├── package.json
├── sandbox/
├── src/
│   ├── css
│   └── js
└── test/

A lot of the root source directory is JSON configs for various package managers because, Internet. Most likely the important things you're looking for will be in src/ and build/. src/ contains all of the source files for both the player JS and the base skin, while the build/ directory contains various grunt tasks as well as the primary build file, grunt.js.

Video.js uses a taskrunner called Grunt for its build pipeline. Before getting started, you'll need Node.js installed.

Install Grunt

This may require sudo.

$ npm install -g grunt-cli

Fork and clone the repository

Contributions to Video.js need to be done via your own fork of the repository. Even if you don't plan on doing so right away, we suggest creating your own fork to work from just in case you want to contribute down the road.

$ git clone https://github.com/YOUR-GITHUB-USERNAME/video.js && cd video.js

Set up an upstream remote

In order to be able to pull upstreams for Video.js in the future, you can set an upstream remote.

$ git checkout master
$ git remote add upstream https://github.com/videojs/video.js.git
$ git pull upstream master

Install dependencies

Dependencies are installed via npm, which is installed along with Node.js

$ npm install

Build away!

For production

There are a few different ways to build the source depending on what you want to do. When we make a new release, we do something like this.

$ grunt dist

This lints the code base, runs the tests, builds Video.js, and puts everything you need for production use in the distdirectory.

For development

In order to use ES6 features, we need to transpile the source code using Babel. This means that during development we have to watch the source for changes so we can rebuild when testing.

$ grunt dev

This will keep updated code in the build directory, allowing to use the Sandbox demo files. To make things easier, this also runs a local http server so you can access the sandbox via localhost:9999/sandbox.

Customize

Using Video.js straight out of the box is fine, but we think it's better if you make it your own. Plugins and skins make it possible to completely customize your player.

Skinning

The player skin is completely built from HTML and CSS, including when Flash and other players like YouTube are used.

Skin changes can be as simple as centering the play button (you can just add the 'vjs-big-play-centered' class to your video tag), or as complex as creating entirely new layouts. We've built a codepen project where you can explore different changes.

Video.js Skin Designer

And if you know CSS, you can always just open your Chrome dev tools and hack away!

Plugins

Video.js by itself is purposefully very simple. It supports the basic video and audio playback features and ensures they work the same across different playback technologies ("techs"). Any more advanced features are built as plugins, including playlists, analytics, advertising, and support for advanced formats like HLS and DASH. Check out the plugins page to see what's available.

Video.js Plugins