Offline speech synthesis FAQ

What are the common causes of synthesis initialization failure?

What are the common causes of authentication failure?

Registration may fail for the following reasons:

• Incorrect parameter settings: For example, the AppKey is incorrect, or the project corresponding to the AppKey is a device-side solution.

• Registration limit exceeded: The console limits the number of daily registrations for a single device.

• Insufficient quota: The requested quota exceeds the limit.

• No network connection: Registration requires a network connection.

The following table lists common error messages. You can retrieve these messages from the `error_msg` field when initialization fails.

What do I do if initialization succeeds but playback fails?

Check if the voice package name and path are set correctly. The SDK and the voice package are completely separate. No voice package is pre-installed in the SDK.

What is the relationship between the callback data length and time?

For example, for PCM data with a sample rate of 16000, if each callback returns 8000 bytes, the number of bytes per second is 16000 × sizeof(short) = 32000. Therefore, 8000 bytes corresponds to a duration of 8000 / 32000 seconds = 250 milliseconds.

How is quota consumed?

Each time the device ID changes, one quota is consumed. The device ID is a valid credential for management and control. As an SDK user, you must ensure that the device_id you set is valid and unique. Otherwise, multiple quotas may be consumed, or authentication may fail.

Consider the following scenarios:

• The device ID changes if the app cannot obtain device information at first but obtains it after permissions are granted.

• The device ID changes if a user disables the permission to access the device ID after it has been granted.

• After upgrading to Android Q, the app fails to retrieve valid device information, which causes the Deviceid to change.

How many times can a single Deviceid be registered per day?

A single device ID can be registered only five times per day. If the device has been successfully registered, uninstalling and reinstalling the app will consume one registration attempt. After five attempts are used, you must wait until midnight to register again.

If the app is not uninstalled, how many times is it registered on the first day and the second day?

After the app registers successfully, if it has storage permissions, the authentication information is saved locally. The app does not need to perform online registration again and can be used indefinitely.

Can I increase my quota after it is used up?

If the quota for an AppKey is exhausted, you can purchase an additional quota. The system then increases the quota as specified in the contract.

Can I access online voice services directly after requesting an offline quota?

No. An offline quota does not grant access to online voice services, such as online speech synthesis or online speech recognition. You must purchase online voice services separately.

Can I use an AppKey that is already in use for online voice services to request an offline quota?

Yes. You can use any AppKey except for those for device-side solutions. If you are using an AppKey for a device-side solution, you need to request a new AppKey specifically for speech synthesis. For details, see Create a project.

How does the SDK perform data reporting?

• Why is data reporting performed?

  • To simplify troubleshooting: After an app is published, logs are usually disabled, which limits the information you can obtain. Data reporting makes it easier to troubleshoot problems.

  • To provide a basis for voice optimization: For example, if most users adjust the volume for the `xiaoyun` voice, it indicates that the default volume of the voice package is too low.

  • To collect latency statistics and optimize synthesis speed: If the latency is too high, issues such as stuttering may occur. You can then provide users with an optimization solution. If stuttering occurs on most devices, you can guide users to adjust the algorithm.

• Does adding points affect the main flow?

  No. Data reporting is attempted when initialization succeeds or fails. If there is no network connection, the process exits directly. To reduce resource consumption, the reported data is less than 1 KB.

• What are the components of a data point?

  To minimize resource consumption and fully protect user privacy, the SDK's data reporting does not involve any user information. The main content includes:

  Category	Trigger time	Content
  Initialization error cause	When initialization fails	Detailed information about the initialization failure error_msg: Detailed error message auth_time: Time taken for authentication inittime: Time taken for initialization
  Performance statistics	When initialization succeeds: The user has started synthesis, so the system asynchronously attempts to send statistics from the last synthesis task.	sdk_ver: The SDK version used Voice: Speaker format: The audio format speed: The speech rate volume: The volume latency: The latency, which reflects device performance sample_rate: The sample rate length: The synthesis length call_time: The number of synthesis calls

• Can you disable point logging?

  Data reporting is enabled by default, but the SDK provides an interface to disable it. If you believe it affects your main process or have privacy concerns, you can disable this feature. When generating initialization parameters, pass the enable_et field and set its value to false. The code is as follows:

  /**
     * @brief :Fill in the authentication information in this format.
     * @param assets:The storage path for resources, including configuration files and resource files.
     * @return std::string :The authentication information packaged in JSON format.
     */
    std::string GenAuthInfo(const char *assets) {
      nuijson::Value root;
      std::string info;
      if (assets) {
        /*
         * Before calling the interface, configure environment variables to read access credentials.
         * The environment variable names for the AccessKey ID, AccessKey secret, and AppKey of Intelligent Speech Interaction are: NLS_AK_ENV, NLS_SK_ENV, and NLS_APPKEY_ENV.
         */
        root["ak_id"] = getenv("NLS_AK_ENV");  // The ak_id is the AccessKey ID of your Alibaba Cloud account. It corresponds to the ak_secret. Do not set it to your Alibaba Cloud account ID (UID).
        root["ak_secret"] = getenv("NLS_SK_ENV");
        root["app_key"] = getenv("NLS_APPKEY_ENV");
        root["workspace"] = assets;
        root["sdk_code"] = "software_nls_tts_offline";  // Offline TTS uses software_nls_tts_offline.
        root["device_id"] = "012345678911a";   // A unique device identifier, such as a MAC address or CPU serial number.
        root["enable_et"] = "false";   // Data reporting is enabled by default. Set this parameter to false to disable it.
        nuijson::FastWriter writer;
        info = writer.write(root);
        printf("info:%s\n", info.c_str());
      }
      return info;
    }

• Instrumentation example

  • The following is an example of reported data for an initialization error:

  {
    "common": {
      "appcode": "026",
      "funcode": "6888",  // Features supported by the SDK.
      "sdk_code": "software_nls_tts_offline",
      "sdk_ver": "V2.5.14-026-20210327"  // The corresponding SDK version number.
    },
    "content": {
      "tts": [
        {
          "auth_time": "277",   // Authentication took 277 ms. This value provides a valid basis for monitoring the authentication service.
          "error_msg": "(170007)Specified access key is not found.-->(170800)register-failed-->(140008)tts-auth failed",  // Detailed error message. It is clear that the user did not set an AppKey, which speeds up troubleshooting.
          "init_time": "277"    // The total initialization time, including authentication and resource loading.
        }
      ]
    }
  }

  • The following is an example of reported data for statistics:

  {
    "common": {
      "appcode": "026",
      "funcode": "4840",
      "sdk_code": "software_nls_tts_offline",
      "sdk_ver": "V2.5.14-026-20210326"
    },
    "content": {
      "tts": [
        {
          "call_time": "1",
          "font": "xiaoyun",
          "format": "pcm",
          "latency": "6",
          "length": "168640",
          "mode": "local",
          "pitch": "0",
          "sample_rate": "16000",
          "speed": "1",
          "volume": "1"
        }
      ]
    }
  }

What is the role of NTP?

NTP stands for Network Time Protocol.

When you first use the Text-to-Speech (TTS) SDK, it needs to access Alibaba Cloud for authentication. Alibaba Cloud requires that the time difference between your local time and Alibaba Cloud's time not exceed 15 minutes. Otherwise, authentication will fail. Therefore, the SDK uses the NTP module to obtain the network time.

Note that NTP itself consumes time when interacting with Alibaba Cloud. This can take more than ten seconds if the network connection is poor. You should evaluate your business needs. If you do not expect the time on the device to be abnormal, or if the low probability of a time anomaly does not affect your business, you can disable NTP. To do this, set enable_ntp to false during initialization.