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.
First Published: May 26, 2015
Revised: June 12, 2015
This chapter describes the Cisco StadiumVision Mobile SDK Release 2.1 for Apple iOS, and contains the following sections:
– Embed the Cisco StadiumVision Mobile SDK in an Existing App
The Cisco StadiumVision Mobile iOS SDK contains the following components bundled together:
The API uses Objective-C classes and method calls to access the StadiumVision Mobile data distribution and video playback functionality within the StadiumVision Mobile iOS SDK library.
Table 2-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 2-2 lists the various iOS SDK build environment requirements.
|
|
|
|
---|---|---|---|
A Mac is required to build an iOS application which includes the StadiumVision Mobile iOS SDK. |
|||
https://developer.apple.com/programs/ios/
Note Beginning February 1, 2015, new iOS apps submitted to the App Store must include 64-bit support and be built with the iOS 8 SDK. Apps that are updated will also need to follow the same requirements beginning on June 1, 2015. It is recommended you use Xcode 6.x to support iOS 8 for new and existing apps.
Step 1 Download StadiumVisionMobileSample-ios-VERSION-RELEASE.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 2-3 lists the extracted content and includes a brief description.
|
|
---|---|
Contains Doxygen API documentation that is accessible by opening the index.html file in a web browser |
|
Note The Cisco StadiumVision Mobile SDK for iOS Release 2.1 does not include "libvoCTS.a" and "voVidDec.dat." These files are no longer required in Release 2.1.
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 a iOS Sample app. The purpose of the Sample 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 2 Under File > Open > locate and select StadiumVisionMobileSample.xcodeproj from the extracted folder contents. Click Open.
Step 3 Select the active scheme (iPhone 5 for example) from the iOS Simluator list as shown in Figure 2-1 (1). To run the Sample app from an external device, connect the device to your computer and then select the device from the iOS Simulator list.
Step 4 Click the Build and then run the current scheme arrow to build and run the Sample app with the selected scheme as shown in Figure 2-1 (2).
Figure 2-1 Xcode—Set and Run the Active Scheme
Note If the external device you want to test on does not appear in the iOS Simulator list, be sure you’ve added it to the list of iOS devices in the iOS Developer Program. Cisco StadiumVision Mobile SDK Release 2.1 supports iOS 64-bit, however the SVM SDK for iOS only includes support for the 32-bit simulator and does not provide 64-bit simulator support.
Step 5 If the build was successful, a message appears followed by the Sample app launching in a new iOS Simulator window or on the external device as shown in Figure 2-2.
Figure 2-2 Xcode—Building the Sample App
There are many ways to customize the Cisco StadiumVision Mobile Sample app including customizing the Default-568h@2x.png graphic file to include a logo and specific colors.
The Sample app customized video player has the following properties:
The video view shown in Interface Builder is connected to the "videoView" property and is of class type "MyVideoView".
The following list outlines integration steps for using the Cisco StadiumVision Mobile SDK.
– Set the app’s iOS version target set to iOS v4.0 or above.
– Copy the "cisco_svm.cfg" and "vompPlay.cfg" config files, and the "voVidDec.dat" license file into the Xcode project.
– Copy the "libStadiumVisionMobile.a" static library into the Xcode project.
Note The Cisco StadiumVision Mobile SDK for iOS Release 2.1 does not include "libvoCTS.a" that was previously included. This file is no longer required in Release 2.1.
4. Include at least one objective C++ file in your project. We recommend renaming "main.m" to "main.mm".
5. Set the Xcode Project "Build Settings"
Add the required linker flag in Xcode using Build Settings > Linking > Other Linker Flags > Add. The required Xcode "Other Linker Flags" settings are shown in Figure 2-3.
– Add the "-ObjC" flag to the "Other Linker Flags" build setting. This ensures all Objective-C categories are loaded from the StadiumVision Mobile static library.
Figure 2-3 Xcode Other Linker Flags
Figure 2-4 shows the Xcode build settings that apply to both the project and target settings.
Figure 2-4 Xcode Build Settings
Note The standard architectures list may or may not include armv7s depending on the Xcode version you are using.
Figure 2-5 shows the settings for generating position dependent and position independent code.
Figure 2-5 Xcode Build Settings—Position Dependent and Independent Code Generation
Figure 2-6 shows the Apple LLVM language settings.
Figure 2-6 Xcode Build Setting—Specify Apple LLVM 6.0 - Language C++
Note If using Xcode version 5 or earlier, set "Apple LLVM 5.1 - Language - C++" > "C++ Standard Library" to "libstdc++ (GNU C++ standard library)". Applications that target iOS 6 and earlier do not need to make this change.
6. Include required iOS libraries by adding frameworks in the target build phases pane of the Xcode project, under "Link Binary With Libraries" section, as shown in Figure 2-7. A full list of required libraries is listed below Figure 2-7.
Figure 2-7 Adding Frameworks in Xcode
There are two configuration files that must be bundled with any iOS app using the StadiumVision Mobile SDK, as listed in Table 2-4 .
Note The Cisco StadiumVision Mobile SDK for iOS does not include "voVidDec.dat" that was previously included. This file is no longer required in Release 2.1.
There are three "field-of-use" (also known as the triplet key) properties in the "cisco_svm.cfg" configuration file that need to be configured for each StadiumVision Mobile application. These three fields must match the channel settings in the Cisco StadiumVision Mobile Streamer for the channels to be accessible by the application:
The "cisco_svm.cfg" configuration 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" configuration file:
Figure 2-8 illustrates the high-level view of the Cisco StadiumVision iOS API libraries and common framework components. The left side of the graphic represents how to modify the sample application, and the right represents how the SDK is packaged.
Figure 2-8 Cisco StadiumVision Mobile iOS SDK Components
The Model View Controller (MVC) design pattern separates aspects of an application into three distinct parts and defines how the three communicate. Figure 2-9 illustrates the Apple iOS MVC. As the name implies, the application is divided into three distinct parts: Model, View and Controller. The main purpose for MVC is reusability where you can reuse the same model for different views.
The singleton "StadiumVisionMobile" class provides the top-level API to start, configure, and stop the framework. "SVMVideoViewController" classes are provided to play the video channels and to allow for customization. Figure 2-10 illustrates the Cisco StadiumVision Mobile API classes.
Figure 2-10 Cisco StadiumVision Mobile iOS API Classes
The iOS "UIViewController" and "UIView" classes are used as base classes. The customer application can extend the Cisco StadiumVision Mobile classes. Figure 2-11 illustrates the UIViewController and UIView classes.
Figure 2-11 Cisco StadiumVision Mobile Video Classes
The Cisco StadiumVision Mobile application classes:
Figure 2-12 Cisco StadiumVision Mobile Sample Application Classes
Figure 2-13 illustrates the roles of the customer application. The application must specify:
Figure 2-13 Customer Application Responsibilities
Table 2-5 summarizes the iOS API library. Detailed API information is available in documentation 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.
Each API call returns a SVMStatus object whenever applicable. Table 2-6 lists the SVMStatus object fields.
Table 2-7 lists the hash keys and description for the Stats API.
The "SVMVideoVideoController" class can be extended and customized. Table 2-8 lists the SVMVideoPlayerActivity API methods and descriptions. Additional API methods and details are listed in the Doxygen build.
Table 2-8 Video View Controller API Summary
The StadiumVision Mobile SDK broadcasts the following iOS NSNotification events for use by the client application (listed in Table 2-9 ).
The following source code registers to receive the Cisco video notifications:
The following source code handles the Cisco video notifications:
The following example shows how to subscribe to receive the video player broadcast notifications:
The following example shows how to parse the video player broadcast notifications for (1) the video channel name and (2) the video channel state:
The SVM video player class ("SVMVideoViewController") provides a set of state flags that the inherited video player class (ie: "MyVideoViewController") can use to monitor the current video player state:
Table 2-10 provides a description of each state flag provided by the StadiumVision Mobile video player ("SVMVideoViewController"):
Starting Cisco StadiumVision Mobile SDK Release 1.3, the SVM video player ("SVMVideoViewController") provides a mode that allows the video player to continue rendering the audio and video channels when the video player view has lost focus. This mode allows the audio to still be played even when the user navigates away from the video player screen (view controller) to a different app screen; causing the video player to be hidden.
The background audio mode is disabled in the "SVMVideoViewController" by default. The following example shows how to set the "SVMVideoViewController" mode that allows the video player to continue rendering audio and video when the "SVMVideoViewController" loses focus (is not visible):
To detect that a currently playing video channel has become invalid (due to Streamer server admin changes), the SVM video player ("SVMVideoViewController") provides a callback to tell the video player sub-class (ie: "MyVideoViewController") 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 'SVMVideoViewController' sub-class (ie: "MyViewViewController"). The following example shows the method signature and implementation of this overridden callback method:
Beginning with Release 2.0, Cisco StadiumVision Mobile SDK includes a mechanism to determine if the Cisco StadiumVision Mobile service is available or not. The SDK provides an indicator to the application indicating if the StadiumVision Mobile service is up or down. This indication should be used by the application to indicate to the user whether the StadiumVision Mobile 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 iOS app can get the "Service State" from the SVM SDK:
When the app receives the "Service Down" notification, the SDK will supply a bitmap containing the reasons why the service was declared as ‘down’ by the SDK. The ‘reasons’ bitmap is given in Table 2-11 :
|
|
---|---|
Note For additional Service Down Notification details, refer to “Cisco StadiumVision Mobile SDK Best Practices” section.
The following example shows how to register to receive the "Service Up/Down" notifications from the StadiumVision Mobile SDK:
The "getServiceState" API method can be used to fetch the current service state from the SDK. The method signature of the "getServiceState" API call is given below:
The following example show how to fetch the current service state from the SVM SDK using the "getServiceState" API call:
Cisco StadiumVision Mobile SDK Release 1.3 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 iOS app can get this "In-Venue Detection" state from the SVM SDK:
1. Register to receive the "In-Venue Detection" notifications.
2. Fetch the current "In-Venue" state from the SDK on-demand.
The following example shows how to register to receive the "Service Up/Down" notifications from the SVM SDK:
The "isConnectedToVenue" API method can be used to fetch the current in-venue state from the SDK. The method signature of the "isConnectedToVenue" API call is given below:
The following example shows how to fetch the current service state from the SVM SDK using the "getServiceState" 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 iOS app. Starting with Release 2.0, 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 Cisco StadiumVision Mobile SDK libraries will support file channels that are easily accessible to the mobile client application. Table 2-12 lists the Cisco StadiumVision Mobile scalable file distribution API.
Table 2-13 lists the Cisco StadiumVision Mobile data channel APIs.
The StadiumVision Mobile SDK automatically handles the following events:
This section describes the Cisco StadiumVision Mobile SDK workflow, and contains the following sections:
The StadiumVision Mobile SDK needs to be started at the application initialization by calling the "start" API method as in the following example:
Sets the logging output level of the SDK, with the "DEBUG" level being more verbose than the "INFO" level. An example follows:
The example below gets the StadiumVision Mobile SDK version string:
The Cisco StadiumVision Mobile SDK is unable to include the MAC address in the periodic stats that it sends to the Cisco StadiumVision Mobile Reporter because Apple does not permit applications to access any device information that can be used to identify that device or its owner. As a substitute for the MAC address, the SDK instead includes a SVM Device UUID (universally unique identifier) that is unique for every device. The UUID allows Reporter data to be correlated with a specific device. In order for the correlation to work, the mobile app must display the UUID somewhere in its menu system (for example on the About or Help tabs).
The app can retrieve the UUID from the SDK via the code sample below. The getDeviceUUID method is documented in the iOS SVM header file.
Note The Cisco StadiumVision Mobile Device UUID should not be confused with the Unique Device Identifier (UDID) that is displayed in iTunes.
The StadiumVision Mobile SDK automatically shuts-down and restarts based upon the iOS life-cycle notifications (NSNotifications). The client iOS application does not need to explicitly stop and restart the StadiumVision Mobile SDK. This ‘shutdown’ API is provided in case a customer use-case requires an explicit SDK shutdown.
This section describes how to customize the video player, and contains the following sections:
To customize the video player, extend the "SVMVideoViewController" base class as in the following example:
Figure 2-14 Video Player Customization
This section describes the Cisco StadiumVision Mobile SDK video channels and contains the following sections:
Table 2-14 lists the "SVMChannel" video channel objects containing all of the information needed to display the channel list to the user.
|
|
---|---|
The example below demonstrates these actions:
The client application registers to receive callback whenever the video channel list is updated, as in the following example:
The StadiumVision Mobile SDK will callback the client application with any video channel list updates.
The last 30 seconds of played video is stored in the device RAM. The following example jumps backwards 20 seconds in the video buffer (instant replay).
The example below jumps back to the top of the video buffer ("live" video playback):
This section describes the Cisco StadiumVision Mobile SDK data channels and contains the following sections:
In the following example, the client application registers to receive callback whenever the data channel list is updated.
In this example, the StadiumVision Mobile SDK will callback the client application with any data channel list updates:
In the following example, the registered class needs to implement the "SVMDataObserver" protocol:
In this example, the "onData:withChannelName" method is called to push the received data to the registered class:
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 an Cisco StadiumVision Mobile powered C-Cast app gains access to the XML timeline and media files.
1. Register a callback to be notified when a file channel becomes available, using addFileChannelDelegate
2. Register to receive the channel notification using
[svm addFileChannelObserver:self forChannelName:@"something"]
3. (Optional) Listen for file channel list updates and potentially register using
(void)onFileChannelListUpdated:(NSMutableDictionary *)fileChannelList {}
4. Handle the file reception (movies/thumbnails/timeline) using
(void)onFile:(NSData *)file withChannelName:(NSString *)channelName {}
5. Check if a file channel is already available, using getFileChannelListArray
6. If a channel is already available or when a callback notification is received, register a file channel observer, using addFileChannelObserver
7. Check if a file with the name ccast-timeline.xml is already available, using getFileDistributionLocalFilename
8. If 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.
9. Once ccast-timeline.xml has been received, parse it using the steps in chapter 5 (How to build the media path) of the C-Cast API spec, then build the media path for all media files. Contact James Stellphlug ( j.stellpflug@evs.com) to obtain the C-Cast API documentation.
10. 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
11. For each filename cycle through onFile() and getFileDistributionLocalFilename until all files have been received.
12. Be prepared for ccast-timeline.xml to change at any time. Repeat steps 7-9 whenever it changes.