本文介绍如何使用声网视频 SDK 快速实现视频直播。
打开 Xcode 并点击 Create a new Xcode project。
选择平台类型为 macOS、项目类型为 App,并点击 Next。
输入项目名称(Product Name)、开发团队信息(Team)、组织名称(Organization Name)和语言(Language)等项目信息,并点击 Next。
选择项目存储路径,并点击 Create。
选择如下任意一种方式集成最新版声网macOS SDK。
开始前确保你已安装 Cocoapods。参考 Getting Started with CocoaPods 安装说明。
在终端里进入项目根目录,并运行 pod init
命令。项目文件夹下会生成一个 Podfile
文本文件。
打开 Podfile
文件,修改文件为如下内容。注意将 Your App
替换为你的 Target 名称。
# platform :macos, '10.11'
target 'Your App' do
pod 'AgoraRtcEngine_macOS'
end
在终端内运行 pod install
命令安装 SDK。成功安装后,Terminal 中会显示 Pod installation complete!
,此时项目文件夹下会生成一个 xcworkspace
文件。
打开新生成的 xcworkspace
文件。
前往 SDK 下载页面,获取最新版的声网macOS 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_macOS
在 Choose Package Options 中指定你想集成的 SDK 版本。如果版本号为 x.y.z,你需要填入 x.y.z;如果版本号为 x.y.z.a,你需要填入 x.y.z-r.a。
现在,我们已经将声网macOS SDK 集成到项目中了。接下来我们要在 ViewController
中调用声网macOS SDK 提供的核心 API 实现基础的视频互动直播功能,API 调用时序见下图。
根据场景需要,为你的项目创建视频互动直播的用户界面。我们推荐你在项目中添加主播的视频窗口,你可以参考以下代码创建一个基础的用户界面。
// ViewController.h
// 导入 AppKit
#import <AppKit/AppKit.h>
@interface ViewController ()
// 定义 localView 变量
@property (nonatomic, strong) NSView *localView;
// 定义 remoteView 变量
@property (nonatomic, strong) NSView *remoteView;
@end
@implementation ViewController
...
- (void)viewDidLoad {
...
// 调用初始化视频窗口函数
[self initViews];
}
// 设置视频窗口布局
- (void)viewDidLayout {
[super viewDidLayout];
self.remoteView.frame = self.view.bounds;
self.localView.frame = CGRectMake(self.view.bounds.size.width - 90, 0, 90, 160);
}
- (void)initViews {
// 初始化远端视频窗口。只有当远端用户为主播时,才会显示视频画面
self.remoteView = [[NSView alloc] init];
[self.view addSubview:self.remoteView];
// 初始化本地视频窗口。只有当本地用户为主播时,才会显示视频画面
self.localView = [[NSView alloc] init];
[self.view addSubview:self.localView];
}
...
@end
// ViewController.swift
// 导入 AppKit
import AppKit
class ViewController: NSViewController {
...
// 定义 localView 变量
var localView: NSView!
// 定义 remoteView 变量
var remoteView: NSView!
override func viewDidLoad() {
...
// 调用初始化视频窗口函数
initView()
}
// 设置视频窗口布局
override func viewDidLayout() {
super.viewDidLayout()
remoteView.frame = self.view.bounds
localView.frame = CGRect(x: self.view.bounds.width - 90, y: 0, width: 90, height: 160)
}
func initView() {
// 初始化远端视频窗口。只有当远端用户为主播时,才会显示视频画面
remoteView = NSView()
self.view.addSubview(remoteView)
// 初始化本地视频窗口。只有当本地用户为主播时,才会显示视频画面
localView = NSView()
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 : NSViewController <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: NSViewController {
...
// 定义 agoraKit 变量
var agoraKit: AgoraRtcEngineKit?
}
调用 sharedEngineWithAppId
创建并初始化 AgoraRtcEngineKit
对象。你需要将 YourAppID
替换为你的声网项目的 App ID。详见获取 App ID。
你还可以根据场景需要,在初始化时注册想要监听的回调事件。
// ViewController.m
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithAppId:@"YourAppID" delegate:self];
// ViewController.swift
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
agoraKit = AgoraRtcEngineKit.sharedEngine(withAppId: "YourAppID", delegate: self)
调用 setChannelProfile
方法,将频道场景设为直播。
一个 AgoraRtcEngineKit
只能使用一种频道场景。如果想切换为其他频道场景,需要先调用 destroy
方法销毁当前的 AgoraRtcEngineKit
对象,然后使用 sharedEngineWithAppId
方法创建一个新的对象,再调用 setChannelProfile
设置新的频道场景。
// ViewController.m
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
[self.agoraKit setChannelProfile:AgoraChannelProfileLiveBroadcasting];
// ViewController.swift
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
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
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 设置用户角色为主播
[self.agoraKit setClientRole:AgoraClientRoleBroadcaster];
// 设置用户角色为观众
AgoraClientRoleOptions *options = [AgoraClientRoleOptions alloc];
options.audienceLatencyLevel = AgoraAudienceLatencyLevelLowLatency;
[self.rtcEngineKit setClientRole:AgoraClientRoleAudience options:options];
// ViewController.swift
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 设置用户角色为主播
agoraKit?.setClientRole(.broadcaster)
// 设置用户角色为观众
let options: AgoraClientRoleOptions = AgoraClientRoleOptions()
options.audienceLatencyLevel = AgoraAudienceLatencyLevelType.lowLatency
agoraKit.setClientRole(.audience, options: options)
在加入频道前设置本地视图,以便主播在直播中看到本地图像。参考以下步骤设置本地视图:
enableVideo
启用视频模块。setupLocalVideo
设置本地视图。// ViewController.m
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 启用视频模块
[self.agoraKit enableVideo];
AgoraRtcVideoCanvas *videoCanvas = [[AgoraRtcVideoCanvas alloc] init];
videoCanvas.uid = 0;
videoCanvas.renderMode = AgoraVideoRenderModeHidden;
videoCanvas.view = self.localView;
// 设置本地视图
[self.agoraKit setupLocalVideo:videoCanvas];
// ViewController.swift
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 启用视频模块
agoraKit?.enableVideo()
let videoCanvas = AgoraRtcVideoCanvas()
videoCanvas.uid = 0
videoCanvas.renderMode = .hidden
videoCanvas.view = localView
// 设置本地视图
agoraKit?.setupLocalVideo(videoCanvas)
调用 joinChannelByToken
加入频道。
在 joinChannelByToken
中你需要将 YourToken
替换成你自己生成的 Token,并将 YourChannelName
替换为你生成 Token 时填入的频道名称。
// ViewController.m
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 频道内每个用户的 uid 必须是唯一的
[self.agoraKit joinChannelByToken:@"YourToken" channelId:@"YourChannelName" info:nil uid:0 joinSuccess:^(NSString * _Nonnull channel, NSUInteger uid, NSInteger elapsed) {
}];
// ViewController.swift
// 将以下代码填入你定义的函数中,例如 viewDidLoad()
// 频道内每个用户的 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
// 声明 AgoraRtcEngineDelegate,用于监听回调
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
// 将以下代码填入你定义的函数中
[self.agoraKit leaveChannel:nil];
// ViewController.swift
// 将以下代码填入你定义的函数中
agoraKit?.leaveChannel(nil)
离开频道后,如果你想释放声网 SDK 使用的所有资源,需调用 destroy
销毁 AgoraRtcEngineKit
对象。
// ViewController.m
// 将以下代码填入你定义的函数中
[AgoraRtcEngineKit destroy];
// ViewController.swift
// 将以下代码填入你定义的函数中
AgoraRtcEngineKit.destroy()
在运行项目前,你需要设置签名和开发团队,并添加设备权限。
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。 |
Capability | Category | Permission |
---|---|---|
App Sandbox | Network |
|
App Sandbox | Hardware |
|
Hardened Runtime | Resource Access |
|
我们建议在 macOS 真机中运行你的项目。运行成功后,主播可以看到本地视频。
你可以邀请一位朋友克隆 API-Examples-Web 项目到本地,在浏览器中打开 Demo/index.html
文件,并输入相同的 App ID、频道名和临时 Token,加入同一频道与 macOS 端互通。当成功开始视频互动直播时,主播可以看到自己和其他主播的视频;观众可以看到主播的视频。
选择如下任意一种方式集成历史版本声网macOS SDK。
开始前确保你已安装 Cocoapods。参考 Getting Started with CocoaPods 安装说明。
在终端里进入项目根目录,并运行 pod init
命令。项目文件夹下会生成一个 Podfile
文本文件。
Podfile
文件,修改文件为如下内容。注意将 Your App
替换为你的 Target 名称,并将 version
替换为你需集成的 SDK 版本。如需了解 SDK 版本信息,查看发版说明。# platform :macos, '10.11'
target 'Your App' do
pod 'AgoraRtcEngine_macOS', 'version'
end
在终端内运行 pod install
命令安装声网 SDK。成功安装后,Terminal 中会显示 Pod installation complete!
,此时项目文件夹下会生成一个 xcworkspace
文件。
打开新生成的 xcworkspace
文件。
不同版本的 SDK 集成方式不同,点击下列版本分类展开集成步骤。
AgoraRtcKit.framework
、Agorafdkaac.framework
、Agoraffmpeg.framework
和 AgoraSoundTouch.framework
动态库到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。AgoraRtcKit.framework
、Agorafdkaac.framework
、Agoraffmpeg.framework
和 AgoraSoundTouch.framework
动态库,并确保添加的动态库 Embed 属性设置为 Embed & Sign。复制 SDK 包中的 AgoraRtcKit.framework
动态库到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。
打开 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_macOS_..._Dynamic/libs
。./Agora_Native_SDK_for_macOS_.../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 CoreWLAN.framework libc++.tbd libresolv.9.tbd SystemConfiguration.framework |
视频 SDK | AgoraRtcKit.framework Accelerate.framework CoreWLAN.framework libc++.tbd libresolv.9.tbd SystemConfiguration.framework VideoToolbox.framework |
AgoraRtcEngineKit.framework
静态库复制到项目的 ./project_name
文件夹下(project_name
为你的项目名称)。AgoraRtcEngineKit.framework
时,还需在点击 + 后点击 Add Other… > Add Files,找到本地文件并打开。SDK | 库 |
---|---|
音频 SDK | AgoraRtcEngineKit.framework Accelerate.framework CoreWLAN.framework libc++.tbd libresolv.9.tbd SystemConfiguration.framework |
视频 SDK | AgoraRtcEngineKit.framework Accelerate.framework CoreWLAN.framework libc++.tbd libresolv.9.tbd SystemConfiguration.framework VideoToolbox.framework |