Voice Master

Heartbeat.tick() chiede all'host se il riconoscimento è in esecuzione. Quando non lo è, registra il momento del decesso e attende un periodo di tolleranza di 1.5 s prima di chiamare onRevive(), così un normale ciclo di stop/start all'interno di Chrome non viene disturbato.

Un solo riavvio alla volta può essere in corso. Se onstart non arriva entro 3 s, il riavvio in sospeso viene scartato e prima del tentativo successivo inizia un nuovo periodo di tolleranza di 1.5 s. Il flag recognizing viene impostato solo da onstart tramite noteEngineUp(), mai in modo ottimistico, così uno start() fallito (InvalidStateError) non può far credere al watchdog che il motore sia attivo.

Il watchdog conserva l'ora di inizio della sotto-sessione attiva corrente. Dopo sessionMaxMs (270000 ms, impostato in speech.js) chiama refreshSession(), che prima consegna al campo di destinazione la trascrizione finale accumulata e l'ultima frase provvisoria, poi ferma il motore. end() vede che lo stop non era manuale e ritorna senza finalizzare; i tick successivi rianimano una sessione nuova.

L'intervallo è scelto per cadere prima del limite di circa cinque minuti osservato dall'autore in Chrome (indicato nei commenti del codice), così il riavvio avviene in un momento controllato dall'estensione invece che in uno scelto da Chrome.

onend scatta per ogni tipo di stop, quindi end() non può distinguerli da solo. L'host mantiene due flag: manualStop è impostato solo dallo stop dell'utente (pulsante, tasto rapido, chiusura del pannello), fatalError solo dagli errori audio-capture e not-allowed. Il watchdog e reviveRecognition() controllano entrambi e restano inattivi quando uno dei due è impostato; ogni altro errore, come no-speech, lascia la sessione da rianimare.

Per not-allowed il gestore confronta l'ora dell'errore con l'ora del clic: un errore entro 100 ms significa che il permesso è bloccato da una policy, uno successivo significa che l'utente ha negato la richiesta, e il pannello mostra un messaggio diverso per ciascun caso.

RecognitionEngine possiede solo l'oggetto webkitSpeechRecognition (continuo, risultati provvisori, 5 alternative) e analizza i risultati in finalText, interimText e hadFinal. start() lascia deliberatamente propagare InvalidStateError perché il chiamante decida se riprovare.

Flag, accumulo e decisioni di riavvio stanno in speech.js, e la politica dei tempi sta in Heartbeat. Le tre parti comunicano tramite piccole interfacce di callback (isRecognizing, onRevive, onRefresh, onSilence), così il watchdog può essere regolato senza toccare il codice di riconoscimento.

Per input e textarea il valore viene spezzato tra selectionStart e selectionEnd e il cursore viene spostato oltre il nuovo testo, così un frammento selezionato è sostituito da quello dettato. Per contenteditable usa execCommand('insertText'), che sostituisce anch'esso la selezione corrente e fa vedere all'editor una normale modifica. Per TinyMCE chiama il comando mceInsertContent dell'editor stesso.

TinyMCE si inizializza tardi, quindi il suo hook di focus viene collegato dopo un ritardo e, se nient'altro era ancora a fuoco, l'editor attivo viene messo a fuoco e tracciato.

Un listener di focus in fase di capture su document registra ogni elemento idoneo in un elenco con il più recente per ultimo, così quando l'utente fa clic sul pannello la destinazione dell'inserimento è ancora l'ultimo campo in cui si trovava.

Il pulsante di avvio annulla mousedown e i selettori di lingua annullano mouseup, così premerli non toglie il focus al campo. Il pannello trascinabile salta la gestione del trascinamento su input, pulsanti e link perché mantengano il normale comportamento di focus e clic.

I risultati finali si accumulano in finalTranscript. Il testo provvisorio va a un pannello di anteprima trascinabile separato e viene ricordato come prev_text; quando arriva un aggiornamento con la parte provvisoria vuota, buffer() consegna la frase ricordata al campo e svuota l'anteprima.

Lo span finale viene ridisegnato solo quando è arrivato un nuovo risultato finale, il che mantiene basso il lavoro sul DOM durante una dettatura lunga.

Il correttore lato pagina costruisce soltanto il prompt. La richiesta passa attraverso il content script fino al service worker, che possiede il fetch. host_permissions in manifest.json copre api.openai.com, api.anthropic.com, api.deepseek.com e generativelanguage.googleapis.com.

Il listener onMessage del worker restituisce true per tenere aperto il canale per la risposta asincrona.

AI_PROVIDERS descrive ogni API in modo dichiarativo: intestazione Bearer per OpenAI e DeepSeek, x-api-key più intestazioni di versione per Anthropic, x-goog-api-key per Gemini, e il percorso del testo in ogni risposta. aiCorrect() è identica per tutti.

Una chiave vuota restituisce il codice 'no_key' invece di un errore, il che permette ai chiamanti di ripiegare in silenzio sul testo grezzo. Gemini è stato aggiunto come quarto provider con una voce di tabella più un permesso host nel manifest.

LiveImprover.push() accoda ogni frammento a un'unica catena di promise, così il frammento N+1 viene inviato solo dopo che il frammento N è stato inserito. Ogni chiamata corre contro un timeout di 20 s. In caso di errore o timeout viene inserito il testo originale, così il parlato dettato non va mai perso.

I modelli restituiscono testo senza spazi ai margini, quindi keepSpacing() ripristina gli spazi iniziali e finali originali del frammento per evitare che frammenti consecutivi si attacchino. Senza chiave la coda segnala il codice 'no_key' e l'interfaccia resta in silenzio, come se la modalità live fosse spenta.

Il codice del pannello gira come module script nella pagina e non ha API chrome.*. GptCorrector.improve() assegna un id di sequenza, memorizza il resolver in una Map e invia stt_ai_correct_request. Il content script lo inoltra al worker e risponde con stt_ai_correct_response che porta lo stesso id, il quale risolve esattamente una promise in sospeso.

Il prompt corr_and_return afferma che il testo proviene da un riconoscitore vocale imperfetto, chiede al modello di sostituire le parole riconosciute male con ciò che chi parla intendeva più probabilmente, di mantenere lingua e significato, di non aggiungere nulla e di restituire solo il testo. È tradotto in ogni locale dell'interfaccia.

Nel pannello di dettatura il testo migliorato sostituisce il contenuto della textarea tramite execCommand('insertText'), così Ctrl+Z ripristina la versione originale.

sttCryptoKey() genera il segreto una volta, lo memorizza e lo importa come CryptoKey non estraibile. I valori cifrati portano un prefisso di versione (stt1:) seguito da IV e testo cifrato in base64.

La crittografia gira nel service worker perché esso è sempre un contesto sicuro con crypto.subtle, mentre un content script su una pagina http semplice non lo è. Il commento nel codice è esplicito nel dire che si tratta di una protezione a riposo contro letture casuali, non contro chi ha l'intero profilo del browser.

sttPublicCfg() è l'unica forma che passa nella pagina: provider, flag live, un booleano per provider e un indizio come i primi 3 e gli ultimi 4 caratteri. Il modulo delle impostazioni non riceve mai la chiave memorizzata; un campo non toccato al Salvataggio significa mantenere la chiave memorizzata (flag keyTouched).

sttGetAi() sposta la vecchia gptApiKey singola nella struttura per provider, cifra ogni valore senza il prefisso stt1:, riscrive il risultato e rimuove la cella legacy. Se il worker non riesce a cifrare, il testo in chiaro viene mantenuto così l'utente non resta bloccato fuori, e la migrazione viene ritentata alla lettura successiva.

sttDecrypt() restituisce una stringa vuota su un valore corrotto o estraneo, così un record rotto si comporta come 'nessuna chiave' invece di generare un'eccezione.

Il pannello di ogni scheda conserva uno specchio locale di provider, flag live e hasKeys. content.js ascolta chrome.storage.onChanged per il record sttAi e invia alla pagina una nuova configurazione sanitizzata, così liveEnabled() non agisce mai su una chiave che è stata eliminata altrove.

Eliminare una chiave nel popover è un'azione locale fino a Salva; chiudere senza salvare mantiene la chiave memorizzata.

start() nel service worker invia l'attivazione alla scheda. Se chrome.runtime.lastError mostra che nessuno è in ascolto, inietta content.js e ripete il messaggio. Il modulo del pannello e il foglio di stile vengono poi iniettati su richiesta, saltando le pagine chrome://.

Il popup controlla allo stesso modo con un ping isLoaded prima di decidere se inviare il messaggio alla scheda o passare dal worker.

getLocalizationKeys() legge l'elenco delle chiavi dal messages.json della locale predefinita, che ha l'insieme completo, poi memorizza chrome.i18n.getMessage(key) per ciascuna con prefisso stt_. Helper.getI18nMessage() nella pagina legge da lì.

Poiché l'elenco delle chiavi proviene da en e i valori da chrome.i18n, una locale con chiavi mancanti ripiega sull'inglese chiave per chiave. La locale hi al momento manca di 7 chiavi ed è coperta in questo modo.