Sambert Speech Synthesis iOS SDK
This document provides a detailed guide on using the Sambert speech synthesis software development kit (SDK) for iOS to convert text into high-quality, expressive speech.
Online experience: Not supported.
ImportantAlibaba Cloud Model Studio has launched a workspace-specific domain for the China (Beijing) region, which delivers superior performance and higher stability for inference requests. We recommend that you migrate from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
{WorkspaceId} must be replaced with the actual Workspace ID. The existing domain remains fully functional.
NeoNui
This SDK is built on the NeoNui singleton architecture and handles speech synthesis events through the callback mechanism.
Architecture features:
-
Singleton pattern: Obtain the global unique instance through
NeoNui.sharedInstance() -
Callback-driven: Receive events and data through the
NeoNuiTtsDelegateprotocol -
Event types:
TTS_EVENT_START: The synthesis task startsonNuiTtsUserdataCallback: Audio data is returnedTTS_EVENT_END: The synthesis task endsTTS_EVENT_ERROR: A synthesis error occurs
Usage procedure
nui_tts_initialize()- Initializes the SDK and sets the callback interface and connection parametersnui_tts_set_param()- Sets the speech synthesis effect parameters (model, timbre, volume, and more)nui_tts_play()- Starts the speech synthesis taskonNuiTtsUserdataCallback()- Receives the audio datanui_tts_release()- Releases the SDK resources
Sambert methods
nui_tts_initialize
Initializes the speech synthesis SDK instance. The SDK uses the singleton pattern. Do not initialize the SDK again before you call nui_tts_release.
-(int) nui_tts_initialize:(const char *)parameters
logLevel:(NuiSdkLogLevel)level
saveLog:(BOOL)save_log;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| A JSON string that contains the authentication, connection, and debug parameters. For more information, see the parameters parameter description below. |
| Controls the print level of the SDK logs. | |
|
| Specifies whether to save local logs. If this parameter is set to |
parameters JSON example: The following code shows an example of a JSON string, in which not all parameters are listed. Add parameters based on your actual needs during encoding:
{
"url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
"apikey": "st-****",
"device_id": "my_device_id"
}
parameters parameter descriptions:
Parameter | Type | Required | Description |
|---|---|---|---|
|
| Yes | The service endpoint, which is fixed as When you call the interface, replace |
|
| Yes | The API key. We recommend that you use a temporary API key that has a shorter validity period and higher security to reduce the risk of long-term key leakage. |
|
| Yes | A unique string that identifies the end user. You can set it to the in-app user ID or a unique device identifier generated on the client. This ID is mainly used for log tracking and troubleshooting. |
|
| No | The storage path of log files. This parameter takes effect only when A maximum of two log files are retained locally. |
|
| No | The maximum number of bytes of a log file. This parameter takes effect only when Default value: 104857600 (100 * 1024 * 1024 bytes, i.e., 100MiB). |
|
| No | The filter level of the log content that is sent through the log callback (onNuiTtsLogTrackCallback). Default value: 2. Valid values:
Note: |
nui_tts_set_param
Sets parameters in key-value pairs. Call this method before you call nui_tts_play.
-(int) nui_tts_set_param:(const char *)param
value:(const char *)value;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| The parameter name. |
|
| The parameter value. |
Parameter | Type | Required | Description |
|---|---|---|---|
|
| Yes | The model name, such as |
|
| No | The audio coding format. Valid values:
|
|
| No | The volume. Default value: 50. Valid values: [0, 100]. |
|
| No | The audio sample rate (Hz). Valid values: 8000, 16000 (default), 22050, 24000. |
|
| No | The speech rate. Default value: 1.0. Valid values: [0.5, 2.0]. |
|
| No | The pitch. Default value: 1.0. Valid values: [0.5, 2.0]. |
|
| No | Specifies whether to enable word-level timestamps. Default value: false. Scope: all Sambert models. |
|
| No | Specifies whether to enable phoneme-level timestamps. Default value: false. You must enable word_timestamp_enabled first. |
|
| No | Specifies whether to enable the built-in audio decoder. Default value: 0. Valid values:
|
nui_tts_get_param
Obtains parameter values. This method is mainly used for troubleshooting.
Method signature:-(const char *) nui_tts_get_param:(const char *)param;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| The parameter. Currently, only "error_msg" is supported. |
Returns the parameter value.
nui_tts_play
Starts a speech synthesis task.
Method signature:-(int) nui_tts_play:(const char *)priority
taskId:(const char *)taskid
text:(const char *)text;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| The task priority. Set it to 1. |
|
| The task ID. If you pass |
|
| The text to synthesize. |
nui_tts_pause
Pauses the current speech synthesis task. After the task is paused, you can resume it through nui_tts_resume or cancel it through nui_tts_cancel. While a task is paused, the SDK does not support starting a new synthesis task.
Note: This operation only pauses data pulling from the server. The audio data already cached in the player continues to play.
Method signature:-(int) nui_tts_pause;
nui_tts_resume
Resumes a paused speech synthesis task.
Method signature:-(int) nui_tts_resume;
nui_tts_cancel
Cancels a synthesis task.
Note: This operation only cancels data pulling from the server. The audio data already cached in the player continues to play.
Method signature:-(int) nui_tts_cancel:(const char *)taskid;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| The ID of the task to cancel. If you pass |
nui_tts_release
Releases all internal SDK resources and forcibly terminates all in-progress synthesis tasks. After this method is called, the SDK instance becomes unavailable. To use the SDK again, you must call nui_tts_initialize to initialize it again.
-(int) nui_tts_release;
NeoNuiTtsDelegate
The Sambert speech synthesis callback protocol, which is used to receive synthesis events, audio data, and logs.
Methods
onNuiTtsEventCallback: listen to events
Method signature:- (void)onNuiTtsEventCallback:(NuiSdkTtsEvent)event taskId:(char*)taskid code:(int)code;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
| The callback event. | |
|
| The speech synthesis task ID. |
|
| Valid only when the TTS_EVENT_ERROR event occurs. |
onNuiTtsUserdataCallback: listen to audio data and timestamp information
Method signature:- (void)onNuiTtsUserdataCallback:(char*)info infoLen:(int)info_len buffer:(char*)buffer len:(int)len taskId:(char*)task_id;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
|
| The timestamp result in JSON format. This parameter takes effect when |
|
| The data length of the info field, which can be ignored. |
|
| The audio data of the current segment. |
|
| The length of the audio data in bytes. |
|
| The speech synthesis task ID. |
onNuiTtsLogTrackCallback: listen to trace logs
This callback is used to receive the detailed logs inside the SDK, which facilitates troubleshooting and debugging.
Method signature:- (void)onNuiTtsLogTrackCallback:(NuiSdkLogLevel)level
logMessage:(const char *)log;
Parameter descriptions:
Parameter | Type | Description |
|---|---|---|
| The log level. | |
|
| The log content. |
NuiSdkTtsEvent
The Sambert speech synthesis event type enumeration.
| Event | Description |
|---|---|
TTS_EVENT_START | The synthesis task starts, and audio data is about to be returned. |
TTS_EVENT_END | The synthesis task ends normally, and all audio data has been sent through the callbacks. |
TTS_EVENT_CANCEL | The synthesis task is canceled. |
TTS_EVENT_PAUSE | The synthesis task is paused. |
TTS_EVENT_RESUME | The synthesis task is resumed. |
TTS_EVENT_ERROR | An error occurs during synthesis. In this case, you can use |
NuiSdkLogLevel
The SDK log level enumeration, which is used to control log output.
Level | Description |
|---|---|
0: LOG_LEVEL_VERBOSE | The most detailed logs, including all debugging information. |
1: LOG_LEVEL_DEBUG | Debug-level logs. |
2: LOG_LEVEL_INFO | General information-level logs (default value). |
3: LOG_LEVEL_WARNING | Warning-level logs. |
4: LOG_LEVEL_ERROR | Error-level logs. |
5: LOG_LEVEL_NONE | Disables log output. |
Sample code
-
Obtain an API key: Obtain and configure an API key
NoteWhen you need to grant temporary access permissions to third-party applications or users, or want to strictly control high-risk operations such as sensitive data access and deletion, we recommend that you use a temporary API key. A temporary API key has a fixed validity period of 60 seconds. You must obtain a new one after it expires.
-
Download the SDK and run the sample code:
- Download the latest SDK package.
- Decompress the ZIP package and add nuisdk.framework in it to your project.
- In Build Phases → Link Binary With Libraries, add nuisdk.framework.
- In General → Frameworks, Libraries, and Embedded Content, set nuisdk.framework to Embed & Sign.
- Open the sample project in Xcode. The sample code is in
DashSambertTTSViewController. Replace the API key and try the feature.
Call procedure
- Initialize the SDK.
- Set the parameters based on your business needs: set the connection parameters through the
parametersparameter of thenui_tts_initializeinterface, and set the speech synthesis effect parameters through thenui_tts_set_paraminterface. - Call
nui_tts_playto start speech synthesis. - Obtain the audio data in the onNuiTtsUserdataCallback callback. We recommend that you use stream playback. To save the audio locally, write the audio to the same file in append mode until the synthesis is complete.
- After the task is complete, call
nui_tts_releaseto release the SDK resources.