# hexgrad/kokoro architecture

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

- Interactive diagram: https://gitdiagram.com/hexgrad/kokoro
- Repository: https://github.com/hexgrad/kokoro

## Overview

Kokoro is an inference library for multilingual text-to-speech, with Python and JavaScript implementations. The main Python workflow accepts text through KPipeline, applies language-aware phonemization and voice selection, then invokes KModel to synthesize audio; users can also use the CLI to write WAV output. The model combines text/prosody components with an audio decoder and STFT support. The JavaScript API provides a parallel generate workflow with sentence splitting, phonemization, voice data, and a Transformers runtime. Relationships for unsampled internals are omitted; documented capabilities and explicit imports are retained.

Main entry points: [`kokoro/pipeline.py`](https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py) (KPipeline), [`kokoro.js/src/kokoro.js`](https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/kokoro.js) (KokoroTTS API), [`kokoro/model.py`](https://github.com/hexgrad/kokoro/blob/main/kokoro/model.py) (KModel), [`kokoro/istftnet.py`](https://github.com/hexgrad/kokoro/blob/main/kokoro/istftnet.py) (Audio decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python_api["Python API"]
  node_cli["CLI WAV output<br/>[__main__.py]"]
  node_pipeline["KPipeline<br/>[pipeline.py]"]
  node_phonemizer["Language G2P<br/>[pipeline.py]"]
  node_voice_load["Voice loading<br/>[pipeline.py]"]
end

subgraph group_python_model["Python Model"]
  node_model["KModel<br/>[model.py]"]
  node_nn_modules["Text and prosody nets<br/>[modules.py]"]
  node_decoder["Audio decoder<br/>[istftnet.py]"]
  node_stft["Custom STFT<br/>[custom_stft.py]"]
end

subgraph group_js_runtime["JavaScript Runtime"]
  node_js_api["KokoroTTS API<br/>[kokoro.js]"]
  node_js_phonemize["Text phonemizer<br/>[phonemize.js]"]
  node_js_splitter["Sentence splitter<br/>[splitter.js]"]
  node_js_voices["Voice data<br/>[voices.js]"]
end

subgraph group_external["External Services"]
  node_transformers["Transformers runtime"]
  node_misaki["Misaki G2P"]
  node_hub["Hugging Face Hub"]
end

node_user(("Text caller"))
node_js_caller(("JS API caller"))

node_user -->|"provides text"| node_cli
node_cli -->|"generates audio"| node_pipeline
node_pipeline -->|"phonemizes text"| node_phonemizer
node_pipeline -->|"loads voice"| node_voice_load
node_pipeline -->|"invokes model"| node_model
node_pipeline -->|"uses G2P"| node_misaki
node_voice_load -->|"downloads voice"| node_hub
node_model -->|"loads weights"| node_hub
node_model -->|"uses networks"| node_nn_modules
node_model -->|"uses decoder"| node_decoder
node_nn_modules -->|"uses blocks"| node_decoder
node_decoder -->|"uses transform"| node_stft
node_js_caller -->|"generates speech"| node_js_api
node_js_api -->|"phonemizes text"| node_js_phonemize
node_js_api -->|"splits text"| node_js_splitter
node_js_api -->|"loads voice data"| node_js_voices
node_js_api -->|"runs model"| node_transformers
node_js_phonemize -->|"uses phonemizer"| node_transformers

click node_cli "https://github.com/hexgrad/kokoro/blob/main/kokoro/__main__.py"
click node_pipeline "https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py"
click node_phonemizer "https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py"
click node_voice_load "https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py"
click node_model "https://github.com/hexgrad/kokoro/blob/main/kokoro/model.py"
click node_nn_modules "https://github.com/hexgrad/kokoro/blob/main/kokoro/modules.py"
click node_decoder "https://github.com/hexgrad/kokoro/blob/main/kokoro/istftnet.py"
click node_stft "https://github.com/hexgrad/kokoro/blob/main/kokoro/custom_stft.py"
click node_js_api "https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/kokoro.js"
click node_js_phonemize "https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/phonemize.js"
click node_js_splitter "https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/splitter.js"
click node_js_voices "https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/voices.js"

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_cli,node_pipeline,node_phonemizer,node_voice_load toneBlue
class node_model,node_nn_modules,node_decoder,node_stft toneAmber
class node_js_api,node_js_phonemize,node_js_splitter,node_js_voices,node_js_caller toneMint
class node_transformers,node_misaki,node_hub toneRose
class node_user toneIndigo
```

## Components

### Python API

- [CLI WAV output](https://github.com/hexgrad/kokoro/blob/main/kokoro/__main__.py): `kokoro/__main__.py`
- [KPipeline](https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py): `kokoro/pipeline.py`
- [Language G2P](https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py): `kokoro/pipeline.py`
- [Voice loading](https://github.com/hexgrad/kokoro/blob/main/kokoro/pipeline.py): `kokoro/pipeline.py`

### Python Model

- [KModel](https://github.com/hexgrad/kokoro/blob/main/kokoro/model.py): `kokoro/model.py`
- [Text and prosody nets](https://github.com/hexgrad/kokoro/blob/main/kokoro/modules.py): `kokoro/modules.py`
- [Audio decoder](https://github.com/hexgrad/kokoro/blob/main/kokoro/istftnet.py): `kokoro/istftnet.py`
- [Custom STFT](https://github.com/hexgrad/kokoro/blob/main/kokoro/custom_stft.py): `kokoro/custom_stft.py`

### JavaScript Runtime

- [KokoroTTS API](https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/kokoro.js): `kokoro.js/src/kokoro.js`
- [Text phonemizer](https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/phonemize.js): `kokoro.js/src/phonemize.js`
- [Sentence splitter](https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/splitter.js): `kokoro.js/src/splitter.js`
- [Voice data](https://github.com/hexgrad/kokoro/blob/main/kokoro.js/src/voices.js): `kokoro.js/src/voices.js`

### External Services

- **Transformers runtime**
- **Misaki G2P**
- **Hugging Face Hub**

### Other components

- **Text caller**
- **JS API caller**

## Connections

- Text caller → CLI WAV output: provides text (evidence: `kokoro/__main__.py`)
- CLI WAV output → KPipeline: generates audio (evidence: `kokoro/__main__.py`)
- KPipeline → Language G2P: phonemizes text (evidence: `kokoro/pipeline.py`)
- KPipeline → Voice loading: loads voice (evidence: `kokoro/pipeline.py`)
- KPipeline → KModel: invokes model (evidence: `kokoro/pipeline.py`)
- KPipeline → Misaki G2P: uses G2P (evidence: `kokoro/pipeline.py`)
- Voice loading → Hugging Face Hub: downloads voice (evidence: `kokoro/pipeline.py`)
- KModel → Hugging Face Hub: loads weights (evidence: `kokoro/model.py`)
- KModel → Text and prosody nets: uses networks (evidence: `kokoro/model.py`)
- KModel → Audio decoder: uses decoder (evidence: `kokoro/model.py`)
- Text and prosody nets → Audio decoder: uses blocks (evidence: `kokoro/modules.py`)
- Audio decoder → Custom STFT: uses transform (evidence: `kokoro/istftnet.py`)
- JS API caller → KokoroTTS API: generates speech (evidence: `kokoro.js/src/kokoro.js`)
- KokoroTTS API → Text phonemizer: phonemizes text (evidence: `kokoro.js/src/kokoro.js`)
- KokoroTTS API → Sentence splitter: splits text (evidence: `kokoro.js/src/kokoro.js`)
- KokoroTTS API → Voice data: loads voice data (evidence: `kokoro.js/src/kokoro.js`)
- KokoroTTS API → Transformers runtime: runs model (evidence: `kokoro.js/src/kokoro.js`)
- Text phonemizer → Transformers runtime: uses phonemizer (evidence: `kokoro.js/src/phonemize.js`)
