This is a message.

Clip

Clip

A Clip object can be though of 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.

PropertyTypeDescription

completeUrl

string

Clip's complete URL. This is the concatenation of the clip's baseUrl property and the clip's url property. baseUrl is undefined if you did not set it explicitly.

cuepoints

array

The cuepoint objects of this clip. The property contains all embedded cuepoints and the cuepoints specified in the configuration.

extension

string

The file extension extracted from the url property.

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. - Shorthand for metaData.duration.

height

integer

Calculated height for the video, in screen pixels, after scaling and screen dimensions have become known.

The original height of the video is available as metaData.height.

index

integer

Index of the clip in the playlist. 0 is the first clip, 1 is the second and so on. The index of the common clip is -1.

isCommon

boolean

true if the clip is a common clip and false otherwise.

isInStream

boolean

Since 3.1.1. This property is true if the clip is contained within an instream playlist.

metaData

object

A large collection of information about the clip. The information might be influenced by the originating server and differ from the actual metadata in the 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 original width of the video is available as metaData.width.

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 / DatatypeDefaultDescription

accelerated
boolean

false

Flag indicating whether Flash 9 (and above) hardware-accelerated fullscreen 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 preloaded into Flowplayer's memory to before and during playback.

connectionProvider
string

The connection provider plugin to be used for this clip. Connection providers handle the connection to a streaming server or to a content delivery network (CDN). The value of this property should be the name of a configured plugin.

An example is our secure streaming plugin which provides the connection to a Wowza RTMP server in this demo.

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

controls
object

null

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 in a playlist and you want to tweak the controlbar looks for a specific clip. All controlbar properties can be tweaked - except the url and positioning properties. You can see this feature in action in the 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.

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.

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:

  • '_self': specifies the current frame in the current window.
  • '_blank': specifies a new window.
  • '_parent': specifies the parent of the current frame.
  • '_top': specifies the top-level frame in the current window.
  • '_popup': a popup browser window.

live
boolean

false

RTMP streaming servers support live streaming, which means that it is possible to set up 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 an item of an instream playlist this property defines the time (in seconds) when the clip will start in relation to the parent clip. If the position is 0 then the clip will be played before the parent clip. 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 a different provider, you must configure the provider explicitly. This page describes how to do that.

Flowplayer comes packaged with pseudostreaming, RTMP and HTTP Streaming providers. You can even build your own.

scaling
string

scale

Setting which defines how video is scaled on the video screen. Available options are:

  • 'fit': fit to window by preserving the aspect ratio encoded in the file's metadata
  • 'half': half-size (preserves aspect ratio)
  • 'orig': use the dimensions encoded in the file; if the video is too big for the available space, the video is scaled preserving the aspect ratio
  • 'scale': scale the video to fill all available space; ignores the dimensions in the metadata

start
integer

0

The time (in seconds) at which playback should commence. This is only supported if you deliver from a streaming server.

Note: Red5 servers currently cannot handle this property.

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

false

If true the clip's url will be url-encoded. Use this if the url contains non-ascii characters, for example chinese.

urlResolvers
string/array

The URL resolver plugins which are applied for this clip. URL resolvers determine the actual URL of the clip to be played. The value of this property should be the name of a configured plugin. Examples are our bandwidth detection and secure streaming plugins.

If you specify more than one URL resolver the value must be an array of strings, for example: ['smil', 'bwcheck'] like in this demo.

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 URL resolvers are applied to this clip.

Clip update

MethodReturnsDescription

update(object)

Clip

Update clip properties with the properties given in the argument. The argument is an object in JSON (JavaScript Object Notation). 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'
});

JavaScript

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.

EventWhen does it fire?If the action is canceled

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.

onMetaDataChange

This fires when the clip's metadata has been changed. Typical usage examples include access to server-side song title updates in an audio live stream or the new URL of the current clip after a bitrate switch.

onPause
onBeforePause

This fires when playback is paused.

The pause action is canceled.

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

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.

EventWhen 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 is one of the 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 set up in the onCuepoint event listener. It differs from all other event listeners inasmuch as it customizes a series of events and is configured as an array with the event handler as second item.

ListenerHow To Configure

onCuepoint

An array of 2 members:

  1. an array of customizable cuepoints containing:

    • the time when the event is fired - either an integer or a property labeled time (mandatory)
    • custom properties for the specific cuepoint (optional)
  2. the cuepoint event handler function which takes 2 arguments:

    1. the current clip object
    2. the current cuepoint