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 import android.annotation.IntDef; 19 import android.annotation.IntRange; 20 import android.media.AudioFormat; 21 import android.speech.tts.TextToSpeech; 22 23 import java.lang.annotation.Retention; 24 import java.lang.annotation.RetentionPolicy; 25 26 /** 27 * A callback to return speech data synthesized by a text to speech engine. 28 * 29 * The engine can provide streaming audio by calling 30 * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally 31 * {@link #done}. 32 * 33 * {@link #error} can be called at any stage in the synthesis process to 34 * indicate that an error has occurred, but if the call is made after a call 35 * to {@link #done}, it might be discarded. 36 * 37 * {@link #done} must be called at the end of synthesis, regardless of errors. 38 * 39 * All methods can be only called on the synthesis thread. 40 */ 41 public interface SynthesisCallback { 42 43 /** @hide */ 44 @Retention(RetentionPolicy.SOURCE) 45 @IntDef({AudioFormat.ENCODING_PCM_8BIT, AudioFormat.ENCODING_PCM_16BIT, 46 AudioFormat.ENCODING_PCM_FLOAT}) 47 public @interface SupportedAudioFormat {}; 48 49 /** 50 * @return the maximum number of bytes that the TTS engine can pass in a single call of 51 * {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths 52 * larger than this value will not succeed. 53 */ getMaxBufferSize()54 public int getMaxBufferSize(); 55 56 // TODO: Replace reference to Android N to an API level when the API level for N is decided. 57 /** 58 * The service should call this when it starts to synthesize audio for this 59 * request. 60 * 61 * This method should only be called on the synthesis thread, 62 * while in {@link TextToSpeechService#onSynthesizeText}. 63 * 64 * @param sampleRateInHz Sample rate in HZ of the generated audio. 65 * @param audioFormat Audio format of the generated audio. Must be one of 66 * {@link AudioFormat#ENCODING_PCM_8BIT} or 67 * {@link AudioFormat#ENCODING_PCM_16BIT}. Can also be 68 * {@link AudioFormat#ENCODING_PCM_FLOAT} when targetting Android N and 69 * above. 70 * @param channelCount The number of channels. Must be {@code 1} or {@code 2}. 71 * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 72 * {@link TextToSpeech#STOPPED}. 73 */ start(int sampleRateInHz, @SupportedAudioFormat int audioFormat, @IntRange(from=1,to=2) int channelCount)74 public int start(int sampleRateInHz, @SupportedAudioFormat int audioFormat, 75 @IntRange(from=1,to=2) int channelCount); 76 77 /** 78 * The service should call this method when synthesized audio is ready for consumption. 79 * 80 * This method should only be called on the synthesis thread, 81 * while in {@link TextToSpeechService#onSynthesizeText}. 82 * 83 * @param buffer The generated audio data. This method will not hold on to {@code buffer}, 84 * so the caller is free to modify it after this method returns. 85 * @param offset The offset into {@code buffer} where the audio data starts. 86 * @param length The number of bytes of audio data in {@code buffer}. This must be 87 * less than or equal to the return value of {@link #getMaxBufferSize}. 88 * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 89 * {@link TextToSpeech#STOPPED}. 90 */ audioAvailable(byte[] buffer, int offset, int length)91 public int audioAvailable(byte[] buffer, int offset, int length); 92 93 /** 94 * The service should call this method when all the synthesized audio for a request has 95 * been passed to {@link #audioAvailable}. 96 * 97 * This method should only be called on the synthesis thread, 98 * while in {@link TextToSpeechService#onSynthesizeText}. 99 * 100 * This method has to be called if {@link #start} and/or {@link #error} was called. 101 * 102 * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} or 103 * {@link TextToSpeech#STOPPED}. 104 */ done()105 public int done(); 106 107 /** 108 * The service should call this method if the speech synthesis fails. 109 * 110 * This method should only be called on the synthesis thread, 111 * while in {@link TextToSpeechService#onSynthesizeText}. 112 */ error()113 public void error(); 114 115 116 /** 117 * The service should call this method if the speech synthesis fails. 118 * 119 * This method should only be called on the synthesis thread, 120 * while in {@link TextToSpeechService#onSynthesizeText}. 121 * 122 * @param errorCode Error code to pass to the client. One of the ERROR_ values from 123 * {@link TextToSpeech} 124 */ error(@extToSpeech.Error int errorCode)125 public void error(@TextToSpeech.Error int errorCode); 126 127 /** 128 * Check if {@link #start} was called or not. 129 * 130 * This method should only be called on the synthesis thread, 131 * while in {@link TextToSpeechService#onSynthesizeText}. 132 * 133 * Useful for checking if a fallback from network request is possible. 134 */ hasStarted()135 public boolean hasStarted(); 136 137 /** 138 * Check if {@link #done} was called or not. 139 * 140 * This method should only be called on the synthesis thread, 141 * while in {@link TextToSpeechService#onSynthesizeText}. 142 * 143 * Useful for checking if a fallback from network request is possible. 144 */ hasFinished()145 public boolean hasFinished(); 146 } 147