README.md 7.02 KB
Newer Older
1
# Responsive Accessible HTML5 Video Player
2

Laura Kalbag's avatar
Laura Kalbag committed
3
## by Ind.ie, based on work by the PayPal Accessibility Team
4

5
See the Authors section below for details.
6
7

## What is it?
8

Laura Kalbag's avatar
Laura Kalbag committed
9
A lightweight responsive HTML5 video player which includes support for captions and screen reader accessibility.
10

11
12
13
14
15
16
17
18
19
## Getting started

If you’re on a Mac or Linux-based system:

  1. [Clone the Git repository.](https://source.ind.ie/project/video-player)
  2. Run ```./demo```

_(On other platforms, or if the demo script doesn’t run because Python is not installed, start a web server with the project folder as root and open it up in a browser.)_

20
## Features
21

Laura Kalbag's avatar
Laura Kalbag committed
22
- Provides a responsive HTML5 video player with custom controls.
23
24
25
26
27
28
29
30
31
32
33
- Supports captions; simply denote a VTT caption file using the standard HTML5 video syntax.
- Uses native HTML5 form controls for volume (range input) and progress indication (progress element).
- Accessible to keyboard-only users and screen reader users.
- Option provided to set captions on or off by default (upon loading).
- Option provided to set number of seconds by which to rewind and forward.
- The width adjusts to the width of the video element.
- No dependencies. Written in "vanilla" JavaScript.
- When JavaScript is unavailable, the browser's native controls are used.

## Implementation

34
### Preparing your videos
35

36
For the videos to work across as many browsers as possible, you’ll need at least the following format:
37
- .mp4
38
39

To be compatible with earlier versions of browsers, you may also want to implement:
40
41
42
- .webm
- .ogv

43
44
(But really these formats aren’t necessary nowadays. [See caniuse.com for more information](http://caniuse.com/#search=mp4).

45
46
To convert videos into these formats, I recommend the [Miro Video Converter](http://www.mirovideoconverter.com) or [Handbrake](https://handbrake.fr). After converting, check the audio and picture for the videos are working correctly. Sometimes conversions can result in a loss of picture, or strange green picture. If this happens, converting again can solve the problem.

47
#### HTTP Live Streaming
48

49
50
Apple has an [HTTP Live Streaming format](https://developer.apple.com/streaming/). For this you’ll need to add the source as a .m3u8 file with the `application/x-mpegURL` source type.

51
52
You may experience CORS issues if your HTTP Live Streaming file is hosted on Vimeo. (This is why we’ve disabled HTTP Live Streaming on the Ind.ie site for now.)

53
### Preparing your captions
54

55
56
I wrote a [blog post about how I created captions for our Spyware 2.0 video](https://ind.ie/about/blog/accessible-video-player). A couple of recommended caption timestamping tools are [Subtitle Horse](http://www.subtitle-horse.com/) and [Jubler](http://www.jubler.org/). This [caption format converter](http://www.3playmedia.com/services-features/tools/captions-format-converter/) can convert different caption file formats to the required .vtt (Web VTT) format.

57
### CSS and Image
58

59
Insert the CSS in the Head of your HTML document. You'll also need to upload the sprite images (or use your own) and adjust the path in the CSS file.
60
61
62
63
64

```html
<link rel="stylesheet" href="/css/px-video.css" />
```

65
### HTML
66
Insert the HTML5 video markup in the Body of your HTML document. Replace the video, poster, and caption URLs. Modify the sizes of video and fallback image as needed.
67
68

If you dont have captions, just don't include the `<track>` element.
69
70
71
```html
<div class="px-video-container" id="myvid">
	<div class="px-video-img-captions-container">
Laura Kalbag's avatar
Laura Kalbag committed
72
		<div class="px-video-captions hide"></div>
Laura Kalbag's avatar
Laura Kalbag committed
73
74
75
			<div class="px-video-wrapper">
				<video poster="../media/foo.jpg" class="px-video" controls>
					<!-- video files -->
76
77
78
					<!-- HTTP Live Streaming -->
					<source src="../media/foo.m3u8" type="application/x-mpegURL" />
					<!-- Standard video files -->
Laura Kalbag's avatar
Laura Kalbag committed
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
					<source src="../media/foo.mp4" type="video/mp4" />
					<source src="../media/foo.webm" type="video/webm" />
					<source src="../media/foo.ogv" type="video/ogg" />

					<!-- text track file -->
					<track kind="captions" label="English captions" src="../media/captions-foo-en.vtt" srclang="en" default />

					<!-- fallback for browsers that don't support the video element -->
					<div>
						<a href="../media/foo.mp4">
							<img src="../media/foo.jpg" width="640" height="360" alt="download video" />
						</a>
					</div>
				</video>
			</div>
		</div><!-- end container for captions and video -->
95
	<div class="px-video-controls"></div>
Laura Kalbag's avatar
Laura Kalbag committed
96
</div><!-- end video container -->
97
98
```

99
### JavaScript
Laura Kalbag's avatar
Laura Kalbag committed
100
Insert the JavaScript file right before the closing `</body>` element of your HTML document. Add a `<script>` element to initialize the video. Options are passed in JSON format. The options are:
101
102
103
104
105
106
107
108
109
110
111
112
113

- videoId: the value of the ID of the widget container (string) [required]
- captionsOnDefault: denotes whether to show or hide caption upon loading (boolean) [optional, default is true]
- seekInterval: the number of seconds to rewind and fast forward (whole number) [optional, default is 10]
- videoTitle: short title of video; used for aria-label attribute on Play button to clarify to screen reader user what will be played (text) [optional, default is "Play"]
- debug: turn console logs on or off (boolean) [optional, default is false]

```html
<script src="js/px-video.js"></script>
<script>
// Initialize
new InitPxVideo({
	"videoId": "myvid",
Laura Kalbag's avatar
Laura Kalbag committed
114
	"captionsOnDefault": false,
115
	"seekInterval": 20,
Laura Kalbag's avatar
Laura Kalbag committed
116
	"videoTitle": "Spyware 2.0",
117
118
119
120
121
	"debug": true
});
</script>
```

Laura Kalbag's avatar
Laura Kalbag committed
122
123
## Testing
Due to Cross-Origin Resource Sharing (CORS), you'll need to run a web server in order to test the video player locally.
124

Laura Kalbag's avatar
Laura Kalbag committed
125
## Original Authors
126
127
128
129
130
- Dennis Lembree, primary developer || [https://github.com/weboverhauls](https://github.com/weboverhauls) || [@dennisl](https://twitter.com/dennisl)
- Victor Tsaran, consultation and testing || [https://github.com/vick08](https://github.com/vick08) || [@vick08](https://twitter.com/vick08)
- Jason Gabriele, consultation
- Tim Resudek, design

Laura Kalbag's avatar
Laura Kalbag committed
131
132
133
## Ind.ie Authors
- Laura Kalbag, design and development

134
135
136
137
138
139
140
141
142
143
144
145
## Browser Support
- Chrome: full support.
- Safari: full support.
- Firefox: full support.
- Internet Explorer 10, 11: full support.
- Internet Explorer 9: native video player used (aesthetic choice since HTML5 range input and progress element are not supported).
- Internet Explorer 8: renders fallback content of video element (in the demo, this is an image linked to the video file).
- Smartphones and tablets: controls and captions are not customized as both are natively supported in latest versions.

## Limitations and Known Issues
- Currently, only one caption file per video is supported.
- Only VTT caption files are supported (not SRT nor TTML). VTT cue settings are not supported but inline styles function (see first few lines of example).
Laura Kalbag's avatar
Laura Kalbag committed
146
- Colour of the progress indicator is currently limited to the defaults provided by the browser.
147
- Take care to ensure the VTT file has UNIX line endings. Otherwise it can’t be processed by the player.
148
149

## Copyright and License
Laura Kalbag's avatar
Laura Kalbag committed
150
Original work copyright 2014, eBay Software Foundation under [the BSD license](LICENSE.md)
151
Additional work copyright © 2013-2015 Ind.ie. © Article 12 under [the BSD license](LICENSE.md)