API for Flex Developers

From Livestream » User Guide

Jump to: navigation, search

Livestream provides an API for Flex developers who want to integrate the player into their own Flex project. The component to load in your Flex application is a regular ActionScript SWF with which you can interact using various functions and by listening to events. The module is hosted on our servers and is available at this URL:

http://cdn.livestream.com/chromelessPlayer/v21/playerapi.swf


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. For Flash and Flex, use the devKey property or the setDevKey() function in the HTML scenario.

You will want to pass your developer key to the player before you set the channel so that it has knowledge of the key before connecting. A good solution is to wait for the "ready" event to fire and set the key first thing.


Player behavior


The first step is to get a general overview of how the player works over here.


Important Notice: Flash Security Restrictions


Before we get started, we should take a look at the Flash security restrictions when it comes to loading a module from a remote domain into your application. If like most developers you are going to test your application locally, trying to load the playerapi.swf module directly from our servers will lead to a 'SWF is not a loadable module' error caused by the Flash security restrictions. The quickest way to get around this is to download the playerapi.swf flash locally to your harddrive and access is from there. When you deploy your application to a web server, you will then need to change the URL of the module to point to our servers again.


Simple example


To use the Livestream API into your application, you can use a SWFLoader class from mx.controls package. You should wait for the complete event before you start interacting with Livestream API component

The following is an example of the simplest integration of our component in a Flex application:

Flex 4 example

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009" xmlns:s="library://ns.adobe.com/flex/spark"
               xmlns:mx="library://ns.adobe.com/flex/mx" minWidth="955" minHeight="600" initialize="application1_initializeHandler(event)" creationComplete="application1_creationCompleteHandler(event)" viewSourceURL="srcview/index.html">
    <fx:Declarations>
        <!-- Place non-visual elements (e.g., services, value objects) here -->
    </fx:Declarations>
    <fx:Script>
        <![CDATA[
            import mx.events.FlexEvent;
            private var player:*;
 
            protected function loader_completeHandler(event:Event):void
            {
                player = loader.content;
                player.addEventListener("errorEvent", playerErrorHandler);
                player.devKey = "REPLACE WITH YOUR DEVKEY";
                player.setSize(640, 360);
 
                loader.width = 640;
                loader.height = 360;
 
                player.load("livestreamapi43");
                player.showFullscreenButton = true;
                player.play();
            }
 
            protected function application1_initializeHandler(event:FlexEvent):void
            {
                Security.allowDomain('cdn.livestream.com');
 
                if (stage)
                {
                    onAddedToStage();
                }
                else
                {
                    addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
                }
            }
 
            protected function onAddedToStage(event:Event = null):void
            {
                removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
                stage.addEventListener(FullScreenEvent.FULL_SCREEN, onFullScreenEventHandler);
            }
 
            protected function playerErrorHandler(event:Event):void
            {
                var e:Object = Object(event);
                trace('Player error: [' + e.code + '] ' + e.message);
            }
 
            protected function application1_creationCompleteHandler(event:FlexEvent):void
            {
                // to test locally download palyerapi.swf into flex project
                try
                {
                    loader.loaderContext = new LoaderContext(true, ApplicationDomain.currentDomain, SecurityDomain.currentDomain);
                }
                catch (e:Error)
                {
                    // to load locally
                    loader.loaderContext = new LoaderContext(true);
                }
 
                loader.load("http://cdn.livestream.com/chromelessPlayer/v21/playerapi.swf");
 
            }
 
            private function onFullScreenEventHandler(event:FullScreenEvent):void
            {
                if (stage.displayState == StageDisplayState.FULL_SCREEN)
                {
                    loader.width = stage.stageWidth;
                    loader.height = stage.stageHeight;
                }
                else
                {
                    loader.width = 640;
                    loader.height = 360;
                }
            }
        ]]>
    </fx:Script>
 
    <mx:SWFLoader 
        id="loader"
        scaleContent="false"
        complete="loader_completeHandler(event)"/>
</s:Application>

Flex 3 example

<?xml version="1.0" encoding="utf-8"?>
<mx:Application 
	initialize="application1_initializeHandler(event)"
	xmlns:mx="http://www.adobe.com/2006/mxml" 
	width="640" height="360"
	horizontalScrollPolicy="off" verticalScrollPolicy="off"
	layout="absolute">
 
	<mx:Script>
		<![CDATA[
			import mx.events.FlexEvent;
			import mx.events.ResizeEvent;
			private var player:*;
			protected function loader_completeHandler(event:Event):void
			{
				player = loader.content;
				player.addEventListener("errorEvent", playerErrorHandler);
				player.devKey = 'REPLACE WITH YOUR DEVKEY';
				player.setSize(640,360);
				player.load("livestreamapi43");
				player.showFullscreenButton = true;
				player.play();
 
			}
 
			protected function application1_initializeHandler(event:FlexEvent):void
			{
				Security.allowDomain('*.livestream.com');
				if(stage)
				{
					stage.addEventListener(Event.RESIZE, onResize);
				}
				else
				{
					addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
				}
			}
 
			protected function onAddedToStage(event:Event):void
			{
				removeEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
				stage.addEventListener(Event.RESIZE, onResize);
			}
 
			protected function onResize(event:Event):void
			{
				if(player != null)
				{
					player.setSize(stage.stageWidth, stage.stageHeight);
				}
			}
 
			protected function playerErrorHandler(event:Event):void
			{
				var e:Object = Object(event);
				trace('Player error: [' + e.code + '] ' + e.message);
			}
		]]>
	</mx:Script>
 
	<mx:SWFLoader 
		id="loader"
		source="http://cdn.livestream.com/chromelessPlayer/v21/playerapi.swf"	
		scaleContent="false"
		complete="loader_completeHandler(event)" />
 
</mx:Application>

Interactions with the Livestream module


Once the SWFLoader has loaded the playerapi.swf, you can assign a variable to it's content which will be the instance of the player you will be interacting with.You are then free to interact with the player using any of the properties and methods documented here.

Here is a listing of the other events that the component dispatches:

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


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.