source: branches/jw6/doc/captions.html @ 2315

Revision 2315, 10.7 KB checked in by jeroen, 11 months ago (diff)

updated docs to talk about download and remove HLS support
Line 
1<!doctype html>
2<html>
3<head>
4<title>Adding Video Captions</title>
5<style>
6    body { padding: 50px 100px; width: 700px; font: 13px/20px Arial; background: #FFF; }
7    a, h1, h2 { color: #369; }
8    h1 { font-size: 32px; }
9    h2 { margin-top: 50px; }
10    h3 { margin-top: 25px; }
11    img { display: block; margin: 0 10px; }
12    pre { font-size: 12px; background: #E5F3C8; padding:5px 10px; border: 1px solid #D3EAA4; }
13    dt { padding-left: 20px; font-weight: bold; }
14    dd { color: #333; font-style: italic; }
15    table { width: 100%; border-collapse: collapse; margin: 20px 0; }
16    tr { border-bottom: 1px solid #CCC; } 
17    tr:nth-child(even) { background: #EEE; }
18    td,th { padding: 5px; font-size: 12px; text-align: left; }
19
20</style>
21</head><body>
22
23<h1>Adding Video Captions</h1>
24
25<p>JW Player supports the rendering of closed captions or subtitles in the video display. Captions can be shown or hidden with a toggle or, when presenting multiple languages, a popup menu. This guide explains how to add captions to your player embeds.</p>
26
27
28
29<h2>Supported Formats</h2>
30
31<p>JW Player supports both external and embedded captions:</p>
32
33<ul>
34<li>External captions should be in <strong>WebVTT</strong> (<a href="http://dev.w3.org/html5/webvtt/">Web Video Text Tracks</a>) format, which is part of the HTML5 standard. The captions are stored and served as separate text files.</li>
35<li>Embedded captions should be in <strong>TX3G</strong> (<a href="http://en.wikipedia.org/wiki/MPEG-4_Part_17">3GPP Timed Text</a>) format, which is part of the MP4 standard. The captions are stored inside the MP4 video files, requiring no separate downloads.</li>
36</ul>
37
38<p>Note that WebVTT builds upon the SRT (<a href="http://en.wikipedia.org/wiki/SubRip">SubRip</a>) format, which is also supported by JW Player.</p>
39
40<p>Unfortunately, neither external nor embedded captions are supported on all desktop browsers and mobile devices. Here is the breakdown:</p>
41
42<table><tr>
43    <th></th><th>Desktop: HTML5</th><th>Desktop: Flash</th><th>Mobile: iOS</th><th>Mobile: Android</th>
44</tr><tr>
45    <th>WebVTT</th><td>yes</td><td>yes</td><td>-</td><td>-</td>
46</tr><tr>
47    <th>TX3G</th><td>-</td><td>yes</td><td>yes</td><td>-</td>
48</tr></table>
49
50<p>WebVTT does not work on mobile devices, since it is not possible for JW Player to <em>polyfill</em> the captions on top of the video during (full-screen) playback. Support for <a href="http://www.longtailvideo.com/html5/#accessibility">HTML5 Text Tracks</a> on iOS and Android will fix this in the (hopefully near-term) future.</p>
51
52<p>TX3G tracks do render on iOS (still not on Android), but on desktops they only display in Flash. TX3G tracks are also hard to edit, since they require tools (like <a href="http://handbrake.fr">Handbrake</a>) to <em>mux</em> your MP4 files. WebVTT files can be authored with any text editor.</p>
53
54
55
56<h3>WebVTT Example</h3>
57
58<p>If short-term iOS support is not critical, we recommend using the WebVTT format. It is easy to author, works on all desktops and will likely get supported on iOS within a few years. Here is a short example file with three cues:</p>
59
60<pre>
61WEBVTT
62
6300:00:08.000 --&gt; 00:00:10.000
64Nothing is going on.
65
6600:00:10.500 --&gt; 00:00:12.500
67Violet, please!
68- I am not your babe!
69
7000:00:17.000 --&gt; 00:00:20.000
71You stupid cow,
72look what you gone and done now, ay.
73</pre>
74
75<p>Note your files should be saved using <strong>UTF8</strong> encoding in order to correctly display special characters (accents, but also e.g. Arab, Chinese, Russian). If these files are not stored and served using UTF8 encoding, rendering issues will almost certainly occur.</p>
76
77
78
79<h2>Embedding Captions</h2>
80
81<p>TX3G captions are automatically picked up by the player and therefore don't need any embed configuration. WebVTT captions can be embedded in a player by adding a <strong>captions</strong> object inside the <strong>playlist</strong> object. Every captions entry must contain two properties:</p>
82
83<dl>
84<dt>file</dt>
85<dd>URL to the WebVTT (or SRT) file to display (e.g. <strong>/assets/myCaptions.vtt</strong>). Note these captions are subject to <a href="crossdomain.html">Crossdomain Security Restrictions</a>, in both Flash and HTML5 mode.</dd>
86<dt>label</dt>
87<dd>Human-readable name of the captions track (e.g. <strong>Closed Captions</strong>). Is displayed in the captions selection menu if more than one track is provided.</dd>
88</dl>
89
90<p>Here is a basic example setup, using one video and three SRT files:</p>
91
92<pre>
93jwplayer("myElement").setup({
94    height: 360,
95    playlist: [{
96        captions: [
97            { file: "/assets/captions-en.vtt", label: "English" },
98            { file: "/assets/captions-fr.vtt", label: "French" },
99            { file: "/assets/captions-es.vtt", label: "Spanish" }
100        ],
101        file: "/assets/sintel.mp4",
102        image: "/assets/sintel.jpg"
103    }],
104    width: 640
105});
106</pre>
107
108<p>See <a href="playlists.html">Working with Playlist</a> for more info on embedding playlists.</p>
109
110<h3>Captions in Feeds</h3>
111
112<p>When <a href="feeds.html">loading RSS Feeds</a> into a player, captions can be included using the <strong>&lt;media:subtitle&gt;</strong> element of the <a href="http://video.search.yahoo.com/mrss">Media RSS specification</a>. Here is an example feed, containing the same video and three captions tracks as above:</p>
113
114<pre>
115&lt;rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/" &gt; 
116  &lt;channel&gt; 
117    &lt;title&gt;Example RSS Playlist&lt;/title&gt; 
118    &lt;item&gt; 
119      &lt;title&gt;Sintel&lt;/title&gt;
120      &lt;description&gt;Sintel is a fantasy computer generated short movie. It's the third
121         release from the Blender Open Movie Project.&lt;/description&gt;
122      &lt;media:content url="http://example.com/assets/sintel.mp4" /&gt;
123      &lt;media:subtitle url="http://example.com/assets/sintel-en.vtt" lang="en" /&gt;
124      &lt;media:subtitle url="http://example.com/assets/sintel-fr.vtt" lang="fr" /&gt;
125      &lt;media:subtitle url="http://example.com/assets/sintel-es.vtt" lang="es" /&gt;
126      &lt;media:thumbnail url="http://example.com/assets/sintel.jpg" /&gt;
127    &lt;/item&gt;
128  &lt;/channel&gt;
129&lt;/rss&gt;
130</pre>
131
132<p>Note the <strong>lang</strong> option is used to provide an <a href="http://www.i18nguy.com/unicode/language-identifiers.html">RFC 3066 language identifier</a>. JW Player will automatically convert this into a readable label for <a href="#codes">widely used languages</a>.</p>
133
134
135
136<h2>Styling the Captions</h2>
137
138<p>It is possible to change the styling of the captions using the <strong>captions</strong> options block of player setups. The following style properties can be set:</p>
139
140<dl>
141<dt>background</dt>
142<dd>By default, no background is displayed for the captions. Instead, they are printed with a thin black outline. Set this option to a hexadecimal color (e.g. <strong>000000</strong>) to draw a colored box around the captions instead. It makes the captions more readable, but also sets them more apart from the video.</dd>
143<dt>color</dt>
144<dd>Can be any hexadecimal color value, the default is <strong>FFFFFF</strong>.</dd>
145<dt>fontsize</dt>
146<dd>By default, the captions are displayed using a font size that fits 80 characters per line. Use this option to override this selection with a specific fontsize in pixels (e.g. <strong>20</strong>). Note the captions are still scaled up during fullscreen playback.</dd>
147</dl>
148
149<p>Here is an example setup where the captions are set in 20px red with a black background:</p>
150
151<pre>
152jwplayer("myElement").setup({
153    captions: {
154        background: '000000',
155        color: 'cc0000',
156        fontSize: '20'
157    },
158    height: 360,
159    playlist: [{
160        captions: [
161            { file: "/assets/captions.vtt", label: "Closed Captions" },
162        ],
163        file: "/assets/sintel.mp4",
164        image: "/assets/sintel.jpg"
165    }],
166    width: 640
167});
168</pre>
169
170<p>Note these styling options do <strong>not</strong> work for TX3G captions on the iPad/iPhone, since these devices offer no control over rendering of the captions.</p>
171
172<h3>Inline Styling</h3>
173
174<p>At present, JW Player does not support WebVTT cue settings (<em>line</em>, <em>position</em>, <em>size</em>, etc.), nor most WebVTT cue objects (<em>class</em>, <em>ruby</em>, <em>timestamp</em>, etc.). They will not break playback, but are simply ignored. However, the following cues are supported, for both SRT and WebVTT:</p>
175
176<ul>
177<li><strong>&lt;b&gt;</strong>: to make text bold.</li>
178<li><strong>&lt;i&gt;</strong>: to make text italic.</li>
179<li><strong>&lt;u&gt;</strong>: to underline text.</li>
180<li><strong>&lt;font size="123"&gt;</strong>: to change the text fontsize.</li>
181<li><strong>&lt;font color="ffcc00"&gt;</strong>: to change the text color.</li>
182</ul>
183
184<p>Here is an example VTT file with a few cues containing inline styles:</p>
185
186
187<pre>
188WEBVTT
189
19000:00:08.000 --&gt; 00:00:10.000
191&lt;b>Nothing&lt;/b> is going on.
192
19300:00:10.500 --&gt; 00:00:12.500
194&lt;font color="#3333CC"&gt;Violet, &lt;i&gt;please&lt;/i&gt;!&lt;/font&gt;
195- I am &lt;font size="20" color="#FF0000"&gt;&lt;u&gt;not&lt;/u&gt;&lt;/font&gt; your babe!
196</pre>
197
198
199
200
201<h2>Language Codes<a name="codes"></a></h2>
202
203<p>JW Player supports automatic conversion of ISO 639 language codes to a human-readable label for popular languages. Here is an overview, listing both two-character codes (as used in RSS) and three-character codes (as used in TX3G):</p>
204
205<table><tr>
206    <th>Language (label)</th><th>ISO 639-1 (mRSS)</th><th>ISO 639-2 (TX3G)</th>
207</tr><tr>
208    <td>Arabic</td><td>ar</td><td>ara</td>
209</tr><tr>
210    <td>Chinese</td><td>zh</td><td>chi, zho</td>
211</tr><tr>
212    <td>Czech</td><td>cs</td><td>cze, ces</td>
213</tr><tr>
214    <td>Danish</td><td>da</td><td>dan</td>
215</tr><tr>
216    <td>Dutch</td><td>nl</td><td>dut, nld</td>
217</tr><tr>
218    <td>English</td><td>en</td><td>eng</td>
219</tr><tr>
220    <td>Finnish</td><td>fi</td><td>fin</td>
221</tr><tr>
222    <td>French</td><td>fr</td><td>fra, fre</td>
223</tr><tr>
224    <td>German</td><td>de</td><td>deu, ger</td>
225</tr><tr>
226    <td>Hindi</td><td>hi</td><td>hin</td>
227</tr><tr>
228    <td>Hungarian</td><td>hu</td><td>hun</td>
229</tr><tr>
230    <td>Indonesian</td><td>id</td><td>ind</td>
231</tr><tr>
232    <td>Italian</td><td>it</td><td>ita</td>
233</tr><tr>
234    <td>Japanese</td><td>ja</td><td>jpn</td>
235</tr><tr>
236    <td>Korean</td><td>ko</td><td>kor</td>
237</tr><tr>
238    <td>Norwegian</td><td>no</td><td>nor</td>
239</tr><tr>
240    <td>Persian</td><td>fa</td><td>per, fas</td>
241</tr><tr>
242    <td>Polish</td><td>pl</td><td>pol</td>
243</tr><tr>
244    <td>Portuguese</td><td>pt</td><td>por</td>
245</tr><tr>
246    <td>Russian</td><td>ru</td><td>rus</td>
247</tr><tr>
248    <td>Spanish</td><td>es</td><td>spa</td>
249</tr><tr>
250    <td>Swedish</td><td>sv</td><td>swe</td>
251</tr><tr>
252    <td>Turkish</td><td>tr</td><td>tur</td>
253</tr></table>
254
255<p>If a language code is not recognized by the player, the unmodified code is used as a label.</p>
256
257</body>
258</html>
Note: See TracBrowser for help on using the repository browser.