Palavra de ativação ("Hey Hermes")

A palavra de ativação transforma o Hermes num assistente sem mãos na CLI, na TUI e no aplicativo desktop: com uma configuração ligada, o Hermes escuta em segundo plano esperando uma frase de gatilho falada. Fale a frase e o Hermes abre uma sessão nova, liga o microfone, captura o seu comando pelo pipeline de voz normal e responde — igualzinho ao "Hey Siri" ou à "Alexa". Use surface para escolher quem escuta.

A detecção roda inteiramente no dispositivo. O ouvinte sempre ligado só fica atento à frase de ativação; nenhum áudio sai da sua máquina até você efetivamente falar um comando para o agente.

Como funciona

1. Com wake_word.enabled: true (ou depois de /wake on), um detector leve de palavra-chave escuta no dispositivo de entrada que você configurou, ou no microfone padrão do processo quando o wake_word.input_device não está definido.
2. Ao ouvir a frase de ativação, ele se pausa (liberando o microfone), abre uma sessão nova e grava uma fala usando a detecção de silêncio do modo de voz.
3. Sua fala é transcrita e enviada ao agente. Depois da resposta, o ouvinte volta automaticamente e espera a próxima palavra de ativação.

O recurso vem desligado por padrão — nada escuta até você ligar.

No aplicativo desktop, uma conversa de voz sem mãos pode ser encerrada simplesmente dizendo "stop" (ou "never mind", "goodbye", "cancel", "that's all") — o comando falado encerra a conversa em vez de ser enviado ao agente. Só uma fala inteira igual ao comando de parada conta, então um pedido real como "stop the docker container" continua passando normalmente.

Desktop remoto (captura no cliente)

Quando o aplicativo desktop se conecta a um backend Hermes remoto (por exemplo, um host Docker sem interface ou uma máquina em outra sala), esse backend muitas vezes não tem microfone. O PortAudio do lado do servidor então falha com "Failed to open the wake-word microphone."

O Hermes suporta captura no cliente para esse caso:

1. O desktop arma a ativação com capture: client (automático na interface gráfica quando o backend não tem dispositivo de entrada local, ou definido explicitamente como abaixo).
2. O openWakeWord continua rodando no backend (mesmos motores, mesmos modelos).
3. O desktop abre o microfone local do Mac/PC, reamostra para 16 kHz mono int16 e transmite quadros curtos pelo RPC wake.feed.
4. Na detecção, o backend emite wake.detected como sempre; o desktop inicia o pipeline de voz normal no microfone do cliente.

wake_word:
  enabled: true
  capture: auto    # auto | local | client
  # auto   — PortAudio local, a menos que o desktop arme com client_capture
  # local  — sempre abre o microfone do backend (padrão da CLI/TUI)
  # client — sempre espera PCM de wake.feed vindo do desktop (bom para uso remoto)

A interface gráfica do desktop sempre passa client_capture: true no wake.start, então backends remotos sem microfone armam em modo cliente automaticamente. A CLI e a TUI mantêm a captura local, a menos que você defina capture: client explicitamente.

Observação de privacidade: com captura no cliente, o PCM de ativação viaja pelo WebSocket autenticado entre desktop e backend (o mesmo canal do resto da sessão). A detecção continua sem enviar áudio para APIs de ativação de terceiros; o motor é local ao processo do backend.

Motores

Motor	Custo	Chave de API	Observações
openWakeWord (padrão)	Grátis	Nenhuma	Modelos ONNX locais. Já vem com um modelo embutido de "hey hermes" (padrão); também suporta hey_jarvis, alexa, hey_mycroft, … e modelos personalizados
sherpa	Grátis	Nenhuma	Vocabulário aberto — detecta QUALQUER frase digitada, sem treinamento. Um modelo pequeno de inglês baixa sozinho no primeiro uso (~13 MB)
Porcupine	Camada grátis / paga	PORCUPINE_ACCESS_KEY	Motor da Picovoice; palavras-chave embutidas + arquivos .ppn personalizados

Por padrão, a frase é "hey hermes" — um modelo para ela vem junto com o Hermes, então funciona de primeira, sem treinamento. (No primeiro uso, o openWakeWord baixa os modelos compartilhados de extração de características — uma busca pequena e única.)

Os dois são instalados sob demanda na primeira vez que você habilita a palavra de ativação (instalações de desktop feitas com --include-desktop já os pré-instalam, então o ouvido funciona na hora). Para instalar antes:

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

Início rápido

# Numa sessão interativa do `hermes`:
/wake on        # começa a escutar (instala o motor no primeiro uso)
/wake status    # mostra frase, provedor e estado
/wake off       # para de escutar

No aplicativo desktop, clique no ícone de orelha no compositor.

O botão É a configuração: ligar ou desligar a palavra de ativação — pelo /wake ou pelo botão de orelha do desktop — também grava wake_word.enabled no ~/.hermes/config.yaml, então a sua escolha persiste entre sessões. Você também pode mudar na mão:

wake_word:
  enabled: true

Configuração

wake_word:
  enabled: false
  surface: auto               # superfície elegível: "auto" | "cli" | "tui" | "gui"
  input_device: null           # índice de entrada do PortAudio ou pedaço do nome do dispositivo; null = padrão do processo
  capture: auto               # auto | local | client — onde o PCM é capturado (veja Desktop remoto)
  provider: openwakeword      # "openwakeword" (grátis, local) | "sherpa" (grátis, qualquer frase) | "porcupine"
  phrase: "hey hermes"        # só um rótulo cosmético — a detecção usa o modelo/palavra-chave abaixo
  sensitivity: 0.6            # 0.0-1.0 — mais alto = mais rigoroso (menos disparos falsos), igual em todos os motores
  confirmation_frames: 3      # só openWakeWord — quadros consecutivos acima do limiar para disparar
  start_new_session: true     # abrir uma sessão nova na ativação em vez de continuar a atual
  openwakeword:
    model: hey_hermes         # padrão embutido; OU um nome interno OU um caminho para um .onnx/.tflite personalizado
    inference_framework: ""   # "" (automático) | "onnx" | "tflite"
  porcupine:
    keyword: jarvis           # palavra-chave interna OU caminho para um .ppn personalizado

sensitivity, phrase e start_new_session valem para os dois motores. Os blocos openwakeword e porcupine selecionam o modelo de detecção de verdade.

O input_device é passado direto para o fluxo PortAudio (sounddevice) do ouvinte de ativação. Use um índice numérico de dispositivo ou um pedaço não ambíguo do nome do dispositivo. Essa configuração só muda a captura da palavra de ativação; o "aperte para falar" do desktop continua usando o caminho de microfone do aplicativo.

Reduzir disparos falsos com fala ambiente

O openWakeWord pontua um quadro curto de áudio (~80ms) por vez, então um fonema perdido numa conversa de fundo pode, de vez em quando, jogar um único quadro acima do limiar e disparar a ativação sem você querer. Dois botões controlam isso:

• confirmation_frames (padrão 3, só openWakeWord) — quantos quadros consecutivos acima do limiar são exigidos antes de a ativação disparar. Um "hey hermes" de verdade mantém pontuação alta por vários quadros; um estalo do ambiente sobe só um. Aumente (por exemplo, 4–5) se você ainda tiver disparos falsos numa sala barulhenta; o custo são algumas dezenas de milissegundos de latência extra. 1 restaura o comportamento antigo de disparar no primeiro quadro.
• sensitivity (padrão 0.6) — o limiar de detecção, de 0.0 a 1.0. Mais alto é mais rigoroso (menos disparos falsos). Essa direção é a mesma em todos os motores — no openWakeWord é o limiar bruto de pontuação por quadro, no sherpa ele é mapeado para o limiar da palavra-chave, e no Porcupine é invertido internamente para que "mais alto = mais rigoroso" também valha lá. O padrão de 0.6 fica acima da linha de base permissiva de 0.5 do openWakeWord, que deixava passar quase-erros como "hey hor"; suba para perto de 0.8 se ainda tiver disparos falsos, e abaixe se falas reais de "hey hermes" estiverem passando batido.

Os motores sherpa e porcupine decodificam a frase inteira internamente, então não têm o problema do pico de quadro único e ignoram o confirmation_frames (mas continuam respeitando o sensitivity).

O inference_framework escolhe o backend do openWakeWord. Deixe vazio (o padrão) para o Hermes escolher por plataforma: tflite no Apple Silicon, onnx em todo o resto. O backend onnx do openWakeWord devolve pontuações quase zero no macOS ARM64 (openWakeWord#336), então um ouvinte fixado em onnx ali vai armar, aparecer como escutando e nunca disparar. O backend tflite precisa do ai-edge-litert no macOS, que o Hermes instala sob demanda junto com as outras dependências de palavra de ativação.

Superfícies (CLI, TUI, GUI)

A palavra de ativação funciona nas três superfícies do Hermes, e o surface escolhe qual delas é dona do ouvinte e abre a sessão nova quando ela dispara:

surface	Comportamento
auto (padrão)	Todas as superfícies locais são elegíveis; a primeira a armar fica dona do ouvinte.
cli	Só a CLI clássica do hermes.
tui	Só o hermes --tui.
gui	Só o aplicativo desktop.

O detector roda no dispositivo e usa um microfone só, então apenas uma superfície escuta por vez, inclusive quando as superfícies do Hermes rodam em processos separados. A posse é grudenta: o primeiro reivindicante elegível fica com o ouvinte até parar, desconectar ou o processo dele encerrar. O Hermes não passa a bola em silêncio para outra superfície aberta. Defina o surface quando você quiser fixar a posse em vez de deixar a primeira reivindicação ganhar. A TUI e a interface gráfica do desktop compartilham o mesmo backend Python (tui_gateway), que roda o detector do lado do servidor e cede o microfone para a captura de voz enquanto um comando é gravado.

Usar outra frase

"Hey Hermes" funciona de primeira — o modelo embutido do openWakeWord (model: hey_hermes) é o padrão. Para ativar com outra coisa, o caminho mais fácil é o motor de vocabulário aberto:

Opção A — sherpa (qualquer frase, zero treinamento)

Digite a frase que você quer; ela é tokenizada em tempo de execução — "hey coder", "computer", "wake up neo", qualquer coisa:

wake_word:
  enabled: true
  provider: sherpa
  phrase: "hey coder"        # chave de detecção — basta digitar sua frase

O modelo pequeno de KWS em inglês (~13 MB) baixa uma vez no primeiro uso. Cada perfil pode ter a própria frase — "hey <perfil>" para cada perfil que você rodar.

Ativar um perfil específico (desktop)

Com o motor sherpa, UM ouvinte pode ativar QUALQUER perfil. Todo perfil cuja configuração tem wake_word.enabled: true é inscrito automaticamente; a frase dele assume por padrão hey <nome do perfil> quando não está definida. Fale a frase de um perfil e o aplicativo desktop troca para aquele perfil ao vivo, abre uma sessão nova lá e inicia a voz sem mãos:

• "hey hermes" → perfil padrão
• "hey coder" → o perfil coder
• "hey trader" → o perfil trader

Defina wake_word.profile_routing: false no perfil do ouvinte para sair desse comportamento e escutar só a frase dele. A CLI e a TUI são processos de um único perfil: uma frase de ativação que pertence a outro perfil imprime o comando de troca (hermes -p <profile>) em vez de rotear.

Os nomes são reconhecidos acusticamente pelos sons de subpalavra em inglês: frases de duas palavras com nomes distintos, de 2 sílabas ou mais, funcionam melhor. Nomes muito curtos, fonologia bem distante do inglês, ou dois perfis com nomes de som parecido pioram a precisão — ajuste o sensitivity por perfil se precisar.

Opção B — openWakeWord (grátis, modelo treinado)

Aponte um modelo interno (hey_jarvis, alexa, hey_mycroft, …), ou treine um modelo personalizado (mais ou menos 75–90 min numa GPU grátis/Colab) para robustez máxima, coloque o arquivo .onnx em algum lugar e aponte para ele:

wake_word:
  enabled: true
  provider: openwakeword
  phrase: "computer"
  openwakeword:
    model: ~/.hermes/wakewords/computer.onnx   # ou um nome interno, como hey_jarvis

Referências de treinamento:

• openWakeWord
• Colab de treinamento de 2026

Escolha uma frase distintiva

Frases de ativação que não colidem com a fala do dia a dia generalizam melhor. Duas sílabas com uma palavra incomum ("hermes" se encaixa) ganham de palavras comuns como "hello" ou "stop".

Opção C — Porcupine (palavra-chave personalizada em segundos)

Crie uma palavra-chave "Hey Hermes" no Console da Picovoice, baixe o .ppn e:

wake_word:
  enabled: true
  provider: porcupine
  phrase: "hey hermes"
  porcupine:
    keyword: ~/.hermes/wakewords/hey_hermes.ppn

Coloque sua chave de acesso em ~/.hermes/.env:

PORCUPINE_ACCESS_KEY=sua-chave-aqui

Requisitos

• Um microfone funcionando e a pilha de áudio sounddevice + numpy (compartilhada com o modo de voz).
• Um provedor de STT para transcrever o comando falado — o faster-whisper local funciona de primeira; veja o Modo de voz para a lista completa de provedores.
• Um provedor de TTS para falar a resposta (o padrão edge-tts funciona sem chave). O fluxo de ativação é totalmente sem mãos, então o botão se recusa a armar até STT e TTS estarem prontos — o hermes tools (seção Voice) configura os dois.
• As dependências do motor de ativação (instaladas automaticamente, ou hermes-agent[wake]).

O /wake status informa exatamente o que está faltando quando o ouvinte não sobe.

"Escutando", mas nunca ativa (macOS)

O macOS concede acesso ao microfone por processo. O STT funcionando no aplicativo desktop prova que o renderer tem acesso ao microfone — o ouvinte de ativação roda no backend Python, que precisa da própria permissão. Sem ela, o CoreAudio entrega ao backend um fluxo "funcionando" que só entrega silêncio, então a orelha aparece escutando mas a frase nunca dispara. O Hermes detecta isso (o /wake status mostra "mic delivers only silence"; a dica da orelha no desktop traz a mesma informação). Correção: Ajustes do Sistema → Privacidade e Segurança → Microfone → habilite o backend do Hermes (ele pode aparecer como o seu terminal, python ou Hermes), depois desligue e ligue de novo a palavra de ativação.

"Escutando", mas recebe silêncio (Windows)

O "aperte para falar" do desktop e a captura da palavra de ativação usam caminhos de microfone diferentes. O "aperte para falar" usa a captura do navegador no aplicativo desktop, enquanto o ouvinte de ativação abre um fluxo PortAudio no backend Python. Um pode funcionar enquanto o outro seleciona uma entrada do Windows silenciosa ou inutilizável.

O /wake status informa o dispositivo de entrada selecionado e a API de host de áudio do Windows. Quando ele acusar silêncio, defina o wake_word.input_device como o índice numérico ou um nome não ambíguo da entrada PortAudio que funciona, e depois desligue e ligue a palavra de ativação:

hermes config set wake_word.input_device "Microphone Array"

Use null para voltar ao padrão do processo:

hermes config set wake_word.input_device null

Observações e limites

• Só superfícies locais. A palavra de ativação roda na CLI, na TUI e na interface gráfica do desktop — onde houver um microfone local. Ela não roda no gateway de mensagens (Telegram, Discord, …), que não tem microfone.
• Um microfone por vez. O detector solta o microfone enquanto um comando está sendo gravado e o retoma quando o turno acaba, então ele não briga com a captura de voz.
• Privacidade. A detecção de palavra-chave é local. Aumente o sensitivity se você tiver disparos falsos, e diminua se ele não te ouvir.

---