本文介绍如何使用声网视频 SDK 快速实现视频直播。
打开 Xcode 并点击 Create a new Xcode project。
选择平台类型为 iOS、项目类型为 Single View App,并点击 Next。
输入项目名称(Product Name)、开发团队信息(Team)、组织名称(Organization Name)和语言(Language)等项目信息,并点击 Next。
选择项目存储路径,并点击 Create。
选择如下任意一种方式获取最新版声网iOS SDK。
开始前确保你已安装 Cocoapods。参考 Getting Started with CocoaPods 安装说明。
在终端里进入项目根目录,并运行 pod init
命令。项目文件夹下会生成一个 Podfile
文本文件。
打开 Podfile
文件,修改文件为如下内容。注意将 Your App
替换为你的 Target 名称。
# platform :ios, '9.0'
target 'Your App' do
pod 'AgoraRtcEngine_iOS'
end
在终端内运行 pod install
命令安装 SDK。成功安装后,Terminal 中会显示 Pod installation complete!
,此时项目文件夹下会生成一个 xcworkspace
文件。
打开新生成的 xcworkspace
文件。
前往 SDK 下载页面,获取最新版的声网iOS SDK,然后解压。
根据你的需求,将 libs
文件夹中的动态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。
打开 Xcode,进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。
点击 + > Add Other… > Add Files 添加对应动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。
添加完成后,项目会自动链接所需系统库。
在 Xcode 中,进入 File > Swift Packages > Add Package Dependencies...,粘贴如下 URL:
https://github.com/AgoraIO/AgoraRtcEngine_iOS
在 Choose Package Options 中指定你想集成的 SDK 版本。如果版本号为 x.y.z,你需要填入 x.y.z;如果版本号为 x.y.z.a,你需要填入 x.y.z-r.a。
现在,我们已经将声网iOS SDK 集成到项目中了。接下来我们要在 ViewController
中调用声网iOS SDK 提供的核心 API 实现基础的视频互动直播功能,API 调用时序见下图。
根据场景需要,为你的项目创建视频互动直播的用户界面。我们推荐你在项目中添加主播的视频窗口,你可以参考以下代码创建一个基础的用户界面。
// ViewController.m
// 导入 UIKit
#import <UIKit/UIKit.h>
@interface ViewController ()
// 定义 localView 变量
@property (nonatomic, strong) UIView *localView;
// 定义 remoteView 变量
@property (nonatomic, strong) UIView *remoteView;
@end
@implementation ViewController
...
- (void)viewDidLoad {
[super viewDidLoad];
// 调用初始化视频窗口函数
[self initViews];
// 后续步骤调用声网 API 使用的函数
[self initializeAgoraEngine];
[self setChannelProfile];
[self setClientRole];
[self setupLocalVideo];
[self joinChannel];
}
// 设置视频窗口布局
- (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];
}
// ViewController.swift
// 导入 UIKit
import UIKit
class ViewController: UIViewController {
...
// 定义 localView 变量
var localView: UIView!
// 定义 remoteView 变量
var remoteView: UIView!
override func viewDidLoad() {
super.viewDidLoad()
// 调用初始化视频窗口函数
initView()
// 后续步骤调用声网 API 使用的函数
initializeAgoraEngine()
setChannelProfile()
setClientRole()
setupLocalVideo()
joinChannel()
}
// 设置视频窗口布局
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)
}
}
在调用声网 API 前,你需要在项目中导入 AgoraRtcKit
类,并定义一个 agoraKit
变量。
// ViewController.h
// 导入 AgoraRtcKit 类
// 自 3.0.0 版本起,AgoraRtcEngineKit 类名更换为 AgoraRtcKit
// 如果获取的是 3.0.0 以下版本的 SDK,请改用 #import <AgoraRtcEngineKit/AgoraRtcEngineKit.h>
#import <AgoraRtcKit/AgoraRtcEngineKit.h>
// 声明 AgoraRtcEngineDelegate,用于监听回调
@interface ViewController : UIViewController <AgoraRtcEngineDelegate>
// 定义 agoraKit 变量
@property (strong, nonatomic) AgoraRtcEngineKit *agoraKit;
// ViewController.swift
// 导入 AgoraRtcKit 类
// 自 3.0.0 版本起,AgoraRtcEngineKit 类名更换为 AgoraRtcKit
// 如果获取的是 3.0.0 以下版本的 SDK,请改用 import AgoraRtcEngineKit
import AgoraRtcKit
class ViewController: UIViewController {
...
// 定义 agoraKit 变量
var agoraKit: AgoraRtcEngineKit?
}
调用 sharedEngineWithAppId
创建并初始化 AgoraRtcEngineKit
对象。你需要将 YourAppID
替换为你的声网项目的 App ID。详见获取 App ID。
你还可以根据场景需要,在初始化时注册想要监听的回调事件。
// ViewController.m
- (void)initializeAgoraEngine {
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"YourAppID" delegate:self];
}
// ViewController.swift
func initializeAgoraEngine() {
agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "YourAPPID", delegate: self)
}
调用 setChannelProfile
方法,将频道场景设为直播。
一个 AgoraRtcEngineKit
只能使用一种频道场景。如果想切换为其他频道场景,需要先调用 destroy
方法销毁当前的 AgoraRtcEngineKit
对象,然后使用 sharedEngineWithAppId
方法创建一个新的对象,再调用 setChannelProfile
设置新的频道场景。
// ViewController.m
- (void)setChannelProfile {
[self.agoraKit setChannelProfile:AgoraChannelProfileLiveBroadcasting];
}
// ViewController.swift
func setChannelProfile(){
agoraKit?.setChannelProfile(.liveBroadcasting)
}
直播频道中可设置用户角色和用户级别:
你可以在 app 中参考如下步骤设置用户角色:
setClientRole
方法,然后根据终端用户的选择设置 role
和 options
参数。role
设为 AgoraClientRoleBroadcaster
(主播)时, options
参数留空。此时主播端延时为 < 400 ms。role
设为 AgoraClientRoleAudience
(观众)时,你还需要将 options
中 audienceLatencyLevel
参数设为 AgoraAudienceLatencyLevelLowLatency
。此时观众端延时为 1500 ms - 2000 ms。AgoraAudienceLatencyLevelLowLatency
(低延时)切换为 AgoraAudienceLatencyLevelUltraLowLatency
(超低延时),会从极速直播产品切换为互动直播产品,延时会变为 400 ms - 800 ms。AgoraClientRoleAudience
(观众)切换为 AgoraClientRoleBroadcaster
(主播),会从极速直播产品切换为互动直播产品,延时会低于 400 ms。AgoraAudienceLatencyLevelLowLatency
时,RemoteAudioStats
中的 jitterBufferDelay
字段(接收端到网络抖动缓冲的网络延迟)不生效。// ViewController.m
- (void)setClientRole {
// 设置用户角色为主播
[self.agoraKit setClientRole:AgoraClientRoleBroadcaster];
// 设置用户角色为观众
AgoraClientRoleOptions *options = [AgoraClientRoleOptions alloc];
options.audienceLatencyLevel = AgoraAudienceLatencyLevelLowLatency;
[self.rtcEngineKit setClientRole:AgoraClientRoleAudience options:options];
}
// ViewController.swift
func setClientRole(){
// 设置用户角色为主播
agoraKit?.setClientRole(.broadcaster)
// 设置用户角色为观众
let options: AgoraClientRoleOptions = AgoraClientRoleOptions()
options.audienceLatencyLevel = AgoraAudienceLatencyLevelType.lowLatency
agoraKit.setClientRole(.audience, options: options)
}
在加入频道前设置本地视图,以便主播在直播中看到本地图像。参考以下步骤设置本地视图:
enableVideo
方法启用视频模块。setupLocalVideo
方法设置本地视图。// ViewController.m
- (void)setupLocalVideo {
// 启用视频模块
[self.agoraKit enableVideo];
AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
videoCanvas.uid = 0;
videoCanvas.renderMode = AgoraVideoRenderModeHidden;
videoCanvas.view = self.localView;
// 设置本地视图
[self.agoraKit setupLocalVideo:videoCanvas];
}
// ViewController.swift
func setupLocalVideo() {
// 启用视频模块
agoraKit?.enableVideo()
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.uid = 0
videoCanvas.renderMode = .hidden
videoCanvas.view = localView
// 设置本地视图
agoraKit?.setupLocalVideo(videoCanvas)
}
调用 joinChannelByToken
加入频道。
在 joinChannelByToken
中你需要将 YourToken
替换成你自己生成的 Token,并将 YourChannelName
替换为你生成 Token 时填入的频道名称。
在测试阶段,你可以直接在控制台生成临时 Token。加入频道时,请确保填入的频道名和生成临时 Token 时填入的频道名一致。
在生产环境,我们推荐你在自己的服务端生成 Token,详见在服务端生成 Token。加入频道时,请确保填入的频道名和 uid 与生成 Token 时填入的频道名和 uid 一致。
mute
方法实现。// ViewController.m
- (void)joinChannel {
// 频道内每个用户的 uid 必须是唯一的
[self.agoraKit joinChannelByToken:@"YourToken" channelId:@"YourChannelName" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
}];
}
// ViewController.swift
func joinChannel(){
// 频道内每个用户的 uid 必须是唯一的
agoraKit?.joinChannel(byToken: "YourToken", channelId: "YourChannelName", info: nil, uid: 0, joinSuccess: { (channel, uid, elapsed) in
})
}
视频互动直播中,通常你也需要看到其他主播。
远端主播成功加入频道后,SDK 会触发 didJoinedOfUid
回调,该回调中会包含这个远端主播的 uid
信息。在该回调中调用 setupRemoteVideo
方法,传入获取到的 uid
,设置远端主播的视图。
// ViewController.m
// 监听 didJoinedOfUid 回调
// 远端主播加入频道时,会触发该回调
- (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];
}
// ViewController.swift,需要在 class ViewController: UIViewController 函数之外添加以下代码
extension ViewController: AgoraRtcEngineDelegate {
// 监听 didJoinedOfUid 回调
// 远端主播加入频道时,会触发该回调
func rtcEngine(_ engine: AgoraRtcEngineKit, didJoinedOfUid uid: UInt, elapsed: Int) {
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.uid = uid
videoCanvas.renderMode = .hidden
videoCanvas.view = remoteView
// 设置远端视图
agoraKit?.setupRemoteVideo(videoCanvas)
}
}
根据场景需要,如结束直播、关闭 app 或 app 切换至后台时,调用 leaveChannel
离开当前直播频道。
// ViewController.m
- (void)leaveChannel {
[self.agoraKit leaveChannel:nil];
}
// ViewController.swift
func leaveChannel() {
agoraKit?.leaveChannel(nil)
}
离开频道后,如果你想释放声网 SDK 使用的所有资源,需调用 destroy
销毁 AgoraRtcEngineKit
对象。
// ViewController.m
// 将以下代码填入你定义的函数中
[AgoraRtcEngineKit destroy];
// ViewController.swift
// 将以下代码填入你定义的函数中
AgoraRtcEngineKit.destroy()
在运行项目前,你需要设置签名和开发团队,并添加设备权限。
在 Xcode 中,打开 info.plist
文件。在右侧列表中添加如下内容,获取相应的设备权限:
Key | Type | Value |
---|---|---|
Privacy - Microphone Usage Description | String | 使用麦克风的目的,例如:for a call or live interactive streaming。 |
Privacy - Camera Usage Description | String | 使用摄像头的目的,例如:for a call or live interactive streaming。 |
我们建议在 iOS 真机中运行你的项目。运行成功后,主播可以看到本地视频。
你可以邀请一位朋友克隆 API-Examples-Web 项目到本地,在浏览器中打开 Demo/index.html
文件,并输入相同的 App ID、频道名和临时 Token,加入同一频道与 iOS 端互通。当成功开始视频互动直播时,主播可以看到自己和其他主播的视频;观众可以看到主播的视频。
选择如下任意一种方式集成历史版本声网iOS SDK。
开始前确保你已安装 Cocoapods。参考 Getting Started with CocoaPods 安装说明。
在终端里进入项目根目录,并运行 pod init
命令。项目文件夹下会生成一个 Podfile
文本文件。
Podfile
文件,修改文件为如下内容。注意将 Your App
替换为你的 Target 名称,并将 version
替换为你需集成的 SDK 版本。如需了解 SDK 版本信息,查看发版说明。# platform :ios, '9.0'
target 'Your App' do
pod 'AgoraRtcEngine_iOS', 'version'
end
在终端内运行 pod install
命令安装声网 SDK。成功安装后,Terminal 中会显示 Pod installation complete!
,此时项目文件夹下会生成一个 xcworkspace
文件。
打开新生成的 xcworkspace
文件。
不同版本的 SDK 集成方式不同,点击下列版本分类展开集成步骤。
根据你的需求,选择以下一种方法将 AgoraRtcKit.framework
、Agorafdkaac.framework
、Agoraffmpeg.framework
和 AgoraSoundTouch.framework
动态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。
a. 如果无需使用模拟器运行项目,复制 SDK 包中 ./libs
路径下的上述动态库。
b. 如需使用模拟器运行项目,复制 SDK 包中 ./libs/ALL_ARCHITECTURE
路径下的上述动态库。该路径下的动态库包含 x86-64 架构,会影响 app 在 App Store 的发布,处理方法见发布注意事项。
AgoraRtcKit.framework
、Agorafdkaac.framework
、Agoraffmpeg.framework
和 AgoraSoundTouch.framework
动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。根据你的需求,选择以下一种方法将 AgoraRtcKit.framework
动态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。
a. 如果无需使用模拟器运行项目,复制 SDK 包中 ./libs
路径下的上述动态库。
b. 如需使用模拟器运行项目,复制 SDK 包中 ./libs/ALL_ARCHITECTURE
路径下的上述动态库。该路径下的动态库包含 x86-64 架构,会影响 app 在 App Store 的发布,处理方法见发布注意事项。
打开 Xcode,进入 TARGETS > Project Name > General > Frameworks, Libraries, and Embedded Content 菜单。
点击 + > Add Other… > Add Files 添加 AgoraRtcKit.framework
动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。添加完成后,项目会自动链接所需系统库。
3.0.0 版 SDK 中包含一个 AgoraRtcKit.framework
动态库和一个 AgoraRtcKit.framework
静态库,你可以根据需要选择其中一个库添加。
两个库在 SDK 包中的路径如下:
./Agora_Native_SDK_for_iOS_..._Dynamic/libs
。./Agora_Native_SDK_for_iOS_.../libs
。动态库集成:
AgoraRtcKit.framework
动态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。AgoraRtcKit.framework
动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。静态库集成:
AgoraRtcKit.framework
静态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。AgoraRtcKit.framework
时,还需在点击 + 后点击 Add Other… > Add Files,找到本地文件并打开。SDK | 库 |
---|---|
音频 SDK | AgoraRtcKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreTelephony.framework |
视频 SDK | AgoraRtcKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreML.framework VideoToolbox.framework |
AgoraRtcEngineKit.framework
静态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。AgoraRtcEngineKit.framework
时,还需在点击 + 后点击 Add Other… > Add Files,找到本地文件并打开。SDK | 库 |
---|---|
音频 SDK | AgoraRtcEngineKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreTelephony.framework |
视频 SDK | AgoraRtcEngineKit.framework Accelerate.framework AudioToolbox.framework AVFoundation.framework CoreMedia.framework libc++.tbd libresolv.tbd SystemConfiguration.framework CoreML.framework VideoToolbox.framework |
如果集成了 SDK 包中 ./libs/ALL_ARCHITECTURE
路径下的动态库,你需要在将 app 发布至 App Store 前移除 x86_64 架构。
在终端中运行如下命令,移除 x86_64 架构。注意将 ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit
替换为动态库在你项目中的路径。
lipo -remove x86_64 ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit -output ALL_ARCHITECTURE/AgoraRtcKit.framework/AgoraRtcKit
更多发布注意事项,可以参考 Preparing Your App for Distribution。