Developer

Voice instructions

VERSION 1.0.0
PUBLIC PREVIEW

Navigation SDK for Android is only available upon request. Contact us to get started.

The Navigation module includes Text To Speech (TTS) functionality for generating voice instructions. TTS is deployed as a separate module. This means that you have to add the following dependency to your module’s build.gradle.kts before you can use it.

implementation("com.tomtom.sdk:tts:1.0.0")

TTS engine

The TTS engine is responsible for providing voice synthesis for messages. The Navigation module provides a default AndroidTextToSpeechEngine based on Android’s TextToSpeech. However, you can also define a custom engine for text to speech conversion. Any custom engine must conform to the TextToSpeechEngine interface.

The TextToSpeech class is a facade for performing operations on TextToSpeechEngine. It takes care of queuing messages based on priority.

You can create TextToSpeech in two different ways.

  • A TextToSpeech that uses the default AndroidTextToSpeechEngine engine underneath: 
    val androidTtsEngine = AndroidTextToSpeechEngine(applicationContext)
    val tts = TextToSpeech(androidTtsEngine)
  • A TextToSpeech with a custom TextToSpeechEngine for voice synthesis: 
    val customTts = TextToSpeech(customTtsEngine)

OnEngineReadyListener

You can listen for whether the TextToSpeechEngine is ready to be used. To do so, set OnEngineReadyListener to TextToSpeech or to TextToSpeechEngine itself. If the listener has already been added, IllegalArgumentException is thrown. OnEngineReadyListener.onReady() is called when the engine is ready. OnEngineReadyListener.onError(TextToSpeechEngineError) is triggered if engine initialization ends with an error. TextToSpeechEngineError provides the reason for the failure.

1val onEngineReadyListener = object : OnEngineReadyListener {
2    override fun onReady() {
3        /* YOUR CODE GOES HERE */
4    }
5

6    override fun onError(error: TextToSpeechEngineError) {
7        /* YOUR CODE GOES HERE */
8    }
9}
10tts.addOnEngineReadyListener(onEngineReadyListener)

If the listener is no longer needed you can remove it. OnEngineReadyListener will be automatically removed when the TextToSpeech.close() method is called.

tts.removeOnEngineReadyListener(onEngineReadyListener)

Playing messages

The TextToSpeech.playAudioMessage(AudioMessage, MessageConfig, MessagePlaybackListener) and the TextToSpeech.playTaggedMessage(TaggedMessage, MessageConfig, MessagePlaybackListener) methods synthesize the provided message using the underlying TextToSpeechEngine. The MessageConfig parameter is used to configure the priority and time limit of the message. Message queuing depends on this priority. If the message that is currently being synthesized has an equal or higher priority to the new message, the new message will be added to the queue (taking the priorities of queued messages into account). If the message that is currently being synthesized has a lower priority than the new one, it will be interrupted and the new message will be processed right away.

val messageConfig = MessageConfig(priority = 10, timeout = TIMEOUT)

You must also provide a MessagePlaybackListener listener. It is used to provide the playback state. It consists of 4 methods that are triggered in different states.

1val messagePlaybackListener = object : MessagePlaybackListener {
2    override fun onStart() {
3        /* YOUR CODE GOES HERE */
4    }
5

6    override fun onDone() {
7        /* YOUR CODE GOES HERE */
8    }
9

10    override fun onError(error: TextToSpeechEngineError) {
11        /* YOUR CODE GOES HERE */
12    }
13

14    override fun onStop() {
15        /* YOUR CODE GOES HERE */
16    }
17}

Playing an audio message

To play an audio message, use the TextToSpeech.playAudioMessage(AudioMessage, MessageConfig, MessagePlaybackListener) method.

1val audioMessage = AudioMessage(
2    message = "In 300 meters turn left",
3    messageType = MessageType.Plain
4)
5tts.playAudioMessage(
6    audioMessage = audioMessage,
7    config = messageConfig,
8    playbackListener = messagePlaybackListener
9)

The AudioMessage can also be provided in Speech Synthesis Markup Language (SSML) format.

1val ssmlMessage = AudioMessage(
2    "<speak>Turn left onto <phoneme alphabet='ipa' ph='e¬¬.¬f¬¬¬'>A4</phoneme> towards " +
3        "<phoneme alphabet='ipa' ph=''sxep.fart.my.'2ze.^m'>Scheepvaartmuseum</phoneme></speak>",
4    MessageType.Ssml
5)

Playing a tagged message

You can also pass the TaggedMessage with phonetics to be substituted using the TextToSpeech.playTaggedMessage(TaggedMessage, MessageConfig, MessagePlaybackListener) method. To create a TaggedMessage, provide the message along with the tags to be synthesized as in the example. The second parameter is PhoneticTranscription. To create a PhoneticTranscription, provide:

  • List of phonetic transcriptions of phrases that are tagged in the message.
  • List of language codes in IETF format, sorted in the same order as the transcriptions.
  • Tag surrounding the phrase within the message.
  • Phonetic alphabet of the transcriptions (e.g. "ipa", "lhp").
1val roadNumberPhonetics = PhoneticTranscription(
2    transcriptions = listOf("e¬¬.¬f¬¬¬"),
3    locales = listOf(Locale("nl", "NL")),
4    tag = "roadNumber",
5    alphabet = "ipa"
6)
7val signpostPhonetics = PhoneticTranscription(
8    transcriptions = listOf("'sxep.fart.my.'2ze.^m"),
9    locales = listOf(Locale("nl", "NL")),
10    tag = "signpostText",
11    alphabet = "ipa"
12)
1val taggedMessage = TaggedMessage(
2    message = "Turn left onto <roadNumber>A4</roadNumber> " +
3        "towards<signpostText>Scheepvaartmuseum</signpostText>",
4    phonetics = listOf(roadNumberPhonetics, signpostPhonetics),
5    language = Locale.US
6)
7

8tts.playTaggedMessage(
9    taggedMessage = taggedMessage,
10    config = messageConfig,
11    playbackListener = messagePlaybackListener
12)

Language

The language of the underlying engine can be changed. Provide the new language in the form of the Locale. It can be done via the TextToSpeech constructor or with the TextToSpeech.changeLanguage(Locale) method. The language is set to American English by default.

tts.changeLanguage(Locale.forLanguageTag("pl-PL"))

Message cancellation

Both the TextToSpeech.playAudioMessage(AudioMessage, MessageConfig, MessagePlaybackListener) and TextToSpeech.playTaggedMessage(TaggedMessage, MessageConfig, MessagePlaybackListener) methods return a Cancellable object. It can be used to cancel the message.

If the message is in the queue it will be removed. If the process has already started, it will be stopped and the MessagePlaybackListener.onStop() will be called.

1val cancellable = tts.playAudioMessage(
2    audioMessage = audioMessage,
3    config = messageConfig,
4    playbackListener = messagePlaybackListener
5)
6cancellable.cancel()

You can also remove all messages from the queue using the TextToSpeech.clearQueue(Boolean) method. The provided parameter specifies whether the message currently being played should be stopped as well.

tts.clearQueue(stopCurrent = true)

Disposal

If the TextToSpeechEngine is no longer needed it should be disposed. You can do this either by calling TextToSpeechEngine.close() directly on the engine, or dispose the underlying engine with the TextToSpeech.close() method.

After the engine is disposed, audio messages cannot be synthesized. An EngineNotReadyError will be raised in that case.

tts.close()

Errors

The Navigation SDK provides the TextToSpeechEngineError error and its subclasses to report on errors that occurred in the AndroidTextToSpeechEngine.

Next steps

Since you have learned how to work with voice instructions, here are recommendations for the next steps: