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 instanceTtsController mTtsController = TtsController.getInstance();// Terminate instanceTtsController.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 sequentiallyTtsError 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 queuemTtsController.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() {@Overridepublic 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}@Overridepublic 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.}@Overridepublic 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!}@Overridepublic 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 SDKQCloudMediaPlayer mediaPlayer = new QCloudMediaPlayer(new QCloudPlayerCallback() {@Overridepublic void onTTSPlayStart() {Log.d(TAG, "Start play");}@Overridepublic void onTTSPlayWait() {Log.d(TAG, "Playback complete, waiting for audio data");}@Overridepublic void onTTSPlayResume() {Log.d(TAG, "Resume play");}@Overridepublic void onTTSPlayPause() {Log.d(TAG, "Pause playing");}@Overridepublic void onTTSPlayNext(String text, String utteranceId) {Log.d(TAG, "Start play: " + utteranceId + "|" + text);}@Overridepublic void onTTSPlayStop() {Log.d(TAG, "Playback stop, internal queue has been cleared");}@Overridepublic 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)*/@Overridepublic 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 parameterQPlayerError err = mediaPlayer.enqueue(byte[] bytes,String text,String utteranceId);// Through audio file parameterQPlayerError err = mediaPlayer.enqueue(File audio,String text,String utteranceId);