Getting Started with the Brightcove App SDK for iOS

This document describes the Brightcove App SDK for iOS, which enables you to develop your own iPhone native application to deliver your Brightcove videos to the iPhone, iPad, and other iOS platforms. In addition to this "getting started" article, check out these other documents:

Brightcove App SDK for iOS. Links to the zip files that include the latest versions of the SDK classes, reference docs, and sample code for the OnePlanet iPhone native app.
Brightcove App SDK for iOS Reference. An on-line reference for the Brightcove App SDK for iOS.
Best Practices for Developing Brightcove Apps for iOS. Tips, tricks, and important points to remember as you develop your Brightcove iPhone application.
Known Issues for the Brightcove App SDK for iOS.

The Brightcove App SDK for iOS is a Cocoa/Objective-C Library for employing the Brightcove Media API and for playing videos in a custom Brightcove movie player on Apple iOS devices like the iPhone, iPad, and iPod Touch. The Media API provides a Cocoa/Objective-C interface for the Brightcove video and playlist APIs. The player component adds support for email and Twitter sharing, and related and popular video overlays to the standard iOS video player.

With the expansion of the iTunes App Store and the iPhone platform, the demand for mobile media continues to grow. Using this SDK to create a native iOS application will help you create a unique experience for viewers. Access to your video content and metadata is easily retrieved using the SDK so you can tailor your app for viewers on the go and keep your brand visible and close to your audience at all times.

If you are considering building an iOS application, it's never too early to start preparing your video content for mobile delivery. Read more about encoding video for mobile delivery. You may also want to consider building a mobile web application; read more about how Brightcove can help.

The Brightcove App SDK for iOS requires that you have Apple iOS SDK version 3.1 or higher (support includes the latest version, iOS 4.1).

OnePlanet Sample Application

Watch this space for an update to the sample application that uses the latest enhancements to our SDK!

We used the 2.x version of the Brightcove App SDK for iOS to develop a sample application named OnePlanet. You can read about how we developed OnePlanet and you can watch a video about it:

You can also get this free iPhone app in the iTunes App Store.

Installing the Brightcove App SDK for iOS in Xcode

To install the Brightcove App SDK for iOS:

Open Xcode and Create or Open an Xcode project.
Select the Project's Target and then Get Info (click the target in the xcode pane, then command-I or File->Get Info).
Choose the Build tab.
Double-click the Other Linking Flags property in the Linking section of the Settings list.
Add the following flag:
```
         -all_load -ObjC
```
Choose the General tab.
Under the Linked Library section click the plus button.
A dialog will slide down, click the Add Other... button.
Now select the libBrightcoveMediaAPI.a file distributed in the Brightcove Media API zip in the lib folder.
Repeat steps 7 - 9 for the libBrightcovePlayerKit.a file distributed in the Brightcove iPad iPhone Kit zip in the lib folder.
Close target settings.
Open Project Settings (Project -> Edit Project Settings).
In the Search Paths section, in the Header Search Paths entry, add the directory in which you put the Brightcove Media API zip on your computer followed by /lib. For example, if you stored the bc-media-api-2.0.0 at /Developer/Brightcove on your computer, then you would enter /Developer/Brightcove/bc-media-api-2.0.0/lib . IMPORTANT: Ensure that the "recursive" checkbox is selected.
In the Search Paths section, in the Header Search Paths entry, add the directory in which you put the Brightcove iPad iPhone Kit on your computer followed by /lib. For example, if you stored the bc-ipad-iphone-kit-2.0.0 at /Developer/Brightcove on your computer, then you would enter /Developer/Brightcove/bc-ipad-iphone-kit-2.0.0/lib . IMPORTANT: Ensure that the "recursive" checkbox is selected.
Close Project Settings.
Add the required Apple frameworks to your project. In the 'Frameworks' section of your Project in Xcode, ensure that all of these frameworks are present:

Foundation.framework
CoreGraphics.framework
UIKit.framework
MediaPlayer.framework

If any of those frameworks are missing, right-click on the Frameworks group in Xcode, select "Add" and "Existing Frameworks..." to open a file browser that will allow you to select and add the frameworks to your project. NOTE: If you want to use only the Brightcove Media APIs and not the Brightcove iPhone video player, you do not need to include MediaPlayer.framework.

Media API Usage

The BCMediaAPI class is a facade for all Brightcove Media API calls. This enables developers to instantiate it once for any needed calls:

    BCMediaAPI *bc = [[BCMediaAPI alloc] initWithReadToken:@"MyApiKey"];

Invocations are handled using Cocoa-style error pointers; thus, the pattern for all invocations is as follows:

Create an NSError object if you desire error info (optional).
Invoke a BC Media API method which will return a BCVideo, BCPlaylist, or BCItemCollection.
Check whether the returned BCObject is nil, and if so examine the NSError (if you used one).
If the returned BCObject was not nil, then access its properties according to your app's needs.

Media API Example Code

// Don't forget to include this line in your source (uncommented):
// #import "BCMediaAPI.h"

 BCMediaAPI *bc = [[BCMediaAPI alloc] initWithReadToken:@"MyApiKey"];

 NSError *err;
 BCVideo *video = [bc findVideoById:1234 error:&err];
 
 if (!video) {
    // if the result is nil, and we sent the optional error argument,
    // then the error will be populated by all underlying errors reported
    // by the Brightcove server. We can use the following convenience method
    // to dump the NSError's userInfo, where the underlying errors are reported,
    // into an NSString for logging or other purposes:
 
    NSString *errStr = [bc getErrorsAsString:err];
    NSLog(errStr);
 }

iPad iPhone Kit Usage

The BCMoviePlayerController class inherits from the Apple MPMoviePlayerController class. This is done to give you more control over how your video player is displayed and exposes the increased functionality that Apple has given developers. We are moving away from the fullscreen only experience that didn't give developers the control they need over the playback experience. The BCMoviePlayerController injects things like extracting the correct url to play back into the MPMoviePlayerController classes flow. The Brightcove specific methods exposed are setContentURL:(BCVideo *) video, searchForRenditionsBetweenLowBitRate:(int) lowBitRate andHighBitRate:(int) highBitRate and initWithContentURL:(BCVideo *) video searchForRenditionWithLowBitRate:(NSNumber *) lowBitRate andHighBitRate:(NSNumber *)highBitRate . These port over the major parts of the BCPlayer class that deal with video playback. To make sure the Brightcove code interacts with the MPMoviePlayerController correctly you need to follow one of the following flows.

Flow 1 OS Targets: iOS 3.2 and greater

This flow is best used when you are targeting iOS 3.2 currently only on the iPad and iOS 4 currently only on the iPhone (3G, 3GS & 4). Linked Library Type setting is Required.

Create the object with the init method and not any other convenience methods.

BCMoviePlayerController *player = [[BCMoviePlayerController alloc] init];

If you want to use the searchForRenditionsBetweenLowBitRate:andHighBitRate: method you have to call it before you set the content.

[player searchForRenditionsBetweenLowBitRate:[NSNumber numberWithInt:200000] andHighBitRate:[NSNumber numberWithInt:300000]];

Finally you set the content, this can be done before or after you have added the player to a view.

[player setContentURL:myVideo];

Flow 2 OS Targets: iOS 3.1 and greater

This flow allows you to develop code that will run on 3.1 and greater with out using any runtime checking to see what OS version you are running. Linked Library setting is Weak.

Create the object with the initWithContentURL: searchForRenditionWithLowBitRate: andHighBitRate: method. If you do not want to change the default bit-rates that we search for 200000 - 500000 you can pass nil for the last two params.

BCMoviePlayerController *player = [[BCMoviePlayerController alloc] initWithContentURL:self.video searchForRenditionWithLowBitRate:[NSNumber numberWithInt:200000] andHighBitRate:[NSNumber numberWithInt:300000]];

Call the play method to start playback

[player play];

iPad iPhone Kit Example Code

 // Don't forget to include this line in your source:

    #import "BCMoviePlayerController.h"


    BCMoviePlayerController *player = [[BCMoviePlayerController alloc] init];

    [player setContentURL:self.video]; // video fetched via the media apis, type is BCVideo

    

    CGRect rect = CGRectMake(0.0f, 0.0f, 480.0f, 320.0f);

    UIView *pView = player.view;

    [pView setFrame:rect];

    

    [self.view addSubview:player.view];

If you need help or have a question, please visit our forums. You can also follow the Brightcove App SDK for iOS on Twitter: http://twitter.com/bciphonesdk or register for updates and announcements about our mobile SDKs..

Browse by Category

Developer Community