Premium SDK For Android

Last updated: 2025-02-06 15:36:47

Note:
The current page is the development documentation for version v2.x.x SDK.
The offline SDK includes the features of the online SDK. For the online part, please refer to the v2.x.x version online SDK development documentation.

Developer

Development Preparation

Supports Android 4.1 and above, API LEVEL 16, compatible with mobile phones and tablets.
The device authorization method requires the mobile phone to be connected to a network (3G/4G/5G or Wi-Fi network, etc.).
It is recommended to develop using Android Studio.

Download and Install SDK

Please refer to Authorization Activation and follow the instructions to activate and download the SDK file.
After decompressing, you will get the example code project. The aar file under the sdk directory is the SDK package.
Open the project with Android Studio to view the Text To Speech (TTS) example code.

Environment Configuration

Add the real-time TTS SDK AAR file to the libs directory, and add the following code to the build.gradle file of the App.
implementation(name: 'qcloudtts-release', ext: 'aar')
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

API Description

Obtain a tts synthesizer instance

// Get instance
TtsController mTtsController = TtsController.getInstance();

// Terminate instance
TtsController.release();

Initialization engine

mTtsController.init(Context context,TtsMode mode,TtsResultListener listener)

TTS Synthesizer Working Mode Parameters

If the downloaded compressed package is "xxx_offline.zip", it supports the following three modes. If it is "xxx_online.zip", it only supports online mode.
Parameter
Description
TtsMode.OFFLINE
Offline
TtsMode.ONLINE
Online
TtsMode.MIX
Mixed

Online Mode Parameter Configuration (Not Required If Not Used)

TtsController configuration parameter method

API
Description
setAppId(long l)
Configure Tencent Cloud AppId
setSecretId(String s)
Configure Tencent Cloud SecretId
setSecretKey(String s)
Configure Tencent Cloud SecretKey
setToken(String s)
Token needs to be set for STS temporary certificate authentication
setOnlineVoiceSpeed(float f)
Set the speech speed of the synthesized online audio, range: [-2, 2], corresponding to different speech speeds:
-2 represents 0.6x, -1 represents 0.8x, 0 represents 1.0x (default), 1 represents 1.2x, 2 represents 1.5x For more precise speech speed, you can keep 2 decimal places, such as 0.5/1.25/2.81, etc.
setOnlineVoiceVolume(float f)
Setting the volume of the synthesized online audio
setOnlineVoiceType(int i)
Set the voice ID of the synthesized online audio. For the complete list of voice IDs, refer to TextToVoice.
setOnlineVoiceLanguage(int i)
Primary language type: 1-Chinese (default), 2-English
setOnlineCodec(String s)
Online mode encoding format, not recommended to change unless necessary: default is mp3, currently supports "mp3", "wav", "pcm". If changed to pcm, playback is not supported.
setConnectTimeout(int i)
Connection timeout, default is 15,000 ms (15s), range [500, 30,000] ms. It is recommended to reduce this value in Mix mode for a better experience.
setReadTimeout(int i)
Read timeout, default is 30,000 ms (30s), range [2200, 60,000] ms. It is recommended to reduce this value in Mix mode for a better experience.
Example:
mTtsController.setAppId(0L);
mTtsController.setSecretId("************************************");
mTtsController.setSecretKey("***************************");
mttsController.setToken(null);
mTtsController.setOnlineVoiceSpeed(mVoiceSpeed);
mTtsController.setOnlineVoiceVolume(1.0);
mTtsController.setOnlineVoiceType(1001);
mTtsController.setOnlineVoiceLanguage(1);
mTtsController.setOnlineCodec("mp3");
mTtsController.setConnectTimeout(15 *1000);
mTtsController.setReadTimeout(30 *1000);


Offline Mode Parameter Configuration (Not Required If Not Used)

TtsController configuration parameter method

Device-based authorization
API
Description
refreshAuth
Whether to force online refresh authorization (false: only activate and download authorization file the first time online, true: refresh authorization file online, activation will fail without network)
secret_id
Tencent Cloud SecretId (may not be the same account as online mode, need to enter the SecretId of the account that purchased the offline SDK)
secret_key
Tencent Cloud SecretKey (may not be the same account as online mode, need to enter the SecretKey of the account that purchased the offline SDK)
lic_key
The licKey corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_pk
The licPk corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
Example:
String secret_id = "AKID********************9SXO";
String secret_key ="f5********************05xa";
String lic_key = "AI8********************064";
String lic_pk = "hg9********************2BO";
mTtsController.setOfflineAuthParamDoOnline(true, secret_id,secret_key,lic_key,lic_pk);
Application-based authorization
API
Description
lic
Authorization key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_sign
The licPk corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
lic_pk
The licSign corresponding to the key, please obtain it from the Tencent Cloud official website or issued offline by Tencent Cloud business.
Example:
String lic = "PLK********************YEoeO1EEUoTDH/R/mk=";
String lic_sign = "PoTpR********************g0ucFkOQOU=";
String lic_pk = "hg9********************2BO";
mTtsController.setOfflineAuthParamDoOffline(lic,lic_sign,lic_pk);

TtsController configuration parameter method

API
Description
setOfflineVoiceVolume(float voiceVolume)
Offline volume > 0
setOfflineVoiceSpeed(float voiceSpeed)
Offline speech speed [0.5, 2.0]
setOfflineVoiceType(String s)
Offline Voice Name, the name configuration is located in the voice resource directory\voices\config.json. You can delete or add voices yourself. Voices need authorization, and an error will be reported if the corresponding voice is not authorized for synthesis. You can contact Tencent Cloud business for purchase.
Default as follows (Offline Voice Name - Voice Name)
M206 - Zhihao db1 - Zhiling db3 - Zhimeng db7 - Zhitian f0 - Zhili f2 - Zhiyun femozhifou - Zhirong fn - Zhiyu kefu - Zhimei kefu2 - Zhina kefu3 - Zhiqi m0 - Zhiyun m25 - Zhihua memozhifou - Zhijing newsman - Zhining pb - Zhixiaoyao xiaowei - Zhiyan
setOfflineResourceDir(String resourceDir)
Set the path where the offline model resource is located
Example
mTtsController.setOfflineResourceDir("/sdcard/res");
mTtsController.setOfflineVoiceSpeed(1.0f);
mTtsController.setOfflineVoiceVolume(1.0f);
mTtsController.setOfflineVoiceType("pb");

Hybrid mode parameter configuration (no need to configure if not used)

The hybrid mode provides a strategy to switch between offline synthesis and online synthesis.
In online mode, it will automatically switch to offline mode based on network conditions (the SDK will switch when the network is poor). In offline mode, it will try to switch back to online mode at intervals.

TtsController authorization configuration

Hybrid mode requires both online and offline authorization. Authorization configuration refers to the methods of online mode and offline mode (both need to be configured).

TtsController configuration parameter method

The configuration of online mode and offline mode will affect the synthesis behavior in the corresponding state under hybrid mode.
The following are hybrid mode-specific configurations that will affect the strategy selection:
API
Description
setCheckNetworkIntervalTime(int i)
In Mix mode, the detection interval time after a network error or backend error occurs while already connected to the network, used to automatically switch back to online mode from offline mode, default value is 5 minutes, in seconds.
Example:
mTtsController.setCheckNetworkIntervalTime(5 * 60);

Synthesis text input parameter API

API
Description
synthesize(String text,)
text is the text to be synthesized
synthesize(String utteranceId)
utteranceId is the ID marking the text, which will be returned to the host layer with the mix result
Example:
// There is an internal queue, statements can be continuously added, and the SDK will synthesize them sequentially
TtsError error = null;
error = mTtsController.synthesize("The weather is nice today", "Sentence 1");
error = mTtsController.synthesize("Tencent Cloud TTS", "Sentence 2");
error = mTtsController.synthesize("Tencent Cloud AI", "Sentence 3");
error = mTtsController.synthesize("Tencent Cloud AI", "Sentence 4");

// Cancel unsynthesized tasks and clear the internal queue
mTtsController.cancel();

Synthesis listener for obtaining synthesis results

When instantiating TtsResultListener, by default, you need to override the onSynthesizeData() and onError() methods.
Explanation of the onSynthesizeData() method signature
Parameter
Description
byte[] bytes
Voice data
String utteranceId
Statement ID
String text
Text
int engineType
Engine type; 0: online, 1: offline
onError() Method Signature Description
Parameter
Description
TtsError error
Error information, return null if no error
String utteranceId
Statement ID (if available, return it)
String text
Text (if available, return)
onOfflineAuthInfo() Method Signature Description
Parameter
Description
offlineAuthInfo.getExpireTime()
Authorization expiration time
offlineAuthInfo.getError().getCode()
0 means authorization success, others mean failure
offlineAuthInfo.getResponse()
When using online authentication to pull the authorization file, the Response data returned by the server (only needs attention when authorization fails)
Example
TtsResultListener listener = new TtsResultListener() {

@Override
public void onSynthesizeData(byte[] bytes, String utteranceId, String text, int engineType) {
// You can save the audio here or send it to the playback API for playing, and call the player input API
}
@Override
public void onError(TtsError error, String utteranceId, String text) {
// You can add error post-processing here
// Note: In actual business, if the backend error code of online composition is returned in hybrid mode, it should be ignored and not processed. The SDK will call offline composition to continue working.
}
@Override
public void onOfflineAuthInfo(QCloudOfflineAuthInfo offlineAuthInfo) {
// offlineAuthInfo returns offline SDK authorization information, including error code, expiration time, and current device ID.
// Note, if using offline mode, you need to call the composition API after receiving this callback, otherwise, composition failure may occur due to authorization failure!
}
@Override
public void onChunk(ByteBuffer chunk) {
// Streaming data returned by offline composition, formatted as 16k single-channel PCM.
}
}

Initialize the player

If the SDK's built-in player does not meet your needs, you can replace it with your own implemented player. The demo also provides additional player source code, which you can modify the player logic. The source code is located in MediaPlayerDemo.java, consistent with the SDK's built-in player.
// Use the player provided in the SDK
QCloudMediaPlayer mediaPlayer = new QCloudMediaPlayer(new QCloudPlayerCallback() {
@Override
public void onTTSPlayStart() {
Log.d(TAG, "Start play");
}

@Override
public void onTTSPlayWait() {
Log.d(TAG, "Playback complete, waiting for audio data");
}

@Override
public void onTTSPlayResume() {
Log.d(TAG, "Resume play");
}

@Override
public void onTTSPlayPause() {
Log.d(TAG, "Pause playing");
}

@Override
public void onTTSPlayNext(String text, String utteranceId) {
Log.d(TAG, "Start play: " + utteranceId + "|" + text);
}

@Override
public void onTTSPlayStop() {
Log.d(TAG, "Playback stop, internal queue has been cleared");
}

@Override
public void onTTSPlayError(QPlayerError error) {
Log.d(TAG, "Player encountered an exception:" + error.getmCode() + ":" + error.getmMessage());
}

/**
* @param currentWord Current playback character (this is an estimated value)
* @param currentIndex Index of the current playback character in the sentence (this is an estimated value)
*/
@Override
public void onTTSPlayProgress(String currentWord, int currentIndex) {
Log.d(TAG, "onTTSPlayProgress: " + currentWord + "|" + currentIndex);
}
});

Player input parameter

enqueue() Method Signature Description
API
Description
byte[] bytes
Return the audio stream, play by passing in a byte array
File audio
Return the audio file, play by passing in a file
String text
Text corresponding to the audio
String utteranceId
<Text ID>
Example
// Through audio data parameter
QPlayerError err = mediaPlayer.enqueue(byte[] bytes,String text,String utteranceId);

// Through audio file parameter
QPlayerError err = mediaPlayer.enqueue(File audio,String text,String utteranceId);