# ohf-voice/piper1-gpl architecture

> Architecture diagram of the GitHub repository ohf-voice/piper1-gpl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ohf-voice/piper1-gpl
- Repository: https://github.com/ohf-voice/piper1-gpl

## Overview

Piper is a local neural text-to-speech engine with Python and C/C++ interfaces, a command-line tool, an optional HTTP server, and voice-training support. Its main workflow accepts text, converts it to phonemes and IDs, runs a voice model, and returns or writes audio. The graph also preserves multilingual phonemization, voice acquisition, and training/export capabilities documented by the README. Some subsystems are represented from the file tree and README because their implementation was not sampled; their internal wiring is intentionally limited.

Main entry points: [`src/piper/voice.py`](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/voice.py) (Python voice runtime), [`libpiper/src/main/main.cpp`](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/main/main.cpp) (C++ CLI), [`libpiper/src/piper.cpp`](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/piper.cpp) (Native synthesis), [`src/piper/phonemize_espeak.py`](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phonemize_espeak.py) (Language phonemizers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_py_cli["Python CLI<br/>[__main__.py]"]
  node_http["HTTP server<br/>[http_server.py]"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_cpp_cli["C++ CLI<br/>[main.cpp]"]
  node_c_api["C/C++ API<br/>[piper.h]"]
  node_voice_download["Voice download<br/>[download_voices.py]"]
end

subgraph group_text["Text processing"]
  node_phonemizers["Language phonemizers"]
  node_chinese["Chinese G2P"]
  node_g2pw["G2PW inference<br/>[g2pw_onnx.py]"]
  node_hebrew["Hebrew IPA<br/>[hebrew_ipa.py]"]
  node_phoneme_ids["Phoneme IDs<br/>[phoneme_ids.py]"]
end

subgraph group_runtime["Speech runtime"]
  node_voice["Python voice runtime<br/>[voice.py]"]
  node_config["Voice configuration<br/>[config.py]"]
  node_onnx[("ONNX voice model")]
  node_audio["Audio playback<br/>[audio_playback.py]"]
  node_libpiper["Native synthesis<br/>[piper.cpp]"]
  node_wav_output["WAV output<br/>[wavfile.cpp]"]
end

subgraph group_training["Voice training"]
  node_train_data["Training dataset<br/>[dataset.py]"]
  node_vits["VITS training model<br/>[models.py]"]
  node_train_infer["Checkpoint inference<br/>[infer_torch.py]"]
  node_export["ONNX export<br/>[export_onnx.py]"]
end

node_user(("Text consumer"))
node_audio_result(("Speech audio"))

node_user -->|"provides text"| node_py_cli
node_user -.->|"sends request"| node_http
node_user -.->|"provides text"| node_python_api
node_user -.->|"provides text"| node_cpp_cli
node_py_cli -->|"synthesizes with"| node_voice
node_http -.->|"serves via"| node_voice
node_python_api -->|"uses"| node_voice
node_cpp_cli -->|"creates and invokes"| node_libpiper
node_libpiper -->|"phonemizes with"| node_phonemizers
node_libpiper -->|"runs model"| node_onnx
node_cpp_cli -->|"writes audio"| node_wav_output
node_voice -->|"loads"| node_config
node_voice -->|"phonemizes with"| node_phonemizers
node_voice -->|"encodes as"| node_phoneme_ids
node_voice -->|"runs inference"| node_onnx
node_voice -->|"returns audio"| node_audio_result
node_voice -.->|"plays through"| node_audio
node_chinese -->|"uses inference"| node_g2pw
node_phonemizers -.->|"supports Hebrew"| node_hebrew
node_voice_download -->|"provides voices"| node_user
node_train_data -->|"supplies batches"| node_vits
node_vits -->|"produces checkpoint"| node_train_infer
node_train_infer -->|"exports model"| node_export
node_export -->|"creates voice model"| node_onnx

click node_py_cli "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/__main__.py"
click node_http "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/http_server.py"
click node_python_api "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/__init__.py"
click node_cpp_cli "https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/main/main.cpp"
click node_c_api "https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/include/piper.h"
click node_voice_download "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/download_voices.py"
click node_phonemizers "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phonemize_espeak.py"
click node_chinese "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phonemize_chinese.py"
click node_g2pw "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/g2pw_onnx.py"
click node_hebrew "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/hebrew/hebrew_ipa.py"
click node_phoneme_ids "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phoneme_ids.py"
click node_voice "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/voice.py"
click node_config "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/config.py"
click node_audio "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/audio_playback.py"
click node_libpiper "https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/piper.cpp"
click node_wav_output "https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/main/utils/wavfile.cpp"
click node_train_data "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/vits/dataset.py"
click node_vits "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/vits/models.py"
click node_train_infer "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/infer_torch.py"
click node_export "https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/export_onnx.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_py_cli,node_http,node_python_api,node_cpp_cli,node_c_api,node_voice_download toneBlue
class node_phonemizers,node_chinese,node_g2pw,node_hebrew,node_phoneme_ids toneAmber
class node_voice,node_config,node_onnx,node_audio,node_libpiper,node_wav_output toneMint
class node_train_data,node_vits,node_train_infer,node_export toneRose
class node_user,node_audio_result toneIndigo
```

## Components

### User interfaces

- [Python CLI](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/__main__.py): `src/piper/__main__.py`
- [HTTP server](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/http_server.py): `src/piper/http_server.py`
- [Python API](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/__init__.py): `src/piper/__init__.py`
- [C++ CLI](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/main/main.cpp): `libpiper/src/main/main.cpp`
- [C/C++ API](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/include/piper.h): `libpiper/include/piper.h`
- [Voice download](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/download_voices.py): `src/piper/download_voices.py`

### Text processing

- [Language phonemizers](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phonemize_espeak.py): `src/piper/phonemize_espeak.py`
- [Chinese G2P](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phonemize_chinese.py): `src/piper/phonemize_chinese.py`
- [G2PW inference](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/g2pw_onnx.py): `src/piper/g2pw_onnx.py`
- [Hebrew IPA](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/hebrew/hebrew_ipa.py): `src/piper/hebrew/hebrew_ipa.py`
- [Phoneme IDs](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/phoneme_ids.py): `src/piper/phoneme_ids.py`

### Speech runtime

- [Python voice runtime](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/voice.py): `src/piper/voice.py`
- [Voice configuration](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/config.py): `src/piper/config.py`
- **ONNX voice model**
- [Audio playback](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/audio_playback.py): `src/piper/audio_playback.py`
- [Native synthesis](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/piper.cpp): `libpiper/src/piper.cpp`
- [WAV output](https://github.com/ohf-voice/piper1-gpl/blob/main/libpiper/src/main/utils/wavfile.cpp): `libpiper/src/main/utils/wavfile.cpp`

### Voice training

- [Training dataset](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/vits/dataset.py): `src/piper/train/vits/dataset.py`
- [VITS training model](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/vits/models.py): `src/piper/train/vits/models.py`
- [Checkpoint inference](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/infer_torch.py): `src/piper/train/infer_torch.py`
- [ONNX export](https://github.com/ohf-voice/piper1-gpl/blob/main/src/piper/train/export_onnx.py): `src/piper/train/export_onnx.py`

### Other components

- **Text consumer**
- **Speech audio**

## Connections

- Text consumer → Python CLI: provides text
- Text consumer → HTTP server: sends request
- Text consumer → Python API: provides text
- Text consumer → C++ CLI: provides text
- Python CLI → Python voice runtime: synthesizes with
- HTTP server → Python voice runtime: serves via
- Python API → Python voice runtime: uses
- C++ CLI → Native synthesis: creates and invokes
- Native synthesis → Language phonemizers: phonemizes with
- Native synthesis → ONNX voice model: runs model
- C++ CLI → WAV output: writes audio
- Python voice runtime → Voice configuration: loads
- Python voice runtime → Language phonemizers: phonemizes with
- Python voice runtime → Phoneme IDs: encodes as
- Python voice runtime → ONNX voice model: runs inference
- Python voice runtime → Speech audio: returns audio
- Python voice runtime → Audio playback: plays through
- Chinese G2P → G2PW inference: uses inference
- Language phonemizers → Hebrew IPA: supports Hebrew
- Voice download → Text consumer: provides voices
- Training dataset → VITS training model: supplies batches
- VITS training model → Checkpoint inference: produces checkpoint
- Checkpoint inference → ONNX export: exports model
- ONNX export → ONNX voice model: creates voice model