Avatar APIs
SDK Integration
For how to download and integrate the SDK, how to set the license, as well as how to run a demo project, see Integrating Tencent Effect SDK (Android).
Copying the Avatar Materials
We offer multiple sets of face customization and dress-up materials, which can be found in the
MotionRes/avatarRes
directory in the SDK package after decompression. Like other animated effect materials, you need to copy them to the assets
directory of your project.
Avatar Customization and SDK APIs
Face customization process | Photo-based face customization process |
| |
The section below offers descriptions of the APIs of
XMagicApi
, including the APIs for data loading, avatar customization, and photo-based avatar customization.1. Load the avatar materials (loadAvatar
)
public void loadAvatar(XmagicProperty<?> property, UpdatePropertyListener updatePropertyListener)
The avatar materials are loaded in the same way as other animated effect materials. The
loadAvatar
API is equivalent to the updateProperty API.2. Load the avatar source data (getAvatarConfig
)
public static Map<String,List<AvatarData>> getAvatarConfig(String avatarResPath, String savedAvatarConfigs)
Input parameters:
avatarResPath: The absolute path of the avatar materials on the user's mobile device, such as
/data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624
.savedAvatarConfigs: The avatar configuration data (a JSON string) saved from the last time the user customized an avatar. If an avatar is customized for the first time or no configuration data is saved, pass in
null
.Output parameters:
This API returns a map, in which
key
corresponds to category
and value
corresponds to the data of the category. For details, see the AvatarCategory
class. After the application layer gets the map, display the data on the UI as needed.3. Customize the face and dress up (updateAvatar
)
public void updateAvatar(List<AvatarData> avatarDataList, UpdateAvatarConfigListener upDataAvatarConfigListener)
When this API is called, the avatar preview will be updated in real time. Each
AvatarData
object corresponds to a configuration (such as changing the hairstyle). You can pass multiple AvatarData
objects to an API call to edit multiple aspects of an avatar, for example, change the hairstyle and hair color. The API will validate the AvatarData
objects passed in. If an object is valid, it will be passed to the SDK; if not, a callback will be sent.For example, if an
AvatarData
object is passed in to change the hairstyle, but the hair model file (specified by value
in AvatarData
) cannot be found on the local device, the AvatarData
object will be considered invalid.Also, if an
AvatarData
object is passed in to change the iris image, but the image file (specified by value
in AvatarData
) cannot be found on the local device, the AvatarData
object will be considered invalid.4. Export avatar settings (exportAvatar
)
public static String exportAvatar(List<AvatarData> avatarDataList)
When the user edits their avatar, the value of
selected
or shape change values in AvatarData
will change. After editing, a new AvatarData
list will be generated and can be exported as a JSON string. You can save it locally or upload it to the server.
The string is exported for the following purposes:The next time you call
loadAvatar
of XMagicApi
to load the avatar materials, you need to set customConfigs
of XMagicProperty
to the JSON string so that the preview will remember the avatar settings from the last time.Also, you need to pass in this JSON string when you call
getAllAvatarData
to update selected
and the shape values in the avatar source data.5. Customize an avatar based on a photo (createAvatarByPhoto
)
For this API to work, the SDK must be connected to the internet.
public void createAvatarByPhoto(String photoPath, List<String> avatarResPaths, boolean isMale,final FaceAttributeListener faceAttributeListener)
photoPath: The photo path. Make sure the face is in the center of the photo. Ideally, the photo should include only one face. If there are multiple, the SDK will select one randomly. To ensure the recognition results, the short side of the photo should preferably be longer than 500 px.
avatarResPaths: You can pass in multiple sets of avatar materials, and the SDK will select the most suitable set based on the photo analysis result.
Note:
Currently, only one set of materials is supported. If multiple sets are passed in, the SDK will use the first one.
isMale: Whether the person is male. Set to true for male and false for female.
faceAttributeListener: If customization fails,
void onError(int errCode, String msg)
will be returned; if it succeeds, void onFinish(String matchedResPath, String srcData)
will be returned, in which the first parameter indicates the path of the matched avatar materials, and the second is the matching result (same as the return value of exportAvatar
).The error codes of
onError
are defined in FaceAttributeHelper.java
:public static final int ERROR_NO_AUTH = 1;// Insufficient permission.public static final int ERROR_RES_INVALID = 5;// The avatar material path passed in is invalid.public static final int ERROR_PHOTO_INVALID = 10;// Failed to read the photo.public static final int ERROR_NETWORK_REQUEST_FAILED = 20;// Failed to connect to the internet.public static final int ERROR_DATA_PARSE_FAILED = 30;// Failed to parse the data returned from the network.public static final int ERROR_ANALYZE_FAILED = 40;// Failed to recognize the face.public static final int ERROR_AVATAR_SOURCE_DATA_EMPTY = 50;// Failed to load the avatar source data.
6. Save the downloaded configuration file (addAvatarResource
)
public static Pair<Integer, List<AvatarData>> addAvatarResource(String resourceRootPath, String category, String zipFilePath)
This API is used if avatar materials are downloaded dynamically. For example, suppose you offer 10 hairstyles and one of them is dynamically downloaded to a device. You need to call this API to pass the path of the downloaded ZIP file to the SDK. The SDK will parse the file and save it to the folder of the corresponding category. When you call
getAvatarConfig
the next time, the SDK will return the newly added data.
Parameters:resourceRootPath: The root directory of the avatar materials, such as
/data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624
.category: The category of the downloaded material.
zipFilePath: The path of the downloaded ZIP file.
The API returns
Pair<Integer, List<AvatarData>>
, where pair.first
is the error code, and pair.second
is the newly added data.The error codes are as follows:
public interface AvatarActionErrorCode {int OK = 0;int ADD_AVATAR_RES_INVALID_PARAMS = 1000;int ADD_AVATAR_RES_ROOT_RESOURCE_NOT_EXIST = 1001;int ADD_AVATAR_RES_ZIP_FILE_NOT_EXIST = 1002;int ADD_AVATAR_RES_UNZIP_FILE_FAILED = 1003;int ADD_AVATAR_RES_COPY_FILE_FAILED = 1004;}
7. Call AvatarData
The
AvatarData
class is at the core of the above APIs. AvatarData
contains the following fields:public class AvatarData {/*** The selector data. For example, for glasses, different types of glasses are offered, and only one can be selected.*/public static final int TYPE_SELECTOR = 0;/*** The slider data, such as cheek width.*/public static final int TYPE_SLIDER = 1;// The category, such as face shape and eye adjustment. Standard categories are defined in `AvatarCategory.java`. If they cannot meet your requirements, you can customize a category (make sure it’s not the same as an existing one).// This field cannot be empty.public String category;// The ID of an avatar configuration item.// For example, each type of glasses has a unique ID. So does each adjustment item.// This field cannot be empty.public String id;// `TYPE_SELECTOR` or `TYPE_SLIDER`public int type;// If `type` is `TYPE_SELECTOR`, this field indicates whether the item is selected.public boolean selected = false;// Each icon or adjustment item has three aspects of configuration details:public String entityName;public String action;public JsonObject value;}
An
AvatarData
object is the smallest unit of configuration, for example, hairstyle change or cheek adjustment.Hairstyle change | Cheek adjustment |
| |
If an item is the selector type, configure it by changing the value of
selected
in AvatarData
. For example, suppose there are four types of glasses: A, B, C, and D. If the user selects A, set selected
of A to true
and that of B, C, and D to false
. If the user selects B, set selected
of B to true
and that of A, C, and D to false
.If an item is the slider type, configure it by changing
value
in AvatarData
. The value
field is a JSON object that includes multiple key-value pairs. Set the value
of a key-value pair to the slider value.8. Get the avatar animation data (getAvatarAnimations
)
public static List<AvatarAnimation> getAvatarAnimations(String avatarResPath)
Input parameter: avatarResPath
The absolute path of the avatar materials on the user's mobile device, such as
/data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624
.Output parameter: All animation resource data is returned in a list. For more information, see the
AvatarAnimation
class.9. Save the downloaded animation configuration file (addAvatarAnimation
)
public static Pair<Integer, List<AvatarAnimation>> addAvatarAnimation(String avatarResPath, String zipFilePath)
This API is used if avatar animation materials are downloaded dynamically. For example, suppose you offer one animation and it is dynamically downloaded to a device. You need to call this API to pass the path of the downloaded ZIP file to the SDK. The SDK will parse the file and save it to the folder of the corresponding animation resource. When you call
getAvatarAnimations
the next time, the SDK will return the newly added data.
Parameters:avatarResPath: The root directory of the avatar materials, such as
/data/data/com.tencent.pitumotiondemo.effects/files/xmagic/MotionRes/avatarRes/animoji_0624
.zipFilePath: The path of the downloaded ZIP file.
The API returns
Pair<Integer, List<
AvatarAnimation>>
, where pair.first
is the error code, and pair.second
is the newly added data.The error codes are as follows:
public interface AvatarActionErrorCode {int OK = 0;int ADD_AVATAR_RES_INVALID_PARAMS = 1000;int ADD_AVATAR_RES_ROOT_RESOURCE_NOT_EXIST = 1001;int ADD_AVATAR_RES_ZIP_FILE_NOT_EXIST = 1002;int ADD_AVATAR_RES_UNZIP_FILE_FAILED = 1003;int ADD_AVATAR_RES_COPY_FILE_FAILED = 1004;int ADD_AVATAR_RES_PARSE_JSON_FILE_FAILED = 1005;}
10. Play back/Pause the avatar animation (playAvatarAnimation
)
public void playAvatarAnimation(AnimationPlayConfig animationConfig)
Input parameters:
AnimationPlayConfig: Animation playback information class. This class mainly contains the following information.
public class AnimationPlayConfig {// The action description. It specifies whether to play back or pause the animation.public static final String ACTION_PLAY = "play";public static final String ACTION_PAUSE = "pause";public static final String ACTION_RESUME = "resume";public static final String ACTION_STOP = "stop";public String entityName;/** * The path of the animation folder. It can be the relative path to the material root directory, such as `custom_configs/animations/Waving`./** It can also be the relative path on the mobile phone, such as `/data/data/xxx/xxx/Waving`.*/public String animPath;// The value can be `ACTION_PLAY`, `ACTION_PAUSE`, `ACTION_RESUME`, or `ACTION_STOP`.public String action;/** * The animation name */public String animName;/** * The number of loops. `-1` indicates an infinite loop.*/public int loopCount = -1;/** * The playback start position of the animation in μs */public long startPositionUs = 0;}
More About AvatarData
The three key fields of
AvatarData
are entityName
, action
, and value
, whose values are automatically entered when the SDK parses the configuration data. In most cases, you won’t need to deal with the details of these three fields. However, for slider data, you need to parse the key-value pairs in the value
field and configure them based on the slider values set on the UI.
Here, the AvatarData
element consists of the entityName, action, and value fields.entityName
entityName
specifies which part of an avatar is to be edited, for example, face, eyes, hair, shirt, or shoes.action
and value
The
action
field indicates the action to be performed on entityName
. Five action
options are defined in AvatarAction.java
in the SDK, which are detailed below:action | Description | Requirements for value |
changeColor | Changes the color of the current material. Color attributes include basic color and emission color. | This field is of JsonObject type and is required. It is generated automatically by the material customization tool. |
changeTexture | Modifies the maps of the current material, including color texture map, metal/roughness texture map, ambient occlusion (AO) map, normal map, and emission map. | This field is of JsonObject type and is required. It is generated automatically by the material customization tool. |
shapeValue | Modifies the shape change value of blendShape . This parameter is generally used for slight adjustment of detailed facial features. | This field is of JsonObject type and is required. Its key is the shape change name and value is of float type. It is generated automatically by the material customization tool. |
replace | Replaces a submodel, for example, glasses, hairstyles, or clothes. | value must be a JSON object that describes the 3D transformation information, model path, and material path of the new submodel. It is generated automatically by the material customization tool. To hide a submodel, set it to null . |
basicTransform | Adjusts the position, rotation, and scaling settings. This field is generally used to adjust the camera distance and angle so as to switch between the full and half-length views of the model. | This field is of JsonObject type and is required. It is generated automatically by the material customization tool. |
Configuring Avatar Customization Data
Avatar configurations are stored in the
resources
folder (in material/custom_configs/resources
):
In most cases, the configuration files are generated automatically and don't need to be configured manually.
To automatically generate the configurations, design your materials using Tencent Effect Studio according to our standards and run the "resource_generator_gui" app we provide (only available on macOS currently). For details, see Design Specifications.
- SDK Integration
- Copying the Avatar Materials
- Avatar Customization and SDK APIs
- 1. Load the avatar materials (loadAvatar)
- 2. Load the avatar source data (getAvatarConfig)
- 3. Customize the face and dress up (updateAvatar)
- 4. Export avatar settings (exportAvatar)
- 5. Customize an avatar based on a photo (createAvatarByPhoto)
- 6. Save the downloaded configuration file (addAvatarResource)
- 7. Call AvatarData
- 8. Get the avatar animation data (getAvatarAnimations)
- 9. Save the downloaded animation configuration file (addAvatarAnimation)
- 10. Play back/Pause the avatar animation (playAvatarAnimation)
- More About AvatarData
- Configuring Avatar Customization Data