source: plugins/captions/doc/guide.html @ 1979

Revision 1979, 17.5 KB checked in by jeroen, 21 months ago (diff)

fixed HTML5 captions rendering, enhanced scaling to screen and started on HTML5 selection menu
Line 
1<!DOCTYPE html>
2<html lang="en">
3<head>
4<meta charset="UTF-8">
5<title>Captions Plugin Reference</title>
6<style>
7    body { padding: 50px 100px; width: 660px; font: 13px/20px Arial; background: #FFF; }
8    a , h1, h2{ color: #369; }
9    h1 { font-size: 32px; }
10    h2 { margin-top: 50px; }
11    h3 { margin-top: 25px; }
12    pre { font-size: 12px; background: #E5F3C8; padding:5px 10px; border: 1px solid #D3EAA4; }
13    dd { color: #333; font-style: italic; }
14</style>
15</head><body>
16
17
18<h1>Captions Plugin Reference</h1>
19
20<h2>Purpose</h2>
21
22<p>The purpose of this guide is providing a feature overview of the <a href="http://www.longtailvideo.com/addons/plugins/84/Captions">JW Player Captions Plugin</a>.</p>
23
24
25
26<h2>Introduction</h2>
27
28<p>The Captions plugin for JW Player supports the display of closed captions or subtitles at the bottom of a video. Captions can be shown or hidden with a toggle:</p>
29
30<p><img src="assets/captions_example.png" alt="A screenshot of example captions implementation" style="margin-left:15px"/></p>
31
32<p>Captions are read from external files, in the SRT (SubRip) text format or the DFXP (W3C TimedText) XML format. Captions are also read from MP4 videos (3GPP Timed Text). The plugin works in both Flash and HTML5, but there are certain format/device restrictions (see below).</p>
33
34<p>The plugin can load multiple subtitle tracks per video, in which case a selection menu is presented. It also supports <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12537/xml-playlist-support">playlists</a> and styling of the captions with CSS properties.</p>
35
36
37
38<h2>Configuration Options</h2>
39
40<p>Like the <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12536/configuration-options">JW Player </a> itself, the Captions plugin can be configured with options that are set in the embed code. The following configuration options are available:</p>
41
42<dl>
43<dt><b>back</b> (<em>false</em>)</dt>
44<dd>By default, the player renders a thin black outline around the captions, similar to TV / DVD captions. When setting this option <b>true</b>, a black box is drawn around the captions. This background makes the captions more readeable (nice for small texts), but does set them more apart from the video.</dd>
45<dt><b>file</b> (<em>undefined</em>)</dt>
46<dd>Location of the captions file to display. Should be the URL to a valid <a href="#dfxp">DFXP</a> or <a href="#srt">SRT</a> captions file. If your captions are embedded in your MP4 videos, or if you use a playlist, this option is not needed.</dd>
47<dt><b>state</b> (<em>true</em>)</dt>
48<dd>Describes whether to show the captions on startup or not. The default is <b>true</b> (captions are shown). When a viewer changes the state, the value is saved in a cookie, so users won't have to disable the captions on every video again if they don't want them.</dd>
49</dl>
50
51<h3>Example</h3>
52
53<p>Here is a basic embed code of a player with the captions plugin, using the <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/15995/jw-embedder-reference-guide">JW Embedder</a>. The <strong>file</strong> option is used to load SRT captions:</p>
54
55<pre>
56&lt;script type="text/javascript" src="/jwplayer/jwplayer.min.js"&gt;&lt;/script&gt;
57
58&lt;p id="container"&gt;The player will be placed here&lt;/p&gt;
59
60&lt;script type="text/javascript"&gt;
61 jwplayer("container").setup({
62   file: "/assets/video.mp4",
63   flashplayer: "/jwplayer/player.swf",
64   height: 360,
65   plugins: {
66     "captions-3": {
67       file: "/assets/captions.srt"
68     }
69   },
70   width: 640
71 });
72&lt;/script&gt;
73</pre>
74
75<h3>Crossdomain loading</h3>
76
77<p>An important issue to keep in mind with captions is that they cannot be loaded cross-domain. In other words, if your player is embedded at <em>http://somesite.com</em>, you cannot load SRT or XML captions from <em>http://othersite.com</em>. This restriction applies to all browsers and devices, in Flash and HTML5. There are workarounds though:</p>
78
79<ul>
80<li>You can place a small (PHP) script on the server that hosts your player to <em>proxy</em> the external playlist. This is the easiest solution which works for both Flash and HTML5.</li>
81<li>If you're using only the Flash mode of JW Player (no HTML5), you can place a <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12541/crossdomain-file-loading-restrictions">crossdomain.xml file</a> on the server that hosts the captions.</li>
82<li>A very technical solution for HTML5 is to configure the server that hosts your captions for <a href="https://developer.mozilla.org/En/HTTP_Access_Control">Cross-Origin Resource Sharing</a>.</li>
83</ul>
84
85
86
87<h2>Formats and Devices</h2>
88
89<p>This section lists the 3 formats the plugin supports, as well as the modes (Flash, HTML5)  and devices (iPad, iPhone, Android) in which these formats work.</p>
90
91<h3>SRT (SubRip)</h3>
92
93<p>The <a href="http://en.wikipedia.org/wiki/SubRip">SRT format</a> is a widely used and easy to understand plain text captioning format. It is supported in both Flash and HTML5 mode on all desktop browsers, plus on the iPad. Unfortunately, SRT is not supported on Android and the iPhone. On those devices, it is not possible to render custom graphics during video playback.</p>
94
95<p>In SRT, a double linebreak is used to distinct between entries. Single linebreaks are used to add breaks in the texts themselves. Lines should be restricted to about 80 characters per line, which fits the default plugin setup. Here's an example file:</p>
96
97<pre>
981
9900:00:08,000 --&gt; 00:00:10,000
100Nothing is going on.
101
1022
10300:00:10,500 --&gt; 00:00:12,500
104Violet, please!
105- I am not your babe!
106
1073
10800:00:17,000 --&gt; 00:00:20,000
109You stupid cow,
110look what you gone and done now, ay.
111</pre>
112
113<p><em>Note your SRT files should be saved using <strong>UTF8</strong> encoding in order to correctly display special characters (accents, but also e.g. Arab, Chinese, Russian).</em></p>
114
115<h3>DFXP (W3C TimedText)</h3>
116
117<p>The <a href="http://www.w3.org/TR/2010/PR-ttaf1-dfxp-20100914/">DFXP format</a> is an XML captioning format popular amongst Flash and Silverlight players. The Captions plugin also supports it in Flash mode, but not in HTML5. DFXP is therefore also not supported on the iPad, Android and the iPhone.</p>
118   
119<p>DFXP is a fairly complicated and structured XML format. The actual captions entries are found inside &lt;p&gt; tags inside the &lt;body&gt;, with &lt;br/&gt; tags used for line breaks. Here is an example:</p>
120
121<pre>
122&lt;tt xmlns="http://www.w3.org/2006/10/ttaf1"&gt;
123 &lt;body&gt;
124   &lt;div&gt;
125     &lt;p begin="00:00:08" end="00:00:10"&gt;- Nothing is going on.&lt;/p&gt;
126     &lt;p begin="00:00:10.5" end="00:00:12.5"&gt;You liar!&lt;/p&gt;
127     &lt;p begin="00:00:13.5" end="00:00:15"&gt;Are you?&lt;/p&gt;
128     &lt;p begin="00:00:17" end="00:00:20"&gt;Violet, please!&lt;br/&gt;- I am not your babe!&lt;/p&gt;
129     &lt;p begin="00:00:34" end="00:00:36"&gt;Vi, please.&lt;br/&gt;- Leave me alone!&lt;/p&gt;
130   &lt;/div&gt;
131 &lt;/body&gt;
132&lt;/tt&gt;
133</pre>
134
135<p><em>Note your DFXP files should be saved using <strong>UTF8</strong> encoding in order to correctly display special characters (accents, but also e.g. Arab, Chinese, Russian).</em></p>
136
137<h3>MP4 (3GPP Text Tracks)</h3>
138
139<p>The MP4 media container has the ability to <a href="http://en.wikipedia.org/wiki/MPEG-4_Part_17">embed timed text tracks</a>, in addition to e.g. a video and an audio track. This text data, often referred to as 3GPP Timed Text, is automatically picked up and displayed by the Captions plugin in Flash mode. On the iPad and iPhone, the HTML5 video elements themselves detect and render the closed captions:</p>
140
141<p><img src="assets/captions_iphone.png" alt="Embedded MP4 captions showing on the iPhone" style="margin-left:60px"/></p>
142
143<p>In HTML5 mode on desktop browsers and on Android, embedded MP4 captions are not supported.</p>
144
145
146
147<h2>Multiple Tracks</h2>
148
149<p>It is possible to assign multiple captions tracks (for multiple languages) to one video. The button that used to toggle the captions then pops up a language selection menu:</p>
150
151<p><img src="assets/captions_multitrack.png" alt="An example with multiple captions tracks" style="margin-left:20px"/></p>
152
153<p>For MP4 files with multiple tracks, the plugin automatically detects the languages and renders the menu. For SRT or DFXP files, there's two configuration options to set:</p>
154
155<dl>
156<dt><b>files</b> (<em>undefined</em>)</dt>
157<dd>When you have multiple captions, use the <b>files</b> option instead of <b>file</b>. Set it to a comma-separated list of URLs. Each URL in this list should link to a valid SRT or DFXP captions file. If your captions are embedded in your MP4 videos, this option is not needed.</dd>
158<dt><b>labels</b> (<em>undefined</em>)</dt>
159<dd>Set this value to a second comma-separated list, defining the labels for each language that should pop up in the selection menu (e.g. <em>English,Deutsch,Francais</em>). The amount and order of these labels should be the same as the amount and order of entries in the <b>files</b> option.</dd>
160</dl>
161
162<p>When a viewer changes the captions track, the value is saved in a cookie. That way the viewer won't have to re-set the track with every new video or page reload. You can override this cookied value by setting another option called <strong>label</strong>. Set it to the label of the track you want pre-selected.<p>
163
164<p><em>Note you can also set the <strong>labels</strong> option to override the default MP4 track labels.</em></p>
165
166<h3>Example</h3>
167
168<p>This example embed code loads a video with 3 different SRT files:</p>
169
170<pre>
171&lt;script type="text/javascript" src="/jwplayer/jwplayer.min.js"&gt;&lt;/script&gt;
172
173&lt;p id="container"&gt;The player will be placed here&lt;/p&gt;
174
175&lt;script type="text/javascript"&gt;
176 jwplayer("container").setup({
177   file: "/assets/video.mp4",
178   flashplayer: "/jwplayer/player.swf",
179   height: 360,
180   plugins: {
181     "captions-3": {
182       files: "/assets/deu.srt,/assets/fra.srt,/assets/ita.srt",
183       labels: "Deutsch,Français,Italiano"
184     }
185   },
186   width: 640
187 });
188&lt;/script&gt;
189</pre>
190
191<p><em>Note the selection menu cannot scroll (yet) if there are too many languages. Work around this issue by offering a language selection outside the player or use browser info for pre-selecting a few languages.</em></p>
192
193
194
195<h2>Playlist Support</h2>
196
197<p>Captions can be assigned to one or more videos in a playlist. The functionality is available for both inline and RSS playlists, in both Flash and HTML5. You can mix videos with and videos without captions in a single feed.</p>
198
199<p>Since RSS playlist format does not define an element for linking to captions files, captions should be set using the <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/12537/xml-playlist-support">JWPlayer XML namespace</a>. In practice, the namespace is enabled by:</p>
200
201<ul>
202<li>Setting an <b>xmlns:jwplayer</b> attribute in the main XML tag.</li>
203<li>Prefixing the XML elements with <b>jwplayer:</b>, e.g. <em>&lt;jwplayer:captions.file&gt;</em></li>
204</ul>
205
206<p>You can set either the <b>captions.file</b> (single track) or the <b>captions.files</b> &amp; <b>captions.labels</b> (multiple tracks) options for each playlist entry.</p>
207
208<h3>Example</h3>
209
210<p>Here is an example RSS playlist. The <em>captions.file</em> option is set for both entries:</p>
211
212<pre>
213&lt;rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/"&gt;
214  &lt;channel&gt;
215    &lt;title&gt;Example RSS playlist with captions&lt;/title&gt;
216
217    &lt;item&gt;
218      &lt;title&gt;Coronation Street&lt;/title&gt;
219      &lt;description&gt;A episode clip, with captions.&lt;/description&gt;
220      &lt;enclosure url="/static/corrie.mp4" /&gt;
221      &lt;jwplayer:captions.file&gt;/static/corrie.srt&lt;/jwplayer:captions.file&gt;
222    &lt;/item&gt;
223
224    &lt;item&gt;
225      &lt;title&gt;Big Buck Bunny&lt;/title&gt;
226      &lt;description&gt;The official trailer, with captions.&lt;/description&gt;
227      &lt;enclosure url="/static/bunny.mp4" /&gt;
228      &lt;jwplayer:captions.file&gt;/static/bunny.srt&lt;/jwplayer:captions.file&gt;
229    &lt;/item&gt;
230
231  &lt;/channel&gt;
232&lt;/rss&gt;
233</pre>
234
235<p><em>Note the same crossdomain loading restrictions that apply to captions also <a href="http://www.longtailvideo.com/support/jw-player/jw-player-for-flash-v5/19824/playlist-support-in-the-jw-player#XML">apply to playlists</a>.</em></p>
236
237
238
239<h2>Styling the Captions</h2>
240
241<p>It is possible to change the styling of the captions with a couple of configuration options. Here's a screenshot of a video with styled captions:</p>
242
243<p><img src="assets/captions_styling.png" alt="A screenshot of player with styled captions" style="margin-left:20px"/></p>
244
245<p>The following six style properties can be set. Add them to the player embed code, just like the <em>back</em> and <em>state</em> options:</p>
246
247<dl>
248<dt><b>color</b> ( <em>#FFFFFF</em> )</dt>
249<dd>Can be any hexadecimal color value (e.g. <strong>#FFCC00</strong>).</dd>
250<dt><b>fontFamily</b> ( <em>Arian,sans-serif</em> )</dt>
251<dd>Can be any font installed <a href="http://www.fonttester.com/web_safe_fonts.html">on a user's computer</a> (e.g. <strong>Georgia,serif</strong>).</dd>
252<dt><b>fontSize</b> ( <em>15</em> )</dt>
253<dd>Can be any size in pixels (e.g. <strong>20</strong>). Note the captions are scaled to cover the video, with the actual pixel size used at a video width of 400px.</dd>
254<dt><b>fontStyle</b> ( <em>normal</em> )</dt>
255<dd>Can be set to <strong>italic</strong> for making the text italic.</dd>
256<dt><b>fontWeight</b> ( <em>normal</em> )</dt>
257<dd>Can be set to <strong>bold</strong> for boldening the text.</dd>
258<dt><b>textDecoration</b> ( <em>none</em> )</dt>
259<dd>Can be set to <strong>underline</strong> to add a line below the text.</dd>
260</dl>
261
262<p><em>Note these styling options do <strong>not</strong> work for MP4 captions on the iPad/iPhone, since these devices offer no control over rendering of the captions.</em></p>
263
264<h3>DFXP Styling</h3>
265
266<p>The DFXP format contains two different mechanisms for styling captions. Both are supported by the player, though solely in Flash mode:<p>
267
268<ul>
269<li>The <em>&lt;head&gt;</em> of a DFXP file can contain one or more style elements. These elements are all given an ID. The individual captions paragraphs can be linked to the style rules using the <em>style="xx"</em> attribute.</li>
270<li>Inside captions paragraphs, text snippets can be wrapped in <em>&lt;span&gt;</em> elements. These spans can contain a <em>style="xx"</em> attribute, or even list individual style rules (like <em>fontWeight="bold"</em>).</li>
271</ul>
272
273<p>Here is the example DFXP file, containing both styling methods. Note the individual rules (color, fontSize, etc.) need to be prefixed with a <b>tts:</b> namespace identifier. The according namespace declaration (<em>xmlns:tts</em>) needs to be set in the main XML element to make it a valid file:</p>
274
275<pre>
276&lt;tt xmlns="http://www.w3.org/2006/10/ttaf1"
277  xmlns:tts="http://www.w3.org/2006/04/ttaf1#styling"&gt;
278  &lt;head&gt;
279   &lt;styling&gt;
280      &lt;style id="normal" tts:fontSize="15" /&gt;
281      &lt;style id="warning" tts:color="#FF0000" tts:fontWeight="bold" tts:fontSize="20" /&gt;
282   &lt;/styling&gt;
283  &lt;/head&gt;
284  &lt;body&gt;
285    &lt;div&gt;
286      &lt;p begin="00:00:08" end="00:00:10" style="normal"&gt;- Nothing is going on.&lt;/p&gt;
287      &lt;p begin="00:00:10.5" end="00:00:12.5" style="warning"&gt;You liar!&lt;/p&gt;
288      &lt;p begin="00:00:17" end="00:00:20" style="normal"&gt;Violet, please!&lt;br/&gt;
289          - I am &lt;span style="warning"&gt;not&lt;/span&gt; your babe!
290      &lt;/p&gt;
291      &lt;p begin="00:00:24" end="00:00:29" style="normal"&gt;
292          You &lt;span tts:fontStyle="italic"&gt;stupid cow&lt;/span&gt;, look what you did.&lt;/p&gt;
293    &lt;/div&gt;
294  &lt;/body&gt;
295&lt;/tt&gt;
296</pre>
297
298<p><em>Note the captions plugin does not support &lt;span&gt; tags inside &lt;span&gt; tags.</em></p>
299
300<h3>SRT Styling</h3>
301
302<p>The SRT file format does not support any styling, but this can be forces by inserting HTML tags. <em>&lt;b&gt;</em>, <em>&lt;i&gt;</em> and <em>&lt;u&gt;</em> can be used to set weight, style and decoration and  <em>&lt;font color="#ff0000" face="Courier" size="18"&gt;</em> can be used to set color, family and size. Use this as last resort, since compatibility with many tools <strong>will likely break</strong>.</p>
303
304
305
306<h2>Changelog</h2>
307
308<h3>Version 3.0</h3>
309
310<ul>
311<li>Added support for HTML5 mode: back/file/state options, SRT/MP4 formats, multiple tracks, captions styling and playlists.</li>
312</ul>
313<ul>
314<li>Enhanced support for dock button language shortcode in multitrack setups. The full label is simply shown.</li>
315<li>Made captions aware of controlbar in the "over" state. For player 5.7+, the captions will now scroll up if the controlbar shows and scroll down again if the controlbar hides.</li>
316<li>Added a timed transition to showing/hiding of the language selector.</li>
317<li>Added support for overriding the MP4 language labels with the "labels" option.</li>
318<li>Added a close button to the language selector menu.</li>
319<li>Added support for displaying filenames in language selector if labels are not shown.</li>
320<li>Added support for forcing a pre-set language through the "label" option.</li>
321<li>Enhanced scaling of the captions. For larger dimensions, they're now scaled relatively smaller.</li>
322</ul>
323<ul>
324<li>Fixed an issue with language selector tabbing that required two tabs for advancing one entry.</li>
325<li>Fixed an issue with OVA advertising that caused displaying captions on the preroll.</li>
326</ul>
327<ul>
328<li>Deprecated skinning the captions toggle (no skinning in HTML5). The feature still works, but only in Flash.</li>
329<li>Deprecated placing the toggle in the controlbar (no custom controlbar buttons in HTML5). The feature still works, but only in Flash.</li>
330</ul>
331
332
333
334</body></html>
Note: See TracBrowser for help on using the repository browser.