Skip to main content

Voice instructions

The Mapbox Navigation SDK allows you to provide prompt and detailed voice instructions to users of your application. You can use a voice instruction to notify the user of an upcoming turn or announce that a faster route has been detected.

The Navigation SDK uses the Mapbox Java SDK's VoiceInstructions class to hold information that should be announced out loud by the device (for example, the street that the user should stay on for a certain distance).

Use default voice instructions

There are two steps to play voice instructions in your application: generate an announcement and then play an announcement.

Create an instance of the speech API

Before you can generate an announcement, you need to instantiate the speech API in your Activity or Fragment:

val speechApi = MapboxSpeechApi(this, Locale.US.toLanguageTag())

Create an instance of the voice instructions player

And before you can play an announcement, you need to instantiate the text-to-speech engine in onCreate of your Activity or onActivityCreated of your Fragment. Do not use lazy initialization for this class since it takes some time to initialize the system services required for on-device speech synthesis. With lazy initialization there is a high risk that said services will not be available when the first instruction has to be played.

lateinit var voiceInstructionsPlayer: MapboxVoiceInstructionsPlayer

override fun onCreate() {
// do your initialization here
voiceInstructionsPlayer = MapboxVoiceInstructionsPlayer(

Generate and play an announcement

Start by generating the content of the announcement using MapboxSpeechApi. MapboxSpeechApi accepts a VoiceInstructions object and returns a state object that includes the content of the announcement when it is ready or an error and a fallback with the raw announcement.

Then, pass the content of the announcement to MapboxVoiceInstructionsPlayer, which will play the announcement aloud. If you provide a synthesized speech MP3 which was successfully generated with the MapboxSpeechApi, a media player will be used to play the instruction. If not, an onboard speech-to-text engine, obtained using built-in Android APIs, will be used to synthesize the raw announcement's text.

The result of invoking MapboxSpeechApi#generate is returned as a callback containing either a success in the form of SpeechValue or failure in the form of SpeechError.

val speechCallback =
MapboxNavigationConsumer<Expected<SpeechError, SpeechValue>> { expected ->
{ error ->
// In case of error, a fallback announcement is returned that can be played
// using [MapboxVoiceInstructionsPlayer]
{ value ->
// The announcement data obtained (synthesized speech mp3 file from Mapbox's API Voice) is played
// using [MapboxVoiceInstructionsPlayer]

val voiceInstructionsObserver =
VoiceInstructionsObserver { voiceInstructions ->
// The data obtained must be used to generate the speech announcement

The result of invoking MapboxVoiceInstructionsPlayer#play is returned as a callback containing SpeechAnnouncement. This can be used to cleanup any associated files generated before:

val voiceInstructionsPlayerCallback =
MapboxNavigationConsumer<SpeechAnnouncement> { value ->
// Remove already consumed file to free-up space
Using only the onboard TTS engine
To decrease latency and cost you can consider using only the MapboxVoiceInstructionsPlayer with manually created SpeechAnnouncements with only announcement text value which will rely only on the usage of the onboard TTS engine.

Start and stop receiving voice events

Register a VoiceInstructionsObserver with MapboxNavigation:


Don't forget to unregister the observer, cancel any potential in-flight MapboxSpeechApi requests and shutdown MapboxVoiceInstructionsPlayer in onStop or onDestroy:

override fun onDestroy() {

Also, every time a new route is obtained make sure to cancel any potential in-flight MapboxSpeechApi requests and clear the MapboxVoiceInstructionsPlayer queue:

val routesObserver =
RoutesObserver { result ->
// Every time a new route is obtained make sure to cancel the [MapboxSpeechApi] and
// clear the [MapboxVoiceInstructionsPlayer]

Adjust voice instructions volume

To set the volume level of MapboxVoiceInstructionsPlayer you need to provide a value between 0.0 (mute) and 1.0 (max) through SpeechVolume:

// This is used to set the speech volume to mute
Was this page helpful?