Voice instructions

Join the Mapbox Developers Discord Communityarrow-right

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:

Java

Kotlin

val speechApi = MapboxSpeechApi(this, getMapboxAccessTokenFromResources(), 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.

Java

Kotlin

lateinit var voiceInstructionsPlayer: MapboxVoiceInstructionsPlayer

override fun onCreate() {
  // do your initialization here
  voiceInstructionsPlayer = MapboxVoiceInstructionsPlayer(
    this,
    getMapboxAccessTokenFromResources(),
    Locale.US.toLanguageTag()
  )
}

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, MapboxVoiceInstructionsPlayer will use the VoiceInstructionsFilePlayer speech player. If not, it will use VoiceInstructionsTextPlayer.

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.

Java

Kotlin

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

val voiceInstructionsObserver =
    VoiceInstructionsObserver { voiceInstructions ->
        // The data obtained must be used to generate the speech announcement
        speechAPI.generate(
            voiceInstructions,
            speechCallback
        )
    }

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

Java

Kotlin

val voiceInstructionsPlayerCallback =
    MapboxNavigationConsumer<SpeechAnnouncement> { value ->
        // Remove already consumed file to free-up space
        speechAPI.clean(value)
    }

Start and stop receiving voice events

Register a VoiceInstructionsObserver with MapboxNavigation:

Java

Kotlin

mapboxNavigation.registerVoiceInstructionsObserver(voiceInstructionsObserver)

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

Java

Kotlin

override fun onDestroy() {
    super.onDestroy()
    mapboxNavigation.unregisterVoiceInstructionsObserver(voiceInstructionsObserver)
    speechApi.cancel()
    voiceInstructionsPlayer.shutdown()
}

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

Java

Kotlin

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

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:

Java

Kotlin

// This is used to set the speech volume to mute
voiceInstructionsPlayer.volume(SpeechVolume(0.0f))

Join the Mapbox Developers Discord Communityarrow-right

Was this page helpful?