Flowplayer Configuration Tailor every aspect of the player to your needs

• Introduction
• Player
• Clips
• Playlists
• Plugins
• Streaming

Introduction

There are four kinds of playlists in Flowplayer:

1. An internal playlist is simply an array of clip objects that are played in sequence.
2. A RSS playlist is a playlist that is supplied in the Media RSS format. When this XML-based playlist configuration file is supplied to Flowplayer, it works just like an internal playlist.
3. An instream playlist is an array of clip objects that are defined for a clip. The clips in an instream playlist can be played before, in the middle or after the main video starts. Instream playlists are mainly used in advertisement configurations.
4. An external playlist is displayed beside the player. This is a visible widget which is confiugred using the JavaScript-based playlist plugin. External playlists are not discussed here.

Internal playlist

Here is an internal playlist configuration in its simplest form:

flowplayer("containerId", "flowplayer-3.2.4.swf", {

	// playlist with two video clips
	playlist: [ 'first.flv', 'second.flv']

});

Playlist clips can also be complex objects with many different configuration properties:

playlist: [
   'first.jpg',
   'second.mp4',

	// customized third clip with autoPlay set to false
   {
		url: 'third.flv',
		autoPlay: false
	}
]

Common clip

The common clip is an important concept in Flowplayer. It specifies common properties for every clip in the playlist. The common clip is configured by defining a clip object outside the playlist. Here is an example:

// these properties are common for each clip in the playlist
clip : {
	scaling: 'fit',
	autoPlay: false
},

// the first clip overrides the scaling property
playlist: [
   { url: 'splash.jpg', scaling: 'orig'},
   'clip1.flv',
   'clip2.mp4'
]

These common properties are applied to all clips and they can be overridden by the entries in the playlist. (The same applies for event properties, described in the events document)

If you define a clip object without playlists, then the playlist is automatically created on your behalf. The playlist will have one entry and its properties become the properties of the common clip and the clips's url is made the first (and only) playlist entry. When modifying the playlist programmatically using the play(clip) method, all the common clip properties are preserved.

Example

Here is an example playlist where each entry in the list is in a different format:

The configuration

Here is the configuration for the above playlist:

// setup player 
$f("player", "http://releases.flowplayer.org/swf/flowplayer-3.2.4.swf", {

	// common clip: these properties are common to each clip in the playlist
	clip: { 
		// by default clip lasts 5 seconds
		duration: 5		
	},
	
	// playlist with four entries
	playlist: [
		
		// JPG image
		'/img/tutorial/tap-splash.jpg', 
		
		// SWF file
		{url: 'http://releases.flowplayer.org/swf/clock.swf', scaling: 'fit'},
		
		// video
		'http://blip.tv/file/get/KimAronson-TwentySeconds58192.flv',
		
		// another image. works as splash for the audio clip
		{url: '/img/demos/national.jpg', duration: 0},
		
		// audio, requires audio plugin. custom duration
		{url: 'http://releases.flowplayer.org/data/fake_empire.mp3', duration: 25}		

	],
	
	// show playlist buttons in controlbar
	plugins:  {
		controls: {
			playlist: true,
			
			// use tube skin with a different background color
			url: 'flowplayer.controls-tube-3.2.2.swf', 
			backgroundColor: '#aedaff'
		} 
	}	
});

RSS playlist

RSS playlists were introduced in Flowplayer version 3.1.1. You can supply a RSS file that uses the Yahoo Media extensions and the player will load it and build the playlist based on it. Here is a sample RSS file with comments about how the information is mapped to playlist clips.

<!-- :mode=xml: -->
<rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/">

	<channel>
		<title>Example media RSS playlist</title>
		<link>http://www.flowplayer.org</link>
		
		<item>
			<!-- The title goes to the clip as a custom property -->
			<title>Happy Feet</title>

			<!-- description goes to the clip as a custom property -->
			<description>A custom property for a clip</description>

			<!-- media:credit goes to the clip as a custom 
						property called 'media:credit' -->
			<media:credit role="author">Kim Aronson</media:credit>

			<!-- media:content is used as the clip URL -->
			<media:content 
				url="KimAronson-TwentySeconds58192.flv" type="video/x-flv" />
		</item>
		<item>
			<title>Beach and palms</title>
			<description>test</description>
			<media:credit role="author">Kim Aronson</media:credit>
			<media:content 
				url="KimAronson-TwentySeconds63617.flv" type="video/x-flv" />
		</item>
		<item>
			<title>Brown Carpet</title>
			
			<!-- the link element is mapped to the clip's linkUrl property -->
			<link>http://flowplayer.org</link>
			<description>test</description>
			<media:credit role="author">Kim Aronson</media:credit>
			
			<!-- custom duration -->
			<media:content url="KimAronson-TwentySeconds71844.flv"
				duration="5"  type="video/x-flv" />
		</item>	
		<item>
			<title>Stuff on a table</title>
			<description>test</description>
			<media:credit role="author">Kim Aronson</media:credit>
			<media:content 
				url="KimAronson-TwentySeconds73213.flv" type="video/x-flv" />
		</item>					
		
	</channel>
	
</rss>

The Following table lists how the RSS data is mapped to playlist clips:

In addition to what is listed above, the file can contain additional elements and attributes. These are all mapped to Clip custom properties. Here is an example modeled after an imaginary advertising solution:

<media:instream_ad type="preroll" url="http://adserver.flowplayer.org/myad.xml" />

Here's the JavaScript code on how to access this data:

onStart: function(clip) {
    var preroll = clip["media:instream_ad"];
    var url = preroll.url;
    var type = preroll.type; // is 'preroll'

    // If there are multiple instream_ad elements for the item/clip
    // they will be contained in an array, for example if there are 3 ads:

    var ads = clip["media:instream_ad"];
    preroll = ads[0];
    var midroll = ads[1];
    var postroll = ads[3];
}

Demos:

• Basic RSS playlist setup
• RSS with the JavaScript playlist plugin

Instream playlist

Instream playlists were introduced in Flowplayer version 3.1.1. These playlists are defined for an individual clip and not for the configuration root. The clips in an instream playlist can be played before, in the middle and after the main clip so that the clip's index property is not changed. The clips inside the instream playlist are called instream clips. Typically these instream clips are mainly used for advertisement purposes.

You can supply a position property for the instream clip which specifies when the clip starts in relation to the parent clip. For example, position: 10 means that the instream clip will start at the 10th second of the parent clip. If the position is 0, then the clip will be played before the parent clip as a preroll and if the position is -1 then the instream clip will be played after the main clip as a postroll.

During the time the instream clip is playing the parent clip will be paused. If you use progressive download or pseudostreaming, it will continue loading the parent clip in the background. With RTMP, the loading will be limited to the buffer size. When the instream clip ends, the parent clip will resume from the position where it had left off.

You can use instream clips of any and all of these media types (audio, video, images). Additionally, you can mix different streaming providers, so that the main clip and it's instream clips are supplied by different providers.

the following demo has three instream clips specified for the positions 0 (beginning), 5 (middle) and -1 (end). You can see the configuration below the demo.

Instream playlist configuration

Here is the configuration for exmple shown above.

flowplayer("rolls", "http://releases.flowplayer.org/swf/flowplayer-3.2.4.swf", {

	// the "parent" clip
	clip: {

		// baseUrl for both parent and instream clips
		baseUrl: 'http://blip.tv/file/get',

		// duration for the parent clip
		duration: 10,

		// instream playlist
		playlist: [

			// before the parent clip starts (ie. "pre-roll")
			{url: 'KimAronson-TwentySeconds59483.flv', duration: 2, position: 0},

			// in the middle of the parent clip (ie. "mid-roll") starting at 5 seconds
			{url: 'KimAronson-TwentySeconds58192.flv', duration: 3, position: 5},

			// at the end of the parent clip (ie. "post-roll")
			{url: 'KimAronson-TwentySeconds63617.flv', duration: 4, position: -1}
		]
	}

});

Take a look at a more advanced instream playlist example. The Flowplayer API can also be used to play instream clips. Here is a mid-roll advertising demo that plays instream clips programmatically via the API.

Instream clips and events

In this section we assume that you have a basic understanding of Flowplayer events.

When an instream clip is started, the main clip is paused; an onPause event will be fired and the instream clip plays just like a regular clip. The instream clip will fire the onBegin, onMetadata and onStart events just like a normal clip. The index property of the instream clip has the same value as its parent clip. If you have an event listener, you can differentiate between main and instream clips by using the isInStream property as follows:

onPause: function(clip) {

	// we are only interested in instream clips when the player is paused
	if (clip.isInStream) {
		// do something
	}
}

When an instream clip finishes, the main video is resumed and an onResume event is fired.

Flowplayer Twitter feed