Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 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 | * |
Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 25 | * {@link #error} can be called at any stage in the synthesis process to |
Narayan Kamath | c3da881 | 2011-07-01 10:13:54 +0100 | [diff] [blame] | 26 | * indicate that an error has occurred, but if the call is made after a call |
| 27 | * to {@link #done}, it might be discarded. |
Przemyslaw Szczepaniak | a6e16b8 | 2012-10-15 10:57:33 +0100 | [diff] [blame] | 28 | * |
| 29 | * After {@link #start} been called, {@link #done} must be called regardless of errors. |
Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 30 | */ |
| 31 | public interface SynthesisCallback { |
| 32 | /** |
| 33 | * @return the maximum number of bytes that the TTS engine can pass in a single call of |
Narayan Kamath | c3da881 | 2011-07-01 10:13:54 +0100 | [diff] [blame] | 34 | * {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths |
| 35 | * larger than this value will not succeed. |
Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 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 | /** |
Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 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 | * |
Przemyslaw Szczepaniak | a6e16b8 | 2012-10-15 10:57:33 +0100 | [diff] [blame] | 76 | * This method has to be called if {@link #start} was called. |
| 77 | * |
Narayan Kamath | e22b69a | 2011-06-08 11:41:47 +0100 | [diff] [blame] | 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 | } |