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 * After {@link #start} been called, {@link #done} must be called regardless of errors. 30 */ 31 public interface SynthesisCallback { 32 /** 33 * @return the maximum number of bytes that the TTS engine can pass in a single call of 34 * {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths 35 * larger than this value will not succeed. 36 */ 37 public int getMaxBufferSize(); 38 39 /** 40 * The service should call this when it starts to synthesize audio for this 41 * request. 42 * 43 * This method should only be called on the synthesis thread, 44 * while in {@link TextToSpeechService#onSynthesizeText}. 45 * 46 * @param sampleRateInHz Sample rate in HZ of the generated audio. 47 * @param audioFormat Audio format of the generated audio. Must be one of 48 * the ENCODING_ constants defined in {@link android.media.AudioFormat}. 49 * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 50 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 51 */ 52 public int start(int sampleRateInHz, int audioFormat, int channelCount); 53 54 /** 55 * The service should call this method when synthesized audio is ready for consumption. 56 * 57 * This method should only be called on the synthesis thread, 58 * while in {@link TextToSpeechService#onSynthesizeText}. 59 * 60 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 61 * so the caller is free to modify it after this method returns. 62 * @param offset The offset into {@code buffer} where the audio data starts. 63 * @param length The number of bytes of audio data in {@code buffer}. This must be 64 * less than or equal to the return value of {@link #getMaxBufferSize}. 65 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 66 */ 67 public int audioAvailable(byte[] buffer, int offset, int length); 68 69 /** 70 * The service should call this method when all the synthesized audio for a request has 71 * been passed to {@link #audioAvailable}. 72 * 73 * This method should only be called on the synthesis thread, 74 * while in {@link TextToSpeechService#onSynthesizeText}. 75 * 76 * This method has to be called if {@link #start} was called. 77 * 78 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 79 */ 80 public int done(); 81 82 /** 83 * The service should call this method if the speech synthesis fails. 84 * 85 * This method should only be called on the synthesis thread, 86 * while in {@link TextToSpeechService#onSynthesizeText}. 87 */ 88 public void error(); 89 90 }
