XmagicApi.java
, utilized for initializing the SDK, updating beauty metric values, invoking animated effects, amongst other features.API | Description |
constructor. | |
@Deprecated | Updates the attribute, it can be invoked in any thread (V3.3.0 and before). |
@Deprecated | Performing bulk attribute updates can be invoked in any thread (V3.3.0 and previous). |
Establishing beauty enhancements, styling, filters, makeup applications, stickers, division and other effects can be invoked in any thread (New in V3.5.0 version) | |
Setting up callback functions for animated hint text, designated to display hints on the frontend page. | |
@Deprecated | Configure the callback of facial keypoints and other data, callback will only be available with the License authorization required to acquire facial keypoints (such as Atomic Capability X102). |
Configure the callback for face, gesture, and body detection statuses. | |
Pause audio playback, which can be associated with the `onPause` lifetime affinity of `Activity`. | |
Resume rendering, can be paired with Activity onResume lifetime affinity. | |
Terminate `xmagic`, which necessitates its invocation within the `GL` thread. | |
The method for SDK rendering to accept data can be used within the camera data callback function. | |
@Deprecated | Invoke this function when only the cessation of the audio is necessitated, without the need to release the GL thread. (This interface has been deprecated) |
It serves to establish the present angle of rotation of the mobile phone, thus adjusting the angle for AI to recognize faces based on this. | |
The list of dynamic effect resources is introduced into the SDK for examination, executing afterwards the XmagicProperty.isSupport field represents whether the atomic capability is applicable. According to XmagicProperty.isSupport , the UI layer can implement click restrictions, or directly eliminate from the resource list. | |
@Deprecated | Pass in a list of dynamic effect resources and return the list of SDK atomic capabilities used by each resource. (This interface has been deprecated) |
Return the atomic capability list supported by the current device. | |
Determine whether the current device supports refinement (OpenGL3.0). | |
Determine which beauties the current lic authorization supports. It only supports the detection of BEAUTY and BODY_BEAUTY types of beauty items. The detection result will be assigned to the XmagicProperty.isAuth field of each beauty object. | |
Set the input data type, the default is Android camera data stream. | |
Establish the log level of the SDK, the default is WARN . During the development and debugging stage, if needed, it can be set to Log.DEBUG. Be sure to set to Log.WARN or Log.ERROR upon official release, otherwise excessive logs will affect performance.Invoke after new XmagicApi(). | |
Whether to mute when using animation materials (Added in V2.5.0): Parameter: true indicates mute, false denotes non-mute. | |
Activate the beautification enhancing pattern (Added in V2.5.1). By default, it is not activated.for specific instructions, please refer to the enhanced mode usage guide. | |
| |
@Deprecated | Invoke this method to enable the high-performance pattern. Upon the activation of the high-performance pattern, the system CPU/GPU resources occupied by beauty filters are minimized, thereby reducing heat generation and latency issues in the mobile device. It is particularly suitable for prolonged use on low-end devices. (This interface has been deprecated) |
Invoke this method to enable the high-performance pattern. Upon the activation of the high-performance pattern, the system CPU/GPU resources occupied by beauty filters are minimized, thereby reducing heat generation and latency issues in the mobile device. It is particularly suitable for prolonged use on low-end devices. | |
Get the picture on the current texture | |
Enable or disable a certain capability. |
XmagicApi(Context context, String resDir)XmagicApi(Context context, String resDir,OnXmagicPropertyErrorListener xmagicPropertyErrorListener)
Parameter | Type | Meaning |
context | Context | context. |
resDir | String | Resource directory. If the SDK resources are built into assets, before the first use of the SDK, the resources need to be copied to the application's private directory. The resource path is set first via XmagicResParser.setResPath(new File(getFilesDir(), "xmagic").getAbsolutePath()) , and then the resource copying is completed via XmagicResParser.copyRes(getApplicationContext()) . See the TEMenuActivity.java document in the Demo for detailed information.If the SDK resources are downloaded from the internet, after a successful download, the resource path can be set by XmagicResParser.setResPath(validAssetsDirectory) .Access the previously set path via XmagicResParser.getResPath() . |
xmagicPropertyErrorListener | OnXmagicPropertyErrorListener | Error callback interface. |
Error code | Meaning |
-1 | Unknown error. |
-100 | 3D engine resource initialization failed. |
-200 | GAN materials are not supported. |
-300 | This device does not support this material component. |
-400 | The template JSON content is empty. |
-500 | The SDK version is too low. |
-600 | Splitting is not supported. |
-700 | OpenGL is not supported. |
-800 | Scripting is not supported. |
5000 | The resolution of the split background image exceeds 2160x3840. |
5001 | Insufficient memory required to segment the background image. |
5002 | Failed to parse the video segmentation of the background. |
5003 | Background video segment exceeds 200 seconds. |
5004 | Background video segment format unsupported. |
5005 | Background image segment possesses rotation angle |
void updateProperty(XmagicProperty<?> p)void updateProperties(List<XmagicProperty<?>> properties)
Parameter | Meaning |
XmagicProperty<?> p | Tencent Effect data entity class. Taking "Skin Smoothing" as an example, an instance can be created as follows: new XmagicProperty<>(Category.BEAUTY, null, null, BeautyConstant.BEAUTY_SMOOTH, new XmagicPropertyValues(0, 100, 50, 0, 1)); To take '2D Animated Effect Bunny Paste' as an example, you can instantiate a new instance in the following manner: new XmagicProperty<>(Category.MOTION, "video_tutujiang", "path of the effect file", null, null); If you want a certain animation/beauty/masking material to be overlaid on the current material, set the mergeWithCurrentMotion of that material's XmagicProperty object to true. For a detailed explanation of material overlay, see Material Overlay. For more examples, please refer to the configuration information in the assets/beauty_panel folder of the Demo project. |
Attribute Field | Description |
category | Category.BEAUTY |
ID | null Special case: The respective ID values for Natural, Goddess, and Handsome in the Face Slimming feature are: BeautyConstant.BEAUTY_FACE_NATURE_ID, BeautyConstant.BEAUTY_FACE_FEMALE_GOD_ID, BeautyConstant.BEAUTY_FACE_MALE_GOD_ID The ID value in the lipstick is: XmagicConstant.BeautyConstant.BEAUTY_LIPS_LIPS_MASK The ID value in the blush is: XmagicConstant.BeautyConstant.BEAUTY_MAKEUP_MULTIPLY_MULTIPLY_MASK The ID value in 3D is: XmagicConstant.BeautyConstant.BEAUTY_SOFTLIGHT_SOFTLIGHT_MASK |
resPath | null Special Case: Lipstick, blush, and three-dimensional resPath represent the paths of resource images. For details, please refer to the `assets/beauty_panel/advanced_beauty.json` file in the Demo. |
effkey | Mandatory, refer to the Demo Example: Brightening BeautyConstant.BEAUTY_WHITEN |
effValue | Mandatory, refer to the assets/beauty_panel/advanced_beauty.json file in the Demo, the demo project parses this file to construct an XmagicPropertyValues object, for XmagicPropertyValues attribute values, see beauty parameter description |
Attribute Field | Description |
category | Category.BODY_BEAUTY |
ID | null |
resPath | null |
effkey | Mandatory, refer to the Demo Example: Long-legged BeautyConstant.BODY_LEG_STRETCH |
effValue | Mandatory, refer to the assets/beauty_panel/beauty_body.json file in the Demo. In the demo project, parse this file to construct an XmagicPropertyValues object. The values of XmagicPropertyValues' properties can be seen in Beauty Parameters Explanation |
Attribute Field | Description |
category | Category.LUT |
ID | Image name, required Sample: dongjing_lf.png The "none" ID corresponds to XmagicProperty.ID_NONE |
resPath | Filter image path, mandatory, "none" setting as null |
effkey | null |
effValue | Mandatory,"None" Setting as null. It is an XmagicPropertyValues object, for the property values of XmagicPropertyValues see
Beauty parameters explanation |
Attribute Field | Description |
category | Category.MOTION |
ID | Resource folder name, required Example: video_lianliancaomei The "none" ID corresponds to XmagicProperty.ID_NONE |
resPath | Mandatory, refer to the Demo |
effkey | null |
effValue | null |
Attribute Field | Description |
category | Category.MAKEUP |
ID | Resource folder name, required Example: video_xuejiezhuang The "none" ID corresponds to XmagicProperty.ID_NONE |
resPath | Mandatory, refer to the Demo |
effkey | Mandatory. The value is: makeup.strength"None" Setting is null |
effValue | Mandatory, "None" Setting is null. This is an XmagicPropertyValues object, for the values of various properties of XmagicPropertyValues, see Beauty Parameter Explanation |
Attribute Field | Description |
category | Category.SEGMENTATION |
ID | Resource folder name, required Example: video_segmentation_blur_45 The "none" ID corresponds to XmagicProperty.ID_NONE From the Definition, the ID value must use: XmagicConstant.SegmentationId.CUSTOM_SEG_ID |
resPath | Mandatory, refer to the Demo |
effkey | null (excluding custom definition background), the value of the custom definition background is the selected resource path |
effValue | null |
void setEffect(String effectName, int effectValue, String resourcePath, Map<String, String> extraInfo)
void setTipsListener(XmagicApi.XmagicTipsListener effectTipsListener)
Parameter | Meaning |
XmagicApi.XmagicTipsListener effectTipsListener | Implementation class of the callback function, callbacks are not necessarily executed in the main thread. |
public interface XmagicTipsListener { /** * Display tips. * @param tips The text information of the returned tips. * @param tipsIcon The file path of the tips' icon, which can be used to resolve the corresponding image. If it is a pag file, it needs to be displayed using pagView.* Note: tipsIcon may be empty if it is not configured in the resources. * @param type The category of tips. 0 indicates that both tips and tipsIcon have values, 1 indicates that it is a pag resource and only tipsIcon has a value. * @param duration The duration of tips display in milliseconds. */ void tipsNeedShow(String tips, String tipsIcon, int type, int duration); /*** * Hide tips。 * @param tips The text information of the returned tips. * @param tipsIcon The file path of the tips' icon, which can be used to resolve the corresponding image. If it is a pag file, it needs to be displayed using pagView. * Note: tipsIcon may be empty if it is not configured in the resources. * @param type The category of tips. 0 indicates that both tips and tipsIcon have values, 1 indicates that it is a pag resource and only tipsIcon has a value. */ void tipsNeedHide(String tips, String tipsIcon, int type); }
public void tipsNeedShow(final String tips, String tipsIcon, int type, int duration) {final int tipsType = type;final String tipsIconPath = tipsIcon;mMainThreadHandler.post(new Runnable() {@Overridepublic void run() {if (tipsType == 0) {if (!TextUtils.isEmpty(tipsIconPath) && !mImageTipsIsShow) {mTipsImageView.setVisibility(View.VISIBLE);Bitmap bitmap = BitmapUtils.decodeSampleBitmap(AEModule.getContext(), tipsIconPath, Integer.MAX_VALUE, Integer.MAX_VALUE);mTipsImageView.setImageBitmap(bitmap);mImageTipsIsShow = true;} else {mTipsImageView.setVisibility(View.GONE);}mTipsTextView.setText(tips);} else {pagFile = PAGFile.Load(tipsIconPath);tipsPAGView.post(new Runnable() {@Overridepublic void run() {if (pagFile != null) {tipsPAGView.setRepeatCount(-1);tipsPAGView.setComposition(pagFile);tipsPAGView.setProgress(0);tipsPAGView.play();tipsPAGView.setVisibility(View.VISIBLE);}}});}}});}public void tipsNeedHide(String tips, String tipsIcon, int type) {final int tipsType = type;final String tipsIconPath = tipsIcon;mMainThreadHandler.post(new Runnable() {@Overridepublic void run() {if (tipsType == 0) {mTipsContainer.setVisibility(View.GONE);mImageTipsIsShow = false;} else {tipsPAGView.post(new Runnable() {@Overridepublic void run() {tipsPAGView.stop();tipsPAGView.setVisibility(View.GONE);}});}}});}
void setYTDataListener(XmagicApi.XmagicYTDataListener ytDataListener)Configuring the callback for face information and other datapublic interface XmagicYTDataListener {void onYTDataUpdate(String data)}
{"face_info":[{"trace_id":5,"face_256_point":[180.0,112.2,...],"face_256_visible":[0.85,...],"out_of_screen":true,"left_eye_high_vis_ratio:1.0,"right_eye_high_vis_ratio":1.0,"left_eyebrow_high_vis_ratio":1.0,"right_eyebrow_high_vis_ratio":1.0,"mouth_high_vis_ratio":1.0},...]}
Field | Type | Range | Description |
trace_id | int | [1,INF) | Face ID. The same ID points to the same face in the process of continuous stream fetching. |
face_256_point | float | [0,screenWidth] or [0,screenHeight] | 512 values in total for 256 facial keypoints. (0,0) is the top-left corner of the screen. |
face_256_visible | float | [0,1] | Visibility of the 256 facial keypoints. |
out_of_screen | bool | true/false | Whether the face is out of the screen. |
left_eye_high_vis_ratio | float | [0,1] | Percentage of the highly visible points of the left eye. |
right_eye_high_vis_ratio | float | [0,1] | Percentage of the highly visible points of the right eye. |
left_eyebrow_high_vis_ratio | float | [0,1] | Percentage of the highly visible points of the left eyebrow. |
right_eyebrow_high_vis_ratio | float | [0,1] | Percentage of the highly visible points of the right eyebrow. |
mouth_high_vis_ratio | float | [0,1] | Percentage of the highly visible points of the mouth. |
Parameter | Meaning |
XmagicApi.XmagicYTDataListener ytDataListener | Callback function implementation class. |
public interface OnAIDataListener {void onFaceDataUpdated(List<TEFaceData> faceDataList);void onHandDataUpdated(List<TEHandData> handDataList);void onBodyDataUpdated(List<TEBodyData> bodyDataList);void onAIDataUpdated(String jsonString); // This method is a new addition in version 3.0.0, and the data structure aligns with the preceding XmagicYTDataListener interface's data}
onPauseAudio
is called internally.void onPause()
void onResume()
// Refer to the sample code in `TECameraBaseActivity.java`public void onGLContextDestroy() { if (this.mXMagicApi != null) { this.mXMagicApi.onDestroy(); this.mXMagicApi = null; } }
// Render the textureint process(int srcTextureId, int srcTextureWidth, int srcTextureHeight)// Render the bitmapBitmap process(Bitmap bitmap, boolean needReset)
Parameter | Meaning |
int srcTextureId | The texture that needs to be rendered. The type is: OpenGL 2D texture format, and the pixel format is RGBA. |
id int srcTextureWidth | Width of the texture that needs to be rendered. |
int srcTextureHeight | Height of the texture that needs to be rendered. |
Bitmap bitmap | The recommended maximum size is 2160 x 4096. Larger images have poor face recognition results or cannot get faces recognized and are likely to cause OOM problems. Shrink such images first before passing them in. |
boolean needReset | Switch the image. First time using partition. Initial use of animated effects. First-time usage of makeup. For these scenarios, the needReset Setting should be set to `true`. |
void onPauseAudio()
void sensorChanged(SensorEvent event, Sensor accelerometer)
Parameter | Meaning |
SensorEvent event | Event entity class returned by the gyroscope sensor callback function onSensorChanged . |
Sensor accelerometer | Sample G-sensor. |
/*** Check whether the current device supports this material* @param motionResPath The path of the material file* @return true means supported, false means not supported*/boolean isDeviceSupport(String motionResPath)
XmagicProperty.isSupport
field signifies if the resource is serviceable. Based on XmagicProperty.isSupport
, click control can be enacted at the UI level, or it can be directly expunged from the resource list.void isDeviceSupport(List<XmagicProperty<?>> assetsList)
Parameter | Meaning |
List<XmagicProperty<?>> assetsList | List of animated effect materials to be checked. |
Parameter | Meaning |
List<XmagicProperty<?>> assets | List of animated effect resources for which to check the atomic capabilities. |
Map<XmagicProperty<?>,ArrayList<String>>
:Map<String,Boolean> getDeviceAbilities()
Map<String,Boolean>
:boolean isSupportBeauty()
XmagicProperty.isAuth
field. If the isAuth field returns false, the entrances for these features can be concealed in the UI.void isBeautyAuthorized(List<XmagicProperty<?>> properties)
Parameter | Meaning |
List<XmagicProperty<?>> properties | Beauty filters that need to be checked. |
void setXmagicStreamType(int type)
Parameter | Meaning |
int type | Data source type, there are two options: XmagicApi.PROCESS_TYPE_CAMERA_STREAM : camera data source.XmagicApi.PROCESS_TYPE_PICTURE_DATA : Image data source. |
Log.DEBUG.
. When officially released, it must be set to Log.WARN or Log.ERROR
otherwise, an immense amount of logs will adversely affect performance.void boolean setDowngradePerformance()
void boolean enableEnhancedMode()
void exportCurrentTexture(ExportTextureCallback callback)
void setFeatureEnableDisable(String featureName, boolean enable)
Parameter | Meaning |
String featureName | feature Name Values: XmagicConstant.FeatureName.ANIMOJI_52_EXPRESSION facial expressions feature.XmagicConstant.FeatureName.BODY_3D_POINT 3D body data feature.XmagicConstant.FeatureName.HAND_DETECT gesture detection.XmagicConstant.FeatureName.WHITEN_ONLY_SKIN_AREA Brightening only applies to skin.XmagicConstant.FeatureName.SEGMENTATION_SKIN segmentation skin.XmagicConstant.FeatureName.SMART_BEAUTY smart beauty(reducing the intensity of beauty and makeup effects for males and babies). |
boolean enable | "true" indicates enabling a capability, while "false" indicates disabling a capability. Note: If it is in downgrade mode, enabling skin segmentation is not allowed. |
API | Description |
VERSION | The SDK version number can be obtained through XmagicApi.VERSION (Added in V3.5.0) |
Setting libPath. | |
Transfer the content located within the directories Light3DPlugin, LightCore, LightHandPlugin, LightBodyPlugin, LightSegmentPlugin under application assets to your designated directory. | |
Copy the AI model files downloaded by the client to the corresponding folders. | |
get Device level |
new XmagicApi
. data/data/package name/files/xmagic_libs
, the so will be loaded from this directory.static boolean setLibPathAndLoad(String path)
Parameter | Meaning |
String path | so: denotes the path to the library. |
static int addAiModeFilesFromAssets(Context context, String resDir)
Parameter | Meaning |
Context context | applicationcontext. |
String resDir | Designated as the root directory for storing beautification resources, this directory corresponds to the path input when creating the xmagicApi object. |
static int addAiModeFiles(String inputResDir, String resDir)
Parameter | Meaning |
String inputResDir | The folder containing the successfully downloaded model files. |
String resDir | Designated as the root directory for storing beautification resources, this directory corresponds to the path input when creating the xmagicApi object. |
static DeviceLevel getDevicLevel(Context context)
Was this page helpful?