The Text To Speech component uses Web Speech Synthesis
API to queue up and read texts.
Browser Support
The Text To Speech component can be used in browsers that support Web Speech Synthesis
API. At the time of writing, July 26
2016, these browsers include:
- Chrome 31+
- Chrome for Android 40+
- Safari 7.1+
- iOS Safari 7.1+
- MS Edge 14 (in Preview Release)
- Firefox 48+ (using the
media.webspeech.synth.enabled
about:config option)
Note: find the latest browser support data for Web Speech Synthesis API from
caniuse.com.
Creator
Use the following function to create a Text To Speech component:
Method |
fluid.textToSpeech(options);
|
Description |
Instantiate the text to speech component. The methods of the instantiated component can be called to
queue up and read texts.
|
Parameters |
- model.utteranceOpts
-
An optional data structure supplied to the component model that configures the Text To Speech
component behaviour, as described below. As part of the component model, can be managed through
the ChangeApplier API to assist in coordination with other
components.
|
Returns |
The Text To Speech component |
Examples |
var tts = fluid.textToSpeech({
model: {
utteranceOpts: {
volume: 1
}
},
});
|
See also |
model.utteranceOpts Options
|
Supported Methods
queueSpeech
Method |
textToSpeech.queueSpeech(text, interrupt, options);
|
Description |
The queueSpeech method allows you to append text to the end of the queue to
begin speaking after the other texts in the queue have been spoken. Setting the interrupt
argument to true will remove all texts from the queue before adding text to the queue.
|
Parameters |
- text
-
The string of text to be appended to the queue and spoken.
- interrupt
-
An optional boolean value. The default value is false. Setting it to true will remove all texts
from the queue before adding the text. Setting it to false will not affect previously queued
texts.
- options
-
An optional javascript object. Allows for the configuration of the specific
SpeechSynthesisUtterance instance used for this particular text. The configuration
passed in here takes the same form as
model.utteranceOpts
and will override them for
this instance only.
|
Example |
fluid.queueSpeech("Hello world", false, {
volume: 0.5
});
|
cancel
Method |
textToSpeech.cancel();
|
Description |
The cancel method allows you to remove all texts from the queue. If a text is being spoken,
speaking ceases immediately.
|
Parameters |
none |
pause
Method |
textToSpeech.pause();
|
Description |
The pause method allows you to immediately pause any texts that are being spoken.
|
Parameters |
none |
resume
Method |
textToSpeech.resume();
|
Description |
The resume method allows you to resume speaking a text that was previously paused.
|
Parameters |
none |
getVoices
Method |
textToSpeech.getVoices();
|
Description |
The getVoices method allows you to get a list of all the voices that are supported by the
browser. This list is an array of SpeechSynthesisVoice objects. Each of these
SpeechSynthesisVoice objects has a number of attributes:
- name: A human-readable name that describes the voice.
- voiceURI: A URI specifying the location of the speech synthesis service for this voice.
- lang: The language code for this voice.
- default: Set to true if this is the default voice used by the browser.
-
localService: The API can use both local and remote services to handle speech synthesis. If this
attribute is set to true the speech synthesis for this voice is handled by a local service. If
it’s false a remote service is being used. This attribute can be useful if you’re building an
app that needs to work offline. You could use a remote service when an internet connection is
present, and fallback to a local service if a connection is not available.
|
Parameters |
none |
Supported Events
Note: if needed, please read the
Infusion Event System
document for a full description of infusion events.
The events fired by the Text To Speech component are described below.
onStart
Description |
This event fires when texts in the queue have begun to be spoken.
|
Type |
default |
Parameters |
none
|
onStop
Description |
This event fires when the speaking stops, which occurs when all the texts in the queue have been spoken
or the speaking is manually stopped.
|
Type |
default |
Parameters |
none
|
onError
Description |
This event fires when an error occurs that prevents the text from being spoken.
|
Type |
default |
Parameters |
none
|
onSpeechQueued
Description |
This event fires when a text has been queued up to be spoken.
|
Type |
default |
Parameters |
- text
-
The text that has been added to the queue.
|
Model Paths
The following model paths can be used with model listeners based on the current state of the
speech:
model.paused
: true
if a spoken text is currently paused, false
otherwise
model.speaking
: true
if text is being spoken (including in a paused state), false
otherwise
model.pending
: true
if there are text items remaining to be spoken, false
otherwise
model.utteranceOpts Configuration
Configuration of the Text To Speech component can be done through model.utteranceOpts
. This model path is a Javascript
object that contains attributes that users can use to define the behaviour of the SpeechSynthesisUtterance
instance (a part of the web
speech API that the Text To Speech component interacts with).
Note: not all speech synthesizers support all these attributes and some may take different ranges.
These attributes include:
text
Description |
The text attribute allows you to set the text that you wish to be spoken.
Note: be careful with this attribute as it will override any text that was
previously passed.
|
Default |
""
|
Example |
fluid.textToSpeech({
model: {
utteranceOpts: {
text: "Override other texts"
}
}
});
|
lang
Description |
The lang attribute gives you ability to specify a BCP 47 language tag indicating the language of the
voice.
|
Default |
Default to the language of the HTML document.
|
Example |
fluid.textToSpeech({
model: {
utteranceOpts: {
lang: "en-US"
}
}
});
|
voice
Description |
The voice attribute must be a SpeechSynthesisVoice
object that specifies the speech synthesis voice that the web application wishes to use. Calling the getVoices method returns an array of all available voices, from which you can
select a valid SpeechSynthesisVoice , or you can call the SpeechSynthesis.getVoices()
function of the browser directly.
Note: in some browsers (such as Chrome), the voice list is populated after the page
is loaded, and you may need to wait for the voiceschanged
event to get a full list.
|
Default |
Default to the user agent default speech service. It varies depending on the browser configuration.
|
Example |
var availableVoices = SpeechSynthesis.getVoices();
var voiceToUse = availableVoices[0];
fluid.textToSpeech({
model: {
utteranceOpts: {
voice: voiceToUse
}
}
});
|
See also |
Method getVoices()
|
volume
Description |
The volume attribute allows you to adjust the volume of the speech. This is a float value
between 0 and 1.
|
Default |
1
|
Example |
fluid.textToSpeech({
model: {
utteranceOpts: {
volume: 0.5
}
}
});
|
rate
Description |
The rate attribute allows you to define the speed at which the text should be spoken. This
is a float value between 0 and 10.
|
Default |
1
|
Example |
fluid.textToSpeech({
model: {
utteranceOpts: {
rate: 2.5
}
}
});
|
pitch
Description |
The pitch attribute allows you to control how high or low the text is spoken. This is a
float value between 0 and 2.
|
Default |
1
|
Example |
fluid.textToSpeech({
model: {
utteranceOpts: {
pitch: 1.2
}
}
});
|