content: // 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);
      }
  
      /** @removed */
      @Deprecated
      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);
              }
          };
      }
  }
  