Added in API level 14

TextToSpeechService


abstract class TextToSpeechService : Service
kotlin.Any
   ↳ 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:

The first three deal primarily with language management, and are used to query the engine for it's support for a given language and indicate to it that requests in a given language are imminent. onSynthesizeText 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: The first three methods are siblings of the onGetLanguage, onIsLanguageAvailable and onLoadLanguage 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
Public constructors

Public methods
open IBinder?
onBind(intent: Intent!)

open Unit

open Unit

open String!
onGetDefaultVoiceNameFor(lang: String!, country: String!, variant: String!)

Return a name of the default voice for a given locale.

open MutableList<Voice!>!

Queries the service for a set of supported voices.

open Int

Checks whether the engine supports a voice with a given name.

open Int
onLoadVoice(voiceName: String!)

Notifies the engine that it should load a speech synthesis voice.

Protected methods
open MutableSet<String!>!
onGetFeaturesForLanguage(lang: String!, country: String!, variant: String!)

Queries the service for a set of features supported for a given language.

abstract Array<String!>!

Returns the language, country and variant currently being used by the TTS engine.

abstract Int
onIsLanguageAvailable(lang: String!, country: String!, variant: String!)

Checks whether the engine supports a given language.

abstract Int
onLoadLanguage(lang: String!, country: String!, variant: String!)

Notifies the engine that it should load a speech synthesis language.

abstract Unit

Notifies the service that it should stop any in-progress speech synthesis.

abstract Unit

Tells the service to synthesize speech from the given text.

Inherited functions

Public constructors

TextToSpeechService

TextToSpeechService()

Public methods

onBind

Added in API level 14
open fun onBind(intent: Intent!): IBinder?
Parameters
intent Intent!: The Intent that was used to bind to this service, as given to android.content.Context#bindService. Note that any extras that were included with the Intent at that point will not be seen here.
Return
IBinder? Return an IBinder through which clients can call on to the service.

onCreate

Added in API level 14
open fun onCreate(): Unit

onDestroy

Added in API level 14
open fun onDestroy(): Unit

onGetDefaultVoiceNameFor

Added in API level 21
open fun onGetDefaultVoiceNameFor(
    lang: String!,
    country: String!,
    variant: String!
): String!

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.
Return
String! A name of the default voice for a given locale.

onGetVoices

Added in API level 21
open fun onGetVoices(): MutableList<Voice!>!

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.

Return
MutableList<Voice!>! A list of voices supported.

onIsValidVoiceName

Added in API level 21
open fun onIsValidVoiceName(voiceName: String!): Int

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.
Return
Int TextToSpeech#ERROR or TextToSpeech#SUCCESS.

onLoadVoice

Added in API level 21
open fun onLoadVoice(voiceName: String!): Int

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.
Return
Int TextToSpeech#ERROR or TextToSpeech#SUCCESS.

Protected methods

onGetFeaturesForLanguage

Added in API level 15
protected open fun onGetFeaturesForLanguage(
    lang: String!,
    country: String!,
    variant: String!
): MutableSet<String!>!

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.
Return
MutableSet<String!>! A list of features supported for the given language.

onGetLanguage

Added in API level 14
protected abstract fun onGetLanguage(): Array<String!>!

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 framework. Can be called on multiple threads.

Return
Array<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

Added in API level 14
protected abstract fun onIsLanguageAvailable(
    lang: String!,
    country: String!,
    variant: String!
): Int

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.
Return
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

Added in API level 14
protected abstract fun onLoadLanguage(
    lang: String!,
    country: String!,
    variant: String!
): Int

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.
Return
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

Added in API level 14
protected abstract fun onStop(): Unit

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

Added in API level 14
protected abstract fun onSynthesizeText(
    request: SynthesisRequest!,
    callback: SynthesisCallback!
): Unit

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.