Android SDK
User guide:For model introductions and selection advice, see Speech synthesis - Sambert.
Interactive demo: Not supported.
ImportantAlibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region, delivering superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
{WorkspaceId} must be replaced with your actual Workspace ID. The existing domain remains fully functional.
NativeNui
This SDK is built on the NativeNui singleton architecture and handles speech synthesis events through a callback mechanism.
Architecture highlights:-
Singleton pattern: Obtain the global unique instance by calling
NativeNui.GetInstance() -
Callback-driven: Receive events and data through the
INativeTtsCallbackinterface -
Event types:
TTS_EVENT_START: The synthesis task has startedonTtsDataCallback: Audio data is returnedTTS_EVENT_END: The synthesis task has endedTTS_EVENT_ERROR: A synthesis error has occurred
Usage flow
tts_initialize()- Initialize the SDK, set the callback interface, and specify connection parameterssetparamTts()- Set speech synthesis effect parameters (model, voice, volume, etc.)startTts()- Start the speech synthesis taskonTtsDataCallback()- Receive audio datatts_release()- Release SDK resources
Sambert methods
tts_initialize
Initializes the speech synthesis SDK instance. The SDK uses the singleton pattern; do not initialize it again before calling tts_release().
This call is blocking and should be invoked on a non-UI thread.
Method signature:public synchronized int tts_initialize(INativeTtsCallback callback,
String ticket,
final Constants.LogLevel level,
boolean save_log)
Parameters:
Parameter | Type | Description |
|---|---|---|
| Implementation of the event and data callback interface. | |
|
| A JSON string containing authentication, connection, and debugging parameters. See the ticket parameters below. |
|
| Controls the log verbosity of the SDK itself. |
|
| Whether to save local logs. If true, you must specify a path through the |
ticket JSON example:
{
"url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
"apikey": "sk-****",
"device_id": "my_device_id",
"mode_type": "2"
}
ticket parameters:
Parameter | Type | Required | Description |
|---|---|---|---|
|
| Yes | Service endpoint, fixed to Replace |
|
| Yes | API Key. We recommend using a temporary API key, which is short-lived and more secure, to reduce the risk of long-lived key leakage. |
|
| Yes | Mode type. Must be set to the string |
|
| Yes | A unique string that identifies the end user, such as an in-app user ID or a client-generated unique device identifier. It is mainly used for log tracking and troubleshooting. |
|
| No | The path where log files are stored. This parameter takes effect only when A maximum of two log files are kept locally. |
|
| No | The maximum size of a log file, in bytes. This parameter takes effect only when Default: 104857600 (100 * 1024 * 1024 bytes, i.e. 100MiB). |
|
| No | Controls the filtering level of log content sent through the log callback ( Default: 2. Valid values:
Note: |
setparamTts
Sets speech synthesis effect parameters as key-value pairs. Call it before startTts().
public synchronized int setparamTts(String param, String value)
Parameters:
Parameter | Type | Description |
|---|---|---|
|
| Parameter name. |
|
| Parameter value. |
Available parameters:
Parameter | Type | Required | Description |
|---|---|---|---|
|
| Yes | Model name, such as |
|
| No | Audio encoding format. Valid values:
|
|
| No | Volume. Default: 50. Valid range: [0, 100]. |
|
| No | Audio sample rate (Hz). Valid values: 8000, 16000 (default), 22050, 24000. |
|
| No | Speech rate. Default: 1.0. Valid range: [0.5, 2.0]. |
|
| No | Pitch. Default: 1.0. Valid range: [0.5, 2.0]. |
|
| No | Whether to enable word-level timestamps. Default: false. Applies to all Sambert models. |
|
| No | Whether to enable phoneme-level timestamps. Default: false. Requires word_timestamp_enabled to be enabled first. |
|
| No | Whether to enable the built-in audio decoder. Default: 0. Valid values:
|
getparamTts
Gets a parameter value. Mainly used for troubleshooting.
Method signature:public String getparamTts(String param);
Parameters:
Parameter | Type | Description |
|---|---|---|
|
| Parameter name. Currently only "error_msg" is supported. |
The parameter value.
startTts
Starts a speech synthesis task. The synthesis result is returned through callbacks.
Method signature:public synchronized int startTts(String priority, String taskid, String text)
Parameters:
Parameter | Type | Description |
|---|---|---|
|
| Task priority. Set it to 1. |
|
| Task ID. When |
|
| The text to synthesize. |
pauseTts
Pauses the current speech synthesis task. Once paused, the task can be resumed with resumeTts() or fully canceled with cancelTts(). While a task is paused, the SDK does not support starting a new synthesis task.
Note: This operation only pauses data fetching from the server; audio data already buffered in the player will continue to play.
Method signature:public synchronized int pauseTts()
resumeTts
Resumes a speech synthesis task that is paused.
Method signature:public synchronized int resumeTts()
cancelTts
Cancels a synthesis task.
Note: This operation only cancels data fetching from the server; audio data already buffered in the player will continue to play.
Method signature:public synchronized int cancelTts(String taskid)
Parameters:
Parameter | Type | Description |
|---|---|---|
|
| The ID of the task to cancel. If |
tts_release
Releases all internal SDK resources and forcibly terminates all ongoing synthesis tasks. After this method is called, the SDK instance becomes unusable; to use it again, you must call tts_initialize() to reinitialize it.
public synchronized int tts_release()
INativeTtsCallback
The Sambert speech synthesis callback interface, used to receive synthesis events and audio data.
onTtsEventCallback: Listening for events
Method signature:void onTtsEventCallback(TtsEvent event, String task_id, int ret_code);
Parameters:
Parameter | Type | Description |
|---|---|---|
| The callback event. | |
|
| Speech synthesis task ID. |
|
| Valid only when a TTS_EVENT_ERROR event occurs. |
onTtsDataCallback: Listening for audio data and timestamp information
During synthesis, the SDK triggers this callback continuously, and you retrieve the audio data in the callback.
Method signature:void onTtsDataCallback(String info, int info_len, byte[] data);
Parameters:
Parameter | Type | Description |
|---|---|---|
|
| Timestamp results in JSON format. Takes effect when |
|
| Data length of the info field; can be ignored. |
|
| The audio data of the current chunk. |
onTtsLogTrackCallback: Listening for trace logs
This callback is used to receive detailed internal SDK logs, making it easier to locate and debug issues.
Method signature:default void onTtsLogTrackCallback(Constants.LogLevel level, String log)
TtsEvent
The Sambert speech synthesis event type enum.
| Event | Description |
|---|---|
TTS_EVENT_START | The synthesis task has started; audio data is about to be returned. |
TTS_EVENT_END | The synthesis task ended normally; all audio data has been delivered through callbacks. |
TTS_EVENT_CANCEL | The synthesis task has been canceled. |
TTS_EVENT_PAUSE | The synthesis task has been paused. |
TTS_EVENT_RESUME | The synthesis task has been resumed. |
TTS_EVENT_ERROR | An error occurred during synthesis. You can call |
Example code
-
Get an API Key: Obtain and configure an API Key. For security reasons, we recommend configuring the API key in an environment variable.
NoteWhen you need to grant a third-party application or user temporary access, or want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using a temporary API key. A temporary API key is valid for 60 seconds by default and must be obtained again after it expires.
-
Download the SDK and run the sample code:
- Download the latest SDK package.
- Extract the ZIP package. Get the AAR SDK from the
app/libsdirectory and add it to your project dependencies.
To integrate with Android CPP, useandroid_libsandandroid_includein the ZIP package to obtain the dynamic libraries and header files. - Open the project in Android Studio. The sample code is in
DashSambertTtsActivity.java; replace the API key and try the features.
Call steps
- Initialize the SDK.
- Set parameters based on your business needs: set connection and control parameters through the
ticketparameter of the tts_initialize interface, and speech synthesis effect parameters through the setparamTts interface. - Call
startTtsto start speech synthesis. - Retrieve audio data in the onTtsDataCallback callback; streaming playback is recommended. To save the audio locally, write it to the same file in append mode until synthesis completes.
- After the task ends, call
tts_releaseto release SDK resources.