快速构建元宇宙专属虚拟形象,实时互动超酷炫

100 阅读7分钟

概述

即构虚拟形象引擎(Zego Avatar)支持自定义管理人物的虚拟形象,通过默认的虚拟形象或者自定义生成的专有虚拟形象,以表情随动、声音驱动等方式与真人实时互动,可广泛应用于语聊直播、社交互动、在线培训等多种场景中。

集成 SDK

准备环境

在开始集成 ZegoAvatar SDK 前,请确保开发环境满足以下要求:

  • Android Studio 2.1 或以上版本。
  • Android SDK 25、Android SDK Build-Tools 25.0.2、Android SDK Platform-Tools 25.x.x 或以上版本。
  • Android 5.1 或以上版本,且支持音视频的 Android 真机设备。
  • 设备的前置摄像头和麦克风功能正常。

集成 SDK

1(可选)新建项目

此步骤以如何创建新项目为例,如果是集成到已有项目,可忽略此步。

2 导入 SDK

目前支持的平台架构包括:armeabi-v7a、arm64-v8a。

  1. 请前往下载页面,获取最新版本的 SDK。

  2. 解压 SDK 压缩包,将 ZegoAvatar 的制品包中的ZegoAvatar.aar拷贝至自己的项目目录下,如 “app/libs”。

3.添加 SDK 引用。进入到 “app” 目录,打开 “build.gradle” 文件,在 “dependencies” 节点引入 “libs” 下所有的 jar。

​​​​​​

implementation fileTree(dir: 'libs', include: ['*.jar', "*.aar"]) //通配引入


3 设置权限

根据实际应用需要,设置应用所需权限。

进入 “app/src/main” 目录,打开 “AndroidManifest.xml” 文件,添加权限。

<!-- SDK 必须使用的权限 -->

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />

<!-- App 需要使用的部分权限 -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />
<uses-permission android:name="android.permission.WAKE_LOCK" />

<uses-feature
    android:glEsVersion="0x00020000"
    android:required="true" />

<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />





因为 Android 6.0 在一些比较重要的权限上要求必须申请动态权限,不能只通过 “AndroidMainfest.xml” 文件申请静态权限。因此还需要参考执行如下代码,其中 “requestPermissions” 是 “Activity” 的方法。

String[] permissionNeeded = {
    "android.permission.CAMERA"};

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
    if (ContextCompat.checkSelfPermission(this, "android.permission.CAMERA") != PackageManager.PERMISSION_GRANTED) {
        requestPermissions(permissionNeeded, 101);
    }
}





必要性权限权限说明申请原因
必要权限CAMERA访问相机权限。通过摄像头画面推理面部表情时,需要使用该权限。
RECORD_AUDIO录制音频权限。通过声音波动推理面部表情时,需要使用该权限。 
WRITE_EXTERNAL_STORAGE内置 SDK 写权限。SDK 会将日志和相关配置文件保存在内置 SDK 内。需要保存截图或录制的视频时,也需要使用该权限。 
非必要权限INTERNET访问网络权限。SDK 鉴权获取时,需要使用该权限。
READ_EXTERNAL_STORAGE文件读取权限。SDK 需要读取资源包时,需要使用该权限。 

4 防止混淆代码

在 “proguard-rules.pro” 文件中,为 SDK 添加-keep类的配置,防止混淆 SDK 公共类名称。

-keep class **.zego.**{*;}





导入资源

使用 Avatar 提供的各项 AI 能力之前,需要导入相应的资源包,请前往下载页面,获取下列资源包。

开发者可以通过动态下载从本地添加两种方式,导入资源包。

(推荐)动态下载

资源名称 说明 资源大小 是否支持
动态下载
建议下载时机
AIModel.bundle Avatar 的 AI 模型资源。当使用表情随动、声音随动、AI 捏脸等能力时,必须先将该资源的绝对路径设置给 Avatar SDK。
  • 表情随动:8.2 MB
  • 声音随动:2.4 MB
  • AI 捏脸:12.4 MB
必须在 ZegoAvatarService 初始化前完成下载。
base.bundle 美术资源,包含基础 3D 人物模型资源、资源映射表、人物模型默认外形等。
  • Android: 13 MB
  • iOS: 14.4 MB
必须在创建 ZegoCharacterHelper 前完成下载。
Packages 美妆、挂件、装饰等资源。 每个资源 200 KB ~ 1 MB 不等,跟资源复杂度相关。 建议在需要使用相关资源时再去下载,不使用时可不下载,减少对本地存储空间的占用。

Packages 中包含了部分美术资源,开发者如有需要,请联系 ZEGO 商务人员,获取所有的美术资源。

从本地添加

  1. 请前往下载页面,获取相关的资源包。

  2. 解压获取到的资源包,找到 “assets” 文件夹,拷贝到自己创建项目的 “assets” 文件夹下。

  3. 运行项目时,将 “AIModel.bundle”、“base.bundle” 、"Packages" 文件,通过以下代码,拷贝到设备的私有目录(/data/data/包名/files)下。(注意:Android 系统的 assets 文件夹只能读取。)

    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "AIModel.bundle"/*apk 里的assets 根目录*/, "assets"/* sd 卡里的目录, 值为:getFilesDir().getAbsolutePath() + File.separator + destPath */);
    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "base.bundle", "assets");
    AssetsFileTransfer.copyAssetsDir2Phone(this.getApplication(),
                "Packages", "assets");
    
    
    
    
    
    
    /**
     * 把assets/${filePath}目录中的所有内容拷贝到 手机的Storage的${destPath}/目录中
     *
     * @param activity activity 使用CopyFiles类的Activity
     * @param filePath String 相对于Android APK内的assets目录的文件路径,如:AIModel.bundle
     * @param destPath String 拷贝的目标, 如:/data/data/包名/files/assets/
     */
    public static void copyAssetsDir2Phone(Context activity, String filePath, String destPath) {
        try {
            String[] fileList = activity.getAssets().list(filePath);
            if (fileList.length > 0) {//如果是目录
                File file = new File(activity.getFilesDir().getAbsolutePath() + File.separator + destPath + File.separator + filePath);
                if (file.exists()) {
                    deleteAllFiles(file);
                }
                file.mkdirs();//如果文件夹不存在,则递归
                for (String fileName : fileList) {
                    filePath = filePath + File.separator + fileName;
    
                    copyAssetsDir2Phone(activity, filePath, destPath);
    
                    filePath = filePath.substring(0, filePath.lastIndexOf(File.separator));
                    Log.i(TAG, filePath);
                }
            } else {//如果是文件
                InputStream inputStream = activity.getAssets().open(filePath);
                File file = new File(activity.getFilesDir().getAbsolutePath() + File.separator + destPath + File.separator + filePath);
                if (file.exists()) {
                    boolean delete = file.delete();
                }
                if (!file.exists() || file.length() == 0) {
                    FileOutputStream fos = new FileOutputStream(file);
                    int len = -1;
                    byte[] buffer = new byte[1024];
                    while ((len = inputStream.read(buffer)) != -1) {
                        fos.write(buffer, 0, len);
                    }
                    fos.flush();
                    inputStream.close();
                    fos.close();
                }
            }
        } catch (IOException e) {
            Log.e(TAG, "copy file faild, src:" + filePath + " dest:" + destPath);
            e.printStackTrace();
        }
    }
    
    
    
    
    
    
  4. 拷贝资源后,在移动设备上运行时,会存在如下的结构。注意:不同的移动设备,getFilesDir().getAbsolutePath()返回的目录可能不一样。这里以华为手机为例,其返回的是:/data/data/im.zego.zegoavatarexample

5.使用某一功能时,在对应接口中,传入接口要求的资源的绝对路径即可。

使用步骤

本节介绍如何使用 ZegoAvatar SDK 实现基本的图像处理功能,API 调用时序如下图:

1 申请鉴权

ZEGO Avatar 目前使用在线鉴权的方式获取 License 授权文件。

1.1 开通 ZegoAvatar 权限

  1. 请先在ZEGO 控制台创建项目,并申请有效的 AppID,详情请参考控制台 - 项目管理中的“项目信息”。

  2. 请联系 ZEGO 商务人员,提供申请到的 AppID,以及自己项目的 Bundle Id,获取鉴权需要使用的 AppSign,并开通相关权限。

1.2 获取参考代码

请将从下载获取到的示例源码中的 LicenseHelper 文件夹中的代码,拷贝到自己的项目下。

  1. 修改ZegoAvatarConfig.h文件,请使用已获取的 AppID 和 AppSign 正确填写,否则示例源码无法正常运行。

    // 鉴权服务器的地址
    static NSString *AVATAR_BASE_URL = @"https://aieffects-api.zego.im?Action=DescribeAvatarLicense";
    
    // 向 ZEGO 申请的 AppID, APPID 跟 Bundle Id 有绑定关系,“Bundle Identifier” 设置为申请 AppID 时所提供的 Bundle Id
    static NSUInteger AVATAR_APPID = YOUR_APP_ID;
    
    // 向 ZEGO 申请的得到的 AppSign
    static NSString *AVATAR_APP_SIGN = YOUR_APP_SIGN;
    
    
    
    
    
    
  2. 在项目中,选择 “TARGETS > Signing & Capabilities” 菜单,将 “Bundle Identifier” 设置为申请 AppID 时所提供的 Bundle Id。

​​​​​​​​​​​​​​

1.3 安装依赖库

  1. 打开终端,进入项目根目录,执行pod 'YTKNetwork',引入依赖库。

  2. 执行pod install命令安装依赖库。

1.4 获取 License

通过 ZGAvatarLicenseHelper 中的requestLicense接口,发起网络请求,获取鉴权 License 字符串。

// 发起网络请求获取 License
[ZGAvatarLicenseHelper requestLicense:^(NSString * _Nonnull license) {
    if (license.length > 0) {

        // 初始化 avatar Service
        [self initAvatarService: license];
    }
}];





2 初始化 AvatarService

  1. 初始化 AvatarService 之前,请先导入以下相关的头文件,准备基础工作。

    // 引入 头文件
    #import <ZegoAvatar/ZegoAvatarService.h>
    
    
    
    
    
    
  2. 导入头文件后,调用initWithConfig 接口,传入之前获取到的鉴权 License 字符串,初始化 AvatarService。

    // 初始化 AvatarService
    - (void) initAvatarService: (NSString*) license{
        // 创建 config
        ZegoServiceConfig *config = [[ZegoServiceConfig alloc] init];
        // 将获取到的 License 文件传入
        config.license = license;
        // 指定 AI 模型的路径
        config.AIPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/AIModel.bundle"];
        // 监听初始化状态,addServiceObserver 需要在 "主线程" 执行!!!
        [[ZegoAvatarService sharedInstance] addServiceObserver:self];
    
        // 初始化 AvatarService
        [[ZegoAvatarService sharedInstance] initWithConfig:config];
    }
    
    
    
    
    
    
  3. 注册onStateChange回调,接收初始化状态的相关回调通知。

    // avatarService初始化状态回调
    - (void)onStateChange:(ZegoAvatarServiceState)state {
        // SDK初始化成功
        if (state == ZegoAvatarServiceState_InitSucceed) {
            // 初始化虚拟形象
            [self initAvatar];
        }
    }
    
    
    
    
    
    

3 创建虚拟形象

在创建虚拟人物形象时,为了简化 Character(虚拟人物形象)的初始化、序列化、数据缓存、路径拼接等功能的接入流程,ZEGO Avatar SDK 提供了ZegoCharacterHelper 类(开源),帮助开发者快速创建人物虚拟形象,详情请参考ZegoCharacterHelper 使用说明

初始化 AvatarService 后,通过创建ZegoCharacterHelper对象,传入虚拟人物形象的外观数据(捏脸、换装、妆容等),设置视图参数(宽、高、位置等),创建一个虚拟形象。

- (void) initAvatar{
    // 创建 Helper,传入基础资源的路径
    NSString *resourcePath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/base.bundle"];
    _characterHelper = [[ZegoCharacterHelper alloc] init:resourcePath];
    
    // 设置素材资源包地址,如果是动态下载,则传入下载的目标目录
    NSString *packagesPath = [[[NSBundle mainBundle] bundlePath] stringByAppendingString:@"/assets/Packages"];
    [_characterHelper setExtendPackagesPath:packagesPath];
    
    // 使用默认形象,以男性角色为例
    [_characterHelper setDefaultAvatar:MODEL_ID_MALE];

    // 创建 AvatarView
    _avatarView = [[ZegoAvatarService sharedInstance] createAvatarView:CGRectMake(0, 0, 200, 200)];
    [self.view addSubview:_avatarView];

    //角色上屏
    [_characterHelper setCharacterView:_avatarView];
}




获取优惠活动

  • 近期有开发规划的开发者可上即构官网查看,恰逢即构七周年全线音视频产品1折的优惠,适合有预算要求的中小型企业和个人开发工作室。
  • 七周年福利:提交表单“Avatar",获得"ZEGO Avatar1个月免费试用"。;
  • 获取更多商务活动热门产品,也可提交信息联系商务;