Flowplayer JavaScript API Object Oriented model of the player
Clip
A Clip object can be though of a as single movie in the Player. It contains information about the movie such as duration and creation date. You can access clip objects using the getClip() function (method) of the Player object, or you can set event listeners on clips and get the Clip object passed as the first argument to your event listener.
In this section:
Clip properties
The following Clip properties are read-only.
| name | type | description |
|---|---|---|
| completeUrl | String | Clip's complete URL. This is the concatenation of the clip's baseUrl property and the clip's url property. Currently baseUrl is undefined if you did not set it. |
| fullDuration | number | Clip's full duration, in seconds and fractions of a second, as taken from the movie file's metadata. This differs from the clip's duration property given in the configuration, which will stop playback after the specified duration. |
| height | integer | Calculated height for the video, in screen pixels, after scaling and screen dimensions have become known. |
| index | integer | Index of the clip in the playlist. 0 is the first clip, 1 is the second and so on. The index of common clip is -1. |
| isInStream integer |
true | since 3.1.1. This property is true if the clip is contained within an instream playlist. |
| isCommon | boolean | true if the clip is a common clip and false otherwise. |
| metaData | Object | A large collection of information about the clip. The information differs between an originating server and a movie file. |
| type | String | The type of a clip. Possible values are "image", "video" and "audio". |
| width | integer | Calculated width for the video, in screen pixels, after scaling and screen dimensions have become known. |
The following Clip properties are read-write. Changes are not active until after the Clip's update() method has been called. Changes that are made to the actively playing Clip become active on the next play.
| property / datatype | default | description |
|---|---|---|
| accelerated boolean |
false | Flag indicating whether Flash 9 (and above) hardware-accelerated full screen mode should be used. |
| autoBuffering boolean |
false | Flag indicating whether loading of clip into player's memory should begin straight away. When this is true and autoPlay is false then the clip will automatically stop at the first frame of the video. |
| autoPlay boolean |
true | Flag indicating whether the player should start playback immediately upon loading. |
| baseUrl string |
The first part of the URL of the video's location. This property is prepended in front of the url property (for relative URLs). If not specified, the video file is loaded from the same directory as the enclosing HTML file.
|
|
| bufferLength integer |
3 | The amount of video data (in seconds) which should be loaded into Flowplayer's memory in advance of playback commencing. |
| connectionProvider string |
Sets a connection provider to be used for this clip. Connection providers can be used to create a connection to a streaming server or to a CDN network. An example is our secure streaming plugin that is configured as a connection provider when used with the Wowza server. The value of this property should be the name of a configured plugin. | |
| cuepointMultiplier integer |
1000 | The times of embedded cuepoints are multiplied by this value before being used. Some encoding tools embed cuepoints in seconds but Flowplayer processes cuepoints in milliseconds. Note that the times are also rounded to the nearest 100 milliseconds. For example, if a file has a cuepoint at 5.535 seconds, the cuepoint is fired at 5500 milliseconds (assuming the default multiplier value of 1000). |
| cuepoints array |
The cuepoint objects of this clip. The property contains all embedded cuepoints, cuepoints specified in the configuration and also all cuepoints added dynamically using the addCuepoint() method. | |
| controls object |
since 3.1.1.. Alternate controlbar configuration for this clip. This overrides the settings specified for the controlbar plugin. This is mainly used when you have multiple clips on the playlist and you want to tweak the controlbar looks for a specific clip. All controlbar properties can be tweaked with the exception to the url and positioning properties. You can see this feature in action in this instream playlist demo. | |
| duration number |
0 | The time, in seconds and fractions of a second, for which a video clip should be played until playback ceases. This must always be less than or equal to the total length of the clip. Zero means to play the whole clip. |
| extension string |
The file extension extracted from the url property. | |
| fadeInSpeed integer |
1000 | Time in milliseconds to fade from zero to full opacity upon commencement of video playback. |
| fadeOutSpeed integer |
1000 | Time in milliseconds to fade from full to zero opacity upon completion of video playback. |
| image boolean |
Is the previous clip being used as a splash image for this audio clip? Only relevant to audio clips. | |
| linkUrl string |
The URL to direct users to when clicking the video screen. | |
| linkWindow string |
_self |
Defines where the page defined by linkUrl is opened. Available options are:
|
| live boolean |
RTMP streaming servers support live streaming, which means that it is possible to setup a video camera or other live video source to stream live video data to Flowplayer. If you have an RTMP server which is providing a live video stream, you should set this property to true. | |
| metaData object |
Normally the player shows the video only when it has read the dimensions metadata from the video file. If the file does not have metadata at all the video will not be shown at all. By setting this to property to false, the player will display the video even when the metadata is not available in the file. | |
| originalUrl string |
The original URL of this clip before it has been updated by any URL resolver, like the bandwidth check plugin that changes the URL to reflect the chosen bitrate. | |
| position integer |
since 3.1.1. If the clip is contained within an instream playlist this property defines when the clip will start in relation to the parent clip. If position is 0 then the clip will be played before the parent clip and if the position is -1 then the instream clip will be played after the main clip. | |
| playlist array |
since 3.1.1. The instream playlist of this clip. | |
| provider string |
http |
The type of video source. By default, Flowplayer assumes that the source is a regular web server (with the provider name http). To use another provider, you must�also configure the provider in your configuration specification. This page describes how to do that.
Flowplayer comes packaged with pseudostreaming and RTMP providers, and you can also build your own. |
| scaling string |
scale |
Setting which defines how video is scaled on the video screen. Available options are:
|
| seekableOnBegin boolean |
Can we seek this clip when it's paused in the first frame. When true the scrubber becomes disabled when the palyer is paused on the first frame. By default the scrubber is enabled when the clip url has one of the filename extensions that are used for Flash video 'f4b', 'f4p', 'f4v', 'flv'. | |
| start integer |
0 | The time (in seconds) at which playback should commence. This is only supported when you have a streaming server. |
| url string |
The URL of the video file to be loaded. You can specify an absolute URL here, or one that is relative to the current HTML file. Supported file formats are FLV and H.264-encoded MP4 and M4V for video, and JPG, GIF and PNG for images. The URL can also be given as the href attribute of the player container. If both are given then the configuration property overrides the href attribute. | |
| urlEncoding boolean |
If true the clip's url will be url-encoded. Use this if the url contains international characters, for example chinese characters. | |
| urlResolvers string/list |
Sets a URL resolver to be used for this clip. URL resolvers are used to resolve the final URL for the clip before it gets played. Examples are our bandwidth detection and secure streaming plugins that are both URL resolvers. The value of this property should be the name of a configured plugin. It's possible to use several URL resolvers and in this case the value is a list, for example ['bwcheck', 'secure']. See this demo that shows how to combine two URL resolvers.. NOTE: URL resolvers are applied automatically if this property is not present and there are URL resolver plugins in the configuration. You can specify urlResolvers: null if you want insure that no urlResolvers are applied for this clip. |
Clip update
| method | returns | description |
|---|---|---|
| update(Object) | Clip |
Update clip properties with the properties given in the argument. You can provide the argument for example as a json object. When this method completes updating the clip's properties, it fires an onUpdate event so that plugins and listeners know that this clip has changed. You can place your own custom properties here too, for example:
$f().getClip(1).update({duration:10, autoPlay:true, myProp:'custom'}); If this method is called before the player has finished loading then the onUpdate event will not fire. |
Clip events
You can register clip event listeners directly with the Player object and they get registered with the common clip so that they will be called when the event ocurrs for each clip of the playlist. Each clip can also have an own set of property values and event listeners that override those of the common clip.
Basic clip events
Listeners to clip events have their this variable set to the current Player object and receive as their first argument a reference to the Clip on which the event fires.
For some events, there is also an onBefore version of the event, e.g. onBeforePause and onPause. Returing false from an onBefore event will cancel the event, i.e. the action is not performed and its on version will not be called.
| Event | When does it fire? | If the action is cancelled |
|---|---|---|
| onBegin onBeforeBegin |
This is always the first event to fire during the 'lifecycle' of a clip, and it does so as soon as the clip's video file has started buffering. Playback of the clip has not yet commenced, but streaming/downloading has been successfully initiated. | Playback will not start. |
| onFinish onBeforeFinish |
This fires when the clip reaches the end and the "Play again" button appears. | In the case of a single clip, the player will start from the beginning of the clip. In the case of an ordinary clip in a playlist, the "Play again" button will appear. In the case of the final clip in a playlist, the player will start from the beginning of the playlist. |
| onLastSecond | This is a convenience handler for performing actions in the last second of playback. The same thing can be accomplished with a so-called "negative cuepoint", but because this is such a common scenario we have added an easy-to-use event handler. | |
| onMetaData | This fires after onBegin, once the video file's metadata has been received. The clip object is provided as an argument to the handler, with the metadata included as a property of the object. | |
| onPause onBeforePause |
This fires when playback is paused. | The pause action is cancelled. |
| onResized | This fires when the clip has been resized. Clip is resized for example when the screen size changes. | |
| onResume onBeforeResume |
This fires when playback is resumed after having been paused. | The player will remain paused. |
| onSeek onBeforeSeek |
This fires when the playhead is seeked forward or backward. This happens when the user clicks on the controlbar's timeline
(i.e., uses the "scrubber"). The second argument to this event is the target time where the seek ended at. In the case of
onBeforeSeek, the argument is the time where the user is intending to seek to and can
be slightly different from the value where the seek actually ends up (because of keyframe positions).
|
The seek action is cancelled. This is useful for critical video content, the playback of which needs to be forced. |
| onStart | This fires at the point at which playback commences. With autoBuffering set to true it even fires when autoPlay is false, because the clip is paused at the first frame. | |
| onStop onBeforeStop |
This fires when playback is stopped. | The stop action is cancelled. |
| onUpdate | This fires when clip properties are updated using the clip object's update() method. The argument which is passed to the handler is the newly modified clip object. |
Advanced clip events
These events are rarely needed by developers and are mostly used internally by the controlbar plugin. However, they may be of interest if your particular application needs to know the status of the buffer.
| Event | When does it fire? |
|---|---|
| onBufferEmpty | This fires when playback has consumed all the buffered video data and the playhead cannot proceed, resulting in a temporary stop in playback. This is more likely to occur with lower connection speeds and may happen multiple times during a clip's lifecycle. |
| onBufferFull | This fires when the video buffer has reached capacity (i.e. all currently required video data has been downloaded into the player's memory). The buffer size is determined by a clip's bufferLength property, which, by default, has a value of 3 seconds. This event may fire multiple times during a clip's lifecycle, depending on the size of the buffer and the user's connection speed. |
| onBufferStop | This fires when the stopBuffering API call is invoked. |
| onNetStreamEvent | Fired when an event is triggered on the NetStream object. The second argument in this event is the type of NetStream event type triggered and it is one of following: 'onXMPData', 'onCaption', 'onCaptionInfo', 'onPlayStatus', 'onImageData', 'RtmpSampleAccess', 'onTextData'. You can register a listener for this event if you are interested in any of the event types listed previously. The third argument of this event is an info object related to the event type in question. |
Cuepoints
Cuepoints are a powerful tool to add functionality to a clip's timeline that lets you take actions at predefined times during playback. This mechanism is especially useful for long videos where you might want to have special events triggered during the period in which the video is playing. For example, in teaching videos you might want to enrich your clip with help texts or other interactive material. Or, in a more commercial setting, you might want to show targeted advertisements at certain points in the video.
It is possible to have multiple cuepoint listeners on the same Clip, and even to have more than one cuepoint with the same timestamp. Cuepoints set on the common clip are common to all Clips in the Player. Cuepoints are given in milliseconds. Here is an example:
// call cuepoint function on first and last second
$f().onCuepoint(
[1000, {time:-1000, custom:'Hello, world!'}],
function(clip, cuepoint) {
alert("cuepoint " + cuepoint + " reached");
}
);Listeners to cuepoints have their this variable set to the current Player and receive as their first argument a reference to the currently playing Clip. onCuePoint() returns the Clip object for method chaining.
| onCuepoint( callback ) | This registers a function that will be called for the cuepoints embedded in an FLV-encoded video clip. To use this option, you need to be able to embed cuepoints in your video. Tools for doing this include Flash Video Encoder and flvtool2. |
| onCuepoint( time, callback ) | This registers a function that will be called when playback reaches the time, in milliseconds, specified in the first argument. If the given value is negative, the location of the cuepoint is calculated from the end of the video, so -1000 means one second before the end of the video. |
| onCuepoint( object, callback ) | This is identical to the previous method except that the cuepoint is given as an object that must have a property called 'time' that has the cuepoint in milliseconds. For example: {time:35000, caption:'Special event'}. This object is later provided to the callback function 'as is', so you will have access to any other custom properties which you may have set. |
| onCuepoint( Array, callback ) | This version of onCuepoint accepts multiple cuepoints in the first argument (by means of an array), and the callback is invoked each time one of these cuepoints is reached. Cuepoints in the array can be integers or objects. See the examples above. |