1 // Copyright 2011 Google Inc. All Rights Reserved. 2 3 package android.speech.tts; 4 5 import android.media.AudioFormat; 6 7 /** 8 * Listener for events relating to the progress of an utterance through 9 * the synthesis queue. Each utterance is associated with a call to 10 * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} with an 11 * associated utterance identifier, as per {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID}. 12 * 13 * The callbacks specified in this method can be called from multiple threads. 14 */ 15 public abstract class UtteranceProgressListener { 16 /** 17 * Called when an utterance "starts" as perceived by the caller. This will 18 * be soon before audio is played back in the case of a {@link TextToSpeech#speak} 19 * or before the first bytes of a file are written to the file system in the case 20 * of {@link TextToSpeech#synthesizeToFile}. 21 * 22 * @param utteranceId The utterance ID of the utterance. 23 */ onStart(String utteranceId)24 public abstract void onStart(String utteranceId); 25 26 /** 27 * Called when an utterance has successfully completed processing. 28 * All audio will have been played back by this point for audible output, and all 29 * output will have been written to disk for file synthesis requests. 30 * 31 * This request is guaranteed to be called after {@link #onStart(String)}. 32 * 33 * @param utteranceId The utterance ID of the utterance. 34 */ onDone(String utteranceId)35 public abstract void onDone(String utteranceId); 36 37 /** 38 * Called when an error has occurred during processing. This can be called 39 * at any point in the synthesis process. Note that there might be calls 40 * to {@link #onStart(String)} for specified utteranceId but there will never 41 * be a call to both {@link #onDone(String)} and {@link #onError(String)} for 42 * the same utterance. 43 * 44 * @param utteranceId The utterance ID of the utterance. 45 * @deprecated Use {@link #onError(String,int)} instead 46 */ 47 @Deprecated onError(String utteranceId)48 public abstract void onError(String utteranceId); 49 50 /** 51 * Called when an error has occurred during processing. This can be called 52 * at any point in the synthesis process. Note that there might be calls 53 * to {@link #onStart(String)} for specified utteranceId but there will never 54 * be a call to both {@link #onDone(String)} and {@link #onError(String,int)} for 55 * the same utterance. The default implementation calls {@link #onError(String)}. 56 * 57 * @param utteranceId The utterance ID of the utterance. 58 * @param errorCode one of the ERROR_* codes from {@link TextToSpeech} 59 */ onError(String utteranceId, int errorCode)60 public void onError(String utteranceId, int errorCode) { 61 onError(utteranceId); 62 } 63 64 /** 65 * Called when an utterance has been stopped while in progress or flushed from the 66 * synthesis queue. This can happen if a client calls {@link TextToSpeech#stop()} 67 * or uses {@link TextToSpeech#QUEUE_FLUSH} as an argument with the 68 * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} methods. 69 * 70 * @param utteranceId The utterance ID of the utterance. 71 * @param interrupted If true, then the utterance was interrupted while being synthesized 72 * and its output is incomplete. If false, then the utterance was flushed 73 * before the synthesis started. 74 */ onStop(String utteranceId, boolean interrupted)75 public void onStop(String utteranceId, boolean interrupted) { 76 } 77 78 /** 79 * Called when the TTS engine begins to synthesize the audio for a request. 80 * 81 * <p> 82 * It provides information about the format of the byte array for subsequent 83 * {@link #onAudioAvailable} calls. 84 * </p> 85 * 86 * <p> 87 * This is called when the TTS engine starts synthesizing audio for the request. If an 88 * application wishes to know when the audio is about to start playing, {#onStart(String)} 89 * should be used instead. 90 * </p> 91 * 92 * @param utteranceId The utterance ID of the utterance. 93 * @param sampleRateInHz Sample rate in hertz of the generated audio. 94 * @param audioFormat Audio format of the generated audio. Should be one of 95 * {@link AudioFormat#ENCODING_PCM_8BIT}, {@link AudioFormat#ENCODING_PCM_16BIT} or 96 * {@link AudioFormat#ENCODING_PCM_FLOAT}. 97 * @param channelCount The number of channels. 98 */ onBeginSynthesis(String utteranceId, int sampleRateInHz, int audioFormat, int channelCount)99 public void onBeginSynthesis(String utteranceId, int sampleRateInHz, int audioFormat, int channelCount) { 100 } 101 102 /** 103 * This is called when a chunk of audio is ready for consumption. 104 * 105 * <p> 106 * The audio parameter is a copy of what will be synthesized to the speakers (when synthesis was 107 * initiated with a {@link TextToSpeech#speak} call) or written to the file system (for 108 * {@link TextToSpeech#synthesizeToFile}). The audio bytes are delivered in one or more chunks; 109 * if {@link #onDone} or {@link #onError} is called all chunks have been received. 110 * </p> 111 * 112 * <p> 113 * The audio received here may not be played for some time depending on buffer sizes and the 114 * amount of items on the synthesis queue. 115 * </p> 116 * 117 * @param utteranceId The utterance ID of the utterance. 118 * @param audio A chunk of audio; the format can be known by listening to 119 * {@link #onBeginSynthesis(String, int, int, int)}. 120 */ onAudioAvailable(String utteranceId, byte[] audio)121 public void onAudioAvailable(String utteranceId, byte[] audio) { 122 } 123 124 /** 125 * This is called when the TTS service is about to speak the specified range of the utterance 126 * with the given utteranceId. 127 * 128 * <p>This method is called when the audio is expected to start playing on the speaker. Note 129 * that this is different from {@link #onAudioAvailable} which is called as soon as the audio is 130 * generated. 131 132 * <p>This information can be used, for example, to highlight ranges of the text while it is 133 * spoken. 134 * 135 * <p>Only called if the engine supplies timing information by calling {@link 136 * SynthesisCallback#rangeStart(int, int, int)}. 137 * 138 * @param utteranceId Unique id identifying the synthesis request. 139 * @param start The start index of the range in the utterance text. 140 * @param end The end index of the range (exclusive) in the utterance text. 141 * @param frame The position in frames in the audio of the request where this range is spoken. 142 */ onRangeStart(String utteranceId, int start, int end, int frame)143 public void onRangeStart(String utteranceId, int start, int end, int frame) { 144 onUtteranceRangeStart(utteranceId, start, end); 145 } 146 147 /** @removed */ 148 @Deprecated onUtteranceRangeStart(String utteranceId, int start, int end)149 public void onUtteranceRangeStart(String utteranceId, int start, int end) { 150 } 151 152 /** 153 * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new progress listener. 154 * 155 * @hide 156 */ from( final TextToSpeech.OnUtteranceCompletedListener listener)157 static UtteranceProgressListener from( 158 final TextToSpeech.OnUtteranceCompletedListener listener) { 159 return new UtteranceProgressListener() { 160 @Override 161 public synchronized void onDone(String utteranceId) { 162 listener.onUtteranceCompleted(utteranceId); 163 } 164 165 @Override 166 public void onError(String utteranceId) { 167 listener.onUtteranceCompleted(utteranceId); 168 } 169 170 @Override 171 public void onStart(String utteranceId) { 172 // Left unimplemented, has no equivalent in the old 173 // API. 174 } 175 176 @Override 177 public void onStop(String utteranceId, boolean interrupted) { 178 listener.onUtteranceCompleted(utteranceId); 179 } 180 }; 181 } 182 } 183