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