Use this guide to quickly start interactive live audio streaming with the Agora Voice SDK for iOS.
Open Xcode, and click Create a new Xcode project.
Choose iOS as the target platform, Single View App as the template, and click Next.
Input the project information, such as the product name, team, organization name, and language, and click Next.
Choose the storage path of the project, and click Create.
Choose one of the following methods to obtain the Agora iOS SDK:
Ensure that you have installed CocoaPods before the following steps. See the installation guide in Getting Started with CocoaPods.
In Terminal, navigate to the project path, and run the pod init
command to create a Podfile
in the project folder.
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' use_frameworks!
target 'Your App' do
pod 'AgoraAudio_iOS'
end
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.
Open the generated xcworkspace
file.
Navigate to SDK Downloads, download the latest version of the Agora iOS SDK, and extract the files from the downloaded SDK package.
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).
Extension
suffix are optional. Add the corresponding libraries according to your needs. For the feature of each extension library, see Release Notes.Open Xcode, and navigate to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content.
Click + > Add Other… > Add Files to add the cooresponding 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.
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:
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?
}
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)
}
}
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)
}
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:
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)
}
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.
mute
methods accordingly.// Objective-C
// ViewController.m
- (void)joinChannel {
[self.agoraKit joinChannelByToken:@"YourToken" channelId:@"YourChannelName" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
}];
}
// Swift
// ViewController.swift
func joinChannel(){
agoraKit?.joinChannel(byToken: "YourToken", channelId: "YourChannelName", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
})
}
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)
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()
Before running the project, you need to set your signing and team, and add device permissions.
In Xcode, open the info.plist
file. Add the following contents to add permissions for your device:
Key | Type | Value |
---|---|---|
Privacy - Microphone Usage Description | String | The purpose for accessing the microphone, such as for a call or interactive live 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.
Choose one of the following methods to integrate a version of the Agora iOS SDK earlier than v3.2.0.
Ensure that you have installed CocoaPods before performing the following steps. See the installation guide in Getting Started with CocoaPods.
In Terminal, navigate to the project path, and run the pod init
command to create a Podfile
in the project folder.
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' use_frameworks!
target 'Your App' do
pod 'AgoraAudio_iOS'
end
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.
Open the generated xcworkspace
file.
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.
According to your requirements, choose one of the following methods to copy the AgoraRtcKit.framework
, Agorafdkaac.framework
, and AgoraSoundTouch.framework
dynamic libraries to the ./project_name
folder in your project (project_name
is an example of your project name):
a. If you do not need to use a simulator to run the project, copy the above dynamic libraries under the path of ./libs
in the SDK package.
b. If you need to use a simulator to run the project, copy the above dynamic libraries under the path of ./libs/ALL_ARCHITECTURE
in the SDK package. The dynamic libraries under this path contains the x86-64 architecture, which affects the distribution of your app in the App Store. See solutions in Distribution consideration.
Click + > Add Other… > Add Files to add the AgoraRtcKit.framework
, Agorafdkaac.framework
, and AgoraSoundTouch.framework
dynamic 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 your requirements, choose one of the following methods to copy the AgoraRtcKit.framework
dynamic library to the ./project_name
folder in your project (project_name
is an example of your project name):
a. If you do not need to use a simulator to run the project, copy the above dynamic library under the path of ./libs
in the SDK package.
b. If you need to use a simulator to run the project, copy the above dynamic library under the path of ./libs/ALL_ARCHITECTURE
in the SDK package. The dynamic libraries under this path contains the x86-64 and i386 architectures, which affects the distribution of your app in the App Store. See solutions in Distribution consideration.
Open Xcode, and navigate to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content.
Click + > Add Other… > Add Files to add the AgoraRtcKit.framework
dynamic library. Ensure that the Embed attribute of the dynamic library is Embed & Sign. Once the dynamic library is added, the project automatically links to other system libraries.
In v3.0.0, the SDK package contains an AgoraRtcKit.framework
dynamic library and an AgoraRtcKit.framework
static library. Choose which of these libraries to add according to your needs.
The paths of the two libraries in the SDK package are as follows:
./Agora_Native_SDK_for_iOS_..._Dynamic/libs
../Agora_Native_SDK_for_iOS_.../libs
.Integrate the dynamic library:
Copy the AgoraRtcKit.framework
dynamic library from the ./libs
path of the SDK package to the ./project_name
folder in your project (project_name
is an example of your project name).
Open Xcode, and navigate to TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content.
Click + > Add Other… > Add Files to add the AgoraRtcKit.framework
dynamic library. Ensure that the Embed attribute of the dynamic library is Embed & Sign.
Once the dynamic library is added, the project automatically links to other system libraries.
Integrate the static library:
AgoraRtcKit.framework
static library from the ./libs
path of the SDK package to the ./project_name
folder in your project (project_name
is an example of your project name).AgoraRtcKit.framework
static library, you need to click +, and then click Add Other....SDK | Library |
---|---|
Voice SDK | AgoraRtcKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreTelephony.framework |
Video SDK | AgoraRtcKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreML.framework VideoToolbox.framework |
AgoraRtcEngineKit.framework
static library from the ./libs
path of the SDK package to the ./project_name
folder in your project (project_name
is an example of your project name).AgoraRtcEngineKit.framework
static library, you need to click +, and then click Add Other....SDK | Library |
---|---|
Voice SDK | AgoraRtcEngineKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreTelephony.framework |
Video SDK | AgoraRtcEngineKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreML.framework VideoToolbox.framework |
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.