SynthesisCallback.java revision e22b69a7de0349b99d3107349d1d3aa72d62c841
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 */ 16package 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 * Alternatively, the engine can provide all the audio at once, by using 26 * {@link #completeAudioAvailable}. 27 * 28 * {@link #error} can be called at any stage in the synthesis process to 29 * indicate that an error has occured, but if the call is made after a call 30 * to {@link #done} or {@link #completeAudioAvailable} it might be discarded. 31 */ 32public interface SynthesisCallback { 33 /** 34 * @return the maximum number of bytes that the TTS engine can pass in a single call of 35 * {@link #audioAvailable}. This does not apply to {@link #completeAudioAvailable}. 36 * Calls to {@link #audioAvailable} with data lengths larger than this 37 * 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} or {@link TextToSpeech#ERROR}. 53 */ 54 public int start(int sampleRateInHz, int audioFormat, int channelCount); 55 56 /** 57 * The service should call this method when synthesized audio is ready for consumption. 58 * 59 * This method should only be called on the synthesis thread, 60 * while in {@link TextToSpeechService#onSynthesizeText}. 61 * 62 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 63 * so the caller is free to modify it after this method returns. 64 * @param offset The offset into {@code buffer} where the audio data starts. 65 * @param length The number of bytes of audio data in {@code buffer}. This must be 66 * less than or equal to the return value of {@link #getMaxBufferSize}. 67 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 68 */ 69 public int audioAvailable(byte[] buffer, int offset, int length); 70 71 /** 72 * The service can call this method instead of using {@link #start}, {@link #audioAvailable} 73 * and {@link #done} if all the audio data is available in a single buffer. 74 * 75 * @param sampleRateInHz Sample rate in HZ of the generated audio. 76 * @param audioFormat Audio format of the generated audio. Must be one of 77 * the ENCODING_ constants defined in {@link android.media.AudioFormat}. 78 * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 79 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 80 * so the caller is free to modify it after this method returns. 81 * @param offset The offset into {@code buffer} where the audio data starts. 82 * @param length The number of bytes of audio data in {@code buffer}. 83 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 84 */ 85 public int completeAudioAvailable(int sampleRateInHz, int audioFormat, 86 int channelCount, byte[] buffer, int offset, int length); 87 88 /** 89 * The service should call this method when all the synthesized audio for a request has 90 * been passed to {@link #audioAvailable}. 91 * 92 * This method should only be called on the synthesis thread, 93 * while in {@link TextToSpeechService#onSynthesizeText}. 94 * 95 * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 96 */ 97 public int done(); 98 99 /** 100 * The service should call this method if the speech synthesis fails. 101 * 102 * This method should only be called on the synthesis thread, 103 * while in {@link TextToSpeechService#onSynthesizeText}. 104 */ 105 public void error(); 106 107}