# Flowplayer - Flash Video Player for the Web
Embed video streams to your website. Superior alternative to YouTube. Open Sourced under the GPL license. No other software makes this smoother.
Author: Tero Piirainen
Keywords: video player for the web, flash video player,web media player,free video player,free flv player,mp4 flash player,mp4 player,open source video player,flash 9 video,flash video,web video,flv player,flv video

# Flash plugin: Captions Subtitles for your videos

## Introduction

The Captions plugin is used to show Closed Captions (CC) for videos. You can supply the Captions information as an external text file. Closed Captioning is a term describing several systems developed to display text on a video screen to provide additional or interpretive information to viewers who wish to access it. The most common use is to provide subtitles for movies. See here for more info.

## Features

- Loading subtitles from the Timed Text or Subrip format files.
- Styling text from styles set in the Time Text format files.
- Loading of subtitles from embedded FLV cuepoints.
- Controls an external Content plugin to show the cuepoints.

Timed Text is a W3C specification for delivering captioning and video description for the web. You can find the spec here in the W3C site. SubRip is a common format for distributing Captions for DVD rips. It is the native subtitle format of the SubRip program.

## SubRip example

The following shows Captions from a SubRib file. You will need a recent version of Flash installed to view the video that is a H.264 encoded mp4 file. The first subtitle comes after 13 seconds.

    $f("player", "@PLAYER_SWF@", {
    	clip: {

    		// here is our high quality movie
    		url: 'mp4:buffalo_soldiers.mp4',

    		// this is the SubRib file with captions info
    		captionUrl: 'http://releases.flowplayer.org/data/buffalo.srt',

    		// we want to use RTMP since this is a 1,5 hour long movie.
    		provider: 'rtmp'
    	},
    	plugins:  {

    		// the captions plugin
    		captions: {
    			url: '@MAIN_PLAYER_SWF@',

    			// pointer to a content plugin (see below)
    			captionTarget: 'content'
    		},

    		/*
    			configure a content plugin so that it
    			looks good for showing subtitles
    		*/
    		content: {
    			url:'../flowplayer.content.swf',
    			bottom: 25,
    			height:40,
    			backgroundColor: 'transparent',
    			backgroundGradient: 'none',
    			border: 0,
                textDecoration: 'outline',
    			style: {
    				body: {
    					fontSize: 14,
    					fontFamily: 'Arial',
    					textAlign: 'center',
    					color: '#ffffff'
    				}
    			}
    		},

    		// streaming plugin configuration
    		rtmp: {
    			url: '../flowplayer.rtmp.swf',
    			netConnectionUrl: 'rtmp://flashy.flowplayer.org:1935/fastplay'
    		},

    		// change default skin to "tube"
    		controls: {
    			url: '../flowplayer.controls.swf'
    		}

    	}
    });

## Configuration

Here is a list of all Captions specific clip properties. These go under the `clip` node in the player configuration:

property | datatype | default | description
--- | --- | --- | ---
`captionUrl` | String |  | Path to a Timed Text or SubRip Captions file.
`captions` | array |  | A json array of cuepoint objects ie { time: 0, name: 'cue1', parameters: { begin: 0, end: 4000, text: 'First caption with default style coming from the Content plugin config' } }
`showCaptions` | boolean | true | Show Captions for this clip. You can set this to false if you have embedded Captions in the video and you don't want to show them.

Here is a list of configuration options for the Captions plugin. These go under the Captions `plugin` node in the player configuration:

property | description
--- | ---
`captionTarget` | The name of a Content plugin configured to show the Captions. The plugin needs to be specified in the player's initial configuration.
`template` | Used with embedded cuepoints. A template string that specifies tokens for names of cuepoint parameters. The tokens are replaced by values that are looked up from the cuepoint parameters. If you embed cuepoints where the subtitles are in the cuepoint parameter called `subtitle`, you should set the use of a template with the value '${subtitle}'.

`button`

Display properties for the CC-button. The default properties are: `{ width: 20, height: 15, right: 5, bottom: 30, label: 'CC' }`. Specify `null` and the button is not shown at all. The `label` property in this object specifies the label text for the button. If you want to make the captions initially hidden, specify `display: 'none'` in the Content plugin that is used to show the captions. Once the CC button is clicked, the captions become visible.

## Scripting

The captions plugin has the following custom methods that can be used at runtime:

method | example | description
--- | --- | ---
loadCaptionsFromFile(clipIndex, captionURL, fileExtension) | loadCaptions(0, 'captions.xml') | Loads captions for the specified clip. The `fileExtension` is an optional parameter and you should specify it if the `captionURL` does not contain a file extension that can be used to recognize the caption file format. The supported `fileExtension` values are 'txt' and 'srt'.
loadCaptions(clipIndex, captions) | loadCaptions(0, captions) | Loads a json array of captions for the specified clip.

## Timed text example

    <a class="player" id="timedtext">
    	<img src="http://static.flowplayer.org/img/player/btn/showme.png"  />
    </a>

    $f("timedtext", "@PLAYER_SWF@", {
    	log: { level: 'debug', filter: 'org.flowplayer.captions.*'},
    	clip: {
    		url: 'http://video.flowplayer.org/flowplayer.flv',

    		// this is the Timed Text file with captions info
    		captionUrl: 'http://releases.flowplayer.org/data/timedtext.xml'
    	},
    	plugins:  {

    		captions: {
    			url: '@MAIN_PLAYER_SWF@',

    			// pointer to a content plugin (see below)
    			captionTarget: 'content'
    		},

    		// configure a content plugin to look good for our purpose
    		content: {
    			url:'../flowplayer.content.swf',
    			bottom: 25,
    			width: '80%',
    			height:40,
    			backgroundColor: 'transparent',
    			backgroundGradient: 'low',
    			borderRadius: 4,
    			border: 0,

    			style: {
    			    'body': {
    				fontSize: '14',
    				fontFamily: 'Arial',
    				textAlign: 'center',
    				color: '#000000'
    			    }
    		    }
    		}
    	}
    });

The timed text XML file used in this example is shown below. The style definitions are in the first part of the file inside the `head` element and below that we have the Captions inside the `body` element.

The first caption does not include the `style` attribute and therefore the style used to render it comes from the styling settings used to configure our Content plugin. The second caption uses the style with id 1 that defines a white font and left text alignment. The third caption has a small font coming from the 2nd style referenced by its id 2.

    <?xml version="1.0" encoding="UTF-8"?>
    <tt xml:lang="en" xmlns="http://www.w3.org/2006/10/ttaf1"
    	xmlns:tts="http://www.w3.org/2006/10/ttaf1#styling">
    	<head>
    		 <styling>
    			  <style id="1" tts:fontFamily="Arial" tts:fontSize="14" tts:color="#FFFFFF"
    			tts:textAlign="left" tts:fontStyle="Bold" />
    			  <style id="2" tts:fontSize="10" tts:color="#000000" />
    		 </styling>
    	</head>
    	<body>
    		  <div xml:lang="en" >
    			  <p begin = "00:00:00.01" dur="04.00">
    			First caption with default style coming from the Content plugin config
    		</p>

    			  <p begin = "00:00:04.19" dur="04.00" style="1">
    		  2nd caption with timed text styling to make the text white
    		</p>

    			  <p begin = "8s" dur="04.00" style="2">
    		  3rd caption using a small black font
    		</p>
    		 </div>
    	</body>
    </tt>

## Embedded Captions example

This example show Captions based on data included in cuepoints that are embedded in the video file. The cuepoints were embedded into the video using RichFLV. The first caption is at 6 seconds.

    <a class="player" id="embedded">
    	<img src="http://static.flowplayer.org/img/player/btn/showme.png"  />
    </a>

The file used in the example above has cuepoints at the following points of the timeline: 6000, 13500, 16000, and at 20000 milliseconds. Using the RichFLV application it's easy to add them. Each of these cuepoints has one parameter called `text` that contins the text displayed as the caption text.

    $f("embedded", "@PLAYER_SWF@", {
    	clip: {
    		url: 'http://video.flowplayer.org/flowplayer_cues.flv',
    		// cuepoint timing is in milliseconds in the file, so override
    		// the default multiplier value of 1000 that converts seconds
    		// to milliseconds
    		cuepointMultiplier: 1
    	},
    	plugins:  {

    		captions: {
    			url: '@MAIN_PLAYER_SWF@',

    			// the content plugin we use to show the captions
    			captionTarget: 'content'
    		},

    		// configure a content plugin to look good for our purpose
    		content: {
    			url:'../flowplayer.content.swf',
    			top: 10,
    			width: '80%',
    			height:40,
    			backgroundColor: 'transparent',
    			backgroundGradient: 'none',
    			border: 0,

                // an outline is useful so that the subtitles are more visible
                textDecoration: 'outline',
    			style: {
    			    'body': {
    				fontSize: '14',
    				fontFamily: 'Arial',
    				textAlign: 'center',
    				color: '#ffffff'
    			    }
    		    }
    		}
    	}
    });

## Json Config Captions Example

This example is Captions based on a Json config.

    $f("json", "@PLAYER_SWF@", {
    	clip: {
    		url: 'http://video.flowplayer.org/flowplayer.flv',
    		captions: [
    						{
    						time: 0,
    						name: 'cue1',
    						parameters: {
    							begin: 0,
    							end: 4000,
    							text: 'First caption with default style coming from the Content plugin config'
    							}
    						},
    						{
    						time: 4000,
    						name: 'cue2',
    						parameters: {
    							begin: 4000,
    							end: 8000,
    							text: '2nd caption with timed text styling to make the text white'
    							}
    						},
    						{
    						time: 8000,
    						name: 'cue3',
    						parameters: {
    							begin: 8000,
    							end: 12000,
    							text: '3rd caption using a small black font'
    							}
    						},

    					]
    	},
    	plugins:  {

    		captions: {
    			url: '@MAIN_PLAYER_SWF@',

    			// the content plugin we use to show the captions
    			captionTarget: 'content'
    		},

    		// configure a content plugin to look good for our purpose
    		content: {
    			url:'../flowplayer.content.swf',
    			top: 10,
    			width: '80%',
    			height:40,
    			backgroundColor: 'transparent',
    			backgroundGradient: 'none',
    			border: 0,

                // an outline is useful so that the subtitles are more visible
                textDecoration: 'outline',
    			style: {
    			    'body': {
    				fontSize: '14',
    				fontFamily: 'Arial',
    				textAlign: 'center',
    				color: '#ffffff'
    			    }
    		    }
    		}
    	}
    });

## Javascript Plugin

Available is the captions javascript plugin which provides a means to dynamically produce a scrollable playlist of the cuepoints.

The captions setup is similar to the javascript playlist plugin, where the template can be provided by the html or config.

    $f("javascript-plugin", "@PLAYER_SWF@", {
    	clip: {
    		url: 'http://video.flowplayer.org/flowplayer.flv',
    		captions: [
    						{
    						time: 0,
    						name: 'cue1',
    						parameters: {
    							begin: 0,
    							end: 4000,
    							text: 'First caption with default style coming from the Content plugin config'
    							}
    						},
    						{
    						time: 4000,
    						name: 'cue2',
    						parameters: {
    							begin: 4000,
    							end: 8000,
    							text: '2nd caption with timed text styling to make the text white'
    							}
    						},
    						{
    						time: 8000,
    						name: 'cue3',
    						parameters: {
    							begin: 8000,
    							end: 12000,
    							text: '3rd caption using a small black font'
    							}
    						},

    					]
    	},
    	plugins:  {

    		captions: {
    			url: '@MAIN_PLAYER_SWF@',

    			// the content plugin we use to show the captions
    			captionTarget: 'content'
    		},

    		// configure a content plugin to look good for our purpose
    		content: {
    			url:'../flowplayer.content.swf',
    			top: 10,
    			width: '80%',
    			height:40,
    			backgroundColor: 'transparent',
    			backgroundGradient: 'none',
    			border: 0,

                // an outline is useful so that the subtitles are more visible
                textDecoration: 'outline',
    			style: {
    			    'body': {
    				fontSize: '14',
    				fontFamily: 'Arial',
    				textAlign: 'center',
    				color: '#ffffff'
    			    }
    		    }
    		}
    	}
    }).captions("div.items", {});

Configuration:

property / datatype | default | description
--- | --- | ---
activeClass string |  | The active selected item class.
template string |  | The template config to be used for generating the thumbnails. The fields of the cuepoints are used for the template like ${time}. If the wrapper has the template set, it will be used instead of the template config.
fadeTime int | 100 | The interval time for fading the wrapper in and out. Useful for hiding the wrapper if a template is set in it.