Skip to content

Latest commit

 

History

History
615 lines (563 loc) · 16.8 KB

TextToSpeechAPI.md

File metadata and controls

615 lines (563 loc) · 16.8 KB
title category
Text To Speech API
Components

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

Note: if needed, please read the Component Configuration Options document for a full description of infusion component options.

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
        }
    }
});