1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of 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,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.speech.tts;
18
19import android.net.Uri;
20import android.os.Bundle;
21import android.os.ParcelFileDescriptor;
22import android.speech.tts.ITextToSpeechCallback;
23import android.speech.tts.Voice;
24
25/**
26 * Interface for TextToSpeech to talk to TextToSpeechService.
27 *
28 * {@hide}
29 */
30interface ITextToSpeechService {
31
32    /**
33     * Tells the engine to synthesize some speech and play it back.
34     *
35     * @param callingInstance a binder representing the identity of the calling
36     *        TextToSpeech object.
37     * @param text The text to synthesize.
38     * @param queueMode Determines what to do to requests already in the queue.
39     * @param param Request parameters.
40     * @param utteranceId Unique identifier of synthesized utterance.
41     */
42    int speak(in IBinder callingInstance, in CharSequence text, in int queueMode, in Bundle params,
43            String utteranceId);
44
45    /**
46     * Tells the engine to synthesize some speech and write it to a file.
47     *
48     * @param callingInstance a binder representing the identity of the calling
49     *        TextToSpeech object.
50     * @param text The text to synthesize.
51     * @param fileDescriptor The file descriptor to write the synthesized audio to. Has to be
52              writable.
53     * @param utteranceId Unique identifier of synthesized utterance.
54     * @param param Request parameters.
55     */
56    int synthesizeToFileDescriptor(in IBinder callingInstance, in CharSequence text,
57        in ParcelFileDescriptor fileDescriptor, in Bundle params, String utteranceId);
58
59    /**
60     * Plays an existing audio resource.
61     *
62     * @param callingInstance a binder representing the identity of the calling
63     *        TextToSpeech object.
64     * @param audioUri URI for the audio resource (a file or android.resource URI)
65     * @param queueMode Determines what to do to requests already in the queue.
66     * @param utteranceId Unique identifier of synthesized utterance.
67     * @param param Request parameters.
68     */
69    int playAudio(in IBinder callingInstance, in Uri audioUri, in int queueMode, in Bundle params,
70            String utteranceId);
71
72    /**
73     * Plays silence.
74     *
75     * @param callingInstance a binder representing the identity of the calling
76     *        TextToSpeech object.
77     * @param duration Number of milliseconds of silence to play.
78     * @param queueMode Determines what to do to requests already in the queue.
79     * @param utteranceId Unique id used to identify this request in callbacks.
80     */
81    int playSilence(in IBinder callingInstance, in long duration, in int queueMode,
82        in String utteranceId);
83
84    /**
85     * Checks whether the service is currently playing some audio.
86     */
87    boolean isSpeaking();
88
89    /**
90     * Interrupts the current utterance (if from the given app) and removes any utterances
91     * in the queue that are from the given app.
92     *
93     * @param callingInstance a binder representing the identity of the calling
94     *        TextToSpeech object.
95     */
96    int stop(in IBinder callingInstance);
97
98    /**
99     * Returns the language, country and variant currently being used by the TTS engine.
100     * Can be called from multiple threads.
101     *
102     * @return A 3-element array, containing language (ISO 3-letter code),
103     *         country (ISO 3-letter code) and variant used by the engine.
104     *         The country and variant may be {@code ""}. If country is empty, then variant must
105     *         be empty too.
106     */
107    String[] getLanguage();
108
109    /**
110     * Returns a default TTS language, country and variant as set by the user.
111     *
112     * Can be called from multiple threads.
113     *
114     * @return A 3-element array, containing language (ISO 3-letter code),
115     *         country (ISO 3-letter code) and variant used by the engine.
116     *         The country and variant may be {@code ""}. If country is empty, then variant must
117     *         be empty too.
118     */
119    String[] getClientDefaultLanguage();
120
121    /**
122     * Checks whether the engine supports a given language.
123     *
124     * @param lang ISO-3 language code.
125     * @param country ISO-3 country code. May be empty or null.
126     * @param variant Language variant. May be empty or null.
127     * @return Code indicating the support status for the locale.
128     *         One of {@link TextToSpeech#LANG_AVAILABLE},
129     *         {@link TextToSpeech#LANG_COUNTRY_AVAILABLE},
130     *         {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE},
131     *         {@link TextToSpeech#LANG_MISSING_DATA}
132     *         {@link TextToSpeech#LANG_NOT_SUPPORTED}.
133     */
134    int isLanguageAvailable(in String lang, in String country, in String variant);
135
136    /**
137     * Returns a list of features available for a given language. Elements of the returned
138     * string array can be passed in as keys to {@link TextToSpeech#speak} and
139     * {@link TextToSpeech#synthesizeToFile} to select a given feature or features to be
140     * used during synthesis.
141     *
142     * @param lang ISO-3 language code.
143     * @param country ISO-3 country code. May be empty or null.
144     * @param variant Language variant. May be empty or null.
145     * @return An array of strings containing the set of features supported for
146     *         the supplied locale. The array of strings must not contain
147     *         duplicates.
148     */
149    String[] getFeaturesForLanguage(in String lang, in String country, in String variant);
150
151    /**
152     * Notifies the engine that it should load a speech synthesis language.
153     *
154     * @param caller a binder representing the identity of the calling
155     *        TextToSpeech object.
156     * @param lang ISO-3 language code.
157     * @param country ISO-3 country code. May be empty or null.
158     * @param variant Language variant. May be empty or null.
159     * @return Code indicating the support status for the locale.
160     *         One of {@link TextToSpeech#LANG_AVAILABLE},
161     *         {@link TextToSpeech#LANG_COUNTRY_AVAILABLE},
162     *         {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE},
163     *         {@link TextToSpeech#LANG_MISSING_DATA}
164     *         {@link TextToSpeech#LANG_NOT_SUPPORTED}.
165     */
166    int loadLanguage(in IBinder caller, in String lang, in String country, in String variant);
167
168    /**
169     * Sets the callback that will be notified when playback of utterance from the
170     * given app are completed.
171     *
172     * @param caller Instance a binder representing the identity of the calling
173     *        TextToSpeech object.
174     * @param cb The callback.
175     */
176    void setCallback(in IBinder caller, ITextToSpeechCallback cb);
177
178    /**
179     * Get the array of available voices.
180     */
181    List<Voice> getVoices();
182
183    /**
184     * Notifies the engine that it should load a speech synthesis voice.
185     *
186     * @param caller a binder representing the identity of the calling
187     *        TextToSpeech object.
188     * @param voiceName Unique voice of the name.
189     * @return {@link TextToSpeech#SUCCESS} or {@link TextToSpeech#ERROR}.
190     */
191    int loadVoice(in IBinder caller, in String voiceName);
192
193    /**
194     * Return a name of the default voice for a given locale.
195     *
196     * This allows {@link TextToSpeech#getVoice} to return a sensible value after a client calls
197     * {@link TextToSpeech#setLanguage}.
198     *
199     * @param lang ISO 3-character language code.
200     * @param country ISO 3-character country code. May be empty or null.
201     * @param variant Language variant. May be empty or null.
202     * @return Code indicating the support status for the locale.
203     *         One of {@link TextToSpeech#LANG_AVAILABLE},
204     *         {@link TextToSpeech#LANG_COUNTRY_AVAILABLE},
205     *         {@link TextToSpeech#LANG_COUNTRY_VAR_AVAILABLE},
206     *         {@link TextToSpeech#LANG_MISSING_DATA}
207     *         {@link TextToSpeech#LANG_NOT_SUPPORTED}.
208     */
209    String getDefaultVoiceNameFor(in String lang, in String country, in String variant);
210}
211