| name | gemini-tts |
| description | Generate spoken MP3 audio from text or Markdown with Gemini TTS. Use for narration, accessibility audio, voice previews, or reading a document aloud with a selected voice, pace, and delivery style. |
| license | MIT |
| compatibility | Requires Python 3.10+, google-genai 1.65+, ffmpeg, and a Gemini API key. Optional playback needs afplay, ffplay, or mpv. |
Gemini TTS
Generate an MP3 from inline text or a UTF-8 text/Markdown file with the bundled script.
Setup
Resolve paths relative to this SKILL.md; do not assume a particular install directory.
python3 -m pip install -r <skill-directory>/requirements.txt
export GEMINI_API_KEY='...'
GOOGLE_API_KEY and OPENCODE_GOOGLE_API_KEY are accepted as fallbacks. Set GEMINI_TTS_MODEL to override the default model.
Before generation
Confirm or infer:
- source text or file
- output path
- voice or template
- desired delivery notes and speed
- whether playback is wanted
For long input, report the chunk count before making paid API calls. Ask for confirmation when the request is unexpectedly large or the user has not clearly approved generation.
Discover voices and templates
python3 <skill-directory>/scripts/generate_tts.py --list-voices
python3 <skill-directory>/scripts/generate_tts.py --list-templates
python3 <skill-directory>/scripts/generate_tts.py --show-template mystery-narrator
Bundled templates include mystery-narrator, newscaster, whisper, empathetic, deadpan, promo-hype, and podcast-newsletter.
Generate audio
From text:
python3 <skill-directory>/scripts/generate_tts.py \
--text 'Read this clearly and naturally.' \
--voice Orus \
--output ./narration.mp3
From a file and template:
python3 <skill-directory>/scripts/generate_tts.py \
--file ./article.md \
--template podcast-newsletter \
--output ./article.mp3 \
--play
Customize delivery when needed:
python3 <skill-directory>/scripts/generate_tts.py \
--file ./script.txt \
--voice Kore \
--profile 'Calm technical narrator' \
--scene 'A quiet recording booth' \
--notes 'Clear diction, measured pace, neutral accent' \
--speed 1.1 \
--output ./script.mp3
Explicit CLI flags override template values. Templates override the hard defaults (Orus, speed 1.0).
Reliability controls
--max-workers N: concurrent chunk requests; default 1--requests-per-minute N: request throttle; default 8; 0 disables it--allow-partial: write an MP3 despite failed chunks; avoid unless the user accepts missing audio
Environment equivalents are GEMINI_TTS_MAX_WORKERS and GEMINI_TTS_RPM.
Verification
After generation:
- Confirm the command exited successfully.
- Confirm the MP3 exists and is non-empty.
- Report the exact output path.
- If playback was requested, report when no supported player is installed.
Never print API keys or include them in command examples, logs, or output files.
