实现元直播
- iOS
更新时间
了解声网解决方案在不同平台上的元直播方式,包括接入流程、关键配置和平台差异。
MetaWorld 解决方案支持元语聊、元直播场景。本文介绍如何实现元直播。
示例项目
声网在 GitHub 上提供开源 Agora-MetaWorld 示例项目供你参考。
如果你还需了解 Unity 部分的工程文件和功能指南,请联系 sales@shengwang.cn 获取。
实现元直播
完成集成声网 Meta SDK 后,你可以参考本节实现元直播。
元直播的 API 调用时序见下图:
实现步骤需用到如下类:
AgoraRtcEngineKit类:提供实时音视频功能的核心类。AgoraMetaServiceKit类:提供 Meta 服务的核心类。可用于获取场景资源列表、下载场景资源、删除本地场景资源等场景资源管理,还可用于创建AgoraMetaScene。AgoraMetaScene类:场景资源相关操作。AgoraMetaLocalUserAvatar类:包含在AgoraMetaScene中,生命周期和AgoraMetaScene相同,用于设置虚拟形象(Avatar)。AgoraMetaEventDelegate类:AgoraMetaServiceKit的异步方法的事件回调类。AgoraMetaSceneEventDelegate类:AgoraMetaScene的异步方法的事件回调类。
1. 初始化 RTC 引擎和 Meta 服务
调用 sharedEngineWithConfig 创建 AgoraRtcEngineKit。调用 sharedMetaServiceWithConfig 创建并初始化 AgoraMetaServiceKit。
初始化 AgoraMetaServiceKit 时,需要在 AgoraMetaServiceConfig 里设置如下重要的字段:
rtcEngine:通过sharedEngineWithConfig方法创建的AgoraRtcEngineKit实例。appId:在声网控制台获取的 App ID。详见开通元语聊服务。userId:登录声网 RTM 系统的用户 ID。推荐取值详见 AgoraMetaServiceConfig。rtmToken:用于登录声网 RTM 系统的动态密钥。开启动态鉴权后可用。详见生成 Token。localDownloadPath:场景资源下载到本地的保存路径。delegate``:AgoraMetaServiceKit的回调事件。
声网项目有两种 Token 和 UID,请不要搞混淆:
- RTC UID:用于在实时音视频通讯中标志用户身份的用户 ID。推荐取值详见 joinChannelByToken 的参数解释。
- RTM UID:用于在云信令系统中标志用户身份的用户 ID。推荐取值详见 AgoraMetaServiceConfig 的字段解释。
- RTC Token:用于保障实时音视频通讯安全的动态密钥。详见如何生成 RTC Token 进行鉴权。
- RTM Token:用于保障云信令系统安全的动态密钥。详见如何生成 RTM Token 进行鉴权。
func createRtcEngine() {
guard let token = KeyCenter.RTM_TOKEN else { return }
// 设置 AgoraRtcEngineKit 配置信息
let rtcEngineConfig = AgoraRtcEngineConfig()
// 声网项目的 App ID,从控制台获取
rtcEngineConfig.appId = KeyCenter.APP_ID
rtcEngineConfig.areaCode = .global
// 创建和初始化 AgoraRtcEngineKit
rtcEngine = AgoraRtcEngineKit.sharedEngine(with: rtcEngineConfig, delegate: self)
rtcEngine?.setVideoFrameDelegate(self)
rtcEngine?.setParameters("{\"rtc.audio.force_bluetooth_a2dp\": true}")
// 设置频道为直播模式
rtcEngine?.setChannelProfile(.liveBroadcasting)
// 设置角色为主播
rtcEngine?.setClientRole(.broadcaster)
// 设置视频编码属性
let vec = AgoraVideoEncoderConfiguration(size: resolution!, frameRate: .fps30, bitrate: AgoraVideoBitrateStandard, orientationMode: .adaptative, mirrorMode: .enabled)
rtcEngine?.setVideoEncoderConfiguration(vec)
}
func createMetaService(userName: String, avatarUrl: String, delegate: AgoraMetaEventDelegate?) {
playerName = userName
currentUserInfo = AgoraMetaUserInfo.init()
currentUserInfo?.userId = KeyCenter.RTM_UID
currentUserInfo?.userName = userName
currentUserInfo?.userIconUrl = avatarUrl
// 设置 AgoraMetaServiceKit 配置信息
let metaServiceConfig = AgoraMetaServiceConfig()
// 声网项目的 App ID,从控制台获取
metaServiceConfig.appId = KeyCenter.APP_ID
// 声网 RTM(云信令)Token,保障安全
// 声网项目有 RTC Token 和 RTM Token,不要搞混淆
metaServiceConfig.rtmToken = KeyCenter.RTM_TOKEN ?? ""
// 声网 RTM(云信令)UID,用户 ID,标志用户身份
// 声网项目有 RTC UID 和 RTM UID,不要搞混淆
metaServiceConfig.userId = KeyCenter.RTM_UID
metaServiceConfig.delegate = delegate
let paths = NSSearchPathForDirectoriesInDomains(.cachesDirectory, .userDomainMask, true)
// 设置场景资源的下载路径
metaServiceConfig.localDownloadPath = paths.first!
// RtcEngine 实例
metaServiceConfig.rtcEngine = rtcEngine
// 创建和初始化 AgoraMetaServiceKit
metaService = AgoraMetaServiceKit.sharedMetaServiceWithConfig(_: metaServiceConfig)
}2. 获取并下载场景资源
调用 AgoraMetaServiceKit 类的 getSceneAssetsInfo 获取场景资源,并通过 AgoraMetaEventDelegate 类的 onGetSceneAssetsInfoResult 回调监听获取场景资源时的事件。
调用 AgoraMetaServiceKit 类的 downloadSceneAssets 获取场景资源,并通过 AgoraMetaEventDelegate 类的 onDownloadSceneAssetsProgress 回调监听获取场景资源时的事件。
// 判断是否下载场景资源
metaService?.isSceneAssetsDownloaded(_ sceneId: Int)
// 获取场景资源
metaService?.getSceneAssetsInfo()
// 监听获取场景资源的回调事件
func onGetSceneAssetsInfoResult(_ scenes: NSMutableArray, errorCode: Int)
// 下载场景资源
metaService?.downloadSceneAssets(_ sceneId: Int)
// 监听下载场景资源的回调事件
func onDownloadSceneAssetsProgress(_ sceneId: Int, progress: Int, state: AgoraMetaDownloadStateType)3. 创建元直播场景
调用 AgoraMetaServiceKit 类的 createScene 创建 AgoraMetaScene,并在 AgoraMetaSceneConfig 中设置场景配置信息。你需要在 AgoraMetaSceneConfig 中设置 enableFaceCapture 为 true,并在 faceCaptureAppId 和 faceCaptureCertificate 中传入面部捕捉插件的 ID 和 Key。
通过 AgoraMetaEventDelegate 类的 onCreateSceneResult 和 onConnectionStateChanged 回调监听创建场景和连接状态的事件。
func createScene(_ delegate: MetaChatSceneViewController) {
// 配置场景信息
let config = AgoraMetaSceneConfig()
config.delegate = delegate
// 设置是否开启面部捕捉
// 元直播场景建议开启面部捕捉
config.enableFaceCapture = true
// 传入面部捕捉插件的 App ID 和 Certificate
config.faceCaptureCertificate = KeyCenter.FACE_CAPTURE_CERTIFICATE
config.faceCaptureAppId = KeyCenter.FACE_CAPTURE_APP_ID
// 创建场景
metaService?.createScene(config)
}
// 监听创建场景的回调事件
func onCreateSceneResult(_ scene: AgoraMetaScene?, errorCode: Int) {
if errorCode != 0 {
print("create scene error: \(errorCode)")
return
}
metaScene = scene
DispatchQueue.main.async {
// 创建场景渲染所需的视图
guard let view = scene?.createRenderView(CGRect(x: 0, y: 0, width: width, height: height)) else { return }
// 开启视频模块
rtcEngine?.enableVideo()
}
}
// 监听连接状态
func onConnectionStateChanged(_ state: AgoraMetaConnectionStateType, reason: AgoraMetaConnectionChangedReasonType) {
if state == .disconnected {
// 一些处理操作,详见源代码
// ...
} else if state == .aborted {
// 一些处理操作,详见源代码
// ...
}
}4. 设置用户信息并进入场景
要完成进入场景的操作,参考如下步骤:
- 调用
AgoraMetaLocalUserAvatar类的setUserInfo和setModelInfo设置用户的基本信息和虚拟形象(Avatar)的模型信息。 - 调用
AgoraMetaLocalUserAvatar类的ILocalUserAvatar类的setExtraInfo设置用户的捏脸、换装信息。 - 调用
AgoraMetaScene类的enterScene进入场景,并通过config设置配置信息。 - 通过
AgoraMetaSceneEventDelegate类的onEnterSceneResult回调监听进入场景的结果。
func enterScene(view: UIView) {
guard let sceneInfo = currentSceneInfo else {
return
}
// 用户的虚拟形象模型信息
let avatarInfo = AgoraMetaAvatarModelInfo.init()
for info in sceneInfo.bundles {
if info.bundleType == .avatar {
avatarInfo.bundleCode = info.bundleCode;
break
}
}
avatarInfo.localVisible = true
avatarInfo.remoteVisible = true
avatarInfo.syncPosition = true
// 设置进入场景时的配置信息
let enterSceneConfig = AgoraMetaEnterSceneConfig()
enterSceneConfig.roomName = KeyCenter.CHANNEL_ID
// 场景资源渲染时所需要的视图,从 createRenderView 创建获得
enterSceneConfig.sceneView = view
// 内容中心对应的 ID
enterSceneConfig.sceneId = sceneInfo.sceneId
// 设置加载场景资源时需要的额外自定义信息,只支持字符串
// 在这里指设置 sceneIndex,取值 0 代表元直播场景,取值 1 代表元语聊场景
// 在业务逻辑中包含多个场景的情况下,你可以用 sceneIndex 来区分不同的场景,Unity 场景脚本可以根据 sceneIndex 来确定进入哪个场景,并执行相应的逻辑
let dict = ["sceneIndex": kSceneIndex.rawValue]
let data = try? JSONSerialization.data(withJSONObject: dict, options: [])
let extraInfo = String(data: data!, encoding: String.Encoding.utf8)
enterSceneConfig.extraInfo = extraInfo!.data(using: String.Encoding.utf8)
// 获得 localUserAvatar 对象
localUserAvatar = metaScene?.getLocalUserAvatar()
// 设置用户的基本信息
localUserAvatar?.setUserInfo(currentUserInfo)
// 设置用户的虚拟形象模型信息
localUserAvatar?.setModelInfo(avatarInfo)
// 设置用户的捏脸、换装信息
let dict = ["avatar": "girl", "dress": [10000, 10100], "face": [["key": "eyeBlink_L", "val": 30] as [String : Any]], "2dbg": ""] as [String : Any]
let data = try? JSONSerialization.data(withJSONObject: dict, options: [])
let extraInfo = String(data: data!, encoding: String.Encoding.utf8)
localUserAvatar?.setExtraInfo(extraInfo!.data(using: String.Encoding.utf8))
// 进入场景
metaScene?.enter(enterSceneConfig)
}
// 监听进入场景的回调事件
func metaScene(_ scene: AgoraMetaScene, onEnterSceneResult errorCode: Int) {}5. 加入频道并开启元直播
进入场景后,你需要将主播端 Avatar 形象的视频流发布到 RTC 频道中,使 3D 场景中的用户都能看到直播。参考如下步骤:
- 调用
AgoraRtcEngineKit类的joinChannelByToken使主播加入 RTC 频道。 - 调用
AgoraMetaScene类的enableSceneVideoCapture并将enable设置为true开启场景渲染画面捕获,发布主播的 Avatar 形象到 RTC 频道。
注意
发送 Avatar 视频前,请确保 AgoraMetaSceneConfig 中已设置开启面部捕捉。
// 加入频道
func joinRtcChannel(success: @escaping () -> Void) {
// 传入声网 RTC Token、频道名和 UID
rtcEngine?.joinChannel(byToken: KeyCenter.RTC_TOKEN, channelId: KeyCenter.CHANNEL_ID, info: nil, uid: KeyCenter.RTC_UID, joinSuccess: { String, UInt, Int in
DLog("joinChannel 回调 ======= ",String,UInt,Int)
success()
})
}
// 开启场景渲染画面捕获
// 默认为 false,即发送摄像头采集的视频画面,建议设置为 true,把场景画面和主播的 Avatar 形象发布到频道
// Swift 中的 enableVideoCapture 对应 Objective-C API 中的 enableSceneVideoCapture
scene?.enableVideoCapture(view!, enable: true)6. 离开频道并释放资源
离开场景时,参考如下步骤:
- 调用
AgoraRtcEngineKit类的leaveChannel离开直播频道。 - 调用
AgoraMetaScene类的leaveScene离开场景。 - 通过
AgoraMetaSceneEventDelegate类的onLeaveSceneResult回调得知成功离开场景后,调用destroy释放AgoraMetaScene。 - 通过
AgoraMetaSceneEventDelegate类的onReleasedScene回调监听AgoraMetaScene是否释放成功。 - 依次调用
AgoraMetaServiceKit和AgoraRtcEngineKit类的destroy方法销毁AgoraMetaServiceKit和AgoraRtcEngineKit。
private func leaveScene() {
// 退出频道
rtcEngine?.leaveChannel()
// 离开场景
metaScene?.leave()
}
// 监听离开场景的回调事件
func metaScene(_ scene: AgoraMetaScene, onLeaveSceneResult errorCode: Int) {
// 销毁场景
metaScene?.destroy()
metaScene = nil
}
// 监听释放 AgoraMetaScene 的回调事件
func metaScene(_ scene: AgoraMetaScene, onReleasedScene errorCode: Int) {
// 销毁 AgoraMetaServiceKit
AgoraMetaServiceKit.destroy()
metaService = nil
// 销毁 AgoraRtcEngineKit
AgoraRtcEngineKit.destroy()
rtcEngine = nil
}开发注意事项
使用 3D 场景的过程中,不能销毁调用 createRenderView 创建的视图。该视图只有退出整个 App 时才能销毁。