Flowplayer Configuration Tailor every aspect of the player to your needs

Introduction

After you have installed Flowplayer, it is time to customize it to your needs. You may want to customize the looks of the player, liaisse with advertisement providers, configure video clips and playlists, setup how your video is streamed or even tweak how the Flash object is embedded. Supplying a configuration is probably the easiest way to accomplish these things and more.

In this section:

Understanding the Configuration
Core objects and Plugins that you can configure
Configuration and JavaScript
Supplying the configuration
Flash embedding

Understanding Configuration

You customize how a particular player shows and behaves on a particular webpage, by providing it with a configuration. A configuration is simply a list of options and their values. You provide it as the third argument in the initial call to flowplayer() when you setup a player on a page. When flowplayer() processes this argument, it installs the player on the page accordingly.

The configuration can be simple (the url of the clip to play) but can also be very complex. To understand the configuration, you must see Flowplayer as a collection of objects, and each object can have zero or more properties that can be set via the configuration. Which properties those are, is defined by that object and is documented there. Via the plugin mechanism, new objects can be added to a player and their properties can then be set too via the configuration. Here is an example that addresses the Clip object of the player installed on the HTML element with id="player":

<script>
flowplayer("player", "flowplayer.swf", {
    clip:  {
        autoPlay: false,
        autoBuffering: true
    }
});
</script>

Core objects and Plugins that you can configure

Flowplayer has the following core objects and plugins that can be specified via the configuration:

Player

Represents a Player on a page. You can set its display properties and provide event listeners in the configuration.

Playlist

A playlist in Flowplayer is simply an array of clips. When you set a playlist in the configuration, Flowplayer will play each of the clips in the playlist in sequence. You can set properties for each of the clips in the playlist. Playlists are described in the JavaScript API, where the configuration options are also discussed.

Common clip

The Common clip is an important concept in Flowplayer. It specifies settings that are common to all clips in the playlist. When replacing the playlist, all Common clip settings are preserved.

Clip

A Clip object can be thought of a as single movie in the player. In the configuration, you can specify the location (url) of the clip, whether to start playing immediately or first show a splash image and many other things.

Plugin (Flash)

Flowplayer offers standard methods and properties that control the loading and placement of a plugin. To load the plugin you specify its url in the configuration. Following this you can specify the properties of the objects the plugin makes available that you want to set. There are several plugins available or you can write your own.

+ show list of Flash plugins

Controls	Shows the controls of the video. The controlbar plugin lets you configure the placement, buttons and appearance of the video controls. Each button and widget can be shown or hidden and the background color and gradient settings can be changed. You can have many controlbars on the same page at the same time. One might be positioned at the upper corner showing only a play/pause button while another may show the timeline, volume control and fullscreen button. And if you still don't like our control bar, you can replace it with your own controlbar plugin. The controlbar plugin is automatically loaded by Flowplayer.
Captions	The Captions plugin is used to show closed Captions 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.
Content	The content plugin lets you place HTML text over or beside the video. You can use it to show descriptive text while the video is playing, show advertisements, show a list of links at the end of the video where the user may want to go or display images. You can combine the content plugin with cuepoints so that you can show HTML content at various points in time during video playback.
Advertising	The Advertising plugins let you obtain live advertisements from various video advertising companies. There are currently advertising plugins available for OpenX, LiveRail and Adotube.
Streaming	Streaming plugins let you handle a variety of sources of video streams. The simplest form of showing a video is just providing the url of the video to play, but if you want to work with live video streams, request a different video quality based on available network bandwidth, work with clustering of video servers or other aspects of reliably obtaining and showing high quality video over the internet, you will definitely want to use a streaming plugin. We have various streaming plugins available which can be found in our plugin section.

Plugin (JavaScript)

A JavaScript Plugin is different from a Flash plugin. No Flash object is involved; however, it does bring new objects into Flowplayer that you can specify via the configuration. There are several standard JavaScript plugins available, or you can write your own, without needing to know Flash programming.

+ show list of JavaScript plugins

Configuration and JavaScript

Note that the configuration is static, that is, you tell a player once how to display and behave. If you want to change that while the player is active, you must use JavaScript. Flowplayer has an extensive JavaScript API that lets you interact with the user and respond to events in the video stream. The beauty is that you even can supply the small snippets of JavaScript for that in the configuration!

You will generally want to do two things: change a setting of a player or respond to an event in the player. For the first, you change a property of the object, often through a so-called "setter" function that shields the property from invalid values; for the second, you provide a small function that handles the event. The following example shows an event listener provided in the configuration that changes a property when called:

<script>
flowplayer("player", "flowplayer.swf", {
    onLoad: function() {	// called when player has finished loading
        this.setVolume(30);	// set volume property
    }
});
</script>

Supplying the configuration

A Player is always installed on the HTML page with a call to the flowplayer() function within a <SCRIPT>...</SCRIPT> tag. Here is a complete example:

<html>
<head>
    <script src="flowplayer-3.1.4.min.js"></script>
</head>
<body>

<div id="player" style="display:block;width:425px;height:300px;"></div>
<script>
    flowplayer("player", "flowplayer.swf", ...);
</script>

</body>
</html>

In this example the three dots represent where you supply the configuration. This argument, in its simplest form, can be a string specifying the URL of the video to play, or it can be an object that has as its properties the configuration options and their values.

The most common way to supply this object is to write it in JavaScript Object Notation, abbreviated as 'JSON'. There are various ways in which you can provide this third argument: you can write a JSON object directly as the third argument, you can assign it to a variable, you can store it in an external JavaScript file (.js) or you can intelligently assemble it at run-time using actual information.

If you know about JSON or have just quickly read about JSON, you know that an object in JSON can contain other objects. That is exactly what you use to set the configuration options of the various objects that Flowplayer is made of.

Here is what a more complex configuration in JSON can look like:

<script>

flowplayer("player", "flowplayer.swf", {		// supply the configuration

    clip : {			// Clip is an object, hence '{...}'
        autoPlay: false,
        autoBuffering: true,
        baseUrl: 'http://blip.tv/file/get/'
    },

    playlist: [			// playlist is an array of Clips, hence [...]
        'KimAronson-TwentySeconds58192.flv',			// simple playlist entry: video
        'KimAronson-TwentySeconds59483.flv',
        {url: '/demos/plugins/fake_empire.mp3', duration: 25}	// small object as entry
    ],

    plugins: {			// load one or more plugins
        controls: {			// load the controls plugin
            url: 'flowplayer.controls-tube-3.1.0.swf',	// always: where to find the Flash object
            playlist: true,				// now the custom options of the Flash object
            backgroundColor: '#aedaff',
            tooltips: {				// this plugin object exposes a 'tooltips' object
                buttons: true,
                fullscreen: 'Enter Fullscreen mode'
            }
        }
    },

    onFinish: function() {		// set an event handler in the configuration
        alert("Click Player to start video again");
    }
});
</script>

Player embedding

Flowplayer is a regular Flash component just like any other Flash component. It is embedded on the page with options provided to Flash.

The Flash configuration is the second argument in the call of flowplayer(). As with the third argument, this configuration can be a simple string that gives the url of the Flash object to load, or it can be a more complex object with options for the Flash embedding. Normally Flowplayer creates a default Flash configuration that it uses to embed the Flash player object, but you can add options or override Flowplayer's defaults.

Flash embedding is discussed in more detail in Player configuration.