chrome.tts

Descrizione

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

Chrome offre questa funzionalità su Windows (con SAPI 5), Mac OS X e ChromeOS, sfruttando le funzionalità di sintesi vocale offerte dal sistema operativo. Su tutte le piattaforme, l'utente può installare estensioni che si registrano come motori vocali alternativi.

Autorizzazioni

tts

Concetti e utilizzo

Genera parlato

Chiama speak() dalla tua estensione per parlare. Ad esempio:

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

Per smettere subito di parlare, chiama stop():

chrome.tts.stop();

Puoi fornire opzioni che controllano varie proprietà del parlato, come frequenza, tono e altro. Ad esempio:

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

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

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

Per impostazione predefinita, ogni chiamata al numero speak() interrompe qualsiasi discorso in corso e parla immediatamente. Per determinare se una chiamata interrompe qualcosa, puoi chiamare isSpeaking(). Inoltre, puoi utilizzare l'opzione enqueue per aggiungere questa frase a una coda di enunciati che verranno pronunciati al termine dell'espressione 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 in tts.speak(). Non tutti i motori di sintesi supportano tutte le opzioni.

Per individuare gli errori e assicurarti di chiamare speak() correttamente, trasmetti una funzione di callback che non accetti 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 inizi a generare voce. Lo scopo del callback è avvisarti degli errori di sintassi nell'utilizzo dell'API TTS, non di rilevare tutti i possibili errori che potrebbero verificarsi durante il processo di sintesi e output del parlato. Per rilevare anche questi errori, devi utilizzare un listener di eventi, descritto nella sezione successiva.

Ascoltare eventi

Per ricevere informazioni più in tempo reale sullo stato della sintesi vocale, passa un listener di eventi nelle opzioni a speak(), come segue:

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 parlato corrente rispetto all'espressione e, per gli eventi di errore, un messaggio di errore facoltativo. I tipi di eventi sono:

  • 'start': il motore ha iniziato a pronunciare l'espressione.
  • 'word': è stato raggiunto un limite di parola. Usa event.charIndex per determinare la posizione attuale del parlato.
  • 'sentence': è stato raggiunto un limite della frase. Usa event.charIndex per determinare la posizione attuale del parlato.
  • 'marker': è stato raggiunto un indicatore SSML. Usa event.charIndex per determinare la posizione attuale del parlato.
  • 'end': il motore ha finito di pronunciare l'espressione.
  • 'interrupted': questa espressione è stata interrotta da un'altra chiamata al numero speak() o stop() e non è stata completata.
  • 'cancelled': questa espressione è stata messa in coda, ma è stata annullata da un'altra chiamata al numero speak() o stop() e non ha mai iniziato a parlare.
  • 'error': si è verificato un errore specifico del motore e questa espressione non può essere pronunciata. Consulta event.errorMessage per i dettagli.

Quattro dei tipi di eventi ('end', 'interrupted', 'cancelled' e 'error') sono finali. Dopo la ricezione di uno di questi eventi, questa enunciata non parlerà più e non saranno ricevuti nuovi eventi di questa frase.

Alcune voci potrebbero non supportare tutti i tipi di evento, mentre altre potrebbero non inviare alcun evento. Se non vuoi utilizzare una voce a meno che non invii determinati eventi, trasmettili nel membro requiredEventTypes dell'oggetto opzioni oppure usa getVoices() per scegliere una voce che soddisfi i tuoi requisiti. Entrambe sono descritte di seguito.

Markup SSML

Le espressioni utilizzate in questa API potrebbero includere il markup che utilizza il Speech Synthesis Markup Language (SSML). Se utilizzi SSML, il primo argomento per 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 riconoscimento vocale supportano tutti i tag SSML e alcuni potrebbero non supportare affatto SSML, ma tutti i motori devono ignorare qualsiasi SSML non supportato e continuare a pronunciare il testo sottostante.

Scegli una voce

Per impostazione predefinita, Chrome sceglie la voce più appropriata per ogni espressione 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 pronunciare qualsiasi testo in almeno una lingua. Tuttavia, alcuni utenti potrebbero avere a disposizione varie voci provenienti dal sistema operativo e dai motori di riconoscimento vocale implementati da altre estensioni di Chrome. In questi casi, puoi implementare codice personalizzato per scegliere la voce appropriata o per presentare all'utente un elenco di opzioni.

Per ottenere un elenco di tutte le voci, chiama getVoices() e trasmettila 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"

TtsEvent

Un evento del motore di sintesi vocale per comunicare lo stato di un'espressione.

Proprietà

  • charIndex

    numero facoltativo

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

  • errorMessage

    stringa facoltativo

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

  • length

    numero facoltativo

    Chrome 74 e versioni successive

    La lunghezza della parte successiva dell'espressione. Ad esempio, in un evento word, questa è la lunghezza della parola che verrà pronunciata dopo. Il valore sarà impostato su -1 se non è impostato dal motore di riconoscimento vocale.

  • Tipo

    EventType

    Il tipo può essere start non appena viene avviata la voce, word quando viene raggiunto il limite di una parola, sentence quando viene raggiunto il limite di una frase, marker quando viene raggiunto un elemento di contrassegno SSML, end quando viene raggiunta la fine dell'espressione vocale, interrupted quando l'espressione viene interrotta prima della fine, cancelled quando viene rimossa dalla coda prima che venga sintetizzata o error quando si verifica qualsiasi altro errore. Quando metti in pausa la conversazione, viene attivato un evento pause se una determinata espressione viene messa in pausa nel mezzo e resume se un'espressione riprende. Tieni presente che gli eventi di messa in pausa e ripresa potrebbero non attivarsi se il parlato viene messo in pausa tra una frase e l'altra.

TtsOptions

Chrome 77 e versioni successive

Le opzioni vocali per il motore di sintesi vocale.

Proprietà

  • desiredEventTypes

    string[] facoltativo

    I tipi di eventi di sintesi vocale che ti interessa ascoltare. Se mancante, possono essere inviati tutti i tipi di eventi.

  • accoda

    booleano facoltativo

    Se il valore è true, mette in coda questa espressione se la sintesi vocale è già in corso. Se il valore è false (valore predefinito), interrompe qualsiasi parlato corrente e svuota la coda della conversazione prima di pronunciare la nuova frase.

  • extensionId

    stringa facoltativo

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

  • gender

    VoiceGender facoltativo

    Obsoleto da Chrome 77

    Il genere è deprecato e verrà ignorato.

    Genere della voce per la sintesi vocale.

  • lang

    stringa facoltativo

    Il linguaggio da utilizzare per la sintesi, nel formato language-region. Esempi: "en", "en-US", "en-GB", "zh-CN".

  • diamante

    numero facoltativo

    Il tono del parlato è compreso tra 0 e 2 inclusi, dove 0 rappresenta il valore più basso e 2 il valore più alto. 1,0 corrisponde al tono predefinito di una voce.

  • velocità di reazione

    numero facoltativo

    Velocità del parlato relativa a quella predefinita per questa voce. 1,0 è la velocità predefinita, normalmente tra 180 e 220 parole al minuto. 2,0 è due volte più veloce e 0,5 è metà più veloce. I valori inferiori a 0,1 o superiori a 10,0 sono severamente vietati, ma molte voci limiteranno ulteriormente la velocità minima e quella massima; ad esempio, una determinata voce potrebbe non parlare più velocemente di tre volte il normale anche se specifichi un valore superiore a 3,0.

  • requiredEventTypes

    string[] facoltativo

    I tipi di eventi di sintesi vocale che la voce deve supportare.

  • voiceName

    stringa facoltativo

    Il nome della voce da utilizzare per la sintesi. Se vuoto, utilizza qualsiasi voce disponibile.

  • volume

    numero facoltativo

    Volume della voce compreso tra 0 e 1 inclusi, dove 0 corrisponde al valore più basso e 1 al valore massimo, con un valore predefinito di 1,0.

  • onEvent

    void facoltativo

    Questa funzione viene richiamata con gli eventi che si verificano nel processo di pronunciamento.

    La funzione onEvent ha il seguente aspetto: 

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

    • event

      TtsEvent

      L'evento di aggiornamento dal motore di sintesi vocale che indica lo stato di questa espressione.

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 facoltativo

    L'ID dell'estensione che fornisce questa voce.

  • gender

    VoiceGender facoltativo

    Deprecata da Chrome 70

    Il genere è deprecato e verrà ignorato.

    Il genere di questa voce.

  • lang

    stringa facoltativo

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

  • telecomando

    booleano facoltativo

    Se il valore è true, il motore di sintesi è una risorsa di rete remota. Potrebbe avere una latenza maggiore e comportare costi per la larghezza di banda.

  • voiceName

    stringa facoltativo

    Il nome della voce.

VoiceGender

Chrome 54 e versioni successive Obsoleto da Chrome 70

Il genere è deprecato e viene ignorato.

Enum

Metodi

getVoices()

Promessa 
chrome.tts.getVoices(
  callback?: function,
)

Recupera un array di tutte le voci disponibili.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (voices: TtsVoice[])=>void

    • voci

      TtsVoice[]

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

Ritorni

  • Promise<TtsVoice[]>

    Chrome 101 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

isSpeaking()

Promessa 
chrome.tts.isSpeaking(
  callback?: function,
)

Controlla se il motore sta parlando. In Mac OS X, il risultato è vero ogni volta che parla il motore di sintesi vocale del sistema, anche se il parlato non è stato avviato da Chrome.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (speaking: boolean)=>void

    • parlare

      boolean

      Vero se si parla, falso negli altri casi.

Ritorni

  • Promise<boolean>

    Chrome 101 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

pause()

chrome.tts.pause()

Mette in pausa la sintesi vocale, potenzialmente nel mezzo di un'espressione. Una chiamata per riprendere o interrompere la chiamata riattiva la conversazione.

resume()

chrome.tts.resume()

Se la voce è stata messa in pausa, riprende a parlare dal punto in cui era stata interrotta.

speak()

Promessa 
chrome.tts.speak(
  utterance: string,
  options?: TtsOptions,
  callback?: function,
)

Pronuncia il testo utilizzando un motore di sintesi vocale.

Parametri

  • enunciato

    stringa

    Il testo da pronunciare, che può essere testo normale o un documento SSML completo e ben strutturato. I motori di riconoscimento vocale che non supportano SSML eliminano i tag e pronunciano il testo. La lunghezza massima del testo è di 32.768 caratteri.

  • opzioni del modello.

    TtsOptions facoltativo

    Le opzioni vocali.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    ()=>void

Ritorni

  • Promise<void>

    Chrome 101 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma vengono forniti callback per garantire la compatibilità con le versioni precedenti. Non puoi utilizzarli entrambi nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo trasmesso al callback.

stop()

chrome.tts.stop()

Interrompe qualsiasi parlato in corso e svuota la coda di eventuali frasi in sospeso. Inoltre, se la voce è stata messa in pausa, verrà riattivata per poter parlare con la chiamata successiva.

Eventi

onVoicesChanged

Chrome 124 e versioni successive 
chrome.tts.onVoicesChanged.addListener(
  callback: function,
)

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

Parametri

  • callback

    funzione

    Il parametro callback ha il seguente aspetto: 

    ()=>void