# SpeechSynthesizer


```
public final class SpeechSynthesizer implements Closeable
```

<br />

*** ** * ** ***

Performs on-device text-to-speech audio synthesis.

One client serves every language. `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerOptions` only supplies a default locale; pass a locale to `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)` to list another language's voices, and the rest of the API follows the `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo` you hand it. There is no reason to `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#close()` and rebuild the client, or to keep one instance per language --- both pay for a Binder reconnect and buy nothing.

Typical usage:

```
// 1. Create a SpeechSynthesizer with desired options.
val options: SpeechSynthesizerOptions =
    speechSynthesizerOptions(Locale.US) {
        // Optionally configure a background executor
        // setExecutor(myExecutor)
        // Optionally fail instead of substituting a voice that is not installed
        // setVoiceFallbackEnabled(false)
    }
val speechSynthesizer: SpeechSynthesizer = SpeechSynthesis.getClient(options)

// 2. Find a supported voice and check its status.
lifecycleScope.launch {
    try {
        // Defaults to the options locale. Pass one to switch language:
        //     speechSynthesizer.getSupportedVoices(Locale.FRANCE)
        val supportedVoices: List<VoiceInfo> = speechSynthesizer.getSupportedVoices()
        val voiceToUse: VoiceInfo? =
            supportedVoices.firstOrNull { it.gender == VoiceInfo.Gender.FEMALE }

        if (voiceToUse != null) {
            val status: Int = speechSynthesizer.checkStatus(voiceToUse)
            if (status == FeatureStatus.DOWNLOADABLE) {
                // 3. If needed, download the voice model.
                speechSynthesizer.download(voiceToUse).collect { downloadStatus ->
                    when (downloadStatus) {
                        is DownloadStatus.DownloadCompleted -> {
                            // Model is ready, start synthesis.
                            startMySynthesis(speechSynthesizer, voiceToUse)
                        }
                        is DownloadStatus.DownloadFailed -> {
                            // Handle download failure.
                        }
                        is DownloadStatus.DownloadProgress -> {
                            // Handle download progress.
                        }
                        else -> {}
                    }
                }
            } else if (status == FeatureStatus.AVAILABLE) {
                // Model is ready, start synthesis.
                startMySynthesis(speechSynthesizer, voiceToUse)
            } else {
                // Handle other statuses like DOWNLOADING or UNAVAILABLE.
            }
        }
    } finally {
        // 5. Release resources. Closing outside the coroutine would tear down the client
        //    while the work above is still in flight.
        speechSynthesizer.close()
    }
}

// 4. Define your synthesis logic.
suspend fun startMySynthesis(synthesizer: SpeechSynthesizer, voice: VoiceInfo) {
  // Create a request and collect the responses.
  val request = SpeechSynthesizerRequest(
      input = SpeechSynthesizerRequest.Input.Text("Hello, world!", voice),
      audioAttributes = AudioAttributes.Builder()
          .setUsage(AudioAttributes.USAGE_MEDIA)
          .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
          .build()
  )
  synthesizer.synthesize(request).collect { response ->
      // Process the responses.
      when (response) {
          is SpeechSynthesizerResponse.StatusUpdate -> {
              when (response.status) {
                  SpeechSynthesizerResponse.Status.START -> { /* Started playing */}
                  SpeechSynthesizerResponse.Status.DONE -> { /* Playback finished */}
                  else -> {}
              }
          }
          is SpeechSynthesizerResponse.AudioAvailable -> {
              // Handle a chunk of synthesized audio
          }
          is SpeechSynthesizerResponse.Error -> {
              // Handle synthesis error. With setVoiceFallbackEnabled(false), a voice that
              // is not installed arrives here as ERROR_NOT_INSTALLED_YET.
          }
      }
  }
}
```

## Summary

| ### Public methods |
|---|---|
| `final @https://developers.google.com/android/reference/com/google/mlkit/genai/common/FeatureStatus int` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#checkStatus(com.google.mlkit.genai.texttospeech.VoiceInfo)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo voiceInfo)` Checks the availability status of a specific `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo`. |
| `void` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#close()()` Releases resources used by this `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/common/DownloadStatus>` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#download(com.google.mlkit.genai.texttospeech.VoiceInfo)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo voiceInfo)` Downloads the model assets required for speech synthesis with the specified `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/util/List.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo>` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/util/Locale.html locale)` Returns the voices supported for `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)`, defaulting to the locale configured in `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerOptions`. |
| `final void` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#stop()()` Stops any active or pending speech synthesis. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerResponse>` | `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#synthesize(com.google.mlkit.genai.texttospeech.SpeechSynthesizerRequest)(@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest request)` Synthesizes the input text from `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` into spoken audio. |

## Public methods

### checkStatus

```
public final @FeatureStatus int checkStatus(@NonNull VoiceInfo voiceInfo)
```

Checks the availability status of a specific `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo`.

| Returns |
|---|---|
| `@https://developers.google.com/android/reference/com/google/mlkit/genai/common/FeatureStatus int` | A `https://developers.google.com/android/reference/com/google/mlkit/genai/common/FeatureStatus` indicator representing the status of the voice. |

### close

```
public void close()
```

Releases resources used by this `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer`.

Subsequent calls are no-ops.

### download

```
public final @NonNull Flow<@NonNull DownloadStatus> download(@NonNull VoiceInfo voiceInfo)
```

Downloads the model assets required for speech synthesis with the specified `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/VoiceInfo`.

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/common/DownloadStatus>` | A `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` of `https://developers.google.com/android/reference/com/google/mlkit/genai/common/DownloadStatus` emitting progress updates and the download outcome. |

### getSupportedVoices

```
public final @NonNull List<@NonNull VoiceInfo> getSupportedVoices(@NonNull Locale locale)
```

Returns the voices supported for `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)`, defaulting to the locale configured in `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerOptions`.

Passing a locale here is cheaper than building a second `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizer`: the platform engine and the service connection are locale-independent, so a single instance can serve every language an app needs. Results are cached per locale for the lifetime of the instance.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developer.android.com/reference/java/util/Locale.html locale` | the locale to list voices for. A locale without a country (for example `https://developer.android.com/reference/java/util/Locale.html#FRENCH`) matches every region of that language. |

### stop

```
public final void stop()
```

Stops any active or pending speech synthesis.

### synthesize

```
public final @NonNull Flow<@NonNull SpeechSynthesizerResponse> synthesize(@NonNull SpeechSynthesizerRequest request)
```

Synthesizes the input text from `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` into spoken audio.

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest request` | The `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` containing the text input and synthesis configurations. |

| Returns |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull.html https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<@https://developer.android.com/reference/androidx/annotation/NonNull.html https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerResponse>` | A `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html` of `https://developers.google.com/android/reference/com/google/mlkit/genai/texttospeech/SpeechSynthesizerResponse` emitting audio data chunks and playback lifecycle updates. |