chrome.tts

refresh date: 2026-09-25 robots: noindex

Descrizione

Utilizza l'API chrome.tts per riprodurre la sintesi vocale (TTS) sintetizzata. Consulta anche l'API ttsEngine correlata, che consente a un'estensione di implementare un motore di sintesi vocale.

Autorizzazioni

tts

Panoramica

Chrome fornisce il supporto nativo per la sintesi vocale su Windows (utilizzando SAPI 5), Mac OS X e ChromeOS, utilizzando le funzionalità di sintesi vocale fornite dal sistema operativo. Su tutte le piattaforme, l'utente può installare estensioni che si registrano come motori di sintesi vocale alternativi.

Generazione di parlato

Chiama speak() dal tuo interno per parlare. Ad esempio:

chrome.tts.speak('Hello, world.');

Per interrompere immediatamente la lettura, chiama stop():

chrome.tts.stop();

Puoi fornire opzioni che controllano varie proprietà del parlato, come la velocità, il tono e altro ancora. Ad esempio:

chrome.tts.speak('Hello, world.', {'rate': 2.0});

È inoltre consigliabile specificare la lingua in modo che venga scelto un sintetizzatore che la supporti (e il dialetto regionale, se applicabile).

chrome.tts.speak('Hello, world.', {'lang': 'en-US', 'rate': 2.0});

Per impostazione predefinita, ogni chiamata a speak() interrompe qualsiasi discorso in corso e parla immediatamente. Per determinare se una chiamata interromperebbe qualcosa, puoi chiamare isSpeaking(). Inoltre, puoi utilizzare l'opzione enqueue per aggiungere questo enunciato a una coda di enunciati che verranno pronunciati al termine dell'enunciato corrente.

chrome.tts.speak('Speak this first.');
chrome.tts.speak(
    'Speak this next, when the first sentence is done.', {'enqueue': true});

Una descrizione completa di tutte le opzioni è disponibile nella tts.speak di seguito. Non tutti i motori di sintesi vocale supportano tutte le opzioni.

Per rilevare gli errori e assicurarti di chiamare speak() correttamente, passa una funzione di callback che non accetta argomenti. All'interno del callback, controlla runtime.lastError per vedere se si sono verificati errori.

chrome.tts.speak(
  utterance,
  options,
  function() {
    if (chrome.runtime.lastError) {
      console.log('Error: ' + chrome.runtime.lastError.message);
    }
  }
);

Il callback viene restituito immediatamente, prima che il motore abbia iniziato a generare la voce. Lo scopo del callback è avvisarti di errori di sintassi nell'utilizzo dell'API TTS, non di rilevare tutti i possibili errori che potrebbero verificarsi nel processo di sintesi e output del parlato. Per rilevare anche questi errori, devi utilizzare un listener di eventi, descritto di seguito.

In ascolto di eventi

Per ricevere maggiori informazioni in tempo reale sullo stato della sintesi vocale, passa un listener di eventi nelle opzioni a speak(), in questo modo:

chrome.tts.speak(
  utterance,
  {
    onEvent: function(event) {
      console.log('Event ' + event.type + ' at position ' + event.charIndex);
      if (event.type == 'error') {
        console.log('Error: ' + event.errorMessage);
      }
    }
  },
  callback
);

Ogni evento include un tipo di evento, l'indice dei caratteri del discorso corrente relativo all'enunciato e, per gli eventi di errore, un messaggio di errore facoltativo. I tipi di eventi sono:

  • '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.
  • 'interrupted': questa espressione è stata interrotta da un'altra chiamata a speak() o stop() e non è stata completata.
  • 'cancelled': questa frase è stata messa in coda, ma poi annullata da un'altra chiamata a speak() o stop() e non è mai stata pronunciata.
  • 'error': si è verificato un errore specifico del motore e non è possibile pronunciare questo enunciato. Per i dettagli, visita la pagina event.errorMessage.

Quattro dei tipi di eventi, 'end', 'interrupted', 'cancelled' e 'error', sono finali. Dopo la ricezione di uno di questi eventi, questo enunciato non verrà più pronunciato e non verranno ricevuti nuovi eventi da questo enunciato.

Alcune voci potrebbero non supportare tutti i tipi di eventi e altre potrebbero non inviare alcun evento. Se non vuoi utilizzare una voce a meno che non invii determinati eventi, passa gli eventi richiesti nel membro requiredEventTypes dell'oggetto options o utilizza getVoices() per scegliere una voce che soddisfi i tuoi requisiti. Entrambe le modalità sono documentate di seguito.

Markup SSML

Le espressioni utilizzate in questa API possono includere il markup utilizzando il linguaggio di markup della sintesi vocale (SSML). Se utilizzi SSML, il primo argomento di speak() deve essere un documento SSML completo con un'intestazione XML e un tag <speak> di primo livello, non un frammento di documento.

Ad esempio:

chrome.tts.speak(
  '<?xml version="1.0"?>' +
  '<speak>' +
  '  The <emphasis>second</emphasis> ' +
  '  word of this sentence was emphasized.' +
  '</speak>'
);

Non tutti i motori di sintesi vocale supportano tutti i tag SSML e alcuni potrebbero non supportare affatto SSML, ma tutti i motori devono ignorare qualsiasi SSML non supportato e pronunciare comunque il testo sottostante.

Scelta di una voce

Per impostazione predefinita, Chrome sceglie la voce più appropriata per ogni frase che vuoi pronunciare, in base alla lingua. Sulla maggior parte dei sistemi Windows, Mac OS X e ChromeOS, la sintesi vocale fornita dal sistema operativo dovrebbe essere in grado di leggere qualsiasi testo in almeno una lingua. Tuttavia, alcuni utenti potrebbero avere a disposizione una varietà di voci dal proprio sistema operativo e dai motori di sintesi vocale implementati da altre estensioni di Chrome. In questi casi, puoi implementare un codice personalizzato per scegliere la voce appropriata o per presentare all'utente un elenco di scelte.

Per ottenere un elenco di tutte le voci, chiama getVoices() e passagli una funzione che riceve un array di oggetti TtsVoice come argomento:

chrome.tts.getVoices(
  function(voices) {
    for (var i = 0; i < voices.length; i++) {
      console.log('Voice ' + i + ':');
      console.log('  name: ' + voices[i].voiceName);
      console.log('  lang: ' + voices[i].lang);
      console.log('  extension id: ' + voices[i].extensionId);
      console.log('  event types: ' + voices[i].eventTypes);
    }
  }
);

Tipi

EventType

Chrome 54 e versioni successive

Enum

"start"

"end"

"word"

"sentence"

"marker"

"interrupted"

"cancelled"

"error"

"pause"

"riprendi"

TtsEvent

Un evento del motore TTS per comunicare lo stato di un enunciato.

Proprietà

  • charIndex

    number optional

    L'indice del carattere corrente nell'enunciato. Per gli eventi di parole, l'evento viene attivato alla fine di una parola e prima dell'inizio della successiva. charIndex rappresenta un punto nel testo all'inizio della parola successiva da pronunciare.

  • errorMessage

    stringa facoltativa

    La descrizione dell'errore, se il tipo di evento è error.

  • lunghezza

    number optional

    Chrome 74 e versioni successive

    La lunghezza della parte successiva dell'enunciato. Ad esempio, in un evento word, questa è la lunghezza della parola che verrà pronunciata successivamente. Se non viene impostato dal motore di sintesi vocale, il valore sarà -1.

  • tipo

    EventType

    Il tipo può essere start non appena inizia il parlato, word quando viene raggiunto un limite di parola, sentence quando viene raggiunto un limite di frase, marker quando viene raggiunto un elemento di contrassegno SSML, end quando viene raggiunta la fine dell'enunciato, interrupted quando l'enunciato viene interrotto o sospeso prima di raggiungere la fine, cancelled quando viene rimosso dalla coda prima di essere sintetizzato o error quando si verifica un altro errore. Quando metti in pausa la sintesi vocale, viene attivato un evento pause se un determinato enunciato viene messo in pausa nel mezzo e resume se un enunciato riprende la sintesi vocale. Tieni presente che gli eventi di pausa e ripresa potrebbero non essere attivati se la sintesi vocale viene messa in pausa tra un enunciato e l'altro.

TtsOptions

Chrome 77 e versioni successive

Le opzioni di sintesi vocale per il motore TTS.

Proprietà

  • desiredEventTypes

    string[] facoltativo

    I tipi di eventi TTS che ti interessa ascoltare. Se non viene specificato, potrebbero essere inviati tutti i tipi di eventi.

  • enqueue

    boolean facoltativo

    Se true, mette in coda questo enunciato se la sintesi vocale è già in corso. Se impostato su false (impostazione predefinita), interrompe l'eventuale parlato in corso e svuota la coda del parlato prima di pronunciare questo nuovo enunciato.

  • extensionId

    stringa facoltativa

    L'ID estensione del motore di sintesi vocale da utilizzare, se noto.

  • gender

    VoiceGender facoltativo

    Ritirato da Chrome 77

    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 una 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à. I valori inferiori a 0,1 o superiori a 10,0 non sono assolutamente consentiti, ma molte voci limiteranno ulteriormente le velocità minime e massime. Ad esempio, una determinata voce potrebbe non parlare effettivamente più velocemente di 3 volte il normale anche se specifichi un valore superiore a 3,0.

  • requiredEventTypes

    string[] facoltativo

    I tipi di eventi TTS che la voce deve supportare.

  • voiceName

    stringa facoltativa

    Il nome della voce da utilizzare per la sintesi. Se il campo è vuoto, viene utilizzata qualsiasi voce disponibile.

  • 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.

  • onEvent

    void optional

    Questa funzione viene chiamata con gli eventi che si verificano durante il processo di pronuncia dell'enunciato.

    La funzione onEvent ha il seguente aspetto: 

    (event: TtsEvent) => {...}

    • evento

      TtsEvent

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

TtsVoice

Una descrizione di una voce disponibile per la sintesi vocale.

Proprietà

  • eventTypes

    EventType[] facoltativo

    Tutti i tipi di eventi di callback che questa voce è in grado di inviare.

  • extensionId

    stringa facoltativa

    L'ID dell'estensione che fornisce questa voce.

  • gender

    VoiceGender facoltativo

    Ritirato da Chrome 70

    Il genere è deprecato e verrà ignorato.

    Il genere di questa voce.

  • lang

    stringa facoltativa

    La lingua supportata da questa voce, nel formato lingua-regione. Esempi: "en", "en-US", "en-GB", "zh-CN".

  • telecomando

    boolean facoltativo

    Se il valore è true, il motore di sintesi è una risorsa di rete remota. Potrebbe avere una latenza più elevata e comportare costi di larghezza di banda.

  • voiceName

    stringa facoltativa

    Il nome della voce.

VoiceGender

Chrome 54 e versioni successive Ritirato da Chrome 70

Il genere è deprecato e viene ignorato.

Enum

"male"

"female"

Metodi

getVoices()

Promise 
chrome.tts.getVoices(
  callback?: function,
): Promise<TtsVoice[]>

Restituisce un array di tutte le voci disponibili.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (voices: TtsVoice[]) => void

    • voci

      TtsVoice[]

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

Resi

  • Promise<TtsVoice[]>

    Chrome 101 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

isSpeaking()

Promise 
chrome.tts.isSpeaking(
  callback?: function,
): Promise<boolean>

Controlla se il motore sta parlando. Su Mac OS X, il risultato è true ogni volta che il motore di sintesi vocale del sistema sta parlando, anche se la sintesi vocale non è stata avviata da Chrome.

Parametri

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    (speaking: boolean) => void

    • speaking

      booleano

      True se l'utente sta parlando, altrimenti False.

Resi

  • Promise<boolean>

    Chrome 101 e versioni successive

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

pause()

chrome.tts.pause(): void

Mette in pausa la sintesi vocale, potenzialmente nel mezzo di un enunciato. Un comando per riprendere o interrompere la lettura vocale annullerà la pausa.

resume()

chrome.tts.resume(): void

Se la lettura vocale è stata messa in pausa, riprende da dove era stata interrotta.

speak()

Promise 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
): Promise<void>

Pronuncia il testo utilizzando un motore di sintesi vocale.

Parametri

  • utterance

    stringa

    Il testo da pronunciare, in formato testo normale o un documento SSML completo e ben formato. I motori di sintesi vocale che non supportano SSML rimuoveranno i tag e leggeranno il testo. La lunghezza massima del testo è di 32.768 caratteri.

  • opzioni

    TtsOptions facoltativo

    Le opzioni di sintesi vocale.

  • callback

    funzione elemento facoltativo

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 101 e versioni successive

    Viene risolto immediatamente, prima che l'utente finisca di parlare. Se si verifica un errore, la promise verrà rifiutata. Utilizza options.onEvent per ricevere un feedback più dettagliato.

    Le promise sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

stop()

chrome.tts.stop(): void

Interrompe l'eventuale sintesi vocale in corso e svuota la coda di eventuali espressioni in attesa. Inoltre, se la sintesi vocale era stata messa in pausa, verrà riattivata per la chiamata successiva.

Eventi

onVoicesChanged

Chrome 124+ 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

Viene chiamato quando l'elenco di tts.TtsVoice che verrebbe restituito da getVoices è cambiato.

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    () => void