# rhasspy/piper architecture

> Architecture diagram of the GitHub repository rhasspy/piper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rhasspy/piper
- Repository: https://github.com/rhasspy/piper

## Overview

Piper provides neural text-to-speech inference and tooling to prepare data, train voice models, and export them for runtime use. A user can submit text through the Python CLI/server or C++ executable, select or download a voice, and synthesize WAV or streamed audio. Training covers dataset preprocessing, VITS modeling, inference, and export; voice conversion and speaker/audio utilities are additional capabilities. Source excerpts and the index confirm some connections; dashed, uncited links mark important training or export relationships not verified in the sampled source.

Main entry points: [`src/python_run/piper/voice.py`](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/voice.py) (Python Voice), [`src/cpp/piper.cpp`](https://github.com/rhasspy/piper/blob/master/src/cpp/piper.cpp) (C++ Synthesis), [`src/python/piper_train/vits/lightning.py`](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/lightning.py) (VITS Training), [`src/python_run/piper/__main__.py`](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/__main__.py) (Python CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_py_runtime["Python Runtime"]
  node_python_cli["Python CLI<br/>[__main__.py]"]
  node_http_server["HTTP Server<br/>[http_server.py]"]
  node_voice_download["Voice Download<br/>[download.py]"]
  node_voice_model["Python Voice<br/>[voice.py]"]
end

subgraph group_cpp_runtime["C++ Runtime"]
  node_cpp_cli["C++ CLI<br/>[main.cpp]"]
  node_cpp_engine["C++ Synthesis<br/>[piper.cpp]"]
end

subgraph group_training["Training Workflow"]
  node_preprocess["Dataset Preprocess<br/>[preprocess.py]"]
  node_audio_norm["Audio Normalize<br/>[__init__.py]"]
  node_train_entry["Training Commands<br/>[__main__.py]"]
  node_vits_train["VITS Training<br/>[lightning.py]"]
  node_train_infer["Training Inference<br/>[infer.py]"]
  node_model_export["Model Export<br/>[export_onnx.py]"]
  node_voice_conversion["Voice Conversion"]
end

subgraph group_vits["VITS Engine"]
  node_vits_models["VITS Models<br/>[models.py]"]
  node_vits_layers["VITS Layers<br/>[modules.py]"]
  node_vits_commons["VITS Operations<br/>[commons.py]"]
  node_vits_transforms["VITS Transforms<br/>[transforms.py]"]
  node_mel_processing["Mel Processing<br/>[mel_processing.py]"]
end

node_user(("Text User"))
node_onnx_runtime["ONNX Runtime"]
node_voice_store[("Voice Files")]
node_phonemizer["Phonemization"]
node_audio_output["WAV Audio"]
node_dataset[("Audio Dataset")]

node_user -->|"submits text"| node_python_cli
node_user -.->|"sends request"| node_http_server
node_python_cli -->|"resolves voice"| node_voice_download
node_http_server -->|"resolves voice"| node_voice_download
node_python_cli -->|"loads voice"| node_voice_model
node_http_server -->|"uses voice"| node_voice_model
node_voice_download -->|"downloads files"| node_voice_store
node_voice_model -->|"runs inference"| node_onnx_runtime
node_voice_model -->|"phonemizes text"| node_phonemizer
node_voice_model -->|"writes WAV"| node_audio_output
node_user -->|"provides text"| node_cpp_cli
node_cpp_cli -->|"synthesizes text"| node_cpp_engine
node_cpp_engine -->|"phonemizes text"| node_phonemizer
node_cpp_engine -->|"runs inference"| node_onnx_runtime
node_cpp_engine -->|"writes audio"| node_audio_output
node_dataset -.->|"provides recordings"| node_preprocess
node_preprocess -->|"normalizes audio"| node_audio_norm
node_preprocess -.->|"prepares training data"| node_train_entry
node_train_entry -.->|"starts training"| node_vits_train
node_vits_train -.->|"trains model"| node_vits_models
node_vits_models -->|"uses layers"| node_vits_layers
node_vits_layers -->|"uses operations"| node_vits_commons
node_vits_layers -->|"uses transforms"| node_vits_transforms
node_audio_norm -->|"computes spectrogram"| node_mel_processing
node_vits_train -.->|"supports inference"| node_train_infer
node_vits_train -.->|"exports trained model"| node_model_export
node_model_export -.->|"produces voice model"| node_voice_store
node_train_infer -.->|"supports conversion"| node_voice_conversion

click node_python_cli "https://github.com/rhasspy/piper/blob/master/src/python_run/piper/__main__.py"
click node_http_server "https://github.com/rhasspy/piper/blob/master/src/python_run/piper/http_server.py"
click node_voice_download "https://github.com/rhasspy/piper/blob/master/src/python_run/piper/download.py"
click node_voice_model "https://github.com/rhasspy/piper/blob/master/src/python_run/piper/voice.py"
click node_cpp_cli "https://github.com/rhasspy/piper/blob/master/src/cpp/main.cpp"
click node_cpp_engine "https://github.com/rhasspy/piper/blob/master/src/cpp/piper.cpp"
click node_preprocess "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/preprocess.py"
click node_audio_norm "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/norm_audio/__init__.py"
click node_train_entry "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/__main__.py"
click node_vits_train "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/lightning.py"
click node_train_infer "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/infer.py"
click node_model_export "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/export_onnx.py"
click node_voice_conversion "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/voice_conversion.py"
click node_vits_models "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/models.py"
click node_vits_layers "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/modules.py"
click node_vits_commons "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/commons.py"
click node_vits_transforms "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/transforms.py"
click node_mel_processing "https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/mel_processing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_python_cli,node_http_server,node_voice_download,node_voice_model,node_user toneBlue
class node_cpp_cli,node_cpp_engine,node_voice_store,node_dataset toneAmber
class node_preprocess,node_audio_norm,node_train_entry,node_vits_train,node_train_infer,node_model_export,node_voice_conversion toneMint
class node_vits_models,node_vits_layers,node_vits_commons,node_vits_transforms,node_mel_processing toneRose
class node_onnx_runtime,node_phonemizer,node_audio_output toneIndigo
```

## Components

### Python Runtime

- [Python CLI](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/__main__.py): `src/python_run/piper/__main__.py`
- [HTTP Server](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/http_server.py): `src/python_run/piper/http_server.py`
- [Voice Download](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/download.py): `src/python_run/piper/download.py`
- [Python Voice](https://github.com/rhasspy/piper/blob/master/src/python_run/piper/voice.py): `src/python_run/piper/voice.py`

### C++ Runtime

- [C++ CLI](https://github.com/rhasspy/piper/blob/master/src/cpp/main.cpp): `src/cpp/main.cpp`
- [C++ Synthesis](https://github.com/rhasspy/piper/blob/master/src/cpp/piper.cpp): `src/cpp/piper.cpp`

### Training Workflow

- [Dataset Preprocess](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/preprocess.py): `src/python/piper_train/preprocess.py`
- [Audio Normalize](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/norm_audio/__init__.py): `src/python/piper_train/norm_audio/__init__.py`
- [Training Commands](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/__main__.py): `src/python/piper_train/__main__.py`
- [VITS Training](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/lightning.py): `src/python/piper_train/vits/lightning.py`
- [Training Inference](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/infer.py): `src/python/piper_train/infer.py`
- [Model Export](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/export_onnx.py): `src/python/piper_train/export_onnx.py`
- [Voice Conversion](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/voice_conversion.py): `src/python/piper_train/voice_conversion.py`

### VITS Engine

- [VITS Models](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/models.py): `src/python/piper_train/vits/models.py`
- [VITS Layers](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/modules.py): `src/python/piper_train/vits/modules.py`
- [VITS Operations](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/commons.py): `src/python/piper_train/vits/commons.py`
- [VITS Transforms](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/transforms.py): `src/python/piper_train/vits/transforms.py`
- [Mel Processing](https://github.com/rhasspy/piper/blob/master/src/python/piper_train/vits/mel_processing.py): `src/python/piper_train/vits/mel_processing.py`

### Other components

- **Text User**
- **ONNX Runtime**
- **Voice Files**
- **Phonemization**
- **WAV Audio**
- **Audio Dataset**

## Connections

- Text User → Python CLI: submits text (evidence: `src/python_run/piper/__main__.py`)
- Text User → HTTP Server: sends request
- Python CLI → Voice Download: resolves voice (evidence: `src/python_run/piper/__main__.py`)
- HTTP Server → Voice Download: resolves voice (evidence: `src/python_run/piper/http_server.py`)
- Python CLI → Python Voice: loads voice
- HTTP Server → Python Voice: uses voice (evidence: `src/python_run/piper/http_server.py`)
- Voice Download → Voice Files: downloads files (evidence: `src/python_run/piper/download.py`)
- Python Voice → ONNX Runtime: runs inference (evidence: `src/python_run/piper/voice.py`)
- Python Voice → Phonemization: phonemizes text (evidence: `src/python_run/piper/voice.py`)
- Python Voice → WAV Audio: writes WAV (evidence: `src/python_run/piper/voice.py`)
- Text User → C++ CLI: provides text (evidence: `src/cpp/main.cpp`)
- C++ CLI → C++ Synthesis: synthesizes text (evidence: `src/cpp/main.cpp`)
- C++ Synthesis → Phonemization: phonemizes text (evidence: `src/cpp/piper.cpp`)
- C++ Synthesis → ONNX Runtime: runs inference (evidence: `src/cpp/piper.cpp`)
- C++ Synthesis → WAV Audio: writes audio
- Audio Dataset → Dataset Preprocess: provides recordings
- Dataset Preprocess → Audio Normalize: normalizes audio (evidence: `src/python/piper_train/preprocess.py`)
- Dataset Preprocess → Training Commands: prepares training data
- Training Commands → VITS Training: starts training
- VITS Training → VITS Models: trains model
- VITS Models → VITS Layers: uses layers
- VITS Layers → VITS Operations: uses operations (evidence: `src/python/piper_train/vits/modules.py`)
- VITS Layers → VITS Transforms: uses transforms (evidence: `src/python/piper_train/vits/modules.py`)
- Audio Normalize → Mel Processing: computes spectrogram (evidence: `src/python/piper_train/norm_audio/__init__.py`)
- VITS Training → Training Inference: supports inference
- VITS Training → Model Export: exports trained model
- Model Export → Voice Files: produces voice model
- Training Inference → Voice Conversion: supports conversion
