This is a message.

Playlists

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. Note: rss playlists are not supported by the ipad plugin.

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.18.swf", {
// playlist with two video clips
playlist: [ 'first.flv', 'second.flv']
});

JavaScript

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
}
]

JavaScript

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'
]

JavaScript

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:

$f("player", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
 
// common clip: these properties are common to each clip in the playlist
clip: {
// by default clip lasts 5 seconds
duration: 5
},
 
// playlist with five entries
playlist: [
 
// JPG image
"/media/img/tutorial/tap-splash.jpg",
 
// SWF file
{url: "/media/swf/clock.swf", scaling: "fit"},
 
// video
"http://edge.flowplayer.org/KimAronson-TwentySeconds58192.flv",
 
// another image. works as splash for the audio clip
{url: "/media/img/demos/national.jpg", duration: 0},
 
// audio, requires audio plugin. custom duration
{url: "/media/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.16.swf",
backgroundColor: '#aedaff'
}
}
 
});

JavaScript

Show this demo as a standalone version

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.

<rss version="2.0" 
xmlns:media="http://search.yahoo.com/mrss/"
xmlns:fp="http://flowplayer.org/fprss/">
 
<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" />

<!-- media:thumbnail is used to set a splash image into the playlist. -->
<media:thumbnail url="/media/img/title/screens.png" />

<!-- you can set flowplayer specific properties for the thumbnail
using a fp:thumbnail element -->
<fp:thumbnail scaling="orig" />
</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-TwentySeconds73213.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-TwentySeconds71844.flv" type="video/x-flv" />
</item>
 
</channel>
 
</rss>

XML

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

RSS XML TagTag AttributeClip Property

title

Custom property named title

media:content

url

The clip's url.

media:content

duration

The clip's duration (optional).

link

The clip's linkUrl pointing to a page which is opened when the user clicks on the video screen while the clip plays.

Custom properties in RSS

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" />

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];
}

JavaScript

Flowplayer specific clip properties in RSS

It's possible to supply Flowplayer specific clip properties in the Media RSS file. This is done using a fp namespace and fp:clip elements.

The media:thumbnail element is also supported. By using it you can include a splash image for a video or a audio clip. You can use fp:thumbnail to set flowplayer specific properties for the thumbnail. The following example shows these fp namespace elements.

<!--  note the fp namespace declaration  -->
<rss version="2.0"
xmlns:media="http://search.yahoo.com/mrss/"
xmlns:fp="http://flowplayer.org/fprss/">
 
<channel>
<title>Example media RSS playlist</title>
<link>http://www.flowplayer.org</link>
 
<item>
<title>Happy Feet</title>
<description>A custom property for a clip</description>
<media:credit role="author">Kim Aronson</media:credit>
<media:content
url="KimAronson-TwentySeconds58192.flv" type="video/x-flv" />
 
<!-- set some clip properties -->
<fp:clip bufferLength="10" scaling="orig" urlResolvers="smil,bwcheck" />
 
<!-- media:thumbnail is used to set a splash image into the playlist. -->
<media:thumbnail url="/media/img/title/screens.png" />
 
<!-- you can set flowplayer specific properties for the thumbnail
using a fp:thumbnail element -->
<fp:thumbnail scaling="orig" />
</item>
</channel>
</rss>

XML

Demos:

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 its 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.

Configuration

Here is the configuration for the example shown above.

flowplayer("rolls", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
 
// the "parent" clip
clip: {
 
// baseUrl for both parent and instream clips
baseUrl: 'http://edge.flowplayer.org',
 
// 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}
]
}
 
});

JavaScript

View this demo as a standalone version

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.

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
}
}

JavaScript

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