This is a message.

Clips

Clips represent movies to play in Flowplayer. Clips can also be provided as a Playlist with a series of clips that will be played in sequence. Clip and Playlist are objects of Player. This must be specified in the configuration as follows:

flowplayer("player", "flowplayer.swf", {
clip: {
...
},
playlist: [
...
]
});

JavaScript

Note: the names of clip and playlist in configuration are all lowercase. In the documentation we talk about these objects with an initial Uppercase letter.

In this section:

Overview of Clip

The Clip object in configuration has a dual role. It is either a collection of properties that will apply to all Clips, called Common Clip, or it is a string with the name and location of a single movie to play. When Flowplayer analyses Clip from the configuration, it places the properties in Common Clip and, if the Clip configuration object also has a movie, creates a Playlist in which it places the movie.

When you specify a Playlist in the configuration, you can specify for each Clip its properties and set event listeners. Properties of a Clip specified in the Playlist override those of the Common Clip. When you later replace the playlist, all Common Clip properties and event listeners are preserved. See also Clip events below for a discussion of Clip events.

Remember that the simplest form of a configuration is a string with the movie to play. Then here follow three examples that illustrate the above:

/ The simplest form of a configuration: clip to play
/
flowplayer("player", "flowplayer.swf", "myMovie.flv");
 

/ Play a single clip but set a property
/
flowplayer("player", "flowplayer.swf", {
clip: {
url: "myMovie.flv",
autoPlay: false
}
});
 

/ Common Clip and playlist
/
flowplayer("player", "flowplayer.swf", {
clip: {
autoPlay: false // applies to all Clips in the playlist
},
playlist: [ // an array of Clip objects
"myMovie.flv", // simple Clip object: movie to play
{ // Clip object
url: "myMovie2.flv",
autoPlay: true // override Common Clip for this clip
}
]
});

JavaScript

Clip types

A clip will generally be a movie to play but it can also be an audio or image file. An image file can be used as a splash screen and with audio files you can even turn Flowplayer into a jukebox.

Flowplayer supports all the video formats supported by Adobe Flash; they are listed here. The supported image formats are .jpg and .png and for audio only .mp3 is supported. When Flowplayer encounters a .mp3 file in the configuration, it automatically loads an audio plugin to play it. Note that setting a Playlist in runtime that has an .mp3 audio file, will not automatically load the Plugin. See the audio plugin for details. Here is an example of playlist that shows a splash image and then starts playing the audio file:

playlist: [
 
// show album cover
{url: 'album_cover.jpg', scaling: 'orig'},
 
// our MP3 does not start automatically
{url: 'my_song.mp3', autoPlay: false}
 
]

JavaScript

Clip properties

The following clip properties can be set in the configuration. Properties of a Clip specified in the Playlist override those of the Common Clip.

Property / DatatypeDefaultDescription

accelerated
boolean

false

Flag indicating whether Flash 9 (and above) hardware-accelerated fullscreen mode should be used.

autoBuffering
boolean

false

Flag indicating whether loading of clip into player's memory should begin straight away. When this is true and autoPlay is false then the clip will automatically stop at the first frame of the video.

autoPlay
boolean

true

Flag indicating whether the player should start playback immediately upon loading.

baseUrl
string

The first part of the URL of the video's location. This property is prepended in front of the url property (for relative URLs). If not specified, the video file is loaded from the same directory as the enclosing HTML file.

bufferLength
integer

3

The amount of video data (in seconds) which should be preloaded into Flowplayer's memory to before and during playback.

connectionProvider
string

The connection provider plugin to be used for this clip. Connection providers handle the connection to a streaming server or to a content delivery network (CDN). The value of this property should be the name of a configured plugin.

An example is our secure streaming plugin which provides the connection to a Wowza RTMP server in this demo.

cuepointMultiplier
integer

1000

The times of embedded cuepoints are multiplied by this value before being used. Some encoding tools embed cuepoints in seconds but Flowplayer processes cuepoints in milliseconds. Note that the times are also rounded to the nearest 100 milliseconds. For example, if a file has a cuepoint at 5.535 seconds, the cuepoint is fired at 5500 milliseconds (assuming the default multiplier value of 1000).

controls
object

null

Since 3.1.1. Alternate controlbar configuration for this clip. This overrides the settings specified for the controlbar plugin. This is mainly used when you have multiple clips in a playlist and you want to tweak the controlbar looks for a specific clip. All controlbar properties can be tweaked - except the url and positioning properties. You can see this feature in action in the instream playlist demo.

duration
number

0

The time, in seconds and fractions of a second, for which a video clip should be played until playback ceases. This must always be less than or equal to the total length of the clip. Zero means to play the whole clip.

fadeInSpeed
integer

1000

Time in milliseconds to fade from zero to full opacity upon commencement of video playback.

fadeOutSpeed
integer

1000

Time in milliseconds to fade from full to zero opacity upon completion of video playback.

linkUrl
string

The URL to direct users to when clicking the video screen.

linkWindow
string

_self

Defines where the page defined by linkUrl is opened. Available options are:

  • '_self': specifies the current frame in the current window.
  • '_blank': specifies a new window.
  • '_parent': specifies the parent of the current frame.
  • '_top': specifies the top-level frame in the current window.
  • '_popup': a popup browser window.

live
boolean

false

RTMP streaming servers support live streaming, which means that it is possible to set up a video camera or other live video source to stream live video data to Flowplayer. If you have an RTMP server which is providing a live video stream, you should set this property to true.

metaData
object

Normally the player shows the video only when it has read the dimensions metadata from the video file. If the file does not have metadata at all the video will not be shown at all. By setting this to property to false, the player will display the video even when the metadata is not available in the file.

originalUrl
string

The original URL of this clip before it has been updated by any URL resolver, like the bandwidth check plugin that changes the URL to reflect the chosen bitrate.

position
integer

Since 3.1.1. If the clip is an item of an instream playlist this property defines the time (in seconds) when the clip will start in relation to the parent clip. If the position is 0 then the clip will be played before the parent clip. If the position is -1 then the instream clip will be played after the main clip.

playlist
array

[ ]

Since 3.1.1. The instream playlist of this clip.

provider
string

http

The type of video source. By default, Flowplayer assumes that the source is a regular web server (with the provider name 'http'). To use a different provider, you must configure the provider explicitly. This page describes how to do that.

Flowplayer comes packaged with pseudostreaming, RTMP and HTTP Streaming providers. You can even build your own.

scaling
string

scale

Setting which defines how video is scaled on the video screen. Available options are:

  • 'fit': fit to window by preserving the aspect ratio encoded in the file's metadata
  • 'half': half-size (preserves aspect ratio)
  • 'orig': use the dimensions encoded in the file; if the video is too big for the available space, the video is scaled preserving the aspect ratio
  • 'scale': scale the video to fill all available space; ignores the dimensions in the metadata

start
integer

0

The time (in seconds) at which playback should commence. This is only supported if you deliver from a streaming server.

Note: Red5 servers currently cannot handle this property.

url
string

The URL of the video file to be loaded. You can specify an absolute URL here, or one that is relative to the current HTML file. The URL can also be given as the href attribute of the player container. If both are given then the configuration property overrides the href attribute.

urlEncoding
boolean

false

If true the clip's url will be url-encoded. Use this if the url contains non-ascii characters, for example chinese.

urlResolvers
string/array

The URL resolver plugins which are applied for this clip. URL resolvers determine the actual URL of the clip to be played. The value of this property should be the name of a configured plugin. Examples are our bandwidth detection and secure streaming plugins.

If you specify more than one URL resolver the value must be an array of strings, for example: ['smil', 'bwcheck'] like in this demo.

NOTE: URL resolvers are applied automatically if this property is not present and there are URL resolver plugins in the configuration. You can specify urlResolvers: null if you want insure that no URL resolvers are applied to this clip.

Custom properties

You can also create custom properties for a clip. You give them a name and they can have any value, which can even be an object in json. Flowplayer stores these custom properties with the Clip object so when you refer to the Clip or receive it in an event listener, all these properties are available to you. Specifying such properties in the Common Clip makes them available for all clips; specifying them only for a single Clip makes them available only for that Clip. Here is an example:

playlist: [
{
// "standard" flowplayer properties
url: 'path/to/movie.flv',
autoPlay: false,
 
// custom property
title: 'Swimming on ice at Lapland',
 
// custom properties can also be objects such as here
details: {
date: '03/24/2008',
creator: 'John Doe',
subject: ['culture', 'traveling', 'scandinavia']
}
}
]

JavaScript

Clip events

When inside a Player or Clip object a situation occurs that might be of interest to you, we have defined an event for that situation. If you want to know the situation occurs, you register an event listener, a function that you provide (write), that will be called when the particular situation occurs. For example, the onStart event of a Clip informs you the Clip has started playing and you may want to set the clip's title below the Player.

You can register Clip event listeners directly in the root of the configuration and Flowplayer will register them with the Common Clip so that they will be called when the event ocurrs for each Clip in the Player. Each Clip can also have own event listeners that will be called before the corresponsing event listener of the Common Clip. If you return false from an event listener, no other event listener will be called.

Note: Although an event listener registerd in the root level is registererd with the Common Clip, it does not replace an event listener that is set in the Common Clip. An event listener provided in the root will be called last.

The following example shows the three ways of providing an event listener in the configuration:

<SCRIPT>
flowplayer("player", "flowplayer.swf", {
clip: {
onStart: function() {
msgs.innerHTML += "Common Clip event listener called\n";
}
},
playlist: [
{
url: 'KimAronson-TwentySeconds58192.flv',
onStart:function() {
msgs.innerHTML += "Playlist's Clip event listener called\n";
}
},
'KimAronson-TwentySeconds63617.flv'
],
onStart: function() {
msgs.innerHTML += "Root's Clip event listener called\n";
}
});
</SCRIPT>
<div id='msgs'></div>

HTML

The output of the above code, when the first clip starts playing, is:

Playlist's Clip event listener called
Common Clip event listener called
Root's Clip event listener called

Text only

Basic clip events

Listeners to clip events have their this variable set to the current Player object and receive as their first argument a reference to the Clip on which the event fires.

For some events, there is also an onBefore version of the event, e.g. onBeforePause and onPause. Returing false from an onBefore event will cancel the event, i.e. the action is not performed and its on version will not be called.

EventWhen does it fire?If the action is canceled

onBegin
onBeforeBegin

This is always the first event to fire during the 'lifecycle' of a clip, and it does so as soon as the clip's video file has started buffering. Playback of the clip has not yet commenced, but streaming/downloading has been successfully initiated.

Playback will not start.

onFinish
onBeforeFinish

This fires when the clip reaches the end and the 'Play again' button appears.

In the case of a single clip, the player will start from the beginning of the clip. In the case of an ordinary clip in a playlist, the 'Play again' button will appear. In the case of the final clip in a playlist, the player will start from the beginning of the playlist.

onLastSecond

This is a convenience handler for performing actions in the last second of playback. The same thing can be accomplished with a so-called 'negative cuepoint', but because this is such a common scenario we have added an easy-to-use event handler.

onMetaData

This fires after onBegin, once the video file's metadata has been received. The clip object is provided as an argument to the handler, with the metadata included as a property of the object.

onMetaDataChange

This fires when the clip's metadata has been changed. Typical usage examples include access to server-side song title updates in an audio live stream or the new URL of the current clip after a bitrate switch.

onPause
onBeforePause

This fires when playback is paused.

The pause action is canceled.

onResized

This fires when the clip has been resized. Clip is resized for example when the screen size changes.

onResume onBeforeResume

This fires when playback is resumed after having been paused.

The player will remain paused.

onSeek
onBeforeSeek

This fires when the playhead is seeked forward or backward. This happens when the user clicks on the controlbar's timeline (i.e., uses the 'scrubber'). The second argument to this event is the target time where the seek ended at. In the case of onBeforeSeek, the argument is the time where the user is intending to seek to and can be slightly different from the value where the seek actually ends up (because of keyframe positions).

The seek action is canceled. This is useful for critical video content, the playback of which needs to be forced.

onStart

This fires at the point at which playback commences. With autoBuffering set to true it even fires when autoPlay is false, because the clip is paused at the first frame.

onStop
onBeforeStop

This fires when playback is stopped.

The stop action is canceled.

onUpdate

This fires when clip properties are updated using the clip object's update() method. The argument which is passed to the handler is the newly modified clip object.

Advanced clip events

These events are rarely needed by developers and are mostly used internally by the controlbar plugin. However, they may be of interest if your particular application needs to know the status of the buffer.

EventWhen does it fire?

onBufferEmpty

This fires when playback has consumed all the buffered video data and the playhead cannot proceed, resulting in a temporary stop in playback. This is more likely to occur with lower connection speeds and may happen multiple times during a clip's lifecycle.

onBufferFull

This fires when the video buffer has reached capacity (i.e., all currently required video data has been downloaded into the player's memory). The buffer size is determined by a clip's bufferLength property, which, by default, has a value of 3 seconds. This event may fire multiple times during a clip's lifecycle, depending on the size of the buffer and the user's connection speed.

onBufferStop

This fires when the stopBuffering API call is invoked.

onNetStreamEvent

Fired when an event is triggered on the NetStream object. The second argument in this event is the type of NetStream event type triggered and is one of the following:

  • 'onXMPData'
  • 'onCaption'
  • 'onCaptionInfo'
  • 'onPlayStatus'
  • 'onImageData'
  • 'RtmpSampleAccess'
  • 'onTextData'

You can register a listener for this event if you are interested in any of the event types listed previously. The third argument of this event is an info object related to the event type in question.

Cuepoints

Here is a basic cuepoint configuration for a clip:

clip : {
url: 'example.f4v',
 
onCuepoint: [
// each integer represents milliseconds in the timeline
[4000, 1100, 3600, -2300],
 
// this function is triggered when a cuepoint is reached
function(clip, cuepoint) {
alert("cuepoint " + cuepoint + " entered on clip " + clip.url);
}
]
}

JavaScript

If the time is given as a negative integer, then it is calculated from the end of the video. So -1000 means the last second of the video, -2000 means two seconds from the end of the video, and so on.

Cuepoints are set up in the onCuepoint event listener. It differs from all other event listeners inasmuch as it customizes a series of events and is configured as an array with the event handler as second item.

ListenerHow To Configure

onCuepoint

An array of 2 members:

  1. an array of customizable cuepoints containing:

    • the time when the event is fired - either an integer or a property labeled time (mandatory)
    • custom properties for the specific cuepoint (optional)
  2. the cuepoint event handler function which takes 2 arguments:

    1. the current clip object
    2. the current cuepoint

Cuepoint properties

Each cuepoint can optionally have custom properties that are supplied to the event handler.

clip : {
url: 'example.m4v',
 
onCuepoint: [
// set up last two cuepoints with custom properties
[
4,
{time: 1100, caption: 'Something weird happened here', bottom:0},
{
time: 3300, duration: 5400,
title: 'Acme home', url:'http://www.acme.org'
}
],
 
// cuepoint argument can have properties
function(clip, cuepoint) {
if (cuepoint.url) {
showAdvertisement(cuepoint);
} else if (cuepoint.caption) {
showCaption(cuepoint);
}
}
]
}

JavaScript

Single cuepoint

Sometimes you just want to define a single cuepoint and not a long list. In that case, you can omit the array and just supply one number.

clip: {
// cause something to happen two seconds before playback ends
onCuepoint: [-2000, function() {
// do something ...
}];
}

JavaScript