Cisco StadiumVision Mobile API for Google Android
First Published: May 26, 2015
Revised: November 2, 2015
This chapter describes the Cisco StadiumVision Mobile SDK Release 2.1.1 for Google Android, and contains the following sections:
- Introduction to Cisco StadiumVision Mobile SDK for Android
- Cisco StadiumVision Mobile and Android Developer Tools
- Download and Unpack the SDK
- Get Started with the Android Demo App
- Cisco StadiumVision Mobile Methods and Functions for Android
- Add Cisco StadiumVision Mobile Services to an Android App—Code Structure and Samples
- Integrate EVS C-Cast
Introduction to Cisco StadiumVision Mobile SDK for Android
The Cisco StadiumVision Mobile Android SDK contains the following components bundled together:
- A set of static libraries, header files
- Demo app and SDK video player
- API documentation (Doxygen build)
The Cisco StadiumVision Mobile API uses Android and Java classes and method calls to access the StadiumVision Mobile data distribution and video playback functionality within the StadiumVision Mobile Android SDK library.
Mobile OS Support describes the mobile operating system versions supported by the Cisco StadiumVision Mobile SDK.
For additional information, refer to the Cisco StadiumVision Mobile Release Notes available from Cisco.com at:
http://www.cisco.com/c/en/us/support/video/stadiumvision/products-release-notes-list.html
Back to top of pageCisco StadiumVision Mobile and Android Developer Tools
Build Environment Requirements lists the various Android SDK build environment requirements.
Option 1: Android Studio Prerequisites
Note: Contact your Cisco account team for details about how to become part of the Cisco StadiumVision Mobile SDK partner program.
Option 2: Eclipse Prerequisites
Note: Existing Eclipse installations require the Eclipse JDT plug-in (included in most Eclipse IDE packages) and JDK 6 (JRE alone is not sufficient). For the latest requirements, refer to the Android Developer website.
- Download and install the Android Developer Tools (ADT) plug-in.
- Download and unpack/unzip the Android Stand-alone SDK Tools.
- Set up the ADT tools plug-in by completing the following:
- Launch Eclipse and when prompted select a folder to use as your workspace.
- Select Help > Install New Software. Click Add (top-right corner) and enter "ADT Plugin" in the name field and the following URL for the location: https://dl-ssl.google.com/android/eclipse/.
- Finish the installation, accept the license agreements, then restart Eclipse.
- In the "Welcome to Android Development" window that appears, select Use existing SDKs.
- Navigate to and select the location of the Android Stand-alone SDK Tools folder. Click Next.
- From the Window drop-down menu, launch the Android SDK Manager.
- Open the applicable Android folder and check the SDK Platform box. Deselect everything else, then install the applicable package as shown in Selecting the SDK Platform.
Download and Unpack the SDK
To download and unpack the SDK, complete the following steps:
If you do not have this file, contact your Cisco account team for details about how to become part of the Cisco StadiumVision Mobile SDK partner program.
- Extract the downloaded package into a directory. Refer to Cisco StadiumVision Mobile SDK File Content for a detailed list of file content.
Note: The clean.stream file that comes bundled with the SDK contains just one video channel. To provide app developers with additional ways to test multiple channels, an additional set of clean.stream files is available. For additional information refer to Testing Your Cisco StadiumVision Mobile App available on DevNet at:
https://developer.cisco.com/site/svm/learn/testing-your-cisco-stadiumvision-mobile-app/
Get Started with the Android Demo App
The Cisco StadiumVision Mobile SDK provided to app developers includes the source code for an Android demo app. The purpose of the demo app is to demonstrate what is possible and to enable a new app developer to quickly get a working app up and running. This section contains the following:
- Build the Demo App
- Customize the Demo App
- Embed the Cisco StadiumVision Mobile SDK in an Existing App
Note: Before creating a new app, review the Cisco StadiumVision Mobile SDK Best Practices at:
https://developer.cisco.com/site/svm/learn/best-practices/
Build the Demo App
There are two ways to build the Demo app depending on the tool you are using.
Option 1: Build the Demo App with Android Studio
To build the Sample app using Android Studio, complete the following steps:
<uses-sdk android:minSdkVersion="14" android:targetSdkVersion="14" />
<uses-sdk android:minSdkVersion=" 15 " android:targetSdkVersion=" 15 " />
- Import the Demo app into Android Studio.
- Open Android Studio .
- Under Quick Start , select Import project (Eclipse ADT, Gradle, etc.).
- Navigate to and select the Cisco StadiumVisionSample folder.
- Specify the Destination Directory in the Import Project from ADT (Eclipse Android) window that appears, then select Next .
- In the Import Project from ADT (Eclipse Android) window that appears, be sure all check boxes are selected, then select Finish .
- When the build is complete, an import-summary.txt file is automatically created. Review the file to verify files are mapped into Android Studio correctly.
- Review your Android Studio project structure, it should be similar to Android Studio Project Structure.
Option 2: Build the Demo App with Eclipse
To build the Sample app using Eclipse, complete the following steps:
- Import the Demo app project into Eclipse.
- Right-click CiscoStadiumVisionMobile in the left Package Explorer window, then select Android Tools > Export Signed Application Package .
Note: If you cannot complete the export due to build errors, check the Android path. Right-click on the Cisco StadiumVisionMobileSample in the left panel, select Build Path > Configure Build Path. In the Properties window that appears, select Android on the left, then select the check box next to the latest Target Name (for example Android 4.4.2) under Project Build Target. Click Apply, then OK. Restart Eclipse from File > Restart.
- Click Next when the Project Checks window appears.
- Select Create new keystore , then browse to a folder where you wish to store the key store file. Click Next .
- Fill in the Key Creation form (there are no right or wrong answers). Click Next .
- Browse to the folder where you wish to place the apk file, then click Finish .
- Download the apk file to your Android device by placing it on a web server, SD card, USB flash key, or by emailing it.
- Install the apk on your device.
Customize the Demo App
There are many ways to customize the Cisco StadiumVision Mobile Demo app, consider the following:
- Change the text for the app icon:
In the file "res/values/strings.xml" change "SVM Demo" to "My SVM App". - Change the name space so that your custom app can be installed side-by-side with the out-of-the-box demo app:
Edit the file "AndroidManifest.xml".
Note: The package name must start with "com" (excluding the quotes).
Embed the Cisco StadiumVision Mobile SDK in an Existing App
The Cisco StadiumVision Mobile SDK can be embedded into an existing app. This section contains information and examples to assist you in embedding SVM capabilities into a custom application:
- Integration Checklist
- Android Permissions
- SDK Java Libraries
- SDK Native Libraries
- Notify Life-Cycle Activity
- Configuration Files
- Wi-Fi AP Info Configuration
Integration Checklist
The following checklist is useful when you want to embed the Cisco StadiumVision Mobile SDK into an existing app:
|
|
|
|
|
|
Android Permissions
The following Android permissions are needed by the Cisco StadiumVision Mobile SDK. Each permission is set in the "AndroidManifest.xml" file.
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />
SDK Java Libraries
Each Java JAR library needs to be included in the Android app’s "libs" folder, as shown in the following example.
./libs/StadiumVisionMobile.jar
./libs/jackson-core-lgpl-1.8.1.jar
./libs/jackson-mapper-lgpl-1.8.1.jar
If using Android Studio, include the additional JAR library files listed here:
./libs/StadiumVisionMobileSender.jar
Back to top of page
SDK Native Libraries
Each library needs to be included in the Android app’s "libs/armeabi" folder.
./libs/armeabi/libvoAndroidVR_S23_OSMP.so
./libs/armeabi/libvoAudioMCDec_OSMP.so
./libs/armeabi/libvoIOMXDec_jb_OSMP.so
./libs/armeabi/libvoOSSource_OSMP.so
./libs/armeabi/libvompEngn_OSMP.so
./libs/armeabi/libvoAACDec_OSMP.so
./libs/armeabi/libvoAndroidVR_S40_OSMP.so
./libs/armeabi/libvoH264Dec_OSMP.so
./libs/armeabi/libvoIOMXDec_kk_OSMP.so
./libs/armeabi/libvoPushPDMgr_OSMP.so
./libs/armeabi/libvoAMediaCodec_OSMP.so
./libs/armeabi/libvoAndroidVR_S41_OSMP.so
./libs/armeabi/libvoH264Dec_v7_OSMP.so
./libs/armeabi/libvoTsParser_OSMP.so
./libs/armeabi/libvoAndroidVR_S16_OSMP.so
./libs/armeabi/libvoAndroidVR_S43_OSMP.so
./libs/armeabi/libvoH265Dec_v7_OSMP.so
./libs/armeabi/libvoMMCCRRS_OSMP.so
./libs/armeabi/libvoVersion_OSMP.so
./libs/armeabi/libvoAndroidVR_S20_OSMP.so
./libs/armeabi/libvoAndroidVR_S50_OSMP.so
./libs/armeabi/libvoIOMXDec_L_OSMP.so
./libs/armeabi/libvoMMCCRRS_v7_OSMP.so
./libs/armeabi/libvoVidDec_OSMP.so
./libs/armeabi/libvoAndroidVR_S22_OSMP.so
./libs/armeabi/libvoAudioFR_OSMP.so
./libs/armeabi/libvoIOMXDec_ics_OSMP.so
./libs/armeabi/libvoOSEng_OSMP.so
Back to top of page
Android Project Classpath
Your "classpath" file should look like the following example:
<?xml version="1.0" encoding="UTF-8"?>
<classpathentry kind="src" path="src"/>
<classpathentry kind="src" path="gen"/>
<classpathentry kind="con" path="com.android.ide.eclipse.adt.ANDROID_FRAMEWORK"/>
<classpathentry kind="lib" path="libs/httpclient-4.1.1.jar"/>
<classpathentry kind="lib" path="libs/httpcore-4.1.jar"/>
<classpathentry kind="lib" path="libs/httpmime-4.1.1.jar"/>
<classpathentry kind="lib" path="libs/jackson-core-lgpl-1.8.1.jar"/>
<classpathentry kind="lib" path="libs/jackson-mapper-lgpl-1.8.1.jar"/>
<classpathentry kind="lib" path="libs/StadiumVisionMobile.jar"/>
<classpathentry kind="output" path="bin"/>
Back to top of page
App Obfuscation Using ProGuard
If you choose to obfuscate your application with ProGuard, consider the following:
If a crash takes place that you would like Cisco to analyze, please run retrace.jar on the stack trace output with your map file before sending us the un-winded stack trace file.
- Specify libraries as input jars with "-libraryjars". Refer to the example below and remember to modify the paths as needed:
-libraryjars ./libs/httpclient-4.1.1.jar
-libraryjars ./libs/httpcore-4.1.jar
-libraryjars ./libs/httpmime-4.1.1.jar
-libraryjars ./libs/jackson-core-lgpl-1.8.1.jar
-libraryjars ./libs/jackson-mapper-lgpl-1.8.1.jar
-libraryjars ./libs/StadiumVisionMobile.jar
-libraryjars ./libs/StadiumVisionMobileSender.jar
If you extend or implement any of our classes or interfaces please specify that in the config file, as shown in the following example:
-keep public class * extends com.cisco.svm.data.ISVMDataObserver
Specify the following in the configuration file, to work with our JARS, as it prevents the StadiumVision Mobile JARS from being obfuscated:
-keep public class com.xxxxxx.vome.*
public protected private *;
}
-keep public class com.cisco.** { public protected private *; }
#for the Jackson library
-keepattributes *Annotation*,EnclosingMethod
-keepnames class org.codehaus.jackson.** { *; }
If ProGuard warns about "joda.org.time" and you have included the library as well as the configuration options above, you can ignore the warnings with the "–ignorewarnings" flag.
Cisco recommends that you do not obfuscate all of the classes that implement or extend the basic Android classes. The following ProGuard configuration is not meant to be a complete configuration, but rather a minimum:
-keep public class * extends android.app.Activity
-keep public class * extends android.app.Application
-keep public class * extends android.app.Service
-keep public class * extends android.content.BroadcastReceiver
-keep public class * extends android.content.ContentProvider
-keep public class * extends android.app.backup.BackupAgentHelper
-keep public class * extends android.preference.Preference
-keep public class com.android.vending.licensing.ILicensingService
-keepclasseswithmembernames class * {
native <methods>;
}
-keepclasseswithmembers class * {
public <init>(android.content.Context, android.util.AttributeSet);
}
-keepclasseswithmembers class * {
public <init>(android.content.Context, android.util.AttributeSet, int);
}
-keepclassmembers class * extends android.app.Activity {
public void *(android.view.View);
}
-keepclassmembers enum * {
public static **[] values();
public static ** valueOf(java.lang.String);
}
-keep class * implements android.os.Parcelable {
public static final android.os.Parcelable$Creator *;
}
Channel ListView Activity Example
The following example illustrates the following actions:
- Obtains the list of available video channels.
- Updates the Activity’s ListView with the channel list.
- Plays the video channel selected in the ListView.
// set the click listener for the list view
channelListView.setOnItemClickListener(new OnItemClickListener() {
public void onItemClick(AdapterView<?> parentView, View clickedView,
// get the selected video channel
SVMChannel selectedChannel = videoChannels[position];
Log.d(TAG, "Selected Video Channel = '" + selectedChannel.name);
// get a reference the StadiumVision Mobile SDK
StadiumVisionMobile svm = StadiumVisionMobile.getInstance();
// play the selected video channel with custom video player
intent.putExtra("channel", selectedChannel);
intent.setClass(MyActivity.this, MyVideoPlayer.class);
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
Notify Life-Cycle Activity
The client app needs to notify the StadiumVision Mobile SDK of it’s life-cycle notifications. This allows the StadiumVision Mobile SDK to automatically shutdown and restart as needed. Each client Activity needs to forward its life-cycle notifications, as shown in the following example:
import com.cisco.svm.app.StadiumVisionMobile;
// notify the cisco sdk of the life-cycle event
StadiumVisionMobile.onPause();
// notify the cisco sdk of the life-cycle event
StadiumVisionMobile.onResume();
Configuration Files
There are three configuration files that must be bundled with any Android app using the StadiumVision Mobile SDK (shown in Configuration Files).
An example set of fields in the cisco_svm.cfg file is shown below. These fields must match the channel settings in the Cisco "Streaming Server" for the channels to be accessible by the application.
"contentOwner": "Multi-Tenant Team-B",
Wi-Fi AP Info Configuration
The cisco_svm.cfg config file can optionally include an array of Wi-Fi AP information that will be used by the StadiumVision Mobile SDK for statistics reporting if available. Below is an example Wi-Fi AP info entry in the cisco_svm.cfg config file:
Cisco StadiumVision Mobile Methods and Functions for Android
This section provides detailed API return types, method names, and method descriptions:
- Cisco StadiumVision Mobile Android API Summary
- Return Status Object
- Video Player Activity API Summary
Note: Detailed API documentation is available in the Doxygen build that is downloaded with the SDK. Navigate to the html folder and double-click index.html to launch the documentation in a web browser.
Back to top of pageCisco StadiumVision Mobile Android API Summary
Cisco StadiumVision Mobile Android API Summary summarizes the Android API library.
Return Status Object
Each API call returns an ‘SVMStatus’ object whenever applicable. SVMStatus Object lists the SVMStatus object fields.
getStats API Hash Keys and Description lists the hash keys and stats description for the getStats API.
Video Player Activity API Summary
The SVMVideoPlayerActivity class can be extended and customized. Video Player Activity API Summary lists the SVMVideoPlayerActivity API methods and descriptions.
Add Cisco StadiumVision Mobile Services to an Android App—Code Structure and Samples
This section describes the SDK workflow and contains the following sections:
- Start the SDK
- Cisco StadiumVision Mobile Service Up or Down Indicator
- In-Venue Detection
- Set the SDK Configuration at Run-Time
- Scalable File Distribution
- Set SDK Configuration using setConfigWithString API Method
- Get the Available Streamer Servers
- Obtain Additional Statistics
- Detect Video Player "Channel Inactive" Callback
- Customize the Default Video Player
Start the SDK
Start the StadiumVision Mobile SDK from the application’s main Android launch Activity, as shown in the following example.
import com.cisco.svm.app.StadiumVisionMobile;
// app’s launch activity ‘onCreate’ notification
// start the StadiumVision Mobile SDK
Cisco StadiumVision Mobile Service Up or Down Indicator
The Cisco StadiumVision Mobile SDK includes an indicator to the application indicating if the SVM service is up or down. This indication should be used by the application to indicate to the user whether the SVM service is available or not. Service is declared 'down' by the SDK when any of the following are true:
- The SDK detects that the video quality is poor.
- The SDK detects that no valid, licensed channel are available.
- The mobile device’s Wi-Fi interface is disabled.
Poor video quality can occur when the user is receiving a weak Wi-Fi signal causing data loss. There are two different ways that the app can get the "Service State" from the SDK:
- Register to receive the "Service Up/Down" notifications.
- Fetch the current service state from the SDK on-demand.
When the app receives the "Service Down" notification, the SDK will supply a bitmap containing the reasons why the service was declared down by the SDK. The reasons bitmap is given in Service Down Notifications.
Note: For additional Service Down Notification details, refer to, review the Cisco StadiumVision Mobile SDK Best Practices at:
https://developer.cisco.com/site/svm/learn/best-practices/
Back to top of pageReceive "Service Up/Down" Notifications
The following example shows how to register and handle the "Service Up/Down" notifications from the SDK:
import com.cisco.svm.app.StadiumVisionMobile;
import com.cisco.svm.app.StadiumVisionMobile.SVMServiceState;
// define the service state broadcast receiver
private BroadcastReceiver serviceStateReceiver;
// create the service state broadcast receiver
serviceStateReceiver = new BroadcastReceiver() {
public void onReceive(Context context, Intent intent) {
Bundle bundle = intent.getExtras();
// get the service state from the bundle
SVMServiceState serviceState = (SVMServiceState)bundle.get(StadiumVisionMobile.SVM_SERVICE_STATE_VALUE_TAG);
// determine the service state
if (serviceState == SVMServiceState.SVM_SERVICE_STATE_UP) {
Log.i(TAG, "### SERVICE STATE: UP");
} else if (serviceState == SVMServiceState.SVM_SERVICE_STATE_DOWN) {
Log.i(TAG, "### SERVICE STATE: DOWN");
// get the service state changed reasons bitmap
int reasons = bundle.getInt(StadiumVisionMobile.SVM_SERVICE_STATE_CHANGED_REASONS_TAG);
// determine the reasons that the service state changed
if ((reasons & StadiumVisionMobile.SVM_SERVICE_STATE_DOWN_REASON_SDK_NOT_RUNNING) != 0) {
Log.i(TAG, "Reason for Service State Change: SDK NOT RUNNING");
} else if ((reasons & StadiumVisionMobile.SVM_SERVICE_STATE_DOWN_REASON_WIFI_DOWN) != 0) {
Log.i(TAG, "Reason for Service State Change: WIFI DOWN");
} else if ((reasons & StadiumVisionMobile.SVM_SERVICE_STATE_DOWN_REASON_NO_CHANNELS) != 0) {
Log.i(TAG, "Reason for Service State Change: NO CHANNELS AVAILABLE");
} else if ((reasons & StadiumVisionMobile.SVM_SERVICE_STATE_DOWN_REASON_POOR_QUALITY) != 0) {
Log.i(TAG, "Reason for Service State Change: POOR QUALITY");
// register to receive the service state intents
IntentFilter serviceStateIntentFilter = new IntentFilter();
serviceStateIntentFilter.addAction(StadiumVisionMobile.SVM_SERVICE_STATE_CHANGED_INTENT_TAG);
registerReceiver(serviceStateReceiver, serviceStateIntentFilter);
Getting the Current "Service Up/Down" State On-Demand
The "getServiceState" API method can be used to fetch the current service state from the SDK. The following example shows how to fetch the current service state from the SDK using the "getServiceState" API call:
import com.cisco.svm.app.StadiumVisionMobile;
import com.cisco.svm.app.StadiumVisionMobile.SVMServiceState;
// get the current svm service state
SVMServiceState serviceState = StadiumVisionMobile.getServiceState();
// determine the current service state
if (serviceState == SVMServiceState.SVM_SERVICE_STATE_UP) {
Log.i(TAG, "### SERVICE STATE: UP");
} else if (serviceState == SVMServiceState.SVM_SERVICE_STATE_DOWN) {
Log.i(TAG, "### SERVICE STATE: DOWN");
In-Venue Detection
Beginning in Cisco StadiumVision Mobile Release 2.0, the SDK provides a mechanism to detect whether the mobile device is connected within the SVM-enabled venue or not.
There are two different ways that the Android app can get this "In-Venue Detection" state from the SDK:
- Register to receive the "In-Venue Detection" notifications.
- Fetch the current "In-Venue" state from the SDK on-demand.
Receiving "In-Venue Detection" Notifications
The following example shows how to register and handle the "Service Up/Down" notifications from the SDK:
import com.cisco.svm.app.StadiumVisionMobile;
// define the 'in-venue status changed' broadcast receiver
private BroadcastReceiver inVenueReceiver;
// handle the venue connection changed event
venueConnectionReceiver = new BroadcastReceiver() {
public void onReceive(Context context, Intent intent) {
String action = intent.getAction();
// determine whether the device is inside or outside of the venue
if (action.equals(StadiumVisionMobile.SVM_VENUE_CONNECTED_INTENT_TAG)) {
Log.i(TAG, "##### App Received 'VENUE-CONNECTED' Notification");
} else if (action.equals(StadiumVisionMobile.SVM_VENUE_DISCONNECTED_INTENT_TAG)) {
Log.i(TAG, "##### App Received 'VENUE-DISCONNECTED' Notification");
// register to receive the venue connected / disconnected intents
IntentFilter inVenueIntentFilter = new IntentFilter();
inVenueIntentFilter.addAction(StadiumVisionMobile.SVM_VENUE_CONNECTED_INTENT_TAG);
inVenueIntentFilter.addAction(StadiumVisionMobile.SVM_VENUE_DISCONNECTED_INTENT_TAG);
registerReceiver(venueConnectionReceiver, inVenueIntentFilter);
Getting the Current "In-Venue" State On-Demand
The "isConnectedToVenue" API method can be used to fetch the current in-venue state from the SDK. The following example shows how to fetch the current service state from the SDK using the "isConnectedToVenue" API call:
import com.cisco.svm.app.StadiumVisionMobile;
// get whether the device is currently connected to the SVM licensed venue
boolean isConnectedToVenue = StadiumVisionMobile.isConnectedToVenue();
// log whether the device is currently connected to the SVM licensed venue
Log.i(TAG, "### Connected to the venue: " + (isConnectedToVenue ? "YES" : "NO"));
Set the SDK Configuration at Run-Time
Previously, the Cisco StadiumVision Mobile SDK could only be configured by using a JSON-formatted config file ("cisco_svm.cfg") bundled within the Android app. Beginning in Release 1.3, the application can set the SDK configuration at run-time through an API method. This allows the application to dynamically configure the SDK. For example, the application can fetch the SDK configuration information from a network connection, and then pass that configuration to the SDK.
Two different ways to set the SDK configuration at run-time:
The signature of the "setConfig" API method is given below:
// configure the sdk using a JSON object containing the configuration settings
public static SVMStatus setConfig(JSONObject givenJsonConfig)
// configure the sdk using an nsdictionary containing the configuration settings
The signature of the "setConfigWithString" API method is given below:
// configure the sdk using a json-formated string containing the configuration settings
public static SVMStatus setConfigWithString(String jsonConfigStr)
The following example shows how to set the SDK configuration using the "setConfigWithString" API method:
// create the json config string
" \"venueName\": \"MyVenueNameKey\","
" \"contentOwner\": \"MyContentOwnerKey\","
Scalable File Distribution
Scalable File Distribution and Service API Summary lists the Cisco StadiumVision Mobile scalable file distribution API.
Data Channels
Data Distribution and Service API Summary lists the Cisco StadiumVision Mobile data channel APIs.
Get the SDK Configuration
"getConfig" API Method
The signature of the "getConfig" API method is given below:
// get the current cisco sdk configuration
public static JSONObject getConfig()
The example below fetches the current configuration from the SDK, and then accesses the configuration values in the configuration JSON object:
// get the sdk configuration dictionary
JSONObject configObj = StadiumVisionMobile.getConfig();
// get the license dictionary from the config dictionary
licenseObj = configObj.getJSONObject("license");
// if the license object is valid
// get the current set of configured license keys
String venueName = licenseObj.getString("venueName");
String contentOwner = licenseObj.getString("contentOwner");
String appDeveloper = licenseObj.getString("appDeveloper");
Back to top of pageThe following example shows how to set the SDK configuration using the "setConfig" API method:
// create the config json object with the set of licensing keys
JSONObject jsonConfig = new JSONObject();
JSONObject licenseConfig = new JSONObject();
licenseConfig.put("venueName", "MyVenueNameKey");
licenseConfig.put("contentOwner", "MyContentOwnerKey");
licenseConfig.put("appDeveloper", "MyAppDeveloperKey");
jsonConfig.put("license", licenseConfig);
Log.e(TAG, "Error building the json config object");
// update the cisco sdk configuration at run-time
StadiumVisionMobile.setConfig(jsonConfig);
Set SDK Configuration using setConfigWithString API Method
The signature of the "setConfigWithString" API method is given below:
// configure the sdk using a json-formated string containing the configuration settings
public static SVMStatus setConfigWithString(String jsonConfigStr)
The following example shows how to set the SDK configuration using the "setConfigWithString" API method:
// create the cisco sdk json configuration string
" \"venueName\": \"MyVenueNameKey\"," +
" \"contentOwner\": \"MyContentOwnerKey\"," +
" \"appDeveloper\": \"MyAppDeveloperKey\"" +
// update the cisco sdk configuration at run-time
Get the Available Streamer Servers
The Android SDK detects the available Streamer servers and provides an API to get the list of servers. A venue will typically have only a single Streamer server. The list is presented as an array of "SVMStreamer" objects.
There are two different methods available that present the "SVMStreamer" objects in either a Java array or ArrayList collection. The signatures for the two API methods are given below:
// get the detected streamer servers as a java array of "SVMStreamer" objects
public static SVMStreamer[] getStreamerArray()
// get the detected streamer servers as a java ArrayList of "SVMStreamer" objects
public static ArrayList<SVMStreamer> getStreamerArrayList()
Each "SVMStreamer" object contains the following properties listed in SVMStreamer Object Properties.
|
Whether this StadiumVision Mobile Streamer server is allowed by the user of this SDK. |
||
The following example shows how to get the list of StadiumVision Mobile Streamer servers detected by the SDK:
// get the list of currently available streamer servers
ArrayList<SVMStreamer> streamerList = StadiumVisionMobile.getStreamerArrayList();
// iterate through the list of streamer objects
for (SVMStreamer nextStreamer: streamerList) {
// get the properties of the next streamer server object
String ipAddress = nextStreamer.getIpAddress();
String statsUploadUrl = nextStreamer.getStatsUploadUrl();
int statsSampleIntervalMs = nextStreamer.getStatsSampleIntervalMs();
int statsPublishIntervalMs = nextStreamer.getStatsPublishIntervalMs();
boolean isAllowed = nextStreamer.isAllowed();
Obtain Additional Statistics
Beginning in Cisco StadiumVision Mobile Release 2.0 SDK, the existing "stats" API call returns the following additional categories of stats information:
The signature of the existing "getStats" API method is given below:
// get the current set of cisco sdk stats as a hashmap
public static HashMap<String, String> getStats()
Note: For a detailed table of the hash keys and stats description for the getStats API refer to getStats API Hash Keys and Description.
StatsManager Dictionary Keys details the StatsManager dictionary keys and descriptions.
|
Number of Reporter stat manager errors other than upload issues (for example, stat generation failures). |
|
Receive Video Player State Notifications
Beginning in Release 1.3, the SDK generates broadcast Intent notifications for each of the video player state transitions (listed in Video Player State Notification). The application can listen to these notifications and take action based on the video player’s state transitions.
|
Occurs when the video player closes the video channel session. |
|
|
Occurs when the video player starts playing the video channel. |
|
The following example shows how to subscribe to receive the video player Intent broadcast messages, and then parse the messages for the (1) channel name and (2) video player state:
// create the channel state change broadcast receiver
channelStateReceiver = new BroadcastReceiver() {
public void onReceive(Context context, Intent intent) {
String action = intent.getAction();
Bundle bundle = intent.getExtras();
// determine the broadcast intent type
if (action.equals(StadiumVisionMobile.SVM_CHANNEL_STATE_CHANGED_INTENT_TAG)) {
// get the updated channel name and state info
String channelName = (String)bundle.get(StadiumVisionMobile.SVM_CHANNEL_NAME_VALUE_TAG);
String channelState = (String)bundle.get(StadiumVisionMobile.SVM_CHANNEL_STATE_VALUE_TAG);
// determine the channel state
if (channelState.equals(StadiumVisionMobile.SVM_VIDEO_PLAYING_STATE) == true) {
IntentFilter channelStateReceiverIntentFilter = new IntentFilter();
channelStateReceiverIntentFilter.addAction(StadiumVisionMobile.SVM_CHANNEL_STATE_CHANGED_INTENT_TAG);
context.registerReceiver(channelStateReceiver, channelStateReceiverIntentFilter);
Detect Video Player "Channel Inactive" Callback
To detect that a currently playing video channel has become invalid (due to Streamer server admin changes), the SVM video player ("SVMVideoPlayerActivity") provides a callback to tell the video player sub-class (ie: "MyVideoPlayerActivity") that the currently playing channel is no longer valid.
When a channel becomes invalid, playback of the video channel is automatically stopped.
To receive these callbacks, the "onCurrentChannelInvalid" method must be overridden by the ‘SVMVideoPlayerActivity’ sub-class (ie: "MyVideoPlayerActivity"). The following example shows the method signature and implementation of this overridden callback method:
protected void onCurrentChannelInvalid() {
super.onCurrentChannelInvalid();
* This "MyVideoPlayerActivity" implements the following app-specific
* behavior when receiving the 'onCurrentChannelInvalid' callback
* 2) Display a toast message describing why video playback was stopped
* 3) Dismiss the video player Activity
// display a notification that the channel is no longer valid
Toast.makeText(this, "\nChannel is no longer valid and the video player has been stopped\n", Toast.LENGTH_LONG).show();
// exit this video player activity now
Customize the Default Video Player
This section describes how to customize the default video player. The default Cisco video player has the following features:
- Implements a separate Android "Activity."
- Supports fullscreen and partial-screen video views.
- Renders video frames using an Android "SurfaceView."
- Extends the "SVMVideoPlayerActivity" class thereby allowing for customization.
Cisco Demo Video Player
- Implemented as "MyVideoPlayerActivity."
- Extends the "SVMVideoPlayerActivity" class.
- Handles all video overlays and gestures.
- Uses standard Android XML layout files ("layout/player.xml").
The video player’s XML layout file defines:
- "SurfaceView" video rendering area.
- Transparent video overlays.
- Play/Pause/Rewind button graphic files.
- Animations used to show/hide the transport controller.
The customized video play extends the "SVMVideoPlayerActivity" base class, as shown below:
import com.cisco.sv.media.SVMVideoPlayerActivity;
public class MyVideoPlayer extends SVMVideoPlayerActivity {
You need to register the new custom Activity in "AndroidManifest.xml", as shown below:
<activity android:label="@string/app_name"
android:name="com.company.MyVideoPlayer"
android:screenOrientation="landscape"
android:configChanges="orientation|keyboardHidden"
android:theme="@android:style/Theme.NoTitleBar.Fullscreen">
Video Channels
This section describes the Cisco StadiumVision Mobile SDK video channels and contains the following sections:
- Getting the Video Channel List
- Presenting the Video Channel List
- Playing a Video Channel
- Seeking Within the Video Buffer
- Setting the Video Dimensions
Getting the Video Channel List
The StadiumVision Mobile SDK dynamically receives all of the available channels (via Wi-Fi multicast). The client application gets an array of channel objects (SVMChannel[]) through the "getVideoChannelArray" API call, as shown in the following example:
import com.cisco.svm.app.StadiumVisionMobile;
// get the list of available video channels
SVMChannel[] channels = StadiumVisionMobile.getVideoChannelArray();
// display some channel information
Log.d(TAG, "Channel Name = " + channels[0].name);
Log.d(TAG, "Channel Bandwidth = " + channels[0].bandwidthKbps);
Presenting the Video Channel List
Each "SVMChannel" video channel object contains all of the information needed to display the channel list to the user. The SVMChannelObject properties and descriptions are shown in SVMChannel Object Properties.
Playing a Video Channel
The following example shows playing a video channel, and performs the following actions:
- Selects a channel from the locally saved channel list.
- Starts video playback of the channel by launching the custom video player Activity ("MyVideoPlayer").
Note: The "SVMChannel" object is parcelable (instances can be written to and restored from a parcel).
Seeking Within the Video Buffer
The last 30 seconds of played video is stored in device RAM. The following example shows jumping backwards 20 seconds in the video buffer (instant replay):
public class MyVideoPlayerActivity extends SVMVideoPlayerActivity {
// seek backwards 20 seconds in the video buffer
The following example shows jumping back to the top of the video buffer ("live" video playback):
public class MyVideoPlayerActivity extends SVMVideoPlayerActivity {
// seek to the top of the video buffer (0 ms offset)
Setting the Video Dimensions
The video region is rendered within a SurfaceView. The video region is configured using standard Android layout XML files. The video region can be set to full screen or to specific pixel dimensions.
Fullscreen Video Layout
The XML layout file below shows how to configure the video ‘SurfaceView’ to fill the entire screen, as shown in the following example:
<?xml version="1.0" encoding="utf-8"?>
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:background="@drawable/black">
android:id="@+id/videoSurfaceView"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:layout_centerInParent="true">
Partial-Screen Video Layout
The XML layout file below shows how to configure the video ‘SurfaceView’ to specific pixel region, as shown in the following example:
<?xml version="1.0" encoding="utf-8"?>
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:background="@drawable/black">
android:id="@+id/videoSurfaceView"
android:layout_centerInParent="true">
Data Channels
This section describes the Cisco StadiumVision Mobile SDK data channels and contains the following sections:
Getting the Data Channel List
The StadiumVision Mobile SDK dynamically receives all of the available data channels (via Wi-Fi multicast). The client application gets an array of channel objects (SVMChannel[]) through the "getDataChannelArray&qquot; API call, as shown in the following example:
import com.cisco.svm.app.StadiumVisionMobile;
// get the list of available data channels
SVMChannel[] channels = StadiumVisionMobile.getDataChannelArray();
// display some channel information
Log.d(TAG, "Channel Name = " + channels[0].name);
Log.d(TAG, "Channel Bandwidth = " + channels[0].bandwidthKbps);
Log.d(TAG, "Channel Body Text = " + channels[0].bodyText);
Observing a Data Channel
Any data channel can be observed by registering a class to receive callbacks for all data received on that channel. The registered class needs to implement the "ISVMDataObserver" interface, as shown in the following example:
import com.cisco.svm.data.ISVMDataObserver;
public class MyDataViewerActivity extends Activity implements ISVMDataObserver {
The "onData" method is called to push the received data to the registered class, as shown in the following example:
public void onData(String channelName, byte[] data) {
// display the received data parameters
Log.d(TAG, "DATA CALLBACK: " +
"channel name = " + channelName + ", " +
"data length = " + data.length);
Audio Channels
This section describes the Cisco StadiumVision Mobile SDK audio channels and contains the following sections:
Getting the Audio Channel List
Cisco StadiumVision Mobile supports audio-only channels, in a similar manner as video channels.
Here is an example to get a reference to the audio manager from the SDK:
import com.cisco.svm.audio.SVMAudioManager;
SVMAudioManager audioManager = StadiumVisionMobile.getAudioManager();
The application starts the audio channels by invoking:
audioManager.startAudioChannel(selectedChannel);
audioManager.stopAudioChannel();
Audio channels will continue to play while other activities are active. However audio channels will stop playing when the application enters background unless the following is entered:
SVMAudioManager audioManager = StadiumVisionMobile.getAudioManager();
audioManager.enableBackgroundAudio ();
Activities can check to see if audio is playing using isAudioActive () as shown in the following example:
if (audioManager.isAudioActive()) {
Available audio channels are discovered the same way that video channels are discovered, as shown in the following example:
SVMChannel[] channels = StadiumVisionMobile.getAudioChannelArray();
Integrate EVS C-Cast
Note: Cisco StadiumVision Mobile is supported with EVS C-Cast version 2.x only. EVS C-Cast version 3.x is not supported.
The steps below describe a high level workflow of how a Cisco StadiumVision Mobile powered C-Cast app gains access to the XML timeline and media files.
-
Register a BroadcastReceiver to be notified when a file channel becomes available using
public Intent registerReceiver (BroadcastReceiver receiver, IntentFilter filter) - Register to receive the channel notification using
public static com.cisco.svm.app.SVMStatus addFileChannelObserver (com.cisco.svm.channel.SVMChannel fileChannel, com.cisco.svm.file.ISVMFileObserver observer) - Handle the file reception (movies/thumbnails /timeline) using
public void onFile (String channelName, String fileName,Integer fileState) - Check to see if a file channel is already available, using getFileChannelListArray.
- If a channel is already available, or when a callback notification is received, register a file channel observer, using
addFileChannelObserver - Check to see if a file named ccast-timeline.xml is already available, using
getFileDistributionLocalFilename - If the ccast-timeline.xml is not yet available, wait for additional files to arrive using onFile(). Each time onFile() is called, do a corresponding check with getFileDistributionLocalFilename to see if the new file is ccast-timeline.xml.
- Once the ccast-timeline.xml file has been received, parse it using the steps in chapter 5 (How to build the media path) of the C-Cast API spec, and then build the media path for all media files.
- For each file media path, remove the path prefix so that only the filename remains. For example:
http://www.mydomain.com/videos/abc/def/ghi/abcdefghijklmnopqrstuvwxyz123456_hls-ipad.m3u8
becomes
abcdefghijklmnopqrstuvwxyz123456_hls-ipad.m3u8 - For each filename, cycle through onFile() and getFileDistributionLocalFilename until all files have been received.
- Be prepared for the ccast-timeline.xml file to change at any time and repeat steps 6-8 whenever it changes.