目录

com.huawei.hms.mlsdk.tts.MLTtsCallback

Implements the single TTS task playback callback, with which the TTS playback status and error and alarm events are listened to.

Public Method Summary

Return typeMethod name
voidonAudioAvailable(String taskId, MLTtsAudioFragment audioFragment, int offset, Pair<Integer, Integer> range, Bundle bundle)
voidonError(String taskId, MLTtsError err)
voidonEvent(String taskId, int eventId, android.os.Bundle bundle)
voidonRangeStart(String taskId, int start, int end)
voidonWarn(String taskId, MLTtsWarn warn)

Public Methods

Method
public void onAudioAvailable(String taskId, MLTtsAudioFragment audioFragment, int offset, Pair<Integer, Integer> range, Bundle bundle)

Audio stream callback API, which is used to return the synthesized audio data to the app. Default specifications of the real-time audio output data are as follows: PCM mono, 16-bit depth, and 16 kHz audio sampling rate.

For example, if you enter text T for an audio synthesis task, the returned task ID is 1587653499796229, and the text is divided into T1 and T2.

T1 is synthesized into three audio segments: A0, A1, and A2. T2 is synthesized into two audio segments: A3 and A4. Five onAudioAvailable callback events are generated as follows:

onAudioAvailable("1587653499796229", A0, 0, Pair(T1.START, T1.END), null)

onAudioAvailable("1587653499796229", A1, 1, Pair(T1.START, T1.END), null)

onAudioAvailable("1587653499796229", A2, 2, Pair(T1.START, T1.END), null)

onAudioAvailable("1587653499796229", A3, 3, Pair(T2.START, T2.END), null)

onAudioAvailable("1587653499796229", A4, 4, Pair(T2.START, T2.END), null)

Parameters

Parameter nameParameter desc
taskIdID of an audio synthesis task corresponding to an audio.
audioFragmentAudio data.
offsetOffset of the audio segment to be transmitted in the queue. One audio synthesis task corresponds to an audio synthesis queue.
range

Text area where the audio segment to be transmitted is located. range.first (included): start position; range.second (excluded): end position. The unit is character. A single Chinese character is counted as one character.

For example, text "Hello, ML!" is input for an audio synthesis task and will be split into "Hello!" and "ML" parts. The two parts correspond to ranges (0, 5) and (5, 11), respectively.
bundleExtended parameter.
Method
public void onError(String taskId, MLTtsError err)
When an error occurs in a TTS task, this API can be used to listen to error events.

Parameters

Parameter nameParameter desc
taskIdID of a TTS task where an error occurs.
errError details.
Method

public void onEvent(String taskId, int eventId, Bundle bundle)

Audio synthesis task callback extension method.

1. Listens to the playback status. This callback function can be used to listen on the APIs for starting, pausing, resuming, and stopping the playback after speech is generated.

2. Listens to the TTS progress. This callback function can be used to listen on the audio synthesis start, end, and processing completion APIs.

Parameters

Parameter nameParameter desc
taskIdID of a TTS task corresponding to a callback event.
eventId

Callback event ID.

  • Playback-related callback APIs (the following APIs do not take effect when an external player is used):

MLTtsConstants.EVENT_PLAYSTART: called when playback starts.

MLTtsConstants.EVENT_PLAYRESUME: called when playback resumes.

MLTtsConstants.EVENT_PLAYPAUSE: called when playback pauses.

MLTtsConstants.EVENT_PLAYSTOP: called when playback stops. This API carries the parameter interrupted of the boolean type. true: The playback ends abnormally and is interrupted by an external error, for example, the QUEUE_FLUSH mode is used, the stop API is called, or an exception occurs. false: The playback ends normally.

  • TTS-related callback APIs:

MLTtsConstants.EVENT_SYNTHESIS_START: called when audio synthesis starts.

MLTtsConstants.EVENT_SYNTHESIS_END: called when audio synthesis ends.

MLTtsConstants.EVENT_SYNTHESIS_COMPLETE: called when TTS event processing completes. This API is called when OPEN_STREAM is enabled (refer to speak) and all streams are transmitted. This API carries the parameter interrupted of the boolean type. true: The audio synthesis task ends abnormally and is interrupted by an external error, for example, the QUEUE_FLUSH mode is used, the stop API is called, or an exception occurs. false: The audio synthesis task ends normally.

bundle

Extended parameter, which is used together with eventId.

  • When eventName is set to MLTtsConstants.EVENT_PLAY_STOP, the MLTtsConstants.EVENT_PLAY_STOP_INTERRUPTED parameter of the boolean type is carried. The value true indicates that playback is interrupted externally.

  • When eventName is set to MLTtsConstants.EVENT_SYNTHESIS_COMPLETE, the MLTtsConstants.EVENT_SYNTHESIS_INTERRUPTED parameter of the boolean type is carried. The value true indicates that the audio synthesis task is interrupted externally.

Sample Code

  1. switch (eventId){ 
  2.     // Pay attention to the following callback APIs when you use the internal player to play the synthesized audio: 
  3.     case MLTtsConstants.EVENT_PLAY_START: 
  4.         // Called when playback starts. 
  5.         break; 
  6.     case MLTtsConstants.EVENT_PLAY_STOP: 
  7.         // Called when playback stops. 
  8.         boolean isInterrupted = bundle.getBoolean(MLTtsConstants.EVENT_PLAYSTOP_INTERRUPTED); 
  9.         break; 
  10.     case MLTtsConstants.EVENT_PLAY_PAUSE: 
  11.         // Called when playback pauses. 
  12.         break; 
  13.     case MLTtsConstants.EVENT_PLAY_RESUME: 
  14.         // Called when playback resumes. 
  15.         break; 
  16.     // Pay attention to the following callback APIs when you focus on only the synthesized audio data but do not use the internal player for playback: 
  17.     case MLTtsConstants.EVENT_SYNTHESIS_START: 
  18.         // Called when audio synthesis starts. 
  19.         break; 
  20.     case MLTtsConstants.EVENT_SYNTHESIS_END: 
  21.         // Called when audio synthesis ends, and the audio streams may be still being transmitted by calling onAudioAvailable. 
  22.               break; 
  23.     case MLTtsConstants.EVENT_SYNTHESIS_COMPLETE: 
  24.         // Called after all audio streams are transmitted to the player in default internal playback scenarios. 
  25.         // Called when all audio streams are transmitted to the app in OPEN_STREAM and EXTERNAL_PLAYBACK modes. 
  26.         boolean isInterrupted = bundle.getBoolean(MLTtsConstants.EVENT_SYNTHESIS_INTERRUPTED); 
  27.         break; 
  28.     default: 
  29.         break; 
  30.  }
Method
public void onRangeStart(String taskId, int start, int end)

The TTS engine splits the text input by the audio synthesis task. This callback function can be used to listen to the playback start event of the split text.

For example, if you enter text T for an audio synthesis task, the returned task ID is 1587653499796229, and the text is divided into T1 and T2.

When T1 is played: onRangeStart("1587653499796229", T1.START, T1.END)

When T2 is played: onRangeStart("1587653499796229", T2.START, T2.END)

The app can listen on this API to highlight and trace the text that is being played.

Notice:
The end position is not included.

Parameters

Parameter nameParameter desc
taskIdID of a TTS task.
startStart position of an audio segment in the input text.
endEnd position (excluded) in the input text of the current audio synthesis task corresponding to the audio segment.

Sample Code

  1. // The speak API passes the text "Hello Tom!How are you?" 
  2. MLTtsEngine ttsEngine = new MLTtsEngine(null); 
  3. ttsEngine.setTtsCallback(new  new MLTtsCallback() { 
  4.     ... 
  5.     public void onRangeStart(String taskId, int start, int end) { 
  6.         // The SDK calls the APIs as follows: 
  7.         // onRangeStart("1587653499796229", 0, 10); indicates "Hello Tom!" starts to be played. 
  8.         // onRangeStart("1587653499796229", 10, 22); indicates "How are you?" starts to be played. 
  9.     } 
  10.     ... 
  11. }); 
  12. ttsEngine.speak("Hello world!"); // The returned taskId is 1587653499796229.
Method
public void onWarn(String taskId, MLTtsWarn warn)
Implements the callback for alarm events. This API is used only for alarm notifications. Your app can determine whether to ignore the notifications based on service requirements. For example, when the network status is poor, or the bandwidth is insufficient, your app will report WARN_INSUFFICIENT_BANDWIDTH. In this way, you can determine whether to notify the user or ignore the notification.

Parameters

Parameter nameParameter desc
taskIdID of a TTS task where an alarm is reported.
warnAlarm details.

Sample Code

  1. warnId = MLTtsWarn.WARN_INSUFFICIENT_BANDWIDTH.