Flutter

TencentEffectApi is the core API class of the Tencent Effect Flutter SDK. It offers capabilities including setting the effect strength and applying animated effects.

Public Member APIs

API
Description
Set the local storage path of beauty resources (V0.3.5.0 version)
Initializes data. You need to call this API before using the Tencent Effect SDK(V0.3.1.1 and earlier).
Configures the license.
Sets the log level of the SDK. We recommend you set it to Log.DEBUG for debugging and Log.WARN for official release. If you set it to Log.DEBUG in a production environment, the output of a large amount of log data may affect your application’s performance.
onResume
Resumes rendering. Call this API when the page is visible.
onPause
Pauses rendering. Call this API when the page is invisible.
enable enhanced mode,for specific instructions, please refer to the enhanced mode usage guide.
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.
set mute(Because some stickers have sound
enable or disable the feature
@Deprecated
Updates an effect property. This API can be called in any thread.(This interface has been deprecated)
setEffect
Updates an effect property(V0.3.5.0 Version
Configures the callback for creating an effect object. The callback will be triggered if an error occurs.
Configures the callback for animated effect tips. The tips can be displayed on the UI.
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).
Configures the callback of face, gesture, and body detection results.
@Deprecated
Checks whether the current license supports a particular type of effects. This API can only check the authorization of BEAUTY and BODY_BEAUTY effects. The result returned determines the value of XmagicProperty.isAuth.(This interface has been deprecated)
Checks whether the current device supports effects (OpenGL 3.0).
Gets a list of Tencent Effect capabilities supported by the current device.
@Deprecated
Checks whether a list of animated effect resources are supported. The result is indicated by XmagicProperty.isSupport. For unsupported resources, you can either disable tapping on the UI or delete them from the resource list.(This interface has been deprecated)
Check if the current device supports this material.
@Deprecated
Gets the Tencent Effect capabilities used by different animated effect resources.(This interface has been deprecated)

API Description

setResourcePath (V0.3.5.0)

To set the local path for storing beauty resources
/// Set the local path for storing beauty resources. This method must be called before using beauty effects.
/// Added in v0.3.5.0. void setResourcePath(String xmagicResDir);

Parameters

Parameter
Description
String xmagicResDir
The resource directory.

initXmagic

Initialize beauty data. In versions prior to V0.3.1.1, this method must be called before using beauty effects. Starting from V0.3.5.0, this method only needs to be called once per version, and the setResourcePath method must be called before this method to set the resource path. In V0.3.5.0, the previous xmagicResDir parameter has been removed. Please refer to the latest demo for more information.
V0.3.5.0 :
void initXmagic(InitXmagicCallBack callBack);

typedef InitXmagicCallBack = void Function(bool reslut);
V0.3.1.1 and earlier :
This API is used to initialize the Tencent Effect SDK.
void initXmagic(String xmagicResDir,InitXmagicCallBack callBack);

typedef InitXmagicCallBack = void Function(bool reslut);

Parameters

Parameter
Description
String xmagicResDir
The resource directory.
InitXmagicCallBack callBack
The initialization callback.

setLicense

This API is used to set the license.
///Set the Tencent Effect license
void setLicense(String licenseKey, String licenseUrl, LicenseCheckListener checkListener);
//The callback of the authorization result
typedef LicenseCheckListener = void Function(int errorCode, String msg);

Parameters

Parameter
Description
String licenseKey
The license key.
String licenseUrl
The license URL.
LicenseCheckListener checkListener
The callback of the authorization result.

setXmagicLogLevel

This API is used to set the log level of the SDK.
void setXmagicLogLevel(int logLevel);

Parameters

Parameter
Description
int logLevel
You can set the log level using a type defined for LogLevel.

onResume

This API is used to resume effect rendering.
void onResume();

onPause

This API is used to pause effect rendering.
void onPause();

enableEnhancedMode

enable enhanced mode,for specific instructions, please refer to the enhanced mode usage guide.
void enableEnhancedMode();

setDowngradePerformance(V0.3.1.1)

Invoke this method to enable the high-performance pattern
void setDowngradePerformance();

setAudioMute(V0.3.1.1)

To set the mute status, the parameter "true" represents mute, while "false" represents unmute.
/// Is the background music muted? void setAudioMute(bool isMute);

setFeatureEnableDisable(V0.3.1.1)

enable or disable one feature
/// enable or disable one feature void setFeatureEnableDisable(String featureName, bool enable);

Parameter

Parameter
Meaning
String featureName
feature Name
Values:
"ai.3dmmV2.enable" facial expressions feature.
"ai.body3dpoint.enable" 3D body data feature.
"ai.hand.enable" gesture detection.
"beauty.onlyWhitenSkin" Brightening only applies to skin.
"ai.segmentation.skin.enable" segmentation skin.
"auto_beauty_switch" 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.

updateProperty (This interface has been deprecated)

This API is used to set an effect value, an animated effect, or a filter. You can call it in any thread.
void updateProperty(XmagicProperty xmagicProperty);

Parameters

Parameter
Description
XmagicProperty xmagicProperty
The object of the effect property.

setEffect(V0.3.5.0)

You can set beautification, filters, makeup, stickers, and segmentation effects. This can be done from any thread. Please refer to the specific parameters for more detailsBeautification Parameter Table
///update beautification parameters void setEffect(String effectName,int effectValue,String? resourcePath,Map<String,String>? extraInfo);

setOnCreateXmagicApiErrorListener

This API is used to configure the callback for errors for the creation of an effect object.
void setOnCreateXmagicApiErrorListener(OnCreateXmagicApiErrorListener? errorListener);
/// The callback for errors for the creation of an effect object
typedef OnCreateXmagicApiErrorListener = void Function(String errorMsg, int code);

Parameters

Parameter
Description
OnCreateXmagicApiErrorListener? errorListener
The callback for errors for the creation of an effect object.
Error codes:
Error Code
Description
-1
Unknown error.
-100
Failed to initialize the 3D engine.
-200
GAN materials are not supported.
-300
The device does not support this material component.
-400
The JSON template is empty.
-500
The SDK version is too old.
-600
Keying is not supported.
-700
OpenGL is not supported.
-800
The script is not supported.
5000
The resolution of the video to be keyed exceeds 2160 x 3840.
5001
Insufficient memory for keying.
5002
Failed to parse the video to be keyed.
5003
The video to be keyed is longer than 200 seconds.
5004
Unsupported video format for keying.

setTipsListener

This API is used to configure the callback for animated effect tips. The tips can be displayed on the UI, asking users to nod, show their palms, or make finger hearts.
void setTipsListener(XmagicTipsListener? xmagicTipsListener);

abstract class XmagicTipsListener {
/// Show the tip
/// @param tips: The content of the tip (string).
/// @param tipsIcon: The icon for the tip.
/// @param type: The display type. If it is set to `0`, both the tip string and icon will be displayed. If it is set to `1`, only the icon will be displayed for PAG materials.
/// @param duration: How long (milliseconds) to show the tip.
void tipsNeedShow(String tips, String tipsIcon, int type, int duration);

/// *
/// Hide the tip
/// @param tips: The content of the tip (string).
/// @param tipsIcon: The icon for the tip.
/// @param type: The display type. If it is set to `0`, both the tip string and icon will be displayed. If it is set to `1`, only the icon will be displayed for PAG materials.
void tipsNeedHide(String tips, String tipsIcon, int type);
}

Parameters

Parameter
Description
XmagicTipsListener xmagicTipsListener
The callback implementation class.

setYTDataListener

This API is used to configure the callback of facial keypoints and other data.
/// Configure the callback of facial keypoints and other data (only available in S1 - 05 and S1 - 06)
void setYTDataListener(XmagicYTDataListener? xmagicYTDataListener);
Configure the callback of facial keypoints and other data

abstract class XmagicYTDataListener {
// YouTu AI data
void onYTDataUpdate(String data);
}
onYTDataUpdate returns a JSON string structure that contains the information of up to 5 faces:
{
"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
},
...
]
}

Fields

Field
Type
Range
Description
trace_id
int
[1,INF)
The face ID. If the faces obtained from a continuous video stream have the same face ID, they belong to the same person.
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]
The visibility of the 256 facial keypoints.
out_of_screen
bool
true/false
Whether only part of the face is captured.
left_eye_high_vis_ratio
float
[0,1]
The percentage of keypoints with high visibility for the left eye.
right_eye_high_vis_ratio
float
[0,1]
The percentage of keypoints with high visibility for the right eye.
left_eyebrow_high_vis_ratio
float
[0,1]
The percentage of keypoints with high visibility for the left eyebrow.
right_eyebrow_high_vis_ratio
float
[0,1]
The percentage of keypoints with high visibility for the right eyebrow.
mouth_high_vis_ratio
float
[0,1]
The percentage of keypoints with high visibility for the mouth.

Parameters

Parameter
Description
XmagicYTDataListener
The callback implementation class.

setAIDataListener

This API is used to configure the callback of face, gesture, and body detection results.
void setAIDataListener(XmagicAIDataListener? aiDataListener);

abstract class XmagicAIDataListener {
void onFaceDataUpdated(String faceDataList);

void onHandDataUpdated(String handDataList);

void onBodyDataUpdated(String bodyDataList);
}

isBeautyAuthorized (This interface has been deprecated)

This API is used to check whether the current license supports a particular type of effects. It can only check the authorization of BEAUTY and BODY_BEAUTY effects. The result returned determines the value of XmagicProperty.isAuth. If isAuth is false, you can disable the corresponding effects on the UI.
Future<List<XmagicProperty>> isBeautyAuthorized(
List<XmagicProperty> properties);

Parameters

Parameter
Description
List<XmagicProperty> properties
The type of effects to check.

isSupportBeauty

This API is used to check whether the current device supports effects (OpenGL 3.0).
Future&lt;bool> isSupportBeauty();

Response

A Boolean value indicating whether effects are supported.

getDeviceAbilities

This API is used to get a list of Tencent Effect capabilities supported by the current device. You can use it together with getPropertyRequiredAbilities.
Future<Map<String, bool>> getDeviceAbilities();

Response

Map<String,Boolean>:
key: The name of a capability (the material name).
value: Whether the current device supports the capability.

isDeviceSupport (This interface has been deprecated)

This API is used to check whether a list of animated effect resources are supported. The result is indicated by XmagicProperty.isSupport. For unsupported resources, you can either disable tapping on the UI or delete them from the resource list.
Future&lt;List<XmagicProperty>> isDeviceSupport(List<XmagicProperty> assetsList);

Parameters

Parameter
Description
List<XmagicProperty> assetsList
A list of animated effect resources to check.

isDeviceSupportMotion (V0.3.5.0)

To check if the current device supports a particular material
Future<bool> isDeviceSupportMotion(String motionResPath);

Parameters

Parameter
Description
motionResPath
the sticker local file path

getPropertyRequiredAbilities (This interface has been deprecated)

This API is used to get the Tencent Effect capabilities used by different animated effect resources. Use case: This API is useful if you have purchased animated effects or made your own animated effect materials. It returns the capabilities each material uses. For example, material 1 uses capabilities A, B, and C, and material 2 relies on capabilities B, C, and D. You can store such information in the server. When a user downloads the two materials from the server, call getDeviceAbilities first to get the capabilities supported by their device. The result is then passed to the server. For example, if a user’s device supports capabilities A, B, and C, but not D, the server will not provide material 2 to the user.
Future<Map<XmagicProperty, List<String>?>> getPropertyRequiredAbilities(
List<XmagicProperty> assetsList);

Parameters

Parameter
Description
List<XmagicProperty> assetsList
A list of the animated effects to check.

Response

Map<XmagicProperty, List<String>?>:
key: The entity class of the animated effect.
value: A list of capabilities used by the effect.