Model Configuration & Hyperparameters
Relevant source files
The following files were used as context for generating this wiki page:
Model Configuration and Hyperparameters in Piper define the architectural blueprint and operational constraints for the VITS-based neural text-to-speech engine. These configurations govern everything from audio signal processing parameters (like sample rates and hop lengths) to deep learning architectural details (such as upsampling rates and residual block dilations).
The system utilizes a hierarchical configuration structure, separating concerns between Mel-spectrogram generation, model architecture (Generator), training dynamics, and real-time inference settings. This ensures that models can be specialized for different use cases, such as high-quality studio synthesis or low-latency edge deployment.
Sources: src/piper/train/vits/config.py:1-125, src/piper/config.py:1-60
Core Architectural Configuration
The ModelConfig and its sub-structures define the static architecture of the VITS model. Piper supports different quality tiers by varying the complexity of the upsampling and residual blocks.
Audio and Upsampling Layers
The ModelAudioConfig defines the decoder's upsampling path, which converts latent representations back into raw audio waveforms. Piper provides predefined templates for "high_quality" and "low_quality" configurations.
This diagram illustrates the architectural differences between high-quality and low-quality model templates.
| Parameter | High Quality Default | Low Quality Default | Description |
|---|---|---|---|
resblock | "1" | "2" | Type of residual block used in the decoder |
upsample_rates | (8, 8, 2, 2) | (8, 8, 4) | Factors for each upsampling layer |
upsample_initial_channel | 512 | 256 | Number of channels entering the first upsample layer |
upsample_kernel_sizes | (16, 16, 4, 4) | (16, 16, 8) | Kernel sizes for transposed convolutions |
Sources: src/piper/train/vits/config.py:27-65
Global Model Hyperparameters
The ModelConfig class aggregates audio, mel, and transformer-specific hyperparameters that determine the capacity of the encoder and flow components.
- Encoder/Flow Channels: Defaults to 192
inter_channelsandhidden_channels. - Transformer Heads: 2 heads for the attention mechanism.
- Layers: 6 layers for the primary encoder and 3 layers for the posterior encoder (
n_layers_q). - Stochastic Duration Predictor (SDP): Enabled by default to provide natural rhythm variations.
Sources: src/piper/train/vits/config.py:68-100
Inference & Synthesis Hyperparameters
Synthesis parameters control the behavior of the model during the generation of speech. These are defined in SynthesisConfig and can be overridden per request.
Scaling Factors
Three primary scales influence the output characteristics:
- Length Scale: Controls the speaking rate. Values < 1.0 are faster; > 1.0 are slower.
- Noise Scale: Affects the variance of the generator, influencing "breathiness" or vocal texture.
- Noise W Scale: Specifically targets phoneme duration variance for more or less robotic timing.
Diagram representing the default inference scaling factors used during synthesis.
Sources: src/piper/config.py:100-118, libpiper/include/piper_impl.hpp:26-30
Multi-Speaker Configuration
For models supporting multiple voices, Piper maps speaker names to numeric IDs.
- Global Speaker Embedding: If
n_speakers> 1, the model usesgin_channels(default 512) for speaker conditioning. - Speaker ID Map: A dictionary mapping string names to integer indices stored in the model configuration.
Sources: src/piper/train/vits/config.py:102-108, src/piper/config.py:53-54
Audio Processing Configuration
Audio parameters are critical for matching the model's expectations during training and synthesis. These are encapsulated in MelAudioConfig.
| Configuration Field | Default Value | Description |
|---|---|---|
sample_rate | 22050 | Sampling frequency of the audio in Hz |
filter_length | 1024 | Window size for Fast Fourier Transform (FFT) |
hop_length | 256 | Number of samples between successive STFT columns |
win_length | 1024 | Window size for STFT |
mel_channels | 80 | Number of Mel bands |
Sources: src/piper/train/vits/config.py:10-21, src/piper/config.py:11-12
Training & Optimization Hyperparameters
The TrainingConfig class defines the constants used by the optimizer (AdamW) and the learning rate scheduler to ensure stable model convergence.
- Learning Rate: Defaults to
2e-4. - Betas: (0.8, 0.99) for the Adam optimizer.
- LR Decay: A factor of
0.999875applied per epoch/step. - Loss Weights:
c_mel: 45 (Weight for Mel-spectrogram reconstruction loss).c_kl: 1.0 (Weight for Kullback–Leibler divergence).
Sources: src/piper/train/vits/config.py:111-125
Data and Phonemization Configuration
Piper identifies characters and phonemes through a mapping system defined in the configuration.
- Phoneme Type: Supports
espeak,text(direct IPA), orpinyin(for Chinese). - Phoneme ID Map: Maps individual phoneme strings to a sequence of integers used as model input.
- Special Tokens: Uses
PAD(0),BOS(1), andEOS(2) for sequence delimitation.
Sources: src/piper/config.py:15-18, libpiper/include/piper_impl.hpp:16-18, src/piper/const.py
Summary of Configuration Flow
The following sequence shows how configuration is loaded and applied from a persistent JSON file to a running PiperVoice instance.
Sequence diagram illustrating the initialization of model parameters from the configuration file.
Sources: src/piper/config.py:63-88, src/piper/voice.py:115-152
Piper's model configuration system provides a robust framework for defining complex TTS architectures while maintaining flexibility through a clear separation of training, architecture, and runtime hyperparameters. This structure allows the engine to remain performant across various hardware targets by simply adjusting specific values in the JSON model metadata.