Usar o modo de voz com o Hermes

Este guia é o companheiro prático da referência do recurso Modo de Voz.

Se a página do recurso explica o que o modo de voz consegue fazer, este guia mostra como usá-lo bem de verdade.

dica

O Nous Portal junta o LLM e o TTS num único OAuth — o modo de voz funciona de ponta a ponta sem credencial extra.

Para que o modo de voz é bom

O modo de voz é especialmente útil quando:

• você quer um fluxo de CLI sem usar as mãos
• você quer respostas faladas no Telegram ou no Discord
• você quer o Hermes sentado num canal de voz do Discord para conversa ao vivo
• você quer capturar ideias rápido, depurar ou trocar ideia enquanto anda por aí, em vez de digitar

Escolha a sua configuração de modo de voz

Na verdade existem três experiências de voz diferentes no Hermes.

Modo	Melhor para	Plataforma
Laço interativo de microfone	Uso pessoal sem as mãos enquanto você programa ou pesquisa	CLI
Respostas faladas no chat	Respostas faladas junto com as mensagens normais	Telegram, Discord
Bot de canal de voz ao vivo	Conversa ao vivo, em grupo ou pessoal, num canal de voz	Canais de voz do Discord

Um bom caminho é:

1. deixar o texto funcionando primeiro
2. habilitar as respostas faladas em segundo lugar
3. ir para os canais de voz do Discord por último, se você quiser a experiência completa

Passo 1: garanta que o Hermes normal funciona antes

Antes de encostar no modo de voz, verifique que:

• o Hermes inicia
• o seu provedor está configurado
• o agente consegue responder prompts de texto normalmente

hermes

Peça algo simples:

Quais ferramentas você tem disponíveis?

Se isso ainda não está firme, arrume o modo de texto primeiro.

Passo 2: instale os extras certos

Microfone + reprodução na CLI

cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"

Plataformas de mensagens

cd ~/.hermes/hermes-agent && uv pip install -e ".[messaging]"

TTS premium da ElevenLabs

cd ~/.hermes/hermes-agent && uv pip install -e ".[tts-premium]"

NeuTTS local (opcional)

python -m pip install -U neutts[all]

Tudo

cd ~/.hermes/hermes-agent && uv pip install -e ".[all]"

Passo 3: instale as dependências de sistema

macOS

brew install portaudio ffmpeg opus
brew install espeak-ng

Ubuntu / Debian

sudo apt install portaudio19-dev ffmpeg libopus0
sudo apt install espeak-ng

Por que elas importam:

• portaudio → entrada de microfone / reprodução para o modo de voz na CLI
• ffmpeg → conversão de áudio para TTS e entrega em mensagens
• opus → suporte ao codec de voz do Discord
• espeak-ng → backend de fonemização para o NeuTTS

Passo 4: escolha os provedores de STT e TTS

O Hermes suporta pilhas de fala locais e na nuvem.

Configuração mais fácil / mais barata

Use STT local e o Edge TTS gratuito:

• provedor de STT: local
• provedor de TTS: edge

Em geral, é o melhor lugar para começar.

Exemplo de arquivo de ambiente

Acrescente ao ~/.hermes/.env:

# Opções de STT na nuvem (o local não precisa de chave)
GROQ_API_KEY=***
VOICE_TOOLS_OPENAI_KEY=***

# TTS premium (opcional)
ELEVENLABS_API_KEY=***

Recomendações de provedor

Fala para texto

• local → melhor padrão para privacidade e uso sem custo
• groq → transcrição na nuvem muito rápida
• openai → boa alternativa paga

Texto para fala

• edge → gratuito e bom o bastante para a maioria das pessoas
• neutts → TTS local/no dispositivo, gratuito
• elevenlabs → melhor qualidade
• openai → bom meio-termo
• mistral → multilíngue, Opus nativo

Se você usa o hermes setup

Se você escolhe o NeuTTS no assistente de configuração, o Hermes confere se o neutts já está instalado. Se está faltando, o assistente avisa que o NeuTTS precisa do pacote Python neutts e do pacote de sistema espeak-ng, oferece instalar os dois para você, instala o espeak-ng com o gerenciador de pacotes da sua plataforma e depois roda:

python -m pip install -U neutts[all]

Se você pula essa instalação ou ela falha, o assistente cai no Edge TTS.

Passo 5: configuração recomendada

voice:
  record_key: "ctrl+b"
  submit_mode: "direct"  # TUI: direct | draft
  max_recording_seconds: 120
  auto_tts: false
  beep_enabled: true
  silence_threshold: 200
  silence_duration: 3.0

stt:
  provider: "local"
  local:
    model: "base"

tts:
  provider: "edge"
  edge:
    voice: "en-US-AriaNeural"

Este é um bom padrão conservador para a maioria das pessoas.

Na TUI, o voice.submit_mode controla o que acontece depois da transcrição:

• direct (padrão) envia a transcrição na hora.
• draft coloca a transcrição no compositor, para você editar ou cancelar antes de apertar Enter.

Para rascunhos de voz editáveis, defina:

voice:
  submit_mode: "draft"

Se você prefere TTS local, troque o bloco tts por:

tts:
  provider: "neutts"
  neutts:
    ref_audio: ''
    ref_text: ''
    model: neuphonic/neutts-air-q4-gguf
    device: cpu

Caso de uso 1: modo de voz na CLI

Ligue

Inicie o Hermes:

hermes

Dentro da CLI:

/voice on

Fluxo de gravação

Tecla padrão:

• Ctrl+B

Fluxo:

1. aperte Ctrl+B
2. fale
3. espere a detecção de silêncio parar a gravação automaticamente
4. o Hermes transcreve e responde
5. se o TTS está ligado, ele fala a resposta
6. o laço pode reiniciar automaticamente, para uso contínuo

Comandos úteis

/voice
/voice on
/voice off
/voice tts
/voice status

Bons fluxos na CLI

Depurar de pé

Diga:

Estou tomando um erro de permissão do docker sem parar. Me ajude a depurar.

Depois continue sem usar as mãos:

• "Leia o último erro de novo"
• "Explique a causa raiz em termos mais simples"
• "Agora me dê a correção exata"

Pesquisa / tempestade de ideias

Ótimo para:

• andar por aí enquanto pensa
• ditar ideias pela metade
• pedir ao Hermes que estruture os seus pensamentos em tempo real

Acessibilidade / sessões com pouca digitação

Se digitar é inconveniente, o modo de voz é um dos jeitos mais rápidos de continuar dentro do laço completo do Hermes.

Ajustar o comportamento na CLI

Limiar de silêncio

Se o Hermes começa/para de forma agressiva demais, ajuste:

voice:
  silence_threshold: 250

Limiar mais alto = menos sensível.

Duração do silêncio

Se você faz muitas pausas entre frases, aumente:

voice:
  silence_duration: 4.0

Tecla de gravação

Se o Ctrl+B conflita com os seus hábitos de terminal ou de tmux:

voice:
  record_key: "ctrl+space"

Caso de uso 2: respostas faladas no Telegram ou no Discord

Este modo é mais simples que os canais de voz completos.

O Hermes continua sendo um bot de chat normal, mas pode falar as respostas.

Suba o gateway

hermes gateway

Ligue as respostas faladas

Dentro do Telegram ou do Discord:

/voice on

ou

/voice tts

Modos

Modo	Significado
off	só texto
voice_only	fala só quando o usuário mandou voz
all	fala toda resposta

Quando usar cada modo

• /voice on se você quer respostas faladas só para mensagens que vieram por voz
• /voice tts se você quer um assistente falado o tempo todo

Bons fluxos em mensagens

Assistente do Telegram no seu celular

Use quando:

• você está longe da sua máquina
• você quer mandar notas de voz e receber respostas faladas rápidas
• você quer o Hermes funcionando como um assistente portátil de pesquisa ou de operação

DMs do Discord com saída falada

Útil quando você quer interação privada, sem o comportamento de menção dos canais de servidor.

Caso de uso 3: canais de voz do Discord

Este é o modo mais avançado.

O Hermes entra num canal de voz do Discord, escuta a fala das pessoas, transcreve, roda o pipeline normal do agente e fala as respostas de volta no canal.

Permissões necessárias no Discord

Além da configuração normal de bot de texto, garanta que o bot tem:

• Connect
• Speak
• de preferência Use Voice Activity

Habilite também os intents privilegiados no Developer Portal:

• Presence Intent
• Server Members Intent
• Message Content Intent

Entrar e sair

Num canal de texto do Discord onde o bot está presente:

/voice join
/voice leave
/voice status

O que acontece depois de entrar

• as pessoas falam no canal de voz
• o Hermes detecta as fronteiras da fala
• as transcrições são publicadas no canal de texto associado
• o Hermes responde em texto e em áudio
• o canal de texto é aquele onde o /voice join foi disparado

Boas práticas para uso em canal de voz do Discord

• mantenha o DISCORD_ALLOWED_USERS apertado
• use um canal de bot/testes dedicado no começo
• verifique se o STT e o TTS funcionam no modo de voz do chat de texto comum antes de tentar o modo de canal de voz

Recomendações de qualidade de voz

Configuração de melhor qualidade

• STT: large-v3 local ou whisper-large-v3 da Groq
• TTS: ElevenLabs

Configuração de melhor velocidade / conveniência

• STT: base local ou Groq
• TTS: Edge

Configuração de custo zero

• STT: local
• TTS: Edge

Modos de falha comuns

"No audio device found"

Instale o portaudio.

"O bot entra mas não escuta nada"

Confira:

• se o seu ID de usuário do Discord está no DISCORD_ALLOWED_USERS
• se você não está mudo
• se os intents privilegiados estão habilitados
• se o bot tem as permissões Connect/Speak

"Ele transcreve mas não fala"

Confira:

• a configuração do provedor de TTS
• a chave de API / a cota da ElevenLabs ou da OpenAI
• a instalação do ffmpeg para os caminhos de conversão do Edge

"O Whisper cospe lixo"

Tente:

• um ambiente mais silencioso
• um silence_threshold mais alto
• outro provedor/modelo de STT
• falas mais curtas e mais claras

"Funciona em DMs mas não em canais de servidor"

Isso costuma ser política de menção.

Por padrão, o bot precisa de uma @menção nos canais de texto de servidor do Discord, a menos que você configure de outro jeito.

Configuração sugerida para a primeira semana

Se você quer o caminho mais curto até o sucesso:

1. deixe o Hermes de texto funcionando
2. rode hermes setup tts para habilitar o suporte a voz
3. use o modo de voz na CLI com STT local + Edge TTS
4. depois habilite o /voice on no Telegram ou no Discord
5. só então tente o modo de canal de voz do Discord

Essa progressão mantém pequena a superfície de depuração.

O que ler depois

• Referência do recurso Modo de Voz
• Gateway de mensagens
• Configuração do Discord
• Configuração do Telegram
• Configuração

---