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. | |
Resumes rendering. Call this API when the page is visible. | |
Pauses rendering. Call this API when the page is invisible. | |
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) |
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 licensevoid setLicense(String licenseKey, String licenseUrl, LicenseCheckListener checkListener);//The callback of the authorization resulttypedef 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
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 objecttypedef 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 dataabstract class XmagicYTDataListener {// YouTu AI datavoid 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<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<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.
- Public Member APIs
- API Description
- setResourcePath (V0.3.5.0)
- initXmagic
- setLicense
- setXmagicLogLevel
- onResume
- onPause
- enableEnhancedMode
- setDowngradePerformance(V0.3.1.1)
- setAudioMute(V0.3.1.1)
- setFeatureEnableDisable(V0.3.1.1)
- updateProperty (This interface has been deprecated)
- setEffect(V0.3.5.0)
- setOnCreateXmagicApiErrorListener
- setTipsListener
- setYTDataListener
- setAIDataListener
- isBeautyAuthorized (This interface has been deprecated)
- isSupportBeauty
- getDeviceAbilities
- isDeviceSupport (This interface has been deprecated)
- isDeviceSupportMotion (V0.3.5.0)
- getPropertyRequiredAbilities (This interface has been deprecated)