piper-tts - SKILL.md Agent Skill

name: piper-tts description: Generate local text-to-speech audio with Piper (offline, no API key required). Use when the user asks to convert text into spoken audio files (WAV), requests a specific Piper voice (for example es_MX-claude-high), wants slower/faster narration, or needs repeatable CLI-based TTS generation in this workspace.

Piper TTS

Generate WAV narration using Piper voices with a reusable script.

Quick start

Install Piper in a dedicated virtual environment:

python3 -m venv .venv-piper
.venv-piper/bin/python -m pip install --upgrade pip
.venv-piper/bin/python -m pip install piper-tts

Generate audio:

.venv-piper/bin/python skills/piper-tts/scripts/generate_piper_audio.py \
  --voice es_MX-claude-high \
  --text "Hola, esto es una prueba" \
  --output audio/prueba.wav

The script auto-downloads the requested voice on first use.

Workflow

1) Pick the voice and input source

Use --voice <name> for a Piper voice name.
Use --text for short content.
Use --text-file for longer content.

2) Set pace and synthesis options

--speed 1.0 = normal
--speed 0.75 = ~25% slower
--speed 1.25 = ~25% faster
Optional tuning: --volume, --noise-scale, --noise-w-scale, --normalize-audio

3) Generate and deliver

Output to a deterministic path under audio/.
If the user asks to receive the file, send it with the message tool.

Commands

From a text file, 25% slower

.venv-piper/bin/python skills/piper-tts/scripts/generate_piper_audio.py \
  --voice es_MX-claude-high \
  --text-file resumen.txt \
  --speed 0.75 \
  --output audio/resumen_lento.wav

Use a direct voice path

.venv-piper/bin/python skills/piper-tts/scripts/generate_piper_audio.py \
  --voice-path voices/piper/es_MX-claude-high.onnx \
  --text "Texto de prueba" \
  --output audio/prueba_directa.wav

Resources

scripts/generate_piper_audio.py: main generator script
references/quick-reference.md: install, usage, speed and CUDA notes