Come Configurare la Modalità Vocale di Hermes Agent

Cosa Ti Serve Prima di Iniziare

La modalità vocale in Hermes Agent aggiunge un'intera pipeline audio sopra l'agente base: ingresso dal microfono, trascrizione speech-to-text, il ciclo di ragionamento standard e output text-to-speech. Ogni fase è personalizzabile, ma le impostazioni predefinite funzionano abbastanza bene da permetterti di iniziare in meno di dieci minuti.

Prerequisiti:

Un'installazione funzionante di Hermes Agent - esegui hermes e verifica che la chat testuale risponda prima di abilitare la voce
Un microfono collegato al tuo computer
Mac, Linux o Windows con WSL2 installato

Windows nativo non è supportato - su quella piattaforma è richiesto WSL2.

Passaggio 1 - Installa il Componente Aggiuntivo Vocale

pip install "hermes-agent[voice]"

Questo installa:

faster-whisper - speech-to-text locale (il backend STT predefinito)
sounddevice - acquisizione dal microfono e riproduzione audio
numpy - elaborazione audio

Il download è di circa 100-300 MB a seconda del tuo ambiente Python esistente.

Android/Termux: Il componente aggiuntivo vocale standard include dipendenze non compatibili con Android. Usa invece il componente aggiuntivo specifico per Termux:

pip install "hermes-agent[termux]"

Passaggio 2 - Verifica i Permessi del Microfono

Prima di abilitare la voce in Hermes, assicurati che il microfono sia accessibile dall'ambiente terminale.

Mac: Vai in Impostazioni di Sistema > Privacy e sicurezza > Microfono. Assicurati che la tua applicazione terminale (Terminal, iTerm2, Warp, ecc.) abbia il permesso di accedere al microfono.

Linux: Esegui arecord -l per elencare i dispositivi di registrazione. Se il tuo microfono non compare, verifica se PulseAudio o PipeWire è in esecuzione:

pulseaudio --check
# or
pactl info

WSL2 (Windows): L'accesso al microfono in WSL2 richiede un bridge PulseAudio dall'host Windows. L'approccio più comune è installare un server PulseAudio su Windows, poi configurare WSL2 per connettersi tramite la variabile d'ambiente PULSE_SERVER. Questo è il passaggio più impegnativo per gli utenti Windows - una volta che il bridge funziona, tutti i passaggi successivi sono identici a Linux.

Passaggio 3 - Abilita la Modalità Vocale

Avvia una sessione Hermes:

hermes

All'interno della sessione, esegui:

/voice on

Vedrai un messaggio di conferma. Premi Ctrl+B per iniziare a registrare, di' un breve messaggio, poi premi di nuovo Ctrl+B per fermarti (o aspetta il rilevamento del silenzio). Hermes trascriverà il tuo messaggio e risponderà.

Un terminale che mostra una sessione CLI di Hermes Agent con la modalità vocale attiva, un indicatore di registrazione in basso e una risposta trascritta sopra

Se l'agente risponde correttamente, la modalità vocale funziona. Continua con il passaggio 4 per configurare quali provider STT e TTS utilizzare. Se qualcosa non va, passa alla sezione risoluzione dei problemi.

Passaggio 4 - Configura lo Speech-to-Text

Il provider STT predefinito è faster-whisper che gira localmente sul tuo computer. Non è richiesta alcuna chiave API e nessun audio viene inviato a servizi esterni.

Il modello Whisper predefinito è base, che è abbastanza veloce e preciso per un parlato inglese chiaro. Per una maggiore precisione con accenti o lingue diverse dall'inglese, passa a un modello più grande:

# ~/.hermes/config.yaml
stt:
  provider: local
  model: small   # options: tiny, base, small, medium, large-v3

I modelli più grandi scambiano velocità per precisione. Su una CPU moderna, small aggiunge circa 1-2 secondi di latenza di trascrizione per una frase breve. Su una GPU, la differenza è trascurabile.

STT cloud (più veloce, senza calcolo locale):

stt:
  provider: groq   # or openai

Imposta la chiave in ~/.hermes/.env:

GROQ_API_KEY=your_groq_key
# or
VOICE_TOOLS_OPENAI_KEY=your_openai_key

L'inferenza Whisper di Groq è veloce e il piano gratuito gestisce un utilizzo consistente. Per messaggi vocali brevi - cattura di attività, ricerche rapide - lo STT cloud con Groq risponde spesso più velocemente dell'inferenza locale su CPU.

Passaggio 5 - Configura il Text-to-Speech

Il provider TTS predefinito è Edge TTS, che non richiede alcuna chiave API e produce un output dal suono naturale:

tts:
  provider: edge

Questo è sufficiente per la maggior parte degli usi personali. Per una panoramica completa di tutti i dieci provider TTS supportati e quando scegliere ciascuno, consulta la guida ai provider TTS di Hermes Agent.

Per gli utenti Telegram: Alcuni provider tra cui NeuTTS producono file WAV che devono essere convertiti in Opus per le note vocali di Telegram. Installa ffmpeg per abilitare la conversione automatica:

# Mac
brew install ffmpeg

# Linux
sudo apt install ffmpeg

Passaggio 6 - Imposta la Voce come Predefinita

Per evitare di eseguire /voice on all'inizio di ogni sessione, aggiungi questo a ~/.hermes/config.yaml:

voice_mode: true

L'agente si avvierà con la voce abilitata automaticamente da quel momento in poi.

Passaggio 7 - Test su Telegram (Opzionale)

Se hai un bot Telegram configurato, invia una nota vocale al tuo bot e conferma che risponda sia con testo che con una nota vocale. Se la nota vocale è assente, verifica che ffmpeg sia installato e che il tuo provider TTS sia configurato correttamente.

Risoluzione dei Problemi

Nessun output audio - l'agente risponde solo in testo

Verifica che tts.provider sia impostato in config.yaml e che tu abbia eseguito /voice on nella sessione corrente. In alternativa, imposta voice_mode: true per l'attivazione automatica.

Ctrl+B non fa nulla / microfono non rilevato

Controlla i permessi del microfono (Mac: Impostazioni di Sistema > Privacy > Microfono). Su Linux, esegui arecord -l e conferma che il tuo dispositivo compaia. Su WSL2, verifica che il bridge PulseAudio verso l'host Windows sia attivo.

La trascrizione è imprecisa o perde parole

Passa da base a small o medium in config.yaml. Il rumore di fondo degrada significativamente la trascrizione - un auricolare o un microfono direzionale fa una grande differenza in pratica.

Le note vocali di Telegram sono assenti o silenziose

Hermes invia audio codificato in Opus a Telegram. Se stai usando NeuTTS e ffmpeg non è installato, la conversione da WAV a Opus fallisce silenziosamente. Installa ffmpeg e riavvia il gateway.

La latenza di risposta è troppo alta

Per la configurazione più veloce: usa lo STT cloud (Groq) per la trascrizione e Edge TTS per l'output. La trascrizione Groq aggiunge meno di un secondo di latenza per i messaggi brevi. La sintesi Edge TTS è veloce e non richiede calcolo locale.

Un diagramma di flusso per la risoluzione dei problemi della pipeline vocale di Hermes che mostra le fasi STT, ragionamento e TTS con i punti di errore comuni evidenziati in ciascuna fase

Comprendere la Latenza in Ogni Fase

Sapere dove viene impiegato il tempo ti aiuta a ottimizzare in base al tuo caso d'uso:

Fase	Locale (tipico)	Cloud (tipico)
Trascrizione STT	1-4s (Whisper base/small)	0.5-1s (Groq)
Ragionamento agente	1-3s	1-3s
Sintesi TTS	0.5-2s	0.3-1s
Totale	2.5-9s	1.8-5s

Per un assistente personale, qualsiasi cosa sotto i 5 secondi sembra naturale. Per i canali vocali Discord in tempo reale, punta a meno di 3 secondi totali - usa STT cloud e un provider TTS veloce.

Salta Completamente la Configurazione

Il self-hosting di Hermes e la gestione della configurazione vocale è fattibile con questa guida, ma non è semplice su tutte le piattaforme - in particolare Windows. Se preferisci avere la voce funzionante subito, Hermify gestisce tutto questo automaticamente. Il tuo agente gira in un container isolato con Edge TTS preconfigurato, e Telegram si collega in due tap dalla dashboard. Nessun file di configurazione, nessun gateway da gestire.