Order Now AdSolution Sign Up | Login » Bits on the Run Sign Up | Login »

AddOns

Captions Plugin Reference Guide

Purpose

The purpose of this guide is providing a feature overview of the JW Player Captions Plugin.

Introduction

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:

A screenshot of example captions implementation

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 not on iOS due to technical limitations (see below).

The plugin can load multiple subtitle tracks per video, in which case a selection menu is presented. It also supports playlists and styling of the captions with a few basic CSS properties.

Configuration Options

Like the JW Player itself, the Captions plugin can be configured with options that are set in the embed code. The following configuration options are available:

file (undefined)
Location of the captions file to display. Should be the URL to a valid SRT (preferred) or DFXP captions file. If your captions are embedded in your MP4 videos, or if you use a playlist, this option is not needed.
back (false)
By default, the player renders a thin black outline around the captions, similar to TV / DVD captions. When setting this option true, a black box is drawn around the captions. This background makes the captions more readable (nice for small texts), but does set them more apart from the video.
state (true)
Describes whether to show the captions on startup or not. The default is true (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 over and over if they don't want them.

Example

Here is a basic embed code of a player with the captions plugin, using the JW Embedder. The file option is used to load SRT captions:

<script type="text/javascript" src="/jwplayer/jwplayer.min.js"></script>

<p id="container">The player will be placed here</p>

<script type="text/javascript">
 jwplayer("container").setup({
   file: "/assets/video.mp4",
   flashplayer: "/jwplayer/player.swf",
   height: 360,
   plugins: {
     "captions-2": {
       file: "/assets/captions.srt"
     }
   },
   width: 640
 });
</script>

Crossdomain loading

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 http://somesite.com, you cannot load SRT or XML captions from http://othersite.com. This restriction applies to all browsers and devices, in Flash and HTML5. There are workarounds though:

Formats and Devices

This section lists the 3 formats the plugin supports, as well as the modes (Flash, HTML5) and devices (Android, iOS) in which these formats work.

SRT (SubRip)

The SRT format 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. On Android, SRT is only supported in Flash mode. SRT is not supported on the iPad/iPhone, since it is not possible to render custom graphics during (fullscreen) video playback.

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:

1
00:00:08,000 --> 00:00:10,000
Nothing is going on.

2
00:00:10,500 --> 00:00:12,500
Violet, please!
- I am not your babe!

3
00:00:17,000 --> 00:00:20,000
You stupid cow,
look what you gone and done now, ay.

Note your SRT files should be saved using UTF8 encoding in order to correctly display special characters (accents, but also e.g. Arab, Chinese, Russian).

MP4 (3GPP Text Tracks)

The MP4 media container has the ability to embed timed text tracks, 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. It is not supported in HTML5.

MP4 captions are supported on the iPad/iPhone though, since their browser itself detect and renders the closed captions. It also displays a language selection menu in case multiple tracks are shown (the speech bubble bottom right):

Embedded MP4 captions showing on the iPhone

Tools like HandBrake or MP4 Box can be used to embed captions in MP4 files.

DFXP (W3C TimedText)

The DFXP format is an XML captioning format popular amongst Flash and Silverlight players. The Captions plugin also supports it in Flash mode (desktop + Android), but not in HTML5. If you have a choice, pick the SRT format over DFXP.

DFXP is a fairly complicated and structured XML format. The actual captions entries are found inside <p> tags inside the <body>, with <br/> tags used for line breaks. Here is an example:

<tt xmlns="http://www.w3.org/2006/10/ttaf1">
 <body>
   <div>
     <p begin="00:00:08" end="00:00:10">- Nothing is going on.</p>
     <p begin="00:00:10.5" end="00:00:12.5">You liar!</p>
     <p begin="00:00:13.5" end="00:00:15">Are you?</p>
     <p begin="00:00:17" end="00:00:20">Violet, please!<br/>- I am not your babe!</p>
     <p begin="00:00:34" end="00:00:36">Vi, please.<br/>- Leave me alone!</p>
   </div>
 </body>
</tt>

Note your DFXP files should be saved using UTF8 encoding in order to correctly display special characters (accents, but also e.g. Arab, Chinese, Russian).

Multiple Tracks

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:

An example with multiple captions tracks

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:

files (undefined)
When you have multiple captions, use the files option instead of file. 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.
labels (undefined)
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. English,Deutsch,Francais). The amount and order of these labels should be the same as the amount and order of entries in the files option.

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 label. Set it to the label of the track you want pre-selected.

Note you can also set the labels option to override the default MP4 track labels.

Example

This example embed code loads a video with 3 different SRT files:

<script type="text/javascript" src="/jwplayer/jwplayer.min.js"></script>

<p id="container">The player will be placed here</p>

<script type="text/javascript">
 jwplayer("container").setup({
   file: "/assets/video.mp4",
   flashplayer: "/jwplayer/player.swf",
   height: 360,
   plugins: {
     "captions-2": {
       files: "/assets/deu.srt,/assets/fra.srt,/assets/ita.srt",
       labels: "Deutsch,Français,Italiano"
     }
   },
   width: 640
 });
</script>

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.

Playlist Support

Captions can be assigned to one or more videos in a playlist. The functionality is available for both inline and RSS playlists. You can mix videos with and videos without captions in a single feed.

Since the RSS playlist format does not define an element for linking to captions files, captions should be set using the JWPlayer XML namespace. In practice, the namespace is enabled by:

You can set either the captions.file (single track) or the captions.files & captions.labels (multiple tracks) options for each playlist entry.

Example

Here is an example RSS playlist. The first entry has a single caption, the second entry has two tracks:

<rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/">
  <channel>
    <title>Example RSS playlist with captions</title>

    <item>
      <title>Coronation Street</title>
      <description>A episode clip, with captions.</description>
      <enclosure url="/static/corrie.mp4" />
      <jwplayer:captions.file>/static/corrie.srt</jwplayer:captions.file>
    </item>

    <item>
      <title>Big Buck Bunny</title>
      <description>The official trailer, with captions.</description>
      <enclosure url="/static/bunny.mp4" />
      <jwplayer:captions.files>/assets/deu.srt,/assets/fra.srt</jwplayer:captions.files>
      <jwplayer:captions.labels>Deutsch,Français</jwplayer:captions.labels>
    </item>

  </channel>
</rss>

Note the same crossdomain loading restrictions that apply to captions also apply to playlists.

Styling the Captions

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:

A screenshot of player with styled captions

The following six style properties can be set. Add them to the player embed code, just like the back and state options:

color ( #FFFFFF )
Can be any hexadecimal color value (e.g. #FFCC00).
fontFamily ( Arian,sans-serif )
Can be any font installed on a user's computer (e.g. Georgia,serif).
fontSize ( 15 )
Can be any size in pixels (e.g. 20). Note the captions are scaled to cover the video, with the actual pixel size used at a video width of 400px.
fontStyle ( normal )
Can be set to italic for making the text italic.
fontWeight ( normal )
Can be set to bold for boldening the text.
textDecoration ( none )
Can be set to underline to add a line below the text.

Note these styling options do not work for MP4 captions on the iPad/iPhone, since these devices offer no control over rendering of the captions.

DFXP Styling

The DFXP format contains two additional mechanisms for styling captions. Both are supported by the player, though solely in Flash mode:

Here is the example DFXP file, containing both styling methods. Note the individual rules (color, fontSize, etc.) need to be prefixed with a tts: namespace identifier. The according namespace declaration (xmlns:tts) needs to be set in the main XML element to make it a valid file:

<tt xmlns="http://www.w3.org/2006/10/ttaf1" 
  xmlns:tts="http://www.w3.org/2006/04/ttaf1#styling">
  <head>
   <styling>
      <style id="normal" tts:fontSize="15" />
      <style id="warning" tts:color="#FF0000" tts:fontWeight="bold" tts:fontSize="20" />
   </styling>
  </head>
  <body>
    <div>
      <p begin="00:00:08" end="00:00:10" style="normal">- Nothing is going on.</p>
      <p begin="00:00:10.5" end="00:00:12.5" style="warning">You liar!</p>
      <p begin="00:00:17" end="00:00:20" style="normal">Violet, please!<br/>
          - I am <span style="warning">not</span> your babe!
      </p>
      <p begin="00:00:24" end="00:00:29" style="normal">
          You <span tts:fontStyle="italic">stupid cow</span>, look what you did.</p>
    </div>
  </body>
</tt>

Note the captions plugin does not support <span> tags inside <span> tags.

SRT Styling

The SRT file format does not support any styling, but this can be forces by inserting HTML tags. <b>, <i> and <u> can be used to set weight, style and decoration and <font color="#ff0000" face="Courier" size="18"> can be used to set color, family and size. Use this as last resort, since this is not what SRT was ment for and compatibility with other players will likely break.

Changelog

Version 2.0

Version 2.1

Version 2.2

Version 2.3

Version 2.4

Version 2.5