Android

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 run TEBeauty_API_Example, and then refer to this document for detailed steps to integrate the SDK with UI.

Integration Method

Note: In the demo project on GitHub, the SDK is integrated using Maven.
Manual Integration (Built-in Resources)
Manual Integration (Dynamic Resource Download)
Maven Integration

Downloading SDK

Download the SDK and decompress it. The directory structure is as follows:


Integration

Copy the xmagic-xxxx.aar file from the SDK folder to your project's libs directory.
Copy the lut from the resource folder to the project's ../src/main/assets directory. If there are resources in the MotionRes folder under resource, also copy this folder to the ../src/main/assets directory.

Importing Method

Open the app module's build.gradle and add the dependency reference:
android{
...
defaultConfig {
applicationId "Modify it with the package name bound to the authorized license."
....
}
packagingOptions {
pickFirst '**/libc++_shared.so'
}
}

dependencies{
...
compile fileTree(dir: 'libs', include: ['*.jar','*.aar'])//add *.aar
}Note:
Note:
The following dependencies need to be added to the project:
dependencies{
implementation 'com.google.code.gson:gson:2.8.2'
//Needs to be added for v2.6.0 to 3.1.0.2.
implementation 'androidx.exifinterface:exifinterface:1.3.3'
//Needs to be added for v3.5.0 or later versions.
implementation 'com.tencent.tav:libpag:4.3.33-noffavc'
}
If you want to use another version of pag, please click here to view.

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).
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.
dependencies {
//For example, the S1-04 package is as follows:
implementation 'com.tencent.mediacloud:TencentEffect_S1-04:version number'
//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
img

<2> to automatically download the SDK and integrate it into the project.
4. If your package includes dynamic effect and filter features, you need to download the corresponding resources from the SDK Download Page and place the dynamic effect and filter materials in the following directories under your project:
Dynamic effect: ../assets/MotionRes
Filter: ../assets/lut

Maven Address for Each Package

Version
Maven Address
A1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_A1-01:version number'
A1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_A1-02:version number'
A1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_A1-03:version number'
A1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_A1-04:version number'
A1 - 05
implementation 'com.tencent.mediacloud:TencentEffect_A1-05:version number'
A1 - 06
implementation 'com.tencent.mediacloud:TencentEffect_A1-06:version number'
S1 - 00
implementation 'com.tencent.mediacloud:TencentEffect_S1-00:version number'
S1 - 01
implementation 'com.tencent.mediacloud:TencentEffect_S1-01:version number'
S1 - 02
implementation 'com.tencent.mediacloud:TencentEffect_S1-02:version number'
S1 - 03
implementation 'com.tencent.mediacloud:TencentEffect_S1-03:version number'
S1 - 04
implementation 'com.tencent.mediacloud:TencentEffect_S1-04:version number'

SDK Usage Process

Step 1: Authenticate

1. Apply for authorization to obtain the license URL and license key. Please refer to the License Guide.
2. Set the URL and key in the initialization code of the related business module to trigger license download to avoid downloading temporarily before use. For example, in our demo project, the download is triggered in the onCreate method of the application. However, we do not recommend triggering it here in your project because network permission might not be available or there could be a high rate of network failure at this time. Please choose a more appropriate time to trigger the license download.
//If you only want to trigger the download or update the license without caring about the authentication result, input null for the fourth parameter.
TELicenseCheck.getInstance().setXMagicLicense(context, URL, KEY, null);
3. Perform authentication before actually using the beauty feature:
TELicenseCheck.getInstance().setTELicense(context, URL, KEY, new TELicenseCheckListener() {

@Override
public void onLicenseCheckFinish(int errorCode, String msg) {
//Note: This callback may not be on the calling thread.
if (errorCode == TELicenseCheck.ERROR_OK) {
// Authentication succeeded.
} else {
// Authentication failed.
}
}
});
Note:
Under normal circumstances, as long as the app can connect to the internet normally and the license URL can be accessed normally in the user's region, the authentication process can be completed using the above code, and the license information will be cached locally. Therefore, you do not need to embed the license file into the project.
But in special situations, the app may consistently fail to connect to the internet or be unable to access the license URL, making authentication impossible. To address this, you can open your license URL in a browser, download the license file, place it in the project's src/main/assets directory, and name it v_cube.license. This way, even if online authentication fails, local authentication can be performed.
If using the built-in license scheme, ensure that the license file in the package is always the latest version. For example, after renewing the license, download the updated license file and place it in the package.
Authentication error code description:
Error Code
Description
0
Success
-1
Invalid input parameters, such as empty URL or KEY
-3
Download failure. Please check your network settings.
-4
TE authorization information read locally is empty, possibly due to I/O failure.
-5
Content of the VCUBE TEMP license file is empty, possibly due to I/O failure.
-6
JSON fields in the v_cube.license file are incorrect. Please contact the Tencent Cloud team to deal with it.
-7
Signature verification failed. Please contact the Tencent Cloud team to deal with it.
-8
Decryption failed. Please contact the Tencent Cloud team to deal with it.
-9
JSON fields in the TELicense field are incorrect. Please contact the Tencent Cloud team to deal with it.
-10
The TE authorization information parsed from the network is empty. Please contact the Tencent Cloud team to deal with it.
-11
Failed to write TE authorization information to a local file, possibly due to I/O failure.
-12
Download failed, and parsing local assets also failed.
-13
Authentication failed. Please check if the .so file is in the package or if the .so path is set correctly.
3004/3005
Invalid authorization. Please contact the Tencent Cloud team to deal with it.
3015
Bundle ID/Package Name mismatch. Check if the Bundle ID/Package Name used by your app is consistent with the applied one, and ensure you are using the correct license file.
3018
The license file has expired. You need to apply for a renewal from Tencent Cloud.
Others
Please contact the Tencent Cloud team to deal with it.

Step 2: Copy resources

The resource files mentioned here consist of two parts:
The SDK model files, located in the assets directory of the SDK's AAR package.
Filter and dynamic effect resource files, located in the assets directory of the demo project, named lut and MotionRes respectively.
Before using the beauty effect, you need to copy the above resources to the app's private directory. If the SDK version is not updated, you only need to copy it once. After a successful copy, you can record it in the SharedPreference of the app, so that you do not need to copy it again next time. For details, refer to TEMenuActivity.java in the demo project.
String resPath = new File(getFilesDir(), AppConfig.getInstance().getBeautyFileDirName()).getAbsolutePath();
if (!resPath.endsWith(File.separator)) {
resPath = resPath + File.separator;
}
AppConfig.resPathForSDK = resPath;
AppConfig.lutFilterPath = resPath + "light_material/lut";
AppConfig.motionResPath = resPath + "MotionRes";


new Thread(() -> {
Context context = getApplicationContext();
int addResult = XmagicApi.addAiModeFilesFromAssets(context, AppConfig.resPathForSDK);
Log.d(TAG, "copyRes, add ai model files result = " + addResult);

String lutDirNameInAsset = "lut";
boolean result = FileUtil.copyAssets(context, lutDirNameInAsset, AppConfig.lutFilterPath);
Log.d(TAG, "copyRes, copy lut, result = " + result);

String motionResDirNameInAsset = "MotionRes";
boolean result2 = FileUtil.copyAssets(context, motionResDirNameInAsset, AppConfig.motionResPath);
Log.d(TAG, "copyRes, copy motion res, result = " + result2);
}).start();

Step 3: Initialize and use the SDK

1. (Optional) Quickly implement cameras.
We assume you have already implemented the camera application, can start the camera normally, and can call back the camera's SurfaceTexture texture information to Activity for beauty effect processing, as shown below:
@Override
public int onCustomProcessTexture(int textureId, int textureWidth, int textureHeight) {
// The beauty effect SDK processes the textureId here, adds beauty effects and special effects for it, and returns the processed new textureID.
}
If you have not yet implemented the camera application, you can refer to TECameraBaseActivity.java in the demo project and use the GLCameraXView component to add it to your Activity's layout for quick camera preview:
<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" />
2. Initialize the beauty effect SDK. In the demo project, it is initialized in the Activity's onCreate() method:
//AppConfig.resPathForSDK is the resource path determined during the resource copy stage.
mXmagicApi = new XmagicApi(this, AppConfig.resPathForSDK);
Parameter
Parameter
Meaning
Context context
Context
String resDir
Resource file directory. For details, refer to Step 2.
OnXmagicPropertyErrorListener errorListener
Optional. Callback function implementation class, for handling some error codes during the SDK initialization and usage process. For the meanings of error codes, refer to API Documentation
3. (Optional) Add a material prompt callback function (method callback might run in a child thread). Some materials will prompt the user to nod, extend the hand, and make a heart gesture. This callback is used to display similar prompts.
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();
}
});
4. The beauty effect SDK processes each frame of data and returns the corresponding processing results. For detailed information on the process method, see the API Documentation.
@Override public int onCustomProcessTexture(int textureId, int textureWidth, int textureHeight) { return mXmagicApi.process(textureId, textureWidth, textureHeight); }
5. Set beauty effects or special effects.
Use the setEffect method for version 3.5.0 and later. For detailed information, see the API Documentation.
Use the updateProperty method for version 3.3.0 and earlier. For detailed information, see the API Documentation.
//Use this method for version 3.5.0 and later.
mXmagicApi.setEffect(String effectName, int effectValue, String resourcePath, Map<String, String> extraInfo)


// Available input parameter properties can be obtained from XmagicResParser.parseRes().
// Use this method for version 3.3.0 and earlier.
@Deprecated
mXmagicApi.updateProperty(XmagicProperty<?> p);
6. Lifecycle method onResume: It is recommended to call it in the Activity's onResume() method. When called, it will resume the sound in the effects.
mXmagicApi.onResume();
7. Lifecycle method onPause: It is recommended to call it in the Activity's onPause() method. When called, it will pause the sound in the effects.
mXmagicApi.onPause();
8. Beauty effect release SDK: It is called when the OpenGL environment is being terminated. It needs to be called in the GL thread, and cannot be called in the main thread (Activity's onDestroy); otherwise, it may cause resource leaks and result in a white or black screen after multiple entries and exits.
@Override public void onGLContextDestroy() { mXmagicApi.onDestroy(); }

Step 4: Obfuscation configuration

If you enable compile optimization (setting minifyEnabled to true) when packaging the release, it will trim some code that is not called in the Java layer. This code may possibly be invoked by the native layer, thus causing the no xxx method exception.
If you have enabled such compile optimization, you should add these keep rules to prevent xmagic's code from being trimmed:
-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 will not affect the usage of that package's feature.
File Type
Description
assets
audio2exp
Avatar virtual human voice-driven model: If this feature is not used, the model is not needed.
benchmark
Used for model adaptation.
Light3DPlugin
Used for 3D stickers.
LightBodyPlugin
LightBody3DModel.bundle
Used for 3D human skeleton points.
LightBodyModel.bundle
Used for the body beauty feature.
LightCore
SDK core model resources
LightHandPlugin
Required for gesture stickers and hand-point capabilities.
LightSegmentPlugin
Required for 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-driven library: If this feature is not used, the library is not needed.
libc++_shared.so
libc_shared.so is a shared library of the C standard library. It provides a set of C standard library functions and classes to support the development and operation of C programs. It is widely used in the Android system and is an essential part of C applications and libraries. If your project already includes a C shared library, you can keep only one copy.
liblight-sdk.so
Light SDK core library
libpag.so
Animation file library that the light SDK depends on
libtecodec.so
Codec library that the light SDK depends on
libv8jni.so
JavaScript parsing library that the light SDK depends on
libYTCommonXMagic.so
Used for license authentication
libs
xmagic-xxxx.aar
Beauty effect SDK .aar file
MotionRes
2dMotionRes
2D stickers
3dMotionRes
3D stickers
avatarRes
Avatar materials
ganMotionRes
Fun stickers
handMotionRes
Gesture stickers
makeupRes
Makeup stickers
segmentMotionRes
Background segmentation stickers
unity
aar
Bridging AAR required for the unity project
module
Original project for the bridging AAR