Gestión del ciclo de vida del Voice Overlay en macOS

¿Alguna vez has intentado manejar dos formas distintas de activar la voz al mismo tiempo? Es un problema común: el usuario activa el wake-word, pero antes de que termine, presiona el hotkey de push-to-talk. Sin una lógica clara, terminas con texto duplicado, overlays que no se cierran o callbacks antiguos que sobrescriben la sesión actual. La mejor forma de evitar este caos es centralizar el control y usar tokens para validar cada evento.

Requisitos previos

• Ser contribuidor de una app para macOS.
• Acceso al sistema de captura de voz y componentes de la interfaz del overlay.

Inicio rápido

Para que el overlay sea predecible, debes implementar un sistema donde el push-to-talk pueda adoptar sesiones existentes y los callbacks antiguos se descarten automáticamente. Sigue estos pasos:

1. Implementar el VoiceSessionCoordinator (actor): Este componente debe gestionar exactamente una VoiceSession a la vez. Utiliza una API basada en tokens con métodos como beginWakeCapture, beginPushToTalk y endCapture.
2. Usar tokens de sesión: Asigna un token único a cada captura. Si llega un callback de un componente antiguo (partial, final, send) con un token que no coincide con la sesión activa, descártalo inmediatamente.
3. Configurar la adopción de texto: Si el usuario presiona el hotkey mientras el overlay del wake-word ya es visible, haz que el push-to-talk mantenga el texto existente como prefijo. Espera hasta 1.5s por una transcripción final antes de continuar con el texto actual.
4. Definir la ruta de envío unificada: Al ejecutar endCapture, si el texto está vacío, descarta el overlay. Si hay texto, ejecuta performSend(session:), activa el chime de envío y cierra la interfaz. Aplica un cooldown corto al terminar para que el wake-word no se reactive por accidente.

Solución de problemas

Si encuentras problemas con overlays que no desaparecen o comportamientos erráticos, revisa estos puntos:

• Logs del sistema: Ejecuta este comando en tu terminal para rastrear los eventos de la sesión y los chimes en tiempo real:

  sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact

• Validación de tokens: Verifica que solo exista un token de sesión activo en el coordinador. Los callbacks antiguos deben ser ignorados para evitar que abridores antiguos reinicien el overlay.
• Cierre de push-to-talk: Asegúrate de que al soltar la tecla de push-to-talk siempre se llame a endCapture con el token activo. Si el texto está vacío, el sistema debe ejecutar dismiss sin enviar nada ni sonar el chime.

AI Setup Assistant

Próximos pasos

• Implementación de VoiceSessionPublisher para SwiftUI.
• Pruebas de integración para la adopción de sesiones y cooldown.