The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
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.
The Cisco StadiumVision Mobile client application supports Android 2.1 or later.
Build Environment Requirments
Table 2-1 lists the various Android SDK build environment requirements.
Table 2-1 Build Environment Requirements
|
|
|
|
---|---|---|---|
Mac or Windows PC |
|||
Eclipse |
3.7.1 (Indigo) |
Eclipse "Classic" for Mac OSX (64-bit) |
http://www.eclipse.org/downloads/ |
The Cisco StadiumVision Mobile Android SDK contains the following components:
•A set of static libraries, configuration files, player layout XML files, and a sample Android application.
•Customizable video player
Figure 2-1 describes the three main Android API classes used in Cisco StadiumVision Mobile. The top-level StadiumVisionMobile class acts as a custom Android application context. An application context is a structure created within a screen or activity. There is no global state across an Android application.
Each SDK API method is called using the StadiumVisionMobileMETHOD-NAME class. The SVMVideoPlayerActivity class is a customizable stand-alone video player.
Figure 2-1 StadiumVision Mobile Class
Figure 2-2 depicts the Android OS with regard to Activities. An Activity represents both the screen layout and controller code. A new Activity is launched by sending an Intent to the Android OS. An intent is a message to Android OS to launch a particular activity. Extra parameters contained in an Intent and are passed to an Activity. The back button is a hard device button used to generically display the previous Activity, and moves back down the Activity stack.
Figure 2-2 Android Activity Overview
Figure 2-3 depicts the Activity inheritance between the Android OS, Cisco StadiumVision Mobile, and the client application.
Figure 2-3 Android Video Player Activity Inheritance
Table 2-2 summarizes the Android API library. Following the summary are detailed tables for each API call.
Table 2-2 Cisco StadiumVision Mobile Android API Summary
The following tables describe each API call in more detail, including example usage.
Each API call returns an `SVMStatus' object whenever applicable. Table 2-3 lists the SVMStatus object fields.
Table 2-3 SVMStatus Object
Table 2-4 Start
Table 2-5 getVideoChannelArray
|
public static SVMChannel[] getVideoChannelArray(); |
---|---|
|
N/A |
|
This method returns a Java array of available video channels as 'SVMChannel' objects. |
|
N/A |
Table 2-6 getDataChannelArrayList
Table 2-7 addDataChannelObserver
Figure 2-4 onData
Table 2-8 removeDataChannelObserver
Table 2-9 getStats
|
public static HashMap<String, String> getStats(); |
---|---|
|
N/A |
|
This method returns the StadiumVision Mobile SDK stats as a hash of name / value pairs. |
|
N/A |
Table 2-10 lists the hash keys and stats description for the getStats API.
Table 2-10 getStats API Hash Keys and Stats Description
Table 2-11 onPause
Table 2-12 onResume
Table 2-13 getWifiInfo
Table 2-14 getBatteryInfo
Table 2-15 getLogLevelArray
|
public static String[] getLogLevelArray(); |
---|---|
|
N/A |
|
This method provides a Java array of available logging levels that can be applied to any component. |
|
N/A |
Table 2-16 getLogLevelArrayList
Table 2-17 setLogLevel
Table 2-18 getLocalIpAddress
|
public static String getLocalIpAddress(); |
---|---|
|
N/A |
|
This method returns this device's local IP address. |
|
N/A |
Table 2-19 getDeviceUUID
Table 2-20 getAppSessionUUID
Table 2-21 sdkVersion
|
|
---|---|
|
N/A |
|
This class property contains StadiumVision Mobile SDK version string. |
|
N/A |
The SVMVideoPlayerActivity class can be extended and customized. Table 2-22 lists the SVMVideoPlayerActivity API methods.
Table 2-22 Video Player Activity API Summary
Table 2-23 setVideoSurfaceView
|
public static String sdkVersion; |
---|---|
|
N/A |
|
This class property contains StadiumVision Mobile SDK version string. |
|
|
|
N/A |
Table 2-24 seekRelative
Table 2-25 seekAbsolute
Table 2-26 rewindForDuration
Table 2-27 playLive
Table 2-28 shutdown
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
void onCreate() {
// call the parent method
super.onCreate();
// start the StadiumVision Mobile SDK
StadiumVisionMobile.start();
}
The StadiumVision Mobile SDK dynamically receives all of the available channels (via WiFi 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);
Log.d(TAG, "Channel Body Text = " + channels[0].bodyText);
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 Table 2-29.
Table 2-29 SVMChannel Object Properties
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).
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
super.seekRelative(-20000);
}
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)
super.seekAbsolute(0);
}
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
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"?>
<RelativeLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:background="@drawable/black">
<SurfaceView
android:id="@+id/videoSurfaceView"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:layout_centerInParent="true">
</SurfaceView>
</RelativeLayout>
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"?>
<RelativeLayout
xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
android:background="@drawable/black">
<SurfaceView
android:id="@+id/videoSurfaceView"
android:layout_width="320px"
android:layout_height="240px"
android:layout_centerInParent="true">
</SurfaceView>
</RelativeLayout>
The StadiumVision Mobile SDK dynamically receives all of the available data channels (via WiFi multicast). The client application gets an array of channel objects (SVMChannel[]) through the "getDataChannelArray" 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);
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);
}
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;
void onPause() {
// notify the cisco sdk of the life-cycle event
StadiumVisionMobile.onPause();
}
void onResume() {
// notify the cisco sdk of the life-cycle event
StadiumVisionMobile.onResume();
This section describes customizing the video player.
Default Cisco Video Player
The default Cisco video player has the following features:
•Implemented as a separate Android "Activity"
•Supports fullscreen and partial-screen video views
•Renders video frames using an Android "SurfaceView"
•Customizable by extending the "SVMVideoPlayerActivity" class
•Uses a customized video player
Figure 2-5 Default Cisco Video Player
The customized video play extends the "SVMVideoPlayerActivity" base class, as shown below:
import com.cisco.sv.media.SVMVideoPlayerActivity;
public class MyVideoPlayer extends SVMVideoPlayerActivity {
}
Figure 2-6 SVMVideoPlayerActivity API
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">
</activity>
The 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:
•The "SurfaceView" video rendering area
•Any transparent video overlays
•Play / Pause / Rewind button graphic files
•Animations used to show / hide the transport controller
The following section describes the required configuration.
There are three configuration files that must be bundled with any Android app using the StadiumVision Mobile SDK.
Table 2-30 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.
{
"license": {
"venueName": "Stadium-A",
"contentOwner": "Multi-Tenant Team-B",
"appDeveloper": "Vendor-C"
}
}
The "cisco_svm.cfg" config file can optionally include an array of WiFi AP information that will be used by the StadiumVision Mobile SDK for statistics reporting if available. Below is an example WiFi AP info entry in the "cisco_svm.cfg" config file:
{
"network": {
"wifiApInfo": [
{
"name": "Press Box Booth 5",
"bssid": "04:C5:A4:09:55:70"
}
]
}
}
This section describes customizing the StadiumVision Mobile application, and contains the following subsections:
•Cisco StadiumVision Mobile Android API Summary12
Figure 2-7 Cisco StadiumVision Mobile Integration Overview
1. Supported Android OS Version
–Set the app's Android version target to v2.1u1 or above
2. Android App Permissions
–Add the required permissions to "AndroidManifest.xml"
3. Copy Config Files
–Add the config files to the app's "assets" folder
4. Copy Libraries
–Add the Java and native libraries to the app's "libs" folder
5. Set a Video "SurfaceView"
–Add a "SurfaceView" to the player Activity's layout XML file
6. Life-Cycle Notifications
–Forward life-cycle notifications to the StadiumVision Mobile SDK
7. Android Project Build Paths
–Set the project build path to include the Jar files in "./libs/"
Figure 2-8 illustrates the roles of the customer application. The application must specify:
•Getting the list of video channels
•Displaying the list of video channels
•Handling user gestures for selecting video channels
•Adding video overlays and layouts
•Handling user gestures to control video overlay
Figure 2-8 Customer Application Responsibilities
The following Android permissions are needed by the 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" />
Each Java JAR library needs to be included in the Android app's "libs" folder, as shown in the following example.
•Cisco StadiumVision Mobile Android SDK
•Apache HTTP Client 4.1
•Jackson JSON 1.8.1
./libs/StadiumVisionMobile.jar
./libs/httpclient-4.1.1.jar
./libs/httpcore-4.1.jar
./libs/httpmime-4.1.1.jar
./libs/jackson-core-lgpl-1.8.1.jar
./libs/jackson-mapper-lgpl-1.8.1.jar
Each library needs to be included in the Android app's "libs/armeabi" folder.
./libs/armeabi/libsvm-android.a
./libs/armeabi/libvoAACDec.so
./libs/armeabi/libvoAACDec_v7.so
./libs/armeabi/libvoH264Dec.so
./libs/armeabi/libvoH264Dec_v7.so
./libs/armeabi/libvoLiveSrcCTS.so
./libs/armeabi/libvoLiveSrcCTS_v7.so
./libs/armeabi/libvoMMCCRRS.so
./libs/armeabi/libvoMMCCRRS_v7.so
./libs/armeabi/libvoTsParser.so
./libs/armeabi/libvoTsParser_v7.so
./libs/armeabi/libvoVidDec.so
./libs/armeabi/libvojni_svmobile.so
./libs/armeabi/libvojni_vome2_sw_v20.so
./libs/armeabi/libvojni_vome2_sw_v22.so
./libs/armeabi/libvojni_vome2_sw_v23.so
./libs/armeabi/libvojni_vome2_sw_v30.so
./libs/armeabi/libvojni_vome2_sw_v31.so
./libs/armeabi/libvompEngn.so
Android Project Classpath
To add Java JAR files to your Eclipse project, use the following steps:
Step 1 Right-click your project in Eclipse
Step 2 Select "Properties"
Step 3 Select "Java Build Properties"
Step 4 Select "Add JARs"
Step 5 Add each of the Java JAR files listed in Adding Java JAR Files in Eclipse14.
Figure 2-9 Adding Java JAR Files in Eclipse
Your "classpath" file should look like the following example:
<?xml version="1.0" encoding="UTF-8"?>
<classpath>
<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"/>
</classpath>
App Obfuscation Using ProGuard
If you choose to obfuscate your application with ProGuard, consider the following points:
•Use the latest version of ProGuard (which is version 4.7 as of August, 2012)
•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 our libraries as input jars with "-libraryjars". See 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 complains 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 not obfuscating all 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:
•Periodically obtains the list of available video channels
•Updatse 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,
int position, long id) {
// 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 intent = new Intent();
intent.putExtra("channel", selectedChannel);
intent.setClass(MyActivity.this, MyVideoPlayer.class);
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
startActivity(intent);
}
});