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.
Autorizzazioni
tts
Panoramica
Chrome offre il supporto nativo per l'audio su Windows (con SAPI 5), Mac OS X e ChromeOS grazie alle funzionalità di sintesi vocale offerte dal sistema operativo. Su tutte le piattaforme, l'utente può installare estensioni che si registrano come motori vocali alternativi.
Generazione voce in corso
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 nella tts.speak
di seguito. 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 di seguito.
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. Usaevent.charIndex
per determinare la posizione attuale del parlato.'sentence'
: è stato raggiunto un limite della frase. Usaevent.charIndex
per determinare la posizione attuale del parlato.'marker'
: è stato raggiunto un indicatore SSML. Usaevent.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 numerospeak()
ostop()
e non è stata completata.'cancelled'
: questa espressione è stata messa in coda, ma è stata annullata da un'altra chiamata al numerospeak()
ostop()
e non ha mai iniziato a parlare.'error'
: si è verificato un errore specifico del motore e questa espressione non può essere pronunciata. Consultaevent.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. Entrambi sono documentati 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.
Scelta di 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
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 successiveLa 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
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 oerror
quando si verifica qualsiasi altro errore. Quando metti in pausa la conversazione, viene attivato un eventopause
se una determinata espressione viene messa in pausa nel mezzo eresume
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
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 77Il 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
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 70Il 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
Il genere è deprecato e viene ignorato.
Enum
Metodi
getVoices()
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
isSpeaking()
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i 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()
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 successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i 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.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