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     * Wraps an old deprecated OnUtteranceCompletedListener with a shiny new
64     * progress listener.
65     *
66     * @hide
67     */
68    static UtteranceProgressListener from(
69            final TextToSpeech.OnUtteranceCompletedListener listener) {
70        return new UtteranceProgressListener() {
71            @Override
72            public synchronized void onDone(String utteranceId) {
73                listener.onUtteranceCompleted(utteranceId);
74            }
75
76            @Override
77            public void onError(String utteranceId) {
78                listener.onUtteranceCompleted(utteranceId);
79            }
80
81            @Override
82            public void onStart(String utteranceId) {
83                // Left unimplemented, has no equivalent in the old
84                // API.
85            }
86        };
87    }
88}
89