SynthesisCallback.java revision 90d15d2371ad85f22254be6985455aa2baa5d15d
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, 4690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 4790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 48e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 49e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param sampleRateInHz Sample rate in HZ of the generated audio. 50e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param audioFormat Audio format of the generated audio. Must be one of 51e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * the ENCODING_ constants defined in {@link android.media.AudioFormat}. 52e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 5390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR}. 5490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of 5590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 56e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 57e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int start(int sampleRateInHz, int audioFormat, int channelCount); 58e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 59e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 60e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method when synthesized audio is ready for consumption. 61e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 62e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 6390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 6490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 65e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 66e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 67e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * so the caller is free to modify it after this method returns. 68e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param offset The offset into {@code buffer} where the audio data starts. 69e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param length The number of bytes of audio data in {@code buffer}. This must be 70e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * less than or equal to the return value of {@link #getMaxBufferSize}. 71e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 7290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of 7390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 74e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 75e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int audioAvailable(byte[] buffer, int offset, int length); 76e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 77e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 78e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method when all the synthesized audio for a request has 79e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * been passed to {@link #audioAvailable}. 80e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 81e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 8290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 8390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 84e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 8590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method has to be called if {@link #start} and/or {@link #error} was called. 86a6e16b86b9f708b4869e123c7c67f6d5675cca18Przemyslaw Szczepaniak * 87e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}. 8890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of 8990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 90e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 91e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int done(); 92e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 93e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 94e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method if the speech synthesis fails. 95e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 96e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 97e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * while in {@link TextToSpeechService#onSynthesizeText}. 98e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 99e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public void error(); 100e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 10190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 10290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 10390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * The service should call this method if the speech synthesis fails. 10490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 10590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 10690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 10790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 10890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 10990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * @param errorCode Error code to pass to the client. One of the ERROR_ values from 11090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * @{link android.sppech.tts.v2.TextToSpeechClient.Status} 11190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 11290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public void error(int errorCode); 11390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 11490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 11590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Communicate to client that the original request can't be done and client-requested 11690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * fallback is happening. 11790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 11890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Fallback can be requested by the client by setting 11990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechClient.Params#FALLBACK_VOICE_ID} voice parameter with a id of 12090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * the voice that is expected to be used for the fallback. 12190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 12290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method will fail if user called {@link #start(int, int, int)} and/or 12390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link #done()}. 12490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 12590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 12690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeTextV2}. 12790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 12890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} if client already 12990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * called {@link #start(int, int, int)}, {@link TextToSpeechClient.Status#STOPPED} 13090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * if stop was requested. 13190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 13290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public int fallback(); 13390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 13490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 13590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Check if @{link #start} was called or not. 13690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 13790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 13890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 13990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 14090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 14190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Useful for checking if a fallback from network request is possible. 14290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 14390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public boolean hasStarted(); 14490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 14590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 14690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Check if @{link #done} was called or not. 14790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 14890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 14990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText} or 15090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link TextToSpeechService#onSynthesizeTextV2}. 15190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 15290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Useful for checking if a fallback from network request is possible. 15390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 15490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public boolean hasFinished(); 155e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath}