Vonage Video API: Real-Time Video in iOS

Livestreaming experiences, like those powered by the Vonage Video API, cover everything from classes to concerts to consultations. But what do these things have in common? That’s right — a lack of tea. It’s time someone built an app to host a virtual tea party. In this tutorial, you’ll build a two-way livestreaming app to host a virtual tea party with a friend. How delightful!

Of course, building a livestreaming server and an associated API is no easy feat. Fortunately, there are a few livestreaming platforms that have already done that work for you. One of them is Vonage’s Video API.

While utilizing this API in your app, you’ll learn what WebRTC, HLS and RTMP mean and how to:

• Create and use a Vonage Video API account.
• Create a livestreaming session.
• Publish your camera and microphone to the session.
• Subscribe to and display the video from another user’s camera in the session.

It’s time to jump in.

Getting Started

Use the Download Materials button at the top or bottom of this tutorial to download the starter project.

The Vonage Video API provides an SDK called OpenTok that’s installed via CocoaPods. It creates a separate project for frameworks and groups it with the main project for use in a workspace.

The starter project has OpenTok pre-installed. Open TeaParty.xcworkspace to access the starter project.

The code and the storyboard already provide the interface for the app. Since you’ll be using your camera and microphone, their permission descriptions are predefined in Info.plist.

Build and run. You’ll see a big button in the center of the screen to enter the lounge:

The lounge is where you’ll livestream with your friend. Tap the Enter Lounge button:

Slight problem — it’s completely black and there’s no sign of any video streaming! Your task is to add the livestreaming functionality.

Livestreaming Technologies

The Vonage Video API allows real-time communications between up to 3,000 simultaneous connections. It uses an open-source, multi-platform framework called WebRTC.

For situations where WebRTC isn’t enough, like non-interactive broadcasts or when you require more than 3,000 connections, Vonage offers the following alternative technologies:

• HTTP Live Streaming (HLS): A traditional adaptive bit rate broadcast technology that uses a CDN (content delivery network) to deliver content with a high latency — around 15 to 20 seconds.
• Real-Time Messaging Protocol (RTMP): A broadcast technology with a latency of around five seconds that pushes content to social media platforms like Facebook or YouTube Live.

Since you aren’t planning to host a 3,001 person tea party, you don’t need to worry about these other broadcasting technologies — or buying large quantities of tea!

Creating Your Vonage Video API Account and Project

Open StreamingViewController.swift; you’ll notice three empty properties at the top: apiKey, sessionId and token. You’ll need these credentials to authenticate with the Vonage Video API.

Retrieve these by signing up for a free account on Vonage’s website.

After signing up, logging in and entering an account name, you’ll see the Vonage Video API account portal. This has many uses, including:

• Creating livestreaming projects.
• Registering server callback URLs.
• Configuring cloud storage for videos.
• Providing analytics and debugging tools for livestreaming sessions.
• Setting up billing.
• Providing links to developer documentation.

The Vonage Video API is a paid service, but it provides a free credit to get you started.

Start by selecting Create Project from the left-hand sidebar:

Next, choose Create Custom Project below the Vonage Video API section:

Then, add a project name and select VP8 as the preferred codec:

When streaming video, a codec encodes the camera’s video output to transport it across the network, then decodes the video to display it on a device’s screen. Vonage provides two codecs:

• VP8: This codec runs as software in the memory of a device and works well at lower bit rates. It’s a mature video codec in the context of WebRTC. It’s better for working with large sessions with many connections.
• H.264: This is available as both a software and hardware codec, depending on the device. When running on hardware, it uses less CPU power than VP8. It’s a relatively new codec in the context of WebRTC. This means that each device may have a different implementation, resulting in varying quality. It isn’t as good as VP8 for handling lower bit rates or large sessions.

In this case, you’ll choose VP8 because you’re likely to use it in a production app that hosts a bigger tea party with more connections from different devices (and more cake).

Click Create, then copy the resulting API key:

In your Xcode project, open StreamingViewController.swift and paste your API key into apiKey:

Creating a Session

Now, back in the Vonage Video API account portal, click View Project and scroll down to the Project Tools section:

This is where you’ll create a session ID and token. As the site explains, a session ID identifies a unique OpenTok session. You can think of the lounge in your Tea Party app as a session.

When creating a session, you use Media Mode to specify how clients in the session will send their video streams. There are two options:

• Relayed: Clients send streams directly between each other — that is, peer-to-peer — rather than using a server. This reduces latency and increases quality due to fewer network hops, but it won’t work if the devices are behind a firewall. A relayed session only supports two clients connected to the session.
• Routed: Clients send streams to each other via the OpenTok Media Router, which is a server that handles distributing the stream to multiple devices. This offers advantages such as the ability to record the stream; audio-fallback when a device has connectivity issues; bandwidth reduction in multi-party sessions and more.

For this app, select Routed as the Media Mode, then click Create Session ID. Copy-paste the given session ID into sessionId in StreamingViewController.swift, as you did with the API key.

Generating the Token

A token verifies each user’s identity. In a production app, each user would have their own unique token generated by a server. However, for simplicity, you’ll use the same token for each user for this project.

Each token has a role associated with it, which determines the capabilities of the client that connects to the session. There are three possible roles:

• Subscriber: Connects to a session and receives the other client’s streams. The client can’t publish their own camera to the session.
• Publisher: Receives streams and publishes their own camera to a session.
• Moderator: Has the ability to force other clients to disconnect from, and/or stop publishing to, a session.

In the token generation section of the account portal, paste your session ID, then set Role to Publisher, and Expiration Time to 30 days. The Connection Data field should be empty, in this case. In a production app, you’d typically use this to pass in a user ID, name or other data to describe the user.

Next, click Generate token and copy-paste the result into token in StreamingViewController.swift:

Now, you have the credentials you need to authenticate and start streaming your virtual tea party with the Vonage Video API. It’s time to put the kettle on!