Able Player React ================= A React-compatible AblePlayer package, forked from the original AblePlayer: https://github.com/ableplayer/ableplayer
You can find the source here: github.com/boronia/ableplayer
Able Player ----------
Able Player is a fully accessible cross-browser HTML5 media player.
To see the player in action check out the [Able Player Examples][examples] page.
Features --------
- Supports both audio and video. - Supports either a single audio track or an entire playlist. - Includes a full set of player controls that are keyboard-accessible, properly labeled for screen reader users, and controllable by speech recognition users. - Includes customizable keyboard shortcuts that enable the player to be operated from anywhere on the web page (unless there are multiple instances of the player on a given page; then the player must have focus for keyboard shortcuts to work). - Features high contrast, scalable controls that remain visible in Windows High Contrast mode, plus an easy-to-see focus indicator so keyboard users can easily tell which control currently has focus. - Supports closed captions and subtitles in Web Video Timed Text (WebVTT) format, the standard format recommended by the HTML5 specification. - Supports chapters, also using WebVTT. Chapters are specific landing points in the video, allowing video content to have structure and be more easily navigated. - Supports text-based audio description, also using WebVTT. At designated times, the description text is read aloud by browsers, or by screen readers for browsers that don't support the Web Speech API. Users can optionally set their player to pause when audio description starts in order to avoid conflicts between the description and program audio. - Supports audio description as a separate video. When two videos are available (one with description and one without), both can be delivered together using the same player and users can toggle between the versions. - Supports adjustable playback rate. Users who need to slow down the video in order to better process and understand its content can do so; and users who need to speed up the video in order to maintain better focus can do so. - Includes an interactive transcript feature, built from the WebVTT chapter, caption and description files as the page is loaded. Users can click anywhere in the transcript to start playing the video (or audio) at that point. Keyboard users can also choose to keyboard-enable the transcript, so they can tab through its content one caption at a time and press enter to play the media at the desired point. - Features automatic text highlighting within the transcript as the media plays. This feature is enabled by default but can be turned off if users find it distracting. - Supports YouTube and Vimeo videos. - Provides users with the ability to customize the display of captions and subtitles. Users can control the font style, size, and color of caption text; plus background color and transparency; all from the Preferences dialog. They can also choose to position captions below the video instead of the default position (an semi-transparent overlay). - Supports fallback content if the media cannot be played (see section on Fallback for details). - Includes extensive customization options. Many of the features described above are controlled by user preferences. This is based on the belief that every user has different needs and there are no one-size-fits-all solutions. This is the heart of universal design.
Supported Languages -------------------
Able Player has been translated into the following languages. To add another language, see instructions below under Contributing.
Català (Catalan)
Chinese, Traditional (Taiwan)
Deutsch (German)
English
Español (Spanish)
Français (French)
עִברִית (Hebrew)
Italiano (Italian)
日本語 (Japanese)
Norsk Bokmål (Norwegian)
Nederlands, Vlaams (Dutch)
Türkçe (Turkish)
Contributing -------------
There are many ways to contribute to Able Player, and we welcome and appreciate your help! Here are some options:
- If you spot bugs are have feature requests, please submit them to the [Issues][issues] queue. - If you have code to contribute, please note that all development occurs on the [develop branch][develop]. This is often many commits ahead of the master branch, so please do all development from develop, and submit pull requests there. We particularly appreciate help with any issues in the Issues queue that have been flagged with "help wanted". - If you are multilingual, please consider translating Able Player into another language! All labels, prompts, messages, and help text for each language are contained within a single file, contained within the /translations directory.
Compatibility -------------
Able Player has been tested with the following browsers.
- Firefox 3.x and higher - Internet Explorer 10 and higher - Microsoft Edge all versions - Google Chrome 7.0 and higher - Opera 10.63 and higher - Safari 5.0 on Mac OS X - Safari on IOS 3.2.2 and higher - Chrome on Android 4.2 and higher
Note that mobile browsers have limitations (e.g., volume control and autostart are not supported)
Dependencies ------------
Able Player has the following third party dependencies:
- Able Player uses [jQuery][]. Version 3.2.1 or higher is recommended. The example code below uses Google’s hosted libraries; no download required. - Able Player uses [js-cookie][] to store and retrieve user preferences in cookies. This script is distributed with *Able Player*. Prior to version 2.3, Able Player used [jquery.cookie][] for this same purpose.
To install Able Player, copy the following files from the Able Player repo into a folder on your web server: - build/* - button-icons/* - images/* - styles/* (optional, see note below) - thirdparty/* (includes js-cookie, as mentioned above) - translations/* - LICENSE
The build folder includes minified production code (ableplayer.min.js and ableplayer.min.css). For debugging and/or style customization purposes, human-readable source files are also available: - build/ableplayer.js - styles/ableplayer.css
Fallback --------
All modern browsers have supported HTML5 media elements for many years. However, there are still older browsers in use that don’t have this support (e.g., Internet Explorer 9 and earlier). For these, you need to provide fallback content.
Prior to version 4.0, Able Player used [JW Player][] as a fallback Flash player for older browsers. However, this solution was built specifically on JW Player 6 which is now many versions old and difficult to find.
Also, prior to version 4.0, Able Player used [Modernizr][] to enable styling of HTML5 elements in Internet Explorer 6 through 8. This too is no longer supported, and Modernizr is no longer needed.
Instead, we recommend providing alternative content as a child of the or element. For example, this could be a link to the media file so users can download it and play it on their player of choice. Or it could be a link to a transcript.
If the browser is unable to play the media file, Able Player will show this alternative content. If no alternative content is provided, Able Player will display a standard message that lists the minimum versions of common web browsers required for playing HTML5 media.
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:
``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.
`HTML
`
Setup Step 3: Add HTML ----------------------
Add an HTML5
$3
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.
`HTML
`
$3
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.
`HTML
`
$3
The following attributes are supported on both the
#### Required Attributes
- id - required; any unique ID - data-able-player - required
#### Optional; General-Purpose
- data-debug - optional; if present will write messages to the developer console - autoplay - optional; play media automatically when page loads. For accessibility reasons, this is not recommended unless user is sure to expect media to automatically start. For example, autoplay could reasonably be used in conjunction with data-start-time in a media search application. - loop - optional; loops and plays the media file repeatedly. If used in conjunction with a playlist, loops the entire playlist rather than individual tracks. - playsinline - optional but recommended; instructs supporting browsers to play the video "inline" within the web page. This is especially applicable on iPhones, which by default load the video in their own built-in video player, thereby removing it from its surrounding context, which includes Able Player buttons and controls, an interactive transcript, and any other companion features added via Able Player. If this attribute is present, it works for all supported videos, including YouTube and Vimeo videos. - preload - optional; tells the browser how much media to download when the page loads. If the media is the central focus of the web page, use preload="auto", which instructs the browser to download as much of the media as possible. If the media is not a central focus, downloading the entire media resource can consume valuable bandwidth, so preload="metadata" would be a better option. - width - width of the media player in pixels. For video, this value should reflect the target width of the media itself. If not provided the player will be sized to fit its container. - data-root-path - define path to root directory of Able Player; generally not required but may be needed in rare instances where Able Player is unable to identify its current path on the web server - data-heading-level - optional; Able Player injects an off-screen HTML heading "Media Player" (or localized equivalent) at the top of the player so screen reader users can easily find the player. It automatically assigns a heading level that is one level deeper than the closest parent heading. This attribute can be used to manually set the heading level, rather than relying on Able Player to assign it automatically. Valid values are 1 through 6. A value of 0 is also supported, and instructs Able Player to not inject a heading at all. The latter should be used only if the web page already includes a heading immediately prior to the media player. - data-hide-controls - optional; set to "true" to hide controls during playback. Controls are visibly hidden but still accessible to assistive technologies. Controls reappear if user presses any key or moves the mouse over the video player region. - data-icon-type - optional; "svg", "font" or "image"; "svg" is the default with automatic fallback to "font" unless either (a) the browser doesn't support icon fonts or (b) the user has a custom style sheet that may impact the display of icon fonts; in either case falls back to images. Should generally leave as is unless testing the fallback. - data-skin - optional; "legacy (default) or "2020". The default skin has two rows of controls, with the seekbar positioned in available space within the top row. The "2020" skin, introduced in version 4.2, has all buttons in one row beneath a full-width seekbar. - data-speed-icons - optional; "animals" (default) or "arrows". The default setting uses a turtle icon for slower and a rabbit icon for faster. Setting this to "arrows" uses the original Able Player icons (prior to version 3.5), arrows pointing up for faster and down for slower. - data-start-time - optional; time at which you want the audio to start playing (in seconds) - data-steno-mode - optional; "true" to allow keyboard shortcuts for controlling the player remotely within textarea form fields, e.g., for transcribing media content. - data-volume - optional; set the default volume (0 to 10; default is 7 to avoid overpowering screen reader audio) - data-seek-interval - optional; interval (in seconds) of forward and rewind buttons. By default, seek interval is intelligently calculated based on duration of the media. - data-show-now-playing - optional; "true" to include "Selected track" section within player; only applies when a playlist is present
#### Language
- data-lang - optional; specify language of the player using 2-character language code (default is "en" for English) - data-force-lang - optional; include this option to force the player to use the value of data-lang as the player language. Otherwise, the player language will be set as follows, in order of precedence: 1) the language of the web page or user's web browser if either is known and if there is a matching translation file; 2) the value of data-lang if provided; 3) English.
#### Captions
- data-captions-position - optional; specify default position of captions relative to the video (either "below" or "overlay"; "below" is the default if not specified). Users can override this setting in Captions Preferences.
#### 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: - "external" - Automatically generated, written to an external div (requires data-transcript-div) - "popup" - Automatically generated, written to a draggable, resizable popup window that can be toggled on/off with a button on the controller - "manual" - A manually coded external transcript (requires data-transcript-src)
The following attributes control which of the above types, if any, are generated: - data-transcript-div - optional; id of an external div in which to display an interactive transcript. - data-transcript-src - optional; id of an external div that contains a pre-existing manually coded transcript. Able Player will parse this transcript and interact with it during playback. - data-include-transcript - optional; set to "false" to exclude transcript button from controller.
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: - data-transcript-title - optional; override default transcript title (default is "Transcript", or "Lyrics" if the data-lyrics-mode attribute is present) - data-lyrics-mode - optional; forces a line break between and within captions in the transcript
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):
- Wrap the entire transcript in a container with class="able-transcript", and wrap that in another container with class="able-transcript-area". - Add an empty <div> just inside the outer container with class="able-window-toolbar". - Wrap all audio description in a <div> element with class="able-transcript-desc". - Add a <span> element to the start of each audio description block, with class="able-hidden" and text "Description:". This helps screen reader users to distinguish between caption and description text. - Wrap each block of caption text in a <div> element with class="able-transcript-block". - Wrap each clickable segment of content in a <span> element, with class="able-transcript-seekpoint", plus data-start and data-end attributes. The values of these two data attributes are the video start and end times expressed in seconds (decimals points are allowed). - If the clickable span is caption text, also add the "able-transcript-caption" class. - Wrap unspoken content such as names of speakers or descriptions of sound in a <span> element with class="able-unspoken". - Use any other markup desired to add structure and style to your transcript. Able Player will ignore it.
#### Chapters
- data-chapters-div - optional; id of an external div in which to display a list of chapters. The list of chapters is generated automatically if a chapters track is available in a WebVTT file. If this attribute is not provided and chapter are available, chapters will be displayed in a popup menu triggered by the Chapters button. - data-use-chapters-button - optional; set to "false" to exclude chapters button from controller. If using the data-chapters-div attribute to write the chapters to an external container, you might not want users to be able to toggle the chapters off. - data-chapters-title - optional; override default chapters title (default is "Chapters"). A null value (data-chapters-title="") eliminates the title altogether. - data-chapters-default - optional; identify ID of default chapter (must correspond with the text or value immediately above the timestamp in your chapter's WebVTT file). If this attribute is present, the media will be advanced to this start time. Otherwise it will start at the beginning. (See also data-start-time). - data-seekbar-scope - optional; default is "video" (seekbar represents full duration of video); if set to "chapter" seekbar represents the duration of the current chapter only
#### Metadata
Metadata is added using the
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:
- PAUSE instructs Able Player to pause the video at that point. - FOCUS: followed by a jQuery selector, places keyboard focus on the designated element, which should have a tabindex attribute with a value of either "0" (element is part of the regular tab order) or "-1" (element is not part of the regular tab order, but can receive focus in this context via JavasScript).
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:
- data-meta-type - required for metadata; indicates the type of metadata contained within a metadata track. Supported values as described above are "text" and "selector". - data-meta-div - required for "text" metadata; id of an external div in which to display the text. - data-duration - optional attribute on the element displayed via a metadata track; value is the number of milliseconds to display the element before it fades out. Elements displayed via metadata tracks automatically fade out at the end time designated within the WebVTT file. However, if the data-duration attribute is present, this enables an element to fade out before the designated time. This is useful if multiple elements appear simultaneously, but some need to fade out earlier than others.
NOTE: If you're using metadata to expose content in sync with videos hosted on YouTube, please review [YouTube's Terms of Service] related to Overlays and Frames. As of August 11, 2016: "You must not display overlays, frames, or other visual elements in front of any part of a YouTube embedded player, including player controls. Similarly, you must not use overlays, frames or other visual elements to obscure any part of an embedded player, including player controls."
#### Search
- data-search - optional; search terms to search for within the caption tracks, separated by a space - data-search-lang - optional; specify 2-character language code of caption or subtitle track to search. If unspecified, searches the default language, which is the language of the web page if specified using the lang attribute on either the or
tag. - data-search-div - optional; id of external container in which to display search results
#### Fallback Player
- data-test-fallback - optional; force browsers to display the fallback content that will be shown to users with older browsers that don't support HTML5 media.