Flowplayer-JavaScript API
Global API access
Use the flowplayer function to get a global handle on the API:
flowplayer(function (api, root) { api.bind("load", function () { // do something when a new video is about to be loaded }).bind("ready", function () { // do something when a video is loaded and ready to play }); });
View standalone demo.
This anonymous callback function is provided by the Flowplayer library and is called every time a Flowplayer instance is created.
You use it to customize the default behaviour of all players on your page in a similar manner as you set global configuration options, and thus it should be called right after the flowplayer script is included on the page and before the page is loaded - before $(document).ready.
The API is provided by the first argument and it looks like this in the browser console:
Via the second argument - called root above - you can access the root or container element of the player.
Selective API access
Once the players are installed initialized you can access specific player instances like this:
// get the first player var api = flowplayer(); // same thing with jQuery api = $(".flowplayer:first").data("flowplayer"); // and the second player api = flowplayer(1); // .. with jQuery api = $(".flowplayer:eq(1)").data("flowplayer"); // use any jQuery selector api = $(".mycustom.flowplayer").data("flowplayer"); // return the API in given jQuery object api = flowplayer($(".myplayer")); // or DOM object var elem = document.getElementById("myplayer"); api = flowplayer(elem);
The installation method determines when you have access to selected APIs:
- automatic: when the DOM (document object model) is ready
- manual: after the specific instance has been initialized
Properties
During its life cycle the player is in varying states which are reflected in the the properties of the API. Here is a complete list of the API properties:
| property | default value | description |
| conf | Object | the initial configuration object |
| currentSpeed | 1 | v5.1 the current playback speed level: - 1 = normal speed less than 1 = slow motion greater than 1 = fast forward |
| disabled | False | true while the player is disabled |
| engine | the chosen video engine - either "html5" or "flash" |
|
| finished | False | true while the player is stopped at the end of the video |
| isFullscreen | False | true while the player is in fullscreen mode |
| loading | False | true while the player is being loaded |
| muted | False | true while the player is muted |
| paused | False | true while the player is paused |
| playing | False | true while the player is playing |
| ready | False | true once the player API is ready and completely loaded |
| seeking | False | true while the player is seeking |
| splash | False | true while the player is in splash state |
| video | Object | the current video object |
| volumeLevel | 0.8 | the current volume level between 0 and 1 |
Depending on the state of the player at the moment when you grab the API or call one of its methods, the full depth of its properties might be not be available.
For example: Before the player is ready video metadata such as its duration has not been processed and is therefore undefined. Similarly you cannot obtain a sensible value for the current playback position at all times. A safe way to retrieve that position would be:
var api = flowplayer(), currentPos; // get the current position, default to 0 currentPos = api.ready ? api.video.time : 0;
Video object
The video property is a reference to the currently playing video. Here is an example:
{ // the length of downloaded bytes in seconds - HTML5 only buffer: 15.43, // flag indicating whether the buffer is fully loaded buffered: false, // length of video in seconds duration: 18.85, // width of video file in pixels width: 640 // height of video in pixels height: 280, // current index in the playlist (since v5.1) index: 0, // true in case the clip is the last in a playlist (since v5.1) is_last: false, // whether the server supports random jumping on timeline seekable: true, // path to currently playing video as given on setup src: 'http://mydomain.com/video1.mp4', // current playback position in seconds time: 5.27681660899654, // video format (media type) type: 'mp4', // array of video formats sources: [ { type: 'webm', src: 'http://mydomain.com/video1.webm', suffix: 'webm' }, { type: 'mp4', src: 'http://mydomain.com/video1.mp4', suffix: 'mp4' }, { type: 'ogg', src: 'http://mydomain.com/video1.ogv', suffix: 'ogv' } ], // video filename suffix suffix: 'mp4', // absolute URL of the video url: 'http://mydomain.com/video1.mp4' }
Check out this demo which prints the entire video object to the page for inspection.
Methods
| method | description |
| disable([flag]) | disable() without argument toggles between disabled and normal API state. disable(true) disables and disable(false) enables the API. While the API is disabled loading, pausing, resuming and seeking is not possible. The progress bar is greyed out (color configurable via CSS). |
| fullscreen() | Toggles between native fullscreen mode and initial screen size. When native fullscreen support is not present the player expands to the full size of the browser window. Note: Many browsers allow this method to work only from events which are triggered by user interaction, like "click", and not for example from player events like "ready" which happen at moments undetermined by the user. |
| load([video], [callback]) | Loads the player with the specified video. See the section on the load method. |
| mute([flag]) | mute() without argument toggles between muted and normal state. mute(true) mutes and mute(false) unmutes. Since v5.2 the original volume level is remembered between page loads. |
| next() | Advances to the next clip in a playlist setup. |
| pause([callback]) | Pauses playback. |
| play(index) | v5.1 Plays the clip of a playlist specified in the zero based index argument. For example: play(0) plays the first clip. |
| play([video], [callback]) | v5.1 Alias for the load method. |
| prev() | Jumps to the previous clip in a playlist setup. |
| resume() | Resumes playback. |
| seek(time, [callback]) | Seeks to the given position in seconds. for example 13.5 The callback is executed once after the seek. |
| seek(flag, [callback]) | v5.1 seek(true) seeks 10% forward and seek(false) seeks 10% backward. The callback is executed once after the seek. |
| seekTo(position, [callback]) | v5.1 seekTo(1) jumps to 10% on the timeline, seekTo(2) goes to 20% and so on. The callback is executed once after the seek finishes. |
| seekTo() | v5.1 Seeks to last seek position. Same as pressing "." on the keyboard. |
| stop() | Pauses playback and seeks to the beginning of the video. In a poster setup the player goes back into poster state. |
| speed(rate, [callback]) | v5.1 Sets the speed level to the given rate. 1 = normal speed less than 1 = slow motion greater than 1 = fast forward The callback is executed once after the speed has changed. |
| speed(flag, [callback]) | v5.1 Changes the speed based on the speed configuration variable. speed(false) switches backward on the speed array and speed(true) switches forward. The callback is executed once after the speed has changed. |
| toggle() | Toggles between pause and play. |
| unload() | In a splash setup unloads the player back to the splash state. |
| volume(level) | Set the volume level to a decimal value between 0 (no volume) - 1 (full volume). Since v5.2 the volume level is remembered between page loads. |
All methods return the API object
Load method
The load() method initializes player and video from the splash state on demand:
api.load();
A VIDEO or OBJECT tag is created depending on browser or engine preference.
You can also change the currently playing video, load it into an existing player instance. For example:
api.load("http://mydomain.com/my/another/video2.mp4");
This will play a new video. The player will use the same video formats as specified in the initial configuration. For example, let's say the player is configured like this:
<div class="flowplayer"> <video> <source type="application/x-mpegurl" src="http://mydomain.com/video1.m3u8"> <source type="video/webm" src="http://mydomain.com/video1.webm"> <source type="video/mp4" src="http://mydomain.com/video1.mp4"> <source type="video/ogg" src="http://mydomain.com/video1.ogv"> </video> </div>
The player will attempt to use video2.m3u8, video2.webm, video2.mp4 or video2.ogv depending on the browser. All formats and filename suffixes must be the same for both videos and the videos must be delivered via HTTP. Alternatively you can explicitly specify the video formats and URLs as an array listing the video src to type mappings as objects:
api.load([ { mpegurl: 'http://mydomain.com/my/other/video.m3u8' }, { webm: 'http://mydomain.com/my/other/video.webm' }, { mp4: 'http://mydomain.com/my/other/video.mp4' }, { ogg: 'http://mydomain.com/my/other/video.ogv' } ]);
The player attempts to pick the formats in the given order depending on browser support - note the shortened spec for the application/x-mpegurl type. If the video locations do not obey a consistent filename and filename suffix naming scheme or if the videos are delivered via RTMP for the Flash engine you must use this method, the argument then cannot be a simple string.
You can provide an event callback function in the second argument. It will be called when the player is ready and the new video is about to start. For example:
api.load("http://mydomoain.com/other/video.mp4", function (event, api, video) {
// the new video is about to start
console.info(video.duration);
});
Events
Use the bind() method to execute your own JavaScript when a specified event happens in the player. For example:
api.bind("pause", function(e, api) { // do your thing });
The first argument is the event name, and the second is a callback function which is fed with 2 or 3 arguments:
- The jQuery event object. This jQuery convention allows fine grained control of the event object's properties.
- Provides a handle on the player API.
- Optional, depends on the event.
Within the callback the this keyword refers to the root element of the player - the container element. It corresponds to the currentTarget property of the first argument.
Here is a full list of events:
| event | when it fires |
| beforeseek | Before seeking starts at the origin position. Since v5.4.2 the 3rd argument gives access to the seek target position. By calling event.preventDefault() (where event is the callback's 1st argument) or returning false the seek can be stopped. |
| disable | When the player toggles between disabled and normal state. In disabled mode the UI elements cannot be used. |
| error | When an error occurred. The 3rd argument provides an object featuring the code and message properties. See the error table below. |
| finish | When playback has finished. |
| fullscreen | When the player goes to fullscreen mode. |
| fullscreen-exit | When player exits fullscreen mode. |
| load | First event in the lifecycle of the player and the video, before the configured video or a new video starts playing. Offers an opportunity to alter the video properties. The 3rd argument provides the video object featuring basic data like src, but not yet the video metadata from the server (such as duration). Returning false will prevent the video from loading. |
| mute | When the player's mute state is toggled. |
| pause | When playback is paused. |
| progress | When the playhead moves forward. Happens approximately every 250 milliseconds during playback. The 3rd argument provides the current playback position, i.e. the current value of the time property of the video object. |
| ready | When the video is fully loaded and video metadata (such as duration) becomes available from the video object which is provided by the 3rd argument. |
| resume | When playback is resumed. |
| seek | When seeking is completed at the target position. Since v5.4.2 the 3rd argument gives access to the target position. |
| speed | v5.1 When the playback speed is changed. The new level is provided by the 3rd argument. |
| stop | v5.2 When playback is stopped by the stop() method. |
| unload | When the player goes back to the splash state. |
| volume | When the volume level is changed. The new level is provided by the 3rd argument. |
Note: You will often find that Flowplayer's CSS programming capabilities provide a more elegant way to customize the player's look and feel dynamically according to its state.
Error codes
Error codes and error messages returned by the third argument of the error event are mapped the following way:
| error code | error message |
| 1 | Video loading aborted |
| 2 | Network error |
| 3 | Video not properly encoded |
| 4 | Video file not found |
| 5 | Unsupported video |
| 6 | Skin not found |
| 7 | SWF file not found |
| 8 | Subtitles not found |
| 9 | Invalid RTMP URL |
| 10 | Unsupported video format. Try installing Adobe Flash. |
Errors 1 through 4 are HTML5 video exceptions, errors 5 through 10 are Flowplayer exceptions.
jQuery
You can also bind your events directly to the jQuery object. For example
$(".flowplayer:first").bind("pause", function(e, api) { });
Internally we use the jQuery mechanism so you can use all the goodies such as binding, unbinding, one and namespaces. These work both against the API object and the jQuery object.
Engines
Currently there are two engines: html5 and flash. They share a common engine interface that is implemented as follows:
flowplayer.engine.html = function(api, root) { // perform initialization here ... // return the API return { resume: function() { }, pause: function() { } // etc... }; };
One might want to make an implementation with Silverlight for WMV support (rather not). Look for the implementation details in Github
window.flowplayer
Flowplayer function is used for accessing the player, making extensions and engines. It also has following properties
// version number var version = flowplayer.version; // default configuration for all players (v5.1) flowplayer.defaults; // global configuration to override defaults flowplayer.conf = { }; // list of engines that are supported by the browser flowplayer.engine
flowplayer.support
v5.1 flowplayer.support is a collection of properties that represent the presence of different browser features. If for example HTML5 video is supported then flowplayer.support.videois true. Here are the supported properties:
animation- HTML animation supportdataload- whether any video data can be loaded before hitting playflashVideo- flash video supportfirstframe- support for display of first video frame on loadfullscreen- native HTML5 fullscreen supportfullscreen_keyboard- keyboard support in fullscreen modehlsDuration- v5.4 whether duration of HLS stream is natively recognizedinlineBlock- CSS inline-block supportinlineVideo- v5.4 support for playing video inlineseekable- v5.4 support for seeking when video is readysubtitles- native subtitle supporttouch- touch interface supportvideo- HTML video supportvolume- volume support via JavaScript APIzeropreload- whether preload="none" completely disables preloading
Flowplayer HTML5 v5.0 extended the jQuery.support but this is now deprecated. Use flowplayer.support instead.
