SynthesisRequest.java revision 4bbca889df9ca76c398f3a11e871fc6ad4a4514d 
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 request for speech synthesis given to a TTS engine for processing.
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 * Alternatively, the engine can provide all the audio at once, by using
26 * {@link #completeAudioAvailable}.
27 */
28public abstract class SynthesisRequest {
29
30    private final String mText;
31    private String mLanguage;
32    private String mCountry;
33    private String mVariant;
34    private int mSpeechRate;
35    private int mPitch;
36
37    public SynthesisRequest(String text) {
38        mText = text;
39    }
40
41    /**
42     * Sets the locale for the request.
43     */
44    void setLanguage(String language, String country, String variant) {
45        mLanguage = language;
46        mCountry = country;
47        mVariant = variant;
48    }
49
50    /**
51     * Sets the speech rate.
52     */
53    void setSpeechRate(int speechRate) {
54        mSpeechRate = speechRate;
55    }
56
57    /**
58     * Sets the pitch.
59     */
60    void setPitch(int pitch) {
61        mPitch = pitch;
62    }
63
64    /**
65     * Gets the text which should be synthesized.
66     */
67    public String getText() {
68        return mText;
69    }
70
71    /**
72     * Gets the ISO 3-letter language code for the language to use.
73     */
74    public String getLanguage() {
75        return mLanguage;
76    }
77
78    /**
79     * Gets the ISO 3-letter country code for the language to use.
80     */
81    public String getCountry() {
82        return mCountry;
83    }
84
85    /**
86     * Gets the language variant to use.
87     */
88    public String getVariant() {
89        return mVariant;
90    }
91
92    /**
93     * Gets the speech rate to use. The normal rate is 100.
94     */
95    public int getSpeechRate() {
96        return mSpeechRate;
97    }
98
99    /**
100     * Gets the pitch to use. The normal pitch is 100.
101     */
102    public int getPitch() {
103        return mPitch;
104    }
105
106    /**
107     * Gets the maximum number of bytes that the TTS engine can pass in a single call of
108     * {@link #audioAvailable}. This does not apply to {@link #completeAudioAvailable}.
109     */
110    public abstract int getMaxBufferSize();
111
112    /**
113     * Checks whether the synthesis request completed successfully.
114     */
115    abstract boolean isDone();
116
117    /**
118     * Aborts the speech request.
119     *
120     * Can be called from multiple threads.
121     */
122    abstract void stop();
123
124    /**
125     * The service should call this when it starts to synthesize audio for this
126     * request.
127     *
128     * This method should only be called on the synthesis thread,
129     * while in {@link TextToSpeechService#onSynthesizeText}.
130     *
131     * @param sampleRateInHz Sample rate in HZ of the generated audio.
132     * @param audioFormat Audio format of the generated audio. Must be one of
133     *         the ENCODING_ constants defined in {@link android.media.AudioFormat}.
134     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
135     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
136     */
137    public abstract int start(int sampleRateInHz, int audioFormat, int channelCount);
138
139    /**
140     * The service should call this method when synthesized audio is ready for consumption.
141     *
142     * This method should only be called on the synthesis thread,
143     * while in {@link TextToSpeechService#onSynthesizeText}.
144     *
145     * @param buffer The generated audio data. This method will not hold on to {@code buffer},
146     *         so the caller is free to modify it after this method returns.
147     * @param offset The offset into {@code buffer} where the audio data starts.
148     * @param length The number of bytes of audio data in {@code buffer}. This must be
149     *         less than or equal to the return value of {@link #getMaxBufferSize}.
150     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
151     */
152    public abstract int audioAvailable(byte[] buffer, int offset, int length);
153
154    /**
155     * The service should call this method when all the synthesized audio for a request has
156     * been passed to {@link #audioAvailable}.
157     *
158     * This method should only be called on the synthesis thread,
159     * while in {@link TextToSpeechService#onSynthesizeText}.
160     *
161     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
162     */
163    public abstract int done();
164
165    /**
166     * The service should call this method if the speech synthesis fails.
167     *
168     * This method should only be called on the synthesis thread,
169     * while in {@link TextToSpeechService#onSynthesizeText}.
170     */
171    public abstract void error();
172
173    /**
174     * The service can call this method instead of using {@link #start}, {@link #audioAvailable}
175     * and {@link #done} if all the audio data is available in a single buffer.
176     *
177     * @param sampleRateInHz Sample rate in HZ of the generated audio.
178     * @param audioFormat Audio format of the generated audio. Must be one of
179     *         the ENCODING_ constants defined in {@link android.media.AudioFormat}.
180     * @param channelCount The number of channels. Must be {@code 1} or {@code 2}.
181     * @param buffer The generated audio data. This method will not hold on to {@code buffer},
182     *         so the caller is free to modify it after this method returns.
183     * @param offset The offset into {@code buffer} where the audio data starts.
184     * @param length The number of bytes of audio data in {@code buffer}.
185     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
186     */
187    public abstract int completeAudioAvailable(int sampleRateInHz, int audioFormat,
188            int channelCount, byte[] buffer, int offset, int length);
189}