> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/ja/navigation/ux/llms.txt)

# Voices

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:

1.  **Prebuilt TTS:** Customize Mapbox's built-in TTS solution.
2.  **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](https://developer.android.com/reference/android/speech/tts/TextToSpeech) for available engines.

```kotlin
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`:

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

### Remote TTS Audio Samples

Below are samples of the remote TTS voices:

Your browser does not support the audio element.

0:00

0:00

Your browser does not support the audio element.

0:00

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:

1.  **Implement the `VoicePlayerMiddleware` Interface:**
    -   Access available resources through `VoicePlayerMiddlewareContext` which is provided by the `onAttached` method.
    -   Manage the lifecycle of your `VoicePlayer` implementation.
2.  **Implement the `VoicePlayer` Interface:**
    -   Handle functionalities such as available voices, languages, playback state, and resource management within your implementation.
3.  **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:

```kotlin
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](https://github.com/mapbox/dash-android-examples). The [`LocalVoicePlayerMiddleware.kt`](https://github.com/mapbox/dash-android-examples/blob/main/app/src/main/java/com/mapbox/dash/showcase/app/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.