# zyphra/zonos architecture

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

- Interactive diagram: https://gitdiagram.com/zyphra/zonos
- Repository: https://github.com/zyphra/zonos

## Overview

##### Project type and purpose
- This is an open-source, Python-based text-to-speech (TTS) toolkit and model library (“Zonos-v0.1”) that provides:
- A core TTS engine (text → DAC tokens → waveform)
- Zero-shot voice cloning via speaker embeddings or audio prefixes
- A minimal CLI sample, a Gradio web UI, and Dockerized deployment

##### File structure
- Top-level artifacts:
- Dockerfile & docker-compose.yml → containerized deployment
- pyproject.toml & uv.lock → build/configuration
- sample.py & gradio_interface.py → two user-facing entry points (CLI vs Web UI)
- assets/ → example audio and static images (used by README and Gradio)
- Core application package: zonos/
- zonos/model.py → main Zonos class (load pretrained, from_pretrained)
- zonos/conditioning.py → build conditioning dict from text/audio/pitch/rate/emotion
- zonos/utils.py → device management, helper functions
- zonos/sampling.py → convert model logits to discrete codes
- zonos/autoencoder.py → decode DAC tokens back to raw waveform
- zonos/backbone/ → two backbone implementations: transformer (_torch.py) vs hybrid SSM (_mamba_ssm.py)
- zonos/config.py, codebook_pattern.py, speaker_cloning.py → auxiliary components

##### README for additional insights
- Describes a linear pipeline:
Text normalization & phonemization (via external espeak-ng) → Transformer/Hybrid DAC token prediction → Autoencoder decode → 44 kHz waveform
- Mentions two modes (“hybrid” vs “transformer”), Gradio UI, Docker instructions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Interface Layer
    subgraph "Interface Layer"
        CLI["CLI Interface\n(sample.py)"]:::ui
        Web["Web UI (Gradio)\n(gradio_interface.py)"]:::ui
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        ES["espeak-ng\n(text→phonemes)"]:::external
        Cond["Conditioning\n(zonos/conditioning.py)"]:::pre
    end

    %% Inference Layer
    subgraph "Inference Layer"
        Zonos["Zonos Model\n(zonos/model.py)"]:::inference
        subgraph "Backbone"
            TF["Transformer Backbone\n(_torch.py)"]:::inference
            SSM["Hybrid SSM Backbone\n(_mamba_ssm.py)"]:::inference
        end
        Samp["Sampling\n(zonos/sampling.py)"]:::inference
    end

    %% Decoding Layer
    subgraph "Decoding Layer"
        AE["Autoencoder\n(zonos/autoencoder.py)"]:::post
    end

    %% Output Layer
    subgraph "Output Layer"
        Disk["Save to Disk"]:::output
        Stream["Stream to UI"]:::output
    end

    %% Utilities
    subgraph "Utilities"
        SC["Speaker Cloning\n(zonos/speaker_cloning.py)"]:::util
        CB["Codebook Pattern\n(zonos/codebook_pattern.py)"]:::util
        CFG["Configuration\n(zonos/config.py)"]:::util
        UT["Utils\n(zonos/utils.py)"]:::util
    end

    %% Deployment & Config
    subgraph "Deployment & Config"
        PyProj["pyproject.toml"]:::deploy
        UV["uv.lock"]:::deploy
        DockerfileNode["Dockerfile"]:::deploy
        Compose["docker-compose.yml"]:::deploy
        Assets["assets/"]:::deploy
    end

    %% External Frameworks
    Ext["External Frameworks\n(PyTorch, Torchaudio, Gradio, uv)"]:::external

    %% Data Flow
    CLI -->|text| ES
    Web -->|text| ES
    ES -->|phonemes| Cond
    CLI -->|audio/text| Cond
    Web -->|audio/text| Cond
    Cond -->|conditioning dict| Zonos
    Zonos -->|choose mode| TF
    Zonos -->|choose mode| SSM
    TF -->|logits| Samp
    SSM -->|logits| Samp
    Samp -->|DAC tokens| AE
    AE -->|wav:44kHz| Disk
    AE -->|wav stream| Stream

    %% Utility Dependencies
    Zonos -.-> UT
    Zonos -.-> CFG
    Zonos -.-> SC
    Zonos -.-> CB
    Zonos -.-> Ext

    %% Deployment Dependencies
    CLI -.->|runtime| PyProj
    CLI -.-> UV
    Web -.->|runtime| PyProj
    Web -.-> UV
    CLI -.-> Compose
    Web -.-> Compose
    DockerfileNode -.-> Compose
    CLI -.-> DockerfileNode
    Web -.-> DockerfileNode
    Assets -.-> Web
    Assets -.-> CLI

    %% Click Events
    click CLI "https://github.com/zyphra/zonos/blob/main/sample.py"
    click Web "https://github.com/zyphra/zonos/blob/main/gradio_interface.py"
    click DockerfileNode "https://github.com/zyphra/zonos/tree/main/Dockerfile"
    click Compose "https://github.com/zyphra/zonos/blob/main/docker-compose.yml"
    click PyProj "https://github.com/zyphra/zonos/blob/main/pyproject.toml"
    click UV "https://github.com/zyphra/zonos/blob/main/uv.lock"
    click Assets "https://github.com/zyphra/zonos/tree/main/assets/"
    click Cond "https://github.com/zyphra/zonos/blob/main/zonos/conditioning.py"
    click Zonos "https://github.com/zyphra/zonos/blob/main/zonos/model.py"
    click TF "https://github.com/zyphra/zonos/blob/main/zonos/backbone/_torch.py"
    click SSM "https://github.com/zyphra/zonos/blob/main/zonos/backbone/_mamba_ssm.py"
    click Samp "https://github.com/zyphra/zonos/blob/main/zonos/sampling.py"
    click AE "https://github.com/zyphra/zonos/blob/main/zonos/autoencoder.py"
    click SC "https://github.com/zyphra/zonos/blob/main/zonos/speaker_cloning.py"
    click CB "https://github.com/zyphra/zonos/blob/main/zonos/codebook_pattern.py"
    click CFG "https://github.com/zyphra/zonos/blob/main/zonos/config.py"
    click UT "https://github.com/zyphra/zonos/blob/main/zonos/utils.py"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#3399ff,color:#003366;
    classDef pre fill:#d4edda,stroke:#28a745,color:#155724;
    classDef inference fill:#ffe5b4,stroke:#ff9900,color:#663300;
    classDef post fill:#e2e3e5,stroke:#6c757d,color:#343a40;
    classDef output fill:#d1ecf1,stroke:#17a2b8,color:#0c5460;
    classDef deploy fill:#f8f9fa,stroke:#6c757d,color:#343a40;
    classDef util fill:#f5f5f5,stroke:#adb5bd,color:#495057;
    classDef external fill:#fdfd96,stroke:#ffd700,color:#8b8000;
```
