This is a message.

Scripting Overview

This document introduces you to the basics of Flowplayer scripting. The following items are covered.

Loading players

When Flowplayer is set up with an initial splash image (or any other HTML content) as follows:

<a id="player" href="my-video.flv">
<img src="splash.jpg"/>
</a>

HTML

The player is not loaded until the containing wrapper element is clicked. Before that Flowplayer API is not fully usable and you cannot use all of the available API methods. Most notably you don't have access to plugins. If you want to do things right after player is loaded you have to place your JavaScript inside onLoad event in configuration or you can do it programmatically as in here.

// create our example player
var player = $f("player", "/path/to/flowplayer-3.2.18.swf");
 
// this function is called when splash image is clicked or player's
// load() method is called
player.onLoad(function() {
// this is the place to start scripting with Flowplayer
alert("player loaded");
 
// this- variable points to the player's API
this.getScreen().animate({width:300, height:200});
});

JavaScript

You can add as many onLoad handlers as you want. Another way of loading is to do it programmatically using an API call load(). This function accepts a function argument that will be called when player is loaded. Here is an example.

// you can also supply your onLoad handler as argument into load() method.
player.load(function() {
alert("player was loaded programmatically");
});

JavaScript

onLoad example

Click on the player to see onLoad in action. Below the video is the embedding script.

$f("loadTest", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf").onLoad(function() {
// a silly example where we move our controlbar to the center
this.getControls().animate({top:'50%'}, 3000);
});

JavaScript

As you saw it was possible to add this onLoad function into the player before the actual Flash component is embedded into the page. The same goes for other event listeners as well. This way all JavaScript plugins and functions can initialize themselves before the player is loaded.

Here is a full list of functions that can be called before player is loaded.

  1. registering event listeners: onLoad, onStart, onFinish, onCuepoint ...

  2. access to clips and playlists: getClip, getPlaylist

  3. these API methods: id, getVersion, load, isLoaded, getState, play

For example:

Accessing players

Flowplayer function returns a handle to the player instance when it is installed

// get player instance upon installation
var player = flowplayer(
"playerDiv", "/path/to/flowplayer-3.2.18.swf", "my-movie.flv"
);

JavaScript

When you have a player instance in your hands you'll have an access to its programming interface (API) which is documented here. So for example if you want to make a HTML button that uses api method pause you'll write following code.

<!--  get first flowplayer and pause it  -->
<button onClick="player.pause();">Pause</button>

HTML

You can also retrieve players after they have been created in following ways

// get first player that is either loaded or first on the page
var player = $f();
 
// get a specific player with index argument. argument is given in
// order they are created
player = $f(1);
 
// or you can use container's id if it's supplied
player = $f("myDiv");
 
// you can always use the long name which is more descriptive
player = flowplayer();

JavaScript

Example

BTW: these players were installed by the following jQuery fuelled code. More about using jQuery later.

// select all players under "multiple" element
$("#multiple a.player").flowplayer("http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
// each clip comes from blip.tv
clip: { baseUrl: 'http://stream.flowplayer.org/' },
 
// disable controls from each player
plugins: { controls:null }
});

JavaScript

Accessing all players

If you want to do operations to all players you can use a special $f("*") call that works as follows:

$f("*").each(function() {
// this- variable is a pointer to a Player instance in current iteration
this.onLoad(function() {
 
// now each player on the page does this when it's loaded
alert("player loaded: " + this.id());
});
});

JavaScript

Players have id's player0, player1 and player2 respectively. If you have Firebug command line in your hands you can play with all available API methods against these player instances.

Using events

Most of the time you will supply your event functions to upon configuration. That is the easiest way. However here we discuss about adding event listeners using Flowplayer API. It allows you to add multiple listeners of the same event type such as onStart. This makes it possible to have many scripts and plugins that don't know about each other to add their own event listeners wihtout disturbing each other.

In this example we will get our player and add onStart event listener to the common clip.

This box will be updated in onStart event.
$f("eventTest").onStart(function(clip) {
/* inside events 'this' variable points to the player API */
 
// print some information to the info box below the player
var info = "Flowplayer " + this.getVersion()[0] + ", playing " + clip.url;
$("#eventInfo").html(info).addClass("petrol");
});

JavaScript

Of course you can do lot's of usefull stuff inside event functions other than this silly example. You can send notification to Google Analytics, launch plugins, manipulate surrounding HTML document (DOM), use powerfull libraries such as jQuery, communicate with server using AJAX… it's all about your imagination (and coding skills).

Here is an example listener that will send a notification to Google Analytics that a clip was started.

$f("analyticsTest").onStart(function(clip) {
// send clip's URL to Google Analytics
pageTracker._trackPageview(clip.url);
});

JavaScript

And here is an example that will make the player more visible on the page using our jquery.expose tool.

$f("exposable", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
plugins: {controls:null}
}).onStart(function() {
$(this.getParent()).expose();
});

JavaScript

This was just a very brief introduction to events and there are milloins of way you can use them. Full list of events is given here.

Using Flash plugins

Flash plugins are usually loaded upon configuration. You can also load them programmatically with loadPlugin method as follows.

Loading plugin dynamically

This is how plugin loading was achieved. We used cuepoints to do the timing.

// create Flowplayer instance
var player = $f("pluginLoad", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf");
 
// on 3rd second load a content plugin and display it
player.onCuepoint(3000, function(clip) {
this.loadPlugin(
"content", "flowplayer.content-3.2.9.swf",
{
html: 'This clip is : ' + parseInt(clip.duration) + ' seconds long'
}
);
});

JavaScript

This way you will download the plugin only when it's really needed. In typical scenario you want to show suggestions to other video clips at the end of the clip. You have a specific suggestions plugin for that task and by using loadPlugin method at clip's onFinish event you will only load it if clip is really watched to the end.

Accessing plugins

When you have configured your player with plugins you'll use getPlugin method to access them. In this example our plugin is configured in the player and it is shown on the first second of the playback

var player = $f("pluginAccess", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
plugins: {
content: {
url: "flowplayer.content-3.2.9.swf",
height: 100,
 
// plugin is initially hidden
display: 'none'
}
},
 
clip: {
 
// on third second get access to the plugin and reveal it
onCuepoint: [3000, function(clip) {
 
// get access to a configured plugin
var plugin = this.getPlugin("content");
 
// make it visible and set its content from an existing
// HTML element
plugin.show(1000).setHtml($("#justSomeTalk").html());
}]
}
});

JavaScript

Just some talk. As you may have noticed Flowplayer API is not just a flat list of functions. We have objects with methods and those methods can return other objects. And all the time we are communicating with a real Flash object. This kind of programming has not been very common in Flash world.

Plugin animations

In previous example we used fadeIn method to change plugin's transparency, but you are allowed to change multiple display properties in the same way and at the same time. Here is a simple example.

// animate "content"- plugins opacity and height in 600 milliseconds
$f().getPlugin("content").animate({opacity:0.9,height,200}, 600);

JavaScript

If you want to do something after animation finishes you can supply a callback function as third argument. (Or second argument if you are happy with the default speed 500 ms).

$f().getPlugin("content").animate(
{
opacity:0.9,
height,200
},
600,
function(player) {
// animation is finished. 'this' variable points to the
// current plugin instance
console.log("animation finished for plugin " + this.name);
 
// current player is supplied as the argument
player.stop();
}
);

JavaScript

There are example animations in our demo page.

Any flash component as plugin

It's very interesting to realize that you can use any displayable Flash component that is coded with ActionScript 3 as a Flowplayer plugin. Here is an example of a random swf file clock.swf I found from the net.

// install player normally
$f("clockPlayer", {
bgcolor:'#112233',
src:"http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf"
}, {
// place a "clock" plugin that is just a Flash component found
// from the web
plugins: {
clock: {
url: '/media/swf/clock.swf',
 
// all display properties work for any Flash component
width:220,
height:220,
top:10,
right:20,
 
// styling properties do not work
border:'1px solid #ffffff'
}
}
});

JavaScript

Public methods

Flash plugins may have methods that are usable via JavaScript. Those methods are documented in Plugin's own documentation. Our content plugin for example has a public method called setHtml which will replace current HTML with a new one. You can call that method just like any other plugin's method. It is really that simple!

In this example we will call setHtml method anytime user moves her mouse over and out of the video screen.

$f("methodTest", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", {
plugins: {
content: {
url: 'flowplayer.content-3.2.9.swf',
html: 'move your mouse here to see setHtml() method in action',
 
// content specific event listeners and methods
onMouseOver: function() {
this.setHtml('Mouse over');
},
 
onMouseOut: function() {
this.setHtml(
'Mouse moved away. Please visit Finland someday.'
);
}
}
}
});

JavaScript

All content plugin's methods are documented here.

Using jQuery

jQuery is a general purpose JavaScript library aiming to help with common browser incompatibility issues. All jQuery specific methods are documented in JavaScript API.

Here are some examples that show you the possibilities what you can do with jQuery.

jQuery selectors

jQuery has a fantastic query language that you can use to select elements from the page. Flowplayer has a support for that language and here are some examples.

// select all links that has a .flv suffix and make them playable with
// flowplayer.
$("a[href*=.flv]").flowplayer("/path/to/flowplayer-3.2.18.swf");
 
// load content plugin to the first player that is contained under div#videos
$("div#videos a.flowplayer:first").flowplayer().each(function() {
this.loadPlugin("content", "plugins/flowplayer.content-0.1.0.swf", {
top:10, left:10, width: 200, height: 50
style: '/css/content.css'
});
});

JavaScript

AJAX actions

jQuery makes it easy to make AJAX calls in cross- browser manner. Here are few examples.

// make a server call each time a clip starts or finishes
$f("#myPlayer").onStart(function(clip) {
$.get("statistics.php?action=start&clip=" + clip.url);
}).onFinish(function(clip) {
$.get("statistics.php?action=finish&clip=" + clip.url);
});

JavaScript

Here we use AJAX to load following flowplayer configuration from the server.

{
"canvas": {
"backgroundColor": "#1f5230",
"backgroundGradient": [0, 0.2, 1]
}
}

JavaScript

Here is the working example and after that you can see how this all is accomplished using jQuery. We should see a green background gradient in the canvas.

<a id="ajaxPlayer" href="http://stream.flowplayer.org/flowplayer-700.flv" class="player plain">
<img src="/media/img/player/btn/showme.png" style="margin-top:50px" />
</a>

HTML
// perform this action when wrapper is clicked.
$("#ajaxPlayer").click(function(evt) {
// load Flowplayer configuration from server
$.getJSON("/media/js/demos/ajax.config.js", function(json) {
// and create a player instance when file is loaded
$f("ajaxPlayer", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", json).load();
 
});
 
// prevent default action from occurring when anchor is clicked
evt.preventDefault();
});

JavaScript

Under tricks and tips you'll see an alternate way of loading external configuration without jQuery.

Tricks and tips

Waiting for the DOM to load

JavaScript beginners tend to do following

<script>
var test = document.getElementById("test");
</script>
 
<!-- we want to get access to this div -->
<div id="test"></div>

HTML

causing the test variable to be null because the DIV has not been loaded at the time the script is run. A (poor) workaround for this is following:

<script>
window.onload = function() {
// now test is set, because document is loaded
var test = document.getElementById("test");
}
</script>
 
<div id="test"></div>

HTML

A major drawback in window.onload is that it is the last function called after everything else has been downloaded, including images. Secondly there can be only one load event on the page. Here are two good solutions.

// use flashembed's method. this is usable if you have flowplayer.js included
flashembed.domReady(function() {
// do stuff
});
 
// use jQuery's method. this is preferred if you are using jQuery
$(function() {
// do stuff
});

JavaScript

It is recommended that you wrap all your scripts that you want to execute upon page load inside previous code blocks. You will find more about this important topic from here.

The flowplayer function takes care of these issues automatically so following will work

<script>
$f("test", "http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf", "my-movie.flv");
</script>
 
<!-- flowplayer get's installed here -->
<div id="test"></div>

HTML

This was implemented so that our installation documents are easier to gasp. However it is recommended to use those previous domReady functions so that every other script on your page will work correctly.

Overriding click action

Sometimes you want something cool to happen when user clicks on the splash image before starting the playback. In this jQuery example we will make a custom animation to the container before loading the player.

// myPlayer is already configured. here we cancel its default click behaviour
$f("myPlayer").onBeforeClick(function() {
return false;
});
 
// here we use custom jQuery to make custom click event
$("#myPlayer").click(function() {
// remove nested play button
$(this).find("img").remove();
 
// perform resizing animation in 3 seconds
$(this).animate({width:425, height:298}, 3000, function() {
// when animation finishes we will load our player. voila.
$f(this).load();
});
});

JavaScript

Here is this code in action.

You can also override click action without jQuery by using standard element.onclick event.

Sometimes you may find yourself confused with those dollar signs all over the place. Remember that instead of $f you can always use flowplayer and instead of $ you can use jQuery. This makes your code more readable but you have to make more typing.