# jianchang512/chattts-ui architecture

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

- Interactive diagram: https://gitdiagram.com/jianchang512/chattts-ui
- Repository: https://github.com/jianchang512/chattts-ui

## Overview

##### Project Type & Purpose
- This is a full‑stack Python web application (“ChatTTS webUI & API”) that provides a browser‑based UI and a RESTful API for on‑premise text‑to‑speech synthesis.
- The backend is a Flask/FastAPI‑style server (app.py/run.py) embedding the ChatTTS engine (in the ChatTTS/ package), and the frontend is a simple HTML/JS interface (templates/ + static/).

##### High‑Level Components
a. Frontend
- templates/index.html, indexen.html
- static/js/layer (layer.js, CSS themes)
b. API/Web Server
- app.py, run.py (entrypoints)
- ChatTTS/infer/api.py (HTTP endpoint logic)
- Dockerfiles & docker‑compose for CPU/GPU deployment
c. ChatTTS Core Engine
- ChatTTS/core.py (orchestrator)
- ChatTTS/config/config.py (singleton config loader)
- ChatTTS/norm.py + uilib/zh_normalization (text normalization)
- ChatTTS/model/ (model definitions & CUDA patches)
- ChatTTS/model/tokenizer.py, processors.py (pre/post‑processing)
d. Inference Compute
- CPU path: torch, torchaudio, pure‑Python inference
- GPU path: ChatTTS/model/cuda/*, PyTorch‑CUDA kernels
- FFmpeg (external binary) for audio merging/post‑processing
e. Assets & Storage
- asset/ (download scripts, pt files)
- speaker/ (converted speaker embeddings)
- static/wavs/ (generated audio files)
f. Utilities & Tools
- ChatTTS/utils/* (download, I/O, logging, GPU detection)
- tools/ (CLI helpers in Go/Python, not part of runtime)

##### Component Interactions & Data Flow
1. User (Browser) → HTTP Request (GET /) → Web Server serves HTML/JS.
2. User triggers TTS → HTTP POST /tts → infer/api.py
3. API layer pulls parameters → calls ChatTTS/core.py
4. core.py invokes:
a. Text normalization (norm.py + uilib)
b. Tokenization & prompt processing (model/tokenizer.py)
c. Model inference via CPU or GPU modules (model/dvae.py, model/gpt.py, model/cuda/…)
5. Generated raw audio segments → post‑process via FFmpeg
6. Write .wav to static/wavs/ → return JSON {code, msg, audio_files:[…URL…]}
7. Browser/Client downloads and plays back audio

##### Architectural Patterns & Principles
- MVC‑style separation:
- View = templates/ + static/
- Controller = app.py + infer/api.py
- Model = ChatTTS package & PyTorch models
- Singleton configuration (config/config.py)
- Pluggable compute backends (CPU vs CUDA vs ROCm)
- Lazy download & caching of model files (utils/download.py)
- Modular normalization pipeline (uilib + ChatTTS/norm.py)

## Diagram (Mermaid)

```mermaid
graph TD
    Browser["Browser"]:::external

    subgraph "Presentation Layer"
        templates_index["templates/index.html"]:::frontend
        templates_indexen["templates/indexen.html"]:::frontend
        layer_js["static/js/layer/layer.js"]:::frontend
        mobile_layer_js["static/js/layer/mobile/layer.js"]:::frontend
        mobile_css["static/js/layer/mobile/need/layer.css"]:::frontend
        theme_css["static/js/layer/theme/default/layer.css"]:::frontend
    end

    Browser -->|"GET /"| app_cpu

    subgraph "Docker Deployment"
        subgraph "CPU Service"
            app_cpu["app.py"]:::api
            run_cpu["run.py"]:::api
            api_cpu["ChatTTS/infer/api.py"]:::api
            core_cpu["ChatTTS/core.py"]:::model
            config_cpu["ChatTTS/config/config.py"]:::util

            subgraph "Domain Logic"
                norm_cpu["ChatTTS/norm.py"]:::model
                uilib_cpu["uilib/zh_normalization"]:::model
                tok_cpu["ChatTTS/model/tokenizer.py"]:::model
                proc_cpu["ChatTTS/model/processors.py"]:::model
                dvae_cpu["ChatTTS/model/dvae.py"]:::model
                gpt_cpu["ChatTTS/model/gpt.py"]:::model
                patch_cpu["ChatTTS/model/cuda/patch.py"]:::model
                llama_cpu["ChatTTS/model/cuda/te_llama.py"]:::model
                llm_cpu["ChatTTS/experimental/llm.py"]:::model
            end

            subgraph "Utilities"
                dl_cpu["ChatTTS/utils/dl.py"]:::util
                download_cpu["ChatTTS/utils/download.py"]:::util
                gpu_cpu1["ChatTTS/utils/gpu.py"]:::util
                gpu_cpu2["ChatTTS/utils/gpu_utils.py"]:::util
                infer_util_cpu["ChatTTS/utils/infer_utils.py"]:::util
                io_cpu1["ChatTTS/utils/io.py"]:::util
                io_cpu2["ChatTTS/utils/io_utils.py"]:::util
                log_cpu["ChatTTS/utils/log.py"]:::util
            end
        end

        subgraph "GPU Service"
            app_gpu["app.py"]:::api
            run_gpu["run.py"]:::api
            api_gpu["ChatTTS/infer/api.py"]:::api
            core_gpu["ChatTTS/core.py"]:::model
            config_gpu["ChatTTS/config/config.py"]:::util

            subgraph "Domain Logic"
                norm_gpu["ChatTTS/norm.py"]:::model
                uilib_gpu["uilib/zh_normalization"]:::model
                tok_gpu["ChatTTS/model/tokenizer.py"]:::model
                proc_gpu["ChatTTS/model/processors.py"]:::model
                dvae_gpu["ChatTTS/model/dvae.py"]:::model
                gpt_gpu["ChatTTS/model/gpt.py"]:::model
                patch_gpu["ChatTTS/model/cuda/patch.py"]:::model
                llama_gpu["ChatTTS/model/cuda/te_llama.py"]:::model
                llm_gpu["ChatTTS/experimental/llm.py"]:::model
            end

            subgraph "Utilities"
                dl_gpu["ChatTTS/utils/dl.py"]:::util
                download_gpu["ChatTTS/utils/download.py"]:::util
                gpu_gpu1["ChatTTS/utils/gpu.py"]:::util
                gpu_gpu2["ChatTTS/utils/gpu_utils.py"]:::util
                infer_util_gpu["ChatTTS/utils/infer_utils.py"]:::util
                io_gpu1["ChatTTS/utils/io.py"]:::util
                io_gpu2["ChatTTS/utils/io_utils.py"]:::util
                log_gpu["ChatTTS/utils/log.py"]:::util
            end
        end
    end

    app_cpu -->|"POST /tts"| api_cpu
    api_cpu -->|"invoke"| core_cpu
    core_cpu --> norm_cpu --> uilib_cpu
    norm_cpu --> tok_cpu --> proc_cpu
    proc_cpu --> dvae_cpu
    proc_cpu --> gpt_cpu
    dvae_cpu --> patch_cpu
    gpt_cpu --> llama_cpu
    patch_cpu --> ffmpeg
    llama_cpu --> ffmpeg
    llm_cpu --> core_cpu

    app_gpu -->|"POST /tts"| api_gpu
    api_gpu -->|"invoke"| core_gpu
    core_gpu --> norm_gpu --> uilib_gpu
    norm_gpu --> tok_gpu --> proc_gpu
    proc_gpu --> dvae_gpu
    proc_gpu --> gpt_gpu
    dvae_gpu --> patch_gpu
    gpt_gpu --> llama_gpu
    patch_gpu --> ffmpeg
    llama_gpu --> ffmpeg
    llm_gpu --> core_gpu

    subgraph "Infrastructure"
        Torch["Torch Runtime"]:::external
        GPUDrv["GPU Driver"]:::external
        ffmpeg["FFmpeg"]:::external
        Storage["File Storage (static/wavs/, asset/, speaker/)"]:::util
    end

    ffmpeg -->|"writes .wav"| Storage
    Storage -->|"serve audio"| Browser

    subgraph "External Services"
        Models["modelscope / huggingface"]:::external
    end

    download_cpu --> Models
    download_gpu --> Models

    classDef frontend fill:#AED6F1,stroke:#1F618D,color:#1B2631
    classDef api fill:#ABEBC6,stroke:#196F3D,color:#1B2631
    classDef model fill:#FAD7A0,stroke:#B9770E,color:#1B2631
    classDef util fill:#D5D8DC,stroke:#566573,color:#1B2631
    classDef external fill:#FEF9E7,stroke:#B7950B,color:#1B2631

    click templates_index "https://github.com/jianchang512/chattts-ui/blob/main/templates/index.html"
    click templates_indexen "https://github.com/jianchang512/chattts-ui/blob/main/templates/indexen.html"
    click layer_js "https://github.com/jianchang512/chattts-ui/blob/main/static/js/layer/layer.js"
    click mobile_layer_js "https://github.com/jianchang512/chattts-ui/blob/main/static/js/layer/mobile/layer.js"
    click mobile_css "https://github.com/jianchang512/chattts-ui/blob/main/static/js/layer/mobile/need/layer.css"
    click theme_css "https://github.com/jianchang512/chattts-ui/blob/main/static/js/layer/theme/default/layer.css"
    click app_cpu "https://github.com/jianchang512/chattts-ui/blob/main/app.py"
    click run_cpu "https://github.com/jianchang512/chattts-ui/blob/main/run.py"
    click api_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/infer/api.py"
    click core_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/core.py"
    click config_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/config/config.py"
    click norm_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/norm.py"
    click uilib_cpu "https://github.com/jianchang512/chattts-ui/blob/main/uilib/zh_normalization/char_convert.py"
    click tok_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/tokenizer.py"
    click proc_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/processors.py"
    click dvae_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/dvae.py"
    click gpt_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/gpt.py"
    click patch_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/cuda/patch.py"
    click llama_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/model/cuda/te_llama.py"
    click llm_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/experimental/llm.py"
    click dl_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/dl.py"
    click download_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/download.py"
    click gpu_cpu1 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/gpu.py"
    click gpu_cpu2 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/gpu_utils.py"
    click infer_util_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/infer_utils.py"
    click io_cpu1 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/io.py"
    click io_cpu2 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/io_utils.py"
    click log_cpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/log.py"
    click dl_gpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/dl.py"
    click download_gpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/download.py"
    click gpu_gpu1 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/gpu.py"
    click gpu_gpu2 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/gpu_utils.py"
    click infer_util_gpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/infer_utils.py"
    click io_gpu1 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/io.py"
    click io_gpu2 "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/io_utils.py"
    click log_gpu "https://github.com/jianchang512/chattts-ui/blob/main/ChatTTS/utils/log.py"
    click Models "https://github.com/jianchang512/chattts-ui/blob/main/asset/模型下载说明.txt"
```
