# eepstein201/qwen3-tts-advanced-eme architecture

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

- Interactive diagram: https://gitdiagram.com/eepstein201/qwen3-tts-advanced-eme
- Repository: https://github.com/eepstein201/qwen3-tts-advanced-eme

## Overview

Qwen3-TTS is a local voice-generation product: users submit text and a voice mode through the CLI, Python/client API, or Gradio UI; the FastAPI server validates requests, loads the requested model, synthesizes audio, and returns completed or streamed results. Clone, Design, and Custom share server-side model management and the inference engine. The README also documents prompt creation, transcription, chunked playback, history/model controls, and Torch, MLX, and optional vLLM backends. Paths for several capabilities are supported by the tree and README, but their internal wiring was not sampled; the graph omits uncertain links.

Main entry points: [`qwen3_tts/server/app.py`](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app.py) (FastAPI server), [`qwen3_tts/core/engine/inference.py`](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/inference.py) (Inference dispatch), [`qwen3_tts/server/client/generator.py`](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/client/generator.py) (Server client), [`qwen3_tts/server/app_generation.py`](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_generation.py) (Generation routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_cli_modes["Batch and dialogue"]
  node_python_api["Python generation<br/>[generate.py]"]
  node_web_ui["Gradio UI"]
  node_client["Server client<br/>[generator.py]"]
end

subgraph group_server["Server orchestration"]
  node_websocket["Streaming endpoint<br/>[websocket.py]"]
  node_fastapi["FastAPI server<br/>[app.py]"]
  node_generation_routes["Generation routes<br/>[app_generation.py]"]
  node_model_routes["Model routes<br/>[app_models.py]"]
  node_model_loading["Model loading<br/>[model_loading.py]"]
  node_prompt_routes["Prompt routes<br/>[app_prompts.py]"]
  node_prompt_loading["Prompt loading<br/>[prompt_loading.py]"]
  node_validation["Request validation<br/>[validation.py]"]
end

subgraph group_generation["Synthesis engine"]
  node_inference["Inference dispatch<br/>[inference.py]"]
  node_text_processing["Text processing<br/>[text_processing.py]"]
  node_audio_processing["Audio processing"]
  node_asr["Speech transcription<br/>[asr.py]"]
end

subgraph group_state["Configuration and voices"]
  node_config["Runtime configuration"]
  node_voice_prompt["Voice prompts<br/>[voice_prompt.py]"]
end

subgraph group_backends["Inference backends"]
  node_model_loader["Torch and MLX<br/>[model_loader.py]"]
  node_vllm_client["vLLM client<br/>[vllm_client.py]"]
  node_vllm_adapter["vLLM adapter<br/>[engine_vllm.py]"]
end

node_user(("User"))
node_audio_result["Generated audio"]

node_user -->|"selects workflow"| node_cli
node_user -->|"submits request"| node_web_ui
node_user -->|"calls API"| node_python_api
node_cli -->|"requests generation"| node_client
node_cli_modes -->|"requests generation"| node_client
node_python_api -->|"requests generation"| node_client
node_web_ui -->|"calls server"| node_client
node_client -->|"HTTP requests"| node_fastapi
node_fastapi -->|"validates input"| node_validation
node_fastapi -->|"dispatches routes"| node_generation_routes
node_generation_routes -->|"runs synthesis"| node_inference
node_inference -->|"prepares text"| node_text_processing
node_inference -->|"processes audio"| node_audio_processing
node_inference -->|"uses backend"| node_model_loader
node_inference -->|"uses voice prompt"| node_voice_prompt
node_inference -->|"reads settings"| node_config
node_model_routes -->|"loads models"| node_model_loading
node_fastapi -->|"dispatches routes"| node_model_routes
node_fastapi -->|"dispatches routes"| node_prompt_routes
node_prompt_routes -->|"loads prompts"| node_prompt_loading
node_prompt_loading -->|"uses prompt handling"| node_voice_prompt
node_generation_routes -->|"returns audio"| node_audio_result
node_generation_routes -->|"streams chunks"| node_websocket
node_websocket -->|"streams audio"| node_audio_result
node_asr -->|"transcribes audio"| node_audio_result
node_fastapi -.->|"uses when configured"| node_vllm_client
node_vllm_client -.->|"calls local backend"| node_vllm_adapter

click node_cli "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/cli.py"
click node_cli_modes "https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/interface/cli"
click node_python_api "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/interface/generate.py"
click node_web_ui "https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/interface/ui"
click node_websocket "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/websocket.py"
click node_fastapi "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app.py"
click node_generation_routes "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_generation.py"
click node_model_routes "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_models.py"
click node_model_loading "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/model_loading.py"
click node_prompt_routes "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_prompts.py"
click node_prompt_loading "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/prompt_loading.py"
click node_validation "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/validation.py"
click node_client "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/client/generator.py"
click node_inference "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/inference.py"
click node_text_processing "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/text_processing.py"
click node_audio_processing "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/audio_processing.py"
click node_asr "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/asr.py"
click node_config "https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/core/config"
click node_voice_prompt "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/voice_prompt.py"
click node_model_loader "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/model_loader.py"
click node_vllm_client "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/vllm_client.py"
click node_vllm_adapter "https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine_vllm.py"

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_cli_modes,node_python_api,node_web_ui,node_client,node_user toneBlue
class node_websocket,node_fastapi,node_generation_routes,node_model_routes,node_model_loading,node_prompt_routes,node_prompt_loading,node_validation toneAmber
class node_inference,node_text_processing,node_audio_processing,node_asr toneMint
class node_config,node_voice_prompt toneRose
class node_model_loader,node_vllm_client,node_vllm_adapter,node_audio_result toneIndigo
```

## Components

### User interfaces

- [CLI](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/cli.py): `qwen3_tts/cli.py`
- [Batch and dialogue](https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/interface/cli): `qwen3_tts/interface/cli`
- [Python generation](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/interface/generate.py): `qwen3_tts/interface/generate.py`
- [Gradio UI](https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/interface/ui): `qwen3_tts/interface/ui`
- [Server client](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/client/generator.py): `qwen3_tts/server/client/generator.py`

### Server orchestration

- [Streaming endpoint](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/websocket.py): `qwen3_tts/server/websocket.py`
- [FastAPI server](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app.py): `qwen3_tts/server/app.py`
- [Generation routes](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_generation.py): `qwen3_tts/server/app_generation.py`
- [Model routes](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_models.py): `qwen3_tts/server/app_models.py`
- [Model loading](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/model_loading.py): `qwen3_tts/server/model_loading.py`
- [Prompt routes](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/app_prompts.py): `qwen3_tts/server/app_prompts.py`
- [Prompt loading](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/prompt_loading.py): `qwen3_tts/server/prompt_loading.py`
- [Request validation](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/validation.py): `qwen3_tts/server/validation.py`

### Synthesis engine

- [Inference dispatch](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/inference.py): `qwen3_tts/core/engine/inference.py`
- [Text processing](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/text_processing.py): `qwen3_tts/core/engine/text_processing.py`
- [Audio processing](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/audio_processing.py): `qwen3_tts/core/engine/audio_processing.py`
- [Speech transcription](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/asr.py): `qwen3_tts/core/engine/asr.py`

### Configuration and voices

- [Runtime configuration](https://github.com/eepstein201/qwen3-tts-advanced-eme/tree/main/qwen3_tts/core/config): `qwen3_tts/core/config`
- [Voice prompts](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/voice_prompt.py): `qwen3_tts/core/engine/voice_prompt.py`

### Inference backends

- [Torch and MLX](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine/model_loader.py): `qwen3_tts/core/engine/model_loader.py`
- [vLLM client](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/server/vllm_client.py): `qwen3_tts/server/vllm_client.py`
- [vLLM adapter](https://github.com/eepstein201/qwen3-tts-advanced-eme/blob/main/qwen3_tts/core/engine_vllm.py): `qwen3_tts/core/engine_vllm.py`

### Other components

- **User**
- **Generated audio**

## Connections

- User → CLI: selects workflow
- User → Gradio UI: submits request
- User → Python generation: calls API
- CLI → Server client: requests generation
- Batch and dialogue → Server client: requests generation
- Python generation → Server client: requests generation
- Gradio UI → Server client: calls server
- Server client → FastAPI server: HTTP requests
- FastAPI server → Request validation: validates input
- FastAPI server → Generation routes: dispatches routes
- Generation routes → Inference dispatch: runs synthesis
- Inference dispatch → Text processing: prepares text
- Inference dispatch → Audio processing: processes audio
- Inference dispatch → Torch and MLX: uses backend
- Inference dispatch → Voice prompts: uses voice prompt
- Inference dispatch → Runtime configuration: reads settings
- Model routes → Model loading: loads models
- FastAPI server → Model routes: dispatches routes
- FastAPI server → Prompt routes: dispatches routes
- Prompt routes → Prompt loading: loads prompts
- Prompt loading → Voice prompts: uses prompt handling
- Generation routes → Generated audio: returns audio
- Generation routes → Streaming endpoint: streams chunks
- Streaming endpoint → Generated audio: streams audio
- Speech transcription → Generated audio: transcribes audio
- FastAPI server → vLLM client: uses when configured
- vLLM client → vLLM adapter: calls local backend