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 iOS SDK is provided as a set of static libraries, header files, and an a sample iOS app (with a complete Xcode project). This 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.
The Cisco StadiumVision Mobile client application supports Apple iOS 5.0 or later.
The Model View Controller (MVC) design pattern separates aspects of an application into three distinct parts and defines how the three communicate. Figure 1-1 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.
Figure 1-1 MVC Design Pattern
Build Environment Requirements
Table 1-1 lists the various iOS SDK build environment requirements.
Note Application developers will need to link against the libstd++ library in their build. This can be done by modifying the Build Settings->Linking->Other Linker Flags-> Add "-lstdc++" in Xcode.
The Cisco StadiumVision Mobile iOS SDK contains the following components:
•A set of static libraries, header files, and an a sample iOS app (with a complete Xcode project)
•Customizable iOS SDK video player
Figure 1-2 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 modifythe sample application, and the right reprsents how the SDK is packaged.
Figure 1-2 Cisco StadiumVision Mobile iOS SDK Components
The singleton "StadiumVisionMobile" class provides the top-level API to start, configure, and stop the framework. Video View Controller classes are provided to play the video channels and allow for customer customization. Figure 1-3 illustrates the StadiumVision Mobile API classes.
Figure 1-3 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 1-4 illustrates the UIViewController and UIView classes.
Figure 1-4 Cisco StadiumVision Mobile Video Classes
The Cisco StadiumVision Mobile application classes:
•Extends and customizes the SVMVideoViewController class
•Adds a UI overlay for controlling video playback (play, stop, close)
•Adds a UI overlay for displaying StadiumVision Mobile stats
•Handles gestures to display UI overlays with the MyVideoViewController class
Figure 1-5 Cisco StadiumVision Mobile Sample Application Classes
Table 1-2 summarizes the iOS API library. Following the summary are detailed tables for each API call.
Table 1-2 Cisco StadiumVision Mobile iOS API Summary
The following tables describe each API call in more detail, including example usage.
Each API call returns a SVMStatus object whenever applicable. Table 1-3 lists the SVMStatus object fields.
Table 1-3 SVMStatus class
Table 1-4 sharedInstance
Table 1-5 Start
Table 1-6 addVideoChannelListDelegate
Table 1-7
setLogLevel
Table 1-8 removeVideoChannelListDelegate
Table 1-9 addDataChannelListDelegate
Table 1-10 removeDataChannelListDelegate
Table 1-11 addDataChannelListDelegate
Table 1-12 removeDataChannelListDelegate
Table 1-13
addDataChannelObserver
Table 1-14 removeDataChannelObserver
Table 1-15 onData
Table 1-16 Stats
Table 1-17 Stats API Hash Keys and Descriptions
Table 1-18
getVideoChannelListArray
Table 1-19
getDataChannelListArray
Table 1-20 wifiInfo
The following tables contain properties are available within the SVMWifiInfo object.
Table 1-21 wifiInfo Object Properties
Table 1-22 version
|
(NSString*) version |
---|---|
|
N/A |
|
This method returns the StadiumVision Mobile SDK version string. |
|
N/A |
The 'SVMVideoVideoController' class can be extended and customized. The SVMVideoVideoController API methods are listed in Table 1-23.
Table 1-23 Video View Controller API Summary
Table 1-24 Video View API Summary
Table 1-25 setRenderVideoView
Table 1-26 playVideo Channel
Table 1-27 seekRelative
Table 1-28 seekAbsolute
Table 1-29 playLive
The StadiumVision Mobile SDK broadcasts the following iOS NSNotification events for use by the client application.
Table 1-30 NSNotification Event Properties
The following source code registers to receive the Cisco video notifications:
#include "StadiumVisionMobile.h"
// register to handle the video buffering events
[[NSNotificationCenter defaultCenter] addObserver:self
selector:@selector(onVideoEvent:)
name:kSVMVideoEventNotification
object:nil];
The following source code handles the Cisco video notifications:
#include "StadiumVisionMobile.h"
// video event notification handler
(void)onVideoEvent:(NSNotification*)notification {
// get the passed "SVMEvent" object
SVMEvent *event = [notification object];
// determine the video event type
switch (event.type) {
case kSVMEventTypeVideoBufferingActive:
// activate the UI "buffering" indicator
break;
case kSVMEventTypeVideoBufferingInactive:
// deactivate the UI "buffering" indicator
break;
}
}
The StadiumVision Mobile SDK needs to be started at the application initialization by calling the "start" API method as in the following example:
#import "StadiumVisionMobile.h"
// get a reference to the StadiumVision Mobile API
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
// start the StadiumVision Mobile SDK
[svm start];
Sets the logging output level of the SDK, with the "DEBUG" level being more verbose than the "INFO" level. An example follows:
// start method sets logs to INFO by default
StadiumVisionMobile *svm = [StadiumVisionMobile sharedInstance];
[svm start];
// set the desired log level
[svm setLogLevel:SVM_API_LOG_DEBUG];
The client application registers to receive callback whenever the video channel list is updated, as in the following example:
// register to receive video channel list updates
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
[svm addVideoChannelListDelegate:self];
The StadiumVision Mobile SDK will callback the client application with any video channel list updates.
#import "StadiumVisionMobile.h"
// implement the "SVMChannelListObserver" protocol
@interface MyViewController : UIViewController <SVMChannelListObserver>
// video channel handler (array of 'SVMChannel' objects)
-(void)onVideoChannelListUpdated:(NSArray*)channelList;
Each "SVMChannel" video channel object contains all of the information needed to display the channel list to the user.
Table 1-31 SVMChannel object properties
The example below demonstrates these actions:
•Selects a channel from the locally saved channel list
•Presents the video view controller modally
•Commands the video view controller to play the selected channel
#import "StadiumVisionMobile"
// get the user-selected video channel object
SVMChannel *selectedChannel = [videochannelList objectAtIndex:0];
NSLog(@"Selected Video Channel = %@", selectedChannel.name);
// create the video view controller
MyVideoViewController *myVC = [[MyVideoViewController alloc] init];
// present the modal video view controller
myVC.modalTransitionStyle = UIModalTransitionStyleCrossDissolve;
[self presentModalViewController:myVC animated:YES];
// play the selected video channel
[myVC playVideoChannel:selectedChannel];
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).
// get a reference to the api object
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
// rewind 20 seconds
[svm rewindForDuration:-20000];
The example below jumps back to the top of the video buffer ("live" video playback):
// get a reference to the api object
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
// play at the "live" video offset
[svm playLive];
In the following example, the client application registers to receive callback whenever the data channel list is updated.
// register to receive data channel list updates
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
[svm addDataChannelListDelegate:self];
In this example, the StadiumVision Mobile SDK will callback the client application with any data channel list updates:
#import "StadiumVisionMobile.h"
// implement the "SVMChannelListObserver" protocol
@interface MyViewController : UIViewController <SVMChannelListObserver>
// data channel handler (array of 'SVMChannel' objects)
(void)onDataChannelListUpdated:(NSArray*)channelList;
In the following example, the registered class needs to implement the "SVMDataObserver" protocol:
#import "SVMDataObserver.h"
@interface DataChannelViewController : UIViewController <SVMDataObserver>
In this example, the "onData:withChannelName" method is called to push the received data to the registered class:
-(void)onData:(NSData*)data withChannelName:(NSString *)channelName {
// convert the data bytes into a string
NSString *dataStr = [[NSString alloc] initWithBytes:[data bytes]
length:[data length]
encoding:NSUTF8StringEncoding];
// display the data bytes and associated channel name
NSLog(@"ChannelListViewController: onData callback: "
"channelName = %@, data = %@", channelName, dataStr);
[dataStr release];}
The example below gets the StadiumVision Mobile SDK Version string:
#import "StadiumVisionMobile"
// get a reference to the api object
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
// get the sdk version string
NSString *sdkVersion = [svm version];
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.
#import "StadiumVisionMobile"
// get a reference to the api object
StadiumVisionMobile *svm = [StadiumVisonMobile sharedInstance];
// shutdown the StadiumVision Mobile SDK
[svm shutdown];
The default Cisco video player has the following features:
•Implemented as a separate iOS "UIViewController"
•Support for fullscreen and partial-screen video views
•Video frames rendered using an iOS "UIView" and OpenGL layer (CAEAGLLayer)
•Customizable by extending the "SVMVideoViewController" class
• The Cisco demo app uses a customized video player
To customize the video player, extend the "SVMVideoViewController" base class as in the following example:
#import "SVMVideoViewController.h";
@interface MyVideoViewController : SVMVideoViewController {
}
Figure 1-6 Video Player Customization
The demo customized video player has the following properties:
•Implemented as "MyVideoViewController"
•Extends the "SVMVideoViewController" class
•Handles all video overlays and gestures
•Single-tap gesture and "Back", "Rewind" / "Live" overlay buttons
•Two-finger double-tap gesture and stats overlay
•Uses the "MyVideoViewController~iphone.xib" to layout the screen
•Located in the "Customer App / App UI Resources / UI XML Files" Xcode project folder
The video view shown in Interface Builder is connected to the "videoView" property and is of class type "MyVideoView".
There are three configuration files that must be bundled with any iOS app using the StadiumVision Mobile SDK, as listed in the following table:
Table 1-32 Configuration Files
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 fields must match the channel settings in the Cisco StadiumVision Mobile Streamer for the channels to be accessible by the application.
•Venue Name
•Content Owner
•App Developer
An example set of fields in the "cisco_svm.cfg" file is shown below:
{
"license": {
"venueName": "Stadium-A",
"contentOwner": "Multi-Tenant Team-B",
"appDeveloper": "Vendor-C"
}
}
The "cisco_svm.cfg" configuration 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" configuration file:
{
"network": {
"wifiApInfo": [
{
"name": "Press Box Booth 5",
"bssid": "04:C5:A4:09:55:70"
}
]
}
}
The following list outlines integration steps for using the Cisco StadiumVision Mobile SDK.
1. Supported iOS version
–Set the app's iOS version target set to iOS v4.0 or above
2. Copy configuration files
–Copy the "cisco_svm.cfg" and vompPlay.cfg" config files, and the "voVidDec.dat" license file into the Xcode project.
3. Copy libraries
–Copy the "libStadiumVisionMobile.a" and "libvoCTS.a" static libraries into the Xcode project.
4. Set the Xcode Project "Build Settings"
–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.
–Add the "-lstdc++" flag to the "Other Linker Flags" build setting. This ensures that the C++ video decoder library is properly linked to the final app build.
5. 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 1-7.
Figure 1-7 Adding frameworks in Xcode
Required iOS Libraries
•UIKit.framework
•Foundation.framework
•CoreGraphics.framework
•AudioToolbox.framework
•OpenGLES.framework
•QuartzCore.framework
•CFNetwork.framework
•SystemConfiguration.framework
•MobileCoreServices.framework
•libz.dylib
The StadiumVision Mobile SDK automatically handles the following events:
•Dynamic video channel discovery and notification
•Dynamic data channel discovery and notification
•Automatic SDK shutdown / restart in response to WiFi up / down events
•Automatic SDK shutdown / restart in response to iOS life-cycle events
•Management of multicast network data threads
•On-demand management of video / audio decoding threads
•Automatic statistics reporting to the StadiumVision Mobile Reporter server
Figure 1-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 overlays
Figure 1-8 Customer Application Responsibilities