This is a message.

Player

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

In this section:

Player methods

MethodReturnsDescription

addClip(clip, index)

Clip

since 3.1.1. Add's a clip to the playlist. First argument is the clip to be added which is either a URL as a string or is a clip configuration that you can specify as json object. The index argument specifies the position where clip is added in the playlist. If the clip object contains a position property then the clip is added to an existing clip as an in-stream clip. The player's playlist is extended with the new clip and the onClipAdd event is fired. All common clip properties and event listeners are preserved.

close()

Player

Closes all connections between the player and the server. This method is usually automatically called for you but in some cases you may want to do this yourself.

getClip()

Clip

Accessing objects of a Player.

getCommonClip()

Accessing objects of a Player.

getControls()

Accessing objects of a Player.

getFlashParams()

Accessing objects of a Player.

getIndex()

integer

Returns the zero-based index of the Player when there are multiple Players on the page. Remember that the index of a Player is not the same as the order in which Players occur in elements on the page. The index number is the order in which the Players were created. Example: $f("myDiv3").getIndex(); // might return '0' if you created it first

getParent()

Element

Returns the Player's containing DOM element.

getLogo()

Accessing objects of a Player.

getPlay()

Accessing objects of a Player.

getPlaylist()

Accessing objects of a Player.

getPlugin()

Accessing objects of a Player.

getScreen()

Accessing objects of a Player.

getState()

integer

Returns the state of the player. Possible values are:

  • -1: unloaded

  • 0: loaded

  • 1: unstarted

  • 2: buffering

  • 3: playing

  • 4: paused

  • 5: ended

getStatus()

Object

Returns a set of status information in a single call. Some plugins may frequently need lots of information. One such plugin is the HTML-based controls plugin. By returning state information in a single call we can greatly reduce CPU intensive Flash/JavaScript communication. The following object is returned with the following initial values:

{
bufferStart: 0,
bufferEnd: 0,
state: 0,
time: 0,
muted: [muted],
volume: [user volume]
}

JavaScript

getTime()

integer

Returns the current time, in seconds, of the current clip.

getVersion()

Array

Returns the Flowplayer version as an array. Depending on your version and whether the player is loaded or not this method returns different results. Example return value: [3, 0, 0, "free", "flowplayer.js 3.0"]

getVolume()

integer

Returns the player's current volume setting as an integer between 0-100. This returns the volume setting even if the player is muted.

hide()

Player

Makes the player hidden in a way that it keeps running. By default Flash works in a way that if you place any HTML on top of it the Flash still shows through. Any z-indexing or CSS trick won't work. This method helps you with these problems by making the Flash object invisible until it is revealed again by a call to show(). You can use the wmode Flash parameter to make Flash work like a regular HTML layer but this is not recommended because it doesn't work with all browsers and it makes Flash very slow. Use hide/show for your coolest HTML tricks.

id()

String

Returns the id of the container of the Player.

isFullscreen()

boolean

Returns true if the player is in full screen mode and false otherwise.

isHidden()

boolean

Returns true if the player is hidden and false otherwise.

isLoaded()

boolean

Returns true if the player's Flash component is loaded and the API is ready to be called, and false otherwise.

isPaused()

boolean

Returns true if the player is paused and false otherwise.

isPlaying()

boolean

Returns true if the player is playing and false otherwise.

load([callback])

Player

This call will save any html or splash image that was in the container and loads a Player flash component that replaces the html or splash image. This may take some time depending on the user's bandwidth and whether Flash is cached on the user's browser or not. If the container contained html or a splash image, then the player will not be shown until it is clicked; the click will issue an onBeforeClick event. The optional callback argument specifies a callback method that is invoked when loading has completed. This method is called only once and is not stored for future loads. This method does nothing if the onBeforeLoad event listener returns false. This method tries to unload all other players by calling their unload method. If you don't want that, define an onBeforeUnload listener for your other players that return false to cancel the unloading.

loadPlugin(name, url, [properties], [callback])

Plugin

Loads a Flash plugin in the player. name specifies a unique name for the plugin that you can later use in calls to getPlugin(). If a plugin exists with a same name this call is ignored. url is an absolute or relative path to the swf file. If you supply only a filename without a path the player tries to load the plugin from the same location where the flowplayer.swf file was originally loaded from. properties (optional) object to configure the plugin. The contents of this properties object is dependent on the plugin to be loaded. callback (optional) function to be called after the plugin is loaded. The callback's this variable references the current Plugin instance.

mute()

Player

Mutes the player. The difference between this and setVolume(0) is that the original volume level is remembered and resumed when unmute() is called.

pause()

Player

Pauses the currently playing clip.

play()

Player

Starts playback of the current clip.

play(index)

Player

Starts playback of the clip specified by index, the zero-based index of the clip in the Player's playlist array.

play(clip)

Player

Plays the clip specified by the clip argument. clip is either a URL as a string or is a clip configuration that you can specify as json object. The player's playlist is replaced with a new playlist consisting of this single clip and the onPlaylistReplace event is fired. All common clip properties and event listeners are preserved.

play([clip, clip ...])

Player

Play the playlist specified by the array argument. Each clip in the array is either a URL as a string or is a clip configuration that you can specify for example in json. The player's playlist is replaced with a new playlist consisting of these clips and the onPlaylistReplace event is fired. All common clip properties and event listeners are preserved.

play(clip, instream)

Player

since 3.1.1. Plays the clip specified by the clip argument as an in-stream clip. This means that the current clip pauses on the background and after the in-stream clip finishes the current clip is resumed. First argument is the clip URL or object to be played and second argument must be true indicating that we are playing an in-stream clip. You can take a look at this demo which uses this method. Note that to play an RTMP clip with this method a dedicated RTMP plugin must be added to the plugin configuration with the mandatory label rtmpInstream.

reset(plugin)

Player

If you have moved your screen or controlbar, this call moves them back to their original positions and size. You can optionally specify an array of plugin names (strings) that you also want to reset to their original state. For example: $f().reset(['content', 'controls']).

resume()

Player

Resumes the currently paused clip.

seek(seconds)

Player

Seeks to the specified time of the current clip, in seconds. If using default URL-based streaming provider then the buffer must have loaded to the point of seeking. When using streaming server this is not required.

getClip()

Accessing objects of a Player.

getPlaylist()

Accessing objects of a Player.

setVolume(integer)

Player

Sets the volume. Accepts an integer between 0-100. 0 is totally muted.

show()

Player

If the player was hidden with a call to hide(), show() will make it visible again.

startBuffering()

Player

Starts downloading video data from the server.

stop()

Player

Stops the current clip.

stopBuffering()

Player

Stops downloading video data from the server.

toggle()

boolean

Toggles the state between play and pause. Returns the new state of the player, with true as playing and false as paused.

toggleFullscreen()

boolean

since 3.1.1. Toggles the state between fullscreen and normal mode. Returns the new state of the player, with true as being in fullscreen mode and false as not. Fullscreen mode cannot be changed from outside the player. Look for this demo for the details.

unload()

Player

Unloads the player Flash component and replaces it with the original HTML content of the container element. This method does nothing if there was no HTML in the container. Otherwise it first fires an onBeforeUnload event, and if that returns false then the method does nothing and returns false. After unloading the onUnload event is fired.

unmute()

Player

Resumes the volume level that was set before the player was muted.

Accessing objects of a Player

MethodReturnsDescription

getClip()

Clip

Returns the current clip.

getClip(index)

Clip

Returns the clip from the playlist specified by index. For example getClip(0) returns the first clip from the playlist.

getCommonClip()

Clip

Returns the common clip object with properties common to all clips of the playlist. If you add event listeners to this object, they will be common to all clips of the playlist.

getPlaylist()

[Clip,...Clip]

Returns the playlist of the player as an array of Clip objects.

getControls()

Plugin

Returns the first controlbar that is configured for the player. Shorthand for getPlugin("controls").

getConfig(copy)

Object

Returns the active configuration as an object. You can modify this object causing the configuration to change, however, it is recommended that you only use the API methods after setting the initial configuration. Use for example the clip's update() method to change the clip's settings. If you supply true as the first argument you'll get a copy of the configuration that you can safely tweak and play with.

getFlashParams()

Object

Returns the configuration object that was supplied upon setup for flashembed. Properties of this object affect the way how Flash is embedded. You can alter these settings before the player gets loaded. See the Flashembed demo for an example.

getLogo()

Plugin

Returns the logo. Shorthand for getPlugin("logo") - commercial version only.

getPlay()

Plugin

Returns the play button. Shorthand for getPlugin("play"). Play cannot be loaded on demand with the loadPlugin() method.

getPlugin(name)

Plugin

Returns the plugin with the given name. You name a plugin in the configuration or via the loadPlugin() method. There are also the following predefined names that you can use:

  • "controls" - returns the controlbar. Same as getControls().
  • "logo" - returns the logo. Same as getLogo() - commercial version only.
  • "play" - returns the play button. Same as getPlay().
  • "screen" - returns the video screen. Same as getScreen().

getScreen()

Plugin

Returns the video screen. Shorthand for getPlugin("screen"). Screen has the same public methods as other plugins have so it can be resized, moved and animated but it cannot be loaded on demand with the loadPlugin() method.

setClip(clip)

Player

Replaces the current playlist with a playlist consisting of a single clip. clip can be either a string representing a relative or absolute URL, or can be a Clip configuration object that you can specify for example in json. All common clip properties and events are preserved. After this an onPlaylistReplace event fires.

setPlaylist([clip,...])

Player

Replaces the current playlist with a new one. The playlist is given as an array of clips that can be either stings (urls) or Clip configuration objects that you can specify for example in json. All common clip properties are preserved. After this an onPlaylistReplace event fires.

Player events

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.

EventWhen 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 load method 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.

onLoad
onBeforeLoad

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.

onUnload
onBeforeUnload

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.

onKeyPress
onBeforeKeyPress

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.)

onVolume
onBeforeVolume

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.

onMute
onBeforeMute

This fires when the player is muted.

Volume level is not changed.

onUnmute
onBeforeUnmute

This fires when the player is unmuted.

Player stays muted.

onFullscreen
onBeforeFullscreen

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

Playlists

A playlist in Flowplayer is simply an array of clips. You can specify a playlist in the initial configuration, or you can set it with a call to the setPlaylist() of the Player object:

/ Set a playlist in the initial configuration /
$f("player", "flowplayer.swf", {
// playlist with two entries
playlist: [
// playlist entry as a string means the url
'http://stream.flowplayer.org/KimAronson-TwentySeconds58192.flv',
 
// playlist entry with custom duration
{
url: 'http://stream.flowplayer.org/KimAronson-TwentySeconds59483.flv',
duration: 10
}
],
 
// show playlist buttons in controlbar
plugins: {
controls: {
playlist: true
}
}
});

JavaScript

/* Set a playlist in run time */
$f("player").setPlaylist( [
// playlist entry as a string means the url
'http://stream.flowplayer.org/KimAronson-TwentySeconds58192.flv',
 
// playlist entry with custom duration
{
url: 'http://stream.flowplayer.org/KimAronson-TwentySeconds59483.flv',
duration: 10
}
]);

JavaScript

Common Clip

Common clip is an important concept in Flowplayer. It specifies properties and event listeners that are common to all clips in the playlist. For example, you can set one onStart event listener that will be called for each clip that starts playing in the playlist. Internally the common clip is a special entry of the playlist array with index -1. When replacing the playlist, this entry is preserved. Each clip can also have its own value for the properties and have own event listeners. These override those of common clip. You can also assign event listeners to both the common clip and the playlist entries. In this case playlist events are called before the common clip events. If you return false from the playlist event then common clip event will not be called. This mechanism is also called "event bubbling". See our event bubbling demo.

Examples:

/ Set common clip properties and event listeners in the initial
* configuration
/
$f("player", "flowplayer.swf", {
// common clip: these properties are common to all clips of the
// playlist
clip: {
duration: 5,
 
// set a common clip event listener
onStart: function(clip) {
alert("Playing");
}
},
 
// onStart event is called for both of these clips
playlist: ['video1.flv', 'video2.flv']
});

JavaScript

/* Set common clip properties and event listeners in run-time */
 
// register event listener with common clip
$f("player").onStart(function() {
alert("Playing");
});
 
// this does the same thing
$f("player").getCommonClip().onStart(function() {
alert("Playing");
});
 
// if you want to register a listener to a specific clip *only*
$f("player").getClip(1).onStart(function() {
alert("Playing");
});

JavaScript

It is important to note that internally the playlist is always created and that it has zero or more entries. If you define a clip object and no playlists, then that clip's properties become the properties of the common clip and the clips's url is placed in the first (and only) playlist entry. When modifying the playlist programmatically using the play(clip) method, all the common clip properties are preserved.

See also common clip configuration.