> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud TTS

> Use the Google Cloud Text-to-Speech plugin in a Zero Runtime pipeline. Setup, options, and usage in Python, JavaScript, and Go.

Google Cloud Text-to-Speech is a **text-to-speech** plugin. It synthesizes the LLM's reply
into the agent's voice using Google Cloud's voice families, from Standard through Chirp 3 HD.
It occupies the pipeline's `tts` slot.

## Setup

Set your Google credentials in the worker environment. Create a service account in the
[Google Cloud console](https://console.cloud.google.com/apis/credentials) and point the SDK at
its JSON key. The Python SDK resolves credentials in priority order: `credentials_json` →
`service_account_path` → `api_key` → the `GOOGLE_APPLICATION_CREDENTIALS` env var → a
`credentials.json` file in the working directory.

```bash theme={null}
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
```

<Note>
  The `api_key` argument also falls back to the `GOOGLE_API_KEY` env var.
</Note>

## Usage

Import the plugin and pass it to the pipeline's `tts` slot.

<CodeGroup>
  ```python Python theme={null}
  from zrt.plugins import GoogleTTS

  tts = GoogleTTS(
      voice="en-US-Neural2-F",
      language_code="en-US",
  )

  # Pipeline(tts=tts, ...)
  ```
</CodeGroup>

## Voice families

Cloud TTS routes by voice name, so the voice family is normally inferred from `voice`. You can
optionally pin the family with `model`, which accepts one of the known `GoogleTTSModel` values:
`"chirp3-hd"`, `"chirp-hd"`, `"studio"`, `"neural2"`, `"wavenet"`, `"standard"`, `"news"`,
`"polyglot"`, `"chirp"`. If the explicit `model` contradicts the family implied by `voice`, a
`ValueError` is raised.

```python Python theme={null}
from zrt.plugins import GoogleTTS

tts = GoogleTTS(
    voice="en-US-Chirp3-HD-Charon",
    model="chirp3-hd",
)
```

## Parameters

*Constructor parameters for the Python SDK (`GoogleTTS`). The JavaScript and Go SDKs expose `voice`, `languageCode`, `model`, `speakingRate`/`SpeakingRate`, and `pitch` in their idiomatic form.*

| Parameter              | Type                | Default             | Description                                                                                                                                                    |
| ---------------------- | ------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api_key`              | `str`               | `None`              | Google API key. Also used as a fallback credential source; falls back to the `GOOGLE_API_KEY` env var.                                                         |
| `credentials_json`     | `str`               | `None`              | Service-account credentials as a raw JSON string or a path to a JSON key file. Highest precedence.                                                             |
| `service_account_path` | `str`               | `None`              | Path to a service-account JSON key file. Used when `credentials_json` is not provided.                                                                         |
| `stream`               | `bool`              | `True`              | Stream audio back progressively for lower time-to-first-audio.                                                                                                 |
| `voice`                | `str`               | `"en-US-Neural2-F"` | Voice name in the form `{language}-{region}-{Family}-{Character}`. The name implicitly determines the voice family.                                            |
| `language_code`        | `str`               | `"en-US"`           | BCP-47 language code for the voice.                                                                                                                            |
| `model`                | `str`               | `""`                | Voice family override (`GoogleTTSModel`). Leave empty to let the voice name determine the family.                                                              |
| `sample_rate`          | `int`               | `24000`             | Output audio sample rate in Hz.                                                                                                                                |
| `speaking_rate`        | `float`             | `None`              | Playback speed multiplier, range `[0.25, 4.0]`. `None` uses the API default.                                                                                   |
| `pitch`                | `float`             | `None`              | Pitch shift in semitones, range `[-20.0, 20.0]`. `None` omits the parameter.                                                                                   |
| `voice_config`         | `GoogleVoiceConfig` | `None`              | Optional voice-selection dataclass (`name`, `languageCode`). Its fields take precedence over `voice` / `language_code` when those are still at their defaults. |

## Import paths

| SDK        | Import                              | Constructor                             |
| ---------- | ----------------------------------- | --------------------------------------- |
| Python     | `from zrt.plugins import GoogleTTS` | `GoogleTTS(...)`                        |
| JavaScript | `from '@zrt/js-sdk/plugins/google'` | `GoogleTTS({ ... })`                    |
| Go         | `.../zrt-golang-sdk/plugins/google` | `google.NewTTS(google.TTSOptions{...})` |

The synthesized audio is streamed back to the caller as the final stage of the
[pipeline](/concepts/pipeline).