speech/tts/UtteranceProgressListener.java

// 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
 * {@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 {@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 {@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 {@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 {@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 {@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.
     *
     * <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.
     *
     * <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.
     *
     * <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);
    }

    /**
     * @deprecated Due to internal API changes. Remove when apps catch up.
     */
    public void onUtteranceRangeStart(String utteranceId, int start, int end) {
    }

    /**
     * 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);
            }
        };
    }
}