# dangvansam/viet-tts architecture

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

- Interactive diagram: https://gitdiagram.com/dangvansam/viet-tts
- Repository: https://github.com/dangvansam/viet-tts

## Overview

##### Main Components
- API Server & CLI: These are exposed through the “viettts/server.py” (for starting the API server) and “viettts/cli.py” (for the CLI commands). This component accepts text or audio inputs and returns synthesized speech.
- TTS Engine Pipeline: Divided into several parts:
– Text Preprocessing/Tokenization: Located in “viettts/tokenizer” (and its multilingual.tiktoken support) and possibly part of “viettts/utils/frontend_utils.py” for front-end text normalization.
– Transformer Module: Found under “viettts/transformer” with multiple submodules for encoder, decoder, attention, etc. This is the core that processes text into an intermediate representation.
– Flow Module: Located in “viettts/flow” contains the decoder, flow matching, and length regulator. This likely manages the timing/alignment aspects of text-to-speech conversion.
– Audio Generation (HifiGAN): Under “viettts/hifigan” with its generator and f0 predictor modules to convert processed representations into audio waveforms.
– Optional LLM Module: The “viettts/llm” directory, which could be used for additional language modeling or voice prompts.
- Utility Modules: “viettts/utils” providing helper functions for file I/O, common tasks, VAD (voice activity detection) and more.
- Pre-built Samples and Assets: The “samples” directory shows example audio files for built-in voices, and “assets” contains branding images, etc.
- Docker & Deployment files: Files like “Dockerfile”, “docker-compose.yaml”, and configurations under “.github/workflows” illustrate the CI/CD, containerization, and deployment processes.

##### Relationships and Flow
- User Interaction Layer:
– Users can interact via the CLI (command-line commands) or invoke REST API calls to the server.
- Request Flow:
– API/CLI receives a text input (and optionally an audio file for voice cloning).
– The input is passed to the text preprocessor/tokenizer to prepare it for synthesis.
– The transformer module then processes this tokenized input to generate an intermediate representation.
– The flow module adjusts timing and alignment before handing data off to the HifiGAN module.
– HifiGAN then synthesizes the final waveform.
– The synthesized audio is sent back as a response.
- Auxiliary interactions:
– Utility modules provide support across all stages.
– Docker configurations ensure that the API server and any required dependencies (e.g., NVIDIA drivers, CUDA) are properly containerized and deployed.

##### Architectural Patterns & Design Principles
- Modular Design: The project is organized into clearly separated components (tokenizer, transformer, flow, HifiGAN, CLI, server), enabling independent development and testing.
- Pipeline Architecture: The audio synthesis process follows a sequential pipeline, which can be visualized as a series of data transformations.
- Containerization & CI/CD: Docker and GitHub workflows indicate that the deployment and continuous integration/delivery are core parts of the development process.
- Extensibility: The design supports adding new voices and configurations easily, as seen in the “samples” directory and built-in voice commands.

## Diagram (Mermaid)

```mermaid
flowchart TD
    U("User"):::user

    subgraph "Frontend Layer"
        CLI("CLI Interface"):::frontend
        API("API Server (REST API)"):::frontend
    end

    U -->|"input"| CLI
    U -->|"input"| API

    subgraph "TTS Engine Pipeline"
        subgraph "Text Preprocessing"
            TP1("Text Tokenizer"):::module
            TP2("Frontend Utils"):::module
            TP1 -->|"normalizes"| TP2
        end
        LLM("Optional LLM Module"):::module
        T("Transformer Module"):::module
        F("Flow Module (Timing/Alignment)"):::module
        HG("Audio Generation (HifiGAN)"):::module
    end

    CLI -->|"invokes"| TP1
    API -->|"invokes"| TP1

    TP2 -->|"processed_text"| T
    TP1 -->|"augment"| LLM
    LLM -->|"supports"| T

    T -->|"transform"| F
    F -->|"generate_waveform"| HG
    HG -->|"synthesized_audio"| U

    UT("Utility Modules"):::module
    TP1 --- UT
    TP2 --- UT
    T --- UT
    F --- UT
    HG --- UT

    subgraph "Assets & Samples"
        SAM("Samples"):::asset
        AS("Assets"):::asset
    end

    HG ---|"reference"| SAM
    HG ---|"reference"| AS

    subgraph "Deployment & Containerization"
        DO("Dockerfile"):::deploy
        DC("docker-compose.yaml"):::deploy
        CP("CI/CD Workflows"):::deploy
    end

    API ---|"deployed_with"| DO
    API ---|"deployed_with"| DC
    API ---|"deployed_with"| CP

    click API "https://github.com/dangvansam/viet-tts/blob/main/viettts/server.py"
    click CLI "https://github.com/dangvansam/viet-tts/blob/main/viettts/cli.py"
    click TP1 "https://github.com/dangvansam/viet-tts/tree/main/viettts/tokenizer"
    click TP2 "https://github.com/dangvansam/viet-tts/blob/main/viettts/utils/frontend_utils.py"
    click T "https://github.com/dangvansam/viet-tts/tree/main/viettts/transformer"
    click F "https://github.com/dangvansam/viet-tts/tree/main/viettts/flow"
    click HG "https://github.com/dangvansam/viet-tts/tree/main/viettts/hifigan"
    click LLM "https://github.com/dangvansam/viet-tts/blob/main/viettts/llm/llm.py"
    click UT "https://github.com/dangvansam/viet-tts/tree/main/viettts/utils"
    click SAM "https://github.com/dangvansam/viet-tts/tree/main/samples"
    click AS "https://github.com/dangvansam/viet-tts/tree/main/assets"
    click DO "https://github.com/dangvansam/viet-tts/tree/main/Dockerfile"
    click DC "https://github.com/dangvansam/viet-tts/blob/main/docker-compose.yaml"
    click CP "https://github.com/dangvansam/viet-tts/tree/main/.github/workflows"

    classDef user fill:#f9f,stroke:#333,stroke-width:2px;
    classDef frontend fill:#cff,stroke:#333,stroke-width:2px;
    classDef module fill:#fcf,stroke:#333,stroke-width:2px;
    classDef asset fill:#cfc,stroke:#333,stroke-width:2px;
    classDef deploy fill:#ff9,stroke:#333,stroke-width:2px;
```
