Ustream Player SDK for tvOS provides an API to play all kinds of Ustream content on Apple Tv. Using this native SDK gives you full control over the Player, including a customizable native user interface, callbacks on status changes, and many more. (Note: if you need none of the above, you may use the HTML-based Player API instead)
This document describes the basic steps to make an app using the Player SDK for tvOS.
Supported tvOS versions
Ustream Player SDK for tvOS requires Xcode 7.1, targeting tvOS 9.0 or above.
Contents of the Package
- TvOSPlayerSDK.framework - the framework itself, containing a flat binary including architectures: x86_64 arm64
- tvOSPlayerSDKSample - a sample application using the Ustream Player SDK for tvOS
Step 1: Adding the framework to your project.
- Unzip the package and copy the Framework directory into your project’s source directory.
- Add the framework to your project from Xcode.
- Make sure that TvOSPlayerSDK.framework is included into Target Settings/Build Phases/Link Binary With Libraries
- Make sure that Target Settings/Build Settings/Framework Search Paths contains the framework’s parent directory
Step 2: Embed the framework
- Add a new Copy Files build phase to build phases
- Set destination to Frameworks
- Add TvOSPlayerSDK.framework to to list of copied files
Step 3: Configuring the player with your API-key
Before you can create and use an instance of the player you have to configure the lib with your Ustream API key:
Step 4: Creating a player and adding it to your view hierarchy
USUstreamPlayer can be instantiated in the usual way using alloc+init or new.
self.ustreamPlayer = [[USUstreamPlayer alloc] init]; self.ustreamPlayer.delegate = self; self.ustreamPlayer.view.frame = self.view.bounds; self.ustreamPlayer.view.autoresizingMask = UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight; [self.view addSubview:self.ustreamPlayer.view];
Step 5: Start playing content
At this point your player is correctly configured and ready to play Ustream-provided media, USUstreamPlayer is capable to play three different kinds of media:
- live streams using the -[USUstreamPlayer playChannel:] API call.
- recorded videos using the -[USUstreamPlayer playRecorded:] API call.
- highlights using the -[USUstreamPlayer playHighlight:] API call.
Step 6: Handling callbacks
USUstreamPlayer reports its state changes and requires user interaction in case of some locks using the USPlayerDelegate protocol. In order to catch these callbacks you have to set a handler conforming to protocol USPlayerDelegate as a delegate of your player instance.
self.ustreamPlayer.delegate = self;
List of Interactive Callbacks
- (void)playerRequiresPassword:(USUstreamPlayer *)player - When the player sends this callback it waits for a password for the locked content. You can provide the password using continueWithPassword:(NSString *)password. If you provide the password the player validates it and starts playing the content if the password is valid otherwise it calls back again with playerRequiresPassword.
- (void)playerRequiresAgeConfirmation:(USUstreamPlayer *)player ageRequired:(NSUInteger)age -When this callback is sent you must ask the user to confirm he is older than the age required. If the user confirms it you can continue the playback with continueWithAgeConfirmed.
- (void)playerRequiresBirthdate:(USUstreamPlayer *)player - When this callback is sent you must ask the user to give his/her birthdate in order to check if he/she is old enough to watch the content. You can continue the playback with continueWithBirthdate:(NSDate *)birthdate;
Note: Beside these locks there are a number of other, non-interactive locks listed in the appendix. In those cases there is no way to continue the playback.
- (void)playerStateDidChange:(USUstreamPlayer *)player - This callback is called whenever the player’s state is changed and allows you to act on it. The possible states are listed in the USPlayerState enum.
Customizing the player UI
By default USUstreamPlayer comes with a full-featured user interface, including a control bar, loading and error views. This is used if the player’s playerControlStyle property is set to USPlayerControlStyleDefault.
You can change this behaviour by setting the playerControlStyle property of the player. By setting it to USPlayerControlStyleNone you can instruct the player to present media without any decoration views.
In case you don’t want to handle all the player states and error cases manually, you can reconfigure the control bars as well, by setting their content using the USUstreamPlayer (USToolbar) category. In order to do so, set the playerControlStyle property to USPlayerControlStyleToolbar.
You can set any of the player toolbar’s contents using the -[USToolbar setToolbarItems:animated:] API. The standard toolbar items are accessible in the USUstreamPlayer (USToolbar) category, and you can create your own items as well by subclassing USToolbarItem.
Ustream provides localizations for all strings used in the Ustream Player SDK for tvOS in the following languages:
If you want to provide more languages and/or redefine the texts include the keys listed in appendix into your app’s localization files. If you don’t redefine these keys the SDK will fall back to the localizations included in the SDK’s resource bundle.
Appendix 1 - Ustream Media Locks:
|Password lock||live, recorded, highlight||Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/advanced/cid|
|Age lock||live, recorded, highlight||This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.|
|Birthdate lock||live, recorded, highlight||This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.|
|Geo lock||live, recorded, highlight||This lock is not available for end users to control. It’s part of special deals conducted by Ustream sales and administered internally.|
|GeoLimit lock||live, recorded, highlight|
|Hash lock||live||Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/webinar/cid|
|IP lock||live, recorded, highlight|
|Referrer lock||live, recorded, highlight||Broadcaster can manage this lock here: http://www.ustream.tv/manage-show/embed/cid|
Appendix 2 - Ustream Player SDK for tvOS Localization Keys:
|USPlayer.preroll.premium||Enjoy ad-free experience with Premium Membership!|
|USPlayer.preroll.resuming||"Resuming in %d seconds"|
|USPlayer.content.status.offline||This channel is off-air.|
|USPlayer.content.status.unrealized||Loading failed, please try again.|
|USPlayer.content.lock.ageLock++||This content is age-restricted.|
|USPlayer.content.lock.birthdateLock||This content is age-restricted. Please provide your birthdate.|
|USPlayer.content.lock.geoLimitLock||Too many viewers in your area.|
|USPlayer.content.lock.geoLock||This content is not available in your area.|
|USPlayer.content.lock.hashLock||This content is not supported in the mobile apps. Please use a browser for watching.|
|USPlayer.content.lock.IPLock||This content is not available in your network.|
|USPlayer.content.lock.passwordLock||This content is password-protected.|
|USPlayer.content.lock.refererLock||Viewer limit exceeded.|
|USPlayer.content.lock.unknownLock||This content is not supported.|
|USPlayer.content.error.update||Sorry, something went wrong. Please try again.|
|USPlayer.content.error.connect||Connection error. Please try again.|
|USPlayer.content.error.deleted||This video has been removed by the owner.|
|USPlayer.content.error.inexistent||This content is inaccessible. Try again later.|
|USPlayer.content.error.unknown||Sorry, something went wrong. Please try again.|
|USPlayer.content.error.timeout||Loading timeout, please try again.|
|USPlayer.player.external.message||This video is playing on "Apple TV".|
|USPlayer.player.audioOnly||Playing audio only...|
|USPlayer.player.started.justNow||Started just now|
|USPlayer.player.started.years||Started years ago|
|USPlayer.player.started.months||Started months ago|
|USPlayer.player.started.weeks||Started weeks ago|
|USPlayer.player.started.days||Started days ago|
|USPlayer.player.started.hours||Started %dh %dm ago|
|USPlayer.player.started.minutes||Started %dm ago|
|USPlayer.content.error.age||Age unconfirmed or too young user|