Voices | Navigation SDK UX Framework | Android Docs

The Navigation SDK UX Framework offers multiple Text-To-Speech (TTS) customization options, enabling developers to tailor speech functionalities to fit their application's specific needs. The SDK provides two main TTS options:

Prebuilt TTS: Customize Mapbox's built-in TTS solution.
Bring Your Own TTS: Integrate custom TTS engines for specialized requirements.

This guide covers both options, complete with implementation details and code examples.

Prebuilt TTS

Prebuilt TTS selects the available voice based on device capabilities and configuration. The TTS will use the device locale or the SDK configuration for language selection, will automatically switch between remote and local TTS depending on network conditions. It has optimizations like caching and streaming to provide the fastest possible experience. Using the prebuilt TTS is the simplest approach and subscribes you to improvements and updates from Mapbox.

Configuration

Configure prebuilt TTS through the DashVoicesConfig:

SelectedVoice: Chooses the remote voice persona. Ignored if preferLocalTts is true.
PreferLocalTts:
- true: Uses only the local voice.
- false: Primarily uses the remote voice, switching to local if the network is poor.
LocalTtsEngine: Specifies the local TTS engine. Defaults to the system engine if not found. For Android, refer to TextToSpeech for available engines.


Dash.init(
    context = this,
    accessToken = getString(R.string.mapbox_access_token),
) {
    voices {
        selectedVoice = PrebuiltDashVoices.voice1
        preferLocalTts = true
        localTtsEngine = "com.samsung.SMT"
    }
}

Change voice configuration at runtime with applyUpdate:


Dash.applyUpdate {
    voices {
        preferLocalTts = settings.isLocalTtsEnabled
    }
}

Remote TTS Audio Samples

Below are samples of the remote TTS voices:

0:00

Bring Your Own TTS

This feature allows you to inject your own TTS engine into the SDK, providing an ability to support unique platforms or integrate with various TTS services.

Implementation Steps

To integrate a custom TTS engine, follow these steps:

Implement the VoicePlayerMiddleware Interface:
- Access available resources through VoicePlayerMiddlewareContext which is provided by the onAttached method.
- Manage the lifecycle of your VoicePlayer implementation.
Implement the VoicePlayer Interface:
- Handle functionalities such as available voices, languages, playback state, and resource management within your implementation.
Integrate with the Mapbox Navigation SDK:
- Construct and inject your implementation with Dash.controller.setVoicePlayerMiddleware(...)

Integration Example

Switch between custom VoicePlayer and the SDK's default TTS engine as needed:


if (enabled) {
    Dash.controller.setVoicePlayerMiddleware(
        LocalVoicePlayerMiddleware()
    )
} else {
    Dash.controller.setDefaultVoicePlayerMiddleware()
}

Custom TTS Example

For a real-world implementation of the VoicePlayerMiddleware, visit our GitHub repository. The LocalVoicePlayerMiddleware.kt file demonstrates how to implement the VoicePlayer interface using Android's TextToSpeech API.

Understanding the SDK Integration Classes

Developing a custom TTS engine involves understanding several key classes and functionalities provided by the SDK. Familiarizing yourself with these classes, as integrating with your own TTS has multiple challenges.

VoicePlayerMiddleware is the primary interface for integrating TTS into the Mapbox SDK. It manages lifecycle (onAttached and onDetached) and injects necessary SDK dependencies through VoicePlayerMiddlewareContext.
VoicePlayerMiddlewareContext provides access to essential SDK dependencies
- platformContext gives access to Android's Application Context.
- language is the SDK's expected language with an ISO code.
- voice is the SDK's selected voice persona.
- audioFocusManager offers an ability to request audio focus.
- soundPlayer offers an ability to play alerts and audio files.
VoicePlayer defines the core functionalities for voice playback.
- Must implement the PlayerCallback to communicate player state changes.
- Optional features such as prefetching announcements, adjusting volume levels, and applying audio effects like fade in/out.
Announcement contains the text that the system will speak with a specific voice.
PlayerCallback communicates playback state changes (start, finish, interruption) back to the Mapbox SDK, enabling synchronized UI updates and application logic.
VoiceProgress tracks the progress of an ongoing announcement, allowing playback to be resumed if stopped mid-way.
Voice represents the voice persona that is surfaced by the VoicePlayer availableVoices property.
Language indicates the languages supported by the TTS engine, surfaced through the availableLanguages property.