Stickam | Mobile | Developers | PayPerLive | LiveCitizen
 

How To Guide

This guide will show you how to set-up and configure your own embeddable StreamAPI players, in order for you to quickly start your own live video broadcasting site.

1) Broadcast and Create a Live Session

A step-by-step guide to create a live session.
Step 1:  Create your custom theme
Step 2:  Create a session
Step 3:  Embed the session
Step 4:  Quick stream option

Step 1:  Create your custom theme

From the "Theme Editor" navigation link, click the "New Theme" button to launch the Theme Editor with a selection of themes you can choose from.

Once you select the theme that fits the design of your site, you can preview how the player will look as a host of the live session by clicking on "Theme Menu" then "Preview Theme without Saving".
If you're satisfied with the preview, you can save this theme by clicking on "Theme Menu" then "Save Theme"

When you save a new theme a skinPath and layoutPath will be generated. These paths are static and will not change when you save the same theme again. You will reference them when generating HTML embed code.

Step 2:  Create a session

For a user to broadcast a video stream you will need to create a new StreamAPI session.
API calls, such as creating a new session, are always made directly from your server to StreamAPI. No REST API requests are ever made directly from your user's web browser to StreamAPI. You can use the StreamAPI HTTP console to check out the result of your create session API call.

Request

    POST http://api.streamapi.com/service/session/create
    	key => IEKDUCKDKDIEDKWIQDK1038DKLEIC8202K
        rid => 123456
        sig => ABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGH
Required request parameters
  • key
    • The API key given to you in the API Settings page.
  • sig
    • The signature of the current request, which is a MD5 hash of the request values, request ID, and secret key. If you're only sending required parameters, you signature (sig) will look like this:
    MD5(key_value + secret_key_value + rid_value) or MD5(IEKDUCKDKDIEDKWIQDK1038DKLEIC8202KABCDEFGHIJKLMNOPQRSTUVWXYZABCDEFGH123456)
    If you're only sending required and optional parameters, you signature (sig) will look like this:
    MD5(key_value + public_hostid_value + site_userid_value + username_value + secret_key_value + rid_value)
  • rid
    • Request ID or request sequence to prevent playback attacks. This is a unique number increasing for every successive call. We recommend that you use current time in milliseconds.

Optional request parameters

  • site_user_id
    • This sets the public_hostid to your own site's user ID. So if a user in your database has id 123456 that will also be the site_user_id for their stream. Besides public_hostid, your streamAPI site ID and a user's site_user_id makes a user unique in the streamAPI system. So, when you create a session and you're passing in a site_user_id value, make sure that the value is for the right user who's session is being created. Otherwise, you can leave this parameter blank.
  • username
    • Displayed as the name of the user in a User List Component or onscreen overlay in the Host video.
  • fme_key
    • To create a live session using a different flash media encoder (such as the Adobe Flash Media Live Encoder), you can pass in a fme_key value, which is a secret unique value that you can set for that user. The fme_key value that is set in StreamAPI and that your user will need to enter in the URL will need to be rtmp://fme.streamapi.com/hd_receiver/[public_host_id]-[fme_key_value] For example, if the fme_key value for a user is f1b8221d2b69 and the user's public host id is 1000016132, the real fme_key that StreamAPI will set is 1000016132-f1b8221d2b69 and the RTMP URL will be rtmp://fme.streamapi.com/hd_receiver/1000016132-f1b8221d2b69
  • is_video_private
    • To create a live session that will allow only authenticated viewers to see the live video and join the live sesion, you can pass in is_video_private with a value of true

Response

private_hostid 

    C0UC4WO3ATORK259QL1STSIZO7RB1G5I
public_hostid 
    1745122342
fme_key (only returned if fme_key is passed in as a parameter in the create session request) 
	1000016132-f1b8221d2b69

Client API examples

  • Perl
    •     use WWW::StreamAPI;

    my $streamapi = WWW::StreamAPI->new(
        secret_key => 'YOUR_SECRET_KEY_HERE',
        api_key => 'YOUR_API_KEY_HERE',
    );

    my ($private_hostid, $public_hostid) = $streamapi->create_session(
        username => 'Peter',
        site_user_id => 123456, # Optionally overrides public_hostid
        # fme_key = > 'YOUR_FME_KEY_FOR_THIS_USER'
    );
  • Java
    • public class TestCreateLiveSession extends HttpServlet {
    
	private final static String API_KEY = "YOUR_API_KEY_HERE";
	private final static String SECRET_KEY = "YOUR_SECRET_KEY_HERE";
	private Logger log = Logger.getLogger(TestCreateSessionServlet.class);
	
	public void doGet(HttpServletRequest request, HttpServletResponse response)
		throws ServletException, IOException {
		
		try {
			StreamAPIClient api = new StreamAPIClient(API_KEY, SECRET_KEY);
			
			// Register user
			Long publicHostId = api.registerUser(123456, 'Peter');
			
			// Create session with required 
			//		and optional parameter: public_hostid
			Session newSession = api.createSession(publicHostId);
			
			// Create session with FME
			// String fmeKey = "YOUR_FME_KEY_FOR_THIS_USER";
			// Session newSession = api.createSession(publicHostId, fmeKey);

			// Create session with only allowing authenticated viewers to view 
			//		and join live session
			// Session newSession = api.createSession(publicHostId, true);
			
			// Create session with required parameters ONLY
			// Session newSession = api.createSession();
			
			// Create session with required 
			//		and optional parameters: site_user_id and username
			// Session newSession = api.createSession(123456L, "Peter");
			
			// Create session with required and optional parameter: username
			// Session newSession = api.createSession("Peter");
			
			Long publicHostId = newSession.getPublicHostId();
			String privateHostId = newSession.getPrivateHostId();
			// String realFMEKey = newSession.getFmeKey();
			// 	log.info("FME KEY IS: " + realFMEKey);
			log.info(
				"Public Host ID: " + String.valueOf(publicHostId) + 
				" Private Host ID: " + privateHostId);
		}
		catch (StreamAPIException sae) {
			// exception action here
		}
	}
}

Step 3:  Embed the session

Every StreamAPI session has a private host ID and a public host ID associated with it. The private session ID is to be given only to the broadcaster themselves. The public host ID is used to view the stream by viewers.

The public hostID and private host ID are embeded as Flashvar arguments for the broadcaster:

Embed code without FME

<OBJECT classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000" 
codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0" 
width="500" height="500" id="liveStream" align="">
<PARAM name="movie" value="http://static.streamapi.com/flash/loader.swf?app=custom.swf&1247246891974">
<PARAM name="FlashVars" value="siteID=1000000041&publicHostID=1000016130
&layoutPath=/themes/100/000/004/1/theme_ead36f16-4f26-11de-9836-25ac2e30640e.xml
&skinPath=/themes/100/000/004/1/skin_ead36f16-4f26-11de-9836-25ac2e30640e.xml
&privateHostID=WI41YDUQF4MTK6WSF84I4QSX4TAFUS6Y&userType=host&">
<PARAM name="allowScriptAccess" value="always">
<PARAM name="allowFullScreen" value="true">
<PARAM name="quality" value="high">
<PARAM name="bgcolor" value="#000000">
<PARAM name="scale" value="noscale">
<PARAM name="wmode" value="transparent">
<embed src="http://static.streamapi.com/flash/loader.swf?app=custom.swf&1247246891974" 
FlashVars="siteID=1000000041&publicHostID=1000016130
&layoutPath=/themes/100/000/004/1/theme_ead36f16-4f26-11de-9836-25ac2e30640e.xml
&skinPath=/themes/100/000/004/1/skin_ead36f16-4f26-11de-9836-25ac2e30640e.xml
&privateHostID=WI41YDUQF4MTK6WSF84I4QSX4TAFUS6Y&userType=host&" 
allowScriptAccess="always" allowFullScreen="true" width="500" height="500" scale="noscale" 
wmode="transparent" quality="high" bgcolor="#000000" type="application/x-shockwave-flash" >
</embed>
</OBJECT>

    <div id="player_container"></div>

    <script type="text/javascript" 
    	src="http://ajax.googleapis.com/ajax/libs/swfobject/2.1/swfobject.js"></script>

    <script type="text/javascript">
       swfobject.embedSWF("http://static.streamapi.com/flash/loader.swf", "player_container", 
       						"500", "500", "9", "", {
            'app' : 'custom.swf',
            'siteID' : '1265428111',
            'publicHostID' : '1745122342',
            'layoutPath' : '/themes/126/542/811/1/theme_03d2cdd0-1d8b-11de-a2c3-f7f8349311a2.xml',
            'skinPath' : '/themes/126/542/811/1/skin_03d2cdd0-1d8b-11de-a2c3-f7f8349311a2.xml',
            'privateHostID' : 'C0UC4WO3ATORK259QL1STSIZO7RB1G5I',
            'userType' : 'host'
        }, {
            allowfullscreen: "true",
            allowscriptaccess: "true"
        });
    </script type="text/javascript">

SWFObject

The embedding examples shown here utlize the SWFObject javascript library for generating embed codes. http://code.google.com/p/swfobject/. This is the recommended way of generating proper HTML Flash embeds. You are also free to generate them manually or using a different library.

Step 4:  Quick Stream option

For one off events, you can create a live session by using the "Quick Stream" option. You can start a live session using Standard option or RTMP Direct option. You would select RTMP Direct option if you're planning on using a different media live encoder.