Use this guide to quickly start interactive live audio streaming with the Agora Voice SDK for iOS.

Understand the tech

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

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

1. Set the client role
   Each user in an Interactive Live Streaming Premium channel is either a host or an audience member. Hosts publish streams to the channel, and the audience subscribe to the streams.

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, you can 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

• Xcode 9.0 or later (the interface description in this article is based on Xcode 11.0).
• An iOS device running iOS 8.0 or later.
• A valid Agora account.

Create an iOS project

1. Open Xcode, and click Create a new Xcode project.

2. Choose iOS as the target platform, Single View App as the template, and click Next.

3. Input the project information, such as the product name, team, organization name, and language, and click Next.

   If you have not added any team information, you can see an Add account... button. Click it, input your Apple ID, and click Next to add your team.

4. Choose the storage path of the project, and click Create.

Integrate the SDK

Choose one of the following methods to obtain the Agora iOS SDK:

Method 1: Through CocoaPods

1. Ensure that you have installed CocoaPods before 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.

# platform :ios, '9.0'
target 'Your App' do
    pod 'AgoraAudio_iOS'
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 the Agora website

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

2. According to your requirements, copy the libraries from the libs folder of the SDK to the ./project_name folder in your project (project_name is an example of your project name).

   The libraries with the Extension suffix are optional. Add the corresponding libraries according to your needs. For the feature of each extension library, see extension libraries.

3. Open Xcode, and navigate to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content.

4. Click + > Add Other… > Add Files to add the corresponding libraries. Ensure that the Embed attribute of these dynamic libraries is Embed & Sign.

   Once these dynamic libraries are added, the project automatically links to other system libraries.

   • According to the official requirements of Apple, the Extension of an app cannot contain the dynamic library. If you need to integrate the SDK with the dynamic library in the Extension, change the file status to Do Not Embed.
   • 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.

Implementation

Once you have integrated the Agora iOS SDK into your project, you need to call the core APIs provided by the Agora iOS SDK in the ViewController file to implement basic live audio streaming. The API call sequence is shown in the following figure:

1. Import AgoraRtcKit

Before calling any Agora API in your project, import the AgoraRtcKit class, and define agoraKit.

// Objective-C
// ViewController.h
// If you use a SDK earlier than 3.0.0, use #import <AgoraRtcEngineKit/AgoraRtcEngineKit.h> instead
#import <AgoraRtcKit/AgoraRtcEngineKit.h>
// Specifies AgoraRtcEngineDelegate for monitoring a callback
@interface ViewController : UIViewController <AgoraRtcEngineDelegate>
// Defines agoraKit
@property (strong, nonatomic) AgoraRtcEngineKit *agoraKit;

// Swift
// ViewController.swift
// If you use a SDK earlier than 3.0.0, use import AgoraRtcEngineKit instead
import AgoraRtcKit
class ViewController: UIViewController {
    ...
    // Defines agoraKit
    var agoraKit: AgoraRtcEngineKit?
}

2. Initialize AgoraRtcEngineKit

Call the sharedEngineWithAppId method to create and initialize the AgoraRtcEngineKit object. When adding the following code in your project, replace YourAppID with the App ID of your project. See Get an App ID.

If you want to monitor a callback for your app scenario, register it when initializing AgoraRtcEngineKit.

// Objective-C
// ViewController.m
@implementation ViewController
- (void)viewDidLoad {
    [super viewDidLoad];
    // The following functions are used when calling Agora APIs
    [self initializeAgoraEngine];
    [self setChannelProfile];
    [self setClientRole];
    [self joinChannel];
}
- (void)initializeAgoraEngine {
    // Initializes AgoraRtcEngineKit
    self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"YourAppID" delegate:self];
}

// Swift
// ViewController.swift
class ViewController: UIViewController {
    ...
     override func viewDidLoad() {
        super.viewDidLoad()
        // The following functions are used when calling Agora APIs
        initializeAgoraEngine()
        setChannelProfile()
        setClientRole()
        joinChannel()  
     }
func initializeAgoraEngine() {
       // Initializes AgoraRtcEngineKit
             agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "YourAPPID", delegate: self)
    }
}

3. Set the channel profile

Call the setChannelProfile method to set the channel profile as LiveBroadcasting.

Each AgoraRtcEngineKit object supports one profile only. If you want to switch to another profile, destroy the current AgoraRtcEngineKit object with destroy, and create a new one with sharedEngineWithAppId; then, call setChannelProfile again.

// Objective-C
// ViewController.m
- (void)setChannelProfile {
[self.agoraKit setChannelProfile:AgoraChannelProfileLiveBroadcasting];
}

// Swift
// ViewController.swift
func setChannelProfile(){
agoraKit?.setChannelProfile(.liveBroadcasting)
}

4. Set the client role

An interactive live streaming channel has two client roles: Broadcaster and Audience; the default role is Audience. After setting the channel profile to LiveBroadcasting, set the client role using the following steps:

1. Ask the user to choose a client role.
2. Call the setClientRole method, and pass in the client role set by the user.

Note that in interactive live audio streaming, only the host can be heard. If you want to switch the client role after joining the channel, call the setClientRole method again.

// Objective-C
// ViewController.m
- (void)setClientRole {
// Set the client role as "host"
[self.agoraKit setClientRole:AgoraClientRoleBroadcaster];
// Set the client role as "audience"
[self.agoraKit setClientRole:AgoraClientRoleAudience];
}

// Swift
// ViewController.swift
func setClientRole(){
// Set the client role as "host"
agoraKit?.setClientRole(.broadcaster)
// Set the client role as "audience"
agoraKit?.setClientRole(.audience)
}

5. Join a channel

Call the joinChannelByToken method to join a channel.
When adding the following code in your project, replace YourToken with the token of your project, and replace YourChannelName with the channel name used to generate the token of your project.

• For testing, you can generate a temporary token in Agora Console. When joining a channel, ensure that the channel name is the same with the one you use to generate the temporary token.
• For production, Agora recommends using a token generated at your server. See Generate a Token. When joining a channel, ensure that the channel name and uid is the same with those you use to generate the token.

// Objective-C
// ViewController.m
- (void)joinChannel {
    // The uid of each user in the channel must be unique.
    [self.agoraKit joinChannelByToken:@"YourToken" channelId:@"YourChannelName" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
}];
}

// Swift
// ViewController.swift
func joinChannel(){
        // The uid of each user in the channel must be unique.
        agoraKit?.joinChannel(byToken: "YourToken", channelId: "YourChannelName", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
    })
}

6. Leave the channel

Call the leaveChannel method when you need to leave the channel, for example, to end the call, close the app, or run the app in the background.

// Objective-C
// ViewController.m
// Add the following code in a defined function
[self.agoraKit leaveChannel:nil];

// Swift
// ViewController.swift
// Add the following code in a defined function
agoraKit?.leaveChannel(nil)

7. Destroy AgoraRtcEngineKit

After leaving the channel, if you want to release the resources used by the Agora SDK, call the destroy method to destroy the AgoraRtcEngineKit object.

// Objective-C
// ViewController.m
// Add the following code in a defined function
[AgoraRtcEngineKit destroy];

// Swift
// ViewController.swift
// Add the following code in a defined function
AgoraRtcEngineKit.destroy()

Run the project

Before running the project, you need to set your signing and team, and add device permissions.

1. Set your signing and team

1. In Xcode, navigate to TARGETS > Project Name > General > Signing, and choose Automatically manage signing.
2. Read the prompts carefully, and click Enable Automatic.
3. After you successfully set your signing, choose a developer in Team.

2. Add device permissions

In Xcode, open the info.plist file. Add the following contents to add permissions for your device:

3. Try interactive live audio streaming

Agora recommends running the project on a real device instead of a simulator.

To test the remote audio, visit the Web Demo, and enter the same App ID, channel name, and token to join the same channel. If live audio streaming runs successfully, a host should hear the other hosts; an audience member should hear all hosts.

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 'AgoraAudio_iOS'
   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.

Reference

• How can I set the log file?
• How can I listen for an audience joining or leaving an interactive live streaming channel?
• Why do I see a prompt to find local network devices when launching an iOS app?