Help & Documentation>Text To Speech

Streaming Text To Speech

Last updated: 2025-02-06 15:33:27

1. Preparations For Access

1.1 SDK Acquisition

The download link for Streaming TTS Android SDK and Demo: Access SDK Download.

1.2 Integration Notes

This SDK requires the phone to be connected to the network, and the Android device API Level must be 16 or later.
To run the demo, you must set AppID, SecretID, and SecretKey, which can be obtained from API Key Management.

1.3 Adding SDK

Copy the downloaded SDK file (*.aar) to the project's libs folder and add the following code to the project's build.gradle file:
dependencies {
implementation fileTree(include: ['*.jar', '*.aar'], dir: 'libs')
// Streaming TTS SDK
implementation files("libs/stream_tts-release-VERSION.aar")
// okhttp library internally depended on by the Streaming TTS SDK (required)
implementation 'com.squareup.okhttp3:okhttp:4.9.3'
// gson library internally depended on by the Streaming TTS SDK (required)
implementation 'com.google.code.gson:gson:2.8.9'
}

1.4 Add Permissions

Add the permissions required by the SDK to the project's AndroidManifest.xml file, for example:
<uses-permission android:name="android.permission.INTERNET" />

2. SDK APIs Use Instructions

This section mainly introduces the detailed procedures for SDK API calls and the timing of API calls (for specific usage, refer to the example code in the SDK delivery Demo).

2.1 Construct Configuration Items

FlowingSpeechSynthesizerRequest request = new FlowingSpeechSynthesizerRequest();
/************ For the meaning of configuration items, please also refer to the official website document: https://cloud.tencent.com/document/product/1073/108595 ************/
request.setVolume(volume); // Volume, range [-10, 10]. Default is 0, representing normal volume. The higher the value, the higher the volume.
request.setSpeed(speed); // Speech speed, range: [-2, 6], corresponding to different speeds: -2: represents 0.6x; -1: represents 0.8x; 0: represents 1.0x (default); 1: represents 1.2x; 2: represents 1.5x; 6: represents 2.5x.
request.setCodec("pcm"); // Return audio format: pcm: returns binary pcm audio (default); mp3: returns binary mp3 audio.
request.setSampleRate(SAMPLE_RATE); // Audio sample rate: 24000: 24k (supported by some voices); 16000: 16k (default); 8000: 8k.
request.setVoiceType(voiceType); // Voice ID.
request.setEnableSubtitle(true); // Enable timestamp feature, default is false.
request.setEmotionCategory("neutral"); // Control the emotion of synthetic audio, only multi-emotion timbres are supported
request.setEmotionIntensity(100); // Control the intensity of the synthetic audio emotion, with a range of [50,200], default is 100; only effective when EmotionCategory is not empty.
request.setSessionId(UUID.randomUUID().toString()); // sessionId, must be globally unique (recommended to use uuid), provide this value for server-side troubleshooting if issues arise
/************ For the meaning of configuration items, please also refer to the official website document: https://cloud.tencent.com/document/product/1073/108595 ************/

2.2 Account Information Configuration

// For account information, refer to 0.2 Access Instructions
Credential credential = new Credential(appId, secretId, secretKey, token);

2.3 Constructing a Synthesizer

// A network proxy, globally unique is sufficient
private static final SpeechClient proxy = new SpeechClient();
...
FlowingSpeechSynthesizerListener listener = new FlowingSpeechSynthesizerListener() {
@Override
public void onSynthesisStart(SpeechSynthesizerResponse response) {// synthesis start}
​
@Override
public void onSynthesisEnd(SpeechSynthesizerResponse response) {// synthesis end}
​
@Override
public void onAudioResult(ByteBuffer buffer) {// synthetic audio data}
​
@Override
public void onTextResult(SpeechSynthesizerResponse response) {//Information of the synthesized text}
​
@Override
public void onSynthesisCancel() {//Synthesis canceled}
​
@Override
public void onSynthesisFail(SpeechSynthesizerResponse response) {//Composition failure}
};
// Construct the synthesizer
FlowingSpeechSynthesizer synthesizer = new FlowingSpeechSynthesizer(proxy, credential, request, listener);

2.4 Launching a Synthesizer

synthesizer.start();

2.5 Sending Text

// Input the text to be synthesized
synthesizer.process(text);

2.4 Stopping a Synthesizer

// Send a disconnection request to the server. After the server completes the existing composition task, it returns a disconnection confirmation to the client, and then the client disconnects the websocket connection
synthesizer.stop();

2.7 Cancelling Synthesis

// Directly disconnect the websocket connection
synthesizer.cancel();


3. API Details

3.1 FlowingSpeechSynthesizer

3.1.1 constructing API

public FlowingSpeechSynthesizer(SpeechClient client,
Credential credential,
FlowingSpeechSynthesizerRequest request,
FlowingSpeechSynthesizerListener listener) throws SynthesizerException
Feature: The constructor API of the core class of the Streaming TTS SDK, pay attention to Exception capturing.
Parameters:
Parameter Type
Parameter Name
Parameter Meaning
SpeechClient
client
A network connection proxy, globally unique is sufficient
Credential
credential
Entity class for authentication information
FlowingSpeechSynthesizerRequest
request
Configuration items for speech synthesis
FlowingSpeechSynthesizerListener
listener
Key event callback for speech synthesis

3.1.2 launching synthesizer API

public void start() throws Exception
Feature: Start the synthesizer, pay attention to exception capturing.

3.1.3 sending text API

public void process(String text) throws Exception
Feature: Send the text to be synthesized, pay attention to exception capturing.
Parameters:
Parameter Type
Parameter Name
Parameter Meaning
String
text
Text to be synthesized

3.1.4 end synthesis API

/**
* End synthesis: Send end synthesis notification, receive server confirmation
*/
public void stop() throws Exception
/**
* End synthesis: Send end synthesis notification, receive server confirmation, throw an exception if timeout occurs
*/
public void stop(long milliSeconds) throws Exception

3.1.5 cancelling synthesis API

public void cancel()
Feature: Cancel synthesis, directly close the websocket connection without sending an end notification to the server-side.

3.1.6 sdk version number

public static String version()

3.2 FlowingSpeechSynthesizerRequest

SDK configuration class. For the meaning of configuration items, please also refer to the official documentation:
Type
Name
Meaning
Default Value
Float
volume
Volume level, ranging from -10 to 10. The default is 0, which represents normal volume. The higher the values, the louder the volume.
0
Float
speed
Speech speed, range: [-2, 6], corresponding to different speeds: -2: represents 0.6x; -1: represents 0.8x; 0: represents 1.0x (default); 1: represents 1.2x; 2: represents 1.5x; 6: represents 2.5x.
0
String
codec
Return audio format: pcm: returns binary pcm audio (default); mp3: returns binary mp3 audio.
pcm
Integer
sampleRate
Audio sample rate: 24000: 24k (supported by some voices); 16000: 16k (default); 8000: 8k.
16000
Integer
voiceType
Timbre ID, refer to official documentation for values.
0
Boolean
enableSubtitle
Enable timestamp feature, default is false.
false
String
emotionCategory
Control the emotion of the synthetic audio, only supported for multi-emotion and multi-timbre. Values: neutral, sad, happy, angry, fear, news, story, radio, poetry, call, sajiao, disgusted, amaze, peaceful, exciting, aojiao, jieshuo.
""
Integer
emotionIntensity
Control the intensity of the synthetic audio emotion, with a range of [50,200], default is 100; only effective when EmotionCategory is not empty.
100
String
sessionId
Must be globally unique (recommended to use uuid), provide this value for server-side troubleshooting if issues arise.
""

3.3 Credential

Key information entity class, can be obtained in API Key Management.
Type
Name
Meaning
Default Value
String
appid
appid, apply in the console
""
String
secretId
secretId, apply in the console
""
String
secretKey
secretKey, apply for it in the console
""
String
token
Used for temporary authorization scenarios
""

3.4 FlowingSpeechSynthesizerListener

Synthesis Listener Class
public abstract class FlowingSpeechSynthesizerListener {
// Synthesis started
public abstract void onSynthesisStart(SpeechSynthesizerResponse response);
// Synthesis ended
public abstract void onSynthesisEnd(SpeechSynthesizerResponse response);
// Synthesized audio data
public abstract void onAudioResult(ByteBuffer data);
// Synthesized text information
public abstract void onTextResult(SpeechSynthesizerResponse response);
// Synthesis canceled
public abstract void onSynthesisCancel();
// Synthesis failed
public abstract void onSynthesisFail(SpeechSynthesizerResponse response);
}

3.5 SpeechSynthesizerResponse

Synthesis Response
Type
Name
Meaning
String
sessionId
Generated by the client during the handshake phase and assigned in the call parameters
Integer
code
Status Codes: 0 means normal, non-zero values indicate an error occurred
Integer
end
When this field returns 1, it indicates that the text synthesis is complete. The client needs to actively close the websocket connection upon receiving it
String
message
Error Description: Displays the specific reason for the error. This text may be frequently updated or changed as the business develops or to optimize the user experience
String
requestId
Unique audio stream ID, automatically generated by the server during the handshake phase
String
messageId
Unique message ID
SpeechSynthesizerResult
result
Text to Speech result

3.6 SpeechSynthesizerResult

Synthesis result
Type
Name
Meaning
SpeechSynthesizerSubtitle[]
subtitles
Word list information

3.7 SpeechSynthesizerSubtitle

Synthesis word information
Type
Name
Meaning
String
text
Text
Integer
beginTime
Text TTS start timestamp
Integer
endTime
Text TTS end timestamp
Integer
beginIndex
The start position of the character in the sentence
Integer
endIndex
The end position of the character in the sentence
String
phoneme
The phoneme of the character


4. Error Codes

Error Code
CLIENT_CANNOT_BE_NULL(-400, "client cannot be null")
CREDENTIAL_CANNOT_BE_NULL(-401, "credential cannot be null")
REQUEST_CANNOT_BE_NULL(-402, "request cannot be null")
LISTENER_CANNOT_BE_NULL(-403, "listener cannot be null")
APPID_IS_EMPTY(-404, "appId cannot be empty")
SECRETID_IS_EMPTY(-405, "secretId cannot be empty")
SECRETKEY_IS_EMPTY(-406,"secretKey cannot be empty")
START_SYNTHESIZER_FAIL(-407, "fail to start synthesizer")
SEND_TEXT_FAIL(-408, "fail to send text")
CONNECT_SERVER_FAIL(-409, "fail to connect server")
INCORRECT_STATE(-410, "") // error message depends on the situation