# SpeechSynthesizer


```
class SpeechSynthesizer : Closeable
```

<br />

*** ** * ** ***

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

One client serves every language. `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerOptions` only supplies a default locale; pass a locale to `https://developers.google.com/android/reference/kotlin/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/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo` you hand it. There is no reason to `https://developers.google.com/android/reference/kotlin/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:

```kotlin
// 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 functions |
|---|---|
| `suspend @https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/common/FeatureStatus https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#checkStatus(com.google.mlkit.genai.texttospeech.VoiceInfo)(voiceInfo: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo)` Checks the availability status of a specific `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo`. |
| `open https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#close()()` Releases resources used by this `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer`. |
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/common/DownloadStatus>` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#download(com.google.mlkit.genai.texttospeech.VoiceInfo)(voiceInfo: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo)` Downloads the model assets required for speech synthesis with the specified `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo`. |
| `suspend https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/index.html<https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/VoiceInfo>` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)(locale: https://developer.android.com/reference/java/util/Locale.html)` Returns the voices supported for `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#getSupportedVoices(java.util.Locale)`, defaulting to the locale configured in `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerOptions`. |
| `https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#stop()()` Stops any active or pending speech synthesis. |
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerResponse>` | `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizer#synthesize(com.google.mlkit.genai.texttospeech.SpeechSynthesizerRequest)(request: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest)` Synthesizes the input text from `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` into spoken audio. |

## Public functions

### checkStatus

```
suspend fun checkStatus(voiceInfo: VoiceInfo): @FeatureStatus Int
```

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

| Returns |
|---|---|
| `@https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/common/FeatureStatus https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html` | A `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/common/FeatureStatus` indicator representing the status of the voice. |

### close

```
open fun close(): Unit
```

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

Subsequent calls are no-ops.

### download

```
fun download(voiceInfo: VoiceInfo): Flow<DownloadStatus>
```

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

| Returns |
|---|---|
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/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/kotlin/com/google/mlkit/genai/common/DownloadStatus` emitting progress updates and the download outcome. |

### getSupportedVoices

```
suspend fun getSupportedVoices(locale: Locale = options.locale): List<VoiceInfo>
```

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

Passing a locale here is cheaper than building a second `https://developers.google.com/android/reference/kotlin/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 |
|---|---|
| `locale: https://developer.android.com/reference/java/util/Locale.html = options.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

```
fun stop(): Unit
```

Stops any active or pending speech synthesis.

### synthesize

```
fun synthesize(request: SpeechSynthesizerRequest): Flow<SpeechSynthesizerResponse>
```

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

| Parameters |
|---|---|
| `request: https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` | The `https://developers.google.com/android/reference/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerRequest` containing the text input and synthesis configurations. |

| Returns |
|---|---|
| `https://kotlin.github.io/kotlinx.coroutines/kotlinx-coroutines-core/kotlinx.coroutines.flow/-flow/index.html<https://developers.google.com/android/reference/kotlin/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/kotlin/com/google/mlkit/genai/texttospeech/SpeechSynthesizerResponse` emitting audio data chunks and playback lifecycle updates. |