Configuration

Tailor every aspect of the player to your needs

Player

A Player is installed on a webpage by a call to the flowplayer() function
or its shorthand $f(). See installation on how and where to place this
call and see the documentation of the flowplayer() function in the api,
Player creation.

Player is the top-level object. Configuration properties and event listeners
are placed in the root of the configuration; it is not a sub-object of the
configuration. Example:

flowplayer("player","http://releases.flowplayer.org/swf/flowplayer-3.2.18.swf",{buffering:false,// set a Player propertyonLoad:function(){// provide a Player event listenerthis.unmute();}});

JavaScript

This section describes the two configuration parameters of the
flowplayer() function:

Player Configuration (parameter #3)

Player properties

Specifies whether the rotating buffering animation
must be shown or not. Set this to false and, the animation
will not be shown.

debugboolean

false

Configures logging of the Flowplayer JavaScript component. This
will output all events triggered by the Flash component to the
Firebug or Safari Dev tools console.

logobject

Configures logging of the Flash component to the Firebug or Safari
Dev tools console. This configuration object has properties you
can set as described in the table below.
Example:

log:{level:'warn',filter:'org.flowplayer.rtmp.*'}

JavaScript

streamCallbacksarray

Names of NetStream callback functions to be
registered to the Player. This allows a way to listen to custom
events that can be triggered by the streaming server or a custom
application running in the streaming server.

connectionCallbacksarray

Names of NetConnection callback functions to be
registered to the Player. This allows a way to listen to custom
events that can be triggered by the streaming server or a custom
application running in the streaming server.

showErrorsboolean

true

Show errors on screen. Only set this to false when you know what
you are doing! For instance when you want to catch a specific error
gracefully in the onError event.

Properties of the log Configuration Object

log property

Default

Description

level

error

Specifies what will be logged to the console. Possible
values are: 'error', 'warn', 'info', 'debug'.
Specifying 'debug' means that everything will be logged.

filter

*

Filters the logging to certain packages of the Flash API or to
loaded Flash Plugins. The default '*' means: all packages. Some
examples:

'org.flowplayer.view.Launcher' logs what happens in the Player
launcher

If you write your own Flash plugin you can use the
Log package of our Flash API to do
your logging.

Player events

You can supply listeners for Player events in the configuration. These
are placed in the root of the configuration. See also
events in the JavaScript api.

Each Player fires events that can inform you of changes in the Player
and of actions the Player intends to take or has just taken. The event
listener receives as its this variable a reference to the current
Player instance.

Before events are marked in italics in the table below. Not all events
have a before event. The 'Cancel action' column says what will happen
when a before event listener returns false.

Event

When does it fire?

Cancel action

onBeforeClick

This event fires: after Flowplayer has been installed on the
container, and the container element is not empty (it
contains html), and it is clicked.

Flowplayer's loadmethod will save the content of the
container and replace it with the Player. The load action
will not be invoked if the onBeforeClick listener
return false. If you cancel the action, you can
later call the load() method to load the Player
in the container.

Note: when a new Player is installed, Flowplayer
will unload all other Players that were installed on
non-empty containers, that is, those Players are removed from
the canvas and their containers' original html content is
restored, unless their onBeforeUnload event listener
returns false.

Flowplayer will not be installed.

onLoadonBeforeLoad

The load action of Flowplayer follows the successful
installation of the Flowplayer Flash component in the
container. If the Player was set up with an initial splash
image (or any other HTML), this action saves the container's
current content and replaces it with the Player.

Before the load action is performed, Flowplayer first fires
the onBeforeLoad event, giving you an opportunity to defer
loading or change its behavior or splash image. Returning
false from an onBeforeLoad event listener will cancel
the load action.

The onLoad event fires after the load action has completed.
When this event fires, the Player is fully operational and all
API methods are available. It will not fire when the onBeforeLoad
event listener returned false.

Player will not be loaded.

onUnloadonBeforeUnload

Flowplayer's default unload behavior is to replace
the content of the container with the originial content.
Before Flowplayer performs this action, it fires the
onBeforeUnload event, giving you a chance to cancel
unloading. Following the unloading the onUnLoad event
fires. These events only fire when the container initially
contained html.

After the Player has been unloaded from a container that
contains html, clicking the container will (again) fire
the onBeforeLoad event.

These events will only fire when the container was not empty.

Player is not unloaded.

onMouseOver

This fires when the mouse pointer moves into the player area.

onMouseOut

This fires when the mouse pointer moves out of the player area.

onKeyPressonBeforeKeyPress

This fires when a user presses a key on the keyboard while the
Player has the focus. The code corresponding to the key which
has been pressed is provided as the first argument to the
event listener. A list of different key codes is
given here.

Default keyboard actions are ignored. (By default, the spacebar
toggles between playing and paused states, and the arrow keys
seek backward and forward.)

onVolumeonBeforeVolume

This fires when the volume level is changed (via any of
the setVolume, mute or unmute methods). The new volume
level is provided as the first argument to the event listener.

Volume level is not changed.

onMuteonBeforeMute

This fires when the player is muted.

Volume level is not changed.

onUnmuteonBeforeUnmute

This fires when the player is unmuted.

Player stays muted.

onFullscreenonBeforeFullscreen

This fires when full screen mode is entered.

Full screen mode will not be entered.

onFullscreenExit

This fires when full screen mode is exited. (Unfortunately,
there is currently no 'onBeforeFullscreenExit' event. This is
because the current implementation of Flash does not permit this
action to be cancelled.)

onClipAdd

Since 3.1.1. This fires when a clip was added to the playlist
via the addClip method. The first argument is the newly
added Clip object. The second argument is the index number
which specifies the position in the playlist. This event is not
fired when an instream clip is added.

onPlaylistReplace

This fires when the playlist is swapped out for another. This
typically happens when the play(clip) method is called and
the original playlist is replaced with a single clip playlist.
The new playlist object (an array of Clip objects) is
provided as the first argument to the event listener.

onError

This fires when an error occurs inside the player. The event
listener receives two arguments: errorCode and errorMessage,
as in the following table.

Error Codes

100

Plugin initialization failed

200

Stream not found

201

Unable to load stream or clip file

202

Provider specified in clip is not loaded

300

Player initialization failed

301

Unable to load plugin

302

Error when invoking plugin external method

303

Failed to load resource such as stylesheet or background image

Flash configuration (parameter #2)

The second parameter of the flowplayer() function specifies the
Flash embedding parameters. If you supply it as a simple string it is
treated as the src property of flashembed which defines
the path to the Flowplayer Flash component (.swf). If you want to customize
the Flash embedding, you can supply the settings as an object written in
JSON (JavaScript Object Notation).

Flowplayer uses our flashembed tool to embed the
Flowplayer Flash component on the page. This tool is included in the
flowplayer-3.2.13.min.js file and you have all its power available
such as version detection and handling of old Flash versions. All
Flash configuration options are given directly to flashembed.

Flowplayer-specific Flash properties

The required Flash version for Flowplayer is [10, 1], and this is
supplied as the default value. When a Flash version lower than 10.1
is encountered, Flowplayer attempts to use Express Install and
if the user has a version lower than 6.56 or no Flash at all, then
Flowplayer shows the default error message as specified in
this flashembed demo.

For Flash versions 10 and greater the two-member array is computed from
the first 2 digits of the Flash plugin's official version string.
For older versions the third digit is used, as the second digit is then
always 0.

expressInstall

By default, Flowplayer uses this file:
http://flowplayer.org/swf/expressinstall.swf for users who have
less than version [10, 1] but greater than [6, 56] installed.
You can skip Express Install by setting expressInstall to null.

onFail event

The Flowplayer API provides this event listener on the Flash level:

Flash Event

Description

onFail

Customizes error handling on the Flash level in its
callback function. See the example below.
Not to be confused with the onErrorPlayer event.

Flash configuration example

In the following example we supply a custom onFail listener for
Flash versions which do not support Flowplayer. On Flash versions below 10.1,
users will experience an Express Install and additionally our onFail
event listener is called, explaining the problem in an info box. The
same behaviour occurs if the container is configured with an initial
splash image.

<divid="player"class="player"style="width:425px;height:300px;"></div><divid="info"class="info"> You have Flash version 10.1 or above. Enjoy Flowplayer!</div><script>// Flowplayer installation with Flashembed parametersflowplayer("player",{

// older versions will see a custom messageonFail:function(){document.getElementById("info").innerHTML="You need at least Flash version 10.1 to play the movie. "+"Your version is "+this.getVersion();}},// here is our third argument which is the Flowplayer configuration{clip:"http://stream.flowplayer.org/KimAronson-TwentySeconds71844.mp4"});</script>

Standard Flash parameters

Note: Only change these when you have to, and if you know what you are doing.
Most of the time passing the value of the src property as string argument is
sufficient.

Property / Datatype

Default

Description

srcstring

The location of flowplayer-3.2.18.swf. May be given as full
URL, absolute path, or relative path. This property is mandatory.

bgcolorstring

#000000

The hexadecimal RGB value in the format of '#RRGGBB'. This specifies
the background color of the Player itself. It is visible for a short
moment on load before it is overlayed by the Player's canvas.

widthstring

100%

It is recommended that you do not change this setting. Instead specify
the width and height for the container element using CSS directives.

heightstring

100%

It is recommended that you do not change this setting. Instead specify
the width and height for the container element using CSS directives.

wmodestring

window

Other valid settings:

'opaque'

'transparent'

'direct' (new and as of yet unstable)

Set this to 'opaque' or 'transparent' if you want to place
HTML elements on top of the Player, for example, a dropdown menu.
Changing this property might affect playback quality. See also
Adobe's documentation on wmode.

allowfullscreenboolean

true

Allows the Player to enter Fullscreen mode.

allowscriptaccessstring

always

This enables Flash-to-JavaScript communication. Other valid settings:

'samedomain'

'never'

If you don't need this feature or are concerned about security,
set this to 'never'.

qualitystring

high

Other valid settings:

'low'

'autolow'

'autohigh'

'best'

'low' favors playback speed over appearance, and 'best' provides
the best display quality, but does not consider playback smoothness.
'high' offers the best compromise between visual and playback quality.

SeamlessTabbingboolean

false

Set this property to true to support accessibility via screen
readers. Further mandatory requirements: