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 */ 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 */ 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 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 */ 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 */ 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 */ 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 */ 121 public void onAudioAvailable(String utteranceId, byte[] audio) { 122 } 123 124 /** 125 * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new 126 * progress listener. 127 * 128 * @hide 129 */ 130 static UtteranceProgressListener from( 131 final TextToSpeech.OnUtteranceCompletedListener listener) { 132 return new UtteranceProgressListener() { 133 @Override 134 public synchronized void onDone(String utteranceId) { 135 listener.onUtteranceCompleted(utteranceId); 136 } 137 138 @Override 139 public void onError(String utteranceId) { 140 listener.onUtteranceCompleted(utteranceId); 141 } 142 143 @Override 144 public void onStart(String utteranceId) { 145 // Left unimplemented, has no equivalent in the old 146 // API. 147 } 148 149 @Override 150 public void onStop(String utteranceId, boolean interrupted) { 151 listener.onUtteranceCompleted(utteranceId); 152 } 153 }; 154 } 155 } 156
