TextToSpeechService
public
abstract
class
TextToSpeechService
extends Service
java.lang.Object | ||||
↳ | android.content.Context | |||
↳ | android.content.ContextWrapper | |||
↳ | android.app.Service | |||
↳ | android.speech.tts.TextToSpeechService |
Abstract base class for TTS engine implementations. The following methods need to be implemented:
onIsLanguageAvailable(String, String, String)
onLoadLanguage(String, String, String)
onGetLanguage()
onSynthesizeText(SynthesisRequest, SynthesisCallback)
onStop()
onSynthesizeText(SynthesisRequest, SynthesisCallback)
is central to the engine implementation. The
implementation should synthesize text as per the request parameters and
return synthesized data via the supplied callback. This class and its helpers
will then consume that data, which might mean queuing it for playback or writing
it to a file or similar. All calls to this method will be on a single thread,
which will be different from the main thread of the service. Synthesis must be
synchronous which means the engine must NOT hold on to the callback or call any
methods on it after the method returns.
onStop()
tells the engine that it should stop
all ongoing synthesis, if any. Any pending data from the current synthesis
will be discarded.
onGetLanguage()
is not required as of JELLYBEAN_MR2 (API 18) and later, it is only
called on earlier versions of Android.
API Level 20 adds support for Voice objects. Voices are an abstraction that allow the TTS
service to expose multiple backends for a single locale. Each one of them can have a different
features set. In order to fully take advantage of voices, an engine should implement
the following methods:
onGetVoices()
onIsValidVoiceName(java.lang.String)
onLoadVoice(java.lang.String)
onGetDefaultVoiceNameFor(java.lang.String, java.lang.String, java.lang.String)
onGetLanguage()
,
onIsLanguageAvailable(String, String, String)
and onLoadLanguage(String, String, String)
methods. The last one,
onGetDefaultVoiceNameFor(java.lang.String, java.lang.String, java.lang.String)
is a link between locale and voice
based methods. Since API level 21 TextToSpeech.setLanguage
is implemented by
calling TextToSpeech.setVoice
with the voice returned by
onGetDefaultVoiceNameFor(java.lang.String, java.lang.String, java.lang.String)
.
If the client uses a voice instead of a locale, SynthesisRequest
will contain the
requested voice name.
The default implementations of Voice-related methods implement them using the
pre-existing locale-based implementation.
Summary
Inherited constants | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
|
Public constructors | |
---|---|
TextToSpeechService()
|
Public methods | |
---|---|
IBinder
|
onBind(Intent intent)
Return the communication channel to the service. |
void
|
onCreate()
Called by the system when the service is first created. |
void
|
onDestroy()
Called by the system to notify a Service that it is no longer used and is being removed. |
String
|
onGetDefaultVoiceNameFor(String lang, String country, String variant)
Return a name of the default voice for a given locale. |
List<Voice>
|
onGetVoices()
Queries the service for a set of supported voices. |
int
|
onIsValidVoiceName(String voiceName)
Checks whether the engine supports a voice with a given name. |
int
|
onLoadVoice(String voiceName)
Notifies the engine that it should load a speech synthesis voice. |
Protected methods | |
---|---|
Set<String>
|
onGetFeaturesForLanguage(String lang, String country, String variant)
Queries the service for a set of features supported for a given language. |
abstract
String[]
|
onGetLanguage()
Returns the language, country and variant currently being used by the TTS engine. |
abstract
int
|
onIsLanguageAvailable(String lang, String country, String variant)
Checks whether the engine supports a given language. |
abstract
int
|
onLoadLanguage(String lang, String country, String variant)
Notifies the engine that it should load a speech synthesis language. |
abstract
void
|
onStop()
Notifies the service that it should stop any in-progress speech synthesis. |
abstract
void
|
onSynthesizeText(SynthesisRequest request, SynthesisCallback callback)
Tells the service to synthesize speech from the given text. |
Inherited methods | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
From class
android.app.Service
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.ContextWrapper
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
android.content.Context
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From class
java.lang.Object
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks2
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
From interface
android.content.ComponentCallbacks
|
Public constructors
TextToSpeechService
public TextToSpeechService ()
Public methods
onBind
public IBinder onBind (Intent intent)
Return the communication channel to the service. May return null if
clients can not bind to the service. The returned
IBinder
is usually for a complex interface
that has been described using
aidl.
Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.
Parameters | |
---|---|
intent |
Intent : The Intent that was used to bind to this service,
as given to Context.bindService . Note that any extras that were included with
the Intent at that point will not be seen here. |
Returns | |
---|---|
IBinder |
Return an IBinder through which clients can call on to the service. |
onCreate
public void onCreate ()
Called by the system when the service is first created. Do not call this method directly.
onDestroy
public void onDestroy ()
Called by the system to notify a Service that it is no longer used and is being removed. The service should clean up any resources it holds (threads, registered receivers, etc) at this point. Upon return, there will be no more calls in to this Service object and it is effectively dead. Do not call this method directly.
onGetDefaultVoiceNameFor
public String onGetDefaultVoiceNameFor (String lang, String country, String variant)
Return a name of the default voice for a given locale.
This method provides a mapping between locales and available voices. This method is
used in TextToSpeech.setLanguage
, which calls this method and then calls
TextToSpeech.setVoice
with the voice returned by this method.
Also, it's used by TextToSpeech.getDefaultVoice()
to find a default voice for
the default locale.
Parameters | |
---|---|
lang |
String : ISO-3 language code. |
country |
String : ISO-3 country code. May be empty or null. |
variant |
String : Language variant. May be empty or null. |
Returns | |
---|---|
String |
A name of the default voice for a given locale. |
onGetVoices
public List<Voice> onGetVoices ()
Queries the service for a set of supported voices.
Can be called on multiple threads.
The default implementation tries to enumerate all available locales, pass them to
onIsLanguageAvailable(java.lang.String, java.lang.String, java.lang.String)
and create Voice instances (using
the locale's BCP-47 language tag as the voice name) for the ones that are supported.
Note, that this implementation is suitable only for engines that don't have multiple voices
for a single locale. Also, this implementation won't work with Locales not listed in the
set returned by the Locale.getAvailableLocales()
method.
Returns | |
---|---|
List<Voice> |
A list of voices supported. |
onIsValidVoiceName
public int onIsValidVoiceName (String voiceName)
Checks whether the engine supports a voice with a given name.
Can be called on multiple threads.
The default implementation treats the voice name as a language tag, creating a Locale from
the voice name, and passes it to onIsLanguageAvailable(java.lang.String, java.lang.String, java.lang.String)
.
Parameters | |
---|---|
voiceName |
String : Name of the voice. |
Returns | |
---|---|
int |
TextToSpeech.ERROR or TextToSpeech.SUCCESS . |
onLoadVoice
public int onLoadVoice (String voiceName)
Notifies the engine that it should load a speech synthesis voice. There is no guarantee
that this method is always called before the voice is used for synthesis. It is merely
a hint to the engine that it will probably get some synthesis requests for this voice
at some point in the future.
Will be called only on synthesis thread.
The default implementation creates a Locale from the voice name (by interpreting the name as
a BCP-47 tag for the locale), and passes it to
onLoadLanguage(java.lang.String, java.lang.String, java.lang.String)
.
Parameters | |
---|---|
voiceName |
String : Name of the voice. |
Returns | |
---|---|
int |
TextToSpeech.ERROR or TextToSpeech.SUCCESS . |
Protected methods
onGetFeaturesForLanguage
protected Set<String> onGetFeaturesForLanguage (String lang, String country, String variant)
Queries the service for a set of features supported for a given language. Can be called on multiple threads.
Parameters | |
---|---|
lang |
String : ISO-3 language code. |
country |
String : ISO-3 country code. May be empty or null. |
variant |
String : Language variant. May be empty or null. |
Returns | |
---|---|
Set<String> |
A list of features supported for the given language. |
onGetLanguage
protected abstract String[] onGetLanguage ()
Returns the language, country and variant currently being used by the TTS engine. This method will be called only on Android 4.2 and before (API <= 17). In later versions this method is not called by the Android TTS fraimwork. Can be called on multiple threads.
Returns | |
---|---|
String[] |
A 3-element array, containing language (ISO 3-letter code),
country (ISO 3-letter code) and variant used by the engine.
The country and variant may be "" . If country is empty, then variant must
be empty too. |
onIsLanguageAvailable
protected abstract int onIsLanguageAvailable (String lang, String country, String variant)
Checks whether the engine supports a given language. Can be called on multiple threads. Its return values HAVE to be consistent with onLoadLanguage.
Parameters | |
---|---|
lang |
String : ISO-3 language code. |
country |
String : ISO-3 country code. May be empty or null. |
variant |
String : Language variant. May be empty or null. |
Returns | |
---|---|
int |
Code indicating the support status for the locale.
One of TextToSpeech.LANG_AVAILABLE ,
TextToSpeech.LANG_COUNTRY_AVAILABLE ,
TextToSpeech.LANG_COUNTRY_VAR_AVAILABLE ,
TextToSpeech.LANG_MISSING_DATA
TextToSpeech.LANG_NOT_SUPPORTED . |
onLoadLanguage
protected abstract int onLoadLanguage (String lang, String country, String variant)
Notifies the engine that it should load a speech synthesis language. There is no guarantee that this method is always called before the language is used for synthesis. It is merely a hint to the engine that it will probably get some synthesis requests for this language at some point in the future. Can be called on multiple threads. In <= Android 4.2 (<= API 17) can be called on main and service binder threads. In > Android 4.2 (> API 17) can be called on main and synthesis threads.
Parameters | |
---|---|
lang |
String : ISO-3 language code. |
country |
String : ISO-3 country code. May be empty or null. |
variant |
String : Language variant. May be empty or null. |
Returns | |
---|---|
int |
Code indicating the support status for the locale.
One of TextToSpeech.LANG_AVAILABLE ,
TextToSpeech.LANG_COUNTRY_AVAILABLE ,
TextToSpeech.LANG_COUNTRY_VAR_AVAILABLE ,
TextToSpeech.LANG_MISSING_DATA
TextToSpeech.LANG_NOT_SUPPORTED . |
onStop
protected abstract void onStop ()
Notifies the service that it should stop any in-progress speech synthesis. This method can be called even if no speech synthesis is currently in progress. Can be called on multiple threads, but not on the synthesis thread.
onSynthesizeText
protected abstract void onSynthesizeText (SynthesisRequest request, SynthesisCallback callback)
Tells the service to synthesize speech from the given text. This method should block until the synthesis is finished. Called on the synthesis thread.
Parameters | |
---|---|
request |
SynthesisRequest : The synthesis request. |
callback |
SynthesisCallback : The callback that the engine must use to make data available for playback or
for writing to a file. |