Switch to api.video Swift player

March 29, 2023 - Romain Petit in iOS, Player, Swift

Have you already developed your own player, but find it challenging to switch to the api.video player?

We have a solution. In this tutorial, we will demonstrate how to play a video from api.video on your player.

Before starting

Before you start, make sure that you have already uploaded at least one video to api.video. If you haven't done so yet, you can follow this guide for assistance.

Extensions

In this tutorial, we will discuss extensions. If you are not familiar with extensions, I will explain them briefly, but if you are, feel free to skip ahead.

Extensions enable you to add custom functionality to a code without altering the original implementation.

For example, let's say you have a struct named "Person" with "firstname" and "lastname" as properties. You can create an extension to retrieve their full name.

struct Person {
	let firstname: String
	let lastname: String
}

extension Person {
	func getFullName() -> String{
		return "\(firstname) \(lastname)"
	}
}

let person = Person(firstname: "John", lastname: "Doe")
let fullname = person.getFullName() // "John Doe"

Adding the api.video Swift player library

In this section, we will cover the two main steps involved in adding the api.video Swift player to your project:

Get the latest version by accessing it here.
Add the ApiVideoPlayer package to your app using one of the following methods:
a. SPM:
- In the Project Navigator, select your project.
- Click on the "Package Dependencies" tab in the Project section.
- Click the "+" button at the bottom.
- Paste the URL below into the search bar in the top right.
- Finally, click the "Add package" button.

https://github.com/apivideo/api.video-swift-player

b. Cocoapods:

Add the following to your Podfile.

pod 'ApiVideoPlayer', 'X.X.X'

Then run:

pod install

Replace X.X.X with the latest version.

VideoOptions

Every video on api.video is assigned a unique identifier called the videoId, which can be found on the Dashboard or in the video list.

As you follow this tutorial, make sure to replace YOUR_VIDEO_ID with the actual videoId of your video.

let videoOptions = VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod)
// for livestream use .live instead of .vod

If you are using private videos, it will be necessary to provide the private token as well.

A private token is an exclusive token that guarantees access to a specific private video, but it can be used only once.

let videoOptions = VideoOptions(videoId: "YOUR_VIDEO_ID", videoType: .vod, token "YOUR_PRIVATE_TOKEN")

AVPlayer Extension

The api.video Swift Player provides an extension for playing new videos with AVPlayer:

let avPlayer = AVPlayer()
avPlayer.replaceCurrentItem(withHls: videoOptions)

If, for any reason, you encounter an error with the HLS stream, you can try again with an MP4 video.

To do this, you need to add an observer to your player and retry when the status fails:

let didTryMp4 = false // add this to avoid infinite loop in status failed
player.currentItem?.addObserver(self, forKeyPath: "status", options: .new, context: nil)

override public func observeValue(
        forKeyPath keyPath: String?,
        of _: Any?,
        change: [NSKeyValueChangeKey: Any]?,
        context _: UnsafeMutableRawPointer?
    ) {
        if keyPath == "status" {
            guard let status = change?[.newKey] as? Int else {
                return
            }
            if status == AVPlayerItem.Status.failed.rawValue {
                if !didTryMp4{ // if didTryMp4 is false 
                    didTryMp4 = true 
                    avPlayer.replaceCurrentItem(withMp4: videoOptions)
            }

           }
        }
    }