# Risveglio vocale e Premi-per-parlare

# Modalità

• Modalità parola di attivazione (predefinita): il riconoscitore vocale sempre attivo attende i token di attivazione (swabbleTriggerWords). Quando trova una corrispondenza avvia la cattura, mostra l'overlay con il testo parziale e invia automaticamente dopo il silenzio.
• Premi-per-parlare (tieni premuto Opzione destro): tieni premuto il tasto Opzione destro per catturare immediatamente, senza bisogno di attivazione. L'overlay appare mentre il tasto è premuto; il rilascio finalizza e inoltra dopo un breve ritardo, così puoi ritoccare il testo.

# Comportamento a runtime (parola di attivazione)

• Il riconoscitore vocale vive in VoiceWakeRuntime.
• L'attivazione scatta solo quando c'è una pausa significativa tra la parola di attivazione e la parola successiva (intervallo di ~0,55s). L'overlay/il suono possono avviarsi sulla pausa anche prima che il comando inizi.
• Finestre di silenzio: 2,0s quando il parlato è in corso, 5,0s se è stata sentita solo l'attivazione.
• Arresto forzato: 120s per prevenire sessioni fuori controllo.
• Debounce tra sessioni: 350ms.
• L'overlay è controllato tramite VoiceWakeOverlayController con colorazione committed/volatile.
• Dopo l'invio, il riconoscitore si riavvia in modo pulito per ascoltare l'attivazione successiva.

# Invarianti del ciclo di vita

• Se Risveglio vocale è abilitato e i permessi sono concessi, il riconoscitore della parola di attivazione dovrebbe essere in ascolto (tranne durante una cattura esplicita premi-per-parlare).
• La visibilità dell'overlay (inclusa la chiusura manuale tramite il pulsante X) non deve mai impedire al riconoscitore di riprendere.

# Modalità di errore dell'overlay persistente (precedente)

In precedenza, se l'overlay restava bloccato visibile e lo chiudevi manualmente, Risveglio vocale poteva sembrare "morto" perché il tentativo di riavvio del runtime poteva essere bloccato dalla visibilità dell'overlay e non veniva pianificato alcun riavvio successivo.

Irrigidimento:

• Il riavvio del runtime di risveglio non è più bloccato dalla visibilità dell'overlay.
• Il completamento della chiusura dell'overlay attiva un VoiceWakeRuntime.refresh(...) tramite VoiceSessionCoordinator, quindi la chiusura manuale con X riprende sempre l'ascolto.

# Specifiche di premi-per-parlare

• Il rilevamento della scorciatoia usa un monitor globale .flagsChanged per Opzione destro (keyCode 61 + .option). Osserviamo solo gli eventi (senza intercettarli).
• La pipeline di cattura vive in VoicePushToTalk: avvia subito il riconoscimento vocale, trasmette i parziali all'overlay e chiama VoiceWakeForwarder al rilascio.
• Quando premi-per-parlare parte, mettiamo in pausa il runtime della parola di attivazione per evitare tap audio in conflitto; si riavvia automaticamente dopo il rilascio.
• Permessi: richiede Microfono + Riconoscimento vocale; per vedere gli eventi serve l'approvazione di Accessibilità/Monitoraggio input.
• Tastiere esterne: alcune potrebbero non esporre Opzione destro come previsto: offri una scorciatoia alternativa se gli utenti segnalano mancate rilevazioni.

# Impostazioni rivolte all'utente

• Interruttore Risveglio vocale: abilita il runtime della parola di attivazione.
• Tieni premuto Cmd+Fn per parlare: abilita il monitor premi-per-parlare. Disabilitato su macOS < 26.
• Selettori di lingua e microfono, misuratore di livello live, tabella delle parole di attivazione, tester (solo locale; non inoltra).
• Il selettore del microfono conserva l'ultima selezione se un dispositivo si disconnette, mostra un suggerimento di disconnessione e ripiega temporaneamente sul valore predefinito di sistema finché non ritorna.
• Suoni: suoni sull'individuazione dell'attivazione e sull'invio; il valore predefinito è il suono di sistema macOS "Glass". Puoi scegliere qualsiasi file caricabile da NSSound (ad esempio MP3/WAV/AIFF) per ciascun evento oppure scegliere Nessun suono.

# Comportamento di inoltro

• Quando Risveglio vocale è abilitato, le trascrizioni vengono inoltrate al gateway/agente attivo (la stessa modalità locale o remota usata dal resto dell'app Mac).
• Le risposte vengono consegnate all'ultimo provider principale usato (WhatsApp/Telegram/Discord/WebChat). Se la consegna non riesce, l'errore viene registrato e l'esecuzione resta comunque visibile tramite WebChat/log di sessione.

# Payload di inoltro

• VoiceWakeForwarder.prefixedTranscript(_:) antepone il suggerimento della macchina prima dell'invio. Condiviso tra i percorsi parola di attivazione e premi-per-parlare.

# Verifica rapida

• Attiva premi-per-parlare, tieni premuto Cmd+Fn, parla, rilascia: l'overlay dovrebbe mostrare i parziali e poi inviare.
• Mentre tieni premuto, le orecchie nella barra dei menu dovrebbero restare ingrandite (usa triggerVoiceEars(ttl:nil)); si riducono dopo il rilascio.

# Correlati

• Risveglio vocale
• Overlay vocale
• App macOS