Android SDK

Updated at:

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:

Usage flow

  1. tts_initialize() - Initialize the SDK, set the callback interface, and specify connection parameters
  2. setparamTts() - Set speech synthesis effect parameters (model, voice, volume, etc.)
  3. startTts() - Start the speech synthesis task
  4. onTtsDataCallback() - Receive audio data
  5. tts_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

callback

INativeTtsCallback

Implementation of the event and data callback interface.

ticket

String

A JSON string containing authentication, connection, and debugging parameters. See the ticket parameters below.

level

Constants.LogLevel

Controls the log verbosity of the SDK itself.

save_log

boolean

Whether to save local logs. If true, you must specify a path through the debug_path field in the ticket parameter, and you can set the file size with max_log_file_size.

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

url

String

Yes

Service endpoint, fixed to wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference.

Replace {WorkspaceId} with your actual Workspace ID when calling.

apikey

String

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.

mode_type

String

Yes

Mode type. Must be set to the string "2", which indicates the online speech synthesis mode.

device_id

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.

debug_path

String

No

The path where log files are stored.

This parameter takes effect only when save_log is set to true when calling the tts_initialize interface. In this case, the log file path must be set; otherwise an error will be reported.

A maximum of two log files are kept locally.

max_log_file_size

int

No

The maximum size of a log file, in bytes.

This parameter takes effect only when save_log is set to true when calling the tts_initialize interface.

Default: 104857600 (100 * 1024 * 1024 bytes, i.e. 100MiB).

log_track_level

int

No

Controls the filtering level of log content sent through the log callback (onTtsLogTrackCallback).

Default: 2.

Valid values:

  • 0: LOG_LEVEL_VERBOSE

  • 1: LOG_LEVEL_DEBUG

  • 2: LOG_LEVEL_INFO

  • 3: LOG_LEVEL_WARNING

  • 4: LOG_LEVEL_ERROR

  • 5: LOG_LEVEL_NONE (disables this feature)

Note: log_track_level and log_level (set through the tts_initialize interface) jointly determine which logs are finally delivered. A log entry is delivered only if its severity value is greater than or equal to both log_track_level and log_level. For example, if log_track_level is 2 (INFO) and log_level is 3 (WARNING), only logs at WARNING or above (value >=3) will be delivered.

setparamTts

Sets speech synthesis effect parameters as key-value pairs. Call it before startTts().

Method signature:
public synchronized int setparamTts(String param, String value)
Parameters:

Parameter

Type

Description

param

String

Parameter name.

value

String

Parameter value.

Available parameters:

Parameter

Type

Required

Description

model

String

Yes

Model name, such as sambert-zhichu-v1.

format

String

No

Audio encoding format.

Valid values:

  • pcm

  • wav (default)

  • mp3

volume

String

No

Volume.

Default: 50.

Valid range: [0, 100].

sample_rate

String

No

Audio sample rate (Hz).

Valid values: 8000, 16000 (default), 22050, 24000.

rate

String

No

Speech rate.

Default: 1.0.

Valid range: [0.5, 2.0].

pitch

String

No

Pitch.

Default: 1.0.

Valid range: [0.5, 2.0].

word_timestamp_enabled

String

No

Whether to enable word-level timestamps.

Default: false.

Applies to all Sambert models.

phoneme_timestamp_enabled

String

No

Whether to enable phoneme-level timestamps.

Default: false.

Requires word_timestamp_enabled to be enabled first.

enable_audio_decoder

String

No

Whether to enable the built-in audio decoder.

Default: 0.

Valid values:

  • 1: Enable. When format is mp3, set it to "1" to enable the SDK built-in decoder, in which case onTtsDataCallback will return decoded PCM data.

  • 0: Disable.

getparamTts

Gets a parameter value. Mainly used for troubleshooting.

Method signature:
public String getparamTts(String param);
Parameters:

Parameter

Type

Description

param

String

Parameter name. Currently only "error_msg" is supported.

Return value:

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

priority

String

Task priority. Set it to 1.

taskid

String

Task ID. When null is passed, it is generated automatically by the SDK.

text

String

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

taskid

String

The ID of the task to cancel. If null is passed, all paused/ongoing synthesis tasks are canceled.

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.

Method signature:
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

event

TtsEvent

The callback event.

task_id

String

Speech synthesis task ID.

ret_code

int

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

info

String

Timestamp results in JSON format. Takes effect when word_timestamp_enabled is set to "1".

info_len

int

Data length of the info field; can be ignored.

data

byte[]

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.

EventDescription

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 getparamTTS("error_msg") to get the detailed error message.

{
  "header": {
    "task_id": "xxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "Please ensure input text is valid.",
    "attributes": {}
  },
  "payload": {}
}

Example code

  1. 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.

  2. Download the SDK and run the sample code:
    • Download the latest SDK package.
    • Extract the ZIP package. Get the AAR SDK from the app/libs directory and add it to your project dependencies.
      To integrate with Android CPP, use android_libs and android_include in 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

  1. Initialize the SDK.
  2. Set parameters based on your business needs: set connection and control parameters through the ticket parameter of the tts_initialize interface, and speech synthesis effect parameters through the setparamTts interface.
  3. Call startTts to start speech synthesis.
  4. 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.
  5. After the task ends, call tts_release to release SDK resources.