content: /*
   * Copyright (C) 2011 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License"); you may not
   * use this file except in compliance with the License. You may obtain a copy of
   * the License at
   *
   * http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
   * License for the specific language governing permissions and limitations under
   * the License.
   */
  package android.speech.tts;
  
  import android.annotation.IntDef;
  import android.annotation.IntRange;
  import android.media.AudioFormat;
  
  import java.lang.annotation.Retention;
  import java.lang.annotation.RetentionPolicy;
  
  /**
   * A callback to return speech data synthesized by a text to speech engine.
   *
   * The engine can provide streaming audio by calling
   * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally
   * {@link #done}.
   *
   * {@link #error} can be called at any stage in the synthesis process to
   * indicate that an error has occurred, but if the call is made after a call
   * to {@link #done}, it might be discarded.
   *
   * {@link #done} must be called at the end of synthesis, regardless of errors.
   *
   * All methods can be only called on the synthesis thread.
   */
  public interface SynthesisCallback {
  
      /** @hide */
      @Retention(RetentionPolicy.SOURCE)
      @IntDef({
          AudioFormat.ENCODING_PCM_8BIT,
          AudioFormat.ENCODING_PCM_16BIT,
          AudioFormat.ENCODING_PCM_FLOAT
      })
      @interface SupportedAudioFormat {};
  
      /**
       * @return the maximum number of bytes that the TTS engine can pass in a single call of {@link
       *     #audioAvailable}. Calls to {@link #audioAvailable} with data lengths larger than this
       *     value will not succeed.
       */
      int getMaxBufferSize();
  
    /**
     * The service should call this when it starts to synthesize audio for this request.
     *
     * <p>This method should only be called on the synthesis thread, while in {@link
     * TextToSpeechService#onSynthesizeText}.
     *
     * @param sampleRateInHz Sample rate in HZ of the generated audio.
     * @param audioFormat Audio format of the generated audio. Must be one of {@link
     *     AudioFormat#ENCODING_PCM_8BIT} or {@link AudioFormat#ENCODING_PCM_16BIT}. Can also be
     *     {@link AudioFormat#ENCODING_PCM_FLOAT} when targetting Android N and above.
     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
     * @return {@link android.speech.tts.TextToSpeech#SUCCESS}, {@link
     *     android.speech.tts.TextToSpeech#ERROR} or {@link android.speech.tts.TextToSpeech#STOPPED}.
     */
    int start(
        int sampleRateInHz,
        @SupportedAudioFormat int audioFormat,
        @IntRange(from = 1, to = 2) int channelCount);
  
    /**
     * The service should call this method when synthesized audio is ready for consumption.
     *
     * <p>This method should only be called on the synthesis thread, while in {@link
     * TextToSpeechService#onSynthesizeText}.
     *
     * @param buffer The generated audio data. This method will not hold on to {@code buffer}, so the
     *     caller is free to modify it after this method returns.
     * @param offset The offset into {@code buffer} where the audio data starts.
     * @param length The number of bytes of audio data in {@code buffer}. This must be less than or
     *     equal to the return value of {@link #getMaxBufferSize}.
     * @return {@link android.speech.tts.TextToSpeech#SUCCESS}, {@link
     *     android.speech.tts.TextToSpeech#ERROR} or {@link android.speech.tts.TextToSpeech#STOPPED}.
     */
    int audioAvailable(byte[] buffer, int offset, int length);
  
    /**
     * The service should call this method when all the synthesized audio for a request has been
     * passed to {@link #audioAvailable}.
     *
     * <p>This method should only be called on the synthesis thread, while in {@link
     * TextToSpeechService#onSynthesizeText}.
     *
     * <p>This method has to be called if {@link #start} and/or {@link #error} was called.
     *
     * @return {@link android.speech.tts.TextToSpeech#SUCCESS}, {@link
     *     android.speech.tts.TextToSpeech#ERROR} or {@link android.speech.tts.TextToSpeech#STOPPED}.
     */
    int done();
  
      /**
       * The service should call this method if the speech synthesis fails.
       *
       * <p>This method should only be called on the synthesis thread, while in {@link
       * TextToSpeechService#onSynthesizeText}.
       */
      void error();
  
    /**
     * The service should call this method if the speech synthesis fails.
     *
     * <p>This method should only be called on the synthesis thread, while in {@link
     * TextToSpeechService#onSynthesizeText}.
     *
     * @param errorCode Error code to pass to the client. One of the ERROR_ values from {@link
     *     android.speech.tts.TextToSpeech}
     */
    void error(@TextToSpeech.Error int errorCode);
  
      /**
       * Check if {@link #start} was called or not.
       *
       * <p>This method should only be called on the synthesis thread, while in {@link
       * TextToSpeechService#onSynthesizeText}.
       *
       * <p>Useful for checking if a fallback from network request is possible.
       */
      boolean hasStarted();
  
      /**
       * Check if {@link #done} was called or not.
       *
       * <p>This method should only be called on the synthesis thread, while in {@link
       * TextToSpeechService#onSynthesizeText}.
       *
       * <p>Useful for checking if a fallback from network request is possible.
       */
      boolean hasFinished();
  
      /**
       * The service may call this method to provide timing information about the spoken text.
       *
       * <p>Calling this method means that at the given audio frame, the given range of the input is
       * about to be spoken. If this method is called the client will receive a callback on the
       * listener ({@link UtteranceProgressListener#onRangeStart}) at the moment that frame has been
       * reached by the playback head.
       *
       * <p>This information can be used by the client, for example, to highlight ranges of the text
       * while it is spoken.
       *
       * <p>The markerInFrames is a frame index into the audio for this synthesis request, i.e. into
       * the concatenation of the audio bytes sent to audioAvailable for this synthesis request. The
       * definition of a frame depends on the format given by {@link #start}. See {@link AudioFormat}
       * for more information.
       *
       * <p>This method should only be called on the synthesis thread, while in {@link
       * TextToSpeechService#onSynthesizeText}.
       *
       * @param markerInFrames The position in frames in the audio where this range is spoken.
       * @param start The start index of the range in the input text.
       * @param end The end index (exclusive) of the range in the input text.
       */
      default void rangeStart(int markerInFrames, int start, int end) {}
  }
  