tencent cloud

Feedback

Last updated: 2024-02-19 17:15:02

    SDK Integration Type

    Manual integration(Resource embedding)
    Manual integration(Dynamic download and integration)
    Maven integration

    Download the SDK

    Download the SDK and unzip it. There are slight differences in the resource files in different package bundles. Please refer to the attachment for detailed instructions.
    We recommend that you import the demo project in the package into AndroidStudio and run it to quickly familiarize yourself with the interface usage. Please refer to the demo run guide.

    Integration

    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:
    android{
    ...
    defaultConfig {
    applicationId "Replace it with the package name bound to the `lic`"
    ....
    }
    packagingOptions{
    pickFirst '**/libc++_shared.so'
    }
    }
    
    dependencies {
    ...
    compile fileTree(dir: 'libs', include: ['*.jar','*.aar'])// Add `*.aar`
    }
    Note:
    You also need to add the following dependencies to the project:
    dependencies{
    implementation 'com.google.code.gson:gson:2.8.2'
    // Version 2.6.0 and subsequent versions require addition
    implementation 'androidx.exifinterface:exifinterface:1.3.3'
    //Version 3.5.0 and subsequent versions require addition
    implementation 'com.tencent.tav:libpag:4.3.33-noffavc'
    }

    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 edition SDKs) required by the SDK online. After successful download, set the paths of the above files in the SDK.
    We recommend that you reuse the download logic of the demo. You can also use your existing download service. For detailed directions related to dynamic download, see Reducing SDK Size (Android).
    The Tencent Effect SDK has been released to the mavenCentral repository, and you can configure Gradle to download updates automatically.
    1. Add the Tencent Effect SDK dependencies to dependencies.
    dependencies {
    // For example, the S1-04 edition is as follows:
    implementation 'com.tencent.mediacloud:TencentEffect_S1-04:version name'
    //The version name can be found on the 'Version History' page of the official website, for example, 3.0.0.13.
    //Alternatively, you can use 'latest.release', but please note that this will always keep your SDK up to date, which may not meet your expectations for some versions with significant changes. Please use 'latest.release' with caution.
    
    }
    2. In defaultConfig, specify the CPU architecture to be used by your application.
    defaultConfig {
    ndk {
    abiFilters "armeabi-v7a", "arm64-v8a"
    }
    }
    Note:
    Currently, the Tencent Effect SDK supports armeabi-v7a and arm64-v8a.
    3. Click
    img
    
    Sync Now to automatically download the SDKs and integrate them into your project.
    4. If your SDK edition includes animated effects and filters, you need to download the corresponding SDK package and add the resources for animated effects and filters to the following directories of your project:
    Animated effects: ../assets/MotionRes.
    Filters: ../assets/lut.

    Maven addresses of different editions

    Edition
    Maven Address
    A1 - 01
    implementation 'com.tencent.mediacloud:TencentEffect_A1-01:version name'
    A1 - 02
    implementation 'com.tencent.mediacloud:TencentEffect_A1-02:version name'
    A1 - 03
    implementation 'com.tencent.mediacloud:TencentEffect_A1-03:version name'
    A1 - 04
    implementation 'com.tencent.mediacloud:TencentEffect_A1-04:version name'
    A1 - 05
    implementation 'com.tencent.mediacloud:TencentEffect_A1-05:version name'
    A1 - 06
    implementation 'com.tencent.mediacloud:TencentEffect_A1-06:version name'
    S1 - 00
    implementation 'com.tencent.mediacloud:TencentEffect_S1-00:version name'
    S1 - 01
    implementation 'com.tencent.mediacloud:TencentEffect_S1-01:version name'
    S1 - 02
    implementation 'com.tencent.mediacloud:TencentEffect_S1-02:version name'
    S1 - 03
    implementation 'com.tencent.mediacloud:TencentEffect_S1-03:version name'
    S1 - 04
    implementation 'com.tencent.mediacloud:TencentEffect_S1-04:version name'

    Overall Process

    Step 1. Authenticate

    1. Apply for a license and get the License URL and License KEY as instructed in License Guide.
    Note:
    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. In the initialization code of the relevant module, set the URL and KEY to trigger the license download. Do not download 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 if a network disconnection occurs.
    // 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 TEMenuActivity.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() {
    
    @Override
    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
    Unable to obtain any Tencent Effect authentication information from the local system, which may be caused by an I/O failure.
    -5
    The 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 TELicense 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
    Download failed, 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 and needs to be renewed.
    Others
    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 TEMenuActivity.java of the demo.
    // Assign `resPathSetting` to the `mResPath` variable in the following `copyRes` method
    String resPath = new File(getFilesDir(), AppConfig.getInstance().getBeautyFileDirName()).getAbsolutePath();
    
    
    // Copy resource files to the private directory. It must be performed just once
    // Invocation should be executed in a child thread
    public static boolean copyRes(Context context) {
    if (TextUtils.isEmpty(mResPath)) {
    throw new IllegalStateException("resource path not set, call XmagicResParser.setResPath() first.");
    }
    int addResult = XmagicApi.addAiModeFilesFromAssets(context, mResPath);
    LogUtils.e(TAG, "add ai model files result = " + addResult);
    String lutDirName = "lut";
    boolean result = FileUtil.copyAssets(context, lutDirName, mResPath + "light_material" + File.separator + lutDirName);
    String motionResDirName = "MotionRes";
    boolean result2 = FileUtil.copyAssets(context, motionResDirName, mResPath + motionResDirName);
    return result && result2;
    }
    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 TEMenuActivity.java of the demo.
    mXmagicApi = new XmagicApi(this, local path of downloaded resource files,new XmagicApi.OnXmagicPropertyErrorListener());

    Step 3. Initialize and use the SDK

    The following is the process of using the Tencent Effect SDK:
    1. Constructing Beautification UI Data, refer to the 'tebeautykit' module in the Demo project for guidance. (the code in the com.tencent.effect.beautykit.provider package).
    2. Add the GLCameraView in the demo to the preview layout.
    <com.tencent.demo.camera.camerax.GLCameraXView
    android:id="@+id/te_camera_layout_camerax_view"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    app:back_camera="false"
    app:surface_view="false"
    app:transparent="true" />
    3. (Optional) Quickly implement the camera feature. Copy the com.tencent.demo.camera directory from the demo project to the project. Use the GLCameraXView class to quickly implement the camera feature. For more information, see TECameraActivity.java of the demo project.
    @Override
    public int onCustomProcessTexture(int textureId, int textureWidth, int textureHeight) {
    int resultTextureId = 0;
    if (!isUseTencentEffect) {
    resultTextureId = textureId;
    } else {
    resultTextureId = mXmagicApi.process(textureId, textureWidth, textureHeight);
    }
    return resultTextureId;
    }
    4. Initialize the beauty filter SDK. We recommend that you put it in the onResume() method of Activity.
    //resPath is the path set in the first step of the second stage.
    mXmagicApi = new XmagicApi(this, resPath,new XmagicApi.OnXmagicPropertyErrorListener());
    Parameters
    Parameters
    Description
    Context context
    Context
    String resDir
    Resource file directory as detailed in Step 2.
    OnXmagicPropertyErrorListener errorListener
    Callback function implementation class.
    Response
    For the descriptions of error codes, see API Documentation (Android).
    5. 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();
    @Override
    public void tipsNeedShow(String tips, String tipsIcon, int type, int duration) {
    mToast.show(MainActivity.this, tips, duration);
    }
    
    @Override
    public void tipsNeedHide(String tips, String tipsIcon, int type) {
    mToast.dismiss();
    }
    });
    6. The beauty filter SDK processes each frame of data and returns the processing results.
    int outTexture = mXmagicApi.process(textureId, textureWidth, textureHeight);
    7. Update the value of the beauty filter effect of a specified type.
    For 3.5.0 and later versions, the setEffect method is used. For a detailed explanation of the method, see the API Documentation.
    For 3.3.0 and earlier versions, the updateProperty method is used. For a detailed explanation of the method, refer to the API Documentation.
    //Use this method for the 3.5.0 version and later
    mXmagicApi.setEffect(String effectName, int effectValue, String resourcePath, Map<String, String> extraInfo)
    
    
    // Available attributes of the input parameters can be obtained from `XmagicResParser.parseRes()`
    // Use this method for version 3.3.0 and earlier
    mXmagicApi.updateProperty(XmagicProperty<?> p);
    8. Recover audio effects, it is recommended to call in the Activity's onResume() method.
    // Restore the sound effects in the beauty, some material contain sound effects
    mXmagicApi.onResume();
    9. Pause the audio effects, recommend invoking the onPause() method in Activity.
    // Pause the sound of the material, regardless of whether the material contains audio effects
    mXmagicApi.onPause();
    10. To release the beauty SDK, it needs to be called in the GL thread.
    // Note that this method needs to be called in the GL thread
    mXmagicApi.onDestroy()

    Step 4. Configure obfuscation

    If you have enabled compilation optimization (by setting minifyEnabled to true) when printing the release package, some code that is not called at the Java layer will be trimmed out and may be called at the native layer, causing a no xxx method exception.
    If you have enabled such compilation optimization, add the following keep rules to prevent Xmagic code from being trimmed out:
    -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.** { *;}

    Attachment (SDK file structure):

    Note:
    This table lists all the files used by the SDK. Some files may not be included in your package, but this does not affect the functionality of the package.
    File Type
    Description
    assets
    audio2exp
    Avatar: A virtual human voice-driven model. If you do not use this feature, you do not need this model.
    benchmark
    Device compatibility usage.
    Light3DPlugin
    Usage of 3D stickers.
    LightBodyPlugin
    LightBody3DModel.bundle
    Usage of 3D skeletal points for human body.
    LightBodyModel.bundle
    Usage of body shaping feature.
    LightCore
    SDK core model resources.
    LightHandPlugin
    Usage of gesture stickers and hand tracking capabilities.
    LightSegmentPlugin
    Usage of background segmentation capabilities.
    lut
    Free filter resources.
    demo_xxx_android_xxxx
    
    Demo project.
    jniLibs
    libace_zplan.so
    3D engine library.
    libaudio2exp.so
    Avatar virtual human voice driver library. If this feature is not being used, then this library is not necessary.
    libc++_shared.so
    libc++_shared.so is a shared library for the C++ standard library, which provides a set of functions and classes to support the development and execution of C++ programs. It is widely used in the Android system and is an important component of C++ applications and libraries. If your project already has a C++ shared library, you can keep only one copy.
    liblight-sdk.so
    Light SDK core library.
    libpag.so
    Animation file library that Light SDK depends on.
    libtecodec.so
    Encoding and decoding library that Light SDK depends on.
    libv8jni.so
    Library used for parsing JavaScript that Light SDK depends on.
    libYTCommonXMagic.so
    license authentication usage
    libs
    xmagic-xxxx.aar
    AAR file of beauty SDK
    MotionRes
    2dMotionRes
    Sticker 2D
    3dMotionRes
    Sticker 3D
    avatarRes
    Avatar Resource
    ganMotionRes
    Sticker gan
    handMotionRes
    Sticker hand
    makeupRes
    Makeup res
    segmentMotionRes
    Background segmentation res
    unity
    aar
    Bridge AAR required for Unity project
    module
    Original project of the bridge AAR
    
    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