Player API Behavior

From Livestream » User Guide

Jump to: navigation, search

The Livestream Player API allows you to build your own custom player using either HTML and Javascript, Flash or Flex. All these approaches share the same core module, and as such share some common behavior.

There are two main modes of operation for the player; linear mode and on-demand mode. Linear mode is the default and plays whatever content is currently being broadcasted on the channel. This might be a live feed, a pre-recorded clip being played from the Livestream studio, or clips from the autopilot running on that channel.

In on-demand mode you may choose to play a specific clip from the channel's on-demand library. You will need to pass a clip ID to the API, at which point it will automatically enter on-demand mode. You can use the [on-demand API] in order to get to the clip ID.

Example of both modes of operation in the twitcam player; notice the seeking controls in on-demand mode.


Initial state


The player is initially in 'off' mode and shows a thumbnail of the content about to be played. This thumbnail will update in linear mode and can be disabled using the module's showThumbnail property. We also display an overlayed play button that is replaced by pause and mute buttons during playback. These can be configured using the showPlayButton, showPauseButton and showMuteButton properties or their javascript equivalent for the HTML API.

If you're planning on building your own mute and play/pause button to run alongside the existing overlays, you can listen to events the module fires in order to toggle their state when the player is muted or paused. The full list of events is available in the API Documentation.

A spinning loader will also be visible by default while the player loads the content of the channel or the on-demand clip. It can similarly be disabled and customized using the spinnerSize property.


During playback


Several functions are available in the API to control playback. The play() function takes an optional argument that may be used to seek to a certain position in the clip in on-demand mode. The argument provided should be the time to seek to in seconds. If you wish to seek during playback, for instance to build your own scrubber, you may use the seek() function of the API.

Also useful for the on-demand mode are the duration and time properties of the player. They will provide you with the total length and current position in the on-demand clip that's playing.

The viewerCount property of the module allows you to poll the player to get the total number of viewers currently watching the channel. This property is updated fairly frequently, in our examples we use a one second polling interval to display the count below the video.

You may also listen on the event of type "isLiveEvent", which indicates that the channel either went on or off live status. The isLive property will indicate what the new status of the channel is.

Please note that the viewerCount as well as the live event both are available even before the player actually is playing content.


To get more information about the available development environments, check out our documentation for: