API for Flash Developers

From Livestream » User Guide

Jump to: navigation, search

Livestream provides developers with a Flash component for easy integration of a Livestream player in an existing Flash project. Feel free to modify the FLA file that we provide, or to copy the LivestreamPlayer component into your own projects directly.


Contents

Prerequisites


In order to be able to use any of the player API's, you need to get a developer key. Once you have obtained it you have it to pass it to the API module as a first thing before you try to connect to a channel. If you are using our flash component, you can use the 'Developer key' component property to set your devkey. If you decide to script the player yourself, just be sure to set the developer key before the channel gets set or it will not be taken into account.


Quickstart


You can first get a general overview of how the player works over here.

To get started with the Livestream API for flash developers, you may modify the existing lightweight example in the LivestreamPlayer.fla file in the archive available here.

Once the LivestreamPlayer component is on stage some parameters may be configured using the component inspector, most notably the width and height of the player. The component currently does not have a live preview or any other visual representation on the stage, so it will only show up as a 1 pixel movie clip. It's size will change to the specified values once the movie is started.

The LivestreamPlayer component will look for certain instance names on stage in order to make it easy to hook up certain functionality. If you create components with those names and place them on the stage, they will automatically be able to interact with the LivestreamPlayer component.

Those are the instance names we currently look for on stage:

  • livestreamPlayerStopButton
  • livestreamPlayerPlayButton
  • livestreamPlayerTogglePlayButton
  • livestreamPlayerFullscreenButton
  • livestreamPlayerVolumeSlider

All of those buttons are optional, if the instances are not found on the stage they are simply ignored. You may also create your own components that interact with the component directly as we will see in the next section.


Advanced interaction


For more advanced features, you may interact with the player attribute of the LivestreamPlayer component. The LivestreamPlayer component fires a event of type "ready" which you should wait for. The following is a simple example of how to react on a mute event. This event assumes that the LivestreamPlayer component on stage has an instance name of 'livestreamPlayer'. It listens for the event of type "ready" on that component and then sets a global variable named 'player' to the player attribute of the LivestreamPlayer component. From then on, you can use that global variable to invoke any methods, set properties or listen to events.

package
{
	import flash.display.MovieClip;
	import flash.events.Event;
 
	public class Player extends MovieClip
	{
		var lsPlayer:*;
 
		public function Player():void
		{
			livestreamPlayer.addEventListener("ready", readyHandler);
		}
 
		private function readyHandler(event:Event):void
		{
			lsPlayer = livestreamPlayer.player;
			lsPlayer.addEventListener('mutedEvent', mutedHandler);
		}
 
		private function mutedHandler(event:Event):void
		{
			trace('player muted');
		}
	}
}

You may now use any function of the interface in order to customize the look of the player or start on-demand clips for instance. Check the interface documentation for ILivestreamPlayer for a detailed description of what functions are available.

That player attribute of the LivestreamPlayer component also fires a number of events you may listen and react to.

Event Type Description
connectionEvent Fired when the player initially connects to the channel. This does not imply that video playback has started
disconnectionEvent Fired when the player gets disconnected from the channel. Does not usually happen unless your connection drops for instance
isLiveEvent Fired when the channel goes on/off live status. You may use isLive after this has been fired to check whether the channel went live or just stopped being live.
playbackEvent Fired when content playback actually starts, when the video starts playing
playbackCompleteEvent Fired when a clip reaches it's end in on-demand mode or when the playback was stopped in live mode
errorEvent Fired when an error occurs. The code attribute on the event will tell you what the error code is and the message attribute contains a short description of the issue
playClickedEvent Fires when the overlay play button is clicked on the player
pauseClickedEvent Fires when the overlay pause button is clicked on the player
mutedEvent Fires when the player is muted
unmutedEvent Fires when the player is unmuted


Other examples


We have used the API for some internal development already, and provide those here for an example of real-life use of the API.

Mandela Day Player

The Mandela day player provided a customized embedable flash player for Mandela Day 2009. The volume slider on the right shows an easy way of hooking up a custom control that interacts with the player. The player takes advantage of the built-in overlay buttons play and pause buttons that are included in the component, while showing how to implement a simple 2-state mute button. An small sprite indicates the live status of the channel. The full source is available here. File:Image-screenshot-mandeladay.jpg

Twitcam Player

Using the flash API internally allowed us to quickly develop the Twitcam Player for our twitcam.com project. It has two states for live and on-demand content. The on-demand state demonstrates how to implement a custom scrubber using the API. It also has an live status indicator that becomes visible when someone starts broadcasting on the channel, as well as a viewer count display. The full source is available here.

File:Image-screenshot-twitcam.jpg


Using the thumbnail API


Livestream also provides a thumbnail API which gives you the ability to periodically retrieve screenshots of the currently running video stream. You can find the documentation of the Live Thumbnail API here.


Using the channel API


You can find an example of how to use the channel API with the player API here.