[[PlayerToc(plugins)]]

= Captions plugin = 

This plugin displays closed captions on top of the video. These captions can come from an external file (in [http://en.wikipedia.org/wiki/Timed_Text Timedtext] or [http://en.wikipedia.org/wiki/Subrip Subrip] format) or as metadata from the video itself (as [http://en.wikipedia.org/wiki/3GPP_Timed_Text MPEG-4 Timedtext] or  [http://www.buraks.com/captionate Captionate] events).

This plugin is compatible with version 4.1 of the player. For 4.3+, the plugin will place a  button in the controlbar. For 4.5+, the plugin will place the button in the dock (if ''dock=true'' is set).

== Examples == 

Here is an example of the captions plugin in action. Below is the string of flashvars used:

[[JWPlayer(400,250,file=/player/testing/files/corrie.flv&plugins=captions&captions.file=/player/testing/files/corrie.xml)]]

{{{
file=/player/testing/files/corrie.flv&plugins=captions&captions.file=/player/testing/files/corrie.xml
}}}

Here is another example of the captions plugin with a video that has built-in captions (MPEG4 Timedtext). The ''dock'' feature of the player is turned on, so the button ends up in the dock. Also, the ''captions.back'' feature is turned on.

[[JWPlayer(400,250,file=/player/testing/files/bunny.mp4&plugins=captions&dock=false&captions.back=true&stretching=fill&dock=true)]]

{{{
file=/player/testing/files/bunny.mp4&plugins=captions&dock=false&captions.back=true&dock=true
}}}


== Configuration == 

The plugin is loaded with the flashvar ''plugins=captions''. This will automatically load the latest version of the plugin straight off our servers. It offers four additional flashvars:

 * '''captions.back''' (''false''): If set to ''true'', the plugin will render a semitransparent background for the captions, instead of a black outline.
 * '''captions.file''' (''undefined''):  - Location of the XML/SRT file to load the closed captions from. You won't have to set it if you have captions embedded in the video. 
 * '''captions.fontsize''' (''14''):  Size of the captions font. At its default, about 70 characters fit on a single line (which is the broadcast default).
 * '''captions.state''' (''true''): Set this to ''false'' to turn off the captions by default.

Here's an example of both a [http://developer.longtailvideo.com/player/testing/files/corrie.xml Timedtext XML file] and a [http://developer.longtailvideo.com/player/testing/files/corrie.srt Subrip text file].

Note that caption files (both XML and SRT) are subject to the [wiki:FlashSecurity Crossdomain security restrictions] of Flash. This means that a videoplayer on one domain cannot load captions from another domain. It can be fixed by placing a [wiki:FlashSecurity  crossdomain.xml] file at the server the captions are loaded from.

== Playlists == 

Captions can also be placed in playlists, by leveraging the [wiki:FlashFormats#JWPlayernamespace JWPlayer namespace]. Use the ''jwplayer:captions'' element name for this. Here is an example of an RSS feed with one video that contains captions:

{{{
<rss version="2.0" xmlns:jwplayer="http://developer.longtailvideo.com/trac/wiki/FlashFormats">
  <channel>
    <title>Example RSS feed with jwplayer extensions</title>
    <item>
      <title>FLV Video</title>
      <link>http://www.bigbuckbunny.org/</link>
      <description>Big Buck Bunny is a short animated film by the Blender Institute, part of the Blender Foundation.</description>
      <enclosure url="../../testing/files/bunny.flv" type="video/x-flv" length="1192846" />
      <jwplayer:captions>files/captions.xml</jwplayer:captions>
    </item>
  </channel>
</rss>
}}}

The ''captions.file'' flashvar will be ignored when a playlist is used.

== Source code == 

The source code of this plugin can be obtained [changeset:HEAD/plugins/captions?old_path=%2F&format=zip in a zip] (click the zip links at the bottom) or through [http://subversion.tigris.org/ Subversion]:

{{{
svn co http://developer.longtailvideo.com/svn/plugins/captions
}}}

If you don't have a Subversion client, check out [http://tortoisesvn.tigris.org/ Tortoise] (Windows) or [http://scplugin.tigris.org/ SC Plugin] (MAC).

You don't need Adobe Flash to modify this plugin. Instead, you can edit the plugin with any text editor you like. The plugin can be compiled with the free, cross-platform [http://www.adobe.com/cfusion/entitlement/index.cfm?e=flex3sdk MXMLC compiler]. See our [wiki:PluginsCompiling plugin compiling overview] for more info.