bdi_podman_serverconf/containers/qwentts/qwentts.README

# Qwentts - Text-to-Speech with Voice Cloning and Voice Design

C++17 port di Qwen3-TTS (Alibaba/Qwen team) con supporto per Text-to-Speech, voice cloning zero-shot e voice design. Supporta 10+ lingue con dialetti Mandarin e output 24 kHz mono.

## Requisiti

- Podman rootless
- Network `internal.network` configurata
- Nginx come reverse proxy
- GPU AMD con Vulkan (opzionale, consigliato)
- Spazio disco: almeno 30 GB per i modelli
- RAM: 16+ GB per il modello 1.7B
- Dipendenze di compilazione (cmake, git, gcc, vulkan-dev)

## Build Container

### 1. Compilare qwentts.cpp

```bash
cd /home/badstorm/Source/bdi/bdi_podman_serverconf/containers/qwentts
./build-container.sh
```

Lo script:
- Installa dipendenze (cmake, git, vulkan-dev, glslc, spirv-tools)
- Clona qwentts.cpp con submoduli ricorsivi
- Compila con `./buildvulkan.sh` per supporto Vulkan
- Copia i binari (`qwen-tts`, `qwen-codec`) in `bin-vulkan/`
- Crea l'entrypoint script

### 2. Buildare l'immagine Podman

```bash
podman build -t qwentts:vulkan-amd64 -f qwentts-vulkan.Containerfile .
```

### 3. Verificare l'immagine

```bash
podman images | grep qwentts
podman run --rm qwentts:vulkan-amd64 --help
```

## Setup Runtime

### 1. Creare le directory di dati

```bash
mkdir -p /srv/containers/qwentts/models
mkdir -p /srv/containers/qwentts/output
chmod 755 /srv/containers/qwentts
chmod 755 /srv/containers/qwentts/models
chmod 755 /srv/containers/qwentts/output
```

### 2. Scaricare i modelli

I modelli pre-convertiti sono disponibili su Hugging Face: https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF

Scarica almeno un modello talker e il tokenizer:

```bash
cd /srv/containers/qwentts/models
pip install huggingface-hub

# Download Base Model (1.7B, default voice)
huggingface-cli download Serveurperso/Qwen3-TTS-GGUF \
  qwen-talker-1.7b-base-Q8_0.gguf \
  qwen-tokenizer-12hz-Q8_0.gguf \
  --local-dir .

# Optional: Download CustomVoice Model (named speakers)
huggingface-cli download Serveurperso/Qwen3-TTS-GGUF \
  qwen-talker-1.7b-customvoice-Q8_0.gguf \
  --local-dir .

# Optional: Download VoiceDesign Model (voice attributes)
huggingface-cli download Serveurperso/Qwen3-TTS-GGUF \
  qwen-talker-1.7b-voicedesign-Q8_0.gguf \
  --local-dir .

# Optional: Smaller 0.6B models for faster inference
huggingface-cli download Serveurperso/Qwen3-TTS-GGUF \
  qwen-talker-0.6b-base-Q8_0.gguf \
  --local-dir .
```

**Opzioni di quantizzazione disponibili:**
- `Q8_0` - Nessuna perdita di qualità, ~50% riduzione dimensione
- `Q4_K_M` - Quantizzazione mista, miglior rapporto qualità/dimensione
- `F32` - Massima qualità, dimensione massima

### 3. Copiare il file quadlet

```bash
cp qwentts.container ~/.config/containers/systemd/
```

### 4. Configurare il dominio

Modifica il file `~/.config/containers/systemd/qwentts.container` se necessario:
- Volumi di modelli e output
- Limiti di memoria (attualmente 16GB)
- Limiti CPU

### 5. Copiare la configurazione Nginx

```bash
cp qwentts.nginx /etc/nginx/conf.d/qwentts.conf
```

Modifica il file per sostituire:
- `qwentts.example.com` con il tuo dominio reale
- Percorsi SSL (standard Let's Encrypt)

### 6. Configurare SSL

```bash
sudo certbot certonly --standalone -d qwentts.tuodominio.com
```

### 7. Riavviare Nginx

```bash
sudo systemctl reload nginx
# oppure per container nginx:
systemctl --user restart nginx
```

### 8. Avviare Qwentts

```bash
systemctl --user daemon-reload
systemctl --user start qwentts
systemctl --user enable qwentts
```

## Verifica

Controlla che il container sia in esecuzione:

```bash
podman ps | grep qwentts
podman logs qwentts
```

## Utilizzo CLI

Qwentts fornisce due tool CLI: `qwen-tts` per la sintesi e `qwen-codec` per la gestione codec.

### Text-to-Speech Base (voce predefinita)

```bash
echo "Hello, this is a test." | podman exec qwentts qwen-tts \
  --model /app/models/qwen-talker-1.7b-base-Q8_0.gguf \
  --codec /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --lang English \
  -o /app/output/test.wav
```

### Voice Cloning (Zero-Shot)

**Opzione 1: Usa WAV + Testo di riferimento**

```bash
echo "I am cloning this voice." | podman exec qwentts qwen-tts \
  --model /app/models/qwen-talker-1.7b-base-Q8_0.gguf \
  --codec /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --ref-wav /app/output/reference.wav \
  --ref-text "This is my reference voice sample" \
  --lang English \
  -o /app/output/cloned.wav
```

**Opzione 2: Pre-encode il riferimento (più efficiente)**

```bash
# Estrai speaker embedding e codici
podman exec qwentts qwen-codec \
  --model /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --talker /app/models/qwen-talker-1.7b-base-Q8_0.gguf \
  -i /app/output/reference.wav

# Sintetizza usando i file pre-encodati
echo "Now I can synthesize with this voice." | podman exec qwentts qwen-tts \
  --model /app/models/qwen-talker-1.7b-base-Q8_0.gguf \
  --codec /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --ref-spk /app/output/reference.spk \
  --ref-rvq /app/output/reference.rvq \
  --ref-text "This is my reference voice sample" \
  --lang English \
  -o /app/output/synthesized.wav
```

### Named Speakers (CustomVoice Mode)

Voci predefinite disponibili: serena, vivian, uncle_fu, ryan, aiden, ono_anna, sohee, eric (dialetto sichuan), dylan (dialetto beijing)

```bash
echo "Hello from a named speaker." | podman exec qwentts qwen-tts \
  --model /app/models/qwen-talker-1.7b-customvoice-Q8_0.gguf \
  --codec /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --speaker vivian \
  --lang English \
  -o /app/output/vivian.wav
```

### Voice Design (Attributi di Voce)

Descrivi gli attributi della voce desiderata in testo libero:

```bash
echo "A very friendly and warm conversation starter." | podman exec qwentts qwen-tts \
  --model /app/models/qwen-talker-1.7b-voicedesign-Q8_0.gguf \
  --codec /app/models/qwen-tokenizer-12hz-Q8_0.gguf \
  --instruct "female, young adult, cheerful, moderate pitch" \
  --lang English \
  -o /app/output/designed.wav
```

Esempi di descrizioni:
- "male, professional, deep voice, authoritative"
- "female, elderly, warm and nurturing"
- "non-binary, young, energetic and upbeat"
- "child, playful, high-pitched, innocent"

## Lingue Supportate

- English
- Mandarin (Standard)
- Mandarin Sichuan (eric speaker)
- Mandarin Beijing (dylan speaker)
- Cantonese
- Japanese
- Korean
- Spanish
- French
- German
- Russian
- And more...

Specifica con il flag `--lang`

## Modelli Disponibili

### Base Mode (Voce predefinita)
- **Size**: 1.7B o 0.6B
- **Quantization**: Q8_0, Q4_K_M, F32
- **Caratteristiche**: Voce singola fissa, voice cloning
- **Use case**: Sintesi rapida con voice cloning da riferimento

### CustomVoice Mode (Altoparlanti nominati)
- **Speakers**: 8 voci predefinite con nomi e dialetti
- **Size**: 1.7B
- **Caratteristiche**: Scelta rapida tra voci note
- **Use case**: Produzione di contenuto con voci consistenti

### VoiceDesign Mode (Attributi di voce)
- **Size**: 1.7B
- **Caratteristiche**: Sintesi controllata via attributi in testo libero
- **Use case**: Creazione di voci custom con prompt descrittivi

### Dimensioni Modelli

| Modello | Dimensione (F32) | Q8_0 | Q4_K_M | RTF (GPU) |
|---------|-----------------|------|--------|-----------|
| 0.6B | 2.4 GB | 1.2 GB | 0.6 GB | < 0.5x |
| 1.7B | 6.8 GB | 3.4 GB | 1.7 GB | < 1.0x |

RTF = Real-Time Factor (< 1.0 significa più veloce del tempo reale)

## Performance

### Benchmark (Estimated)

**CPU (AMD Ryzen 9950X3D):**
- Sintesi 10 secondi: ~2-5 secondi

**GPU (NVIDIA A100 o AMD GPU equivalente con Vulkan):**
- Sintesi 10 secondi: < 1 secondo

### Ottimizzazione

Per migliore performance:
1. Usa modello 0.6B per latenza bassa
2. Usa quantizzazione Q8_0 o superiore
3. Pre-encode i riferimenti con `qwen-codec --talker` per voice cloning
4. Aumenta memoria allocata nel quadlet se disponibile

## Troubleshooting

### Build falls con dipendenze mancanti
```bash
# Esegui con sudo
sudo ./build-container.sh
```

### Vulkan non disponibile su container
```bash
# Verifica driver Vulkan
podman run --rm --device=/dev/dri --device=/dev/kfd ghcr.io/library/debian:13-slim vulkaninfo
```

### Modelli non trovati
```bash
# Verifica volume mounting
podman exec qwentts ls -la /app/models
```

### Memory issues
Se il container crasha per memoria:
```bash
# Aumenta memoria nel quadlet (attualmente 16GB)
# Oppure usa quantizzazione Q4_K_M per ridurre consumo
```

### Sintesi lenta
- Verifica che Vulkan sia attivo
- Usa modello 0.6B
- Aumenta CPUQuota nel quadlet
- Verifica che /dev/dri e /dev/kfd siano accessibili

## Aggiornamento

Per aggiornare a una versione più recente di qwentts.cpp:

```bash
# Ricompila
./build-container.sh

# Rebuild immagine
podman build -t qwentts:vulkan-amd64 -f qwentts-vulkan.Containerfile .

# Riavvia container
systemctl --user restart qwentts
```

## References

- [Qwentts.cpp GitHub](https://github.com/ServeurpersoCom/qwentts.cpp)
- [Models on Hugging Face](https://huggingface.co/Serveurperso/Qwen3-TTS-GGUF)
- [Qwen3-TTS Documentation](https://docs.qwenlm.ai/)
- [Architecture & API Reference](https://github.com/ServeurpersoCom/qwentts.cpp/blob/master/docs/ARCHITECTURE.md)