Mobile API

From Livestream » User Guide

Jump to: navigation, search

The Mobile API allows you to build your own mobile application by accessing channel specific mobile stream information for both live and on-demand content.

Important Note: This API is still in development and bound to be modified. Please check back on this page regularly to make sure you are using the most up-to-date methods.



Contents

Audience


This document is intended for programmers who want to write client applications that can access Livestream channel's mobile streams. The document provides examples of the supported operations using raw HTTP and XML, along with explanations.




Prerequisites


In order to query the Livestream APIs you need to have one or more livestream channel(s). To create a channel please visit www.livestream.com [1]

Required knowledge:

1. Basic understanding of REST ([2]).

2. Forming the request URL as described here.

3. Understanding the request throttling limits as described here.

4. Any programming language.

How to publish a mobile compatible stream


The recommended way of publishing a mobile stream is by using the Livestream Procaster encoder. Livestream Procaster is free and allows users to specifically target mobile platforms when going live. Download it at http://www.livestream.com/procaster.

Livestream also supports mobile playback of all streams encoded using the H264 video codec and AAC audio codec.

How to get mobile compatible clips from a channel's library

The mobile compatible clips can be obtained from any of the "latestclips", "listclips" or "clipdetails" methods in the Channel API.

The media rss returned contains a "<isMobileCompatible>" element specifying if the clip is mobile compatible or not.

Example media RSS:

http://xmashablex.api.channel.livestream.com/2.0/latestclips?maxresults=3

<rss xmlns:media="http://search.yahoo.com/mrss" xmlns:ls="http://api.channel.livestream.com/2.0" version="2.0">
  <channel>
    <title>MashableTV</title>
    <link>http://www.livestream.com/mashable</link>
    <description>Watch on iPad, Blackberry, Android, iPhone by visiting http://mobile.livestream.com/mashablemobile. Mashable is the top source for news and trends in digital media, technology and web culture. Our coverage includes curated and reported news stories, features, resourceful guides, reviews, and analysis of trends in the industry.</description>
    <image>
      <url>http://www.livestream.com/filestore/logos/e14fe191-f974-2bf9-c81c-0489bf14c888-small.png</url>

    </image>
    <language>English</language>
    <category>Science & Tech</category>
    <category_ad_name>science</category_ad_name>
    <pubDate>Wed, 20 Feb 2008 20:22:55 GMT</pubDate>
    <shareUrl>http://livestre.am/870</shareUrl>

    <ls:totalClips>43</ls:totalClips>
    <item>
      <title>Closing Keynote with Alec Ross (Secretary of State Hillary Clinton’s Senior Advisor for Innovation)</title>
      <description />
      <link>http://www.livestream.com/mashable/ondemand/pla_eba92bab-d578-4aae-84ad-981f67bf1b92</link>
      <guid>pla_eba92bab-d578-4aae-84ad-981f67bf1b92</guid>
      <ls:workflowStatus>Complete</ls:workflowStatus>

      <ls:isRecorded>true</ls:isRecorded>
      <ls:isMobileCompatible>true</ls:isMobileCompatible>
      <media:thumbnail url="http://www.livestream.com/filestore/user-files/chmashable/2010/06/08/23fd032c-6461-4ccf-ae8e-6af77d30f722_1.jpg" />
      <media:content duration="949.13" type="video/x-flv" url="http://www.livestream.com/mashable/ondemand/pla_eba92bab-d578-4aae-84ad-981f67bf1b92" />
      <pubDate>Tue, 08 Jun 2010 21:07:31 GMT</pubDate>
      <shareUrl>http://livestre.am/60id</shareUrl>
    </item>
  </channel>

</rss>



Requesting a mobile stream


To access the mobile-compatible stream of a channel, send an HTTP GET request to:

Request URL

http://[escaped url]/getstream

See here for information on how to form the escaped url.

Request parameters:

By default, this method will return the URL to access the channel's live stream, for all platforms.

The method supports the following optional HTTP parameters:

1. id - The clip id, if requesting the mobile stream URL for a specific on-demand clip. The clip id (guid) can be obtained from any of the "latestclips", "listclips" or "clipdetails" in the Channel API. If this parameter is ommited, this method will return the channel's live stream URL.

2. platform - The target mobile platform for which the mobile stream should be returned. Possible values:

  • iphone
  • android
  • blackberry
  • rtsp
  • http
  • all

Default value is "all".

3. targetBitrate - The target bitrate of the stream in kilo bits per seconds (kbps).

Example request for a channel's live stream:

http://xproshowcasex.channel-api.livestream-api.com/2.0/getstream

Example request for a specific clip:

http://xmashablex.api.channel.livestream.com/2.0/getstream?id=pla_2bc0bbfa-cc39-4f80-b9ef-376b97da94a4&targetBitrate=200

Response values:

The response contains the following elements:

1. isLive - Whether the channel is currently live or not.

2. currentViewerCount - The current number of viewers for this channel.

3. isMobileCompatible - Whether the channel's current live stream is mobile compatible or not. See How to publish a mobile compatible stream.

4. iPhoneUrl - The iPhone compatible stream URL.

5. androidUrl - The Android compatible stream URL.

6. blackberryUrl - The Blackberry compatible stream URL.

7. rtspUrl - The stream URL for devices supporting RTSP playback of H264/AAC streams.

8. HttpUrl - The stream URL for devices supporting Apple HTTP streaming (iPhone, iPad, iPod touch and QuickTime).

Example Response:

The response returned will be similar to the following RSS xml.

<?xml version="1.0" encoding="UTF-8"?>
<channel xmlns:ls="http://api.channel.livestream.com/2.0">
  <ls:isLive>false</ls:isLive>
  <ls:currentViewerCount>0</ls:currentViewerCount>
  <ls:isMobileCompatible>false</ls:isMobileCompatible>
  <ls:iPhoneUrl>http://xproshowcasex.is.channel.livestream.com/livestreamiphone/proshowcase/playlist.m3u8</ls:iPhoneUrl>
  <ls:androidUrl>rtsp://xproshowcasex.is.channel.livestream.com/livestreamiphone/proshowcase</ls:androidUrl>
  <ls:blackberryUrl>rtsp://xproshowcasex.is.channel.livestream.com/livestreamiphone/proshowcase</ls:blackberryUrl>
  <ls:rtspUrl>rtsp://xproshowcasex.is.channel.livestream.com/livestreamiphone/proshowcase</ls:rtspUrl>
  <ls:httpUrl>http://xproshowcasex.is.channel.livestream.com/livestreamiphone/proshowcase</ls:httpUrl>
</channel>



Example: Playing back a stream on the iPhone/iPad/Ipod


The following simple HTML code will show you how to embed an iPhone compatible stream on a page:

<html>
<body>
<h1>iPhone Example:</h1>
<video width="300" height="225" 
   src="http://xmashablex.is.channel.livestream.com/onDemand/ls/mashable/pla_2bc0bbfa-cc39-4f80-b9ef-376b97da94a4/playlist.m3u8" 
   poster="http://www.livestream.com/filestore/user-files/chmashable/2010/06/08/d333a646-94aa-4035-a66e-1185bd885622_1.jpg" 
   controls="" 
   autoplay="true" 
   tabindex="0">
</video>
</body>
</html>

Try it on your mobile here: http://cdn.livestream.com/examples/mobile/iphone.html




Example: Playing back a stream on the Android and Blackberry


The following simple HTML code will show you how to embed an Android/Blackberry compatible stream on a page:

<html>
<body>
<h1>Android Example:</h1>
<a href="rtsp://xmashablex.is.channel.livestream.com:1935/onDemand/ls/mashable/pla_2bc0bbfa-cc39-4f80-b9ef-376b97da94a4" id="thumbnail">
<img width="320" height="240" 
src="http://www.livestream.com/filestore/user-files/chmashable/2010/06/08/d333a646-94aa-4035-a66e-1185bd885622_1.jpg" 
alt="thumbnail" title="thumbnail"/>
</a><br>
Click image to play
</body>
</html>

Try it on your mobile here: http://cdn.livestream.com/examples/mobile/bb-android.html