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 18a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport android.annotation.IntDef; 19a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport android.annotation.IntRange; 20a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport android.media.AudioFormat; 21a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport android.speech.tts.TextToSpeech; 22a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts 23a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport java.lang.annotation.Retention; 24a24b50bee1aca19028477b235862bcd2c37135edNiels Egbertsimport java.lang.annotation.RetentionPolicy; 25a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts 26e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath/** 27e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * A callback to return speech data synthesized by a text to speech engine. 28e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 29e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The engine can provide streaming audio by calling 30e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally 31e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * {@link #done}. 32e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 33e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * {@link #error} can be called at any stage in the synthesis process to 34c3da8818f0598b3ab2cd6f4168349da6d0f72cb1Narayan Kamath * indicate that an error has occurred, but if the call is made after a call 35c3da8818f0598b3ab2cd6f4168349da6d0f72cb1Narayan Kamath * to {@link #done}, it might be discarded. 36a6e16b86b9f708b4869e123c7c67f6d5675cca18Przemyslaw Szczepaniak * 3790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * {@link #done} must be called at the end of synthesis, regardless of errors. 3890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 3990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * All methods can be only called on the synthesis thread. 40e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 41e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamathpublic interface SynthesisCallback { 42a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts 43a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts /** @hide */ 44a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts @Retention(RetentionPolicy.SOURCE) 45a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts @IntDef({AudioFormat.ENCODING_PCM_8BIT, AudioFormat.ENCODING_PCM_16BIT, 46a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts AudioFormat.ENCODING_PCM_FLOAT}) 47a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts public @interface SupportedAudioFormat {}; 48a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts 49e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 50e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @return the maximum number of bytes that the TTS engine can pass in a single call of 51c3da8818f0598b3ab2cd6f4168349da6d0f72cb1Narayan Kamath * {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths 52c3da8818f0598b3ab2cd6f4168349da6d0f72cb1Narayan Kamath * larger than this value will not succeed. 53e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 54e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int getMaxBufferSize(); 55e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 56a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts // TODO: Replace reference to Android N to an API level when the API level for N is decided. 57e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 58e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this when it starts to synthesize audio for this 59e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * request. 60e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 61e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 62fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 63e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 64e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param sampleRateInHz Sample rate in HZ of the generated audio. 65e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param audioFormat Audio format of the generated audio. Must be one of 665fd28893f299cc069257de2199f91762dfba16b1Niels Egberts * {@link AudioFormat#ENCODING_PCM_8BIT} or 675fd28893f299cc069257de2199f91762dfba16b1Niels Egberts * {@link AudioFormat#ENCODING_PCM_16BIT}. Can also be 685fd28893f299cc069257de2199f91762dfba16b1Niels Egberts * {@link AudioFormat#ENCODING_PCM_FLOAT} when targetting Android N and 69a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts * above. 70e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 71fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 72fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * {@link TextToSpeech#STOPPED}. 73e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 74a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts public int start(int sampleRateInHz, @SupportedAudioFormat int audioFormat, 75a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts @IntRange(from=1,to=2) int channelCount); 76e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 77e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 78e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method when synthesized audio is ready for consumption. 79e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 80e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 81fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 82e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 83e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 84e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * so the caller is free to modify it after this method returns. 85e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param offset The offset into {@code buffer} where the audio data starts. 86e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * @param length The number of bytes of audio data in {@code buffer}. This must be 87e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * less than or equal to the return value of {@link #getMaxBufferSize}. 88fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 89fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * {@link TextToSpeech#STOPPED}. 90e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 91e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int audioAvailable(byte[] buffer, int offset, int length); 92e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 93e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 94e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method when all the synthesized audio for a request has 95e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * been passed to {@link #audioAvailable}. 96e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 97e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 98fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 99e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 10090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method has to be called if {@link #start} and/or {@link #error} was called. 101a6e16b86b9f708b4869e123c7c67f6d5675cca18Przemyslaw Szczepaniak * 102fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 103fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * {@link TextToSpeech#STOPPED}. 104e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 105e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public int done(); 106e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 107e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath /** 108e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * The service should call this method if the speech synthesis fails. 109e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * 110e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * This method should only be called on the synthesis thread, 111e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath * while in {@link TextToSpeechService#onSynthesizeText}. 112e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath */ 113e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath public void error(); 114e22b69a7de0349b99d3107349d1d3aa72d62c841Narayan Kamath 11590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 11690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 11790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * The service should call this method if the speech synthesis fails. 11890d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 11990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 120fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 12190d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 12290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * @param errorCode Error code to pass to the client. One of the ERROR_ values from 123fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * {@link TextToSpeech} 12490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 125a24b50bee1aca19028477b235862bcd2c37135edNiels Egberts public void error(@TextToSpeech.Error int errorCode); 12690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 12790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 128eb337054edef31c9bdab4a59913f42038d5deaaeNick Kralevich * Check if {@link #start} was called or not. 12990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 13090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 131fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 13290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 13390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Useful for checking if a fallback from network request is possible. 13490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 13590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public boolean hasStarted(); 13690d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak 13790d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak /** 138eb337054edef31c9bdab4a59913f42038d5deaaeNick Kralevich * Check if {@link #done} was called or not. 13990d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 14090d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * This method should only be called on the synthesis thread, 141fc4b2890378eb1b6e0b11d60d703eb6854268064Przemyslaw Szczepaniak * while in {@link TextToSpeechService#onSynthesizeText}. 14290d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * 14390d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak * Useful for checking if a fallback from network request is possible. 14490d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak */ 14590d15d2371ad85f22254be6985455aa2baa5d15dPrzemyslaw Szczepaniak public boolean hasFinished(); 146d41b852f92ec2def734eac68a76ecbcea17e3cc9Siva Velusamy} 147