1// Copyright 2011 Google Inc. All Rights Reserved.
2
3package 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 */
13public 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     */
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     */
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
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     */
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     */
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     */
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