Flowplayer Events Player configuartion taken to the next level
Introduction
Here is a list of of clip events that you can define actions for. These are specified for the clip node. For example:
flowplayer("player", "flowplayer-3.2.4.swf", {
// a clip object
clip: {
// a clip event is defined inside clip object
onStart: function() {
alert("clip started");
}
},
// player events are defined directly to "root" (not inside a clip)
onLoad: function() {
alert("player loaded");
}
});List of clip-specific events that you can define actions for.
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. |
| 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. | |
| 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. |
Common clip
When you define event actions for the common clip, those event actions are applied to every clip in the playlist. Clip-specific events do not override common clip events by default. Instead, event action specifications at the playlist item level are evaluated first, and if they do not explicitly return false, the event actions specified for the common clip are evaluated subsequently. In the event world this is known as "event bubbling".
Event bubbling example
When playback starts, we will first trigger the clip-specific event action, and because it does not return false, we will proceed to the event action for the common clip.
When playlists are combined with event handlers, there is a lot of potential to do clever and interesting things.
Registering custom NetStream and NetConnection events
It's possible to register listeners for custom events that get triggered in the NetStream and NetConnection objects. You can use this mechanism to listen to custom events that you programmatically generate in a streaming server application. Following shows how to register two custom events:
flowplayer("player", "flowplayer-3.2.4.swf", {
// define what custom events should be listened to by the player
connectionCallbacks: [ 'onMyConnectionEvent' ],
streamCallbacks: ['onMyStreamEvent', 'onMyOtherStreamEvent'],
// a clip object with our listener functions
clip: {
// this gets called when my custom NetConnection event fires
onMyConnectionEvent: function(clip, info) {
alert("connection event triggered on clip " + clip.url + " info: " + info);
},
// this gets called when my custom NetStream event fires
onMyStreamEvent: function(clip, info) {
alert("stream event triggered on clip " + clip.url + " info: " + info);
}
// this gets called when my second custom NetStream event fires
onMyOtherStreamEvent: function(clip, info) {
alert("my second stream event triggered on clip " + clip.url + " info: " + info);
}
}
});