Android
Feature Overview
To facilitate customers' quick integration of the beauty effect and simplify the development of UI panels, we provide the beauty effect UI component: TEBeautyKit. It includes further encapsulation of the SDK and customizable UI panels, as shown in the figure below. If you do not need to use this UI, refer to No UI integration of Tencent effects.
Demo Project: TEBeautyDemo
Clone the demo project from GitHub, follow the instructions in the TEBeautyDemo/README document to run TEBeautyDemo, and then refer to this document for detailed steps on integrating the SDK with UI.
Integrate TEBeautyKit
Note:
This library only supports Tencent Effect SDK V3.5.0 and later versions.
Step 1: Add TencentEffectSDK dependency
Step 2: Add TEBeautyKit dependency
Copy the TEBeautyKit module from the demo project into your project, and modify the SDK package type and version number in
tebeautykit/build.gradle
to match the SDK package type and version number in Step 1.implementation 'com.tencent.mediacloud:TencentEffect_S1-04:SDK version number'
Then add the dependency on the TEBeautyKit module in the relevant module of your app:
implementation project(':tebeautykit')
Add the dependency on the TEBeautyKit library in your app's dependencies. The SDK version number should match the version number in Step 1.
dependencies{...implementation 'com.tencent.mediacloud:TEBeautyKit:SDK version number'}
Since TEBeautyKit also depends on components like Gson and OkHttp, you need to add the following dependencies:
dependencies{implementation 'com.google.code.gson:gson:2.8.2'implementation 'com.squareup.okhttp3:okhttp:3.9.0'implementation 'com.github.bumptech.glide:glide:4.12.0'implementation 'androidx.appcompat:appcompat:1.0.0'implementation 'androidx.constraintlayout:constraintlayout:2.1.3'implementation 'androidx.recyclerview:recyclerview:1.2.1'}
Download TEBeautyKit (The downloaded file will be a zip file. Extract it to get the AAR file.)
Copy the
tebeautykit-xxxx.aar
file to the app project's libs
directory.Open the app module's
build.gradle
and add the dependency reference:dependencies{...implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])}
Since TEBeautyKit also depends on components like Gson and OkHttp, you need to add the following dependencies:
dependencies{implementation 'com.google.code.gson:gson:2.8.2'implementation 'com.squareup.okhttp3:okhttp:3.9.0'implementation 'com.github.bumptech.glide:glide:4.12.0'implementation 'androidx.appcompat:appcompat:1.0.0'implementation 'androidx.constraintlayout:constraintlayout:2.1.3'implementation 'androidx.recyclerview:recyclerview:1.2.1'}
Step 3: Add the panel JSON file
Obtain the panel configuration file from the demo project's demo/src/main/assets/beauty_panel, or click here to download and unzip it. The file includes configurations for beauty, body beauty, filters, dynamic effect stickers, and segmentation properties. Select a set of JSON files according to your package type and place them in the
assets/beauty_panel
folder in your project (the panel_icon folder also needs to be placed in this directory).
The downloaded archive contains the files as shown above. Each package name corresponds to several JSON files. The table below explains each JSON file:
File | Description |
beauty.json | Configuration file for beauty effect, shaping, image adjustment, etc. |
beauty_body..json | Configuration file for body beauty |
lut.json | Filter configuration file. Note: Since different customers use different filter materials, customers can configure according to the JSON structure after downloading (refer to JSON File Structure Description) and delete the default configuration. |
makeup.json | Configuration file for full-face makeup style. Note: Since different customers use different materials for full-face makeup style, customers can configure according to the JSON structure after downloading (refer to JSON File Structure Description). |
motions.json | Dynamic effect sticker configuration file. Note: Since different customers use different dynamic effect sticker materials, customers can configure according to the JSON structure after downloading (refer to JSON File Structure Description). |
segmentation.json | Background segmentation (virtual background) configuration file. Note: Since different customers use different segmentation materials, customers can configure according to the JSON structure after downloading (refer to JSON File Structure Description). |
panel_icon | This folder is used for storing images configured in the JSON file, and must be added. |
How to Use TEBeautyKit
We strongly recommend that you refer to the
TEMenuActivity.java
and TECameraBaseActivity.java
of the demo project's to understand how to integrate TEBeautyKit.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.//TEApplication.javaTEBeautyKit.setTELicense(context, LicenseConstant.mXMagicLicenceUrl, LicenseConstant.mXMagicKey, null);
3. Perform authentication before actually using the beauty feature (e.g., before launching the camera):
//TEMenuActivity.javaTEBeautyKit.setTELicense(context, LicenseConstant.mXMagicLicenceUrl, LicenseConstant.mXMagicKey, new TELicenseCheckListener() {@Overridepublic 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.}}});
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: Set the path
//TEMenuActivity.javaString resPath = new File(getFilesDir(), AppConfig.getInstance().getBeautyFileDirName()).getAbsolutePath();TEBeautyKit.setResPath(resPath);
Step 3: 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 resPath set in Step 2. 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 the
copyRes
method of TEMenuActivity.java
in the demo project.//TEMenuActivity.javaprivate void copyRes() { if (!isNeedCopyRes()) { return; } new Thread(() -> { TEBeautyKit.copyRes(getApplicationContext()); }).start(); }
Step 4: Initialize TEBeautyKit and add the view to the page
//TECameraBaseActivity.javaTEBeautyKit.create(this.getApplicationContext(), beautyKit -> { mBeautyKit = beautyKit; initBeautyView(beautyKit); });public void initBeautyView(TEBeautyKit beautyKit){TEPanelViewResModel resModel = new TEPanelViewResModel();String combo = "S1_07"; //Set according to your package. If your package does not include a certain feature, the customer is set to null.resModel.beauty = "beauty_panel/"+combo+"/beauty.json";resModel.lut = "beauty_panel/"+combo+"/lut.json";resModel.beautyBody = "beauty_panel/"+combo+"/beauty_body.json";resModel.motion = "beauty_panel/"+combo+"/motions.json";resModel.lightMakeup = "beauty_panel/"+combo+"/light_makeup.json";resModel.segmentation = "beauty_panel/"+combo+"/segmentation.json";TEUIConfig.getInstance().setTEPanelViewRes(resModel);mTEPanelView = new TEPanelView(this);mTEPanelView.setTEPanelViewCallback(this);mTEPanelView.setupWithTEBeautyKit(beautyKit);mTEPanelView.showView(this);this.mPanelLayout.addView(mTEPanelView, new LinearLayout.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.WRAP_CONTENT));}
The parameter in the
TEUIConfig.getInstance().setTEPanelViewRes
method is the JSON file in the src/main/assets/beauty_panel mentioned above. If you do not need a particular item, you can input null at the corresponding position.Step 5: Use beauty effect
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:
//TECameraBaseActivity.java@Overridepublic 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.GLCameraXViewandroid: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" />
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.
//TECameraBaseActivity.java@Override public int onCustomProcessTexture(int textureId, int textureWidth, int textureHeight) { return mBeautyKit.process(textureId, textureWidth, textureHeight); }
Step 6: Manage the lifecycle
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.mBeautyKit.onResume();
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.mBeautyKit.onPause();
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() { mBeautyKit.onDestroy(); }
Step 7: Export and import beauty effect parameters
Export the current beauty effect parameters and save them in SharedPreference:
String json = mBeautyKit.exportInUseSDKParam(); if (json != null) { getSharedPreferences("demo_settings", Context.MODE_PRIVATE).edit().putString("current_beauty_params", json).commit(); }
Next time when initializing TEBeautyKit, import this string to modify the default beauty effect:
Appendix
Panel JSON File Description
Beauty effect and body beauty
Field | Description |
displayName | Chinese name |
displayNameEn | English name |
icon | Image address, supports local images and network images. Local images support assets resources and SD resources. For asset images, refer to the image above. For SD card images, set the full paths of the images. For network images, set the corresponding HTTP links. |
sdkParam | Properties required by the beauty effect SDK, including four properties. Refer to the beauty effect parameter table. |
effectName | |
effectValue | |
resourcePath | |
extraInfo |
Filters, dynamic effect stickers, and segmentations
Since the configurations of filters, dynamic effect stickers, and segmentations are basically the same, the JSON for filters is explained here. The
downloadPath
and resourceUri
fields are added.Field | Description |
downloadPath | If your filter materials are downloaded from the network, the local storage location for the download is configured here. This is a relative path, with the full path being the one set in TEBeautyKit.setResPath + the path set here. |
resourceUri | If your material needs to be downloaded via a network, the network address is configured here, as in the third red box in the image above. However, if your filter material is local, configure the corresponding local address according to the image above. |
Full-face makeup style
An additional field
makeupLutStrength
under extraInfo
has been included in the full-face makeup style. This field is used to moderate the intensity of filters in the full-face makeup style (configure this if the full-face makeup style supports filter intensity modulation). Refer to the beauty effect parameter table for this field.TEBeautyKit Method Description
//Asynchronously create the TEBeautyKit object.public static void create(@NonNull Context context, @NonNull OnInitListener initListener)//isEnableHighPerformance: Whether to enable high-performance mode//After the high-performance mode is enabled, the system CPU/GPU resources occupied by beauty effect are less, which reduces phone heating and lag, making it more suitable for long-term use on low-end devices.//However, please note: after the high-performance mode is enabled, the following beauty options will be disabled://1. Eye: eye width, eye height, and elimination of eye bags//2.Eyebrow: angle, distance, height, length, thickness, and eyebrow peak//3. Mouth: smile lip//4. Face: slim face (natural, goddess, and handsome), tighten lower jaw, remove wrinkles, and remove nasolabial folds. It is recommended to use face shape to achieve a comprehensive, large-eyed, slimming effect.public static void create(@NonNull Context context, boolean isEnableHighPerformance, @NonNull OnInitListener initListener)//Constructor method of TEBeautyKit, used for synchronously creating the TEBeautyKit objectpublic TEBeautyKit(Context context)/** * @param context Application context * @param isEnableHighPerformance: Whether to enable the high-performance mode */ public TEBeautyKit(Context context, boolean isEnableHighPerformance)/** * Set the mute state. * * @param isMute: true indicates the mute state. */ public void setMute(boolean isMute)/** * If you are carrying out beauty processing on pictures, you need to call this method to set the type of the data source, which could either be a camera data source or a picture data source. * Camera data source: XmagicApi.PROCESS_TYPE_CAMERA_STREAM Picture data source: XmagicApi.PROCESS_TYPE_PICTURE_DATA * @param type: The default type is a video stream. */ public void setBeautyStreamType(int type)/** * Enable or disable a specific feature. * * @param featureName: Refer to XmagicConstant.FeatureName for values. * @param enable true indicates to enable; false indicates to disable. */ public void setFeatureEnableDisable(String featureName, boolean enable)/** * Perform beauty processing on the image. * * @param bitmap * @param needReset * @return */ public Bitmap process(Bitmap bitmap, boolean needReset)/** * Process each frame of video/camera data. * * @param textureId: The ID of the texture. This texture requires a texture type of GL_TEXTURE_2D and a pixel texture format of RGBA. * @param width Texture width * @param height Texture height * @return: processed texture ID */ public int process(int textureId, int width, int height)/** * Update beauty properties. * * @param paramList */ public void setEffectList(List<TEUIProperty.TESDKParam> paramList)/** * Update beauty properties. * * @param teParam */ public void setEffect(TEUIProperty.TESDKParam teParam)/** * Enable or disable the enhanced mode. * * @param enableEnhancedMode: true indicates to enable the enhanced mode; false indicates to disable the enhanced mode. * @return: A returned value of true indicates a state change has occurred; and a returned value of false indicates that there is no change in state. */ public boolean enableEnhancedMode(boolean enableEnhancedMode)/** * Obtain the currently active beauty properties list string. * Clients can save the exported string locally and call the `setLastParamList` method to perform setting after creating a TEPanelView object next time. * @return */ public String exportInUseSDKParam()/** * Used to restore the sound in stickers. * Restore the gyroscope sensor. */ public void onResume()/** * Used to pause the sound in stickers. * Pause the gyroscope sensor. */ public void onPause()/** * Terminate the beauty effect. * Note: This method must be called in the GL thread. */ public void onDestroy()/** * Set event listener for listening to smartphone direction events for the adapter. * @param listener Event listener callback */ public void setEventListener(EventListener listener)/** * Set setAIDataListener callback. * * @param aiDataListener */ public void setAIDataListener(XmagicApi.XmagicAIDataListener aiDataListener)/** * Set dynamic effect tips callback function to display tips on the front-end page. * * @param tipsListener */ public void setTipsListener(XmagicApi.XmagicTipsListener tipsListener)/** * Capture the current texture screen. * * @param callback */ public void exportCurrentTexture(XmagicApi.ExportTextureCallback callback)/** * Set the degree of anti-clockwise rotation of the texture. * Primary feature: Used for texture rotation inside the SDK. After rotation of a certain degree, the head is upright, enabling face recognition inside the SDK. * By default, inside the SDK, a sensor is used to obtain the required degree of rotation. * * @param orientation: Its value can only be 0, 90, 180, or 270. */ public void setImageOrientation(TEImageOrientation orientation)/** * Check whether the current device supports this material. * * @param motionResPath: the path to the material file * @return */ public boolean isDeviceSupport(String motionResPath)/** * Obtain the on-and-off state of the beauty effect. * * @return EffectState */ public EffectState getEffectState()/** * Set whether to enable the beauty effect. * * @param effectState ENABLED indicates enabled; DISABLED indicates disabled. */ public void setEffectState(EffectState effectState)/** * Set the policy implementation class for the enhanced mode. If not set, the default implementation is used. * * @param teParamEnhancingStrategy: Enhanced mode processing class. */ public void setParamEnhancingStrategy(TEParamEnhancingStrategy teParamEnhancingStrategy)//The following are the static methods./** * Set the path for storing beauty resources. * * @param resPath */ public static void assignResPath(String resPath)/** * Unpack resource files from the APK's assets to a specified path. First, you need to set the path: {@link #setResPath(String)}. <br> * This should be called once after the first installation of the app, or after an app upgrade. * Copy xmagic resource from assets to a local path. */ public static boolean copyRes(Context context)/** * Perform beauty authorization check. * Note: When this method is used, if the callback interface is not set, authorization will not be performed (it will only download the authorization information from the network). * Therefore, you can refer to the demo and call it in the application without setting a callback, but call this method again (set the callback interface) for authorization before using the TEBeautyKit object. * @param context Application context * @param licenseKey LicenseKey applied for on the platform * @param licenseUrl License URL applied for on the platform * @param teLicenseCheckListener: Authorization callback interface */ public static void setTELicense(Context context, String licenseUrl, String licenseKey, TELicenseCheck.TELicenseCheckListener teLicenseCheckListener)
TEUIConfig Description
Modify panel colors
Global modification: After obtaining the object through
TEUIConfig.getInstance()
, you can adjust the panel colors by modifying the following fields.Partial modification: Using the
new TEUIConfig
object, adjust the panel colors by modifying the following fields, and update the panel style using the TEPanelView.updateUIConfig
method.@ColorInt public int panelBackgroundColor = 0x66000000; //Default background color @ColorInt public int panelDividerColor = 0x19FFFFFF; //Divider color @ColorInt public int panelItemCheckedColor = 0xFF006EFF; //Selected item color @ColorInt public int textColor = 0x99FFFFFF; //Text color @ColorInt public int textCheckedColor = 0xFFFFFFFF; //Selected text color @ColorInt public int seekBarProgressColor = 0xFF006EFF; //Progress bar color
Configure the JSON file of the panel
/** * Set the JSON file path of the beauty panel. * @param beauty: JSON file path for beauty properties. Set to null if not available. * @param beautyBody: JSON file path for body beauty properties. Set to null if not available. * @param lut: JSON file path for filter properties. Set to null if not available. * @param motion: JSON file path for dynamic effect sticker properties. Set to null if not available. * @param makeup: JSON file path for full-face makeup style properties. Set to null if not available. * @param segmentation: JSON file path for segmentation properties. Set to null if not available. */ public void setTEPanelViewRes(String beauty, String beautyBody, String lut, String motion, String makeup, String segmentation)
Update panel language
//When the client program detects a modification to the system's font, it may call this method. At present, the panel supports only Chinese and English.public void setSystemLocal(Locale locale)
TEPanelView Description
/** * Used to set the data of the last beauty effect, with the intent to restore the beauty panel to its prior state. * Note: This method needs to be used prior to the {@link #showView(TEPanelViewCallback tePanelViewCallback)}} method. * * @param lastParamList: Beauty data, which can be obtained through the {@link TEBeautyKit#exportInUseSDKParam()} ()}} method, and then stored. Input this string the next time you start the beauty effect. */ void setLastParamList(String lastParamList); /** * Present the beauty panel. * @param tePanelViewCallback: Panel event callback interface */ void showView(TEPanelViewCallback tePanelViewCallback); /** * Bind the TEBeautyKit object. When the user clicks an item, the panel will directly call the method of TEBeautyKit to set the properties. * @param beautyKit The TEBeautyKit object */ void setupWithTEBeautyKit(TEBeautyKit beautyKit);/** * Select the selected items for the custom segmentation or green screen, because after the click of the green screen or custom segmentation button, it navigates to the album. * Only after the user has selected a picture or video, the corresponding item can be selected. If the user cancels the operation during this process, the corresponding item cannot be selected. * * @param uiProperty */ void validatePanelViewItem(TEUIProperty uiProperty);/** * Set the UI configuration of the current panel. * @param uiConfig */ void updateUIConfig(TEUIConfig uiConfig);