Gemini Tts

Setup

Install dependencies:

pip install -r scripts/requirements.txt

API key — set GOOGLE_API_KEY in your environment or a .env file:

GOOGLE_API_KEY=your_key_here

Import tools:

from scripts.tts_tools import generate_speech, get_asset_info, inspect_asset

Quick Start — Simple TTS

generate_speech(text="Welcome to our product tour.")

Output saved to ./tts_output/tts-<timestamp>.wav by default.

Specifying Output Path

generate_speech(
    text="Welcome to our product tour.",
    output_path="audio/intro.wav"
)

Choosing a Voice

Pick a voice that fits the tone:

Full 30-voice list → references/voices.md

Adding Style

generate_speech(
    text="This is the moment everything changed.",
    voice_name="Sulafat",
    style_prompt="Speak slowly and dramatically, like a documentary narrator building suspense."
)

Multi-Speaker Dialogue

generate_speech(
    text="""Alex: Hey, did you see the new release?
Sam: Yeah, it looks incredible!""",
    speakers=[
        {"name": "Alex", "voice_name": "Kore"},
        {"name": "Sam",  "voice_name": "Puck"}
    ]
)

• Max 2 speakers per request.
• Speaker names must exactly match the labels used in the text.
• Multi-speaker only works with gemini-2.5-flash-preview-tts.

Full multi-speaker details → references/multi-speaker.md

Core Workflow

1. Generate with generate_speech(...) → saves WAV to your output path.
2. Measure with get_asset_info(...) → get exact duration.
3. Adjust — if duration doesn't match target, rewrite text shorter/longer and regenerate.
4. Validate with inspect_asset(...) → check pronunciation, pacing, emotional fit.
5. Iterate chunk by chunk until satisfied.

Tool Reference

generate_speech

generate_speech(
    text: str,                    # Required.
    output_path: str = None,      # Optional. Absolute or relative path, e.g. "audio/intro.wav"
    output_dir: str = None,       # Optional. Base dir for auto-named files (default: ./tts_output)
    voice_name: str = "Kore",     # Optional. Any of the 30 prebuilt voices.
    style_prompt: str = "",       # Optional. Natural-language delivery instructions.
    model: str = "gemini-2.5-flash-preview-tts",  # Optional.
    speakers: list = None         # Optional. For multi-speaker: [{"name": ..., "voice_name": ...}]
)

Returns: { success, path, voice_name, model, duration_seconds, sample_rate_hz, channels, size_bytes, text_characters } On error: { error: "..." }

Output is always 24 kHz mono WAV (PCM 16-bit).

get_asset_info

get_asset_info(asset_path: str)

Returns file metadata. For WAV files, reads duration without ffprobe. For video/audio, uses ffprobe if installed.

Returns: { path, size_bytes, mime_type, duration_seconds, ... }

inspect_asset

inspect_asset(
    asset_path: str,
    prompt: str = "",    # Optional. What to analyze.
    model: str = None,   # Optional. Defaults to GEMINI_MODEL env var or "gemini-2.0-flash".
)

Uploads the file to Gemini and returns an analysis (tone, pacing, quality issues, etc.).

Models

Note: Both models are in preview. Model IDs may change when they reach GA.

Prompting Quick Guide

For simple tasks, a one-line style_prompt is enough:

• "Read in a calm, professional tone."
• "Excited sports announcer style."
• "Whisper softly, like telling a secret."

For complex performances, structure the prompt:

1. Audio Profile — Who is speaking (name, role, character).
2. Scene — Environment, mood.
3. Director's Notes — Style, pacing, accent.
4. Transcript — The actual text.

Full prompting guide → references/prompting-style-and-flow.md

When to Read References

References

• references/models-and-limits.md
• references/voices.md
• references/languages.md
• references/prompting-style-and-flow.md
• references/multi-speaker.md
• references/timeline-integration.md