文档中心
视频通话 (Legacy)
Console 官网 社区 技术支持
简体中文
search-icon

实现视频通话

更新时间 2023/02/06 10:21:48

本文介绍如何使用声网 Unity SDK 快速实现视频通话。

前提条件

  • Unity 2017 或以上版本

  • 操作系统与编译器要求：

    开发平台 操作系统版本 编译器版本
    Android Android 4.1 或以上 Android Studio 3.0 或以上
    iOS iOS 9.0 或以上 Xcode 9.0 或以上
    macOS macOS 10.10 或以上 Xcode 9.0 或以上
    Windows Windows 7 或以上 Microsoft Visual Studio 2017 或以上

  • 有效的声网账户 和 App ID

如果你的网络环境部署了防火墙，请根据应用企业防火墙限制打开相关端口。

准备开发环境

本节介绍如何创建项目，将声网 Unity SDK 集成进你的项目中。

创建 Unity 项目

参考以下步骤或 Unity 官方操作指南创建一个 Unity 项目。若已有 Unity 项目，可以直接查看集成 SDK。

创建 Unity 项目

  1. 开始前确保你已安装 Unity。若未安装，点击此处下载。

  2. 打开 Unity，点击 New。

  3. 依次填入以下内容后，点击 Create project。

    • Project name：项目名称
    • Location：项目存储路径
    • Organization：组织名称
    • Template：项目类型。选择 3D。

集成 SDK

选择如下任意一种方式将声网 Unity SDK 集成到你的项目中。

方法一：使用 Unity Asset Store 自动集成

  1. 在 Unity 中点击 Asset Store 栏，输入 Agora 搜索并选择 Agora Video SDK for Unity。
  2. 在 SDK 详情页中，点击页面右侧的 Download 按钮下载 SDK。
  3. 下载成功后，会出现 Import 按钮，点击查看可导入的内容。
  4. 取消勾选不需要的插件（默认勾选 SDK 包含的所有插件）。然后点击 Import。

方法二：手动复制 SDK 文件

  1. 前往 SDK 下载页面，在视频通话/视频互动直播 SDK 中下载最新版的 声网 Unity SDK，然后解压。

  2. 将 SDK 包内 samples/Hello-Video-Unity-Agora/Assets/AgoraEngine 路径下的 Plugins 文件夹拷贝到项目的 Assets 文件夹下。

    • 对于开发 Android 或 iOS 应用的用户，如需在 macOS 或 Windows 设备中使用 Unity Editor 调试，请确保拷贝 macOS 或 X86/X86_64 文件夹。
    • iOS 平台集成时，还需要拷贝 samples/Hello-Video-Unity-Agora/Assets/AgoraEngine/Editor 路径下的 BL_BuildPostProcess.cs 脚本。

实现视频通话

本节介绍如何实现视频通话。视频通话的 API 调用时序见下图：

1. 创建用户界面

根据场景需要，为你的项目创建视频通话的用户界面。若已有界面，可以直接查看获取设备权限（仅 Android 平台）或初始化 IRtcEngine。

在视频通话中，声网推荐你添加如下 UI 元素：

  • 本地视频窗口
  • 远端视频窗口
  • 结束通话按钮

当你使用 Unity Editor 创建 UI 时，请确保你将 VideoSurface.cs 与显示本地或远端视频的物体绑定。当你将 VideoSurface.cs 与立方体绑定用于显示本地视频，且将 VideoSurface.cs 与圆柱体绑定用于显示远端视频时，你会看到如下界面：

2. 获取设备权限（仅 Android 平台）

仅 Android 平台需要设置此步骤，其他平台可以直接查看初始化 IRtcEngine。

在 UNITY_2018_3_OR_NEWER 或以上版本中，Unity 不会主动向用户获取麦克风和相机权限，需要用户调用 CheckPermission 方法获取权限。 

#if(UNITY_2018_3_OR_NEWER) 
using UnityEngine.Android; 
#endif 
void Start () 
{  
#if(UNITY_2018_3_OR_NEWER) 
permissionList.Add(Permission.Microphone);  
permissionList.Add(Permission.Camera);  
#endif  
} 
private void CheckPermission()
{ 
#if(UNITY_2018_3_OR_NEWER) 
foreach(string permission in permissionList) 
{ 
if (Permission.HasUserAuthorizedPermission(permission)) 
{ 
} 
else 
{  
Permission.RequestUserPermission(permission); 
} 
} 
#endif 
} 
void Update () 
{  
#if(UNITY_2018_3_OR_NEWER) 
// 获取设备权限。 
CheckPermission(); 
#endif  
}

3. 初始化 IRtcEngine

在调用其他声网 API 前，需要初始化 IRtcEngine 对象。

调用 GetEngine 方法，传入获取到的 App ID，即可初始化 IRtcEngine。

如果你想退出应用或者释放 IRtcEngine 内存，需调用 Destroy 方法销毁 IRtcEngine。详见销毁 IRtcEngine。

你还可以根据场景需要，在初始化时注册想要监听的回调事件，如本地用户加入频道，及解码远端用户视频首帧等。

// 填入 App ID 并初始化 IRtcEngine。 
mRtcEngine = IRtcEngine.GetEngine (appId); 
// 注册 OnJoinChannelSuccessHandler 回调。 
// 本地用户成功加入频道时，会触发该回调。
mRtcEngine.OnJoinChannelSuccessHandler = OnJoinChannelSuccessHandler; 
// 注册 OnUserJoinedHandler 回调。
// SDK 接收到第一帧远端视频并成功解码时，会触发该回调。
// 可以在该回调中调用 SetForUser 方法设置远端视图。
mRtcEngine.OnUserJoinedHandler = OnUserJoinedHandler; 
// 注册 OnUserOfflineHandler 回调。 
// 远端用户离开频道或掉线时，会触发该回调。
mRtcEngine.OnUserOfflineHandler = OnUserOfflineHandler;

4. 设置本地视频显示

成功初始化 IRtcEngine 对象后，需要在加入频道前设置本地视频显示，以便在通话中看到本地图像。参考以下步骤设置本地视频显示：

  • 调用 EnableVideo 方法启用视频模块。

  • 调用 EnableVideoObserver 方法启用本地视频显示。

      // 启用视频模块。 
  mRtcEngine.EnableVideo();
  // 获取本地视频显示，并传递到 Unity 层。
  mRtcEngine.EnableVideoObserver();`

  • 选择显示本地视频的物体，将视频渲染脚本 VideoSurface.cs 拖动至该物体的 Script 进行绑定，即可看到本地图像。Unity 中默认渲染器可以渲染 3D 物体，例如：Cube，Cylinder，Plane等。若需渲染其他类型的物体，需修改 VideoSurface.cs 文件中的渲染器。

      // 默认渲染器为 Renderer。 
  Renderer rend = GetComponent(); 
  rend.material.mainTexture = nativeTexture; 
  // 将渲染器修改为 RawImage。 
  RawImage rend = GetComponent(); 
  rend.texture = nativeTexture;`

5. 加入频道

完成初始化和启用视频帧传输后，你就可以调用 JoinChannelByKey 方法加入频道。你需要在该方法中传入如下参数：

  • channelKey：传入能标识用户角色和权限的 Token。可设为如下一个值：

    • 临时 Token。在安全要求一般的测试场景下，可使用临时 Token。你可以在控制台里生成一个临时 Token（服务有效期为 24 小时），详见获取临时 Token。
    • 在你的服务器端生成的 Token。在安全要求高的场景下，声网推荐你使用此种方式生成的 Token，详见生成 Token。
    • 若项目已启用 App 证书，请使用 Token。
    • 请勿将 channelKey 设为 ""。

  • channelName: 传入能标识频道的频道 ID。输入频道 ID 相同的用户会进入同一个频道。

  • uid: 本地用户的 ID。数据类型为整型，且频道内每个用户的 uid 必须是唯一的。若将 uid 设为 0，则 SDK 会自动分配一个 uid，并在 OnJoinChannelSuccessHandler 回调中报告。

    用户成功加入频道后，会默认订阅频道内其他所有用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 Mute 方法实现。
// 加入频道。 
mRtcEngine.JoinChannelByKey(null, channel, null, 0);

6. 设置远端视频显示

视频通话中，通常你也需要看到其他用户。在加入频道后，可通过调用 VideoSurface.cs 文件中的 SetForUser 方法设置远端视频显示。远端用户成功加入频道后，SDK 会触发 OnUserJoinedHandler 回调，该回调中会包含这个远端用户的 uid 信息。

  • 在** VideoSurface.cs** 文件，通过 OnUserJoinedHandler 回调来调用 SetForUser 方法，传入获取到的 uid，设置远端视频显示。

  • 选择显示远端视频的物体，将视频渲染脚本 VideoSurface.cs 拖动至该物体的 Script 进行绑定，即可看到远端图像。

  • 声网 Unity SDK 默认的视频采集和渲染帧率是 15 fps，根据场景，调用 VideoSurface.cs 文件中的 SetGameFps 方法调节视频刷新帧率。

    默认 VideoSurface.cs 文件中 SetForUser 方法的 uid 是 0，表示渲染本地视频。
// SDK 接收到第一帧远端视频并成功解码时，会触发 OnUserJoinedHandler 回调。
// 在该回调中调用 SetForUser 方法设置远端视频显示。
private void OnUserJoinedHandler(uint uid, int elapsed)
    {
        Debug.Log ("OnUserJoinedHandler: uid = " + uid)
        GameObject go = GameObject.Find (uid.ToString ());
        if (!ReferenceEquals (go, null)) {
            return; 
        }
        go = GameObject.CreatePrimitive (PrimitiveType.Plane);
        if (!ReferenceEquals (go, null)) {
            go.name = uid.ToString ();
            VideoSurface remoteVideoSurface = go.AddComponent<VideoSurface> ();
          // 设置远端视频显示。
          remoteVideoSurface.SetForUser (uid);
          // 调节视频刷新帧率。声网 Unity SDK 默认的视频采集和渲染帧率是 15 fps。
          // 例如，游戏场景中，游戏刷新帧率为 60 fps。我们此时视频渲染帧率相对于视频刷新帧率会产生 3 倍的冗余，需通过 SetGameFps 方法，将游戏刷新帧率调节为 15 fps。
          remoteVideoSurface.SetGameFps (60);
          remoteVideoSurface.SetEnable (true);
        }
        mRemotePeer = uid;
    }

若需移除 VideoSurface.cs 文件，参考以下示例代码：

private void OnUserOfflineHandler(uint uid, USER_OFFLINE_REASON reason)
    {
        // 移除视频流。
        // 请在主线程中调用此方法。
        GameObject go = GameObject.Find (uid.ToString());
        if (!ReferenceEquals (go, null)) {
            Destroy (go);
        }
    }

7. 离开频道

根据场景需要，如结束通话或关闭 App 时，调用 LeaveChannel 离开当前通话频道，并调用 DisableVideoObserver 关闭视频显示。

public void leave()
    {
        Debug.Log ("calling leave");
        if (mRtcEngine == null)
            return;
        // 离开频道。
        mRtcEngine.LeaveChannel();
        // 关闭视频显示。
        mRtcEngine.DisableVideoObserver();
    }

8. 销毁 IRtcEngine

离开频道后，如果你想退出应用或者释放 IRtcEngine 内存，需调用 Destroy 方法销毁 IRtcEngine。

void OnApplicationQuit()
{
    if (mRtcEngine != null)
    {
    // 销毁 IRtcEngine。
    IRtcEngine.Destroy();
    mRtcEngine = null;
    }
}

示例代码

声网在 GitHub 上提供了开源示例项目，你可以查看完整的源码和代码逻辑。

运行项目

你可以在 Unity 中运行此项目。当你成功开始视频通话时，你可以同时看到本地和远端的视频。

相关链接

使用声网 Unity SDK 开发过程中，你还可以参考如下文档：