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.
This chapter describes the Cisco StadiumVision Mobile SDK Release 2.1 for Google Android, and contains the following sections:
– Embed the Cisco StadiumVision Mobile SDK in an Existing App
The Cisco StadiumVision Mobile Android SDK contains the following components bundled together:
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.
Table 3-1 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
Table 3-2 lists the various Android SDK build environment requirements.
|
|
|
|
---|---|---|---|
https://eclipse.org/downloads/packages/eclipse-classic-372/indigosr2 |
|||
https://developer.android.com/sdk/installing/installing-adt.html |
|||
Basic tools for app development for use without an Integrated Development Environment (IDE). |
Note There are many different methods and platforms to use when developing and testing apps for Google Android. Android Studio is an Integrated Development Environment (IDE) that is available, however please note we have not tested using this tool. For additional IDE details and information, go to:
– Eclipse version 3.7.2 is available at:
https://eclipse.org/downloads/packages/eclipse-classic-372/indigosr2
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:
https://developer.android.com/sdk/installing/installing-adt.html
https://developer.android.com/sdk/installing/installing-adt.html
https://developer.android.com/sdk/installing/index.html
– Launch Eclipse and when prompted select a folder to use as your workspace.
– In Eclipse 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 selected package as shown in Figure 3-1:
Note Cisco StadiumVision Mobile supports Android 4.0 (API 14) and higher.
Figure 3-1 Selecting the SDK Platform Box
Step 1 Download StadiumVisionMobileSample-Android-VERSION.tar.bz2. If you do not have this file, contact your Cisco account team for details as to how to become part of the Cisco StadiumVision Mobile SDK partner program.
Step 2 Extract the downloaded package into a directory. Table 3-3 lists the extracted content and includes a brief description.
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” section.
Step 3 Open the API documentation available in the Doxygen build that is downloaded with the SDK. Navigate to the extracted folder contents, open the html folder > double-click index.html to launch the documentation in a web browser.
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.
Note Before creating a new app, review the Cisco StadiumVision Mobile SDK Best Practices.
Step 1 Import the demo app project into Eclipse as follows:
a. In Eclipse go to File > Import.
b. Go to General > Existing Projects into Workspace, then select Next.
c. Click Browse to Select the root directory and navigate to the folder where you unpacked the Cisco StadiumVision Mobile SDK, then click Finish.
d. Restart Eclipse from File > Restart.
Step 2 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.
Step 3 Click Next when the Project Checks window appears.
Step 4 Select Create new keystore, then browse to a folder where you wish to store the key store file. Click Next.
Step 5 Fill in the Key Creation form (there are no right or wrong answers). Click Next.
Step 6 Browse to the folder where you wish to place the apk file, then click Finish.
Step 7 Download the apk file to your Android device by placing it on a web server, emailing it, SD card, or USB flash key, etc.
Step 8 Install the apk on your device.
Here are some of the first items you may want to customize in the demo app:
– Change "package="com.cisco.sv"" to "package="com.cisco.svm.foo""
– Change "android:name="com.cisco.svm.app.StadiumVisionMobile"" to "android:name="com.cisco.svm.foo""
Note The package name must start with "com" (excluding the quotes).
The following table outlines the integration steps for embedding Cisco StadiumVision Mobile SDK into an existing app:
The following Android permissions are needed by the StadiumVision Mobile SDK. Each permission is set in the "AndroidManifest.xml" file.
Each Java JAR library needs to be included in the Android app’s "libs" folder, as shown in the following example.
Each library needs to be included in the Android app’s "libs/armeabi" folder.
To add Java JAR files to your Eclipse project, complete the following steps:
Step 1 Right-click your project in Eclipse.
Step 2 Select Properties > Java Build Properties.
Step 4 Add each of the Java JAR files listed in Adding Java JAR Files in Eclipse14.
Figure 3-2 Adding Java JAR Files in Eclipse
Your "classpath" file should look like the following example:
App Obfuscation Using ProGuard
If you choose to obfuscate your application with ProGuard, consider the following points:
If you extend or implement any of our classes or interfaces please specify that in the config file, as shown in the following example:
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:
Channel ListView Activity Example
The following example illustrates the following actions:
There are three configuration files that must be bundled with any Android app using the StadiumVision Mobile SDK (shown in Table 3-4 ).
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.
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:
This section describes how SVM fits into the Android Framework, and contains the following sections:
Figure 3-3 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 global structure created within the current process. It is tied to the lifetime of the process rather than the current component.
Each SDK API method is called using the StadiumVisionMobile class. The SVMVideoPlayerActivity class is a customizable stand-alone video player.
Figure 3-3 StadiumVision Mobile Class
Figure 3-4 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 3-4 Android Activity Overview
Figure 3-5 depicts the Activity inheritance between the Android OS, Cisco StadiumVision Mobile, and the client application.
Figure 3-5 Android Video Player Activity Inheritance
Figure 3-6 Cisco StadiumVision Mobile Integration Overview
Figure 3-7 illustrates the roles of the customer application. The application must specify:
Figure 3-7 Customer Application Responsibilities
Table 3-5 summarizes the Android API library. Detailed API documentation is available in the Doxygen build that is downloaded with the SDK. Navigate to the htm 1 folder and double-click index.html to launch the documentation in a web browser.
Each API call returns an ‘SVMStatus’ object whenever applicable. Table 3-6 lists the SVMStatus object fields.
Table 3-7 lists the hash keys and stats description for the getStats API.
The SVMVideoPlayerActivity class can be extended and customized. Table 3-8 lists the SVMVideoPlayerActivity API methods and descriptions.
This section describes the SDK workflow, and contains the following sections:
Start the StadiumVision Mobile SDK from the application’s main Android launch Activity, as shown in the following example.
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:
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:
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:
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 Table 3-9 .
Note For additional Service Down Notification details, refer to “Cisco StadiumVision Mobile SDK Best Practices” section.
The following example shows how to register and handle the "Service Up/Down" notifications from the SDK:
The "getServiceState" API method can be used to fetch the current service state from the SDK. The following example show how to fetch the current service state from the SDK using the "getServiceState" API call:
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:
The following example shows how to register and handle the "Service Up/Down" notifications from the SDK:
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:
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. Starting with the 1.3 release, 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 methods are provided for setting the SDK configuration at run-time:
The signature of the "setConfig" API method is given below:
The signature of the "setConfigWithString" API method is given below:
The following example shows how to set the SDK configuration using the "setConfigWithString" API method:
Table 3-10 lists the Cisco StadiumVision Mobile scalable file distribution API.
Table 3-11 lists the Cisco StadiumVision Mobile data channel APIs.
The signature of the "getConfig" API method is given below:
The example below fetches the current configuration from the SDK, and then accesses the configuration values in the configuration JSON object:
The following example shows how to set the SDK configuration using the "setConfig" API method:
The signature of the "setConfigWithString" API method is given below:
The following example shows how to set the SDK configuration using the "setConfigWithString" API method:
The Android SDK detects the available Streamer servers and provides an API to get the list of servers. A venue will typically only have 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:
Each "SVMStreamer" object contains the following properties listed in Table 3-12 .
|
|
|
---|---|---|
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:
In the 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:
public static HashMap<String, String> getStats()
Note For a detailed table of the hash keys and stats description for the getStats API refer to Table 3-7.
Table 3-13 details the StatsManager dictionary keys and descriptions.
|
|
---|---|
Number of Reporter stat manager errors other than upload issues (for example, stat generation failures). |
|
The 1.3 SDK generates broadcast Intent notifications for each of the video player state transitions (listed in Table 3-14 ). 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:
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:
This section describes how to customize the default video player. The default Cisco video player has the following features:
Figure 3-8 Default Cisco Video Player
Figure 3-9 SVMVideoPlayerActivity API
The video player’s XML layout file defines:
The customized video play extends the "SVMVideoPlayerActivity" base class, as shown below:
You need to register the new custom Activity in "AndroidManifest.xml", as shown below:
This section describes the Cisco StadiumVision Mobile SDK video channels and contains the following sections:
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:
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 3-15 .
|
|
---|---|
The following example shows playing a video channel, and performs the following actions:
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):
The following example shows jumping back to the top of the video buffer ("live" video playback):
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:
The XML layout file below shows how to configure the video ‘SurfaceView’ to specific pixel region, as shown in the following example:
This section describes the Cisco StadiumVision Mobile SDK data channels and contains the following sections:
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" API call, as shown in the following example:
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:
The "onData" method is called to push the received data to the registered class, as shown in the following example:
This section describes the Cisco StadiumVision Mobile SDK audio channels and contains the following sections:
Cisco StadiumVision Mobile supports audio-only channels, in a similar manner as video channels.
Get a reference to the audio manager from the SDK
The application starts the audio channels by invoking
Audio channels will continue to play while other activities are active but will terminate when the application enters background unless
Activities can check to see if audio is playing using isAudioActive ()
Available audio channels are discovered the same way that video channels are discovered.
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.
1. Register a BroadcastReceiver to be notified when a file channel becomes available using
public Intent registerReceiver (BroadcastReceiver receiver, IntentFilter filter)
2. 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)
3. Handle the file reception (movies/thumbnails /timeline) using
public void onFile (String channelName, String fileName,Integer fileState)
4. Check to see if a file channel is already available, using getFileChannelListArray.
5. If a channel is already available, or when a callback notification is received, register a file channel observer, using
addFileChannelObserver
6. Check to see if a file named ccast-timeline.xml is already available, using
getFileDistributionLocalFilename
7. 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.
8. 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.
9. 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
10. For each filename, cycle through onFile() and getFileDistributionLocalFilename until all files have been received.
11. Be prepared for the ccast-timeline.xml file to change at any time and repeat steps 6-8 whenever it changes.