1 // Copyright 2011 Google Inc. All Rights Reserved.
2 
3 package android.speech.tts;
4 
5 /**
6  * Listener for events relating to the progress of an utterance through
7  * the synthesis queue. Each utterance is associated with a call to
8  * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} with an
9  * associated utterance identifier, as per {@link TextToSpeech.Engine#KEY_PARAM_UTTERANCE_ID}.
10  *
11  * The callbacks specified in this method can be called from multiple threads.
12  */
13 public abstract class UtteranceProgressListener {
14     /**
15      * Called when an utterance "starts" as perceived by the caller. This will
16      * be soon before audio is played back in the case of a {@link TextToSpeech#speak}
17      * or before the first bytes of a file are written to storage in the case
18      * of {@link TextToSpeech#synthesizeToFile}.
19      *
20      * @param utteranceId the utterance ID of the utterance.
21      */
onStart(String utteranceId)22     public abstract void onStart(String utteranceId);
23 
24     /**
25      * Called when an utterance has successfully completed processing.
26      * All audio will have been played back by this point for audible output, and all
27      * output will have been written to disk for file synthesis requests.
28      *
29      * This request is guaranteed to be called after {@link #onStart(String)}.
30      *
31      * @param utteranceId the utterance ID of the utterance.
32      */
onDone(String utteranceId)33     public abstract void onDone(String utteranceId);
34 
35     /**
36      * Called when an error has occurred during processing. This can be called
37      * at any point in the synthesis process. Note that there might be calls
38      * to {@link #onStart(String)} for specified utteranceId but there will never
39      * be a call to both {@link #onDone(String)} and {@link #onError(String)} for
40      * the same utterance.
41      *
42      * @param utteranceId the utterance ID of the utterance.
43      * @deprecated Use {@link #onError(String,int)} instead
44      */
45     @Deprecated
onError(String utteranceId)46     public abstract void onError(String utteranceId);
47 
48     /**
49      * Called when an error has occurred during processing. This can be called
50      * at any point in the synthesis process. Note that there might be calls
51      * to {@link #onStart(String)} for specified utteranceId but there will never
52      * be a call to both {@link #onDone(String)} and {@link #onError(String,int)} for
53      * the same utterance. The default implementation calls {@link #onError(String)}.
54      *
55      * @param utteranceId the utterance ID of the utterance.
56      * @param errorCode one of the ERROR_* codes from {@link TextToSpeech}
57      */
onError(String utteranceId, int errorCode)58     public void onError(String utteranceId, int errorCode) {
59         onError(utteranceId);
60     }
61 
62     /**
63      * Called when an utterance has been stopped while in progress or flushed from the
64      * synthesis queue. This can happen if a client calls {@link TextToSpeech#stop()}
65      * or uses {@link TextToSpeech#QUEUE_FLUSH} as an argument with the
66      * {@link TextToSpeech#speak} or {@link TextToSpeech#synthesizeToFile} methods.
67      *
68      * @param utteranceId the utterance ID of the utterance.
69      * @param interrupted If true, then the utterance was interrupted while being synthesized
70      *        and its output is incomplete. If false, then the utterance was flushed
71      *        before the synthesis started.
72      */
onStop(String utteranceId, boolean interrupted)73     public void onStop(String utteranceId, boolean interrupted) {
74     }
75 
76     /**
77      * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new
78      * progress listener.
79      *
80      * @hide
81      */
from( final TextToSpeech.OnUtteranceCompletedListener listener)82     static UtteranceProgressListener from(
83             final TextToSpeech.OnUtteranceCompletedListener listener) {
84         return new UtteranceProgressListener() {
85             @Override
86             public synchronized void onDone(String utteranceId) {
87                 listener.onUtteranceCompleted(utteranceId);
88             }
89 
90             @Override
91             public void onError(String utteranceId) {
92                 listener.onUtteranceCompleted(utteranceId);
93             }
94 
95             @Override
96             public void onStart(String utteranceId) {
97                 // Left unimplemented, has no equivalent in the old
98                 // API.
99             }
100 
101             @Override
102             public void onStop(String utteranceId, boolean interrupted) {
103                 listener.onUtteranceCompleted(utteranceId);
104             }
105         };
106     }
107 }
108