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