# sparkaudio/spark-tts architecture

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

- Interactive diagram: https://gitdiagram.com/sparkaudio/spark-tts
- Repository: https://github.com/sparkaudio/spark-tts

## Overview

##### Project’s Key Purposes
- Spark-TTS is an advanced LLM-based text-to-speech solution that performs efficient voice synthesis, zero-shot voice cloning, bilingual support, and controllable speech generation.
- It provides multiple interfaces (CLI, Web UI) and supports production deployment via Nvidia Triton Inference Server with TensorRT-LLM.
- The project is divided into core inference code (within the “sparktts” package), utilities and helper modules, runtime integration for Triton, and demo resources.

##### Break Down the Project into Main Components
A. Input Interfaces:
- CLI Tools: Components under the cli folder (SparkTTS.py and inference.py) for direct command-line invocation.
- Web UI: The webui.py file launches a user interface for voice cloning and creation.

B. Core Inference Engine (Spark-TTS Library):
- Core Modules: The “sparktts” directory contains the models, key modules (like blocks, encoder_decoder, fsq, speaker, vq) and utility functions (found in sparktts/utils and sparktts/models).
- These modules together implement the decoding pipeline for audio reconstruction, voice cloning capabilities, and parameter control.

C. Pre-processing and Demos:
- Demos Folder (“src/demos”): Provides sample audio files used for demonstration purposes.

D. Runtime and Deployment:
- Triton Inference Server Components: The “runtime/triton_trtllm” directory includes Dockerfile configurations, gRPC/HTTP clients, docker-compose files, Triton model repos, and conversion scripts.
- These files detail how Spark-TTS is packaged as a service that can serve requests in production environments.

E. Configuration and Dependency Management:
- “requirements.txt” for Python dependencies.
- Additional configuration files (e.g., Dockerfiles and .sh scripts) that support deployment and conversion tasks.

##### Relationships and Data Flow
- Processing Flow:
- Within the core library, highlight internal sub-components such as the audio_tokenizer, vocoder, and the decoupled text-to-speech modules which together create the speech output.
- Output Flow: Display the flow from the core library to the output (e.g., generated audio files stored in a “results” folder under examples or returned via the web interface).
- Deployment Path: Separately, illustrate the Triton Inference Serving branch where the models (organized as audio_tokenizer, spark_tts, spark_tts_decoupled, tensorrt_llm, vocoder under the Triton model repo) are deployed and served via GRPC and HTTP client modules.

##### Architectural Patterns and Design Principles
- Modularity: Emphasize the separation of concerns between input handling (CLI & UI), processing logic (Spark-TTS core modules), and deployment (runtime Triton stack).
- Decoupling: Note the “single-stream decoupled speech tokens” architectural choice where the LLM predicts codes that are directly used to reconstruct audio.
- Service Orientation: For the runtime part, show how Docker and docker-compose are used to containerize and orchestrate the inference server.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Interfaces Subgraph
    subgraph "Input Interfaces"
        CLI_SparkTTS("CLI: SparkTTS"):::user
        CLI_Inference("CLI: Inference"):::user
        Web_UI("Web UI"):::user
    end

    %% Core Processing Subgraph
    subgraph "Core Processing"
        SparkTTS_Core("Spark-TTS Core Engine"):::core
        subgraph "Internal Modules"
            Core_Modules("Core Modules & Models"):::coreInternal
        end
        SparkTTS_Core -->|"uses"| Core_Modules
        SparkTTS_Core -->|"produces"| Audio_Output("Audio Output"):::output
        SparkTTS_Core -->|"deploys"| Triton_Runtime("Triton Inference Server Runtime"):::deployment
        SparkTTS_Core -->|"demo output"| Demos("Pre-processing & Demos"):::demos
    end

    %% Configuration Subgraph
    subgraph "Configuration & Dependencies"
        Config("Config & Dependency Files"):::config
    end

    %% Client Interaction Subgraph
    subgraph "Client Interaction"
        Client("Client Requests"):::user
    end

    %% Connections from Input Interfaces to Core Processing
    CLI_SparkTTS -->|"input"| SparkTTS_Core
    CLI_Inference -->|"input"| SparkTTS_Core
    Web_UI -->|"input"| SparkTTS_Core

    %% Connections from Configuration to Core and Runtime
    Config -->|"dependencies"| SparkTTS_Core
    Config -->|"dependencies"| Triton_Runtime

    %% Connection from Runtime to Client
    Triton_Runtime -->|"serves"| Client

    %% Click Events
    click CLI_SparkTTS "https://github.com/sparkaudio/spark-tts/blob/main/cli/SparkTTS.py"
    click CLI_Inference "https://github.com/sparkaudio/spark-tts/blob/main/cli/inference.py"
    click Web_UI "https://github.com/sparkaudio/spark-tts/blob/main/webui.py"
    click Core_Modules "https://github.com/sparkaudio/spark-tts/tree/main/sparktts/"
    click Demos "https://github.com/sparkaudio/spark-tts/tree/main/src/demos"
    click Triton_Runtime "https://github.com/sparkaudio/spark-tts/tree/main/runtime/triton_trtllm"
    click Config "https://github.com/sparkaudio/spark-tts/blob/main/requirements.txt"

    %% Styles
    classDef user fill:#f9e79f,stroke:#c0392b,stroke-width:2px;
    classDef core fill:#aed6f1,stroke:#2471a3,stroke-width:2px;
    classDef coreInternal fill:#d6eaf8,stroke:#1f618d,stroke-width:2px;
    classDef deployment fill:#fad7a0,stroke:#d35400,stroke-width:2px;
    classDef config fill:#fcf3cf,stroke:#f1c40f,stroke-width:2px;
    classDef demos fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef output fill:#f9c6c9,stroke:#c0392b,stroke-width:2px;
```
