Javascript Api

Use Flowplayer Javascript API to make the player interactive

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
Accessing objects of a Player
Player events
Playlists
Common clip

Player methods

Method	Returns	Description
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 instream 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 instream clip. This means that the current clip pauses on the background and after the instream 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 instream clip. You can take a look at demo that uses this method.
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

Method	Returns	Description
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.

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