This is a message.

Basics

The Flowplayer JavaScript API provides its users with an easy-to-use, yet powerful way to control one or more Flowplayer instances on a html page. Flowplayer consists of two parts: the flowplayer swf object, that is a wrapper around a Flash object, and a JavaScript library that translates the easy-to-use api commands into the more complex interaction with the Flowplayer swf object (that in turn controls the Flash object).

The Flowplayer JavaScript API is not just a flat list of functions. It is truly Object Oriented, which means that we provide you with objects that have properties and methods, and those methods can return other objects. And all the time you are communicating with a real Flash object. This approach is not seen very often in the Flash world but to our experience it surely makes your life easier!

Read the section on Object Orientation to get acquainted with our way of writing the examples.

(latest API version 3.2.13)

In this section:

flowplayer() and $f()

When you have included flowplayer.js in your page, you have the flowplayer() function available. It is the starting point for all Flowplayer activities and it is used to both create and access Flowplayer instances. A handy shorthand is $f(), which is a reference to the flowplayer() function and which can be used as a synonym. This shorthand is frequently used in this site's examples. These two functions is everything the Flowplayer JavaScript API needs to make available. Here are few examples of how to use this function.

// install flowplayer inside a DIV with id "player" and make it play
// "my-video.flv".
$f("player", "flowplayer.swf", "my-video.flv");
 
// get a handle to the player just installed and call its method
// "getVersion"
$f("player").getVersion();
 
// get a handle to the first player on the page and start the clip
$f(0).play();
 
// get a handle to the first player and stop it
$f().stop();
 
// loop through all players on the page
$f("*").each(function() {
console.info(this.getVersion());
});

JavaScript

flowplayer.js uses our flashembed tool to embed the Flowplayer Flash component on the page. Flashembed provides many crucial Flowplayer functionalities such as events, basic API and handling multiple instances. Although the script is rich in features, it weighs only 5.5 kb when minified or gzipped.

Flowplayer objects

Here are the core objects that you work with when scripting Flowplayer:

Player

When accessing player instances on a page with the flowplayer() function, Player objects are returned. You can think of it as a DVD player with playback buttons such as start, stop and pause.

Clip

A Clip object can be though of a as single movie in the Player. It contains information about the movie such as duration and creation date. You can access clip objects using the getClip() function (method) of the Player object.

Playlist

A playlist in Flowplayer is not really an object; it simply is an array of clips. A Player always has a playlist, al be it empty. This playlist has one special entry, the common clip, whose properties apply to all clips of the currently active playlist.

Plugin

Represents a Flash plugin inside the Player. You can obtain a handle to a plugin via the getPlugin() method of the Player object.

Configurations

A configuration is the set of initial parameters that you provide when creating a Player. It can define such things as the clip(s) to play, background color etcetera. The minimum configuration is the clip to play (a string). If you give it as an object, it can contain information about the clips to load, controls to load and various player settings. You can provide such a configuration for example as a json object. Example:

$f("player1", "flowplayer.swf", {
clip: {
url: 'KimAronson-TwentySeconds59483.flv',
autoPlay: true,
autoBuffering: true
},
plugins: {
controls: null
},
onLoad: function(){
alert("player loaded");
}
});

JavaScript

See also the configuration section.

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 onBeforeVolume event of a Player informs you the volume is going to change, e.g. because the user moves the volume slider, and your function can decide that at this time of day (night) it would be too loud and you limit the volume.

The event listener (your function) receives as its this variable a reference to the current object on which the event occurs.

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

Setting event listeners

To set an event listener on an object, you can provide the listener in its configuration when creating the player, or you can set it any time later. The following two examples show this:

/ setting an event listener in the initial configuration /
$f("player1", "flowplayer.swf", {
clip: {
url: 'KimAronson-TwentySeconds59483.flv'
},
onLoad: function(){
alert("player loaded.");
}
});

JavaScript

To set an event in run time, you call the event name as a function of the object, for example:

/ setting an event listener in run time /
$f().onLoad(function() {
alert("player loaded!");
});

JavaScript

You can set more than one event listener on the same event of the same object. You cannot provide an additional listener in the configuration because the second definition will replace the first definition, however, you can set an additional listener in run-time with the $f() function, as in the second example above.

Each of these on-functions return the current object so you can simply place a dot and give the next event listener, and so on (method chaining), for example:

$f().onVolume(function(level) {
alert("volume level is now " + level);
}).onFullscreen(function() {
alert("player went fullscreen");
});

JavaScript

JavaScript plugins

JavaScript plugins are JavaScript functions that you register with flowplayer and that are from then on available for your use as if they were flowplayer methods. All JavaScript plugins are registered with the addPlugin() method of flowplayer as follows:

$f.addPlugin("fly", function(top, left, speed) {
// 'this' points to the Player instance
var version = this.getVersion();
 
// return the Player to enable the plugin and method chaining
return this;
});

JavaScript

After registering the plugin you can use it through the Player object, as follows:

$("myPlayer").fly(10, 30, 500).load();

JavaScript

Internally this method attaches your plugin to the Player's prototype object. Take care that your plugin's name does not conflict with already loaded plugins or with Player methods, or you cannot access your plugin. You can read more about writing JavaScript plugins here.

jQuery support

jQuery is a general purpose JavaScript library aiming to help with common browser incompatibility issues. In addition it has a fantastic query language that you can use to select elements on the page. Flowplayer has support for the jQuery language. jQuery skills are definitely not needed when using Flowplayer but if you are accustomed to using jQuery (like us) then you can do things like:

/ select all links with .flv suffix and make them playable with
* flowplayer
/
$("a[href*=.flv]").flowplayer(
"flowplayer-3.2.18.swf"
);

JavaScript

See the player's jQuery support for details.

About our Object Orientation

Our Object Oriented way of developing the JavaScript API and the Flowplayer object makes life much easier for the end-user of the API. For one thing, although internally we use lots of different object types and special methods, we only expose one function, the flowplayer() function and its shortcut alias $f(). Through this function you can access all objects of Flowplayer that are of interest to you.

The following aspects of JavaScript are frequently used in our documentation and examples.

JavaScript Object Notation (json)

A notation often used in the examples on this site (and in our own code) is the JavaScript Object Notation, abbreviated to 'json'. With this notation you can specify complete objects as literals and pass them to functions that expect objects. The notation encloses the object between the braces { and }. Within the braces is a list of members (properties or methods), separated by commas, each consisting of a name and a value separated by a colon, for example {url: "myclip.flv", autoPlay: true}.

You can nest this object notation, so you can specify an object that has as members other objects. So the syntax of json is:

{ name:value,... }, where value can be any value, including another json object, for example

{ name:value, { name:value,...}, name:value ... }, or even a function:

{ name:value, { name:function(){...},...}, name:value ...}

The advantage of literals is that these objects and functions are unnamed, which means that you don't clobber namespaces with named functions or objects that can only collide with those of other developers' JavaScript libraries. This is one of the ways how we only need to expose one function to completely control our player.

$f("player", {src: "flowplayer.swf"}, {
clip: {
url: "myClip.flv",
autoPlay: true,
 
// attach event listener
onStart: function(clip){
alert("Clip "+ clip.url);
}
},
play: {
label: null,
replayLabel: "click to play again"
}
});

JavaScript

Note: A common error when writing json, and one that is not always flagged, is to have a comma after the last property of a json object as in:

clip:  {
autoPlay: false,
autoBuffering: true, // last property, so remove this extra comma!
}

JavaScript

This error is ignored by Firefox, and JavaScript will continue to work. However, in Internet Explorer it causes an error and JavaScript will stop working. This is why it is sometimes hard to find this error.

So, if your player works on Firefox but not on Internet Explorer because there is a JavaScript error, the first thing to check is if your configuration ends in an extra comma.

Method chaining

Where possible, the call of a method of an object returns that object. This allows us to call another method of the object by simple placing a dot and calling the method. This reduces the amount of code you have to write. For example:

// methods return objects that return objects and so on
flowplayer().setVolume(50).seek(40).onFinish(function() {
this.unload();
});

JavaScript

This example works as follows: flowplayer() returns a Player object, of which we call the setVolume() method; the setVolume() method returns the (same) Player object, of which we next call the seek() method, which returns (again) the Player object, on which we set an onFinish event listener that unloads the player once the clip has finished playing. Easy, isn't it?

The API

Finally, for those who tweak our API, we use this unnamed object way of writing JavaScript to define our API:

(function(){...})();

JavaScript

This defines an unnamed function (defined where the ellipses are between the braces { and }). That function actually is our API and has objects, methods, properties and more objects. With the brackets ( and ) around the function we tell JavaScript we have finished defining our unnamed function. But what use is an unnamed function? So next we call that function with ();. As one of the last actions of the function, it attaches the $f and flowplayer functions to the window object, so now our API is exposed for use!

For more information on this kind of advanced JavaScript programming we refer you to:

Download

The Flowplayer JavaScript API is a separate JavaScript file that you can update separately from the Flowplayer Flash component, as long as their major and minor version numbers are the same. The following files contain the JavaScript API.

FileSizeDescription

flowplayer-3.2.13.js

None

Source code

flowplayer-3.2.13.min.js

None

Minified with YUI compressor

See the download section for other downloads.