Amazon IVS Player SDK: iOS Guide

The Amazon Interactive Video Service (IVS) iOS player provides the interfaces required to use the Amazon IVS player on iOS.

Latest version of iOS player: 1.17.0 (Release Notes)

Reference documentation: For information on the most important methods available in the Amazon IVS iOS player, see the reference documentation at https://aws.github.io/amazon-ivs-player-docs/1.17.0/ios/.

Sample code: See the iOS sample repository on GitHub: https://github.com/aws-samples/amazon-ivs-player-ios-sample.

Platform requirements: Xcode 11 or greater is required for development. The SDK supports deployment targets of iOS 10 and above, for both physical devices and the iOS Simulator.

A React Native wrapper for the Amazon IVS Player SDK is available. For the code and documentation, see https://github.com/aws/amazon-ivs-react-native-player.

Getting Started

We recommend that you integrate the player SDK via CocoaPods. (Alternately, you can manually add the framework to your project.)

Recommended: Integrate the Player SDK (CocoaPods)

Releases are published via CocoaPods under the name AmazonIVSPlayer. Add this dependency to your Podfile:

pod 'AmazonIVSPlayer'

Run pod install and the SDK will be available in your .xcworkspace.

Alternate Approach: Install the Framework Manually

1. Download the latest version from https://player.live-video.net/1.17.0/AmazonIVSPlayer.xcframework.zip.

2. Extract the contents of the archive. AmazonIVSPlayer.xcframework contains the SDK for both device and simulator.

3. Embed AmazonIVSPlayer.xcframework by dragging it into the Frameworks, Libraries, and Embedded Content section of the General tab for your application target:

   

Create Player

The player object is IVSPlayer. It can be initialized as shown below:

Swift:

import AmazonIVSPlayer

let player = IVSPlayer()

Objective-C:

#import <AmazonIVSPlayer/AmazonIVSPlayer.h>

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

Set Up Delegate

Delegate callbacks provide information on playback state, events, and errors. All callbacks are invoked on the main queue.

Swift | Objective-C:

// Self must conform to IVSPlayer.Delegate
player.delegate = self

Display Video

The player displays video in a custom layer, IVSPlayerLayer. The SDK also provides IVSPlayerView, a UIView subclass backed by this layer. Use whichever is more convenient for your application’s UI.

In both cases, display the video from a player instance by using the player property.

Swift:

// When using IVSPlayerView:
playerView.player = player

// When using IVSPlayerLayer:
playerLayer.player = player

Objective-C:

// When using IVSPlayerView:
playerView.player = player;

// When using IVSPlayerLayer:
playerLayer.player = player;

Load a Stream

The player loads the stream asynchronously. Its state indicates when it is ready to play.

Swift:

player.load(url)

Objective-C:

[player load:url];

Play a Stream

When the player is ready, use play to begin playback. Use the delegate interface or key-value observing on the state property to observe the state change. Here is an example of the delegate-based approach:

Swift:

func player(_ player: IVSPlayer, didChangeState state: IVSPlayer.State) {
    if state == .ready {
        player.play()
    }
}

Objective-C:

- (void)player:(IVSPlayer *)player didChangeState:(IVSPlayerState)state {
    if (state == IVSPlayerStateReady) {
        [player play];
    }
}

Pause On App Backgrounding

The player does not support playback while the app is in the background, but it does not need to be fully torn down. Pausing is sufficient; see the examples below.

Swift:

override func viewDidLoad() {
    super.viewDidLoad()

    NotificationCenter.default.addObserver(self,
        selector: #selector(applicationDidEnterBackground(_:)),
        name: UIApplication.didEnterBackgroundNotification,
        object: nil)
}

@objc func applicationDidEnterBackground(_ notification: NSNotification) {
    playerView?.player?.pause()
}

Objective-C:

- (void)viewDidLoad {
    [super viewDidLoad];

    NSNotificationCenter *defaultCenter = NSNotificationCenter.defaultCenter;
    [defaultCenter addObserver:self
                      selector:@selector(applicationDidEnterBackground:)
                          name:UIApplicationDidEnterBackgroundNotification
                        object:nil];
}

- (void)applicationDidEnterBackground:(NSNotification *)notification {
    [playerView.player pause];
}

Thread Safety

The player API is not thread safe. You should create and use a player instance from the application main thread.

Putting It All Together

The following simple, view-controller snippet loads and plays a URL in a player view. Note that the playerView property is initialized from an XIB/Storyboard, and its class is set to IVSPlayerView in Interface Builder using the Custom Class section of the Identity Inspector.

Swift:

import AmazonIVSPlayer

class MyViewController: UIViewController {
...
    // Connected in Interface Builder
    @IBOutlet var playerView: IVSPlayerView!

    override func viewDidLoad() {
        super.viewDidLoad()

        NotificationCenter.default.addObserver(self,
            selector: #selector(applicationDidEnterBackground(_:)),
            name: UIApplication.didEnterBackgroundNotification,
            object: nil)
    }

    @objc func applicationDidEnterBackground(_ notification: NSNotification) {
        playerView?.player?.pause()
    }
...
    // Assumes this view controller is already loaded.
    // For example, this could be called by a button tap.
    func playVideo(url videoURL: URL) {
        let player = IVSPlayer()
        player.delegate = self
        playerView.player = player
        player.load(videoURL)
    }
}

extension MyViewController: IVSPlayer.Delegate {
    func player(_ player: IVSPlayer, didChangeState state: IVSPlayer.State) {
        if state == .ready {
            player.play()
        }
    }
}

Objective-C:

// MyViewController.h

@class IVSPlayerView;

@interface MyViewController: UIViewController
...
// Connected in Interface Builder
@property (nonatomic) IBOutlet IVSPlayerView *playerView;
...
@end


// MyViewController.m

#import <AmazonIVSPlayer/AmazonIVSPlayer.h>

@implementation MyViewController <IVSPlayerDelegate>
...

- (void)viewDidLoad {
    [super viewDidLoad];

    NSNotificationCenter *defaultCenter = NSNotificationCenter.defaultCenter;
    [defaultCenter addObserver:self
                      selector:@selector(applicationDidEnterBackground:)
                          name:UIApplicationDidEnterBackgroundNotification
                        object:nil];
}

- (void)applicationDidEnterBackground:(NSNotification *)notification {
    [playerView.player pause];
}

// Assumes this view controller is already loaded.
// For example, this could be called by a button tap.
- (void)playVideoWithURL:(NSURL *)videoURL {
    IVSPlayer *player = [[IVSPlayer alloc] init];
    player.delegate = self;
    playerView.player = player;
    [player load:videoURL];
}

- (void)player:(IVSPlayer *)player didChangeState:(IVSPlayerState)state {
    if (state == IVSPlayerStateReady) {
        [player play];
    }
}

...
@end

SDK Size

The Amazon IVS player SDKs are designed to be as lightweight as possible. For current information about SDK size, see the Release Notes.

Important: When evaluating size impact, the size of the IPA produced by Xcode is not representative of the size of your app downloaded to a user’s device. The App Store performs optimizations to reduce the size of your app.

Known Issues and Workarounds

Please report all issues to Amazon IVS Support.

• The player may crash when testing against the arm64e architecture. This only applies when targeting arm64e specifically, and does not apply to App Store builds.

  Workaround: Do not use arm64e.