Start Interactive Live Video Streaming

People engage longer when they see, hear, and interact with each other. The Agora SDK enables you to embed real-time voice and video interaction in any app, on any device, anywhere.

This page shows the minimum code you need to integrate high-quality, low-latency live streaming experience into your app using the Agora Video SDK for iOS.

Understand the tech

The following figure shows the workflow to integrate into your app in order to add Interactive Live Streaming Standard functionality.

As shown in the figure, the workflow for adding Interactive Live Streaming Standard in your project is as follows:

1. Set the client role and latency level
   Each user in an Interactive Live Streaming Standard channel is either a host or an audience member. Hosts publish streams to the channel, and the audience subscribe to the streams. When a user is an audience member, you can control the delay the user receives host streams using ClientRoleOptions.

2. Retrieve a token
   A token is the credential that authenticates a user when your app client joins a channel. In a test or production environment, your app client retrieves tokens from a server in your security infrastructure.

3. Join a channel
   Call joinChannel to create and join a channel. App clients that pass the same channel name join the same channel.

4. Publish and subscribe to audio and video in the channel
   After joining a channel, app clients with the role of the host can publish audio and video. For an auidence memeber to send audio and video, call setClientRole to switch the client role.

For an app client to join a channel, you need the following information:

• The App ID: A randomly generated string provided by Agora for identifying your app. You can get the App ID from Agora Console.
• The user ID: The unique identifier of a user. You need to specify the user ID yourself, and ensure that it is unique in the channel.
• A token: In a test or production environment, your app client retrieves tokens from a server in your security infrastructure. For this page, you use a temporary token with a validity period of 24 hours that you retrieve from Agora Console.
• The channel name: A string that identifies the channel for the live stream.

Prerequisites

Before proceeding, ensure that your development environment meets the following requirements:

• Xcode 9.0 or later.
• An iOS device running iOS 9.0 or later.
• A valid Agora account.
• A valid Agora project with an App ID and a temporary token. For details, see Get Started with Agora.
• A computer with access to the internet. If your network has a firewall, follow the instructions in Firewall Requirements.

Project setup

In Xcode, follow the steps to create the environment necessary to add Interactive Live Streaming Standard into your app.

1. Create a new iOS app and configure the following settings:
   • Product Name: Any name you like.
   • Team: If you have added a team, choose it from the pop-up menu. If not, you can see the Add account button. Click it, input your Apple ID, and click Next to add your team.
   • Organization Identifier: The identifier of your organization. If you do not belong to an organization, use any identifier you like.
   • Interface: Choose Storyboard.
   • Language: Choose Swift.

2. Integrate the Video SDK into your project:

   Go to File > Swift Packages > Add Package Dependencies..., and paste the following URL:

     https://github.com/AgoraIO/AgoraRtcEngine_iOS

   In Choose Package Options, specify the Video SDK version you want to use. You need to fill in x.y.z for version x.y.z and x.y.z-r.a for version x.y.z.a. For example, fill in 3.5.0 for version 3.5.0 and 3.5.0-r.2 for version 3.5.0.2.

3. Enable automatic signing for your project.
4. Set the deployment target for your app:
   1. In the project editor, choose your target and click General.
   2. In the Deployment Info settings, choose the operating system version for your iOS app from the dropdown menu.

5. Add permissions for microphone and camera usage.
   In the Project navigator, open the info.plist file of your project and add the following properties:
   • Privacy - Microphone Usage Description
   • Privacy - Camera Usage Description

Implement a client for Interactive Live Streaming Standard

This section shows how to use the Agora Video SDK to implement Interactive Live Streaming Standard into your app step by step.

Create the UI

In the interface, you should have one frame for local video and another for remote video. In ViewController.swift, replace any existing content with the following:

import UIKit
class ViewController: UIViewController {
    var localView: UIView!
    var remoteView: UIView!

    override func viewDidLoad() {
        super.viewDidLoad()
        initView()
     }

    override func viewDidLayoutSubviews() {
        super.viewDidLayoutSubviews()
        remoteView.frame = self.view.bounds
        localView.frame = CGRect(x: self.view.bounds.width - 90, y: 0, width: 90, height: 160)
    }

    func initView() {
        remoteView = UIView()
        self.view.addSubview(remoteView)
        localView = UIView()
        self.view.addSubview(localView)
    }
}

Implement the Interactive Live Streaming Standard logic

When your app opens, you create an RtcEngine instance, enable the video, join a channel, and if the local user is a host, publish the local video to the lower frame layout in the UI. When another host joins the channel, your app catches the join event and adds the remote video to the top frame layout in the UI.

The following figure shows the API call sequence of implementing Interactive Live Streaming Standard.

To implement this logic, take the following steps:

1. Import the Agora kit and add the agoraKit variable.
   Modify your ViewController.swift as follows:

   import UIKit
   // Add this line to import the Agora kit 
   import AgoraRtcKit
   class ViewController: UIViewController {
       var localView: UIView!
       var remoteView: UIView!
       // Add this linke to add the agoraKit variable
       var agoraKit: AgoraRtcEngineKit?
   }
   
   override func viewDidLoad() {
              super.viewDidLoad()
              initView()
           }

2. Initialize the app and join the channel.

   Call the core methods to initialize the app and join a channel. In this example app, this functionality is encapsulated in the initializeAndJoinChannel function.

   In ViewController.swift, add the following lines after the initView function, and fill in your App ID, temporary token, and channel name:

    func initializeAndJoinChannel() {
      // Pass in your App ID here
      agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "Your App ID", delegate: self)
      // For a live streaming scenario, set the channel profile as liveBroadcasting.
      agoraKit?.setChannelProfile(.liveBroadcasting)
      // Set the client role as audience and the latency level as low latency.
      let options: AgoraClientRoleOptions = AgoraClientRoleOptions()
      options.audienceLatencyLevel = AgoraAudienceLatencyLevelType.lowLatency
      agoraKit?.setClientRole(.audience, options: options)
      // Video is disabled by default. You need to call enableVideo to start a video stream.
      agoraKit?.enableVideo()
   
      // Join the channel with a token. Pass in your token and channel name here
      agoraKit?.joinChannel(byToken: "Your token", channelId: "Channel name", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
           })
       }

3. Add the remote interface when a remote host joins the channel.

   In ViewController.swift, add the following lines after the ViewController class:

    extension ViewController: AgoraRtcEngineDelegate {
        // This callback is triggered when a remote host joins the channel
        func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
            let videoCanvas = AgoraRtcVideoCanvas()
            videoCanvas.uid = uid
            videoCanvas.renderMode = .hidden
            videoCanvas.view = remoteView
            agoraKit?.setupRemoteVideo(videoCanvas)
        }
    }

Start and stop your app

Now you have created the Interactive Live Streaming Standard functionality, start and stop the app. In this implementation, a live stream starts when the user opens your app. The live stream ends when the user closes your app.

To implement the functionality of starting and stopping the app, do the following:

1. Check that the app has the correct permissions. If permissions are granted, call initializeAndJoinChannel to join a live streaming channel.

   When the view is loaded, call initializeAndJoinChannel to join a live streaming channel.
   In ViewController.swift, add the initializeAndJoinChannel function inside the viewDidLoad function:

   override func viewDidLoad() {
           super.viewDidLoad()
           initView()
           // Add this line
           initializeAndJoinChannel()
        }

2. When the user closes this app, clean up all the resources used by your app.

   In ViewController.swift, add viewDidDisappear after the initializeAndJoinChannel function.

   override func viewDidDisappear(_ animated: Bool) {
          super.viewDidDisappear(animated)
          agoraKit?.leaveChannel(nil)
          AgoraRtcEngineKit.destroy()
    }

Test your app

To test your app on a physical device, do the following:

1. Check whether you fill in your App ID, temporary token, and channel name in ViewController.swift.
2. Connect an iOS device to your computer.
3. In Xcode, choose the device from the scheme menu in the toolbar, and click the Run button.
4. On your device, launch the app. In your app, the client role is set as audience. You do not see yourself on the local view.
5. Ask a friend to join the live streaming with you on the demo app. Enter the same App ID and channel name. After your friend joins the channel, you should be able to see and hear your friend, but your friend will not be able to see or hear you.

Next steps

Generating a token by hand is not helpful in a production context. Authenticate Your Users with Tokens shows you how to start live streaming with a token that you retrieve from your server.

See also

This section provides additional information for your reference.

Other approaches to integrate the latest SDK

In addition to integrating the Agora Video SDK for iOS through Swift Package, you can also import the SDK into your project through CocoaPods or by manually copying the SDK files.

Automatically integrate the SDK with CocoaPods

1. Install CocoaPods if you have not. See Getting Started with CocoaPods.

2. In Terminal, navigate to the root of your project folder, and run the pod init command to create a Podfile in the project folder.

3. Open the Podfile, and replace all contents with the following code. Remember to replace Your App with the target name of your project.

   # platform :ios, '9.0'
   target 'Your App' do
      pod 'AgoraRtcEngine_iOS'
   end

4. In Terminal, run the pod install command to install the SDK. When the SDK is installed successfully, you can see Pod installation complete! in Terminal and an xcworkspace file in the project folder.
5. Open the xcworkspace file for any further steps.

Manually copy the SDK files

1. Go to SDK Downloads, download the latest version of the Agora Video SDK, and extract the files from the downloaded SDK package.

2. From the libs folder of the downloaded SDK package, copy the files or subfolders you need to the root of your project folder.

3. In Xcode, link your target to the frameworks or libraries you have copied. Be sure to choose Embed & Sign from the pop-up menu in the Embed column.

   • Apple does not allow an app extension to contain any dynamic library. If you are integrating the Agora SDK to an app extension, choose Do Not Embed in the Embed column.
   • The Agora SDK uses libc++ (LLVM) by default. Contact support@agora.io if you want to use libstdc++ (GNU). The SDK provides FAT image libraries with multi-architecture support for both 32/64-bit audio emulators and 32/64-bit audio/video real devices.

Objective-C code sample

To implement live streaming in your app using Objective-C:

1. Replace the contents in the ViewController.h file with the following:

   #import <UIKit/UIKit.h>
   
   #import <AgoraRtcKit/AgoraRtcEngineKit.h>
   
   @interface ViewController : UIViewController <AgoraRtcEngineDelegate>
   @property (strong, nonatomic) AgoraRtcEngineKit *agoraKit;
   
   @end

2. Replace the contents in the ViewController.m file with the following:

   #import "ViewController.h"
   #import <UIKit/UIKit.h>
   
   @interface ViewController ()
   @property (nonatomic, strong) UIView *localView;
   @property (nonatomic, strong) UIView *remoteView;
   @end
   
   @implementation ViewController
   - (void)viewDidLoad {
       [super viewDidLoad];
       [self initViews];
       [self initializeAndJoinChannel];
   }
   
   - (void)viewDidLayoutSubviews {
       [super viewDidLayoutSubviews];
       self.remoteView.frame = self.view.bounds;
       self.localView.frame = CGRectMake(self.view.bounds.size.width - 90, 0, 90, 160);
   }
   
   - (void)initViews {
       self.remoteView = [[UIView alloc] init];
       [self.view addSubview:self.remoteView];
       self.localView = [[UIView alloc] init];
       [self.view addSubview:self.localView];
   }
   
   - (void)initializeAndJoinChannel {
       // Pass in your App ID here
       self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"Your App ID" delegate:self];
       [self.agoraKit setChannelProfile:AgoraChannelProfileLiveBroadcasting];
       AgoraClientRoleOptions *options = [AgoraClientRoleOptions alloc];
       options.audienceLatencyLevel = AgoraAudienceLatencyLevelLowLatency;
       [self.agoraKit setClientRole:AgoraClientRoleAudience options:options];
       [self.agoraKit enableVideo];
       AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
       videoCanvas.uid = 0;
       videoCanvas.renderMode = AgoraVideoRenderModeHidden;
       videoCanvas.view = self.localView;
       [self.agoraKit setupLocalVideo:videoCanvas];
       // Pass in your token and channel name here
       [self.agoraKit joinChannelByToken:@"Your token" channelId:@"Channel name" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
       }];
   }
   
   - (void)rtcEngine:(AgoraRtcEngineKit *)engine didJoinedOfUid:(NSUInteger)uid elapsed:(NSInteger)elapsed {
       AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
       videoCanvas.uid = uid;
       videoCanvas.renderMode = AgoraVideoRenderModeHidden;
       videoCanvas.view = self.remoteView;
       [self.agoraKit setupRemoteVideo:videoCanvas];
   }
   
   - (void)viewDidDisappear:(BOOL)animated {
     [super viewDidDisappear:animated];
     [self.agoraKit leaveChannel:nil];
     [AgoraRtcEngineKit destroy];
   }
   @end

Integrate earlier versions of the SDK

Choose one of the following methods to integrate a version of the Agora iOS SDK earlier than v3.2.0.

Method 1: Through CocoaPods

1. Ensure that you have installed CocoaPods before performing the following steps. See the installation guide in Getting Started with CocoaPods.

2. In Terminal, navigate to the project path, and run the pod init command to create a Podfile in the project folder.

3. Open the Podfile, delete all contents, and input the following codes. Remember to replace Your App with the target name of your project and replace version with the version of the SDK that you want to integrate. For information about the SDK version, see Release Notes.

   # platform :ios, '9.0'
   target 'Your App' do
    pod 'AgoraRtcEngine_iOS', 'version'
   end

4. Return to Terminal, and run the pod install command to install the Agora SDK. Once you successfully install the SDK, it shows Pod installation complete! in Terminal, and you can see an xcworkspace file in the project folder.

5. Open the generated xcworkspace file.

Method 2: Through your local storage

You need to use different integration methods to integrate different versions of the SDK. Click the following version categories to expand the corresponding integration steps.

Distribution consideration

If you integrate dynamic libraries under the path of ./libs/ALL_ARCHITECTURE in the SDK package, you need to remove the x86-64 architecture in the libraries before uploading the app to the App Store.

In Terminal, run the following command to remove the x86-64 architecture. Remember to replace ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit with the path of the dynamic library in your project.

lipo -remove x86-64 ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit -output ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit

See more considerations in Preparing Your App for Distribution.