This document shows you how to quickly integrate Beauty AR SDK.
Developer Environment Requirements
Android 4.4 (SDK API level 19) or later versions. Android 7.0 (SDK API level 24) or later versions are recommended.
Android Studio 3.5 or later versions.
Demo Project: TEBeauty_API_Example
Clone the demo project from GitHub, where the TEBeautyDemo is a demo project with UI, and the TEBeauty_API_Example is a demo project without UI.
Follow the instructions in the TEBeauty_API_Example/README document to get the TEBeauty_API_Example running, and then combine this text to understand the detailed steps for integrating the SDK without a UI.
Note:
In the demo project on GitHub, the SDK is integrated using Maven.
Step 1. IntegrationSDK
Choose one of the following integration methods:
Maven Intergration
Manual Integration (Built-in Resources)
Manual Integration (Dynamic Resource Download)
The Tencent Effect SDK has been released to the mavenCentral repository, and you can configure Gradle to download updates automatically.
1. Add the Tencent Effect SDK dependency in the dependencies section.
//The version number can be found on the Version History page on the official website, e.g., 3.0.0.13. You can also use latest.release for the version number.
//But please note: using latest.release will always keep your SDK version up to date, which might not meet your expectations for versions with major changes. Use latest.release with caution.
2. In defaultConfig, specify the CPU architecture for the app.
defaultConfig {
ndk {
abiFilters "armeabi-v7a", "arm64-v8a"
}
}
Note:
Currently, the Tencent Effect SDK supports armeabi-v7a and arm64-v8a.
3. click
<2> to automatically download the SDK and integrate it into the project.
Downloading SDK
Download the SDK and decompress it. The directory structure is as follows: .
Dynamically Downloading Assets, .so Libraries, and Dynamic Effect Resources Guide
To reduce the package size, you can change the download mode of the assets resources, .so libraries, and dynamic effect resources MotionRes (some basic SDKs do not have dynamic effect resources) required by the SDK to the online mode. After successful download, provide the paths of the above files to the SDK through setting.
You can use your existing download service, but we recommend you use the download logic of the demo. For detailed directions on implementing dynamic download, see Reducing SDK Size (Android).
Step 2. Integrate Effect Resources
If your package includes dynamic effect and filter features, you need to download the corresponding resources and place the dynamic effect and filter materials in the following directories under your project:
Dynamic effect: ../assets/MotionRes
Filter: ../assets/lut
Step 3. Authenticate
1. Apply for a license and get the License URL and License KEY as instructed in License Guide.
2. In the initialization code of the relevant module, set the URL and KEY to trigger the license download. Do not download it just before use. You can also trigger the download in the onCreate method of the Application, but this is not recommended as the download is very likely to fail if there is no network permission or if a network disconnection occurs.
// If you just want to trigger the download or update the license but don't care about the authentication result, you can pass in `null` for the fourth parameter.
3. Authenticate when you need to use the beauty filter feature (for example, in the TEMenuActivity.java of the demo):
// If your `so` library is downloaded from the internet, set the `so` path before calling `TELicenseCheck.getInstance().setTELicense`; otherwise, authentication will fail.
// Note: this callback is not necessarily in the call thread
if(errorCode ==TELicenseCheck.ERROR_OK){
// Authentication succeeded
}else{
// Authentication failed
}
}
});
Authentication errorCode description:
Error Code
Description
0
Success.
-1
The input parameter is invalid; for example, the URL or KEY is empty.
-3
Download failed. Check the network settings.
-4
Unable to obtain any authentication information from the local system, which may be caused by an I/O failure.
-5
The VCUBE TEMP license file is empty, which may be caused by an I/O failure.
-6
The JSON field in the v_cube.license file is incorrect. Contact Tencent Cloud for assistance.
-7
Signature verification failed. Contact Tencent Cloud for assistance.
-8
Decryption failed. Contact Tencent Cloud for assistance.
-9
The JSON field in TELicense is incorrect. Contact Tencent Cloud for assistance.
-10
The SDK authorization information parsed online is empty. Contact Tencent Cloud for assistance.
-11
Failed to write the SDK authorization information to the local file, which may be caused by an I/O failure.
-12
Download failed, and failed to parse local assets.
-13
Authentication failed. Check whether the so file is in the package or the so path has been set correctly.
3004/3005
The authorization is invalid. Contact Tencent Cloud for assistance.
3015
Bundle ID and Package Name mismatch. Check whether the Bundle ID or Package Name used by your app are the same as the ones you applied for and whether the correct license file is used.
3018
The license file has expired and needs to be renewed.
Others
Contact Tencent Cloud for assistance.
Step 4. Copy resources
1. If your resource files are built into the assets directory, you need to copy them to the app's private directory before use. You can copy them in advance or in the callback of successful authentication in the previous step. The sample code is in the TEMenuActivity.java of the demo.
// Assign `resPathSetting` to the `mResPath` variable in the following `copyRes` method
2. If your resource files are downloaded dynamically from the internet, after the download succeeds, you need to set the resource file path. The sample code is in the TEMenuActivity.java of the demo.
mXmagicApi =newXmagicApi(this, local path of downloaded resource files,newXmagicApi.OnXmagicPropertyErrorListener());
Step 5. Initialize and use the SDK
The following is the process of using the Beauty AR SDK:
1. Constructing Beautification UI Data, refer to the 'tebeautykit' module in the Demo project for guidance. (the code in the com.tencent.effect.beautykit.provider package).
2. Add the GLCameraView in the demo to the preview layout.
<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. (Optional) Quickly implement the camera feature.
Copy the com.tencent.demo.camera directory from the demo project to the project. Use the GLCameraXView class to quickly implement the camera feature. For more information, see TECameraActivity.java of the demo project.
5. Add the callback function for material prompt (method callbacks may run in child threads). Some materials will prompt the user to nod, stretch out their palms, or make a finger heart, and this callback is used to display the prompts.
8. Recover audio effects, it is recommended to call in the Activity's onResume() method.
// Restore the sound effects in the beauty, some material contain sound effects
mXmagicApi.onResume();
9. Pause the audio effects, recommend invoking the onPause() method in Activity.
// Pause the sound of the material, regardless of whether the material contains audio effects
mXmagicApi.onPause();
10. To release the beauty SDK, it needs to be called in the GL thread.
// Note that this method needs to be called in the GL thread
mXmagicApi.onDestroy()
Step 6. Configure obfuscation
If you have enabled compilation optimization (by setting minifyEnabled to true) when printing the release package, some code that is not called at the Java layer will be trimmed out and may be called at the native layer, causing a no xxx method exception.
If you have enabled such compilation optimization, add the following keep rules to prevent Xmagic code from being trimmed out:
-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.**{*;}
Attachment (SDK file structure):
Note:
This table lists all the files used by the SDK. Some files may not be included in your package, but this does not affect the functionality of the package.
File Type
Description
assets
audio2exp
Avatar: A virtual human voice-driven model. If you do not use this feature, you do not need this model.
benchmark
Device compatibility usage.
Light3DPlugin
Usage of 3D stickers.
LightBodyPlugin
LightBody3DModel.bundle
Usage of 3D skeletal points for human body.
LightBodyModel.bundle
Usage of body shaping feature.
LightCore
SDK core model resources.
LightHandPlugin
Usage of gesture stickers and hand tracking capabilities.
LightSegmentPlugin
Usage of background segmentation capabilities.
lut
Free filter resources.
demo_xxx_android_xxxx
Demo project.
jniLibs
libace_zplan.so
3D engine library.
libaudio2exp.so
Avatar virtual human voice driver library. If this feature is not being used, then this library is not necessary.
libc++_shared.so
libc++_shared.so is a shared library for the C++ standard library, which provides a set of functions and classes to support the development and execution of C++ programs. It is widely used in the Android system and is an important component of C++ applications and libraries. If your project already has a C++ shared library, you can keep only one copy.
liblight-sdk.so
Light SDK core library.
libpag.so
Animation file library that Light SDK depends on.
libtecodec.so
Encoding and decoding library that Light SDK depends on.
libv8jni.so
Library used for parsing JavaScript that Light SDK depends on.