虚拟形象 SDK
有奖捉虫：办公协同&微信生态&物联网文档专题 HOT
文档中心 > 虚拟形象 SDK > SDK 集成指引 > 快速开始 > Android

Android

最近更新时间：2023-05-19 11:06:22

我的收藏

本页目录：

集成方式

手动集成（资源内置）
手动集成（资源动态下载）
Maven 集成

下载SDK

下载 SDK，并解压。不同套餐包内的资源文件略有差异，详细说明见 附件。
建议您将包内的 demo 工程导入 AndroidStudio 跑起来，以便快速熟悉接口使用方法。请参考快速跑通 Demo。

集成

添加下载的 xmagic-xxxx.aar 文件到 app 工程 libs 目录下。
将 SDK 包内的 assets/ 目录下的全部资源拷贝到 ../src/main/assets 目录下，如果 SDK 包中的 MotionRes 文件夹内有资源，将此文件夹也拷贝到 ../src/main/assets 目录下 。
将 jniLibs 文件夹拷贝到工程的 ../src/main/jniLibs 目录下。

导入方法

打开 app 模块的 build.gradle 添加依赖引用：
android{
    ...
    defaultConfig {
        applicationId "修改成与授权lic绑定的包名"
        ....
    }
    packagingOptions {
        pickFirst '**/libc++_shared.so'
    }
}

dependencies{
    ...
    compile fileTree(dir: 'libs', include: ['*.jar','*.aar'])//添加 *.aar
}
注意
如果项目中没有集成 Google 的 Gson 库则还需添加如下依赖：
dependencies{
    implementation 'com.google.code.gson:gson:2.8.2'
    //2.6.0 版本及之后需要添加
    implementation 'androidx.exifinterface:exifinterface:1.3.3'
}


动态下载 assets、so、动效资源指引

为了减少包大小，您可以将 SDK 所需的 assets 资源、so 库、以及动效资源 MotionRes（部分基础版 SDK 无动效资源）改为联网下载。在下载成功后，将上述文件的路径设置给 SDK。
我们建议您复用 Demo 的下载逻辑，当然，也可以使用您已有的下载服务。动态下载的详细指引，请参见 SDK 包体瘦身（Android）。
腾讯特效 SDK 已经发布到 mavenCentral 库，您可以通过配置 gradle 自动下载更新。
1. 在 dependencies 中添加腾讯特效 SDK 的依赖。
dependencies {
 //例如：S1-04套餐如下
 implementation 'com.tencent.mediacloud:TencentEffect_S1-04:latest.release'
}
2. 在 defaultConfig 中，指定 App 使用的 CPU 架构。
defaultConfig {
 ndk {
     abiFilters "armeabi-v7a", "arm64-v8a"
 }
}
说明
目前 特效 SDK 支持 armeabi-v7a 和 arm64-v8a。
3. 单击
img

Sync Now，自动下载 SDK 并集成到工程里。
4. 如果您的套餐包含动效和滤镜功能，那么需要在 SDK 下载 下载对应的套餐包，将包内免费的动效和滤镜素材放置在您工程下的如下目录：
动效：../assets/MotionRes
滤镜：../assets/lut

各套餐对应的 Maven 地址

版本
Maven 地址
A1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_A1-01:latest.release'
A1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_A1-02:latest.release'
A1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_A1-03:latest.release'
A1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_A1-04:latest.release'
A1 - 05
implementation 'com.tencent.mediacloud:TencentEffect_A1-05:latest.release'
A1 - 06
implementation 'com.tencent.mediacloud:TencentEffect_A1-06:latest.release'
S1 - 00
implementation 'com.tencent.mediacloud:TencentEffect_S1-00:latest.release'
S1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_S1-01:latest.release'
S1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_S1-02:latest.release'
S1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_S1-03:latest.release'
S1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_S1-04:latest.release'


SDK使用流程

步骤一：鉴权

1. 申请授权，得到 License URL 和 License KEY，请参见 License 指引。
注意
正常情况下，只要 App 成功联网一次，就能完成鉴权流程，因此您不需要把 License 文件放到工程的 assets 目录里。但是如果您的 App 在从未联网的情况下也需要使用 SDK 相关功能，那么您可以把 License 文件下载下来放到 assets 目录，作为保底方案，此时 License 文件名必须是 v_cube.license。
2. 在相关业务模块的初始化代码中设置 URL 和 KEY，触发 License 下载，避免在使用前才临时去下载。也可以在 Application 的 onCreate 方法里触发下载，但不建议，因为此时可能没有网络权限或联网失败率较高。
//如果仅仅是为了触发下载或更新license，而不关心鉴权结果，则第4个参数传入null。
TELicenseCheck.getInstance().setTELicense(context, URL, KEY, null);
3. 然后在真正要使用美颜功能前( 例如 Demo 的 TEMenuActivity.java)，再去做鉴权：
// 如果您的so库是从网络下载的，那么请在调用TELicenseCheck.getInstance().setTELicense之前，先设置so的路径，否则鉴权会失败。
// XmagicApi.setLibPathAndLoad(validLibsDirectory);
// 如果您的so内置在apk包内，则无需调用上面的方法。
TELicenseCheck.getInstance().setTELicense(context, URL, KEY, new TELicenseCheckListener() {

         @Override
         public void onLicenseCheckFinish(int errorCode, String msg) {
             //注意：此回调不一定在调用线程
             if (errorCode == TELicenseCheck.ERROR_OK) {
                 //鉴权成功
             } else {
                 //鉴权失败
             }
         }
     });
鉴权 errorCode 说明：
错误码
说明
0
成功。Success
-1
输入参数无效，例如 URL 或 KEY 为空
-3
下载环节失败，请检查网络设置
-4
从本地读取的 TE 授权信息为空，可能是 IO 失败引起
-5
读取 VCUBE TEMP License文件内容为空，可能是 IO 失败引起
-6
v_cube.license 文件 JSON 字段不对。请联系腾讯云团队处理
-7
签名校验失败。请联系腾讯云团队处理
-8
解密失败。请联系腾讯云团队处理
-9
TELicense 字段里的 JSON 字段不对。请联系腾讯云团队处理
-10
从网络解析的 TE 授权信息为空。请联系腾讯云团队处理
-11
把TE授权信息写到本地文件时失败，可能是 IO 失败引起
-12
下载失败，解析本地 asset 也失败
-13
鉴权失败，请检查 so 是否在包里，或者已正确设置 so 路径
3004/3005
无效授权。请联系腾讯云团队处理
3015
Bundle Id / Package Name 不匹配。检查您的 App 使用的 Bundle Id / Package Name 和申请的是否一致，检查是否使用了正确的授权文件
3018
授权文件已过期，需要向腾讯云申请续期
其他
请联系腾讯云团队处理

步骤二：资源拷贝

1. 如果您的资源文件是内置在 assets 目录的，那么使用前需要 copy 到 app 的私有目录。您可以提前 copy 好，或者在上一步鉴权成功的回调里执行拷贝操作。示例代码在 Demo 的 TEMenuActivity.java。
XmagicResParser.setResPath(new File(getFilesDir(), "xmagic").getAbsolutePath());
//loading

//copy资源文件到私有目录，只需要做一次
XmagicResParser.copyRes(getApplicationContext());
2. 如果您的资源文件是从 网络动态下载 的，下载成功后，需要设置资源文件路径。示例代码在 Demo 的 TEMenuActivity.java。
XmagicResParser.setResPath(下载的资源文件本地路径);

步骤三：SDK 初始化及使用方法

使用腾讯特效 SDK 生命周期大致如下：
1. 构造美颜 UI 数据，可参考 Demo 工程（com.tencent.demo.beauty.provider包下代码）。
2. 预览布局中添加 Demo 中的 GLCameraXView。 
<com.tencent.demo.camera.camerax.GLCameraXView    
   android:id="@+id/te_camera_layout_camerax_view"  
   android:layout_width="match_parent"   
   android:layout_height="match_parent"  
   app:back_camera="false"   
   app:surface_view="false" 
   app:transparent="true" />
3. （可选）快速实现相机。 将 Demo 工程中的 com.tencent.demo.camera 目录拷贝到工程中。利用 GLCameraXView 类快速实现相机功能。详细实现可参考 Demo 工程的 TECameraActivity.java。
@Override
public int onCustomProcessTexture(int textureId, int textureWidth, int textureHeight) {  
    int resultTextureId = 0;    
    if (!isUseTencentEffect) {       
         resultTextureId = textureId;  
     } else {      
         resultTextureId = mBeautyImpl.process(textureId, textureWidth, textureHeight); 
       } 
    return resultTextureId;
  }
4. 初始化美颜 SDK，建议放在 Activity 的 onResume()方法中。
mXmagicApi = new XmagicApi(this, XmagicResParser.getResPath(),new XmagicApi.OnXmagicPropertyErrorListener());
参数
参数
含义
Context context
上下文
String resDir
资源文件目录，详见请参见 步骤二
OnXmagicPropertyErrorListener errorListener
回调函数实现类
返回 错误码含义请参见 API 文档。
5. 添加素材提示语回调函数（方法回调有可能运行在子线程），部分素材会提示用户：点点头、伸出手掌、比心，这个回调就是用于展示类似的提示语。
mXmagicApi.setTipsListener(new XmagicTipsListener() {
 final XmagicToast mToast = new XmagicToast();
 @Override
 public void tipsNeedShow(String tips, String tipsIcon, int type, int duration) {
     mToast.show(MainActivity.this, tips, duration);
 }

 @Override
 public void tipsNeedHide(String tips, String tipsIcon, int type) {
     mToast.dismiss();
 }
});
6. 美颜 SDK 处理每帧数据并返回相应处理结果。
int outTexture = mXmagicApi.process(textureId, textureWidth, textureHeight);
7. 更新指定类型的美颜特效数值。
// 可用的入参属性可以从 XmagicResParser.parseRes() 获得
mXmagicApi.updateProperty(XmagicProperty<?> p);
8. Pause美颜 SDK，建议与 Activity 的 onPause() 生命周期绑定。
//在 Activity 的 onPause 时调用, 需要在 OpenGL 线程调用
mXmagicApi.onPause();
9. 释放美颜 SDK，建议与 Activity 的 onDestroy() 生命周期绑定。
//注意，此方法需要在GL线程中调用
mXmagicApi.onDestroy();

步骤四：混淆配置

如果您在打 release 包时，启用了编译优化（把 minifyEnabled 设置为 true），会裁掉一些未在 java 层调用的代码，而这些代码有可能会被 native 层调用，从而引起 no xxx method 的异常。
如果您启用了这样的编译优化，那就要添加这些 keep 规则，防止 xmagic 的代码被裁掉：
-keep class com.tencent.xmagic.** { *;}
-keep class org.light.** { *;}
-keep class org.libpag.** { *;}
-keep class org.extra.** { *;}
-keep class com.gyailib.**{ *;}
-keep class com.tencent.cloud.iai.lib.** { *;}
-keep class com.tencent.beacon.** { *;}
-keep class com.tencent.qimei.** { *;}
-keep class androidx.exifinterface.** { *;}

附件（SDK文件结构）：

注意：
此表格列出了SDK用到的所有文件，可能您的套餐中没有某些文件，但并不影响该套餐功能的使用。
文件类型
说明
assets
audio2exp
avatar 虚拟人语音驱动模型，如果不使用该功能，则无需该模型
benchmark
机型适配使用
Light3DPlugin
3D 贴纸使用
LightBodyPlugin
LightBody3DModel.bundle
人体 3D 骨骼点位使用
LightBodyModel.bundle
美体功能使用
LightCore
SDK 核心模型资源
LightHandPlugin
手势贴纸、手部点位能力需要
LightSegmentPlugin
背景分割能力需要使用
lut
免费的滤镜资源
demo_xxx_android_xxxx

demo 工程
jniLibs
libace_zplan.so
3D 引擎库
libaudio2exp.so
avatar 虚拟人语音驱动库，如果不使用该功能，则无需该库
libc++_shared.so
libc++_shared.so 是一个 C++ 标准库的共享库，它提供了一组C++ 标准库函数和类，用于支持 C++ 程序的开发和运行。它在 Android 系统中被广泛使用，是 C++ 应用程序和库的重要组成部分。如果您的工程中已有 C++ 共享库，可以只保留一份
liblight-sdk.so
light sdk 核心库
libpag.so
light sdk 依赖的动画文件库
libtecodec.so
light sdk 依赖的编解码库
libv8jni.so
light sdk 依赖的用于解析 JavaScript 的库
libYTCommonXMagic.so
license 鉴权使用
libs
xmagic-xxxx.aar
美颜 SDK 的 aar 文件
MotionRes
2dMotionRes
2D 贴纸
3dMotionRes
3D 贴纸
avatarRes
Avatar素材
ganMotionRes
童趣贴纸
handMotionRes
手势贴纸
makeupRes
美妆贴纸
segmentMotionRes
背景分割贴纸
unity
aar
unity 项目需要使用的桥接 aar
module
桥接 aar 的原工程

中国站