Home | History | Annotate | Download | only in tts 
      1 /*
      2  * Copyright (C) 2011 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License"); you may not
      5  * use this file except in compliance with the License. You may obtain a copy of
      6  * the License at
      7  *
      8  * http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
     12  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
     13  * License for the specific language governing permissions and limitations under
     14  * the License.
     15  */
     16 package android.speech.tts;
     17 
     18 /**
     19  * A callback to return speech data synthesized by a text to speech engine.
     20  *
     21  * The engine can provide streaming audio by calling
     22  * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally
     23  * {@link #done}.
     24  *
     25  * {@link #error} can be called at any stage in the synthesis process to
     26  * indicate that an error has occurred, but if the call is made after a call
     27  * to {@link #done}, it might be discarded.
     28  *
     29  * {@link #done} must be called at the end of synthesis, regardless of errors.
     30  *
     31  * All methods can be only called on the synthesis thread.
     32  */
     33 public interface SynthesisCallback {
     34     /**
     35      * @return the maximum number of bytes that the TTS engine can pass in a single call of
     36      *         {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths
     37      *         larger than this value will not succeed.
     38      */
     39     public int getMaxBufferSize();
     40 
     41     /**
     42      * The service should call this when it starts to synthesize audio for this
     43      * request.
     44      *
     45      * This method should only be called on the synthesis thread,
     46      * while in {@link TextToSpeechService#onSynthesizeText}.
     47      *
     48      * @param sampleRateInHz Sample rate in HZ of the generated audio.
     49      * @param audioFormat Audio format of the generated audio. Must be one of
     50      *         the ENCODING_ constants defined in {@link android.media.AudioFormat}.
     51      * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
     52      * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
     53      *          {@link TextToSpeech#STOPPED}.
     54      */
     55     public int start(int sampleRateInHz, int audioFormat, int channelCount);
     56 
     57     /**
     58      * The service should call this method when synthesized audio is ready for consumption.
     59      *
     60      * This method should only be called on the synthesis thread,
     61      * while in {@link TextToSpeechService#onSynthesizeText}.
     62      *
     63      * @param buffer The generated audio data. This method will not hold on to {@code buffer},
     64      *         so the caller is free to modify it after this method returns.
     65      * @param offset The offset into {@code buffer} where the audio data starts.
     66      * @param length The number of bytes of audio data in {@code buffer}. This must be
     67      *         less than or equal to the return value of {@link #getMaxBufferSize}.
     68      * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
     69      *          {@link TextToSpeech#STOPPED}.
     70      */
     71     public int audioAvailable(byte[] buffer, int offset, int length);
     72 
     73     /**
     74      * The service should call this method when all the synthesized audio for a request has
     75      * been passed to {@link #audioAvailable}.
     76      *
     77      * This method should only be called on the synthesis thread,
     78      * while in {@link TextToSpeechService#onSynthesizeText}.
     79      *
     80      * This method has to be called if {@link #start} and/or {@link #error} was called.
     81      *
     82      * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or
     83      *          {@link TextToSpeech#STOPPED}.
     84      */
     85     public int done();
     86 
     87     /**
     88      * The service should call this method if the speech synthesis fails.
     89      *
     90      * This method should only be called on the synthesis thread,
     91      * while in {@link TextToSpeechService#onSynthesizeText}.
     92      */
     93     public void error();
     94 
     95 
     96     /**
     97      * The service should call this method if the speech synthesis fails.
     98      *
     99      * This method should only be called on the synthesis thread,
    100      * while in {@link TextToSpeechService#onSynthesizeText}.
    101      *
    102      * @param errorCode Error code to pass to the client. One of the ERROR_ values from
    103      *      {@link TextToSpeech}
    104      */
    105     public void error(int errorCode);
    106 
    107     /**
    108      * Check if {@link #start} was called or not.
    109      *
    110      * This method should only be called on the synthesis thread,
    111      * while in {@link TextToSpeechService#onSynthesizeText}.
    112      *
    113      * Useful for checking if a fallback from network request is possible.
    114      */
    115     public boolean hasStarted();
    116 
    117     /**
    118      * Check if {@link #done} was called or not.
    119      *
    120      * This method should only be called on the synthesis thread,
    121      * while in {@link TextToSpeechService#onSynthesizeText}.
    122      *
    123      * Useful for checking if a fallback from network request is possible.
    124      */
    125     public boolean hasFinished();
    126 }
    127