Sobre el proyecto

## Descripción general del proyecto AirPods Voice 输入法 es una app nativa de barra de menús de macOS que controla la entrada de voz con el gesto de un clic en los AirPods: un clic inicia la grabación, otro clic detiene, confirma el texto y lo envía automáticamente, todo sin tocar el teclado. La versión estable actual es 1.0. ## Funciones principales - Un clic en los AirPods inicia la entrada de voz; otro clic la detiene y la envía automáticamente. - Admite varios ciclos consecutivos; tras cada ciclo vuelve al estado inactivo listo para reiniciarse. - Compatible con el micrófono integrado y el de los AirPods, sin cambiar la configuración de la app. - Por defecto simula una pulsación larga de `Fn`; también puede configurarse como Control, Option, Command, Shift o F1–F12. - La barra de menús y la ventana de control ofrecen estado de ejecución, inicio, detención, instrucciones y salida. - Cada vez que se abre la app se muestra la ventana de control; al cerrarla, sigue ejecutándose en la barra de menús. - La entrada por teclado físico aborta automáticamente la tecla de voz no finalizada, evitando que las teclas modificadoras afecten a terminales o apps de tareas. - No ocupa el Dock ni depende de software de automatización de terceros como BetterTouchTool. - Compatible con Apple Silicon e Intel Mac; requiere macOS 13 como mínimo. ## Requisitos de uso Es necesario configurar el atajo de entrada de voz de tu propio método de entrada como «pulsación larga de Fn». El README indica que la versión 1.0 se validó con el método de entrada Doubao en varios ciclos con AirPods físicos; otros métodos deben admitir el comportamiento de «mantener el atajo para grabar y soltar para finalizar». Mientras la app está en ejecución, asume el clic de reproducción/pausa de los AirPods, por lo que en ese momento no se puede controlar la música con un clic; al detener o salir de la app, se restaura el control multimedia. ## Instalación y permisos Descarga el paquete PKG desde GitHub Releases e instálalo en `/Applications/AirPods Voice 输入法.app`. El instalador detiene y elimina automáticamente versiones beta antiguas para evitar que dos versiones asuman el control de los AirPods a la vez. El paquete actual usa firma ad-hoc; si macOS lo bloquea, haz clic derecho en Finder y elige «Abrir». La app debe obtener el permiso de «Accesibilidad» de macOS para simular la pulsación larga de la tecla de voz y enviar Intro. El permiso se concede a la propia app, no hace falta autorizar Terminal ni herramientas de desarrollo, ni se requiere acceso total al disco; la app no captura el micrófono, ya que el permiso de micrófono lo gestiona el método de entrada de voz elegido por el usuario. ## Cómo funciona (según el README) La app mantiene una sesión de Now Playing mediante `MPRemoteCommandCenter` para recibir el clic de los AirPods; solo acepta eventos multimedia cuyo origen sea `com.apple.bluetoothd` o `com.apple.cloudpaird`, por lo que otras fuentes como la tecla de reproducción del teclado no inician la voz. Cuando el micrófono de los AirPods entra en modo de audio de llamada, el segundo clic es reportado por `bluetoothd` como Software Mute, y la app solo lo trata como señal de detener y enviar dentro de su propia sesión de voz ya iniciada. La escucha IOHID actúa como canal de respaldo, y la misma operación física se deduplica mediante una ventana de 350 ms. El primer clic envía una activación de Fn mediante `IOHIDPostEvent`; el segundo clic finaliza la sesión de grabación y envía dos Intro consecutivos: el primero confirma el texto compuesto del método de entrada y el segundo envía el mensaje. Para evitar que las teclas modificadoras globales afecten a apps sensibles a atajos, la versión 1.0 incorpora tres capas de protección: al iniciar se limpian restos históricos de Fn; durante la voz, si se detecta entrada de teclado físico, primero se retira la tecla modificadora de voz y se finaliza la voz de inmediato; si la app termina de forma anómala, un proceso guardián independiente libera Fn. Al detener con normalidad, cambiar de app en primer plano, superar el tiempo de seguridad de 5 minutos o salir de la app, solo se libera la tecla, sin envíos erróneos. ## Configuración y registros El archivo de configuración predeterminado es `config/voice-key`, con contenido `fn`; puede cambiarse a control, option, command, shift o f1–f12, y hay que reiniciar el script tras modificarlo. También puede especificarse temporalmente mediante variables de entorno al ejecutar desde el código fuente. Los registros se encuentran en `/tmp/airpods-voice-input-method/`: app.log, app.stdout.log y app.stderr.log. Puede confirmarse el proceso con `pgrep -fl airpods-voice-input-method` y detenerse de forma segura liberando la tecla de voz con `./scripts/stop.sh`. ## Compilación y pruebas Se incluye `scripts/build.sh` para compilar la app universal y `scripts/package-release.sh` para generar el PKG, con soporte para especificar un certificado Developer ID. Los scripts de prueba cubren escenarios de regresión como cuatro ciclos de interacción de voz, consumo de Fn, seguridad de teclado y recuperación tras fallos; además, `tests/hitl-two-cycle.sh` sirve para la validación manual con AirPods físicos. ## Licencia El código fuente usa la licencia PolyForm Noncommercial 1.0.0, que es source-available y no una licencia de código abierto según la definición de la OSI; se permite el uso personal de aprendizaje, investigación y no comercial, mientras que el uso comercial requiere autorización aparte.