Gemini Tts

Gemini TTS - Read-Aloud Speech Skill

Use the Python script in scripts/ to turn text into natural read-aloud audio via Google Gemini TTS. Model: gemini-3.1-flash-tts-preview (single TTS model — there is no Pro variant).

The mode is automatically detected from the input:

• Detected 2 speaker labels → multi-speaker (2 is a hard limit)
• Detected 1 or 0 → single-speaker
• Detected 3+ → warns and falls back to single-speaker narration
• Override with --single / --multi

Prerequisites

1. Install dependencies

pip install google-genai

2. Configure API credentials (one of the following)

Option A: Gemini Developer API (recommended for personal use)

Set the GEMINI_API_KEY environment variable. Get a key at https://aistudio.google.com/apikey

export GEMINI_API_KEY="your-api-key"

Option B: Vertex AI API (for Google Cloud users)

Set GOOGLE_CLOUD_PROJECT and optionally GOOGLE_CLOUD_LOCATION. Requires a GCP project with the Vertex AI API enabled and Application Default Credentials configured (gcloud auth application-default login).

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"   # optional, defaults to us-central1

Priority: If both GOOGLE_CLOUD_PROJECT and GEMINI_API_KEY are set, Vertex AI is used.

3. Optional environment variables

Script

scripts/generate.py - Text-to-speech generation

Basic narration (single voice)

python scripts/generate.py "Have a wonderful day!" -o hello.wav

Choose a voice and style

python scripts/generate.py "Welcome aboard!" --voice Puck --style cheerfully -o welcome.wav

You can also steer delivery inline with audio tags, e.g. [whispers], [shouting], [excitedly], or a natural-language prefix like Say in a calm voice:.

Read text from a file (good for long input)

python scripts/generate.py -f article.txt -o article.wav

Multi-speaker dialogue (auto-detected)

Given dialogue.txt:

Taro: How's it going today, Hanako?
Hanako: Not too bad, how about you?

python scripts/generate.py -f dialogue.txt -o conversation.wav

Assign voices to speakers explicitly

python scripts/generate.py -f dialogue.txt \
  --speaker "Taro:Kore" --speaker "Hanako:Puck" -o conversation.wav

List available voices

python scripts/generate.py --list-voices

Disable SSL verification (for corporate proxies or self-signed certs)

python scripts/generate.py "hello" --no-ssl-verify -o hello.wav

JSON output (for programmatic use)

python scripts/generate.py "hello" --json -o hello.wav

Full options

usage: generate.py [-h] [-f FILE] [-o OUTPUT] [--voice VOICE]
                   [--speaker "Name:Voice"] [--style STYLE]
                   [--temperature T] [--single] [--multi] [--list-voices]
                   [-v] [--json] [--no-ssl-verify] [text]

Arguments:
  text                Text to read aloud (or use -f)

Options:
  -f, --file PATH     Read input text from a file
  -o, --output PATH   Output .wav file path (auto-generated if omitted)
  --voice VOICE       Voice for single-speaker mode (default: Zephyr)
  --speaker "N:V"     Multi-speaker voice mapping "Name:Voice" (repeatable)
  --style STYLE       Style prefix for single speaker (e.g. "cheerfully")
  --temperature T     Sampling temperature (default: 1.0)
  --single            Force single-speaker mode
  --multi             Force multi-speaker mode (requires 2 "Name:" speakers)
  --list-voices       List the available prebuilt voices and exit
  -v, --verbose       Show detailed output
  --json              Output result as JSON
  --no-ssl-verify     Disable SSL certificate verification

--single and --multi are mutually exclusive.

Output Format

Gemini TTS returns raw PCM (audio/L16;rate=24000, mono). The script wraps it in a WAV header and saves a playable .wav file (16-bit, 24 kHz, mono).

Voices

30 prebuilt voices are available (e.g. Zephyr bright, Puck upbeat, Charon informative, Kore firm, Sulafat warm, Leda youthful, Enceladus breathy, Achernar soft). 70+ languages are supported — the output language follows the input text's language.

See references/voices.md for the full voice list with characteristics and a style / audio-tag guide.

Style & Delivery Control

• Natural-language prefix: Say cheerfully: ..., Read this slowly and calmly: ... (or use --style cheerfully, which prepends Say cheerfully:).
• Audio tags (inline): [whispers], [shouting], [laughs], [excitedly], [sarcastically], etc. — 200+ tags steer vocal style, pace, and delivery.
• Multi-speaker: label each line Name: text; the speaker names must match the --speaker "Name:Voice" mappings exactly.

Limitations

• Single TTS model: gemini-3.1-flash-tts-preview (no Pro variant).
• Multi-speaker cap: at most 2 speakers per request.
• No voice cloning: requests to imitate a specific real person's voice are blocked by safety filters.

Error Handling