Player SDK for iOS

Introduction

The Ustream Player SDK lets you play Ustream live and recorded videos in your native applications. Using the 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 a mobile app using the Player SDK for iOS.

Before you begin

Account prerequisites

Before going into details, please note that document assumes the following:

  • you have a registered user at ustream.tv
  • your Ustream user is entitled to use the Player SDK specifically (if you have questions, please contact us)

Development prerequisites

Xcode

The Player SDK requires Xcode 5, targeting iOS 7.0 or above.

Frameworks

The Player SDK requires the MobileCoreServices.framework.

Dynamic libraries

  1. libsqlite3.dylib
  2. libxml2.dylib
  3. libz.dylib

Step 1: Explore the SDK package

USPlayer

  • include: contains the SDK header files
  • lib: contains the static library
  • resource: contains a required resource bundle

USPlayerSample

This is a sample application showcasing the Player SDK on iOS.

libUSPlayerSDK.a

This file is a fat file including the following architectures:

  • i386
  • x86_64
  • armv7
  • arm64
  • armv7s

Step 2: Create (or open) your project

Open the project that you would like to integrate the SDK in.

In case you wish to use a new project, follow these steps in Xcode:

  1. Choose File > New > New Project.
  2. Select the project template for your iOS or OS X product, and click Next.
  3. Enter the product name and other project details, and click Next.
  4. Specify the project’s row and its location in your file system, and click Save.

Step 3: Add the SDK to the project

1. Add the library to your project

The required resources are included in the USPlayer directory in the PlayerSDK package: the static library (libUSPlayerSDK.a), the header files and the resource bundle (USPlayerResources.bundle).

  1. Unzip the package and copy the USPlayer directory into your project’s source directory.
  2. Add the files to your project from XCode.
  3. Make sure that libUSPlayerSDK.a is included into Target Settings/Build Phases/Link Binary With Libraries.
  4. Add the required frameworks and dynamic libraries to Target Settings/Build Phases/Link Binary With Libraries.
  5. Make sure that USPlayerResources.bundle is included into Target Settings/Build Phases/Copy Bundle Resources.

2. Set up linker options

Since libUSPlayerSDK.a contains some category implementations, you need to set the flag "-ObjC" in your project’s Build Settings/Other Linker Flags.

Step 4: Register your app at Ustream

The SDK requires the use of a Ustream API key, which is validated whenever the SDK communicates with Ustream streaming servers. The sample application contains a sample API key which you can use for testing. The sample API key can only be used to play content on the test channel(s) also used in the sample app.

Before you can start using the Player SDK for playing content from your own channel(s), you will need to:

  • get a valid Ustream API key owned by the Ustream user that owns the content you would like to play
  • register the application identifier(s) - of every app in which you will integrate the Player SDK in - at Ustream

The application identifier is typically structured as com.your_company.your_project.

Before you can create and use an instance of the player you have to configure the lib with your Ustream API key:

[USUstreamPlayer configureWithApiKey:place your API key here];

Step 5: Create a Player

USUstreamPlayer can be instantiated in the usual way using alloc+init or new. The created player object is a subclass of the USUstreamPlayer optimized for the targeted device (iPhone or iPad).

For example:

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 6: Play live or recorded content

By now you have configured your player and it is ready to play live and recorded video content via Ustream.

USUstreamPlayer can play 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.

For example you can play the live video streamed right now on your channel:

[self.ustreamPlayer playChannel:place your channel id here];

Step 7: Handle Player callbacks

Ustream content owners can protect their content using various "locks" that implement password protection, age restriction and other limitations. Streaming servers reject clients connecting for playback if lock conditions are not met. The SDK calls the appropriate callback function to indicate this to the application.

Generic callbacks

USUstreamPlayer reports its state changes using the USPlayerDelegate protocol. It may also require user interaction in case the servers indicate the Player about content restrictions (so-called "locks") set up by the Ustream user. In order to catch these callbacks you have to set a handler conforming to protocol USPlayerDelegate as a delegate of your player instance.

For example:

self.ustreamPlayer.delegate = self;

Player state is changed

The player instance reports its state changes so that application states can be updated accordingly. For example your app can change the layout of the player screen depending on whether playback is in progress.

When the Player sends the callback:

(void)playerStateDidChange:(USUstreamPlayer *)player

it indicates that the state of the Player has changed so that you may choose to act on it. The states are listed in the USPlayerState enum.

Interactive callbacks

Callbacks caught can be "interactive": they can be used to reconnect for playback using some kind of user input.

Password lock

When the Player sends the callback:

(void)playerRequiresPassword:(USUstreamPlayer *)player

it waits for a password belonging to 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.

Age lock

When the Player sends the callback

(void)playerRequiresAgeConfirmation:(USUstreamPlayer *)player ageRequired:(NSUInteger)age

or the callaback:

(void)playerRequiresBirthdate:(USUstreamPlayer *)player

you need to ask the user's birth date without hints to the required age. If the user-specified age is not less than the required age, you can continue the playback with continueWithAgeConfirmed.

Step 8: Refine the Player UI

Appearance

USUstreamPlayer includes a full-featured user interface by default, including a control bar, loading and error views. You can change this behavior by setting the playerControlStyle property of the player. By setting it to USPlayerControlStyleNone you can instruct the player to display media only, without any decoration views.

In case you don’t want to handle all the player states and error cases manually, you can also reconfigure the control bars by setting their content using the USUstreamPlayer (USToolbar) category.

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.

Localization

Ustream provides localizations for all strings used in the Player SDK in the following languages:

  • English
  • Spanish
  • Japanese
  • Korean

If you want to provide more languages and/or redefine texts, include the keys listed below into the localization files of your application. If you don’t redefine these keys, then the SDK will fall back to the localizations included in the resource bundle of the SDK.

KeyDefault value in English
USPlayer.content.status.offlineThis channel is off-air.
USPlayer.content.status.realizingInitializing...
USPlayer.content.status.unrealizedLoading failed, please try again.
USPlayer.content.lock.ageLockThis content is age-restricted.
USPlayer.content.lock.birthdateLockThis content is age-restricted. Please provide your birthdate.
USPlayer.content.lock.geoLimitLockToo many viewers in your area.
USPlayer.content.lock.geoLockThis content is not available in your area.
USPlayer.content.lock.hashLockThis content is not supported in the mobile apps. Please use a browser for watching.
USPlayer.content.lock.IPLockThis content is not available in your network.
USPlayer.content.lock.passwordLockThis content is password-protected.
USPlayer.content.lock.refererLockViewer limit exceeded.
USPlayer.content.lock.unknownLockThis content is not supported.
USPlayer.content.error.updateSorry, something went wrong. Please try again.
USPlayer.content.error.connectConnection error. Please try again.
USPlayer.content.error.unsuportedUnsupported content.
USPlayer.content.error.deletedThis video has been removed by the owner.
USPlayer.content.error.inexistentThis content is inaccessible. Try again later.
USPlayer.content.error.unknownSorry, something went wrong. Please try again.
USPlayer.content.error.authenticationInvalid password.
USPlayer.content.error.timeoutLoading timeout, please try again.
USPlayer.player.external.titleAirPlay
USPlayer.player.external.messageThis video is playing on "Apple TV".
USPlayer.player.audioOnlyPlaying audio only...
USPlayer.player.status.bufferingBuffering...
USPlayer.control.viewerCount%d viewers
USPlayer.player.started.justNowStarted just now
USPlayer.player.started.yearsStarted years ago
USPlayer.player.started.monthsStarted months ago
USPlayer.player.started.weeksStarted weeks ago
USPlayer.player.started.daysStarted days ago
USPlayer.player.started.hoursStarted %dh %dm ago
USPlayer.player.started.minutesStarted %dm ago
USPlayer.player.status.finishedfinished
USPlayer.content.error.ageAge unconfirmed or too young user