SDK FAQ

How do I configure custom hotwords through an SDK?

A custom hotword vocabulary configured in the console is associated with the project Appkey and does not need to be configured again in code. For a vocabulary created through the POP API, specify its vocabulary ID in the SDK. A vocabulary specified in code takes precedence over the console setting.

For short-sentence recognition, real-time transcription, and recording file recognition, see Configure custom hotwords through an SDK.

How do I troubleshoot DNS resolved timeout?

Check the nameserver settings in /etc/resolv.conf. You can add nameserver 114.114.114.114 and give it priority.

Set a custom language model with the SDK

If you create a custom language model in the console, you can select the model when you switch models for a project. After you publish the model, it is automatically bound to the Appkey and you do not need to configure it in your code. However, if you obtain a custom language model by using a POP API, you must set its model ID in the SDK to use the model. For more information about how to set a custom language model for Short Sentence Recognition, Real-time Speech Recognition, and Audio File Transcription, see Set a custom language model by using SDK 2.0.

Android and iOS SDKs for Apsara Stack

Yes, SDKs are available but are not included in the Apsara Stack installation package by default. You can download them from the service documentation on the Alibaba Cloud Help Center, such as the Android SDK and iOS SDK for Real-time Speech Recognition. These mobile SDKs can call public cloud ASR and Text-to-Speech services and can also be used in an Apsara Stack environment.

How do I use and refresh a token?

A public cloud token can be reused across projects, processes, and threads within the same account. Obtain a new token before it expires. Obtain tokens on the server and let clients request them from the application server instead of storing AccessKey credentials on clients. See Obtain a token by using an SDK.

The default token for a private cloud deployment is default and does not need to be changed.

The WeChat mini program SDK checks local storage when getToken() is called. Its cache key concatenates the AccessKey ID, &, and AccessKey Secret. It reuses a valid cached token and requests a token if the cache is missing or expired; it does not refresh tokens on a background timer. In production, manage AccessKey credentials and tokens on the application server.

New token invalidation

No, obtaining a new token does not invalidate an existing one. A token's validity is determined solely by its expiration time. You can get the expiration time from the ExpireTime parameter in the server's response message. For more information, see Token Protocol Description.

Must I recreate a Java NlsClient when its token expires?

Token expiry alone does not require recreating NlsClient, but a new connection still requires a valid token. Reuse the client, obtain a new token before expiry, and update it with NlsClient.setToken().

Service IP allowlist

We do not provide an IP allowlist because the server IPs change dynamically with scaling and machine replacements, making any static list quickly outdated. Instead, we recommend adding access rules for the following domains on ports 80 and 443: nls-meta.cn-shanghai.aliyuncs.com and nls-gateway-cn-shanghai.aliyuncs.com.

Control logging and save audio

The SDK provides multi-level log control, which you can configure in the initialization API.

It also allows you to save audio data to help diagnose issues. To do this, set the save_wav and debug_path initialization parameters. For more information, see API Reference.

API call limitations

The SDK encapsulates access to the speech services. You only need to call the start method and handle the appropriate events in the callbacks, typically for errors and recognition results. Do not call SDK methods directly within a callback, as this may cause a deadlock.

Why must recognition start before audio is sent?

Establish a connection and start the recognition task before sending audio. Synchronous and asynchronous behavior and callback names vary by SDK. Wait for the success result or event specified by that SDK before sending audio. At the end of the task, send the appropriate stop directive and receive the completion event.

Framework linking issues

The framework's code is a mix of Objective-C and C++. Therefore, you must use a file with a .mm extension to call it. Also, ensure that the header and library search paths in your project are set correctly.

Diagnose SDK errors

When the SDK reports an error, check the error code first. It usually provides a general idea of the problem.

Does the WeChat mini program SDK support real-time transcription?

Yes. The WeChat mini program SDK provides SpeechTranscription. Start the task with start(), send audio chunks with sendAudio(), and receive results through recognition events.

How do I specify a synthesis voice?

Specify the target voice through the SDK voice parameter, such as setVoice() in the Java SDK. Use a voice name supported by the interface being called. A voice selected on a console experience page is not a substitute for the voice setting in code.

Get the taskID in the Real-time Speech Recognition Go SDK

The taskID is found in the header.task_id field of the JSON data returned by the callback function. Example structure:

{
  "header": {
    "task_id": "fba2f3db6e7e42bc804c2d99295db109",
    "namespace": "SpeechTranscriber",
    "name": "TranscriptionStarted",
    "status": 20000000
  }
}

Parse the header.task_id field from the callback's JSON response to retrieve the task ID.

How do I retain transcription results after a page refresh?

Results stored only in page memory are lost on refresh. Save received text to persistent storage such as IndexedDB, then read it and restore the display when the page reloads. The application is responsible for this persistence logic.

How do I choose a mobile SDK variant?

Variant codes such as 039 and 01B identify different combinations of capabilities. Compare the capability table on the SDK download page against the required recognition, synthesis, and on-device features. Also check the specific version and integration requirements when choosing an integrated or renamed package.

Can I integrate a local Android SDK AAR through Gradle?

Yes. Gradle supports local AAR dependencies. Place the AAR from the downloaded SDK package in the project dependency directory and configure a local file dependency.

send() method parameters and usage

In the Java SDK, both Short Sentence Recognition and Real-time Speech Recognition provide three overloaded send() methods:

public void send(InputStream ins);
public void send(InputStream ins, int batchSize, int sleepInterval);
public void send(byte[] data);

When using these methods, you must send audio data to the server continuously and in real time.

The demo simulates a real-time audio stream by sending audio from a file. Typically, a chunk of audio data is sent every 100 ms or 200 ms (sleepInterval). The size of each chunk (batchSize) depends on the sampling rate. A long sending interval can cause high latency and connection drops, while a short interval can consume excessive server and network resources. You can experiment to find an optimal value.

For the second method, the ins parameter is the simulated audio stream, and you need to control the sending rate. For a 16 kHz sampling rate, send 3,200 bytes from ins every 100 ms. Example call:

recognizer.send(ins, 3200, 100); // For 16 kHz audio

For the third method, the data parameter is the chunk of data to be sent in one go. You control the interval between calls in a loop. Example call:

recognizer.send(data); // 100 ms of audio data
try {
 Thread.sleep(100);
} catch (InterruptedException e) {
 e.printStackTrace();
}

Analyze latency with SDK logs

The following examples use Java SDK logs.

• For Short Sentence Recognition, latency is the time from when an utterance ends to when the final recognition result is received.

  Search for the keywords StopRecognition and RecognitionCompleted in the logs to find the log entries for when audio sending finishes and when recognition completes. The time difference is the latency recorded by the SDK. In the following logs, the latency is 662 - 528 = 134 ms.

  22:21:28.528 DEBUG [           main] [c.a.n.c.transport.netty4.NettyConnection] thread:1,send:{"header":{"namespace":"SpeechRecognizer","name":"StopRecognition","message_id":"b9dc****","appkey":"ubwk****","task_id":"cd5c****"}}
  22:21:28.662 DEBUG [ntLoopGroup-2-1] [  c.a.n.c.p.asr.SpeechRecognizerListener] on message:{"header":{"namespace":"SpeechRecognizer","name":"RecognitionCompleted","status":20000000,"message_id":"a27e****","task_id":"cd5c****","status_text":"Gateway:SUCCESS:Success."},"payload":{"result":"the weather in beijing will be sent it tomorrow","duration":2183}}

• For Text-to-Speech, the key metric is first-packet latency, which is the time from sending the synthesis request to receiving the first audio packet.

  Search the logs for the keywords send and tts first latency. The time difference between the two entries is the first-packet latency. In the following logs, the latency is 355 - 190 = 165 ms.

  22:21:51.190 DEBUG [           main] [c.a.n.c.transport.netty4.NettyConnection] thread:1,send:{"payload":{"volume":50,"voice":"siyue","pitch_rate":100,"sample_rate":16000,"format":"wav","speech_rate":100,"enable_subtitle":false,"text":"The weather in Beijing will be sunny tomorrow."},"context":{"sdk":{"name":"nls-sdk-java","version":"2.1.6"},"network":{"upgrade_cost":107,"connect_cost":59}},"header":{"namespace":"SpeechSynthesizer","name":"StartSynthesis","message_id":"ab94****","appkey":"ubwk****","task_id":"cd5c****"}}
  22:21:51.355 INFO [ntLoopGroup-2-1] [c.a.nls.client.SpeechSynthesizerDemo] tts first latency : 165 ms

• The logs for the Real-time Speech Recognition SDK are similar to those for Short Sentence Recognition. You can calculate the end-of-speech latency from the logs using the keywords StopTranscription and TranscriptionCompleted.

• For RESTful API calls, the client-side logs do not show latency. You need to write custom code to measure it or check the server-side logs.

Missing com.alibaba JAR package

See Original SDK User Guide to install Alibaba Cloud SDK for Java.

What does a completion timeout in SpeechRecognizer.stop() mean?

timeout after 10 seconds waiting for complete confirmation. state: STATE_STOP_SENT means that the stop directive was sent but completion was not confirmed within the wait period. The state itself does not mean the connection is closed. Check network stability and request and callback logs around the stop directive. Intermittent failures may be related to network fluctuations.

Troubleshoot the Audio File Transcription demo

1. Verify that the region where you enabled Intelligent Speech Interaction matches the region specified in your code. In the Intelligent Speech Interaction console, confirm that the current region (for example, China (Shanghai)) is the same as the region configured in your code. Also, check that the status of the required service (for example, Audio File Transcription) is Enabled.

   private static String appKey = "Your AppKey";
   private static String accessKeyId = "Your AccessKey ID";
   private static String accessKeySecret = "Your AccessKey Secret";
   private static String REGION_ID = "cn-shanghai";

2. Check the dependency versions for the fastjson and aliyun-java-sdk-core libraries. The Alibaba Cloud Java SDK core library must be version 3.5.0 or later. If you use version 4.0.0 or later, you may need to add corresponding third-party dependencies as indicated by error messages. For more information, see Audio File Transcription Java SDK.

   <dependency>
       <groupId>com.aliyun</groupId>
       <artifactId>aliyun-java-sdk-core</artifactId>
       <version>3.7.1</version>
   </dependency>
   <dependency>
       <groupId>com.alibaba</groupId>
       <artifactId>fastjson</artifactId>
       <version>1.2.83</version>
   </dependency>

Which recording file recognition interface does the Android SDK provide?

The Android SDK provides startFileTranscriber for the short-latency recording file recognition service. Do not confuse it with the asynchronous submission and query interfaces of standard recording file recognition. Identify the service variant before choosing an integration method.

How does the Java SDK signal the end of audio input?

Short-sentence recognition uses SpeechRecognizer, whereas real-time transcription uses SpeechTranscriber. Do not mix their termination rules. After sending audio, call stop() on the corresponding object to end input and wait for the final result or completion callback. enable_intermediate_result=true controls intermediate results; it does not replace the stop directive.

Trigger the onTranscriptionComplete callback

Calling stop() triggers the onTranscriptionComplete callback. The state changes to STATE_STOP_SENT, and after the callback is processed, the state becomes STATE_COMPLETE.

Resolve the "invalid token" error

java.lang.IllegalStateException: complete already: DefaultChannelPromise@75822ea8(failure: java.lang.Exception: WebSocket Client failed to connect,status:403 Forbidden,reason:Meta:ACCESS_DENIED:The token '***' is invalid!)"

This error indicates that the token is invalid. Generate a new token. For more information, see Obtain a token.

SpeechSynthesizer creation failure (ClosedChannelException)

java.nio.channels.ClosedChannelException

We recommend you test the demo in a new, empty project within a Java environment. If the demo runs without issues, the issue is likely in your client-side integration, not the SDK.

Where can I get Java SDK dependencies for recognition and synthesis?

Configure dependencies according to the relevant Java SDK documentation. For real-time transcription dependencies and examples, see Real-time transcription Java SDK.

Resolve the "hostname can't be null" error

ERROR NlsClient:102 - failed to connect to server after 3 tries,error msg is :hostname can't be null

If you are not using the demo, you must specify the hostname, which is the endpoint of the Alibaba Cloud speech service.

For endpoint details, see wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1 or Real-time Speech Recognition Java SDK.

Resolve ClosedChannelException in speech synthesis

java.nio.channels.ClosedChannelException at io.netty.channel.AbstractChannel$AbstractUnsafe.ensureOpen(...)

If a TaskId is not generated, the request did not reach the server. This typically points to a local environment issue. Check your local network and environment, and compare your implementation with the official demo.

Resolve the "JSONArray.iterator()" error

Ensure that all required dependency packages are included. Find and add the following two dependencies.

<dependency>
<groupId>org.json</groupId>
<artifactId>json</artifactId>
<version>20170516</version>
</dependency>

<dependency>
<groupId>com.google.code.gson</groupId>
<artifactId>gson</artifactId>
<version>2.8.2</version>
</dependency>

Upload an audio file for recognition

The SDK example demonstrates how to upload an audio file for recognition by calling a RESTful API. For more information, see Short Sentence Recognition Java SDK.

// The SDK example demonstrates how to upload an audio file for recognition by calling a RESTful API.
String result = SpeechFlashRecognizer.submit(url, appKey, token);

Recognition failure with a custom audio file

Use the file command to check if your audio format meets the product requirements. The standard format for 8K models is 8 kHz sampling rate, 16 bit sample size, and mono WAV. The standard format for 16K models is 16 kHz sampling rate, 16 bit sample size, and mono WAV. For testing, you can use tools like Sox or FFmpeg to convert your file to the standard format. For production use, refer to the relevant product documentation.

See the API Reference for Real-time Speech Recognition for an example.

The Real-time Speech Recognition API supports the following audio format parameters: the sampling rate (sample_rate) supports 8000 and 16000, the audio encoding format (format) supports pcm, wav, opus, and opu, the sample size is 16 bit, and the number of channels is mono.

How do I troubleshoot a missing class after adding a Maven dependency?

Check that the project includes the dependency containing the class, and verify its version, scope, and runtime classpath. If these settings are correct, reload the Maven project and clear the IDE cache if necessary.

How do I configure connection timeout when creating a Java FlowingSpeechSynthesizer?

The FlowingSpeechSynthesizer constructor establishes a connection. In Java SDK 2.2.19, NlsClient supports the nls.ws.connect.timeout system property in milliseconds, with a default of 5000. Set it before the NlsClient class is initialized. Connections may be retried, so the per-attempt timeout is not the total constructor duration. The constructor can also throw an exception directly; handle it at the call site instead of relying only on an error callback.

UTF-8 encoding error in speech synthesis

If the input text contains Chinese characters and is not UTF-8 encoded, the start function call in the Text-to-Speech SDK will fail and return the error message Socket recv failed, errorCode: 0. An error code of 0 means the server closed the connection. In this case, verify that the text is UTF-8 encoded.

Obtain a token with the C++ SDK

For more information, see Obtain a token.

After downloading, you will get the NlsCommonSDK directory, which contains the lib/ and include/ subdirectories.

The downloaded C++ token SDK provides NlsCommonSDK, which includes functions for obtaining a token and for Audio File Transcription.

NlsCppSDK (versions 3.0.X and the older 2.X) does not include NlsCommonSDK. It supports Real-time Speech Recognition, Short Sentence Recognition, and Text-to-Speech. For these older NlsCppSDK versions, you must obtain a token separately as described above.

NlsCppSDK (versions 3.1.X and later) includes NlsCommonSDK. It supports obtaining a token, Audio File Transcription, Real-time Speech Recognition, Short Sentence Recognition, and Text-to-Speech, so a separate token SDK download is not required. A valid token is still required for service calls.

Real-time Speech Recognition API call failure

1. This issue occurs rarely in C++ SDK versions 3.0 and earlier and can be ignored. In version 3.1 and later, this issue is likely caused by network problems in the runtime environment. Check your local network environment.

2. If a TaskId is not returned, it means the connection was dropped during the connection process. You do not need to repeatedly call the Real-time Speech Recognition API. Repeated calls are subject to concurrency limits and timeouts. If the concurrency limit is exceeded, an error is returned immediately. A WebSocket connection will automatically disconnect if no audio is received for 10 seconds, but it will return a TaskId.

3. This situation is often caused by network congestion. Use a packet capture tool to check for tcp retransmission. You can run the traceroute command or use an MTR tool on the client to test the link to nls-gateway-cn-shanghai.aliyuncs.com and determine if the network connection to the service endpoint is unstable.

Resolve the "appkey not set" error

OnSynthesisTaskFailed: status code=10000002 task id=***error message={TaskFailed":"{"task_id":"00000000000000000000000000000000","result":"","status":40000003,"message":"Gateway:PARAMETER_INVALID:appkey not set"}"}"

A status of 40000003 indicates an invalid parameter. Double-check that the parameters you passed, such as appkey, voice, and url, are correct.

GCC version compatibility

Yes. On Linux, GCC 4.8.5 or later is supported. We have verified that the SDK compiles and runs successfully with GCC versions 4.8.5, 5.5.0, and 8.4.0.

Where do g_akid and g_akSecret in speechRecognizerDemo.cpp come from?

These variables hold the AccessKey ID and AccessKey Secret used to obtain an NLS token. For credentials and token retrieval, see Obtain a token by using an SDK. Do not commit real credentials to a code repository.

Resolve the idle timeout error

status_text:Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time, the last directive is 'StartTranscription'!

1. This error occurs because the connection timed out and was automatically closed after 10 seconds of inactivity. Also, verify that the URI is correct: wss://nls-gateway-cn-shanghai.aliyuncs.com/ws/v1. If this happens, implement a retry mechanism to retry the request.

2. This can also happen if the server receives too many concurrent requests, preventing it from processing your request in time. We recommend retrying the request.

Custom timestamp for token generation

No. The token must be generated based on the system time.

Resolve DNS resolution failures

ali-recog-skd.log:AliSpeech_C++SDK(ERROR): GetInetAddressByHostname:252 DNS: resolved timeout.ali-recog-skd.log:AliSpeech_C++SDK(ERROR): start:76 start failed: DNS: resolved timeout..unimrcpserver_current.log: [ERROR] [[./ali/AliRecogChannel.cpp:772,onTaskFailed]]Ali Task start failed Msg :DNS: resolved timeout., start finised."

• Older versions: This issue is more likely to occur under high concurrency or when the system's DNS is busy. We recommend updating to version 3.1.X or retrying the request.

• Updated versions: A defense mechanism has been added for this issue. If it still occurs occasionally, it is due to a busy system DNS, and you should retry the request.

How do I investigate error 10000002 in the C++ SDK?

10000002 is the C++ SDK's generic DefaultErrorCode, not an OpenSSL error code that identifies a single cause. Check the detailed callback error, the last directive sent, and connection logs. If IDLE_TIMEOUT is also reported, check the audio transmission sequence against that task's idle timeout behavior.

Compilation failure after changing _GLIBCXX_USE_CXX11_ABI

This parameter needs to be changed for the entire project, not just in CMakeLists.txt. For example, you also need to modify config/linux.thirdparty.debug.cmake and config/linux.thirdparty.release.cmake. Search the entire directory for _GLIBCXX_USE_CXX11_ABI and modify all instances.

Resolve the "missing nlsCommonSdk.dll" error

The nlsCommonSdk.dll is not part of SDK versions 3.1 and later.

Difference between NlsSdkCpp2.0 and NlsSdkCpp3.X

In NlsSdkCpp2.0, each request runs in a separate thread, and the API is synchronous.

In NlsSdkCpp3.X, a third-party library, libevent, handles all event messages, providing better concurrency performance. The API is asynchronous.

How does _GLIBCXX_USE_CXX11_ABI differ from C11 and C++11?

_GLIBCXX_USE_CXX11_ABI selects the old or new libstdc++ ABI. It does not enable the C11 or C++11 language standard. The application, SDK, and dependent libraries must use compatible ABI settings. The original project defaults to 0. If the new ABI is required, check build settings throughout the project and its dependencies rather than changing a single macro.

Resolve "invalid token" and call order errors

Meta:ACCESS_DENIED:The token '' is invalid!, start finised.start() failed.CbParam: 1 exg.onTaskFailed: status code: 10000011, error message: Stop invoke error. Please check the order of execution or whether the data sent is valid.

The message Meta:ACCESS_DENIED:The token '' is invalid!, start finised. means the token is invalid and authentication failed. Check if the appkey is incorrect, if a token was provided, or if the token has expired. The message status code: 10000011 indicates an incorrect order of API calls. This error is reported if you call the send method after the SDK has already closed the connection upon receiving a Failed or Complete event.

Resolve the "certificate verify failed" error

transcriber process start...alispeech-DEBUG start:60 starting transcriber...alispeech-WARNING _on_error:123 retry start: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed (_ssl.c:852)alispeech-DEBUG _on_close:110 callback on_channel_closedMyCallback.OnRecognitionChannelClosed

This indicates an SSL certificate verification failure. Check that the system time on the calling machine is correct.

Resolve error 40000004 after calling stop()

{"header":{"namespace":"Default","name":"TaskFailed","status":40000004,"message_id":"xxxxxxxxxxxxxxxxxxxxxxxxx","task_id":"xxxxxxxxxxxxxxxxxxxxxxxxx","status_text":"Gateway:IDLE_TIMEOUT:Websocket session is idle for too long time, the last directive is 'StopRecognition'!"}}

This may happen if the server receives a large number of requests at once, preventing it from processing a specific request in time. We recommend retrying the request.

DNS resolution failure during project integration

1. The SDK attempts DNS resolution using all enabled protocol families (IPv4, IPv6) on the device. Because nls-gateway-cn-shanghai.aliyuncs.com does not support IPv6, the resolution fails, causing the SDK to exit. You can disable the IPv6 protocol family on your device. Future C++ SDK versions will make this configurable.

2. We recommend upgrading to version 3.1.12 or later.

Network connection failure during project integration

This indicates a network connection failure. The logs show that the IP address resolved by DNS is unreachable, which can be confirmed by a ping test. This issue is caused by local DNS interception, which causes the SDK's internal libevent function evdns_getaddrinfo to obtain an incorrect IP address.

Solutions:

• For versions before 3.1.12, manually replace evdns_getaddrinfo() with the system's getaddrinfo().

• For version 3.1.12, modify CMakeLists.txt by adding add_definitions(-DNLS_USE_NATIVE_GETADDRINFO).

• Versions 3.1.12 and later include the setDirectHost() API. You can perform DNS resolution outside the SDK and pass the correct IP address using this API.

• Versions 3.1.13 and later have resolved this issue. If the problem persists at runtime, call the setUseSysGetAddrInfo(true) API.

TTS demo WAV file generation failure

ERROR alibabaNlsLog: [ID:15284][AlibabaNls::ConnectNode::parseFrame:1014]Node:000001D733079F20 Result conversion failed.**

The demo included in NlsSdkCpp3.X-20210629 is not suitable for Windows. Use the demo from the alibabacloud-nls-cpp-sdk repository on GitHub, which is intended for Windows.

Opus audio support in Real-time Speech Recognition

Short Sentence Recognition and Flash ASR support Opus data. However, Real-time Speech Recognition only supports PCM-encoded, 16-bit, mono audio. For more information, see API Reference.

Automatic reconnection on network disconnection

No, the SDK will not reconnect automatically after a network disconnection. You must implement a retry mechanism to reconnect.

What is the minimum Android version?

Mobile SDK 2.7.4 requires Android 5.0 or later, API level 21. For other SDK packages, follow the requirements for that specific version.

Can I query a Flash ASR task by task ID?

Flash ASR does not support querying task status by task ID.

Callbacks not received in Flash ASR

You need to verify the following:

• Whether the resource files were copied successfully.

• Whether the CommonUtils.copyAssetsData function was called.

Recognition issues with 8K models

Recognition accuracy depends on your parameter settings. Check the following:

• Ensure the nls_config.put("sr_format", "pcm") parameter value is in lowercase.

• Ensure the static variable SAMPLE_RATE is set to 8000: public final static int SAMPLE_RATE = 8000.

• Ensure that the 8K model is correctly selected.

Resolve initialization error 240021

This error code indicates a FILE_ACCESS_FAIL error. Check the following:

• Whether your app has file read/write permissions.

• Whether the SDK configuration files have been copied. The following code shows an example of how to check if the copy operation is complete.

if (CommonUtils.copyAssetsData(this)) {
Log.i(TAG, "copy assets data done");
} else {
Log.i(TAG, "copy assets failed");
return;
}

Unnatural pauses in offline speech synthesis

You can try using SSML to control the pauses. For more information, see Introduction to SSML.

ANR when calling cancel in Text-to-Speech

The SDK methods are synchronous. Do not call them from the main thread.

Does real-time transcription require a specific Android version?

Yes. Requirements depend on the SDK package version. For example, mobile SDK 2.7.4 requires Android 5.0 or later, API level 21.

Resolve the "audio recoder not init" error

You can troubleshoot this issue by checking the following:

• Verify that AudioRecord is initialized correctly.

• Check if there is an issue with the audio player.

• Write a separate piece of code that only uses AudioRecord to test if recording works normally.

Application crashes on simulators

Simulators can have unexpected issues. We recommend testing on a physical device.

Callback delay and error 50000000

This indicates an internal server error. Please retry the request.

Resolve TTS error 140002

tts event:TTS_EVENT_ERROR ret 140002

We recommend you check if the input text is valid.

Troubleshoot the Text-to-Speech SDK

Check if the following conditions are met:

• Ensure that you have met all the prerequisites for the Text-to-Speech Android SDK. For more information, see Prerequisites.

• Check if you have enabled the commercial version of the service.

Background processing

The SDK itself does not restrict foreground or background execution. However, the iOS SDK sample project only supports foreground processing by default. To enable background processing, make the following changes:

1. In your project's Info.plist file, add the Required background modes setting. Under this setting, add an item with the value App plays audio or streams audio/video using AirPlay. The type for this setting is an Array.

2. In your recording module, do not stop recording when the app enters the background. In other words, do not call the stop recording method in the _appResignActive interface of NLSVoiceRecorder.m.

   - (void)_appResignActive {
       // Do not stop recording when entering the background.
       // [self stop];
   }

App fails to run on a real device

Reason: no suitable image found. Did find:xxx

We recommend deleting the corresponding app from your device, running xcode clean, and then trying to run the app again. Additionally, check your code signing. If the signature is incorrect, revoke your original in-house certificate, create a new certificate and provisioning profile, re-sign your code, and package the app again.

Resolve MIC errors when running NuiSdk

Check if the recording device is currently being used by another application.

Header file import failure

This is usually caused by an incorrect SDK import. In your Xcode project's Frameworks, Libraries, and Embedded Content section, confirm that nuisdk.framework has been added and set to Embed & Sign. If it is already configured correctly, try changing the header import statement to #import <nuisdk/NeoNui.h>.

Resolve framework build errors

This may be due to a high Xcode version. Try changing your project's Validate Workspace setting to Yes and then recompiling.

Using the Legacy Build System

We recommend changing your project's Validate Workspace setting to Yes and then recompiling.

Resolve "Embed & Sign" errors

Check if the header file was imported correctly as described in the documentation. The correct import format is #import <nuisdk/NeoNui.h>.

Resolve "Unsupported Architectures" error on submission

Unsupported Architectures. The executable for AliYunSmart.app/Frameworks/nuisdk.framework contains unsupported architectures '[x86_ _64, i386]'. With error code

This is likely caused by the inclusion of simulator architectures. You can use the following method to check the framework's architectures and remove the ones for the simulator.

1. Navigate to the framework's directory.

2. Run the command lipo -info xxxFramework to view the framework's architectures. If it includes simulator architectures, you must remove them before submission.

Resolve microphone conflicts with TRTC

Try using TRTC's audio/video stream, get the MediaStreamTrack object using localStream.getAudioTrack, convert it to an ASR-compatible audio stream, and then send a request using the speech recognition SDK.

Audio playback in the background

Audio playback is not possible after the app has been terminated.

Get timestamp information in TTS

By default, the SDK does not return timestamps. To get timestamp information, use the setparamTts method to set enable_subtitle. For more information, see API Reference.

Save synthesized audio to a file

You can save the synthesized data to a file within the onNuiTtsUserdataCallback interface. The format of the synthesized audio is determined by the output parameter, for example, [nls_config setObject:@"mp3" forKey:@"encode_type"].

Supported formats are PCM, WAV, and MP3. Note that the audio player in the Text-to-Speech documentation examples does not support the MP3 format, and using it directly may produce noise. However, you can listen to the saved MP3 file with a player that supports MP3. If the synthesized audio seems to be missing words, the synthesis speed of the selected voice (such as xiaoyun) might be too fast, causing some data to be discarded before being written to the file. You can call fflush after fwrite to ensure all data is written to the file.

- (void)onNuiTtsUserdataCallback:(NSString *)info infoLen:(int)infoLen buffer:(NSData *)data len:(int)len {
    fwrite(data.bytes, 1, data.length, tts_file);
    fflush(tts_file);
}

App termination on rapid playback

Online synthesis requires a network connection, and network conditions can directly affect API response times. If your business requires quickly stopping one task and starting the next, you can adjust the network timeout according to your business needs.

Resolve "Undefined symbols" error with Flutter

Undefined symbols for architecture arm64: "std::__1::mutex::~mutex()", referenced from: ___cxx_global_var_init in libflutter_tts.a(ringBuf.o)

Open the Podfile in your iOS project, modify the post_install do |installer| section with the following code, and then rebuild the project.

post_install do |installer|
  installer.pods_project.targets.each do |target|
    target.build_configurations.each do |config|
      config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
      config.build_settings['CLANG_CXX_LANGUAGE_STANDARD'] = 'gnu++17'
    end
  end
end

Why does the offline Aijia voice sound different during playback?

The Ai-series voices, including Aijia, synthesize audio at 24000 Hz. Playing that audio at 16000 Hz changes how it sounds. Set the player to the actual audio sample rate of 24000 Hz.

Audio plays as noise

First, confirm the synthesized audio format (PCM, WAV, or MP3). If the saved audio stream is in MP3 format but the player does not support it, you will hear noise. Try a different media player. Some users also report noise only at the end of the audio. Use a tool like BeyondCompare to inspect the audio stream and check for accidentally included log data.

How do I send audio over WebSocket and choose a chunk size?

Control directives use JSON text frames with header and payload. Send audio in binary frames, without wrapping it in JSON.

Choose chunk size according to sample rate, bit depth, channel count, and transmission interval. For example, 100 ms of 16 kHz, 16-bit mono PCM is 3200 bytes; at 8 kHz, it is 1600 bytes. These are examples calculated from audio duration, not the only permitted chunk sizes.

Resolve the "Invalid message id" error

When using WebSocket, you are constructing the request yourself. The message_id is a 32-character unique ID that you generate.

You need to change the message_id to a 32-character hexadecimal string and check if the sent message conforms to the required format.

How do I troubleshoot a WebSocket closure without a clear error?

Check that the token is valid and audio is sent promptly according to the task protocol. Record server error events, the close code, and the close reason to distinguish authentication, audio transmission, and network issues.

Get message_id and task_id in WebSocket

You generate the message_id and task_id on the client side.

Both message_id and task_id can be 32-character unique IDs. Within a single task, the task_id should remain constant to uniquely identify the task. We recommend generating a new random message_id for each message you send to uniquely identify that message.

Does real-time transcription require a local audio file?

No. Examples read a local file to simulate a live audio stream. An application can capture audio continuously and send binary audio over WebSocket according to the protocol. Follow the audio format and control directive requirements in Real-time transcription API reference.