# neuphonic/neutts architecture

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

- Interactive diagram: https://gitdiagram.com/neuphonic/neutts
- Repository: https://github.com/neuphonic/neutts

## Overview

NeuTTS is an on-device text-to-speech library built around language-model backbones and neural audio codecs. The main workflow accepts text and a speaker reference, prepares model input, generates speech tokens, decodes them to audio, and returns a waveform; GGUF models also support streaming. The graph preserves the Air and emotional 2E variants, multilingual phonemization, cloning, and watermarking. Some internal inference details and codec wiring are only partially excerpted, so edges are limited to documented or visible relationships.

Main entry points: [`neutts/neutts.py`](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py) (NeuTTS API), [`neutts/neutts_2e.py`](https://github.com/neuphonic/neutts/blob/main/neutts/neutts_2e.py) (NeuTTS 2E), [`neuttsair/neutts.py`](https://github.com/neuphonic/neutts/blob/main/neuttsair/neutts.py) (NeuTTS Air), [`neutts/phonemizers.py`](https://github.com/neuphonic/neutts/blob/main/neutts/phonemizers.py) (Phonemization)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_apis["TTS interfaces"]
  node_api["NeuTTS API<br/>[neutts.py]"]
  node_air["NeuTTS Air<br/>[neutts.py]"]
  node_twoe["NeuTTS 2E<br/>[neutts_2e.py]"]
end

subgraph group_speech["Speech generation"]
  node_backbone["Speech backbone<br/>[neutts.py]"]
  node_codec["Audio codec<br/>[neutts.py]"]
  node_watermark["Audio watermark<br/>[neutts.py]"]
  node_stream["Streaming output<br/>[neutts.py]"]
end

subgraph group_language["Language and voices"]
  node_voices[("Speaker references<br/>[neutts_2e.py]")]
  node_phonemizer["Phonemization<br/>[phonemizers.py]"]
end

node_user(("Application user"))
node_text["Text and reference"]
node_audio["Generated waveform"]

node_user -->|"uses"| node_api
node_text -->|"provides input"| node_api
node_user -->|"uses"| node_air
node_user -->|"uses"| node_twoe
node_air -->|"inherits"| node_api
node_twoe -->|"delegates inference"| node_api
node_twoe -->|"loads references"| node_voices
node_api -->|"uses"| node_phonemizer
node_api -->|"generates tokens"| node_backbone
node_api -->|"decodes tokens"| node_codec
node_api -->|"watermarks audio"| node_watermark
node_api -->|"yields chunks"| node_stream
node_api -->|"returns waveform"| node_audio
node_stream -->|"yields audio"| node_audio

click node_api "https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py"
click node_air "https://github.com/neuphonic/neutts/blob/main/neuttsair/neutts.py"
click node_twoe "https://github.com/neuphonic/neutts/blob/main/neutts/neutts_2e.py"
click node_voices "https://github.com/neuphonic/neutts/blob/main/neutts/neutts_2e.py"
click node_phonemizer "https://github.com/neuphonic/neutts/blob/main/neutts/phonemizers.py"
click node_backbone "https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py"
click node_codec "https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py"
click node_watermark "https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py"
click node_stream "https://github.com/neuphonic/neutts/blob/main/neutts/neutts.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_api,node_air,node_twoe,node_user toneBlue
class node_backbone,node_codec,node_watermark,node_stream toneAmber
class node_voices,node_phonemizer toneMint
class node_text,node_audio toneIndigo
```

## Components

### TTS interfaces

- [NeuTTS API](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py): `neutts/neutts.py`
- [NeuTTS Air](https://github.com/neuphonic/neutts/blob/main/neuttsair/neutts.py): `neuttsair/neutts.py`
- [NeuTTS 2E](https://github.com/neuphonic/neutts/blob/main/neutts/neutts_2e.py): `neutts/neutts_2e.py`

### Speech generation

- [Speech backbone](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py): `neutts/neutts.py`
- [Audio codec](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py): `neutts/neutts.py`
- [Audio watermark](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py): `neutts/neutts.py`
- [Streaming output](https://github.com/neuphonic/neutts/blob/main/neutts/neutts.py): `neutts/neutts.py`

### Language and voices

- [Speaker references](https://github.com/neuphonic/neutts/blob/main/neutts/neutts_2e.py): `neutts/neutts_2e.py`
- [Phonemization](https://github.com/neuphonic/neutts/blob/main/neutts/phonemizers.py): `neutts/phonemizers.py`

### Other components

- **Application user**
- **Text and reference**
- **Generated waveform**

## Connections

- Application user → NeuTTS API: uses (evidence: `README.md`)
- Text and reference → NeuTTS API: provides input (evidence: `README.md`)
- Application user → NeuTTS Air: uses (evidence: `README.md`)
- Application user → NeuTTS 2E: uses (evidence: `README.md`)
- NeuTTS Air → NeuTTS API: inherits (evidence: `neuttsair/neutts.py`)
- NeuTTS 2E → NeuTTS API: delegates inference (evidence: `neutts/neutts_2e.py`)
- NeuTTS 2E → Speaker references: loads references (evidence: `neutts/neutts_2e.py`)
- NeuTTS API → Phonemization: uses (evidence: `neutts/neutts.py`)
- NeuTTS API → Speech backbone: generates tokens (evidence: `neutts/neutts.py`)
- NeuTTS API → Audio codec: decodes tokens (evidence: `neutts/neutts.py`)
- NeuTTS API → Audio watermark: watermarks audio (evidence: `neutts/neutts.py`)
- NeuTTS API → Streaming output: yields chunks (evidence: `neutts/neutts.py`)
- NeuTTS API → Generated waveform: returns waveform (evidence: `neutts/neutts.py`)
- Streaming output → Generated waveform: yields audio (evidence: `neutts/neutts.py`)
