View on GitHub

Able Player

Fully accessible cross-browser HTML5 media player.

Download this project as a .zip file Download this project as a tar.gz file

Able Player

Able Player is a fully accessible cross-browser media player. It uses the HTML5 <audio> or <video> element for browsers that support them, and (optionally) the JW Player as a fallback for those that don’t.

To see the player in action check our Able Player Examples page.

Features

Contributing

There are many ways to contribute to Able Player, and we welcome and appreciate your help! Here are some options:

Compatibility

Able Player has been tested with the following browsers and assistive technologies.

Note that mobile browsers have limitations (e.g., volume control and autostart are not supported)

Dependencies

Able Player has a few dependencies, but most are either provided with Able Player or available through Google’s hosted libraries. The one exception is the fallback player—see the Fallback section below for details.

Fallback

For older browsers that don’t support HTML5 media elements, you need a fallback solution. Able Player was developed to work seamlessly with JW Player, specifically JW Player 6 (successfully tested with versions 6.0 and 6.11). JW Player is free for non-commercial use but is licensed separately and is not distributed with Able Player. After licensing and downloading JW PLayer, copy jwplayer.js, jwplayer.html5.js, and jwplayer.flash.swf into the Able Player /thirdparty directory.

If you choose to use JW Player as your fallback player, users with some older browsers will have a similar experience with Able Player as users with newer browsers.

Note that most browsers in use today support HTML5 media elements. Here’s a breakdown:

Note the following limitations in Internet Explorer (IE):

At some point we may decide that it’s reasonable to stop supporting a fallback player. However, according to WebAIM’s 2014 Screen Reader User Survey 19.8% of screen reader users are still using Internet Explorer 8, 7, or 6. Until these users catch up, we think we have to provide a working fallback.

As an alternative fallback, you could link to the media file so users can download it and play it on their player of choice, and/or provide a transcript.

Setup Step 1: Use HTML5 Doctype

Able Player is built on the HTML5 media elements, so at the top of your web page be sure you have the HTML5 doctype:

<!DOCTYPE html>

Setup Step 2: Add JavaScript and CSS

Copy and paste the following code into your web page. This code applies to all use cases, both audio and video.

<!-- Dependencies -->
<script src="thirdparty/modernizr.custom.js"></script>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js"></script>
<script src="thirdparty/js.cookie.js"></script>

<!-- CSS --> 
<link rel="stylesheet" href="build/ableplayer.min.css" type="text/css"/>

<!-- JavaScript -->
<script src="build/ableplayer.min.js"></script>

Setup Step 3: Add HTML

Add an HTML5 <audio> or <video> element to your web page, as follows.

Audio

Copy and paste the following code into your web page, replacing the source files with the path to your own media files. Use both OGG and MP3 to ensure cross-browser compatibility, since some browsers don’t support MP3.

<audio id="audio1" data-able-player preload="auto">
  <source type="audio/ogg" src="path_to_audio_file.ogg"/>
  <source type="audio/mpeg" src="path_to_audio_file.mp3"/>
</audio>

Video

Copy and paste the following code into your web page, replacing the source files with the path to your own media files. Use both WebM and MP4 to ensure cross-browser compatibility, since some browsers don’t support MP4.

<video id="video1" data-able-player preload="auto" width="480" height="360" poster="path_to_image.jpg">
  <source type="video/webm" src="path_to_video.webm" data-desc-src="path_to_described_video.webm"/>
  <source type="video/mp4" src="path_to_video.mp4" data-desc-src="path_to_described_video.mp4"/>
  <track kind="captions" src="path_to_captions.vtt"/>
  <track kind="descriptions" src="path_to_descriptions.vtt"/>
</video>

Supported Attributes

The following attributes are supported on both the <audio> and <video> elements:

Required Attributes

Optional; General-Purpose

Language

Captions

Transcript

Able Player can automatically generate an accessible interactive transcript from the chapters, captions, and descriptions tracks. There are three types of interactive transcripts supported:

The following attributes control which of the above types, if any, are generated:

If none of the above attributes are present, the transcript will be displayed in a draggable, resizable popup that can be toggled on/off using a button on the controller. Note that a toggle button is added to the controller only if the transcript is a "popup" type; there is no toggle button for either the "external" or "manual" transcript types.

Additional transcript-related attributes include:

To manually code the transcript, one simple strategy is to first allow Able Player to automatically generate a transcript. Then copy and paste its content as a starting point. To manually code a transcript from scratch, use the following markup (see Video Demo #7 for an example):

Chapters

Metadata

Metadata is added using the <track> element with kind="metadata". It must be in Web Video Text Tracks format (WebVTT). Able Player supports two types of metadata:

  1. "text" - The WebVTT file contains text, intended to be written to an external container at the designated times. You must provide the external container; Able Player does not generate that automatically.

  2. "selector" - The WebVTT file contains jQuery selectors which target hidden content that is already present on the web page. At the designated times, the hidden content referenced by the jQuery selectors is made visible. In addition to selectors, the WebVTT file can contain either of the following keywords, each on a line by itself:

This combination of exposing new content, pausing the video, and placing keyboard focus on a newly exposed element, can be used to provide supplemental content including clickable "hot spots" overlaid on the video.

The following attributes make all this possible:

Search

Fallback Player

The following attributes are supported on the <video> element only:

The following additional features are supported by Able Player:

Multiple source files

As with audio, we recommend including two versions of each video, one in H.264 (MP4) and another in WebM or OGG for browsers that don’t support MP4. Browsers will play the first media source that they support.

Closed Captions

Captions are added using the <track> element with kind="captions". Captions must be in Web Video Text Tracks format (WebVTT). WebVTT tags within captions are currently ignored.

NOTE: Able Player only supports valid WebVTT files. Be sure to validate your WebVTT using a WebVTT Validator.

If captions are provided, a CC button will be added to the Able Player controller.

Audio Description

Supplemental description of key visual content for blind users can be added using one of two methods.

The first method is the same as closed captions, a <track> element, with kind="descriptions". This points to a WebVTT file, which is essentially the same as a closed caption file, but its contents are description text rather than captions. With this method, description text is written to a container that has ARIA role="alert". Supporting screen readers automatically announce the new text as soon as it is written to the page.

The second method is to produce a separate video with description mixed in. If multiple video sources are already provided (e.g., an MP4 and WebM file), then the described version must be available in both of these formats. For each video source that has a described version available, add a data-desc-src attribute to the <source> element for that video. The value of this attribute is a path pointing to the described version of the video. With this method, the described version of the video can be played instead of the non-described version, and the two versions can be swapped with clicking the "D" button on the controller.

If descriptions are available using either of the above methods, a Description toggle button appears on the controller (represented by the universal Description symbol, the letter "D"). How descriptions are ultimately delivered depends on which of the above methods is used, and on user preference. If a user prefers text-based description announced by their screen reader, that’s what they’ll get. If they prefer an alternate video with description mixed in, that’s what they’ll get. See the section below on User Preferences for additional information about preferences.

In some applications, text-based descriptions might be a required part of the interface (e.g., if video pauses so users can interact with HTML overlays; text-based description could be used in this context to provide additional instructions for screen reader users). In such cases the Descriptions button can be eliminated from the controller with data-use-descriptions-button="false".

Sign language

Sign language translation is supported in a separate video player, synchronized with the main player. Tips for filming a sign language interpreter are available from Signing Books for the Deaf:

If multiple video sources are already provided (e.g., an MP4 and WebM file), then the sign language video must be available in both of these formats. For each video source that has a sign language version available, add a data-sign-src attribute to the <source> element for that video. The value of this attribute is a path pointing to the sign language version of the video. If a sign language version is available, a sign language button will be added to the media controller. This button will toggle the display of a secondary window in which the sign language video will appear.

This is an experimental feature and a work in progress. Ultimately the intent is for the user to have full control of the size and position of the sign language video.

Setup Step 4: Review User-Defined Variables in ableplayer.js

The JavaScript file initialize.js includes a block of user-defined variables that can be modified from their default settings, such as volume, color of controller buttons, seek interval for rewind and forward buttons, and others. Explanations of each variable are provided in the comments.

If you make changes to this or any other JavaScript script files,
the player will need to be recompiled before your changes will take effect. To do so, run the shell script compile.sh.

Playlists

An Able Player playlist is an HTML list of tracks. The list can be either ordered (<ol>) or unordered (<ul>). The following attributes are supported on the list element:

Within the playlist, each list item must include data-* attributes where * is the media type and the value of the attribute is the URL pointing to the media file of that type. For example, the following audio playlist includes three songs, each of which is available in MP3 and OGG:

<ul class="able-playlist" data-player="audio1" data-embedded>
  <li data-mp3="song1.mp3" data-ogg="song1.ogg">My First Song</li>
  <li data-mp3="song2.mp3" data-ogg="song2.ogg">My Second Song</li>
  <li data-mp3="song3.mp3" data-ogg="song3.ogg">My Third Song</li>
</ul>

Supported data-* audio types:

Supported data-* video types:

When a playlist is included on a page, the <source> elements within the <audio> or <video> tags are optional. If they are provided, they should match the first item in the playlist.

Interactive Transcript

Able Player interactive transcripts are generated automatically from WebVTT caption and description files. If a transcript is available, a Transcript button will be added to the Able Player controller.

Features of the interactive transcript include the following:

YouTube Support

To play a YouTube video in Able Player, simply include a data-youtube-id attribute on the <video> element. The value of this attribute must be the video's 11-character YouTube ID.

If a described version of the video is available on YouTube, include a data-youtube-desc-id attribute on the <video> element. The value of this attribute must be the 11-character YouTube ID of the described version. If users turn on the Description button on their player controller, the described version of the video will be loaded instead of the non-described version.

Starting with 2.3.1, a YouTube Data API key is required for playing YouTube videos in Able Player.
Get a YouTube Data API key by registering your application at the Google Developer Console. For complete instructions, see Google's Getting Started page. Note: All that's needed for playing YouTube videos in Able Player is a simple API key, not OAuth 2.0.

After obtaining your YouTube Data API Key, insert the following code into your HTML page:

<script>
  var youTubeDataAPIKey = "paste your API key here";    
  var googleApiReady = false;
  function initGoogleClientApi() {    
    googleApiReady = true;
  }
</script>
<script src="http://apis.google.com/js/client.js?onload=initGoogleClientApi"></script>

If captions or subtitles are available on the YouTube video, these will be displayed for all users,
and can be controlled using Able Player's CC button. Alternatively, if you include your own <track kind="captions"> elements, these will be used instead of the captions on YouTube.

The advantage of managing captions entirely on YouTube is that you only have to manage them in one place, and they're available everywhere your YouTube video is played.

The advantages of including captions locally in <track> elements include:

Adjustable playback rate is available for some videos.

MIME Types

If your media doesn’t play, one possibility is that your web server is attempting to serve up the media with the incorrect MIME type. On Apache, this can be correct by adding the following commands to the .htaccess file:

# Audio MIME Types
AddType audio/mpeg mp3
AddType audio/mp4 mp4 
AddType audio/mp4 mpa
AddType audio/ogg ogg
AddType audio/ogg oga
AddType audio/wav wav 

# Video MIME Types
AddType video/mp4 mp4
AddType video/ogg ogv
AddType video/webm webm

If you don’t have access to your server’s .htaccess file, you should be able to view and add MIME types somewhere within your server’s control panel.

If your site is running on a Windows server, consult the documentation from Microsoft. For example:

Keyboard Shortcuts

Able Player includes several keyboard shortcuts that enable users to control the player from anywhere on the web page, as follows:

Note that modifier keys (Alt, Control, and Shift) can be assigned by clicking the Preferences button on the player. If users find that shortcut keys aren’t working as advertised, they might have better success by selecting different combinations of modifier keys to accompany the default shortcut keys.

By default, keyboard shortcuts must be accompanied by Alt + Control.

User Preferences

One of Able Player’s accessibility features is that the player is highly customizable by users. The controller includes a Preferences button that allows users to change default preferences and settings. Their changes are stored in a browser cookie and in most cases should therefore be preserved the next time they visit the site. Specifically, users can control the following:

Building the Able Player source

The source JavaScript files for Able Player are in the /scripts directory, and the source CSS files are in the /styles directory. These source files are ultimately combined into several different files (in the /build directory) using npm and Grunt:

npm install
grunt

The npm and Grunt build process is defined by the Gruntfile.js and package.json files. (Note that the version number is specified in package.json, and must be updated when a new version is released).

Files created by the build process are put into the /build directory:

Acknowledgments