tencent cloud

Mobile Terminal Android SDK Integration
Download PDF
Last updated:2025-11-05 10:04:05
Mobile Terminal Android SDK Integration
Last updated: 2025-11-05 10:04:05
Download PDF

Software and Hardware Requirements

System
Support Android 6 and later systems
Processor Architecture
Support arm64-v8a CPU architecture
Processor Performance Requirements
Support Qualcomm Snapdragon 8+, HiSilicon Kirin 980+, and MediaTek mt6878+
Development IDE
Android Studio
Memory Requirements
More than 500 MB

Package Description

The model package is divided into Base Model package and Character Model package. The detailed introduction is as follows:

Base Model Package

The Base Model package is irrelevant to the image and is required for running 2D endpoint rendering. The model package directory is named: common_model/. If there are multiple character models, they can share one Base Model package.

Character Image Pack

The Character Model package contains image data and inference model for driving 2D Digital Human. Each character has one model package. To change the image, just load different character model packages. The model package directory is named: human_xxxxx_540p_v2/, where xxxxx is the name of the custom avatar.
The current SDK package includes a public image with the package name: human_bingwen_540p_v3, which can be used directly.
Note:
SDK Integration requires placing the model package into the App sandbox. When initializing the SDK, pass the absolute paths of the two models as an argument to the SDK.
The model package can be dynamically downloaded. The logic for dynamic download and update needs to be implemented by the connected App.

Digital Human Client-Side Rendering SDK Integration

The calling process of Digital Human SDK is as follows:


Adding an aar Package and Third-Party Library

Guide the aar package of Digital Human rendering SDK into the project. The filename is: virtualhuman_2d_sdk_v202502071637.aar
Since OkHttp library is used, it is necessary to add the OkHttp dependency to the build.gradle (Module:app) file.
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.aar'])
    
    // add dependency
    implementation 'com.squareup.okhttp3:okhttp:4.9.0'
    implementation 'com.parse.bolts:bolts-tasks:1.4.0'
}

Setting Log Level and Callback Function

// Set log level
VirtualHumanController.setLogLevel(Int level);
// Set log callback
VirtualHumanController.setLogCallback(IDataCallback logCallback);
Log Level
Log level
level Flag
Close logs
0
Error logs
1
Warning logs
2
Log information
3
Debug Logs
4
Trace logs
5
IDataCallbackCallback Parameters
Parameter Name
Data Type
Parameter Type
Description
level
int
Required or Not
Log level
logMsg
String
Required or Not
Log information

Creating a Digital Human Controller (VirtualHumanController)

VirtualHumanParam vhParam = new VirtualHumanParam();
// local model path
vhParam.humanModelPath = "/data/user/0/com.tencent.virtualhuman_2d_demo/files/test_model/human_model";
// local model path
vhParam.commonModelPath = "/data/user/0/com.tencent.virtualhuman_2d_demo/files/test_model/common_model";
vhParam.appId = "License appId";
vhParam.secretKey = "License secretKey";
vhParam.deviceName = "Device tag, recommended to use nameplate info";

// error callback function
vhParam.errorCallback = (code, message) -> {
    Log.d(TAG, "Code: " + code + ", Message: " + message);
};
// event callback function
vhParam.eventCallback = (code, message) -> {
    Log.d(TAG, "Code: " + code + ", Message: " + message);
};
controller = new VirtualHumanController(this, vhParam);
int ret = controller.initHuman();
if (ret == 0) {
    controller.setRenderView(virtualHumanView);// set rendering view
    controller.startHuman();// start rendering
} else {
    Log.i(TAG, "init fail=" + ret);
}
VirtualHumanParam parameter description
Parameter Name
Data Type
Required
Description
humanModelPath
String
Yes
local model path
commonModelPath
String
Yes
local general model path
appId
String
Yes
AppId in License
secretKey
String
Yes
SecretKey in License
eventCallback
IDataCallback
No
event callback function event notification
eventCallback
IDataCallback
Yes
exception callback function, monitor exception messages
deviceName
String
No
device alias, recommended to use nameplate info
IDataCallback
Parameter Name
Data Type
Required
Description
code
int
Yes
code
message
String
Yes
Information
Error list (will be continuously supplemented)
Error No.
Error Message
20001
Algorithm model initialization error.
20010
Authentication failed.
20012
Insufficient device performance, cannot operate smoothly.
Information list
Error No.
Error Message
10001
Broadcast started.
10002
Broadcast ended.
10003
controller.appendAudioData('audio data', boolean, 'tag').
When calling appendAudioData with a tag parameter, 10003 represents the start event for playing this audio data, and the tag is returned in the callback event.
10004
controller.appendAudioData('audio data', boolean, 'tag').
When calling appendAudioData with a tag parameter, 10003 represents the end event for playing this audio data, and the tag is returned in the callback event.
10005
The callback event for the first-frame image rendering of Digital Human.

4. Creating Digital Human View (VirtualHumanView)

VirtualHumanView is the foundation view for Digital Human rendering. The connecting party can use VirtualHumanView in Activity or any view for display. There are two configuration methods:
Configure directly in XML:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

    <LinearLayout
            android:id="@+id/ll_floating_ball"
            android:layout_width="180dp"
            android:layout_height="320dp"
            android:background="#8f15ab71"
            android:gravity="center"
            android:orientation="horizontal">

        <com.tencent.virtualhuman_2d_sdk.VirtualHumanView
                android:id="@+id/virtual_human_view"
                app:TVHFillMode="fill" // render View filling mode
                android:layout_width="match_parent"
                android:layout_height="match_parent" />
    </LinearLayout>
</LinearLayout>
can also dynamically add:
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
        android:orientation="vertical"
        android:layout_width="match_parent"
        android:layout_height="match_parent">

    <LinearLayout
            android:id="@+id/ll_container"
            android:layout_width="480dp"
            android:layout_height="480dp"
            android:background="#8f15ab71"
            android:gravity="center"
            android:orientation="horizontal">
    </LinearLayout>
    
</LinearLayout>
Example Code
// context is the context of the current Activity interface
 VirtualHumanView virtualHumanView = new VirtualHumanView(context);
 virtualHumanView.setFillMode(VirtualHumanViewType.fill);
LinearLayout ll_container = findViewById(R.id.ll_container);
ll_container.addView(virtualHumanView);
The render View filling mode can be configured.
VirtualHumanViewType.stretch
Stretch image
VirtualHumanViewType.fit
Crop image
VirtualHumanViewType.fill
Keep black border (transparent edge)

Setting Render View for Controller

Parameter description
Parameter Name
Data Type
Parameter Type
Description
virtualHumanView
VirtualHumanView
Required or Not
controller.setRenderView(virtualHumanView);

5. Streaming Input Audio Driver Digital Person

The input audio format is s16le (signed 16 bits little endian) PCM, with a sampling rate of 16000 and mono.
Parameter Name
Data Type
Parameter Type
Description
decodedBytes
Byte[]
Yes
PCM audio data.
isFinal
Boolean
Yes
Whether it is the audio end frame.
metaData
String
No
Import the tag corresponding to the audio data. There will be event 10003/10004 when broadcasting the audio fragment.
Example Code
controller.appendAudioData(decodedBytes, isFinal);
controller.appendAudioData(decodedBytes, isFinal, metaData);

6. Interrupt Request 

controller.interrupt();

7. Suspending Request

controller.pause();

8. Restore Request 

controller.resume();

Demo App Instructions

The SDK includes a fully functional Demo App. The project engineering architecture is as follows:


Modifying the local.properties File

The local.properties file contains ALL AppKeys and other keys used. Please change to the customer application.


2. Running Demo

Click the Run button to run the 2D endpoint rendering Demo application.

3. Downgrade Solution for Early Stage Devices

The endpoint rendering Digital Human SDK uses client computing power to complete AI Algorithm reasoning and image synthesis, requiring specific performance requirements for mobile devices.
We provide a copy of Android model compatibility blocklist/allowlist. The connecting party can compare the values obtained from Build.MODEL with the blocklist/allowlist to confirm if this model's performance meets Digital Human rendering requirements.
Note:
Blocklist/allowlist will be updated continuously as new models are generated.
We also provide a way to determine at runtime whether the performance of an Android model meets Digital Human rendering requirements. Sample code:
Refer to the above text to create a Digital Human controller
controller = new VirtualHumanController(DemoActivity.this, vhParam);
int ret = controller.initHuman();// Initialize Digital Human
if (ret == 0) {
    2. Not calling setRenderView, start rendering directly
    controller.startHuman();
} else {
    Log.i(TAG, "init fail=" + ret);
}
Listen to the returned value of errorCallback. If error code 20012 occurs within a period of time, it indicates low performance of the device and cannot ensure smooth operation.

4. Upgrading From an Old Version

Upgrading From Version 1.1.x to Version 1.3.x

1. Dependencies of third-party libraries: implementation 'com.parse.bolts:bolts-tasks:1.4.0'.
2. Remove the vhParam.bindDevice parameter.
3. Change the original controller.setRenderView(virtualHumanView); to the following writing style:
    int ret = controller.initHuman();
    if (ret == 0) {
        controller.setRenderView(virtualHumanView);
        controller.startHuman();
    } else {
        Log.i(TAG, "init fail=" + ret);
    }

Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback