<br />

The MediaPipe Text-to-Speech task lets you synthesize natural-sounding speech audio from
text directly on-device using open-weight neural text-to-speech
[models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models) (Kokoro-82M, PocketTTS 100M, or Phonon 31M), each packaged in
a single `.litertlm` bundle. The task operates as a headless PCM audio
generator, returning normalized 24 kHz mono 32-bit floating-point (`float32`)
audio samples that your application can play through platform audio APIs, save
as WAV files, or pass to downstream audio pipelines.


<iframe class="mp-demo-frame mp-demo-frame--studio" aria-label="Text-to-Speech interactive Web SDK demo" loading="lazy" data-src="https://developers.devsite.google/frame/edge/mediapipe/demos/embed/text_to_speech.jshtml" allow="camera *; microphone *"></iframe>

[Open in Web Demos](https://google-ai-edge.github.io/mediapipe-samples-web/#/audio/text_to_speech)[Edit in StackBlitz](https://stackblitz.com/github/google-ai-edge/mediapipe-samples-web?file=src/tasks/text-to-speech.ts)

<br />

> [!NOTE]
> **Note:** Please ensure you process voice data responsibly and in accordance with applicable law.

## Quickstart

Install the SDK for your platform, initialize the task with a model, and
synthesize full clips or streaming audio chunks.

> [!NOTE]
> **No `RunningMode` enum:** As a text-in, audio-out synthesis task, `TextToSpeech` does not use `AudioRunningMode` (`AUDIO_CLIPS` / `AUDIO_STREAM`). Instead, call `synthesize` / `synthesizeAsync` to generate a complete 24 kHz clip at once, or call `synthesizeStream` / `openStream` to stream `AudioChunk` buffers clause-by-clause for low time-to-first-audio.

### Web

npm`npm install @mediapipe/tasks-audio`[Web demo](https://google-ai-edge.github.io/mediapipe-samples-web/#/audio/text_to_speech)·[Edit in StackBlitz](https://stackblitz.com/github/google-ai-edge/mediapipe-samples-web?file=src/tasks/text-to-speech.ts)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_web.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one concatenated 24 kHz PCM waveform.

```typescript
import { FilesetResolver, TextToSpeech } from "@mediapipe/tasks-audio";

const audio = await FilesetResolver.forAudioTasks(
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-audio@latest/wasm"
);
// Use Kokoro-82M ("kokoro_int8_gpu_fp16.litertlm", delegate: "GPU") or Phonon 31M ("phonon_int8.litertlm", ~87 MB CPU).
const tts = await TextToSpeech.createFromOptions(audio, {
  baseOptions: {
    modelAssetPath: "kokoro_int8_gpu_fp16.litertlm",
    delegate: "GPU",
  },
  defaultVoiceId: "af_heart",
});

// Synthesize a 24 kHz mono clip
const audioResult = await tts.synthesize("Hello from MediaPipe Text to Speech in the browser!");
enqueuePcmPlayback(audioResult.samples, audioResult.sampleRateHz);
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is vocoded so playback starts immediately.

```typescript
import { FilesetResolver, TextToSpeech } from "@mediapipe/tasks-audio";

const audio = await FilesetResolver.forAudioTasks(
  "https://cdn.jsdelivr.net/npm/@mediapipe/tasks-audio@latest/wasm"
);
const tts = await TextToSpeech.createFromOptions(audio, {
  baseOptions: {
    modelAssetPath: "kokoro_int8_gpu_fp16.litertlm",
    delegate: "GPU",
  },
  defaultVoiceId: "af_heart",
});

// Clause-by-clause streaming (or call tts.openStream() -> stream.pushText(delta)
// -> stream.finishInput() to pipe live LLM tokens into speech)
const stream = await tts.synthesizeStream(
  "First sentence plays right away. Second sentence vocodes while the first plays."
);
for await (const chunk of stream) {
  enqueuePcmPlayback(chunk.samples, chunk.sampleRateHz);
}
```

### Android (Kotlin)

Gradle`implementation("com.google.mediapipe:tasks-audio:latest.release")`[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/text_to_speech/android)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_android.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one concatenated 24 kHz PCM waveform.

```kotlin
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeech
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeechOptions
import com.google.mediapipe.tasks.core.BaseOptions
import com.google.mediapipe.tasks.core.Delegate

val options = TextToSpeechOptions(
    baseOptions = BaseOptions.builder()
        .setModelAssetPath("${context.filesDir}/kokoro_int8_gpu_fp16.litertlm")
        .setDelegate(Delegate.GPU)
        .build(),
    defaultVoiceId = "af_heart",
    cacheDir = context.cacheDir.absolutePath,
)
val tts = TextToSpeech.create(options)

// Suspending unary call: returns one complete 24 kHz AudioResult.
// Call it from a coroutine (for example, lifecycleScope.launch { speak(...) }).
suspend fun speak(text: String): FloatArray {
    val audioResult = tts.synthesizeAsync(text)
    return audioResult.samples // 24 kHz mono PCM (audioResult.sampleRateHz)
}
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is vocoded so playback starts immediately.

```kotlin
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeech
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeechOptions
import com.google.mediapipe.tasks.core.BaseOptions
import com.google.mediapipe.tasks.core.Delegate

val options = TextToSpeechOptions(
    baseOptions = BaseOptions.builder()
        .setModelAssetPath("${context.filesDir}/kokoro_int8_gpu_fp16.litertlm")
        .setDelegate(Delegate.GPU)
        .build(),
    defaultVoiceId = "af_heart",
    cacheDir = context.cacheDir.absolutePath,
)
val tts = TextToSpeech.create(options)

// Clause-by-clause Flow<AudioChunk>: playback starts after the first clause
// (or call tts.openStream() -> stream.pushText(delta) -> stream.finishInput() for live LLM tokens).
suspend fun speakStreaming(text: String, onChunk: (FloatArray, Int) -> Unit) {
    tts.synthesizeStream(text).collect { chunk ->
        onChunk(chunk.samples, chunk.sampleRateHz)
    }
}
```

### Android (Java)

Gradle`implementation 'com.google.mediapipe:tasks-audio:latest.release'`[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/text_to_speech/android)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_android.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one concatenated 24 kHz PCM waveform.

```java
import com.google.mediapipe.tasks.audio.texttospeech.AudioResult;
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeech;
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeechOptions;
import com.google.mediapipe.tasks.core.BaseOptions;
import com.google.mediapipe.tasks.core.Delegate;

BaseOptions baseOptions = BaseOptions.builder()
    .setModelAssetPath(context.getFilesDir() + "/kokoro_int8_gpu_fp16.litertlm")
    .setDelegate(Delegate.GPU)
    .build();
TextToSpeechOptions options = new TextToSpeechOptions(
    baseOptions, "af_heart", null, 1.0f, 64, context.getCacheDir().getAbsolutePath()
);
TextToSpeech tts = TextToSpeech.create(options);

// Synchronous unary call on a worker thread: returns complete 24 kHz AudioResult
AudioResult audioResult = tts.synthesize("Hello from MediaPipe Text to Speech on Android!");
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is vocoded so playback starts immediately.

```java
import com.google.mediapipe.tasks.audio.texttospeech.AudioChunk;
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeech;
import com.google.mediapipe.tasks.audio.texttospeech.TextToSpeechOptions;
import com.google.mediapipe.tasks.audio.texttospeech.TtsStream;
import com.google.mediapipe.tasks.core.BaseOptions;
import com.google.mediapipe.tasks.core.Delegate;

BaseOptions baseOptions = BaseOptions.builder()
    .setModelAssetPath(context.getFilesDir() + "/kokoro_int8_gpu_fp16.litertlm")
    .setDelegate(Delegate.GPU)
    .build();
TextToSpeechOptions options = new TextToSpeechOptions(
    baseOptions, "af_heart", null, 1.0f, 64, context.getCacheDir().getAbsolutePath()
);
TextToSpeech tts = TextToSpeech.create(options);

// Pull-based streaming using TtsStream: play each clause chunk as soon as ready
try (TtsStream stream = tts.openStream(
    "First sentence plays right away. Second sentence follows seamlessly.",
    null,
    /* finishInput= */ true
)) {
    AudioChunk chunk;
    while ((chunk = stream.readNext()) != null) {
        float[] samples = chunk.getSamples(); // 24 kHz mono PCM (chunk.getSampleRateHz())
    }
}
```

### iOS

SwiftPM`https://github.com/google-ai-edge/mediapipe → MediaPipeTasksAudio`[Package.swift](https://developers.google.com/edge/mediapipe/solutions/setup_ios.md.txt#package_swift)·[Sample code](https://github.com/google-ai-edge/mediapipe-samples/tree/main/examples/text_to_speech/ios)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_ios.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one concatenated 24 kHz PCM waveform.

```swift
import Foundation
import MediaPipeTasksAudio

guard let modelPath = Bundle.main.path(forResource: "kokoro_int8_gpu_fp16", ofType: "litertlm") else { return }
let cacheDir = FileManager.default.temporaryDirectory.appendingPathComponent("mediapipe_tts_cache").path

let options = TextToSpeechOptions(
    baseOptions: TTSBaseOptions(modelAssetPath: modelPath, delegate: .gpu),
    defaultVoiceId: "af_heart",
    cacheDirectory: cacheDir
)
let tts = try TextToSpeech(options: options)

// Non-blocking unary call: returns one concatenated 24 kHz AudioResult
let audioResult = try await tts.synthesizeAsync("Hello from MediaPipe Text to Speech on Apple platforms!")
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is vocoded so playback starts immediately.

```swift
import Foundation
import MediaPipeTasksAudio

guard let modelPath = Bundle.main.path(forResource: "kokoro_int8_gpu_fp16", ofType: "litertlm") else { return }
let cacheDir = FileManager.default.temporaryDirectory.appendingPathComponent("mediapipe_tts_cache").path

let options = TextToSpeechOptions(
    baseOptions: TTSBaseOptions(modelAssetPath: modelPath, delegate: .gpu),
    defaultVoiceId: "af_heart",
    cacheDirectory: cacheDir
)
let tts = try TextToSpeech(options: options)

// AsyncThrowingStream<AudioChunk, Error>: play each clause as soon as vocoded
for try await chunk in tts.synthesizeStream(
    "First sentence plays right away. Second sentence streams seamlessly."
) {
    let samples = chunk.samples // 24 kHz mono Float samples (chunk.sampleRateHz)
}
```

### Python

pip`pip install mediapipe numpy`[Sample code](https://colab.research.google.com/github/google-ai-edge/mediapipe-samples/blob/main/examples/text_to_speech/python/text_to_speech.ipynb)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_python.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one concatenated 24 kHz PCM waveform.

```python
import os
import tempfile
import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
TextToSpeech = mp.tasks.audio.TextToSpeech
TextToSpeechOptions = mp.tasks.audio.TextToSpeechOptions

options = TextToSpeechOptions(
    base_options=BaseOptions(
        model_asset_path="kokoro_int8_gpu_fp16.litertlm",
        delegate=BaseOptions.Delegate.GPU,
    ),
    default_voice_id="af_heart",
    cache_dir=os.path.join(tempfile.gettempdir(), "mediapipe_tts_cache"),
)

with TextToSpeech.create_from_options(options) as tts:
    result = tts.synthesize("Hello from MediaPipe Text to Speech!")
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is vocoded so playback starts immediately.

```python
import os
import tempfile
import mediapipe as mp

BaseOptions = mp.tasks.BaseOptions
TextToSpeech = mp.tasks.audio.TextToSpeech
TextToSpeechOptions = mp.tasks.audio.TextToSpeechOptions

options = TextToSpeechOptions(
    base_options=BaseOptions(
        model_asset_path="kokoro_int8_gpu_fp16.litertlm",
        delegate=BaseOptions.Delegate.GPU,
    ),
    default_voice_id="af_heart",
    cache_dir=os.path.join(tempfile.gettempdir(), "mediapipe_tts_cache"),
)

with TextToSpeech.create_from_options(options) as tts:
    # Or use tts.open_stream() -> stream.push_text(delta) -> stream.finish_input() for LLM tokens
    for chunk in tts.synthesize_stream(
        "First sentence plays right away. Subsequent clauses synthesize in the background."
    ):
        play(chunk.samples, chunk.sample_rate_hz)
```

### Flutter

pub`flutter pub add mediapipe_audio`[Live gallery](https://google.github.io/flutter-mediapipe/)·[Sample code](https://github.com/google/flutter-mediapipe/tree/main/samples/audio/text_to_speech)·[Setup guide](https://developers.google.com/edge/mediapipe/solutions/setup_flutter.md.txt)

#### Full clip

`Full clip`Complete 24 kHz audioSynthesizes the full prompt and returns one 24 kHz PCM waveform.

```dart
import 'dart:typed_data';

import 'package:mediapipe_audio/mediapipe_audio.dart';

/// Speaks [text] in the first Phonon voice for [locale], or in freya when
/// none speaks it, and returns null if [stop] completes first.
Future<Float32List?> speakInLocale(
  String text,
  String locale, {
  Future<void>? stop,
}) async {
  final tts = await TextToSpeech.create(
    TextToSpeechOptions(model: AudioModels.phonon, defaultVoiceId: 'freya'),
  );
  stop?.then((_) => tts.cancel());
  try {
    final voices = await tts.listVoices();
    for (final voice in voices) {
      print('${voice.voiceId} (${voice.displayName}): ${voice.locale}');
    }
    final voice = voices.where((v) => v.locale == locale).firstOrNull;
    print('Speaking in ${voice?.voiceId ?? 'the default voice'}');
    final speech = await tts.synthesize(
      text,
      voiceId: voice?.voiceId,
      locale: voice?.locale,
    );
    return speech.samples;
  } on TaskException catch (error) {
    if (error.statusCode != 1) rethrow; // 1: Google's status for cancelled
    print('Stopped');
    return null;
  } finally {
    await tts.dispose();
  }
}
```

#### Audio stream

`Clause stream`Low-latency chunksStreams each synthesized clause chunk as soon as it is ready so playback starts early. Cancelling the subscription cancels the synthesis.

```dart
import 'dart:typed_data';

import 'package:mediapipe_audio/mediapipe_audio.dart';

/// Speaks [text] with Phonon, handing each chunk to [play] as soon as it is
/// ready. Completing [stop], from a Stop button for example, cancels the
/// rest.
Future<void> speakAsReady(
  String text, {
  required void Function(Float32List samples, int sampleRateHz) play,
  Future<void>? stop,
}) async {
  final tts = await TextToSpeech.create(
    TextToSpeechOptions(model: AudioModels.phonon),
  );
  final chunks = tts.synthesizeStream(text, voiceId: 'freya').listen((chunk) {
    // Chunk 0 can start playing while the rest is synthesized.
    play(chunk.samples, chunk.sampleRateHz);
    for (final word in chunk.wordTimestamps) {
      // Times count from the stream's start, not the chunk's.
      final spoken = text.substring(word.start, word.end);
      final at = word.startSeconds.toStringAsFixed(2);
      print('chunk ${chunk.chunkIndex}: $spoken at $at s');
    }
  });
  try {
    await Future.any([
      chunks.asFuture<void>(),
      if (stop != null) stop.then((_) => chunks.cancel()),
    ]);
  } finally {
    await tts.dispose();
  }
}
```

## Task details

This section describes the capabilities, inputs, outputs, and configuration
options of this task.

### Features

- **Single-file `.litertlm` deployment** - Packages each model's weights, text-processing data, and voice embeddings into a single `.litertlm` bundle.
- **Low-latency streaming synthesis** - Streams `AudioChunk` buffers clause by clause (`synthesizeStream` / `synthesize_stream`) so playback starts after the first clause, and accepts incremental text input (`openStream` / `open_stream` with `pushText` and `finishInput`) for LLM-to-speech pipelines.
- **Per-utterance voice switching** - Switches between bundled voices per utterance using `SynthesisOptions` without reloading the model (under 1 ms with Kokoro-82M).
- **Automatic sentence chunking** - Splits multi-sentence paragraphs at clause and sentence boundaries (`.`, `!`, `?`, `;`, `:`, `\n`) so long inputs stay within the model's context window.
- **Immediate cancellation** - Thread-safe `cancel()` aborts in-flight unary or streaming synthesis within milliseconds when a user interrupts.

Inputs The Text-to-Speech accepts the following inputs:

- UTF-8 text: a single sentence, a multi-sentence paragraph, or incremental text deltas pushed using `TtsStream`
- Optional per-utterance `SynthesisOptions` (`voice_id` and `locale` keyword arguments in Python, `voiceId` and `locale` named arguments in Flutter)
Outputs The Text-to-Speech outputs the following results:

- `AudioResult` (`TextToSpeechResult` on Web and Flutter, `TtsAudioResult` in Python) for unary calls
- A stream of `AudioChunk` (`TextToSpeechAudioChunk` on Web, `TextToSpeechResult` in Flutter) buffers with `chunkIndex` and `isFinal` metadata for streaming calls
- Normalized 32-bit float mono PCM samples in `[-1.0, 1.0]` at 24,000 Hz, plus optional `wordTimestamps` when produced by the model

### Configuration options

This task has the following configuration options:

### Web

| Option Name | Description | Value Range | Default Value |
|---|---|---|---|
| `baseOptions.modelAssetPath` | Path (or URL / `modelAssetBuffer` as a `Uint8Array` or `ReadableStreamDefaultReader` on Web) to a supported `.litertlm` model bundle (see [Models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models)). Keep the original filename, which the task uses to detect the model type. | String / Path | Required |
| `baseOptions.delegate` | Hardware acceleration delegate used by the LiteRT runtime. When set to `GPU`, the Kokoro acoustic stage executes on CPU (XNNPACK) and the neural vocoder executes on GPU (OpenCL/Metal/WebGPU) with CPU fallback. PocketTTS and Phonon run on CPU. | {`CPU`, `GPU`} | `CPU` |
| `speakingRate` | Speaking rate multiplier applied to synthesized audio (`1.0` represents normal speaking speed). | Float `(0.0, 4.0]` | `1.0` |
| `targetBucket` | Target sequence-length bucket for the Kokoro acoustic/vocoder graph (for example, `64`, `128`, or `256` tokens). Smaller buckets reduce synthesis latency for short sentences; `0` uses the model's default capacity. PocketTTS and Phonon ignore this option. | `0`, `64`, `128`, `256` | `0` |
| `defaultVoiceId` | Default voice ID (for example, `"af_heart"` for Kokoro-82M, `"alba"` for PocketTTS, or `"freya"` for Phonon). Can be overridden per utterance using `SynthesisOptions`. | String (Optional) | The model's default voice |
| `defaultLocale` | Optional default BCP 47 language tag (for example, `"en-US"`, `"es"`, `"zh-CN"`). When omitted, the task automatically infers the language from the selected voice. | BCP 47 String (Optional) | Inferred from voice (`"en-US"` in Python) |

**Per-utterance options (`SynthesisOptions`):**

| Option Name | Description | Default Value |
|---|---|---|
| `voiceId` | Overrides the voice profile for a single `synthesize` call (for example, switching from `"af_heart"` to `"ef_dora"` in under 1 ms without reloading model weights). | `null` (uses task default) |
| `locale` | Optional BCP 47 locale override for a single utterance. Leave unset when switching voices so the engine automatically resolves the target language from `voiceId`. | `null` (inferred from `voiceId`) |

### Android

| Option Name | Description | Value Range | Default Value |
|---|---|---|---|
| `baseOptions.modelAssetPath` | Path (or URL / `modelAssetBuffer` as a `Uint8Array` or `ReadableStreamDefaultReader` on Web) to a supported `.litertlm` model bundle (see [Models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models)). Keep the original filename, which the task uses to detect the model type. | String / Path | Required |
| `baseOptions.delegate` | Hardware acceleration delegate used by the LiteRT runtime. When set to `GPU`, the Kokoro acoustic stage executes on CPU (XNNPACK) and the neural vocoder executes on GPU (OpenCL/Metal/WebGPU) with CPU fallback. PocketTTS and Phonon run on CPU. | {`CPU`, `GPU`} | `CPU` |
| `speakingRate` | Speaking rate multiplier applied to synthesized audio (`1.0` represents normal speaking speed). | Float `(0.0, 4.0]` | `1.0` |
| `targetBucket` | Target sequence-length bucket for the Kokoro acoustic/vocoder graph (for example, `64`, `128`, or `256` tokens). Smaller buckets reduce synthesis latency for short sentences; `0` uses the model's default capacity. PocketTTS and Phonon ignore this option. | `0`, `64`, `128`, `256` | `0` |
| `defaultVoiceId` | Default voice ID (for example, `"af_heart"` for Kokoro-82M, `"alba"` for PocketTTS, or `"freya"` for Phonon). Can be overridden per utterance using `SynthesisOptions`. | String (Optional) | The model's default voice |
| `defaultLocale` | Optional default BCP 47 language tag (for example, `"en-US"`, `"es"`, `"zh-CN"`). When omitted, the task automatically infers the language from the selected voice. | BCP 47 String (Optional) | Inferred from voice (`"en-US"` in Python) |
| `cacheDir` | Writable directory path used to persist unpacked phonetic dictionary assets and LiteRT XNNPACK weight caches across runs for faster cold starts (Kokoro-82M). Pass `":nocache"` to disable caching. | Directory Path (Optional) | `""` |

**Per-utterance options (`SynthesisOptions`):**

| Option Name | Description | Default Value |
|---|---|---|
| `voiceId` | Overrides the voice profile for a single `synthesize` call (for example, switching from `"af_heart"` to `"ef_dora"` in under 1 ms without reloading model weights). | `null` (uses task default) |
| `locale` | Optional BCP 47 locale override for a single utterance. Leave unset when switching voices so the engine automatically resolves the target language from `voiceId`. | `null` (inferred from `voiceId`) |

### iOS

| Option Name | Description | Value Range | Default Value |
|---|---|---|---|
| `baseOptions.modelAssetPath` | Path (or URL / `modelAssetBuffer` as a `Uint8Array` or `ReadableStreamDefaultReader` on Web) to a supported `.litertlm` model bundle (see [Models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models)). Keep the original filename, which the task uses to detect the model type. | String / Path | Required |
| `baseOptions.delegate` | Hardware acceleration delegate used by the LiteRT runtime. When set to `GPU`, the Kokoro acoustic stage executes on CPU (XNNPACK) and the neural vocoder executes on GPU (OpenCL/Metal/WebGPU) with CPU fallback. PocketTTS and Phonon run on CPU. | {`CPU`, `GPU`} | `CPU` |
| `speakingRate` | Speaking rate multiplier applied to synthesized audio (`1.0` represents normal speaking speed). | Float `(0.0, 4.0]` | `1.0` |
| `targetBucket` | Target sequence-length bucket for the Kokoro acoustic/vocoder graph (for example, `64`, `128`, or `256` tokens). Smaller buckets reduce synthesis latency for short sentences; `0` uses the model's default capacity. PocketTTS and Phonon ignore this option. | `0`, `64`, `128`, `256` | `0` |
| `defaultVoiceId` | Default voice ID (for example, `"af_heart"` for Kokoro-82M, `"alba"` for PocketTTS, or `"freya"` for Phonon). Can be overridden per utterance using `SynthesisOptions`. | String (Optional) | The model's default voice |
| `defaultLocale` | Optional default BCP 47 language tag (for example, `"en-US"`, `"es"`, `"zh-CN"`). When omitted, the task automatically infers the language from the selected voice. | BCP 47 String (Optional) | Inferred from voice (`"en-US"` in Python) |
| `cacheDirectory` | Writable directory path used to persist unpacked phonetic dictionary assets and LiteRT XNNPACK weight caches across runs for faster cold starts (Kokoro-82M). Pass `":nocache"` to disable caching. | Directory Path (Optional) | `""` |

**Per-utterance options (`SynthesisOptions`):**

| Option Name | Description | Default Value |
|---|---|---|
| `voiceId` | Overrides the voice profile for a single `synthesize` call (for example, switching from `"af_heart"` to `"ef_dora"` in under 1 ms without reloading model weights). | `null` (uses task default) |
| `locale` | Optional BCP 47 locale override for a single utterance. Leave unset when switching voices so the engine automatically resolves the target language from `voiceId`. | `null` (inferred from `voiceId`) |

### Python

| Option Name | Description | Value Range | Default Value |
|---|---|---|---|
| `base_options.model_asset_path` | Path (or URL / `modelAssetBuffer` as a `Uint8Array` or `ReadableStreamDefaultReader` on Web) to a supported `.litertlm` model bundle (see [Models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models)). Keep the original filename, which the task uses to detect the model type. | String / Path | Required |
| `base_options.delegate` | Hardware acceleration delegate used by the LiteRT runtime. When set to `GPU`, the Kokoro acoustic stage executes on CPU (XNNPACK) and the neural vocoder executes on GPU (OpenCL/Metal/WebGPU) with CPU fallback. PocketTTS and Phonon run on CPU. | {`CPU`, `GPU`} | `CPU` |
| `speaking_rate` | Speaking rate multiplier applied to synthesized audio (`1.0` represents normal speaking speed). | Float `(0.0, 4.0]` | `1.0` |
| `target_bucket` | Target sequence-length bucket for the Kokoro acoustic/vocoder graph (for example, `64`, `128`, or `256` tokens). Smaller buckets reduce synthesis latency for short sentences; `0` uses the model's default capacity. PocketTTS and Phonon ignore this option. | `0`, `64`, `128`, `256` | `0` |
| `default_voice_id` | Default voice ID (for example, `"af_heart"` for Kokoro-82M, `"alba"` for PocketTTS, or `"freya"` for Phonon). Can be overridden per utterance using `SynthesisOptions`. | String (Optional) | The model's default voice |
| `default_locale` | Optional default BCP 47 language tag (for example, `"en-US"`, `"es"`, `"zh-CN"`). When omitted, the task automatically infers the language from the selected voice. | BCP 47 String (Optional) | Inferred from voice (`"en-US"` in Python) |
| `cache_dir` | Writable directory path used to persist unpacked phonetic dictionary assets and LiteRT XNNPACK weight caches across runs for faster cold starts (Kokoro-82M). Pass `":nocache"` to disable caching. | Directory Path (Optional) | `""` |

**Per-utterance keyword arguments on `synthesize` / `synthesize_stream`:**

| Option Name | Description | Default Value |
|---|---|---|
| `voice_id` | Overrides the voice profile for a single `synthesize` call (for example, switching from `"af_heart"` to `"ef_dora"` in under 1 ms without reloading model weights). | `None` (uses task default) |
| `locale` | Optional BCP 47 locale override for a single utterance. Leave unset when switching voices so the engine automatically resolves the target language from `voice_id`. | `None` (inferred from `voice_id`) |

### Flutter

| Option Name | Description | Value Range | Default Value |
|---|---|---|---|
| `model` / `modelPath` | The model bundle: one of Google's pinned `AudioModels.kokoro`, `AudioModels.pocketTtsEn`, or `AudioModels.phonon` (bundled at build time, or downloaded on first use when `ModelStore.allowDownloads` is `true`), or a `modelPath` to a supported `.litertlm` file (see [Models](https://developers.google.com/edge/mediapipe/solutions/audio/text_to_speech.md.txt#models)). Set exactly one. Keep the original filename, which the task uses to detect the model type. | `DownloadAsset` / File path | Required |
| `delegate` | Hardware acceleration delegate. `Delegate.gpu` runs Kokoro-82M's vocoder on the GPU and is offered only on macOS 15 and later on arm64; elsewhere, and for PocketTTS and Phonon, it throws a `RuntimeUnavailableException`. | {`Delegate.cpu`, `Delegate.gpu`} | `Delegate.cpu` |
| `speakingRate` | Speaking rate multiplier applied to synthesized audio (`1.0` represents normal speaking speed). | `double` `(0.0, 4.0]` | `1.0` |
| `targetBucket` | Target sequence-length bucket for the Kokoro acoustic/vocoder graph (`64`, `128`, or `256` tokens). Smaller buckets reduce synthesis latency for short sentences; `0` uses the model's default capacity. PocketTTS and Phonon ignore this option. | `0`, `64`, `128`, `256` | `0` |
| `defaultVoiceId` | Default voice ID (for example, `'af_heart'` for Kokoro-82M, `'alba'` for PocketTTS, or `'freya'` for Phonon). Can be overridden per call with `voiceId`. | `String` (Optional) | The model's default voice |
| `defaultLocale` | Optional default BCP 47 language tag (for example, `'en-US'`, `'es'`, `'zh-CN'`). When not set, the task infers the language from the selected voice. | BCP 47 `String` (Optional) | Inferred from voice |
| `cacheDirectory` | Writable directory where the task caches unpacked model files and compiled weights across runs for faster cold starts (Kokoro-82M). When not set, Kokoro caches next to its model file. Set this to `':nocache'` to turn caching off. | Directory path (Optional) | Not set |

**Per-utterance named arguments on `synthesize` / `synthesizeStream`:**

| Option Name | Description | Default Value |
|---|---|---|
| `voiceId` | Overrides the voice profile for a single `synthesize` call (for example, switching from `'af_heart'` to `'ef_dora'` in under 1 ms without reloading model weights). | `null` (uses `defaultVoiceId`) |
| `locale` | Optional BCP 47 locale override for a single utterance. Leave unset when switching voices so the engine automatically resolves the target language from `voiceId`. | `null` (uses `defaultLocale`) |

### Task output

Unary calls (`synthesize`) return a complete `AudioResult` (`TextToSpeechResult` on Web and in Dart, `TtsAudioResult` in Python), and streaming calls (`synthesizeStream` / `synthesize_stream`) yield `AudioChunk` buffers (`TextToSpeechResult` chunks in Dart) as each clause is vocoded:

| Field | Type / Range | Description |
|---|---|---|
| `samples` | `Float32Array` (`[-1.0, 1.0]`) | Synthesized mono PCM audio samples (a `Float32List` in Dart). |
| `sampleRateHz` | `int` (Hz) | Output audio sample rate, such as `24000` Hz for Kokoro (`sample_rate_hz` in Python). |
| `wordTimestamps` | `WordTimestamp[]` (seconds) | Optional word-level alignment intervals (`word`, `startTimeSec`, `endTimeSec`; in Dart, `word`, `startSeconds`, `endSeconds`, plus `start` and `end` UTF-16 indexes into the input text). |
| `chunkIndex` | `int` | Zero-based clause sequence index yielded on each streaming `AudioChunk` (`chunk_index` in Python). |
| `isFinal` | `boolean` | `true` on the final streaming `AudioChunk` of an utterance (`is_final` in Python). |

#### Example `TextToSpeechResult` payload

The following example shows synthesized 24 kHz mono PCM audio with word-level alignment timestamps:

```javascript
{
  sampleRateHz: 24000,
  samples: Float32Array(57600) [-0.0012, 0.0045, 0.0118 /* ... 2.4s mono PCM */],
  wordTimestamps: [
    { word: "Hello", startTimeSec: 0.04, endTimeSec: 0.38 },
    { word: "world", startTimeSec: 0.40, endTimeSec: 0.82 }
  ]
}
```

## Models

The MediaPipe Text-to-Speech task requires a speech synthesis model in the LiteRT-LM
(`.litertlm`) format. Models aren't included in the MediaPipe Tasks libraries.
Download one of the following pre-packaged model bundles from Hugging Face,
store it on the device, and pass the local path to
`BaseOptions.modelAssetPath` (`model_asset_path` in Python).

> [!NOTE]
> **Note:** Keep the original filename. The task uses the filename or the bundle's contents to detect the model type.

| Model | Model Bundle | Size | Quantization | Delegate | License | Supported Locales | Recommended Use Case |
|---|---|---|---|---|---|---|---|
| Kokoro-82M | [**`kokoro_int8_gpu_fp16.litertlm`**](https://huggingface.co/litert-community/Kokoro-82M/resolve/main/kokoro_int8_gpu_fp16.litertlm) | \~295 MB | INT8 acoustic + FP16 GPU vocoder | GPU | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) | All nine locales (`en-US`, `en-GB`, `es`, `fr-FR`, `it`, `pt-BR`, `hi`, `cmn`, `ja`) | Multilingual on-device speech synthesis across mobile, desktop, and web. |
| PocketTTS 100M | [**`pocket_tts_int8.litertlm`**](https://huggingface.co/litert-community/pocket-tts/resolve/main/pocket_tts_int8.litertlm) | \~760 MB | INT8 | CPU | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | Seven locales (`en-US`, `fr-FR`, `de-DE`, `es-ES`, `it-IT`, `pt-BR`, `nl-NL`) | Multilingual speech synthesis on CPU. |
| PocketTTS 100M (English) | [**`pocket_tts_en_int8.litertlm`**](https://huggingface.co/litert-community/pocket-tts/resolve/main/pocket_tts_en_int8.litertlm) | \~163 MB | INT8 | CPU | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) | `en-US` | English speech synthesis on CPU with a smaller download. |
| Phonon 31M | [**`phonon_int8.litertlm`**](https://huggingface.co/litert-community/phonon-31m-en/resolve/main/phonon_int8.litertlm) | \~87 MB | INT8 | CPU | [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0) | `en-US` | English speech synthesis with the smallest download. |

### Supported languages and voices

Each model bundle includes its own set of voices. You can enumerate the voices
in the loaded `.litertlm` bundle at runtime using `listVoices()` /
`list_voices()`.

#### Kokoro-82M voices

Kokoro-82M includes **54 pre-packaged voice embeddings** across **nine locales**
(eight languages). Each voice ID uses a two-letter prefix
`<lang_char><gender_char>_<name>` (for example, `af_heart` = American English
Female "Heart", `ef_dora` = Spanish Female "Dora").

> [!NOTE]
> **Note:** In Kokoro-82M, the voice prefix determines the phonemizer language. When switching voices using `SynthesisOptions` (or keyword arguments in Python), you only need to set `voiceId` (`voice_id` in Python)---leave `locale` unset (`null` / `None`) so the task automatically infers the matching BCP 47 language tag from the voice ID.

| Language | BCP 47 Language Tag | Prefix | Bundled Voice IDs (54 Total) |
|---|---|---|---|
| **English (American)** | `en-US` | `af_`, `am_` | **Female (11):** `af_alloy`, `af_aoede`, `af_bella`, `af_heart` *(default)* , `af_jessica`, `af_kore`, `af_nicole`, `af_nova`, `af_river`, `af_sarah`, `af_sky` **Male (9):** `am_adam`, `am_echo`, `am_eric`, `am_fenrir`, `am_liam`, `am_michael`, `am_onyx`, `am_puck`, `am_santa` |
| **English (British)** | `en-GB` | `bf_`, `bm_` | **Female (4):** `bf_alice`, `bf_emma`, `bf_isabella`, `bf_lily` **Male (4):** `bm_daniel`, `bm_fable`, `bm_george`, `bm_lewis` |
| **Spanish** | `es` | `ef_`, `em_` | **Female (1):** `ef_dora` **Male (2):** `em_alex`, `em_santa` |
| **French** | `fr-FR` | `ff_` | **Female (1):** `ff_siwis` |
| **Hindi** | `hi` | `hf_`, `hm_` | **Female (2):** `hf_alpha`, `hf_beta` **Male (2):** `hm_omega`, `hm_psi` |
| **Italian** | `it` | `if_`, `im_` | **Female (1):** `if_sara` **Male (1):** `im_nicola` |
| **Portuguese (Brazilian)** | `pt-BR` | `pf_`, `pm_` | **Female (1):** `pf_dora` **Male (2):** `pm_alex`, `pm_santa` |
| **Mandarin Chinese** | `zh-CN` / `cmn` | `zf_`, `zm_` | **Female (4):** `zf_xiaobei`, `zf_xiaoni`, `zf_xiaoxiao`, `zf_xiaoyi` **Male (4):** `zm_yunjian`, `zm_yunxi`, `zm_yunxia`, `zm_yunyang` |
| **Japanese** | `ja` | `jf_`, `jm_` | **Female (4):** `jf_alpha`, `jf_gongitsune`, `jf_nezumi`, `jf_tebukuro` **Male (1):** `jm_kumo` |

#### PocketTTS 100M voices

Each PocketTTS voice speaks one language. The multilingual bundle
(`pocket_tts_int8.litertlm`) includes all of the following voices, and the
English bundle (`pocket_tts_en_int8.litertlm`) includes only English voices.

| Language | BCP 47 Language Tag | Voice IDs |
|---|---|---|
| **English** | `en-US` | `alba` *(default)* , `azelma`, `cosette`, `eponine`, `fantine`, `javert`, `jean`, `marius` |
| **French** | `fr-FR` | `estelle` |
| **German** | `de-DE` | `juergen` |
| **Spanish** | `es-ES` | `lola` |
| **Italian** | `it-IT` | `giovanni` |
| **Portuguese (Brazilian)** | `pt-BR` | `rafael` |
| **Dutch** | `nl-NL` | `daan` |

As with Kokoro-82M, set only `voiceId` (`voice_id` in Python) when you switch
voices. If you also set a `locale` that doesn't match the voice's language, the
task uses the default voice for that locale instead.

#### Phonon 31M voices

Phonon 31M speaks English (`en-US`) only. It includes five voices:
`freya` *(default)* , `claire`, `lucas`, `lukas`, and `sofia`.

### Model license and attribution

Kyutai publishes PocketTTS under the
[Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/)
(CC-BY-4.0) license. If you distribute an app that uses a PocketTTS model, give
appropriate credit to Kyutai, for example in your app's open source notices.

## How it works

![Text-to-Speech pipeline overview](https://developers.google.com/static/edge/mediapipe/images/solutions/diagrams/text_to_speech.svg)

For Kokoro-82M, the MediaPipe Text-to-Speech task runs a multi-stage pipeline:

1. **Sentence segmentation** : Multi-sentence input text (or incremental text pushed using `TtsStream`) is split at punctuation boundaries to fit the acoustic model's token capacity.
2. **Grapheme-to-phoneme (G2P) frontend**: Converts normalized text into phoneme token IDs using the phonetic dictionaries bundled in the model for each supported language.
3. **Acoustic stage**: Runs the LiteRT acoustic model, conditioned on the selected voice's style embedding, to predict duration, pitch, and energy contours together with the acoustic features.
4. **Neural vocoder stage** : Runs the ISTFTNet-based LiteRT vocoder model (on CPU using XNNPACK, or hybrid CPU+GPU) to convert the acoustic features into a 24 kHz mono `float32` PCM waveform. During streaming synthesis, each clause's `AudioChunk` is emitted as soon as it is vocoded; unary synthesis concatenates all chunks into a single `AudioResult`.

PocketTTS 100M and Phonon 31M use a different architecture: a Flow-LM
transformer generates audio latents, and a Mimi neural audio decoder converts
them into 24 kHz audio. Both models run on CPU.