chrome.ttsEngine

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.ttsEngine per implementare un motore di sintesi vocale(TTS) utilizzando un'estensione. Se la tua estensione si registra utilizzando questa API, riceverà eventi contenenti un'espressione da pronunciare e altri parametri quando un'estensione o un'app di Chrome utilizza l'API tts per generare la sintesi vocale. L'estensione può quindi utilizzare qualsiasi tecnologia web disponibile per sintetizzare e generare l'output vocale e inviare eventi alla funzione chiamante per segnalare lo stato.

Autorizzazioni

ttsEngine

Panoramica

Un'estensione può registrarsi come motore di sintesi vocale. In questo modo, può intercettare alcune o tutte le chiamate a funzioni come tts.speak e tts.stop e fornire un'implementazione alternativa. Le estensioni possono utilizzare qualsiasi tecnologia web disponibile per fornire la sintesi vocale, incluso l'audio in streaming da un server e l'audio HTML5. Un'estensione potrebbe anche fare qualcosa di diverso con gli enunciati, ad esempio visualizzare i sottotitoli codificati in una finestra popup o inviarli come messaggi di log a un server remoto.

Manifest

Per implementare un motore TTS, un'estensione deve dichiarare l'autorizzazione "ttsEngine" e poi dichiarare tutte le voci che fornisce nel manifest dell'estensione, in questo modo:

{
  "name": "My TTS Engine",
  "version": "1.0",
  "permissions": ["ttsEngine"],
  "tts_engine": {
    "voices": [
      {
        "voice_name": "Alice",
        "lang": "en-US",
        "event_types": ["start", "marker", "end"]
      },
      {
        "voice_name": "Pat",
        "lang": "en-US",
        "event_types": ["end"]
      }
    ]
  },
  "background": {
    "page": "background.html",
    "persistent": false
  }
}

Un'estensione può specificare un numero qualsiasi di voci.

Il parametro voice_name è obbligatorio. Il nome deve essere sufficientemente descrittivo da identificare il nome della voce e il motore utilizzato. Nell'improbabile caso in cui due estensioni registrino voci con lo stesso nome, un client può specificare l'ID dell'estensione che deve eseguire la sintesi.

Il parametro lang è facoltativo, ma vivamente consigliato. Quasi sempre, una voce può sintetizzare il parlato in una sola lingua. Quando un motore supporta più di una lingua, può facilmente registrare una voce separata per ogni lingua. Nelle rare circostanze in cui una singola voce può gestire più di una lingua, è più semplice elencare due voci separate e gestirle utilizzando la stessa logica internamente. Tuttavia, se vuoi creare una voce che gestisca gli enunciati in qualsiasi lingua, ometti il parametro lang dal manifest dell'estensione.

Infine, il parametro event_types è obbligatorio se il motore può inviare eventi per aggiornare il client sullo stato di avanzamento della sintesi vocale. Come minimo, è vivamente consigliato supportare il tipo di evento 'end' per indicare quando la sintesi vocale è terminata, altrimenti Chrome non può pianificare le espressioni in coda.

Una volta caricata, un'estensione può sostituire l'elenco delle voci dichiarate chiamando chrome.ttsEngine.updateVoices. (Tieni presente che i parametri utilizzati nella chiamata programmatica a updateVoices sono in notazione a cammello, ad esempio voiceName, a differenza del file manifest che utilizza voice_name.)

I possibili tipi di eventi che puoi inviare corrispondono ai tipi di eventi ricevuti dal metodo speak():

  • 'start': il motore ha iniziato a pronunciare l'enunciato.
  • 'word': è stato raggiunto un confine di parola. Utilizza event.charIndex per determinare la posizione corrente della sintesi vocale.
  • 'sentence': è stato raggiunto un limite di frase. Utilizza event.charIndex per determinare la posizione corrente della sintesi vocale.
  • 'marker': è stato raggiunto un indicatore SSML. Utilizza event.charIndex per determinare la posizione corrente della sintesi vocale.
  • 'end': il motore ha terminato la pronuncia dell'enunciato.
  • 'error': si è verificato un errore specifico del motore e non è possibile pronunciare questo enunciato. Passa più informazioni in event.errorMessage.

Gli eventi 'interrupted' e 'cancelled' non vengono inviati dal motore di sintesi vocale, ma vengono generati automaticamente da Chrome.

I client di sintesi vocale possono ottenere le informazioni sulla voce dal manifest dell'estensione chiamando tts.getVoices, a condizione che tu abbia registrato i listener di eventi di sintesi vocale come descritto di seguito.

Gestione degli eventi vocali

Per generare la sintesi vocale su richiesta dei client, l'estensione deve registrare i listener sia per onSpeak sia per onStop, in questo modo:

const speakListener = (utterance, options, sendTtsEvent) => {
  sendTtsEvent({type: 'start', charIndex: 0})

  // (start speaking)

  sendTtsEvent({type: 'end', charIndex: utterance.length})
};

const stopListener = () => {
  // (stop all speech)
};

chrome.ttsEngine.onSpeak.addListener(speakListener);
chrome.ttsEngine.onStop.addListener(stopListener);

La decisione di inviare o meno una determinata richiesta di sintesi vocale a un'estensione si basa esclusivamente sul fatto che l'estensione supporti i parametri vocali specificati nel suo manifest e abbia registrato listener per onSpeak e onStop. In altre parole, non esiste un modo per un'estensione di ricevere una richiesta di sintesi vocale e decidere dinamicamente se gestirla.

Tipi

AudioBuffer

Chrome 92 e versioni successive

Parametri contenenti un buffer audio e i dati associati.

Proprietà

  • audioBuffer

    ArrayBuffer

    Il buffer audio del motore di sintesi vocale. Deve avere una lunghezza esattamente pari a audioStreamOptions.bufferSize ed essere codificato come mono, con audioStreamOptions.sampleRate e come PCM lineare, float con segno a 32 bit, ovvero il tipo Float32Array in JavaScript.

  • charIndex

    number optional

    L'indice dei caratteri associato a questo buffer audio.

  • isLastBuffer

    boolean facoltativo

    True se questo buffer audio è l'ultimo per il testo pronunciato.

AudioStreamOptions

Chrome 92 e versioni successive

Contiene il formato dello stream audio che dovrebbe essere prodotto da un motore.

Proprietà

  • bufferSize

    numero

    Il numero di campioni all'interno di un buffer audio.

  • sampleRate

    numero

    La frequenza di campionamento prevista in un buffer audio.

LanguageInstallStatus

Chrome 132+

Lo stato di installazione di una voce.

Enum

"notInstalled"

"installing"

"installed"

"failed"

LanguageStatus

Chrome 132+

Stato di installazione di una lingua.

Proprietà

  • errore

    stringa facoltativa

    Dettagli sugli errori di installazione. Compilato facoltativamente se l'installazione della lingua non è riuscita.

  • installStatus

    LanguageInstallStatus

    Stato dell'installazione.

  • lang

    stringa

    Stringa della lingua nel formato codice lingua-codice regione, dove la regione può essere omessa. Esempi: en, en-AU, zh-CH.

LanguageUninstallOptions

Chrome 132+

Opzioni per la disinstallazione di una determinata lingua.

Proprietà

  • uninstallImmediately

    booleano

    True se il client TTS vuole che la lingua venga disinstallata immediatamente. Il motore può scegliere se o quando disinstallare la lingua, in base a questo parametro e alle informazioni del richiedente. Se impostato su false, potrebbe utilizzare altri criteri, ad esempio l'utilizzo recente, per determinare quando disinstallare.

SpeakOptions

Chrome 92 e versioni successive

Opzioni specificate per il metodo tts.speak().

Proprietà

  • gender

    VoiceGender facoltativo

    Ritirato da Chrome 92

    Il genere è deprecato e verrà ignorato.

    Genere della voce per la sintesi vocale.

  • lang

    stringa facoltativa

    La lingua da utilizzare per la sintesi, nel formato lingua-regione. Esempi: "en", "en-US", "en-GB", "zh-CN".

  • diamante

    number optional

    Tonalità della voce compresa tra 0 e 2 inclusi, dove 0 è la più bassa e 2 è la più alta. 1.0 corrisponde al tono predefinito di questa voce.

  • velocità di reazione

    number optional

    Velocità di pronuncia rispetto alla velocità predefinita per questa voce. 1.0 è la velocità predefinita, normalmente compresa tra 180 e 220 parole al minuto. 2.0 è il doppio della velocità e 0.5 è la metà della velocità. Questo valore è garantito essere compreso tra 0,1 e 10,0 inclusi. Quando una voce non supporta l'intera gamma di velocità, non restituire un errore. Invece, limita la velocità all'intervallo supportato dalla voce.

  • voiceName

    stringa facoltativa

    Il nome della voce da utilizzare per la sintesi.

  • volume

    number optional

    Volume della voce compreso tra 0 e 1 inclusi, dove 0 è il volume più basso e 1 è il volume più alto, con un valore predefinito di 1,0.

TtsClient

Chrome 131+

Identificatore del client che richiede lo stato.

Proprietà

  • id

    stringa

    Client che effettua una richiesta di gestione della lingua. Per un'estensione, si tratta dell'ID estensione univoco. Per le funzionalità di Chrome, si tratta del nome leggibile della funzionalità.

  • origine

    TtsClientSource

    Tipo di richiedente.

TtsClientSource

Chrome 131+

Tipo di richiedente.

Enum

"chromefeature"

"extension"

VoiceGender

Chrome 54 e versioni successive Ritirato da Chrome 70

Il genere è deprecato e verrà ignorato.

Enum

"male"

"female"

Metodi

updateLanguage()

Chrome 132+ 
chrome.ttsEngine.updateLanguage(
  status: LanguageStatus,
): void

Chiamato da un motore quando viene tentata l'installazione di una lingua e quando una lingua viene disinstallata. Viene chiamato anche in risposta a una richiesta di stato da un client. Quando una voce viene installata o disinstallata, il motore deve anche chiamare ttsEngine.updateVoices per registrarla.

Parametri

updateVoices()

Chrome 66 e versioni successive 
chrome.ttsEngine.updateVoices(
  voices: TtsVoice[],
): void

Chiamato da un motore per aggiornare il suo elenco di voci. Questo elenco sostituisce le voci dichiarate nel manifest di questa estensione.

Parametri

  • voci

    TtsVoice[]

    Array di oggetti tts.TtsVoice che rappresentano le voci disponibili per la sintesi vocale.

Eventi

onInstallLanguageRequest

Chrome 131+ 
chrome.ttsEngine.onInstallLanguageRequest.addListener(
  callback: function,
)

Attivato quando un client TTS richiede l'installazione di una nuova lingua. Il motore deve tentare di scaricare e installare la lingua e chiamare ttsEngine.updateLanguage con il risultato. In caso di esito positivo, il motore deve anche chiamare ttsEngine.updateVoices per registrare le voci appena disponibili.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (requestor: TtsClient, lang: string) => void

onLanguageStatusRequest

Chrome 132+ 
chrome.ttsEngine.onLanguageStatusRequest.addListener(
  callback: function,
)

Attivato quando un client TTS richiede lo stato di installazione di una lingua.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (requestor: TtsClient, lang: string) => void

onPause

chrome.ttsEngine.onPause.addListener(
  callback: function,
)

(Facoltativo) Se un motore supporta l'evento di pausa, deve mettere in pausa l'enunciato corrente, se presente, finché non riceve un evento di ripresa o di interruzione. Tieni presente che un evento di interruzione deve anche cancellare lo stato di pausa.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onResume

chrome.ttsEngine.onResume.addListener(
  callback: function,
)

Facoltativo: se un motore supporta l'evento di pausa, deve supportare anche l'evento di ripresa, per continuare a pronunciare l'enunciato corrente, se presente. Tieni presente che un evento di interruzione deve anche cancellare lo stato di pausa.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onSpeak

chrome.ttsEngine.onSpeak.addListener(
  callback: function,
)

Viene richiamato quando l'utente effettua una chiamata a tts.speak() e una delle voci del manifest di questa estensione è la prima a corrispondere all'oggetto options.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (utterance: string, options: SpeakOptions, sendTtsEvent: function) => void

    • utterance

      stringa

    • opzioni

      SpeakOptions

    • sendTtsEvent

      funzione

      Il parametro sendTtsEvent ha il seguente aspetto: 

      (event: tts.TtsEvent) => void

      • evento

        tts.TtsEvent

        L'evento del motore di sintesi vocale che indica lo stato di questo enunciato.

onSpeakWithAudioStream

Chrome 92 e versioni successive 
chrome.ttsEngine.onSpeakWithAudioStream.addListener(
  callback: function,
)

Viene richiamato quando l'utente effettua una chiamata a tts.speak() e una delle voci del manifest di questa estensione è la prima a corrispondere all'oggetto options. Si differenzia da ttsEngine.onSpeak in quanto Chrome fornisce servizi di riproduzione audio e gestisce l'invio di eventi tts.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    (utterance: string, options: SpeakOptions, audioStreamOptions: AudioStreamOptions, sendTtsAudio: function, sendError: function) => void

    • utterance

      stringa

    • opzioni

      SpeakOptions

    • audioStreamOptions

      AudioStreamOptions

    • sendTtsAudio

      funzione

      Il parametro sendTtsAudio ha il seguente aspetto: 

      (audioBufferParams: AudioBuffer) => void

      • audioBufferParams

        AudioBuffer

        Parametri contenenti un buffer audio e i dati associati.

    • sendError

      funzione

      Chrome 94 e versioni successive

      Il parametro sendError ha il seguente aspetto: 

      (errorMessage?: string) => void

      • errorMessage

        stringa facoltativa

        Una stringa che descrive l'errore.

onStop

chrome.ttsEngine.onStop.addListener(
  callback: function,
)

Attivato quando viene effettuata una chiamata a tts.stop e questa estensione potrebbe essere in fase di lettura. Se un'estensione riceve una chiamata a onStop e la sintesi vocale è già interrotta, non deve fare nulla (non deve generare un errore). Se la sintesi vocale è in pausa, questa azione dovrebbe annullare lo stato di pausa.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void

onUninstallLanguageRequest

Chrome 132+ 
chrome.ttsEngine.onUninstallLanguageRequest.addListener(
  callback: function,
)

Attivato quando un client TTS indica che una lingua non è più necessaria.

Parametri