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     */
44    public abstract void onError(String utteranceId);
45
46    /**
47     * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new
48     * progress listener.
49     *
50     * @hide
51     */
52    static UtteranceProgressListener from(
53            final TextToSpeech.OnUtteranceCompletedListener listener) {
54        return new UtteranceProgressListener() {
55            @Override
56            public synchronized void onDone(String utteranceId) {
57                listener.onUtteranceCompleted(utteranceId);
58            }
59
60            @Override
61            public void onError(String utteranceId) {
62                listener.onUtteranceCompleted(utteranceId);
63            }
64
65            @Override
66            public void onStart(String utteranceId) {
67                // Left unimplemented, has no equivalent in the old
68                // API.
69            }
70        };
71    }
72}
73