tencent cloud


Last updated: 2022-07-18 10:06:17


    1. Download the SDK and unzip it.
    2. Prepare the following files:
      File TypeDescription
      xmagic-xxx.aarSDK (required)
      ../assets/Algorithm model and material resource package (required)
      ../jniLibs`so` library (required)

    Resource Import


    • Add all the .aar files prepared above to the libs directory of the app project.
    • Copy all the files in assets/ of your SDK package to the ../src/main/assets directory. If there are files in the MotionRes folder of your SDK package, also copy them to the ../src/main/assets directory.
    • Copy the jniLibs folder to the ../src/main/jniLibs directory of the project.

    Method to import

    Open the build.gradle of the app module to add a dependency reference:

      defaultConfig {
          applicationId "Replace it with the package name bound to the `lic`"
          pickFirst '**/libc++_shared.so'
    dependencies {
      compile fileTree(dir: 'libs', include: ['*.jar','*.aar'])// Add `*.aar`

    Package Downsizing: Guide to Dynamically Downloading assets, so, and MotionRes

    To reduce the package size, you can download the assets resources, so library, and animated effect resources MotionRes (unavailable in some basic SDKs) required by the SDK online. After successful download, set the paths of the above files in the SDK.

    We recommend you reuse the download logic of the demo. You can also use your existing download service. For detailed directions of dynamic download, see SDK Package Downsizing (Android).

    Overall Process

    Step 1. Authenticate

    1. Apply for a license and get the License URL and License KEY.


      Under normal circumstances, the authentication process can be completed by connecting your app to the internet one time, so you don't need to put the license file in the assets directory. However, if your app needs to use the SDK features without ever connecting to the internet, you can download the license file and put it in the assets directory. In this case, the license file must be named v_cube.license.

    2. Set the URL and KEY in the initialization code of the relevant business module to trigger the license download. Avoid downloading it just before use. You can also trigger the download in the onCreate method of the Application, but this is not recommended as the download is very likely to fail if there is no network permission or connection.

      // If you just want to trigger the download or update the license but don't care about the authentication result, you can pass in `null` for the fourth parameter.
      TELicenseCheck.getInstance().setXMagicLicense(context, URL, KEY, null);
    3. Authenticate when you need to use the beauty filter feature (for example, in the LaunchActivity.java of the demo):

      // If your `so` library is downloaded from the internet, set the `so` path before calling `TELicenseCheck.getInstance().setTELicense`; otherwise, authentication will fail.
      // XmagicApi.setLibPathAndLoad(validLibsDirectory);
      // If your `so` library is built into the APK package, you don't need to call the above method.
      TELicenseCheck.getInstance().setTELicense(context, URL, KEY, new TELicenseCheckListener() {
              public void onLicenseCheckFinish(int errorCode, String msg) {
                  // Note: This callback is not necessarily in the call thread
                  if (errorCode == TELicenseCheck.ERROR_OK) {
                      // Authentication succeeded
                  } else {
                      // Authentication failed

    Authentication errorCode description:

    Error Code Description
    0 Success.
    -1 The input parameter is invalid; for example, the `URL` or `KEY` is empty.
    -3 Download failed. Check the network settings.
    -4 The Tencent Effect SDK authorization information read from the local system is empty, which may be caused by an I/O failure.
    -5 The content of read VCUBE TEMP license file is empty, which may be caused by an I/O failure.
    -6 The JSON field in the v_cube.license file is incorrect. Contact Tencent Cloud for assistance.
    -7 Signature verification failed. Contact Tencent Cloud for assistance.
    -8 Decryption failed. Contact Tencent Cloud for assistance.
    -9 The JSON field in the `TELicense` field is incorrect. Contact Tencent Cloud for assistance.
    -10 The Tencent Effect SDK authorization information parsed online is empty. Contact Tencent Cloud for assistance.
    -11 Failed to write the Tencent Effect SDK authorization information to the local file, which may be caused by an I/O failure.
    -12 Failed to download and failed to parse local assets.
    -13 Authentication failed. Check whether the `so` file is in the package or the `so` path has been set correctly.
    3004/3005 The authorization is invalid. Contact Tencent Cloud for assistance.
    3015 `Bundle ID` and `Package Name` mismatch. Check whether the `Bundle ID` or `Package Name` used by your app are the same as the ones you applied for and whether the correct license file is used.
    3018 The license file has expired. You need to apply to Tencent Cloud for renewal.
    Other Contact Tencent Cloud for assistance.

    Step 2. Copy resources

    1. If your resource files are built into the assets directory, you need to copy them to the app's private directory before use. You can copy them in advance or in the callback of successful authentication in the previous step. The sample code is in the LaunchActivity.java of the demo.

      XmagicResParser.setResPath(new File(getFilesDir(), "xmagic").getAbsolutePath());
      // Copy the resource files to the private directory, which only need to be copied once
    2. If your resource files are downloaded dynamically from the internet, after the download succeeds, you need to set the resource file path. The sample code is in the LaunchActivity.java of the demo.

      XmagicResParser.setResPath(local path of downloaded resource files);

    Step 3. Initialize and use the SDK

    The following is the lifecycle of using Tencent Effect SDK:

    1. Build the beauty filter UI data as instructed in the XmagicResParser.java,XmagicUIProperty.java,XmagicPanelDataManager.java code of the demo project.

    2. Add the GLSurfaceView to the preview layout.

      android:layout_height="match_parent" />
    3. (Optional) Quickly implement the camera feature.
      Copy the com.tencent.demo.camera directory from the demo project to the project. Use the PreviewMgr class to quickly implement the camera feature. For more information, see MainActivity.java of the demo project.

      // Initialize the camera
      mPreviewMgr = new PreviewMgr();
      // Pass the `GlSurfaceView` example of the layout into the camera tool class
      // Register the callback function to preview texture data
      mPreviewMgr.setCustomTextureProcessor((textureId, textureWidth, textureHeight) -> {
      if (mXmagicApi == null) {
           return textureId;
      // Call the beauty filter SDK for rendering
      int outTexture = mXmagicApi.process(textureId, textureWidth, textureHeight);
      return outTexture;
      // Enable the camera in the `onResume` method of `Activity`
      mPreviewMgr.onResume(this, 1280, 720);
    1. Initialize the beauty filter SDK. We recommend you put it in the onResume() method of Activity.
      mXmagicApi = new XmagicApi(this, XmagicResParser.getResPath(),new XmagicApi.OnXmagicPropertyErrorListener()); 
    • Parameters

      Context contextContext
      String resDirResource file directory as detailed in Step 2
      OnXmagicPropertyErrorListener errorListenerCallback function implementation class
    • Response
      Error codes and descriptions:

      Error CodeDescription
      -1An unknown error occurred.
      -100Failed to initialize the 3D SDK resources.
      -200GAN materials are not supported.
      -300This material component is not supported by the device.
      -400The template JSON content is empty.
      -500The SDK version is too low.
      -600Keying is not supported.
      -700OpenGL is not supported.
      -800The script is not supported.
      5000The resolution of the background image to be keyed exceeds 2160*3840.
      5001The memory required by background image keying is insufficient.
      5002Failed to parse the background video to be keyed.
      5003The background video to be keyed exceeds 200 seconds.
      5004The format of the background video to be keyed is not supported.
    1. Add the callback function for material prompt (method callbacks may run in child threads). Some materials will prompt the user to nod, stretch out their palms, or make a finger heart, and this callback is used to display the prompts.

      mXmagicApi.setTipsListener(new XmagicTipsListener() {
      final XmagicToast mToast = new XmagicToast();
      public void tipsNeedShow(String tips, String tipsIcon, int type, int duration) {
       mToast.show(MainActivity.this, tips, duration);
      public void tipsNeedHide(String tips, String tipsIcon, int type) {
    2. The beauty filter SDK processes each frame of data and returns the processing results.

      int outTexture = mXmagicApi.process(textureId, textureWidth, textureHeight);
    3. Update the value of the beauty filter effect of a specified type.

      // Available attributes of the input parameters can be obtained from `XmagicResParser.parseRes()`
      mXmagicApi.updateProperty(XmagicProperty<?> p);
    4. Pause the beauty filter SDK. We recommend you bind it to the onPause() lifecycle of Activity.

      // When called upon `onPause` of `Activity`, it needs to be called in the `OpenGL` thread
    5. Release the beauty filter SDK. We recommend you bind it to the onDestroy() lifecycle of Activity.

      // Note that this method needs to be called in the GL thread
    Contact Us

    Contact our sales team or business advisors to help your business.

    Technical Support

    Open a ticket if you're looking for further assistance. Our Ticket is 7x24 avaliable.

    7x24 Phone Support