https://source.android.com/ 
// Copyright 2011 Google Inc. All Rights Reserved.

package android.speech.tts;

import android.media.AudioFormat;


Listener for events relating to the progress of an utterance through the synthesis queue. Each utterance is associated with a call to TextToSpeech.speak or TextToSpeech.synthesizeToFile with an associated utterance identifier, as per Engine.KEY_PARAM_UTTERANCE_ID. The callbacks specified in this method can be called from multiple threads. 
/**
 * Listener for events relating to the progress of an utterance through
 * the synthesis queue. Each utterance is associated with a call to
 * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} with an
 * associated utterance identifier, as per {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID}.
 *
 * The callbacks specified in this method can be called from multiple threads.
 */
public abstract class UtteranceProgressListener {
    
Called when an utterance "starts" as perceived by the caller. This will be soon before audio is played back in the case of a TextToSpeech.speak or before the first bytes of a file are written to the file system in the case of TextToSpeech.synthesizeToFile. 
Params:
  • utteranceId – The utterance ID of the utterance.
/**
     * Called when an utterance "starts" as perceived by the caller. This will
     * be soon before audio is played back in the case of a {@link TextToSpeech#speak}
     * or before the first bytes of a file are written to the file system in the case
     * of {@link TextToSpeech#synthesizeToFile}.
     *
     * @param utteranceId The utterance ID of the utterance.
     */
    public abstract void onStart(String utteranceId);

    
Called when an utterance has successfully completed processing. All audio will have been played back by this point for audible output, and all output will have been written to disk for file synthesis requests. This request is guaranteed to be called after onStart(String). 
Params:
  • utteranceId – The utterance ID of the utterance.
/**
     * Called when an utterance has successfully completed processing.
     * All audio will have been played back by this point for audible output, and all
     * output will have been written to disk for file synthesis requests.
     *
     * This request is guaranteed to be called after {@link #onStart(String)}.
     *
     * @param utteranceId The utterance ID of the utterance.
     */
    public abstract void onDone(String utteranceId);

    
Called when an error has occurred during processing. This can be called at any point in the synthesis process. Note that there might be calls to onStart(String) for specified utteranceId but there will never be a call to both onDone(String) and onError(String) for the same utterance. 
Params:
  • utteranceId – The utterance ID of the utterance.
Deprecated:Use onError(String, int) instead
/**
     * Called when an error has occurred during processing. This can be called
     * at any point in the synthesis process. Note that there might be calls
     * to {@link #onStart(String)} for specified utteranceId but there will never
     * be a call to both {@link #onDone(String)} and {@link #onError(String)} for
     * the same utterance.
     *
     * @param utteranceId The utterance ID of the utterance.
     * @deprecated Use {@link #onError(String,int)} instead
     */
    @Deprecated
    public abstract void onError(String utteranceId);

    
Called when an error has occurred during processing. This can be called at any point in the synthesis process. Note that there might be calls to onStart(String) for specified utteranceId but there will never be a call to both onDone(String) and onError(String, int) for the same utterance. The default implementation calls onError(String). 
Params:
  • utteranceId – The utterance ID of the utterance.
  • errorCode – one of the ERROR_* codes from TextToSpeech
/**
     * Called when an error has occurred during processing. This can be called
     * at any point in the synthesis process. Note that there might be calls
     * to {@link #onStart(String)} for specified utteranceId but there will never
     * be a call to both {@link #onDone(String)} and {@link #onError(String,int)} for
     * the same utterance. The default implementation calls {@link #onError(String)}.
     *
     * @param utteranceId The utterance ID of the utterance.
     * @param errorCode one of the ERROR_* codes from {@link TextToSpeech}
     */
    public void onError(String utteranceId, int errorCode) {
        onError(utteranceId);
    }

    
Called when an utterance has been stopped while in progress or flushed from the synthesis queue. This can happen if a client calls TextToSpeech.stop() or uses TextToSpeech.QUEUE_FLUSH as an argument with the TextToSpeech.speak or TextToSpeech.synthesizeToFile methods. 
Params:
  • utteranceId – The utterance ID of the utterance.
  • interrupted – If true, then the utterance was interrupted while being synthesized
       and its output is incomplete. If false, then the utterance was flushed
       before the synthesis started.
/**
     * Called when an utterance has been stopped while in progress or flushed from the
     * synthesis queue. This can happen if a client calls {@link TextToSpeech#stop()}
     * or uses {@link TextToSpeech#QUEUE_FLUSH} as an argument with the
     * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} methods.
     *
     * @param utteranceId The utterance ID of the utterance.
     * @param interrupted If true, then the utterance was interrupted while being synthesized
     *        and its output is incomplete. If false, then the utterance was flushed
     *        before the synthesis started.
     */
    public void onStop(String utteranceId, boolean interrupted) {
    }

    
Called when the TTS engine begins to synthesize the audio for a request.

 It provides information about the format of the byte array for subsequent onAudioAvailable calls. 



This is called when the TTS engine starts synthesizing audio for the request. If an
application wishes to know when the audio is about to start playing, {#onStart(String)}
should be used instead.



Params:
/**
     * Called when the TTS engine begins to synthesize the audio for a request.
     *
     * <p>
     * It provides information about the format of the byte array for subsequent
     * {@link #onAudioAvailable} calls.
     * </p>
     *
     * <p>
     * This is called when the TTS engine starts synthesizing audio for the request. If an
     * application wishes to know when the audio is about to start playing, {#onStart(String)}
     * should be used instead.
     * </p>
     *
     * @param utteranceId The utterance ID of the utterance.
     * @param sampleRateInHz Sample rate in hertz of the generated audio.
     * @param audioFormat Audio format of the generated audio. Should be one of
     *        {@link AudioFormat#ENCODING_PCM_8BIT}, {@link AudioFormat#ENCODING_PCM_16BIT} or
     *        {@link AudioFormat#ENCODING_PCM_FLOAT}.
     * @param channelCount The number of channels.
     */
    public void onBeginSynthesis(String utteranceId, int sampleRateInHz, int audioFormat, int channelCount) {
    }

    
This is called when a chunk of audio is ready for consumption.

 The audio parameter is a copy of what will be synthesized to the speakers (when synthesis was initiated with a TextToSpeech.speak call) or written to the file system (for TextToSpeech.synthesizeToFile). The audio bytes are delivered in one or more chunks; if onDone or onError is called all chunks have been received. 



The audio received here may not be played for some time depending on buffer sizes and the
amount of items on the synthesis queue.



Params:
/**
     * This is called when a chunk of audio is ready for consumption.
     *
     * <p>
     * The audio parameter is a copy of what will be synthesized to the speakers (when synthesis was
     * initiated with a {@link TextToSpeech#speak} call) or written to the file system (for
     * {@link TextToSpeech#synthesizeToFile}). The audio bytes are delivered in one or more chunks;
     * if {@link #onDone} or {@link #onError} is called all chunks have been received.
     * </p>
     *
     * <p>
     * The audio received here may not be played for some time depending on buffer sizes and the
     * amount of items on the synthesis queue.
     * </p>
     *
     * @param utteranceId The utterance ID of the utterance.
     * @param audio A chunk of audio; the format can be known by listening to
     *        {@link #onBeginSynthesis(String, int, int, int)}.
     */
    public void onAudioAvailable(String utteranceId, byte[] audio) {
    }

    
This is called when the TTS service is about to speak the specified range of the utterance
with the given utteranceId.

This method is called when the audio is expected to start playing on the speaker. Note that this is different from onAudioAvailable which is called as soon as the audio is generated. 
This information can be used, for example, to highlight ranges of the text while it is
spoken.

Only called if the engine supplies timing information by calling SynthesisCallback.rangeStart(int, int, int). 
Params:
  • utteranceId – Unique id identifying the synthesis request.
  • start – The start index of the range in the utterance text.
  • end – The end index of the range (exclusive) in the utterance text.
  • frame – The position in frames in the audio of the request where this range is spoken.
/**
     * This is called when the TTS service is about to speak the specified range of the utterance
     * with the given utteranceId.
     *
     * <p>This method is called when the audio is expected to start playing on the speaker. Note
     * that this is different from {@link #onAudioAvailable} which is called as soon as the audio is
     * generated.

     * <p>This information can be used, for example, to highlight ranges of the text while it is
     * spoken.
     *
     * <p>Only called if the engine supplies timing information by calling {@link
     * SynthesisCallback#rangeStart(int, int, int)}.
     *
     * @param utteranceId Unique id identifying the synthesis request.
     * @param start The start index of the range in the utterance text.
     * @param end The end index of the range (exclusive) in the utterance text.
     * @param frame The position in frames in the audio of the request where this range is spoken.
     */
    public void onRangeStart(String utteranceId, int start, int end, int frame) {
        onUtteranceRangeStart(utteranceId, start, end);
    }

    
@removed
/** @removed */
    @Deprecated
    public void onUtteranceRangeStart(String utteranceId, int start, int end) {
    }

    
Wraps an old deprecated OnUtteranceCompletedListener with a shiny new progress listener.

@hide
/**
     * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new progress listener.
     *
     * @hide
     */
    static UtteranceProgressListener from(
            final TextToSpeech.OnUtteranceCompletedListener listener) {
        return new UtteranceProgressListener() {
            @Override
            public synchronized void onDone(String utteranceId) {
                listener.onUtteranceCompleted(utteranceId);
            }

            @Override
            public void onError(String utteranceId) {
                listener.onUtteranceCompleted(utteranceId);
            }

            @Override
            public void onStart(String utteranceId) {
                // Left unimplemented, has no equivalent in the old
                // API.
            }

            @Override
            public void onStop(String utteranceId, boolean interrupted) {
                listener.onUtteranceCompleted(utteranceId);
            }
        };
    }
}