Flowplayer JavaScript API Object Oriented model of the player
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
| 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(); |
||||||||||||||
| getParent() | Element | Returns the Player's containing DOM element. | ||||||||||||||
| 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:
|
||||||||||||||
| 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:
|
||||||||||||||
| 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 an 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 the player is full screen or if there was no html in the container. This method first fires an onBeforeUnload event and if that returns false then the method does nothing and returns false. Following the unloading an onUnload 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. This is just a shorthand for the equivalent call 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. |
| 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:
|
| getScreen() | Plugin | Returns the video screen. This is just a shorthand for the equivalent call 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 gray. 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 action 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 setup 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 when 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 addClip method. First argument is the newly added Clip object and second argument is the index number that 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 follows:
|
|||||||||||||||||
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://blip.tv/file/get/KimAronson-TwentySeconds58192.flv',
// playlist entry with custom duration
{url: 'http://blip.tv/file/get/KimAronson-TwentySeconds59483.flv', duration: 10}
],
// show playlist buttons in controlbar
plugins: {
controls: {
playlist: true
}
}
});/* Set a playlist in run time
*/
$f("player").setPlaylist( [
// playlist entry as a string means the url
'http://blip.tv/file/get/KimAronson-TwentySeconds58192.flv',
// playlist entry with custom duration
{url: 'http://blip.tv/file/get/KimAronson-TwentySeconds59483.flv', duration: 10}
]);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']
});/* 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");
});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.