piper-tts-training
Train custom TTS voices for Piper (ONNX format) using fine-tuning or from-scratch approaches. Use when creating new synthetic voices, fine-tuning existing Piper checkpoints, preparing audio datasets for TTS training, or deploying voice models to devices like Raspberry Pi or Home Assistant. Covers dataset preparation, Whisper-based validation, training configuration, and ONNX export.
- Installs
- 64
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/sammcj/agentic-coding --skill piper-tts-training- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads piper-tts-training automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
Piper TTS Voice Training
Train custom text-to-speech voices compatible with Piper's lightweight ONNX runtime.
Overview
Piper produces fast, offline TTS suitable for embedded devices. Training involves:
- Corpus preparation (text covering phonetic range)
- Audio generation or recording
- Quality validation via Whisper transcription
- Fine-tuning from existing checkpoint (recommended) or training from scratch
- ONNX export for deployment
Fine-tuning vs from-scratch:
- Fine-tuning: ~1,300 phrases + 1,000 epochs (days on modest GPU)
- From scratch: ~13,000+ phrases + 2,000+ epochs (weeks/months)
Workflow
1. Corpus Preparation
Gather 1,300-1,500+ phrases covering broad phonetic range:
- Use piper-recording-studio corpus as base
- Add domain-specific phrases for your use case
- Include varied sentence structures and lengths
Critical for non-US English: Ensure corpus uses correct regional spelling. See Localisation.
2. Audio Generation
Generate or record training audio at 22050Hz mono WAV.
If using voice cloning (e.g., Chatterbox TTS):
- Generate at source sample rate (often 24kHz)
- Convert to 22050Hz:
sox -v 0.95 input.wav -r 22050 -t wav output.wav - The
-v 0.95prevents clipping during resampling
Recording requirements:
- Consistent microphone position and room acoustics
- Minimal background noise
- Natural speaking pace (not reading voice)
3. Quality Validation with Whisper
Automate quality checks rather than manual listening:
import whisper
from piper_phonemize import phonemize_text
model = whisper.load_model("base")
def validate_sample(audio_path, expected_text):
result = model.transcribe(audio_path)
transcribed = result["text"].strip()
# Compare phonemically to handle spelling/punctuation differences
expected_phonemes = phonemize_text(expected_text, "en-gb")
transcribed_phonemes = phonemize_text(transcribed, "en-gb")
return expected_phonemes == transcribed_phonemes
Retry failed samples up to 3 times. Target 95%+ dataset coverage.
4. Dataset Format (LJSpeech)
Structure your dataset:
dataset/
├── metadata.csv
└── wavs/
├── sample_0001.wav
├── sample_0002.wav
└── ...
metadata.csv format: {id}|{text} (pipe-separated, no headers)
sample_0001|The quick brown fox jumps over the lazy dog.
sample_0002|Pack my box with five dozen liquor jugs.
5. Preprocessing
Convert to PyTorch tensors:
python3 -m piper_train.preprocess \
--language en-gb \
--input-dir dataset/ \
--output-dir piper_training_dir/ \
--dataset-format ljspeech
Use en-gb for Australian/NZ/UK voices (espeak-ng phoneme set).
6. Training
Fine-tuning (recommended):
python3 -m piper_train \
--dataset-dir piper_training_dir/ \
--accelerator gpu \
--devices 1 \
--batch-size 12 \
--max_epochs 3000 \
--resume_from_checkpoint ljspeech-2000.ckpt \
--checkpoint-epochs 100 \
--quality high \
--precision 32
Key parameters:
--batch-size: Reduce if VRAM limited (12 works on 8GB)--resume_from_checkpoint: Start from LJSpeech high-quality checkpoint--precision 32: More stable than mixed precision--validation-split 0.0 --num-test-examples 0: Skip validation for small datasets
Monitor with TensorBoard: watch loss_disc_all for convergence.
7. ONNX Export
python3 -m piper_train.export_onnx checkpoint.ckpt output.onnx.unoptimized
onnxsim output.onnx.unoptimized output.onnx
Create metadata file output.onnx.json from training config.json.
Localisation for Australian, New Zealand and UK English
Piper uses espeak-ng for phonemisation. American pronunciations in training data cause accent drift.
Corpus preparation:
- Run
scripts/convert_spelling.pyon corpus text before training - Use
en-gboren-auespeak-ng voice for phonemisation - Review generated phonemes for Americanisms
Common spelling conversions:
| American | Australian/UK |
|---|---|
| -ize | -ise |
| -or | -our |
| -er | -re |
| -og | -ogue |
| -ense | -ence |
Phoneme considerations:
- /r/ linking and intrusion patterns differ
- Vowel sounds in words like "dance", "bath", "castle"
- Final -ile pronunciation (hostile, missile)
For complete word lists and phonetic details, see references/localisation.md.
Validation: Use Whisper with language="en" and verify transcriptions match expected regional forms.
Dependencies
Pin versions to avoid API breakage:
pytorch-lightning==1.9.3
torch<2.6.0
piper-phonemize
onnxruntime-gpu
onnxsim
Docker containerisation recommended for reproducibility.
Hardware Requirements
Minimum (fine-tuning):
- 8GB VRAM GPU (Pascal or newer)
- 8GB system RAM
- ~5 days for 1,000 epochs on Tesla P4
From scratch: Multiply time by ~200x.
Troubleshooting
| Issue | Solution |
|---|---|
| CUDA OOM | Reduce batch-size (try 8 or 4) |
| Checkpoint won't load | Check pytorch-lightning version matches checkpoint |
| Garbled output | Insufficient training epochs or dataset too small |
| Wrong accent | Check espeak-ng language code and corpus spelling |
FAQ
What does the piper-tts-training skill do?
Train custom TTS voices for Piper (ONNX format) using fine-tuning or from-scratch approaches. Use when creating new synthetic voices, fine-tuning existing Piper checkpoints, preparing audio datasets for TTS training, or deploying voice models to devices like Raspberry Pi or Home Assistant. Covers dataset preparation, Whisper-based validation, training configuration, and ONNX export.
How do I install piper-tts-training?
Run npx skills add https://github.com/sammcj/agentic-coding --skill piper-tts-training in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/piper-tts-training/ (personal) or .claude/skills/piper-tts-training/ (project).
Which AI agents can use piper-tts-training?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is piper-tts-training safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains piper-tts-training?
It is published by sammcj in sammcj/agentic-coding. It has 64 recorded installs.
More from sammcj/agentic-coding
critical-thinking-logical-reasoning
sammcj/agentic-coding
Critically analyse the reasoning in written content (articles, blogs, transcripts, reports), not code. Use only when explicitly asked to critically analyse or critique an argument.
writing-documentation-with-diataxis
sammcj/agentic-coding
Applies the Diataxis framework to create or improve technical documentation. Use when being asked to write high quality tutorials, how-to guides, reference docs, or explanations, when reviewing documentation quality, or when deciding what type of documentation to create. Helps identify documentation types using the action/cognition and acquisition/application dimensions.
creating-development-plans
sammcj/agentic-coding
Creates structured development plans with phased task breakdowns, requirements, and QA checklists. Use when the user explicitly asks to create a dev plan, development plan, or document development requirements.
ghostty-config
sammcj/agentic-coding
Use when creating, editing or debugging Ghostty terminal configuration - config.ghostty files, config option names and their valid values, keybinds and key sequences, themes, fonts, shell integration, or ghostty + CLI actions. Covers macOS and Linux/GTK differences.
code-simplification
sammcj/agentic-coding
Use this skill when you need to review and refactor code to make it simpler, more maintainable, and easier to understand. Helps with identifying overly complex solutions, unnecessary abstractions.
prompt-enhancer
sammcj/agentic-coding
Transform poor or overly simple prompts with expert-level framing. Use when the user explicitly asks to improve, refine, or rewrite a prompt, or wants help framing a request for another AI system. Do NOT use for authoring, reviewing, or migrating system prompts or skills targeting a specific Claude model.
Popular media & creative skills
hyperframes
heygen-com/hyperframes
Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.
media-use
heygen-com/hyperframes
Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.
hyperframes-registry
heygen-com/hyperframes
About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
hyperframes-creative
heygen-com/hyperframes
Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.
ai-video-generation
101-skills/superpowers
Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse
ai-image-generation
101-skills/superpowers
Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image