EzTTS-cuda-webui-api

Vocalizzatore TTS con WebUI + API, basato su Qwen3-TTS. Gira su CPU, GPU NVIDIA (CUDA) o backend remoto (LM Studio / endpoint OpenAI-compatibile) — la stessa app in tutte le modalità: stessa API, stessa WebUI, stessa gallery.

• Voce di default: Vivian (femminile, vivace) — alternative: Serena, Ryan, Aiden, Ono_Anna, Sohee, Uncle_Fu, Dylan, Eric
• Lingua di default: Italian (o Auto per code-switching italiano/inglese nei termini tecnici)
• Tono/direzione opzionale: "parla in modo caldo e amichevole", "tono serio", "sussurra", ecc.
• Offline: modello scaricato una volta, poi tutto locale sulla GPU

Funzionalità

Funzione	Descrizione
🖥️ WebUI voicechat	Tema scuro, bolle chat, wave animata, feed delle ultime 12 generazioni con opzioni usate (voce, lingua, tono, tempo) per replicare i toni
📖 Guida in pagina	Dropdown con REST API, MCP, skill e usi (mail, segreteria, roleplay, spiegazioni)
🔌 API	/api/tts (JSON→WAV) e /v1/audio/speech (OpenAI-compat)
🤖 MCP	qwen_tts_mcp.py → tool qwen_tts_speak per qualsiasi agente
🎧 Play locale	audio_daemon.py + play_audio.py: coda FIFO senza sovrapposizioni
🖼️ Gallery	Solo le generazioni fatte DALLA webui finiscono nel feed; API/MCP/agent ricevono il file diretto (mai in gallery)
🐳 Docker	CPU, GPU CUDA, o remote backend — vedi sotto

Avvio rapido (nativo, Windows/Linux)

# 1. ambiente
uv venv .venv --python 3.11
uv pip install --python ".venv/Scripts/python.exe" -r requirements.txt   # Windows
# su GPU NVIDIA: reinstallare torch con CUDA
uv pip install --python ".venv/Scripts/python.exe" --upgrade torch --index-url https://download.pytorch.org/whl/cu126

# 2. server (modello ~1.2GB scaricato al primo avvio, poi in VRAM)
./.venv/Scripts/python.exe qwen_server.py --port 8790

# 3. apri http://127.0.0.1:8790/

Avvio rapido (Docker)

# CPU
docker build -t eztts:latest .
docker run -p 8790:8790 -v eztts_out:/app/outputs eztts:latest

# GPU NVIDIA
docker build --build-arg TARGET=cuda -t eztts:cuda .
docker run --gpus all -p 8790:8790 -v eztts_out:/app/outputs eztts:cuda

# oppure con compose
docker compose up -d                                    # CPU
docker compose -f docker-compose.yml -f docker-compose.gpu.yml up -d     # GPU

Backend remoto (LM Studio / API esterna)

Senza GPU locale: l'app stessa fa da proxy verso un endpoint OpenAI-compatibile.

docker compose -f docker-compose.yml -f docker-compose.remote.yml up -d
# oppure nativo:
EZ_TTS_REMOTE_URL=http://127.0.0.1:1234/v1 python qwen_server.py --port 8790

Variabili: EZ_TTS_REMOTE_URL (obbligatoria per attivare), EZ_TTS_REMOTE_API_KEY (opzionale), EZ_TTS_REMOTE_MODEL (opzionale, per endpoint OpenAI-style). WebUI e gallery si comportano identiche. Vedi docker-compose.remote.yml e docs/BACKEND-REMOTO.md.

API

POST /api/tts

{"text": "...", "speaker": "Vivian", "language": "Italian", "instruct": "tono caldo", "save_gallery": false}

→ WAV bytes. save_gallery solo true dalla webui.

POST /v1/audio/speech (OpenAI-compat)

{"input": "...", "voice": "Vivian", "language": "Italian"}

→ WAV bytes, mai in gallery.

GET

• /api/voices — voci disponibili
• /api/status — modello, speakers, lingue, uptime
• /api/gallery — ultime 12 generazioni con opzioni usate
• /audio/<file> — file della gallery
• /health — stato

Integrazione Hermes

tts:
  provider: qwen3
  providers:
    qwen3:
      type: command
      command: '"C:/percorso/qwen_tts_client.py" --input {input_path} --output {output_path}'
      output_format: wav
      timeout: 300

MCP: vedi docs/MCP.md. Skill Hermes: local-tts-voice.

Struttura

qwen_server.py       server FastAPI (modello in VRAM, API, webui)
webui.html           UI voicechat (modificabile senza riavviare il server)
qwen_tts_client.py   client CLI per Hermes/agenti (play locale automatico)
qwen_tts_mcp.py      server MCP (tool qwen_tts_speak)
audio_daemon.py      coda di riproduzione FIFO (no overlap)
play_audio.py        accoda un file per il play locale
Dockerfile           CPU/GPU multi-target
docker-compose*.yml  CPU / GPU / remote overlay
requirements.txt
docs/                documentazione estesa
outputs/             gallery (volumizzata in docker)

Note

• Intel Arc / ZLUDA: ZLUDA è orientato AMD (ROCm) e non supporta le GPU Intel Arc (verificato 2026-08): sulla B50 Pro usare CPU oppure backend remoto.
• Il primo avvio scarica i pesi del modello (Hugging Face, ~1.2GB per la 0.6B).
• Generazione: ~10-40s per frase breve su RTX 4060 senza flash-attn (si usa SDPA).