SpeechSynthesis
Namespace: Wisej.Web.Ext.Speech
Assembly: Wisej.Web.Ext.Speech (4.1.0.0)
Represents a component that uses the SpeechSynthesis interface of the Web Speech API to speak text in the browser; it can also be used to retrieve information about the synthesis voices available on the device, start and pause speech, and extends controls to speak their text or value when they are activated or deactivated.
- C#
- VB.NET
public class SpeechSynthesis : Component, IExtenderProvider
Public Class SpeechSynthesis
Inherits Component
Implements IExtenderProvider
The speech is produced by the browser using the voices installed on the user's device. When the browser doesn't support the Web Speech API the component does nothing. Browsers may refuse to speak before the user has interacted with the page.
Voice, Language, Volume, Rate and Pitch apply to all the utterances, including those spoken automatically for the extended controls.
Example:
Speaking a message and reading a field aloud when it gets the focus:
var speech = new SpeechSynthesis { Language = "en-US", Rate = 1.2f };
var props = speech.GetSpeechSynthesis(this.textBoxName);
props.SpeakMode = SpeechSynthesis.SpeakMode.TextOnEnter;
props.TextToSpeak = "Please enter your name.";
speech.Speak("Welcome back!");
Constructors
SpeechSynthesis()
Initializes a new instance of the SpeechSynthesis class.
Properties
Enabled
Boolean: Returns or sets whether the SpeechSynthesis extender speaks for the extended controls. (Default: True)
When false, the extended controls are not spoken when activated or deactivated. It doesn't affect Speak. The default is true.
Language
String: Returns or sets the language of the utterance. (Default: "")
The value is a BCP 47 language tag, i.e. "en-US", "fr-FR". When empty (default) the browser uses the language of the page or of the user agent. It's ignored when Voice matches an installed voice.
Pitch
Single: Returns or sets the pitch at which the utterance will be spoken at. (Default: 1)
The value ranges from 0 (lowest) to 2 (highest); the default is 1.
Throws:
- ArgumentOutOfRangeException The value is less than 0 or greater than 2.
Rate
Single: Returns or sets the speed at which the utterance will be spoken at. (Default: 1)
The default is 1 (normal speed); 2 is twice as fast and 0.5 is half as fast. The Web Speech API accepts values from 0.1 to 10, although most voices support a narrower range.
Throws:
- ArgumentOutOfRangeException The value is less than 0 or greater than 10.
Voice
String: Returns or sets the name of the voice that will be used to speak the utterance. (Default: "native")
The value must match exactly the name of one of the voices installed in the browser, as returned by GetVoicesAsync, i.e. "Google UK English Female" or "Microsoft Zira - English (United States)". When a matching voice is found, it overrides Language.
The default is "native": since no voice has this name, the browser picks the default voice for the Language. Setting null or an empty string restores "native".
Example:
Selecting the first English voice available in the browser:
var voices = await this.speechSynthesis1.GetVoicesAsync();
var english = voices?.FirstOrDefault(v => v.Contains("English"));
if (english != null)
this.speechSynthesis1.Voice = english;
Volume
Single: Returns or sets the volume that the utterance will be spoken at. The default is 1 (maximum). (Default: 1)
The value ranges from 0 (silent) to 1 (maximum).
Throws:
- ArgumentOutOfRangeException The value is less than 0 or greater than 1.
Methods
Cancel()
Removes all utterances from the utterance queue. If an utterance is currently being spoken, speaking will stop immediately.
Example:
Stopping the speech when the user closes the form:
private void Form1_FormClosing(object sender, FormClosingEventArgs e)
{
this.speechSynthesis1.Cancel();
}
CanExtend(target)
Returns true if SpeechSynthesis can offer an extender property to the specified target component.
| Parameter | Type | Description |
|---|---|---|
| target | Object | The target object to add an extender property to. |
Returns: Boolean. true if the SpeechSynthesis class can offer one or more extender properties; otherwise, false.
All controls can be extended.
Example:
Checking whether a component can be extended:
if (this.speechSynthesis1.CanExtend(this.buttonOK))
this.speechSynthesis1.GetSpeechSynthesis(this.buttonOK).TextToSpeak = "OK";
Dispose(disposing)
| Parameter | Type | Description |
|---|---|---|
| disposing | Boolean |
GetSpeechSynthesis(control)
Returns the speech synthesis properties associated with the specified control.
Returns: Properties. A Properties instance with the SpeechSynthesis properties.
The properties are created the first time they are requested for a control and are removed automatically when the control is disposed. Changing them updates the component on the client.
Throws:
- ArgumentNullException control is null.
Example:
Reading the value of a text box aloud when the user leaves it:
var props = this.speechSynthesis1.GetSpeechSynthesis(this.textBoxAmount);
props.SpeakMode = SpeechSynthesis.SpeakMode.ValueOnLeave;
GetVoicesAsync()
Asynchronously returns the names of the voices available in the browser.
Returns: Task<String[]>. A task that represents the asynchronous operation. The task result contains the names of the voices, or null when the browser doesn't support speech synthesis or hasn't loaded the voices yet.
Some browsers load the list of voices asynchronously, the first call may return null: call it again later. Use one of the returned names to set Voice.
Example:
Filling a combo box with the available voices:
private async void Form1_Load(object sender, EventArgs e)
{
var voices = await this.speechSynthesis1.GetVoicesAsync();
if (voices != null)
this.comboBoxVoices.Items.AddRange(voices);
}
OnWebRender(config)
Renders the client component.
| Parameter | Type | Description |
|---|---|---|
| config | Object | Dynamic configuration object. |
Pause()
Puts the SpeechSynthesis object into a paused state.
The speech can be continued from the same point with Resume. The pause applies to the browser's speech queue, shared by all the SpeechSynthesis components in the page.
Example:
Toggling pause and resume with a check box:
private void checkBoxPause_CheckedChanged(object sender, EventArgs e)
{
if (this.checkBoxPause.Checked)
this.speechSynthesis1.Pause();
else
this.speechSynthesis1.Resume();
}
RemoveAll()
Removes all speech extenders.
The component is not updated on the client by this method: the controls stop speaking the next time the component is updated, i.e. when one of its properties changes.
Example:
Removing the speech from all controls:
this.speechSynthesis1.RemoveAll();
Resume()
Resumes speaking if the SpeechSynthesis object was already paused.
Example:
Resuming the speech paused by Pause:
private void buttonResume_Click(object sender, EventArgs e)
{
this.speechSynthesis1.Resume();
}
SetSpeechSynthesis(control, speechSynthesis)
Required by the designer to make the extender property writable; this method doesn't do anything.
| Parameter | Type | Description |
|---|---|---|
| control | Control | The extended control. |
| speechSynthesis | Properties | The speech synthesis properties. The value is ignored. |
Use GetSpeechSynthesis and change the returned Properties instead.
Example:
Changing the speech properties of a control:
// SetSpeechSynthesis() has no effect, modify the existing properties instead.
this.speechSynthesis1.GetSpeechSynthesis(this.buttonOK).SpeakMode = SpeechSynthesis.SpeakMode.TextOnEnter;
Speak(text)
Adds an utterance to the utterance queue; it will be spoken when any other utterances queued before it have been spoken.
| Parameter | Type | Description |
|---|---|---|
| text | String | The text to speak. Null or empty values are ignored. |
The utterance uses the current values of Voice, Language, Volume, Rate and Pitch. It's spoken also when Enabled is false.
Example:
Announcing the result of an operation:
private void buttonSave_Click(object sender, EventArgs e)
{
SaveDocument(this.document);
this.speechSynthesis1.Speak("The document has been saved.");
}
Implements
| Name | Description |
|---|---|
| IUserData | |
| IWisejComponent | |
| IWisejSerializable |