Qwen3-TTS in locale: sintesi vocale e voci clonata

#Perché Qwen3-TTS invece di una voce cloud

I servizi di sintesi vocale online suonano bene, ma ogni frase che affidi loro lascia la tua macchina, viene fatturata a carattere e dipende da un account che può essere chiuso. Per un lettore di documenti interni, un assistente domotico o un prototipo di applicazione, una voce che funziona interamente in locale elimina tutte e tre queste dipendenze in un colpo solo.

Nell'ecosistema open source finora coesistevano due famiglie. Da un lato, modelli molto leggeri come Piper o Kokoro: veloci sul processore, voci fisse, nessun clonaggio. Dall'altro, modelli più pesanti ed espressivi, spesso incentrati sull'inglese e sul cinese. Qwen3-TTS si colloca tra i due: pesi compatti, ma un'architettura di tipo LLM che accetta istruzioni di stile in linguaggio naturale e un supporto esplicito del francese fin dal lancio.

La particolarità della famiglia è essere suddivisa in tre comportamenti, anziché in un unico modello universale. Scarichi solo la variante corrispondente alle tue esigenze, aspetto importante su una GPU da 8 o 12 GB condivisa con un LLM testuale.

#Modelli disponibili: Base, CustomVoice, VoiceDesign

Au lancement, la famille comprend deux tailles de modèle, 0,6 et 1,7 milliard de paramètres, déclinées en trois variantes fonctionnelles, plus un tokenizer audio partagé. Les identifiants Hugging Face suivent le motif Qwen/Qwen3-TTS-12Hz-<dimensione>-<variante>. Le « 12Hz » désigne la fréquence du codec audio: le modèle produit douze trames de jetons acoustiques par seconde de parole, ce qui explique sa frugalité en calcul par rapport à des codecs plus denses.

CustomVoice

Voci predefinite, ciascuna con un timbro e una lingua d'origine, controllabili tramite un'istruzione di stile («parla lentamente, con tono rassicurante»). È la variante da scegliere per leggere un testo senza doversi preoccupare della voce. Disponibile in 0,6B e 1,7B.

VoiceDesign

Descrivi la voce desiderata in linguaggio naturale (età, genere percepito, energia, accento, emozione) e il modello la inventa. Nessuna registrazione di riferimento, quindi nessuna persona reale imitata. Pubblicata in 1,7B.

Base

Clonaggio a partire da un estratto audio di pochi secondi e dalla sua trascrizione. È la variante più potente e l'unica che solleva una questione di consenso, trattata più avanti. Disponibile in 0,6B e 1,7B.

Tokenizer-12Hz

Il codec audio che codifica e decodifica il parlato. Viene scaricato automaticamente dalle varianti sopra; devi gestirlo solo in caso di utilizzo avanzato.

Le lingue dichiarate sono il cinese, l'inglese, il giapponese, il coreano, il tedesco, il francese, il russo, il portoghese, lo spagnolo e l'italiano, oltre a diversi dialetti cinesi. Il parametro della lingua accetta un nome esplicito come «French» oppure «Auto» per lasciare che il modello rilevi la lingua del testo. Per il francese, forzare il valore evita esitazioni nella pronuncia di nomi propri e anglicismi.

#Requisiti hardware e software

Sistema

Linux x86_64 è la piattaforma di riferimento documentata dal repository. macOS e Windows sono possibili, con le riserve dettagliate nella sezione dedicata.

GPU

Una scheda NVIDIA con CUDA è la soluzione prevista. Una RTX 3060 da 12 GB è più che sufficiente per la sola 1,7B; l'esecuzione sul processore funziona per provare una frase, ma non è adatta a un uso interattivo.

Python

Il repository consiglia Python 3.12 in un ambiente virtuale dedicato. Evita di installare nel sistema o nell'ambiente di un altro progetto audio: le versioni di PyTorch e transformers richieste dal pacchetto potrebbero entrare in conflitto.

Spazio su disco

Metti in conto pochi gigabyte per ogni variante scaricata, nella cache di Hugging Face (~/.cache/huggingface per impostazione predefinita).

Rete

Solo al primo avvio, per scaricare i pesi. Dopodiché, tutto funziona offline.

Un ultimo prerequisito non è tecnico: se intendi usare la variante Base, procurati una registrazione di cui hai il diritto di utilizzare la voce. La tua voce è il caso più semplice e sicuro per imparare.

#Passaggio 1: installare il pacchetto qwen-tts

Il pacchetto Python ufficiale si chiama qwen-tts su PyPI e viene importato con il nome qwen_tts. Installa PyTorch e transformers come dipendenze. L'installazione qui sotto usa un ambiente virtuale standard; anche conda funziona bene, se è quello che usi di solito.

# Environnement isolé
python3.12 -m venv ~/qwen3-tts
source ~/qwen3-tts/bin/activate
pip install --upgrade pip

# Paquet officiel
pip install -U qwen-tts

# Lecture et écriture de fichiers audio pour les exemples
pip install soundfile

Il repository offre facoltativamente FlashAttention 2 per accelerare l'inferenza sulle GPU recenti. La compilazione è lunga e non riesce con alcune combinazioni CUDA/PyTorch. Non è indispensabile: senza di essa, il modello utilizza l'attenzione standard di PyTorch. Installala solo quando il resto funziona.

pip install -U flash-attn --no-build-isolation

Verifica che import passe e che PyTorch rilevi correttamente la tua GPU prima di procedere.

python -c "import torch, qwen_tts; print(torch.__version__, torch.cuda.is_available())"

#Passaggio 2: generare una prima frase in francese con Qwen3-TTS

La variante CustomVoice è la più diretta per una prima prova: nessuna registrazione di riferimento, nessuna descrizione da scrivere. Si carica il modello, si sceglie una voce dall'elenco del repository, poi si passano il testo e la lingua. La prima chiamata scarica i pesi da Hugging Face.

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_custom_voice(
    text="Bonjour, ceci est un test de synthèse vocale locale avec Qwen3-TTS.",
    language="French",
    speaker="Ryan",
    instruct="Ton calme et posé, débit modéré.",
)

sf.write("sortie_custom_voice.wav", wavs[0], sr)
print("Fichier écrit à", sr, "Hz")

Tre parametri meritano una spiegazione. Il campo speaker indica una delle voci predefinite; l'elenco esatto, con la lingua d'origine e la descrizione di ciascun timbro, figura nel README e nella scheda Hugging Face del modello CustomVoice. Tutte queste voci possono leggere testi in francese, ma ciascuna conserva un accento coerente con la propria lingua madre: è una scelta estetica, non un difetto. Il campo instruct è un'istruzione di stile in linguaggio naturale: emozione, ritmo, intenzione. È facoltativo. Infine, la funzione restituisce un elenco di forme d'onda e la frequenza di campionamento, permettendo di elaborare più testi in batch.

textes = [
    "Première phrase à lire.",
    "Deuxième phrase, avec une intonation différente.",
]
wavs, sr = model.generate_custom_voice(
    text=textes,
    language=["French", "French"],
    speaker=["Ryan", "Serena"],
    instruct=["Neutre.", "Enjouée, un peu plus rapide."],
)
for i, w in enumerate(wavs):
    sf.write(f"lot_{i}.wav", w, sr)

#Passaggio 3: progettare una voce tramite descrizione

VoiceDesign risponde a un'esigenza frequente: vuoi una voce che non compare nell'elenco, senza imitare nessuno. Descrivi il risultato in una o due frasi e il modello produce un timbro coerente con l'istruzione. È anche la variante da preferire per un prodotto, poiché non viene riprodotta alcuna voce reale.

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_voice_design(
    text="Votre rendez-vous est confirmé pour demain à quatorze heures.",
    language="French",
    instruct="Voix féminine d'une quarantaine d'années, grave et chaleureuse, "
             "articulation nette, rythme lent, sans emphase.",
)

sf.write("sortie_voice_design.wav", wavs[0], sr)

La descrizione funziona meglio quando descrive caratteristiche acustiche (altezza, velocità, energia, nitidezza) invece di metafore. «Voce di un presentatore radiofonico notturno» dà risultati meno stabili di «voce maschile profonda, lenta e vellutata». Una voce progettata in questo modo non è fissa da una chiamata all'altra: se ti serve la stessa voce per centinaia di frasi, genera un primo estratto che ti soddisfa, poi usalo come riferimento con la variante Base. In questo modo cloni una voce sintetica, quindi non ci sono problemi di consenso.

#Passaggio 4: clonare una voce, con il consenso del suo proprietario

La variante Base riproduce un timbro a partire da un breve estratto audio e dalla sua trascrizione. Bastano pochi secondi di parlato pulito per ottenere una voce riconoscibile. È la funzione più impressionante della famiglia e quella che richiede maggiore rigore ancor prima di scrivere una riga di codice.

Per preparare il riferimento, registra una frase da cinque a dieci secondi in un luogo tranquillo, senza musica di sottofondo né riverbero, parlando in modo naturale. Trascrivila parola per parola, inclusa la punteggiatura: è questo il testo che il modello allinea all'audio per apprendere il timbro. Un file WAV mono è il formato più sicuro.

import torch
import soundfile as sf
from qwen_tts import Qwen3TTSModel

model = Qwen3TTSModel.from_pretrained(
    "Qwen/Qwen3-TTS-12Hz-1.7B-Base",
    device_map="cuda:0",
    dtype=torch.bfloat16,
)

wavs, sr = model.generate_voice_clone(
    text="Voici une phrase que je n'ai jamais prononcée, lue avec ma propre voix.",
    language="French",
    ref_audio="ma_reference.wav",
    ref_text="Bonjour, je m'appelle Thomas et j'enregistre cette phrase pour tester le clonage.",
)

sf.write("sortie_clone.wav", wavs[0], sr)

Il repository documenta due utilizzi avanzati utili in produzione. Innanzitutto, la possibilità di precalcolare una «impronta» della voce di riferimento una volta per tutte, per poi riutilizzarla per ogni frase senza ricaricare l'audio: è ciò che serve per un lettore di documenti o un assistente che parla in modo continuativo. Inoltre, una modalità in cui viene utilizzata solo l'impronta del parlante, senza la trascrizione: è più rapida, ma meno fedele. I nomi esatti di questi parametri sono riportati nel README; sono cambiati tra le prime versioni del pacchetto, da qui l'importanza di leggere la documentazione installata anziché un tutorial datato.

Cosa migliora il risultato

Un riferimento pulito, una trascrizione esatta, una lingua impostata anziché « Auto » e un testo di destinazione con la punteggiatura (il modello prende fiato alle virgole e ai punti).

Cosa lo peggiora

Rumore di fondo, un riferimento troppo breve o troppo lungo, un sussurro, una trascrizione approssimativa e cifre scritte in numeri anziché in lettere nei casi ambigui.

Cosa documentare

Chi ha dato il proprio consenso, per quale uso, in quale data e dove viene conservata la registrazione. Per un progetto personale basta un semplice file di testo accanto al riferimento; per un uso professionale serve un vero registro dei trattamenti.

#Passaggio 5: interfaccia web e server

Il pacchetto installa una demo Gradio dalla riga di comando, pratica per provare le voci e le istruzioni senza scrivere uno script. Carica un modello all'avvio ed espone una pagina web locale.

qwen-tts-demo Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --ip 127.0.0.1 --port 8000

Mantenete l'indirizzo di ascolto su 127.0.0.1 finché la macchina non è protetta: Gradio non autentica nessuno per impostazione predefinita e un'interfaccia di clonazione vocale esposta su una rete non è una cosa da prendere alla leggera. Se dovete accedervi da un'altra postazione, usate un tunnel SSH o un reverse proxy con autenticazione, come per qualsiasi servizio locale.

Per un'integrazione applicativa, il team Qwen consiglia vLLM-Omni, l'estensione multimodale di vLLM, che permette di servire il modello con un'API HTTP e un'uscita in streaming (l'audio inizia a essere riprodotto prima che la generazione sia terminata). È la strada da valutare per un assistente vocale in cui la latenza è importante; per la generazione in batch di file audio, lo script Python diretto è sufficiente ed evita un ulteriore livello.

#Apple Silicon e Windows: percorsi della comunità, indicati come tali

Il repository ufficiale documenta Linux con CUDA. Sulle altre piattaforme, quanto segue appartiene all'ecosistema della comunità: non abbiamo verificato personalmente questi percorsi e il loro stato cambia di mese in mese.

Mac Apple Silicon

Il pacchetto ufficiale si basa su PyTorch; puoi provare device_map="mps" con dtype float16 o float32 (bfloat16 non è sempre supportato da MPS), mettendo in conto operazioni non supportate. Su Mac la soluzione più naturale è un porting MLX: il progetto della community mlx-audio ha annunciato il supporto a Qwen3-TTS. Controlla nel repository quali varianti sono coperte e con quale livello di maturità prima di impegnarti.

Windows nativo

PyTorch con CUDA si installa normalmente, ma FlashAttention è difficile da compilare su Windows: lascialo da parte e usa l'attenzione predefinita. Alcune dipendenze audio richiedono binari di sistema (per esempio ffmpeg nel PATH). Circolano installatori di terze parti « con un clic »; spesso includono una versione bloccata del pacchetto, quindi leggi cosa installano.

Windows tramite WSL2

È la strada più vicina alla documentazione ufficiale: una distribuzione Ubuntu sotto WSL2 con il driver NVIDIA Windows recente rileva la GPU e segue esattamente i comandi di questa guida. Il costo è un ulteriore livello e un accesso ai file Windows leggermente più lento.

#Risoluzione dei problemi

CUDA out of memory durante il caricamento

Un altro processo sta occupando la scheda (Ollama, un browser con accelerazione, una sessione di Stable Diffusion). Verifica con nvidia-smi, libera memoria oppure passa alla variante 0,6B.

Download interrotto o repository non trovato

Verifica l'identificativo esatto del modello sulla pagina Hugging Face dell'organizzazione Qwen; i nomi delle varianti potrebbero essere cambiati rispetto alla stesura. Un download parziale riprende rilanciando lo script.

Errore di import liée in transformers o torch

Conflitto di versioni con un altro progetto installato nello stesso ambiente. Ricrea un ambiente virtuale pulito e reinstalla solo qwen-tts e soundfile.

Pronuncia strana in francese

Impostate language="French" invece di «Auto», scrivete i numeri in lettere quando la lettura è ambigua e usate la punteggiatura. Le sigle si leggono meglio se separate da punti o spazi.

Il clone non assomiglia al riferimento

Registra nuovamente il riferimento in un ambiente silenzioso, verifica la trascrizione parola per parola e prova la 1,7B se stavi usando la 0,6B. Un estratto troppo lungo non aiuta: pochi secondi di parlato nitido valgono più di un minuto rumoroso.

Silenzio o file vuoto

Verificate di scrivere correttamente wavs[0] e non l'intera lista, e che la frequenza di campionamento restituita dal modello sia quella passata a soundfile.

Lentezza estrema

Probabilmente il modello gira sulla CPU. Il test torch.cuda.is_available() del passaggio 1 deve restituire True; altrimenti reinstalla PyTorch con la versione CUDA corrispondente al tuo driver.

#Per approfondire

Qwen3-TTS copre la parte del « parlare » di una catena vocale locale. Per l'altra metà, la comprensione, e per confrontare modelli di sintesi più leggeri, il sito tratta già diversi argomenti affini. Le versioni dei pacchetti e dei modelli citati in questa guida sono quelle del repository QwenLM/Qwen3-TTS al momento della stesura; in caso di discrepanze, fanno fede il repository e le schede Hugging Face.

Kokoro TTS: una voce locale convincente e leggera

Il modello da 82 milioni di parametri che parla più velocemente del tempo reale su processore, senza clonazione. La scelta giusta quando la frugalità viene prima dell'espressività. https://quelllm.fr/guide/kokoro-tts-voix-locale

Assistente vocale 100 % locale: Whisper + Ollama + Piper

La catena completa: ascolto, ragionamento, risposta parlata. Qwen3-TTS può sostituire Piper per la sintesi, se la tua GPU lo consente. https://quelllm.fr/guide/assistant-vocal-local-whisper-piper

Scheda del modello Voxtral 4B TTS

L'altro recente modello europeo open-source di sintesi vocale, per collocare Qwen3-TTS nel panorama senza un confronto numerico. https://quelllm.fr/modele/voxtral-4b-tts