よくある質問
1. How to solve the problem when the Android release package reports errors about missing certain methods?
If you enable compile optimization (setting minifyEnabled to true) when packaging the release, it will trim some code that is not called in the Java layer. This code may possibly be invoked by the native layer, thus causing the
no xxx method exception.If you enabled such compile optimization, you should add these keep rules to avoid trimming xmagic's code:
-keep class com.tencent.xmagic.** { *;}-keep class org.light.** { *;}-keep class org.libpag.** { *;}-keep class org.extra.** { *;}-keep class com.gyailib.**{ *;}-keep class com.tencent.cloud.iai.lib.** { *;}-keep class com.tencent.beacon.** { *;}-keep class com.tencent.qimei.** { *;}-keep class androidx.exifinterface.** { *;}
2. How to resolve the conflict of the gson library when integrating Android SDK into the host project?
Add the following code into the
build.gradle file of the hosting project:Android{configurations {all*.exclude group: 'com.google.code.gson'}}
3. Why did the .so library fail to load on Android with targetSdkVersion 31 or higher? Or why can't GAN-type special effects (e.g., fairy tale face, childhood bubble gum, etc.) be used?
When Android targetSdkVersion is 31 or a later version, locate the
AndroidManifest.xml file under the app module, then insert the following tag within the application tag:<uses-native-libraryandroid:name="libOpenCL.so"android:required="false" />//true indicates that libOpenCL is essential for the current app. Without this library, the system will not allow the app to install。It is not recommended to set it to true, as it may prevent users from installing the app.//false indicates that libOpenCL is not essential for the current app. The app can be installed normally with or without this library. If the device has this library, GAN-type special effects in the Tencent Special Effects SDK (e.g., fairy tale face, comics face) will function normally. If the device does not have this library, GAN-type effects won't work, but it will not affect the use of other features within the SDK.//For information about uses-native-library, please refer to the Android official website: https://developer.android.com/guide/topics/manifest/uses-native-library-element
4. When using the beauty filter, the texture passed is a horizontal texture. How can this be resolved?
You can use the convert method of the tool class
TextureConverter.java in the demo to rotate the texture, convert it to portrait mode, and then pass it to the beauty SDK./*** This method is used for rotating and mirroring 'RGBA' textures. The process is as follows: rotate 'rotation' degrees clockwise (values can be 0, 90, 180, 270), then flip horizontally (flipHorizontal) and vertically (flipVertical).* Use case: Some streaming SDKs return horizontal textures or the orientation of the people in the picture is incorrect, and the Tencent EffectSDK requires that the individuals in the texture are facing the right direction. Therefore, this method can be used to convert the texture.** @param srcID RGBA Texture* @param width Texture Width* @param height Texture Height* @param rotation Degrees of required rotation.* @return Rotated texture. Note: if rotated by 90 or 270 degrees, the width needs to be interchanged.*/public int convert(int srcID, int width, int height, @RotationDegreesValue int rotation, boolean flipVertical, boolean flipHorizontal)
5. When using the beauty filter, the texture passed is an OES texture. How can this be resolved?
You can use the oes2Rgba method of the tool class
TextureConverter.java in the demo to convert the texture into an RGBA texture, and then pass it to the beauty SDK./*** This method is used to convert oes texture to rgba texture** @param srcID oes texture* @param width texture width* @param height texture height* @return RGBA Texture ID*/public int oes2Rgba(int srcID, int width, int height)
6. If you want to use a different version of PAG, how can you solve it? Versions 3.5.0 and above are supported
When integrating the Beauty SDK for customers:
If integrating via Maven, by implementing TencentEffect, PAG can be imported. If you do not want to use the PAG dependency of TencentEffect, you can exclude it and then introduce the version of PAG you need in your app's build.gradle:
implementation ('com.tencent.mediacloud:TencentEffect_S1-04:version number'){exclude group: "com.tencent.tav", module: "libpag"}
If downloading the beauty SDK's aar for manual integration, depend on TencentEffect.aar in the project. This aar does not include PAG, and you also need to add an implementation PAG statement in your app's build.gradle to use PAG:
implementation 'com.tencent.tav:libpag:4.3.33-noffavc'
If you want to dynamically download the PAG's .so files, please go to the PAG official website to find the version you need, download the .aar, rename the .aar to .zip, extract it, remove the .so files, compress the remaining files back into a .zip, and then rename it back to .aar. Finally, import this .aar of PAG without the .so files; the PAG's .so files will then be downloaded dynamically over the internet.
7. Common Android Error Codes
7.1. General Error Codes
Error Code | Meaning | Tips for checking things out |
0 | Success | No issues, the API call succeeded. |
-1 | Unknown error | Fallback error not classified by a specific error code. Please check the detailed logs with the Xmagic / Light tag in Logcat first. |
7.2. Initialization Phase Error Codes
XmagicApi has errors related to its construction and destruction lifecycle.
Error Code | Meaning | Tips for checking things out |
-10000 | SDK has not been initialized yet | You must successfully construct XmagicApi before calling other interfaces. Check whether initialization was missed or has already failed. |
-10010 | so dynamic library failed to load | Check if the APK contains the target ABI's so files, if the abiFilters are configured correctly, and if they have been stripped. If it's a dynamically loaded so, you can ignore it for now. |
-10020 | SDK not authorized | The license failed verification. Make sure the LicenseKey/LicenseUrl has been issued and the package name matches, and check if the network can access the license service. |
-10025 | The resource directory parameter is null or an empty string. | The resDir passed in by the caller is empty. Unlike -10030: this error is due to a parameter issue, so please check the parameter passing logic in the upper layer. |
-10030 | Resource model directory does not exist | The path is valid but can't be found on the disk. Check if the resource pack has been extracted to the expected path or if the path was deleted by the app's cleanup policy. |
-10040 | template.json does not exist | The template.json is missing from the resource directory, check the resource pack for completeness. |
-10050 | Face model file does not exist | Missing face detection model file, please copy the complete model resources again. |
-10060 | Required model files are incomplete | Some model files are missing, usually due to an interrupted resource copy. Try copying the complete resource package again. |
-10070 | Failed to load empty template | Light engine failed to load an empty template. Attaching the log, please contact tech support. |
-10080 | Empty template material returns an error code | Empty template resource error, attached Light layer logs for troubleshooting. |
-10090 | Light engine creation failed | The Light engine can't build, usually along with other C++ layer errors. Check the device's GL environment and permissions. |
-10100 | Unhandled exception thrown during initialization | If a Throwable (including RuntimeException / UnsatisfiedLinkError / OOM, etc.) is thrown inside the init call stack, you need to check the stack info in Logcat. Compared to -1: it went into the catch block as a fallback. |
-10110 | SDK was called after being destroyed | After onDestroy, you shouldn't call XmagicApi methods anymore. Check your lifecycle management to avoid holding onto and using old instances after they're destroyed. |
7.3. setEffect Error Codes
Error code generated when calling setEffect to set materials/filters/beauty effects.
Error Code | Meaning | Tips for checking things out |
-30000 | Effect name is empty | Check the name parameter of setEffect and don't allow an empty string. |
-30010 | Light makeup JSON does not exist | The JSON file is missing in the light makeup resources directory. Check the integrity of the resource package. |
-30020 | Light makeup JSON content is empty | The light makeup JSON file is empty, resend the resource. |
-30030 | GAN beauty filter is not supported | GAN beauty filter requires separate authorization and device support, contact business for confirmation. |
-30040 | Special effects template JSON does not exist | The template.json is missing from the material path, check the resource pack for completeness. |
-30050 | Invalid split type | The passed-in split type enum value is invalid. |
-30060 | Split background type is invalid | The background type enum value for segmentation is invalid. |
-30070 | Split background path is invalid | The path to the background file for splitting is empty or doesn't exist. |
7.4. Background Segmentation Error Codes
Error codes related to video/image background replacement (seg type in setEffect).
Error Code | Meaning | Tips for checking things out |
-20000 | Unauthorized Use of Background Segmentation | Segmentation capability requires separate authorization; please contact our business team to enable it. |
-20010 | The background resource path is empty. | Check the passed background path parameter to ensure it is neither null nor an empty string. |
-20020 | Invalid background resource path. | Path format is invalid or file does not exist; please verify the path spelling and file permissions. |
-20030 | Invalid background type | The background type enumeration was passed incorrectly. Please refer to the background type definition for segmentation in XmagicConstant. |
-20040 | The resolution of the background image exceeds 2160×3840. | Please downsample the image to within 2160×3840 before uploading. |
-20050 | Background image rotation angle is not supported. | Background images do not support rotation angles. If an image has a rotation angle, it can be pre-processed externally beforehand. |
-20060 | Insufficient memory for background images. | If the image is too large and causes an out-of-memory (OOM) error during decoding, compress it before uploading or free up memory and try again. |
-20070 | Background image decoding failed. | The image file is corrupted or in an unsupported format; please try converting it to a standard JPEG or PNG format. |
-20080 | Background video format is not supported. | Only supports common MP4 encoding; please verify the video container and encoding format. |
-20090 | The duration of the background video exceeds 200 seconds. | Please trim the video to within 200 seconds. |
-20100 | Background video parsing error | MediaExtractor parsing failed; please verify the integrity of the video file. |
-20110 | Invalid basic segmentation type | The provided basic segmentation enumeration value is invalid. Please refer to the documentation for correction. |
7.5. Process Phase Error Codes
XmagicApi.process error codes generated during each frame processing stage, encompassing Java layer errors (-40000 ~ -40100) and Light engine C++ layer errors (-2 ~ -1801, which involve material loading, device/version compatibility, authorization, image content legality detection, etc.).
Error Code | Meaning | Tips for checking things out |
-40000 | Invalid input texture dimensions. | The texture width or height is 0 or exceeds the limit; please check the output from the upstream CameraX or TextureView. |
-40010 | Failed to load material by path. | The material file path is incorrect or there is a disk I/O exception. |
-40020 | Asset loading encountered errors. | The material has been loaded but an internal error occurred. Attached is the Light layer log for troubleshooting. |
-40030 | Material update failed. | Failed to update material parameters; please verify the validity of the parameters. |
-40040 | Material updates have been disregarded. | Update not taking effect (e.g., status remains unchanged). Confirm whether a forced refresh is required. |
-40050 | Merge Material Context Error | Internal error in the material merging process; attached logs for troubleshooting. |
-40060 | Failed to merge and add material. | Failed to add sub-material when merging materials. |
-40070 | Failed to merge and export materials. | Merge result export failed. |
-40080 | Camera configuration is empty during rendering. | SDK internal error: cameraConfig is null. |
-40090 | Rendered video output is empty. | The videoOutput within the SDK is null. |
-40100 | The input Bitmap is empty. | Check the input parameters for image beautification. |
-2 | Template JSON path is empty. | Check whether the passed material path parameter is null or an empty string. |
-100 | 3D Engine Resource Not Found | Confirm the integrity of the 3D model files to ensure no files were lost during the copying or extraction process. |
-200 | GAN materials are not supported. | GAN-based materials require separate authorization and device support. Please contact business or technical support to confirm permissions. |
-300 | Device does not support this material. | The minimum device requirements specified for the material exceed those of the current device. Please consider upgrading your device or using a lower-specification version of the material. |
-400 | The template JSON content is empty. | The template.json file is empty; please verify if the asset package is corrupted. |
-500 | The SDK version is lower than the asset version. | Upgrade the SDK to the minimum version required by the material, or use older versions of the material. |
-600 | Headless material is not supported. | Capability for head detection requires authorization and device support; please contact business representatives for confirmation. |
-700 | OpenGL version not supported. | The required OpenGL version for the material exceeds the capabilities of the current device, rendering it unusable on this hardware. |
-800 | JavaScript scripting is not supported. | The current SDK does not have JavaScript capabilities enabled. Please contact the business team to enable it or switch to alternative materials. |
-900 | Components that do not support cropping | The material includes a cropping component, which is not supported by the SDK. |
-1000 | Segmentation not supported. | Segmentation capability is not authorized or the device does not support it; authorization for segmentation needs to be activated. |
-1100 | Filament is not supported. | The current SDK does not include Filament capabilities. Please contact our business team to enable this feature or consider using alternative materials. |
-1200 | Multi-GLContext (shared context) is not supported. | The current device/driver does not support shared GLContext. Please check the rendering thread and EGLContext configuration. |
-1300 | UE rendering failed | UE rendering error detected; please check the Light layer logs and GPU status. |
-1400 | The template JSON is missing the root node. | The structure of the template.json file is invalid. Please request the content provider to fix it. |
-1500 | Filament skeletal animation is not supported. | The skeletal animation feature is not enabled. Please contact our business team or replace the material. |
-1600 | ClipAsset failed to load. | Video editing material failed to load; please verify file integrity and disk permissions. |
-1700 | License verification failed. | Authorization information is invalid or expired. Please verify that the LicenseKey/LicenseUrl is correct, has not expired, and matches the package name. |
-1800 | The input image has been detected as a black screen. | Input texture is completely black; please verify whether the camera is outputting images normally and if the texture binding is correct. |
-1801 | The input image has been detected as a blank screen. | Input texture is entirely white; please check the upstream image source. |
7.6. Historical XMagicError (Deprecated)
The following error codes are only applicable in SDK versions 4.2.0 and earlier, and are reported via the OnXmagicPropertyErrorListener callback. In the current version, these have been replaced by the TEErrorCode series ranging from -20040 to -20090. They are retained solely for compatibility with existing customers.
Error Code | Meaning | Tips for checking things out |
5000 | The resolution of the background image exceeds 2160×3840. | Equivalent to TE_BACKGROUND_IMAGE_RESOLUTION_EXCEEDS_2160_3840 (-20040). |
5001 | Insufficient memory for background images. | Equivalent to TE_BACKGROUND_IMAGE_MEMORY_INSUFFICIENT(-20060). |
5002 | Background video parsing failed. | Equivalent to TE_BACKGROUND_VIDEO_PARSE_EXCEPTION(-20100). |
5003 | The duration of the background video exceeds 200 seconds. | Equivalent to TE_BACKGROUND_VIDEO_OVER_200_SECONDS(-20090). |
5004 | Background video format is not supported. | Equivalent to TE_BACKGROUND_VIDEO_FORMAT_NOT_SUPPORTED(-20080). |
5005 | Background image rotation angle is not supported. | Equivalent to TE_BACKGROUND_IMAGE_ROTATION_ANGLE(-20050). |
