airpods-voice-input-method

## Visão geral do projeto O AirPods Voice 输入法 é um app nativo da barra de menus do macOS que usa o gesto de um clique nos AirPods para controlar a entrada de voz: um clique inicia a gravação, outro clique para, confirma o texto e envia automaticamente, tudo sem tocar no teclado. A versão estável atual é a 1.0. ## Principais recursos - Um clique nos AirPods inicia a entrada de voz; outro clique para e envia automaticamente. - Suporta vários ciclos consecutivos, retornando ao estado ocioso pronto para reiniciar após cada ciclo. - Compatível com microfone interno e microfone dos AirPods, sem alterar configurações do app. - Por padrão simula pressionar e segurar `Fn`, mas pode ser configurado para Control, Option, Command, Shift ou F1–F12. - A barra de menus e a janela de controle oferecem estado de execução, iniciar, parar, instruções de uso e sair. - A janela de controle aparece a cada abertura do app; ao fechá-la, o app continua na barra de menus. - Entrada pelo teclado físico interrompe automaticamente a tecla de voz não finalizada, evitando que modificadores afetem terminais ou apps de tarefas. - Não ocupa o Dock nem depende de softwares de automação de terceiros como o BetterTouchTool. - Suporta Macs Apple Silicon e Intel; requisito mínimo macOS 13. ## Pré-requisitos de uso É necessário configurar o atalho de entrada de voz do seu próprio método de entrada de voz como "pressionar e segurar Fn". O README informa que a versão 1.0 foi validada com o método de entrada Doubao em múltiplos ciclos com AirPods físicos; outros métodos precisam suportar o comportamento de "segurar o atalho para gravar, soltar para encerrar". Durante a execução, o app assume o clique de play/pause dos AirPods, portanto nesse período não é possível controlar música com um clique; ao parar ou sair do app, o controle de mídia é restaurado. ## Instalação e permissões Baixe o pacote PKG em GitHub Releases e instale em `/Applications/AirPods Voice 输入法.app`. O instalador interrompe e remove automaticamente versões de teste antigas, evitando que duas versões assumam os AirPods ao mesmo tempo. O pacote atual usa assinatura ad-hoc; se o macOS bloquear, clique com o botão direito no Finder e escolha "Abrir". O app precisa da permissão de "Acessibilidade" do macOS para simular a tecla de voz pressionada e enviar Enter. A autorização é concedida ao próprio app, não sendo necessário autorizar o terminal ou ferramentas de desenvolvimento, nem Acesso Total ao Disco; o app em si não captura o microfone, pois a permissão de microfone é gerenciada pelo método de entrada de voz escolhido pelo usuário. ## Como funciona (descrição do README) O app mantém uma sessão Now Playing via `MPRemoteCommandCenter` para receber o clique dos AirPods, aceitando apenas eventos de mídia com origem `com.apple.bluetoothd` ou `com.apple.cloudpaird`; outras origens, como teclas de reprodução do teclado, não iniciam a voz. Após o microfone dos AirPods entrar no modo de áudio de chamada, o segundo clique é reportado pelo `bluetoothd` como Software Mute, e o app só o trata como sinal de parar e enviar dentro de sua própria sessão de voz já iniciada. O monitoramento IOHID serve como canal alternativo, com deduplicação da mesma operação física por uma janela de 350 ms. O primeiro clique envia uma ativação de Fn via `IOHIDPostEvent`; o segundo clique encerra a sessão de gravação e envia dois Enter em sequência, o primeiro confirmando o texto composto pelo método de entrada e o segundo enviando a mensagem. Para evitar que modificadores globais afetem apps sensíveis a atalhos, a versão 1.0 adiciona três camadas de proteção: limpar resíduos históricos de Fn na inicialização; ao detectar entrada de teclado físico durante a voz, remover primeiro o modificador de voz e encerrar imediatamente a voz; e, em saída anormal do app, um processo guardião independente libera o Fn. Em parada normal, troca de app em primeiro plano, timeout de segurança de 5 minutos ou saída do app, apenas a tecla é liberada, sem envio acidental. ## Configuração e logs O arquivo de configuração padrão é `config/voice-key`, com conteúdo `fn`, podendo ser alterado para control, option, command, shift ou f1–f12; após a alteração, reinicie o script. Também é possível especificar temporariamente via variável de ambiente ao executar a partir do código-fonte. Os logs ficam em `/tmp/airpods-voice-input-method/` como app.log, app.stdout.log e app.stderr.log; use `pgrep -fl airpods-voice-input-method` para confirmar o processo e `./scripts/stop.sh` para parar com segurança e liberar a tecla de voz. ## Build e testes Há `scripts/build.sh` para construir o app universal, `scripts/package-release.sh` para gerar o PKG, com suporte a certificado Developer ID especificado. Os scripts de teste cobrem cenários de regressão como quatro ciclos de interação de voz, consumo de Fn, segurança do teclado e recuperação de falhas; além disso, `tests/hitl-two-cycle.sh` serve para validação manual com AirPods físicos. ## Licença O código-fonte usa a licença PolyForm Noncommercial 1.0.0, sendo source-available e não uma licença de código aberto segundo a definição da OSI; uso pessoal de aprendizado, pesquisa e não comercial é permitido, mas uso comercial exige autorização separada.