macOS companion app

Ativação por voz (macOS)

Ativação por voz e pressione para falar

Requisitos

A ativação por voz e o recurso de pressionar para falar exigem o macOS 26 ou mais recente. Em versões anteriores do macOS, os controles ficam ocultos na página de configurações de Voz, que exibe o requisito do macOS 26.

Modos

Modo de palavra de ativação (padrão): um reconhecedor de fala sempre ativo aguarda tokens de ativação (swabbleTriggerWords). Quando há uma correspondência, ele inicia a captura, exibe a sobreposição com o texto parcial e envia automaticamente após um período de silêncio.
Pressione para falar (mantenha pressionada a tecla Option direita): mantenha pressionada a tecla Option direita para iniciar a captura imediatamente, sem precisar de uma palavra de ativação. A sobreposição aparece enquanto a tecla está pressionada; ao soltá-la, a captura é finalizada e encaminhada após um pequeno atraso, permitindo que você edite o texto.

Comportamento em tempo de execução (palavra de ativação)

O reconhecedor reside em VoiceWakeRuntime.
A ativação ocorre somente quando há uma pausa significativa entre a palavra de ativação e a palavra seguinte (triggerPauseWindow = 0,55 s). A sobreposição e o aviso sonoro podem ser iniciados durante a pausa, antes mesmo do início do comando.
Janelas de silêncio: 2,0 s (silenceWindow) enquanto a fala está fluindo; 5,0 s (triggerOnlySilenceWindow) se apenas a palavra de ativação tiver sido ouvida.
Interrupção forçada: 120 s (captureHardStop) para evitar sessões descontroladas.
Intervalo de estabilização entre sessões: 350 ms (debounceAfterSend) após um envio.
A sobreposição é controlada por VoiceWakeOverlayController, com cores distintas para o texto confirmado e o texto temporário.
Após o envio, o reconhecedor é reiniciado de forma limpa para aguardar a próxima ativação.

Invariantes do ciclo de vida

Se a ativação por voz estiver habilitada e as permissões tiverem sido concedidas, o reconhecedor da palavra de ativação permanecerá em escuta, exceto durante uma captura ativa de pressionar para falar.
O fechamento da sobreposição, incluindo o fechamento manual pelo botão X, sempre retoma o reconhecedor: VoiceSessionCoordinator.overlayDidDismiss chama VoiceWakeRuntime.refresh(state:) em todos os caminhos de fechamento. Consulte Sobreposição de voz para conhecer o modelo de sessão/token.

Detalhes de pressionar para falar

A detecção da tecla de atalho usa um monitor global de .flagsChanged para a tecla Option direita (keyCode 61 + .option). Ele apenas observa os eventos, sem nunca bloqueá-los.
A captura reside em VoicePushToTalk: inicia o reconhecimento de fala imediatamente, transmite resultados parciais para a sobreposição e chama VoiceWakeForwarder quando a tecla é solta.
O início de pressionar para falar pausa o tempo de execução da palavra de ativação para evitar capturas de áudio concorrentes; ele é reiniciado automaticamente após a tecla ser solta.
Permissões: exige acesso ao Microfone e ao Reconhecimento de Fala; o recebimento de eventos de teclado exige aprovação para Acessibilidade/Monitoramento de Entrada.
Teclados externos: alguns não expõem a tecla Option direita conforme esperado. Ofereça um atalho alternativo caso os usuários relatem falhas de detecção.

Configurações visíveis ao usuário

Alternância Ativação por voz: habilita o tempo de execução da palavra de ativação.
Mantenha pressionada a tecla Option direita para falar: habilita o monitor de pressionar para falar.
Seletores de idioma e microfone, um medidor de nível em tempo real, uma tabela de palavras de ativação e uma ferramenta de teste (somente local, nunca encaminha).
O seletor de microfone preserva a última seleção quando um dispositivo é desconectado, exibe um aviso de desconexão e usa temporariamente o dispositivo padrão do sistema até que o dispositivo retorne.
Sons: avisos sonoros ao detectar a ativação e ao enviar, usando por padrão o som de sistema "Glass" do macOS. Selecione qualquer arquivo que possa ser carregado por NSSound (por exemplo, MP3/WAV/AIFF) para cada evento ou escolha Sem som.

Comportamento de encaminhamento

Ao encaminhar, VoiceWakeForwarder.selectedSessionOptions seleciona a chave da sessão ativa do WebChat, se houver uma definida; caso contrário, seleciona a chave da sessão principal do Gateway.
Ele procura essa sessão por meio de sessions.list e obtém o canal e o destino de entrega a partir do contexto de entrega da sessão (usando como alternativas o último canal/destino e, depois, uma chave de sessão analisada), adotando o WebChat como padrão se nada for resolvido.
Se a entrega falhar, o erro será registrado (categoria voicewake.forward), e a execução continuará visível por meio dos registros do WebChat/da sessão.

Carga útil de encaminhamento

VoiceWakeForwarder.prefixedTranscript(_:) adiciona uma linha de indicação para a máquina (nome do host resolvido, usando "este Mac" como alternativa) antes da transcrição, compartilhada entre os caminhos de palavra de ativação e de pressionar para falar.

Verificação rápida

Ative pressionar para falar, mantenha pressionada a tecla Option direita, fale e solte-a: a sobreposição deverá exibir os resultados parciais e, em seguida, enviar.
Enquanto a tecla estiver pressionada, as orelhas da barra de menus deverão permanecer ampliadas (triggerVoiceEars(ttl: nil)); elas voltam ao tamanho normal após a tecla ser solta.

Relacionado

Was this useful?