API for HTML Developers

From Livestream » User Guide

Revision as of 12:15, 6 August 2013 by Moguluswikiadmin (Talk | contribs)
(diff) ← Older revision | Current revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Livestream provides an easy to use API for HTML developers so that users and developers can seamlessly integrate a chrome-less player in their own user experience.

In order to do that, HTML developers can embed a special flash application hosted on the livestream servers and interact with it using javascript.

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. The example below demonstrates how to do this.

Important notice: fullscreen mode

Please note that fullscreen mode cannot be activated with the HTML API. This is due to a security restriction built into flash that requires fullscreen mode to be activated as a result of an interaction from within the flash application itself. If you need a fullscreen button in your player, please use either the Flash or Flex API's.


Step one: embed the flash application


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

The flash application may be embedded in the web page using any available methods. We recommend using the swfobject script for it's compatibility and simplicity. The application is hosted at http://cdn.livestream.com/chromelessPlayer/v21/playerapi.swf. It needs to be embedded using the 'AllowScriptAccess' embed attribute set to 'always'. You may also optionally specify a 'channel' flashvar that the player uses to connect to a certain livestream channel automatically on startup.

The swfobject script replaces the div you specify with the embed tag for the flash application. If a div with the id 'livestreamPlayer' was placed somewhere on the web page, and you wanted to connect to the channel 'mogulusbackstage', the resulting call to swfobject would look like this:

<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
<script type="text/javascript">
	flashvars = { channel: 'livestreamapi43' };
	params = { AllowScriptAccess: 'always' };
	swfobject.embedSWF("http://cdn.livestream.com/chromelessPlayer/v20/playerapi.swf", 
		"livestreamPlayer", "400", "300", "9.0.0", "expressInstall.swf", flashvars, params);
</script>
 
<div id="livestreamPlayer"></div>

Step two: interact with the player using Javascript


The first step will get you started with a chrome-less player playing your channel. Now we'll see how to interact with the player using Javascript.

Important notice: Flash security restrictions when testing locally

If you are trying to test your application locally, you might run into some problems related to the flash security model. The flash security model does not grant you Javascript access from flash by default. In that case, you might get a "Security Sandbox Violation" from the player or it might fail silently. You'll notice something is wrong if none of the Buttons / Javascripts functions are working. In that case if you want to test locally, you need to configure the security settings using the Flash Player Settings Manager.

In the "Global Security Settings" tab, you can add a location corresponding to the folder where your test page is located. The player should now load properly locally and you will be able to use Javascript for interaction.

The flash application exposes several functions that enable you to control the player:

Basic functions:

Function Values Description
setDevKey(key) key: string Use this function to pass the developer key you created to the player (required).
load(channel, clipID) channel: string clipID:String (optional) Set the channel and clip the player will connect to. You need to set this before being able to access certain functions that provide channel meta-data such as getViewerCount() or getCurrentContentTitle(). Set clipID to null if you would like to play live content after playing an ondemand clip
startPlayback(seek) seek: number Start playing live or on-demand, depending on whether a clipID was set. If playing on-demand, you may specify an offset in seconds where the clip should start playing
stopPlayback() Stop playing. In case of ondemand, You may call startPlayback() again to start playing the clip where it stopped
seek(pos) pos: number When playing an on-demand clip, seek to the specified position (seconds) in the clip
volumeUp() Increase the volume by 10%
volumeDown() Decrease the volume by 10%
setVolume(n) n: float between 0.0 and 1.0 Sets the volume to the specified value. Valid values range between 0 (mute) and 1 (max).
getVolume() returns: float between 0.0 and 1.0 Get the current volume
isMute() returns: boolean Returns whether or not the player is currently muted
getTime() returns: number When playing an on-demand clip, this function returns the current playhead position in seconds
getDuration() returns: number When playing an on-demand clip, this function returns the complete duration of the clip.
getCurrentContentTitle() returns: string Get The title of the clip, storyboard or live stream that is currently playing on-air.
getViewerCount() returns: number The number of viewers currently watching this Livestream channel.
getChannelFullName() returns: string Return the full name of this Livestream channel
getChannelDescription() returns: string Return the description of this Livestream channel
getChannelLogoURL() returns: string Return the URL of this channel's logo
isLive() returns: boolean True if the channel is live, ie. if it is displaying a live stream or is being controlled from a live Livestream studio. If false, this channel is running in autopilot mode

Advanced functions:

Function Values Description
setUsername(username) username: string Set the Livestream username for this channel. Only required on private channels.
setPassword(password) password: string Set the Livestream password for this channel. Only required on private channels.
setAffiliateID(id) id: string Your Livestream affiliate id. Only required for affiliates.
setAffiliateKey(key) key: string Your Livestream affiliate key. Only required for affiliates.
isOnAir() returns: boolean Whether or not the player is currently playing content being broadcasted on the Livestream channel
isInSync() returns: boolean Whether or not the player is synchronized with the channel. Player may lose synchronization due to poor connection speeds, but will automatically attempt to resynchronise.
toggleMute() Toggle muting of the stream
showPlayButton(val) val: boolean Toggle display of the overlay play button
showPauseButton(val) val: boolean Toggle display of the overlay pause button
showMuteButton(val) val: boolean Toggle display of the overlay mute button during stream playback
showFullscreenButton(val) val: boolean Toggle display of the overlay fullscreen button during stream playback
showThumbnail(val) val: boolean Toggle display of the updating thumbnail when playback is off
showSpinner(val) val: boolean Toggle display of the spinner while the stream is loading
startPreroll() Starts preroll ads on demand, to enable this feature ‘triggerAdsFromJS’ flash var has to be set to true. This feature is only supported for premium channels. A new ad request is made every time when this function gets called.
startOverlays() Starts overlay ads on demand, to enable this feature ‘triggerAdsFromJS’ flash var has to be set to true.This feature is only supported for premium channels. A new ad request is made every time when this function gets called.


You can access the player object from javascript using the document.getElementById(playerid) function, where 'playerid' is the id of the div tag you specified in the previous section. The player has to be fully loaded though before any of these functions are available through JavaScript. Thus it is best to wait for the "ready" event (described below) gets fired by the player before trying to interact with it.

The player also calls a special function when an event occurs. The name of that function by default is livestreamPlayerCallback, but it can be configured by using the jscallback flashvar. It takes one parameter which is the type of the event that fired. Here at the different event types, in the order that they are usually fired:

event type Description
ready Fired after the player is done loading. It is safe to interact with it after this event fired
connectionEvent Fired when the player connects to the channel. if autoOnAir is set to false, the content will not start playing immediately but you will already be able to access certain properties of the channel such as the viewer count or it's full description.
onAirEvent Fired when the player starts playing content being broadcasted on the channel
inSyncEvent Fires when the player synchronizes with the channel
isLiveEvent Fires when live content is being broadcasted to the channel or when the channel is being controlled from a Livestream studio
disconnectionEvent Fired when the player disconnects from the channel, whether a result of user interaction or not.

In the previous example you would receive events from the player using by adding the following function to your page:

function livestreamPlayerCallback(event) {
	if (event == "ready") {
		// do something here
	}
}

Complete example


Here is a simple example of how to embed the player and use HTML input buttons to interact with it. Be sure to download swfobject.js version 2.0 or higher if you want to try that example. For a more advanced example that takes advantage of the thumbnail API (described below) and other advanced features, check out this example.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
  <title>Livestream API for web developers - example</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
  <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>
  <script type="text/javascript">
    params = { AllowScriptAccess: 'always' };
    function livestreamPlayerCallback(event) {
      if (event == 'ready') {
	player = document.getElementById("livestreamPlayer");
      	player.setDevKey('YOUR DEVKEY');
      	player.load('livestreamapi43');	
      }
 
      log = document.getElementById('log');
      log.innerHTML = log.innerHTML + '<br/>' + event; 
    }
    swfobject.embedSWF("http://cdn.livestream.com/chromelessPlayer/v21/playerapi.swf",
      "livestreamPlayer", "400", "300", "9.0.0", "expressInstall.swf", null, params);
  </script>
</head>
<body>
  <div id="livestreamPlayer">
  <h1>This page requires flash</h1>
    <p><a href="http://www.adobe.com/go/getflashplayer">download flash</a></p>
  </div>
  <br/>
  <input type="button" value="play" onclick="player.startPlayback()"/>
  <input type="button" value="pause" onclick="player.stopPlayback()"/>
  <input type="button" value="vol +" onclick="player.volumeUp()"/>
  <input type="button" value="vol -" onclick="player.volumeDown()"/>
  <div id="log"></div>
</body>
</html>

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.