Configuración de Voice Wake y Push-to-Talk

A veces, escribir comandos rompe el ritmo de trabajo. Quieres hablar y que las cosas pasen, pero configurar un sistema de voz que no falle y que sepa exactamente cuándo escucharte es un reto técnico real. Gestionar los estados del micrófono y la interfaz sin que el sistema se bloquee requiere una integración limpia.

What You’ll Need

• Permisos de Microphone y Speech otorgados.
• Aprobación de Accessibility e Input Monitoring para detectar eventos de teclado.
• macOS 26 o superior (necesario para el atajo Cmd+Fn).
• Un Gateway o agente activo configurado en la app.

Quick Start

Sigue estos pasos para activar la captura de voz en menos de 5 minutos:

1. Activa Voice Wake: Enciende el interruptor de Voice Wake en los settings para iniciar el VoiceWakeRuntime. Por defecto, usará las palabras definidas en swabbleTriggerWords.
2. Configura el Trigger: Habla usando tu palabra de activación. El sistema necesita una pausa de ~0.55s entre el trigger y tu comando para empezar a capturar.
3. Usa Push-to-Talk: Si prefieres no usar triggers, mantén presionada la tecla Right Option (keyCode 61). El VoicePushToTalk pausará el runtime de wake-word para evitar conflictos de audio.
4. Verifica el envío: Una vez que termines de hablar o sueltes la tecla, el VoiceWakeForwarder enviará el transcript al último proveedor usado (WhatsApp, Telegram, Discord o WebChat).

Troubleshooting

• La voz parece “muerta” tras cerrar el overlay: Si cierras el overlay manualmente con el botón X, el VoiceSessionCoordinator ahora ejecuta un VoiceWakeRuntime.refresh(...). Esto garantiza que el sistema siga escuchando sin bloquearse.
• El teclado externo no activa el Push-to-Talk: Algunos teclados no exponen la tecla Option derecha como se espera. Si esto sucede, utiliza el atajo alternativo Cmd+Fn en los settings.
• La captura se detiene antes de tiempo: El sistema tiene una ventana de silencio de 2.0s durante el habla fluida y de 5.0s si solo se detectó el trigger. Existe un hard stop de 120s para evitar sesiones infinitas.
• Fallo en la entrega del mensaje: Si el transcript no llega a tu Gateway, revisa los logs de WebChat. El error se registrará allí, aunque la sesión sea visible en el historial.

AI Setup Assistant

What’s Next

• Configuración de VoiceWakeOverlayController
• Personalización de sonidos con NSSound
• Gestión de estados en VoiceSessionCoordinator
• Guía de VoiceWakeForwarder y payloads de transcripción