# ampixa/sanotts architecture

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

- Interactive diagram: https://gitdiagram.com/ampixa/sanotts
- Repository: https://github.com/ampixa/sanotts

## Overview

sanoTTS is a family of compact neural text-to-speech voices deployed through Python, browser/WASM, Arduino, ESPHome, mobile, and Home Assistant interfaces. The principal workflow is text input, language-appropriate phonemization, voice/model loading, neural inference, and PCM audio output. The Python engine and the documented browser path expose the clearest end-to-end flows; embedded runtimes and integrations are represented as distinct deployment branches. Some platform implementations are unsampled, so their internal links are limited to README statements and explicit source-index references.

Main entry points: [`pypkg/sanotts/engine.py`](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/engine.py) (Synthesizer), [`pypkg/sanotts/__init__.py`](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/__init__.py) (Python API), [`arduino/src/snt_nano.c`](https://github.com/ampixa/sanotts/blob/master/arduino/src/snt_nano.c) (Nano inference), [`web/snt_voice.js`](https://github.com/ampixa/sanotts/blob/master/web/snt_voice.js) (Voice WASM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python Runtime"]
  node_python_api["Python API<br/>[__init__.py]"]
  node_synth["Synthesizer<br/>[engine.py]"]
  node_front["Text frontend<br/>[frontend.py]"]
  node_nano_g2p["Nano G2P<br/>[nano_g2p.py]"]
  node_piper_g2p["Piper G2P<br/>[piper_g2p.py]"]
  node_nano_front["Nano frontend<br/>[nano_frontend.py]"]
  node_voicepack["Voice packs<br/>[voicepack.py]"]
  node_numpy_models["NumPy inference<br/>[models.py]"]
end

subgraph group_browser["Browser Runtime"]
  node_web_g2p["G2P WASM<br/>[snt_g2p.js]"]
  node_zh_g2p["Chinese G2P<br/>[zh_g2p.mjs]"]
  node_zh_tables["Chinese tables<br/>[unicode_tables.mjs]"]
  node_web_tts["Web TTS API<br/>[snt_tts.js]"]
  node_wasm_voice["Voice WASM<br/>[snt_voice.js]"]
end

subgraph group_embedded["Embedded Runtime"]
  node_arduino_api["Arduino API<br/>[SanoTTS.cpp]"]
  node_nano_runtime["Nano inference<br/>[snt_nano.c]"]
  node_nano_api["Nano interface<br/>[snt_nano.h]"]
end

subgraph group_integrations["Platform Integrations"]
  node_esphome["ESPHome component<br/>[sanotts.cpp]"]
  node_lex_g2p["Lexicon G2P<br/>[nano_lex_g2p.c]"]
  node_ha_tts["Home Assistant TTS<br/>[tts.py]"]
  node_mobile_api["Mobile binding<br/>[sanotts.c]"]
end

subgraph group_models["Voice Models"]
end

node_user(("Text user"))
node_voice_host[("Voice host")]
node_browser_user(("Browser user"))
node_pcm["PCM audio"]

node_user -->|"provides text"| node_python_api
node_python_api -->|"calls"| node_synth
node_synth -->|"uses"| node_front
node_synth -->|"dispatches"| node_nano_g2p
node_synth -->|"dispatches"| node_piper_g2p
node_synth -->|"uses"| node_nano_front
node_synth -->|"uses"| node_voicepack
node_synth -->|"uses"| node_numpy_models
node_voicepack -->|"downloads voices"| node_voice_host
node_python_api -->|"returns audio"| node_pcm
node_browser_user -->|"provides text"| node_web_g2p
node_web_g2p -->|"supplies phonemes"| node_wasm_voice
node_browser_user -->|"provides Chinese"| node_zh_g2p
node_zh_g2p -->|"reads"| node_zh_tables
node_web_tts -.->|"invokes"| node_wasm_voice
node_wasm_voice -->|"synthesizes"| node_pcm
node_user -.->|"provides phonemes"| node_arduino_api
node_arduino_api -.->|"invokes"| node_nano_runtime
node_nano_api -->|"defines interface"| node_nano_runtime
node_nano_runtime -->|"emits PCM"| node_pcm
node_esphome -.->|"uses G2P"| node_lex_g2p
node_ha_tts -->|"uses package"| node_python_api
node_mobile_api -.->|"invokes"| node_nano_runtime

click node_python_api "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/__init__.py"
click node_synth "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/engine.py"
click node_front "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/frontend.py"
click node_nano_g2p "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/nano_g2p.py"
click node_piper_g2p "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/piper_g2p.py"
click node_nano_front "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/nano_frontend.py"
click node_voicepack "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/voicepack.py"
click node_numpy_models "https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/models.py"
click node_web_g2p "https://github.com/ampixa/sanotts/blob/master/web/snt_g2p.js"
click node_zh_g2p "https://github.com/ampixa/sanotts/blob/master/web/g2p-lazy/zh/zh_g2p.mjs"
click node_zh_tables "https://github.com/ampixa/sanotts/blob/master/web/g2p-lazy/zh/unicode_tables.mjs"
click node_web_tts "https://github.com/ampixa/sanotts/blob/master/web/snt_tts.js"
click node_wasm_voice "https://github.com/ampixa/sanotts/blob/master/web/snt_voice.js"
click node_arduino_api "https://github.com/ampixa/sanotts/blob/master/arduino/src/SanoTTS.cpp"
click node_nano_runtime "https://github.com/ampixa/sanotts/blob/master/arduino/src/snt_nano.c"
click node_nano_api "https://github.com/ampixa/sanotts/blob/master/arduino/src/snt_nano.h"
click node_esphome "https://github.com/ampixa/sanotts/blob/master/esphome/components/sanotts/sanotts.cpp"
click node_lex_g2p "https://github.com/ampixa/sanotts/blob/master/esphome/components/sanotts/nano_lex_g2p.c"
click node_ha_tts "https://github.com/ampixa/sanotts/blob/master/custom_components/sanotts/tts.py"
click node_mobile_api "https://github.com/ampixa/sanotts/blob/master/mobile/sanotts.c"

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_api,node_synth,node_front,node_nano_g2p,node_piper_g2p,node_nano_front,node_voicepack,node_numpy_models,node_user,node_browser_user toneBlue
class node_web_g2p,node_zh_g2p,node_zh_tables,node_web_tts,node_wasm_voice,node_voice_host toneAmber
class node_arduino_api,node_nano_runtime,node_nano_api toneMint
class node_esphome,node_lex_g2p,node_ha_tts,node_mobile_api toneRose
class node_pcm toneIndigo
```

## Components

### Python Runtime

- [Python API](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/__init__.py): `pypkg/sanotts/__init__.py`
- [Synthesizer](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/engine.py): `pypkg/sanotts/engine.py`
- [Text frontend](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/frontend.py): `pypkg/sanotts/frontend.py`
- [Nano G2P](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/nano_g2p.py): `pypkg/sanotts/nano_g2p.py`
- [Piper G2P](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/piper_g2p.py): `pypkg/sanotts/piper_g2p.py`
- [Nano frontend](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/nano_frontend.py): `pypkg/sanotts/nano_frontend.py`
- [Voice packs](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/voicepack.py): `pypkg/sanotts/voicepack.py`
- [NumPy inference](https://github.com/ampixa/sanotts/blob/master/pypkg/sanotts/models.py): `pypkg/sanotts/models.py`

### Browser Runtime

- [G2P WASM](https://github.com/ampixa/sanotts/blob/master/web/snt_g2p.js): `web/snt_g2p.js`
- [Chinese G2P](https://github.com/ampixa/sanotts/blob/master/web/g2p-lazy/zh/zh_g2p.mjs): `web/g2p-lazy/zh/zh_g2p.mjs`
- [Chinese tables](https://github.com/ampixa/sanotts/blob/master/web/g2p-lazy/zh/unicode_tables.mjs): `web/g2p-lazy/zh/unicode_tables.mjs`
- [Web TTS API](https://github.com/ampixa/sanotts/blob/master/web/snt_tts.js): `web/snt_tts.js`
- [Voice WASM](https://github.com/ampixa/sanotts/blob/master/web/snt_voice.js): `web/snt_voice.js`

### Embedded Runtime

- [Arduino API](https://github.com/ampixa/sanotts/blob/master/arduino/src/SanoTTS.cpp): `arduino/src/SanoTTS.cpp`
- [Nano inference](https://github.com/ampixa/sanotts/blob/master/arduino/src/snt_nano.c): `arduino/src/snt_nano.c`
- [Nano interface](https://github.com/ampixa/sanotts/blob/master/arduino/src/snt_nano.h): `arduino/src/snt_nano.h`

### Platform Integrations

- [ESPHome component](https://github.com/ampixa/sanotts/blob/master/esphome/components/sanotts/sanotts.cpp): `esphome/components/sanotts/sanotts.cpp`
- [Lexicon G2P](https://github.com/ampixa/sanotts/blob/master/esphome/components/sanotts/nano_lex_g2p.c): `esphome/components/sanotts/nano_lex_g2p.c`
- [Home Assistant TTS](https://github.com/ampixa/sanotts/blob/master/custom_components/sanotts/tts.py): `custom_components/sanotts/tts.py`
- [Mobile binding](https://github.com/ampixa/sanotts/blob/master/mobile/sanotts.c): `mobile/sanotts.c`

### Other components

- **Text user**
- **Voice host**
- **Browser user**
- **PCM audio**

## Connections

- Text user → Python API: provides text (evidence: `README.md`)
- Python API → Synthesizer: calls (evidence: `pypkg/sanotts/__init__.py`)
- Synthesizer → Text frontend: uses (evidence: `pypkg/sanotts/engine.py`)
- Synthesizer → Nano G2P: dispatches (evidence: `pypkg/sanotts/engine.py`)
- Synthesizer → Piper G2P: dispatches (evidence: `pypkg/sanotts/engine.py`)
- Synthesizer → Nano frontend: uses (evidence: `pypkg/sanotts/engine.py`)
- Synthesizer → Voice packs: uses (evidence: `pypkg/sanotts/engine.py`)
- Synthesizer → NumPy inference: uses (evidence: `pypkg/sanotts/engine.py`)
- Voice packs → Voice host: downloads voices (evidence: `README.md`)
- Python API → PCM audio: returns audio (evidence: `README.md`)
- Browser user → G2P WASM: provides text (evidence: `README.md`)
- G2P WASM → Voice WASM: supplies phonemes (evidence: `README.md`)
- Browser user → Chinese G2P: provides Chinese (evidence: `web/g2p-lazy/zh/zh_g2p.mjs`)
- Chinese G2P → Chinese tables: reads (evidence: `web/g2p-lazy/zh/zh_g2p.mjs`)
- Web TTS API → Voice WASM: invokes
- Voice WASM → PCM audio: synthesizes (evidence: `README.md`)
- Text user → Arduino API: provides phonemes
- Arduino API → Nano inference: invokes
- Nano interface → Nano inference: defines interface (evidence: `arduino/src/snt_nano.h`)
- Nano inference → PCM audio: emits PCM
- ESPHome component → Lexicon G2P: uses G2P
- Home Assistant TTS → Python API: uses package (evidence: `custom_components/sanotts/tts.py`)
- Mobile binding → Nano inference: invokes
