Configuration

Tailor every aspect of the player to your needs

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
Clip properties and Custom properties
Clip events
Cuepoints

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 / Datatype	Default	Description
`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.

Event	When 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.
`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.

Event	When 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.

Listener	How To Configure
`onCuepoint`	An array of 2 members: 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) the cuepoint event handler function which takes 2 arguments: the current clip object 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