Modo de Voz: Ditando os Prompts para o Console

📚 Navegação da Série: O capítulo anterior 46 Configurações de Desenvolvimento detalhou como preparar e isolar o ambiente operacional do Claude Code (sandbox, devcontainer e proxies corporativos). Este capítulo aborda a ergonomia de interação — como habilitar o ditado por voz para converter fala em texto diretamente no console de comandos da CLI. O comando /voice permite alternar a digitação tradicional pela fala, apresentando algumas diretrizes e restrições de uso para sua ativação.

⚠️ Funcionalidade experimental, sujeita a alterações em atualizações de versão. A documentação de comandos e atalhos reflete a especificação estável atual. Caso ocorram variações no ditado da sua máquina, adote as orientações do utilitário /voice local.

É comum encarar o recurso de entrada por voz em ferramentas de programação com ceticismo. Desenvolvedores costumam digitar rapidamente, e termos técnicos (como nomes de variáveis, métodos camelCase e sintaxes específicas) costumam ser mal interpretados por sistemas de voz convencionais, exigindo mais tempo de correção manual de termos do que a digitação tradicional de comandos.

No entanto, a CLI do Claude Code implementa dois recursos específicos para contornar esses cenários:

Adequação a vocabulários de desenvolvimento: O motor de transcrição reconhece termos específicos de programação (como regex, OAuth, JSON, localhost e REST).
Contextualização com o repositório: A IA insere os nomes de arquivos do projeto e a branch Git ativa no motor de transcrição, aumentando a taxa de acerto de termos locais e siglas específicas do repositório.

Este recurso não visa substituir a escrita do código em si, mas facilitar a descrição de instruções extensas e cenários de testes complexos (como "Reescreva a lógica do middleware de autenticação para validar os tokens usando o novo validador de sessão"). Falar a instrução costuma ser mais rápido e natural do que digitar o parágrafo no console.

Ao ler este capítulo, você obterá:

O conceito da transcrição de voz no Claude Code e onde ocorre o processamento dos áudios.
A restrição técnica de uso: compatibilidade exclusiva com logins de contas Claude.ai, inviabilizando o uso de chaves de API.
A tabela de compatibilidade do recurso nos diferentes sistemas operacionais e conexões remotas.
O funcionamento dos dois perfis de gravação: Modo Hold (Pressionar para falar) e Modo Tap (Clicar para falar).
Como configurar a inicialização do modo de voz nas preferências do usuário, alterar o idioma e customizar o atalho de teclado de acionamento.
Um exercício prático guiado para ativar e testar o ditado de voz no repositório de testes.

01 O Ditado de Voz e Processamento de Áudio no Claude Code

O recurso de voz capta o sinal do seu microfone, converte o áudio em texto em tempo real e insere o resultado no campo de digitação do console, funcionando como uma alternativa de entrada ao teclado físico da máquina.

Analogia: Transcrição ao vivo de palestras. Ao assistir a uma apresentação contendo legendas em tempo real, o palestrante fala no microfone e a fala é exibida em formato de texto na tela. O Claude Code atua de forma similar: você fala no microfone e as palavras são inseridas no prompt, prontas para edição antes do envio final.

A documentação oficial descreve esse comportamento híbrido:

Fale as instruções no terminal em vez de digitá-las. A fala é transcrita no console em tempo real, permitindo intercalar o ditado de voz e ajustes com o teclado na mesma mensagem.

Essa flexibilidade permite descrever a instrução em linhas gerais usando a voz e, em seguida, posicionar o cursor para inserir termos exatos ou caminhos de arquivos de forma manual via teclado.

Atenção à regra de privacidade de dados: o áudio captado não é processado na máquina local.

O ditado de voz realiza a transmissão do sinal de áudio gravado diretamente para a infraestrutura de servidores da Anthropic para a execução da transcrição. Os dados de voz não são processados na máquina local.

Dessa forma, o recurso exige conexão com a internet ativa e validação de credenciais de acesso para processar o áudio.

Os recursos de transcrição não consomem cotas de tokens do seu plano nem geram cobranças adicionais:

As chamadas de transcrição de voz não consomem cotas de tokens ou mensagens da assinatura Claude Pro/Max, e não entram na contagem de limites de consumo do comando /usage.

A transcrição de áudio funciona como um recurso de usabilidade de entrada da plataforma, sem custos adicionais de tokens.

💡 Resumo em uma frase: O modo de voz converte fala em texto em tempo real enviando o áudio para transcrição nos servidores da Anthropic, permitindo intercalar voz e escrita sem consumo de tokens do plano.

02 Restrição de Autenticação: Necessidade de Conta Claude.ai

Para validar a sessão e transmitir o sinal de voz para a infraestrutura da nuvem, a CLI exige a validação da conta.

O ditado por voz possui uma restrição importante de licenciamento:

O serviço de voz exige que a sessão de uso da CLI esteja autenticada sob uma conta Claude.ai. O ditado por voz não está disponível para execuções que utilizam chaves de API (ANTHROPIC_API_KEY), conexões com Amazon Bedrock, Google Vertex AI ou instâncias de nuvem privada Microsoft Foundry. Ambientes corporativos configurados sob regras de conformidade HIPAA também possuem o recurso de voz desativado por padrão.

A arquitetura do motor de voz depende do backend de serviços das contas de usuário da plataforma, inviabilizando conexões por chaves de API de faturamento direto.

Mapeamento de acessibilidade do recurso de voz:

Método de Acesso à CLI	Suporte ao Modo de Voz	Mensagem de Retorno
Conta Claude.ai (Login Pro/Max)	✅ Habilitado	Inicializa o canal de voz normalmente.
*API Direct Key (`sk-ant-`)**	❌ Desabilitado	Erro: `Voice mode requires a Claude.ai account`
Serviços de Nuvem (Bedrock/Vertex)	❌ Desabilitado	Não compatível.
Ambientes com conformidade HIPAA	❌ Desabilitado	Bloqueado por regras de privacidade.

Se a sua máquina retornar a mensagem Voice mode requires a Claude.ai account, execute o comando /login na CLI para redefinir as credenciais da sessão, adotando o login via conta do Claude.ai (Capítulo 7) para liberar o ditado.

💡 Resumo em uma frase: O recurso de voz é exclusivo para sessões com login via conta Claude.ai (Pro/Max), retornando erros de ausência de permissão se a inicialização for executada sob chaves de API ou conexões corporativas de nuvens parceiras.

03 Requisitos de Hardware e Tabelas de Compatibilidade de Sistemas

Além do login de usuário, a captação de voz exige a presença física e permissão de acesso ao microfone local do desenvolvedor.

Analogia: Chamadas em ambientes virtualizados. Ao acessar um computador do escritório via acesso remoto (SSH ou Terminal Server), você utiliza os recursos de tela e teclado. No entanto, se você tentar falar, o sistema remoto não captará o áudio a menos que exista um canal de passagem do sinal de áudio do seu microfone físico para a máquina remota. O Claude Code necessita desse caminho físico para ler o sinal de voz.

A documentação detalha a restrição de conexões remotas:

O ditado por voz requer acesso físico ao microfone local, impossibilitando a operação em sessões remotas via conexões SSH ou através da versão baseada em nuvem Claude Code on the web.

Compatibilidade de suporte de voz por plataformas:

Sistema Operacional / Ambiente	Suporte de Voz	Observação Técnica
macOS	✅ Compatível	Solicita autorização de microfone do sistema no primeiro uso.
Windows	✅ Compatível	Permissões de microfone devem estar ativas para o console nas configurações do Windows.
Linux (Nativo)	✅ Compatível	Utiliza o módulo de som local, com fallback automático para utilitários `arecord` ou `rec`.
WSL2	⚠️ Condicional	Requer suporte a WSLg ativo (Win 10/11) para ponte de áudio; incompatível com WSL1.
SSH Terminal	❌ Incompatível	Conexão remota não transmite o áudio local por padrão.
VS Code Remote	❌ Incompatível	Conexões usando SSH, Dev Containers ou Codespaces rodam o processo da IA no host remoto.

No Linux, caso a CLI não localize as dependências nativas de áudio, o console exibirá o comando de instalação do pacote utilitário compatível com a sua distribuição (como SoX ou ALSA). Execute a instalação recomendada no terminal:

bash

# Exemplo de pacote utilitário de gravação
sudo apt-get install sox

💡 Resumo em uma frase: O ditado por voz requer o acesso ao microfone físico local; ele funciona de forma nativa no macOS, Windows e Linux, mas é incompatível com conexões SSH e ambientes virtualizados de VS Code Remote.

04 Os Dois Modos de Captação: Hold (Pressionar) e Tap (Clicar)

O comando /voice oferece duas abordagens para gerenciar a gravação do áudio:

Analogia: Comunicação via rádio (Walkie-Talkie) vs. Gravador portátil. O Walkie-Talkie exige manter o botão de transmissão pressionado durante a fala e soltá-lo ao terminar — esse é o modo Hold. O gravador portátil é ativado com um único clique de início e grava de forma contínua até receber outro clique de parada — esse é o modo Tap.

Comparativo operacional dos modos de captação:

Característica	Modo Hold (Pressionar)	Modo Tap (Clicar)
Ativação	Pressionar e segurar a barra de `Espaço`.	Clicar uma única vez na barra de `Espaço`.
Encerramento	Soltar a tecla de `Espaço`.	Clicar novamente na barra de `Espaço`.
Envio	Mantém o texto no prompt para edição manual (padrão).	Envia o texto automaticamente (se a transcrição tiver ≥3 palavras).
Requisitos	Claude Code v2.1.69 ou superior.	Claude Code v2.1.116 ou superior (Modo mais recente).

1. Modo Hold (Padrão)

No modo Hold (pressionar para falar), mantenha a tecla Espaço pressionada enquanto fala e solte-a ao terminar a instrução.

A CLI monitora a repetição contínua da tecla no console para detectar o pressionamento. O processo apresenta uma pequena etapa de calibração ("aquecimento") de meio segundo. O console exibe o texto keep holding... antes de iniciar a captura do áudio. As letras iniciais digitadas durante esse aquecimento são removidas de forma automática assim que a gravação é ativada.

O ditado é inserido exatamente onde o cursor de digitação está posicionado no prompt.

2. Modo Tap

No modo Tap (clicar para falar), ative o ditado digitando no chat:

text

/voice tap

Para usar, clique uma vez em Espaço para iniciar a gravação, fale a instrução e clique novamente na tecla Espaço para parar. O texto captado é transcrito e submetido diretamente para resposta da IA (se a frase possuir pelo menos 3 palavras), oferecendo agilidade no fluxo de interação.

O modo Tap possui uma proteção para evitar disparos indesejados: a gravação é iniciada apenas se o campo de texto do prompt estiver vazio, impedindo que cliques na barra de espaço durante a digitação de códigos ativem o microfone acidentalmente. A gravação é encerrada de forma automática se o sistema detectar silêncio por mais de 15 segundos ou se o tempo total atingir 2 minutos.

💡 Resumo em uma frase: O modo Hold grava enquanto a tecla Espaço é pressionada e mantém o texto para revisão; o modo Tap inicia e encerra a gravação com cliques simples e envia a instrução automaticamente.

05 Configurações de Preferências e Customização do Atalho de Voz

Esta seção apresenta como ajustar o comportamento do modo de voz nas preferências do usuário.

1. Habilitando a Inicialização Automática da Voz

Para carregar o suporte de voz automaticamente a cada inicialização da CLI, adicione o bloco voice no arquivo de preferências do usuário ~/.claude/settings.json:

json

{
  "voice": {
    "enabled": true,
    "mode": "tap"
  }
}

Para que o modo Hold (Pressionar) envie a instrução de forma imediata ao soltar a tecla, adicione a opção autoSubmit: true nas preferências:

json

{
  "voice": {
    "enabled": true,
    "mode": "hold",
    "autoSubmit": true
  }
}

2. Configurações de Idiomas de Transcrição

O ditado de voz herda a definição de idioma configurada no parâmetro global language da CLI. Se o parâmetro estiver em branco, o sistema adota o idioma inglês como padrão de transcrição.

Importante: No momento, a lista oficial de idiomas suportados pelo ditado de voz no Claude Code não inclui suporte nativo ao idioma português (pt-BR). Falar em português sob a calibração de inglês gerará palavras incorretas no prompt. A transcrição de voz suporta idiomas como inglês, espanhol, francês, alemão, italiano, japonês e coreano. Verifique os idiomas ativos em sua instalação consultando as informações exibidas ao ativar o comando /voice.

Para definir o idioma de transcrição (por exemplo, espanhol ou inglês), modifique o arquivo settings ou utilize o comando /config:

json

{
  "language": "english"
}

3. Redefinindo a Tecla de Atalho (Keybindings)

Se preferir utilizar outra tecla em vez de Espaço para ativar a gravação, altere a associação da ação voice:pushToTalk no arquivo ~/.claude/keybindings.json (detalhes no Capítulo 14):

json

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "meta+k": "voice:pushToTalk",
        "space": null
      }
    }
  ]
}

No modo Hold (pressionar), evite configurar teclas de letras simples (como a letra v avulsa). Como o sistema operacional repete caracteres ao manter a tecla pressionada, a letra seria impressa no campo do prompt antes do início da gravação. Priorize atalhos contendo teclas modificadoras (como meta+k ou ctrl+k).

💡 Resumo em uma frase: Configure a voz no settings.json indicando o modo de captação; atente-se de que o ditado herda o parâmetro de idioma global language e redefina a tecla associando a ação voice:pushToTalk.

06 Prática: Habilitando e Testando a Captação de Voz

Executaremos o teste prático de gravação e validação da transcrição de voz.

Requisitos: sessão do Claude Code autenticada com conta Claude.ai (login Pro/Max), microfone físico conectado e operacional.

Passo 1: Validar versão mínima instalada (no terminal do sistema)

bash

claude --version

Resultado esperado: O terminal indica a versão instalada. Confirme se a versão é igual ou superior a 2.1.69.

Passo 2: Iniciar a sessão e ativar o canal de voz

bash

claude

Na janela de chat, execute o comando de ativação:

text

/voice

Resultado esperado: O sistema operacional macOS ou Windows exibe uma janela solicitando permissão de acesso ao microfone físico. Clique em permitir. O console exibe a mensagem Voice mode enabled (hold).

Passo 3: Gravar a instrução em modo Hold

Pressione e mantenha a tecla Espaço pressionada. Após o aviso sonoro ou a indicação visual de gravação, diga de forma clara uma instrução em inglês (idioma padrão de ditado):

text

# Mantendo Espaço pressionado, diga:
show status

Solte a tecla Espaço.

Resultado esperado: A frase ditada é impressa no prompt no formato show status de forma legível.

Passo 4: Intercalar com digitação manual

Com o cursor no final da frase ditada, digite os termos adicionais usando o teclado físico:

text

# Adicione via teclado:
 show status and version

Pressione Enter para enviar o prompt completo ao Claude.

Resultado esperado: O Claude processa a instrução unificada (voz + teclado) e retorna os detalhes técnicos da sessão ativa.

Passo 5: Testar o fechamento e desligamento do modo de voz

Desative o canal de áudio da CLI:

text

/voice off

Resultado esperado: O console exibe o alerta informando que a captação de voz foi desativada, e a barra de espaço retorna ao funcionamento de digitação de caracteres padrão.

💡 Resumo em uma frase: A prática guiará você na validação da versão da CLI, liberação de acesso ao microfone, gravação da instrução em inglês no modo Hold, edição híbrida com o teclado e desligamento da captação via /voice off.

07 Resumo

O modo de voz (ditado de voz) do Claude Code atua como um canal de entrada ergonômico, convertendo instruções faladas em texto de forma direta no console de desenvolvimento.

Conceitos centrais revisados neste capítulo:

Diretriz	Detalhe
Funcionamento	Grava o áudio do microfone e transmite para transcrição nos servidores da Anthropic; o recurso não consome tokens do seu plano de uso.
Restrição de Login	Exige obrigatoriamente a autenticação de sessões sob contas Claude.ai, retornando erros se ativado sob chaves de API.
Limitação Física	Requer acesso físico ao microfone local, sendo incompatível com conexões remotas via SSH ou ambientes VS Code Remote.
Perfis	Divide-se em modo Hold (gravação contínua ao pressionar o Espaço) e modo Tap (acionamento por cliques simples de ligar/desligar).
Idioma	O ditado herda o idioma configurado no parâmetro global `language` da CLI (sem suporte ao português na especificação atual).

Ajustar e utilizar o ditado por voz acelera a descrição de tarefas de desenvolvimento extensas e simplifica o fluxo de interação com o console local.

O próximo capítulo, 48 "Projeto Capstone: Desenvolvendo uma Aplicação do Zero", consolidará os conhecimentos da série. Desenvolveremos um projeto completo — desde a criação de pastas, configuração de regras de linters, integração MCP, refatorações locais até a publicação de Pull Requests automatizados. Nos vemos no próximo capítulo!

Modo de Voz: Ditando os Prompts para o Console ​

01 O Ditado de Voz e Processamento de Áudio no Claude Code ​

02 Restrição de Autenticação: Necessidade de Conta Claude.ai ​

03 Requisitos de Hardware e Tabelas de Compatibilidade de Sistemas ​

04 Os Dois Modos de Captação: Hold (Pressionar) e Tap (Clicar) ​

1. Modo Hold (Padrão) ​

2. Modo Tap ​

05 Configurações de Preferências e Customização do Atalho de Voz ​

1. Habilitando a Inicialização Automática da Voz ​

2. Configurações de Idiomas de Transcrição ​

3. Redefinindo a Tecla de Atalho (Keybindings) ​

06 Prática: Habilitando e Testando a Captação de Voz ​

07 Resumo ​

Leituras Recomendadas ​

Modo de Voz: Ditando os Prompts para o Console

01 O Ditado de Voz e Processamento de Áudio no Claude Code

02 Restrição de Autenticação: Necessidade de Conta Claude.ai

03 Requisitos de Hardware e Tabelas de Compatibilidade de Sistemas

04 Os Dois Modos de Captação: Hold (Pressionar) e Tap (Clicar)

1. Modo Hold (Padrão)

2. Modo Tap

05 Configurações de Preferências e Customização do Atalho de Voz

1. Habilitando a Inicialização Automática da Voz

2. Configurações de Idiomas de Transcrição

3. Redefinindo a Tecla de Atalho (Keybindings)

06 Prática: Habilitando e Testando a Captação de Voz

07 Resumo

Leituras Recomendadas