SynthesisCallback.java revision d41b852f92ec2def734eac68a76ecbcea17e3cc9 
1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not
5 * use this file except in compliance with the License. You may obtain a copy of
6 * the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13 * License for the specific language governing permissions and limitations under
14 * the License.
15 */
16package android.speech.tts;
17
18/**
19 * A callback to return speech data synthesized by a text to speech engine.
20 *
21 * The engine can provide streaming audio by calling
22 * {@link #start}, then {@link #audioAvailable} until all audio has been provided, then finally
23 * {@link #done}.
24 *
25 * {@link #error} can be called at any stage in the synthesis process to
26 * indicate that an error has occurred, but if the call is made after a call
27 * to {@link #done}, it might be discarded.
28 *
29 * {@link #done} must be called at the end of synthesis, regardless of errors.
30 *
31 * All methods can be only called on the synthesis thread.
32 */
33public interface SynthesisCallback {
34    /**
35     * @return the maximum number of bytes that the TTS engine can pass in a single call of
36     *         {@link #audioAvailable}. Calls to {@link #audioAvailable} with data lengths
37     *         larger than this value will not succeed.
38     */
39    public int getMaxBufferSize();
40
41    /**
42     * The service should call this when it starts to synthesize audio for this
43     * request.
44     *
45     * This method should only be called on the synthesis thread,
46     * while in {@link TextToSpeechService#onSynthesizeText} or
47     * {@link TextToSpeechService#onSynthesizeTextV2}.
48     *
49     * @param sampleRateInHz Sample rate in HZ of the generated audio.
50     * @param audioFormat Audio format of the generated audio. Must be one of
51     *         the ENCODING_ constants defined in {@link android.media.AudioFormat}.
52     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
53     * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR}.
54     *          {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of
55     *          {@link TextToSpeechService#onSynthesizeTextV2}.
56     */
57    public int start(int sampleRateInHz, int audioFormat, int channelCount);
58
59    /**
60     * The service should call this method when synthesized audio is ready for consumption.
61     *
62     * This method should only be called on the synthesis thread,
63     * while in {@link TextToSpeechService#onSynthesizeText} or
64     * {@link TextToSpeechService#onSynthesizeTextV2}.
65     *
66     * @param buffer The generated audio data. This method will not hold on to {@code buffer},
67     *         so the caller is free to modify it after this method returns.
68     * @param offset The offset into {@code buffer} where the audio data starts.
69     * @param length The number of bytes of audio data in {@code buffer}. This must be
70     *         less than or equal to the return value of {@link #getMaxBufferSize}.
71     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
72     *          {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of
73     *          {@link TextToSpeechService#onSynthesizeTextV2}.
74     */
75    public int audioAvailable(byte[] buffer, int offset, int length);
76
77    /**
78     * The service should call this method when all the synthesized audio for a request has
79     * been passed to {@link #audioAvailable}.
80     *
81     * This method should only be called on the synthesis thread,
82     * while in {@link TextToSpeechService#onSynthesizeText} or
83     * {@link TextToSpeechService#onSynthesizeTextV2}.
84     *
85     * This method has to be called if {@link #start} and/or {@link #error} was called.
86     *
87     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
88     *          {@link TextToSpeechClient.Status#STOPPED} is also possible if called in context of
89     *          {@link TextToSpeechService#onSynthesizeTextV2}.
90     */
91    public int done();
92
93    /**
94     * The service should call this method if the speech synthesis fails.
95     *
96     * This method should only be called on the synthesis thread,
97     * while in {@link TextToSpeechService#onSynthesizeText}.
98     */
99    public void error();
100
101
102    /**
103     * The service should call this method if the speech synthesis fails.
104     *
105     * This method should only be called on the synthesis thread,
106     * while in {@link TextToSpeechService#onSynthesizeText} or
107     * {@link TextToSpeechService#onSynthesizeTextV2}.
108     *
109     * @param errorCode Error code to pass to the client. One of the ERROR_ values from
110     *      {@link TextToSpeechClient.Status}
111     */
112    public void error(int errorCode);
113
114    /**
115     * Communicate to client that the original request can't be done and client-requested
116     * fallback is happening.
117     *
118     * Fallback can be requested by the client by setting
119     * {@link TextToSpeechClient.Params#FALLBACK_VOICE_NAME} voice parameter with a id of
120     * the voice that is expected to be used for the fallback.
121     *
122     * This method will fail if user called {@link #start(int, int, int)} and/or
123     * {@link #done()}.
124     *
125     * This method should only be called on the synthesis thread,
126     * while in {@link TextToSpeechService#onSynthesizeTextV2}.
127     *
128     * @return {@link TextToSpeech#SUCCESS}, {@link TextToSpeech#ERROR} if client already
129     *          called {@link #start(int, int, int)}, {@link TextToSpeechClient.Status#STOPPED}
130     *          if stop was requested.
131     */
132    public int fallback();
133
134    /**
135     * Check if {@link #start} was called or not.
136     *
137     * This method should only be called on the synthesis thread,
138     * while in {@link TextToSpeechService#onSynthesizeText} or
139     * {@link TextToSpeechService#onSynthesizeTextV2}.
140     *
141     * Useful for checking if a fallback from network request is possible.
142     */
143    public boolean hasStarted();
144
145    /**
146     * Check if {@link #done} was called or not.
147     *
148     * This method should only be called on the synthesis thread,
149     * while in {@link TextToSpeechService#onSynthesizeText} or
150     * {@link TextToSpeechService#onSynthesizeTextV2}.
151     *
152     * Useful for checking if a fallback from network request is possible.
153     */
154    public boolean hasFinished();
155}
156