Use Speech Synthesis Events (Microsoft.Speech)

As a SpeechSynthesizer instance emits synthesized speech, it raises events for which applications can register event handlers. See the example at the end of this topic for more information.

Some events report the progress of the speech synthesizer in the speaking of a prompt. In ascending degrees of granularity, these events range from reporting each individual character or word processed, to features encountered in a prompt such as bookmarks, to the beginning and ending of the speaking of an entire prompt.

Other events report on the state of the speech synthesizer and on the changing of its speaking voice. The following table lists events on the SpeechSynthesizer class.

Each of the events listed in the table is associated with a particular EventArgs class. Many of these associated classes contain properties named Cancelled, Error, and UserState that are inherited from the AsyncCompletedEventArgs class. These properties indicate, respectively, whether the particular asynchronous operation was cancelled, information about an error if one occurred, and an identifier for the asynchronous task that raised the event. In addition to these common properties, some of the event argument classes contain specialized properties, which are described under the following headings.

StateChanged

The synthesizer raises the StateChanged event when its state changes. This event is associated with the StateChangedEventArgs class, which has properties that indicate the synthesizer’s previous state (PreviousState) and its state after the change (State). The possible states (Paused, Ready, and Speaking) are members of the SynthesizerState enumeration.

SpeakStarted

The synthesizer automatically raises the SpeakStarted event when the synthesizer begins speaking the prompt it has synthesized. This event is associated with the SpeakStartedEventArgs class. The Prompt property on this class contains the prompt that caused the SpeakStarted event to be raised.

SpeakProgress

The synthesizer raises the SpeakProgress event periodically after the synthesized prompt has begun playing. These events are triggered as the speech synthesizer processes individual words in a prompt. This event is associated with the SpeakProgressEventArgs class, which contains the following properties that provide information about the prompt: AudioPosition, CharacterCount, CharacterPosition, Prompt, and Text.

BookmarkReached

You can insert a bookmark into a prompt using either the AppendBookmark(String) method, or into prompts containing markup that conforms to the Speech Synthesis Markup Language (SSML) Version 1.0, using the mark element. A synthesizer will raise the BookmarkReached event when it encounters the bookmark. This event is associated with the BookmarkReachedEventArgs class, which has properties that store the position in the audio stream (AudioPosition) and the name of the bookmark (Bookmark). For more information and an example, see Use Bookmarks (Microsoft.Speech).

VoiceChange

The synthesizer raises the VoiceChange event when the voice used for synthesis (the speaking voice) changes. This event is associated with the VoiceChangeEventArgs class. The only property of this class contains a VoiceInfo object, which provides information about the new voice, including the age, culture, and gender of the speaker. For more information, see Control Voice Attributes (Microsoft.Speech).

SpeakCompleted

The synthesizer automatically raises the SpeakCompleted event when it finishes speaking a synthesized prompt initiated with any of the SpeakAsync() or SpeakSsmlAsync(String) methods. The synthesizer does not raise this event for synchronous speak operations. This event is associated with the SpeakCompletedEventArgs class. The Prompt property on this class contains the prompt that caused the SpeakCompleted event to be raised. See the example for a typical use of this event when the speak operation is asynchronous.

Examples

The following example shows a console application that creates a SpeechSynthesizer instance named synth. The example then registers event handlers for the StateChanged, SpeakStarted, SpeakProgress, VoiceChange, and SpeakCompleted events. The example then creates basic code that demonstrates some of the information that is available in the handlers for these events. Because the speak operation is asynchronous, the playback of the WAV file occurs in the handler for the SpeakCompleted event.

using System;
using Microsoft.Speech.Synthesis;

namespace SampleSynthesis
{
  class Program
  {
    static void Main(string[] args)
    {

      // Initialize a new instance of the SpeechSynthesizer.
      SpeechSynthesizer synth = new SpeechSynthesizer();

      // Configure the audio output. 
      synth.SetOutputToWaveFile(@"C:\test\Garden.wav");

      // Register for events.
      synth.StateChanged += new EventHandler<StateChangedEventArgs>(synth_StateChanged);
      synth.SpeakStarted += new EventHandler<SpeakStartedEventArgs>(synth_SpeakStarted);
      synth.SpeakProgress += new EventHandler<SpeakProgressEventArgs>(synth_SpeakProgress);
      synth.VoiceChange += new EventHandler<VoiceChangeEventArgs>(synth_VoiceChange);
      synth.SpeakCompleted += new EventHandler<SpeakCompletedEventArgs>(synth_SpeakCompleted);

      // Speak the prompt.
      synth.SpeakAsync("Green is my garden.");

      // Keep the console window open.
      Console.WriteLine("Press any key to exit...");
      Console.ReadKey();
    }

    // Write the current state of the synthesizer to the console.
    static void synth_StateChanged(object sender, StateChangedEventArgs e)
    {
      Console.WriteLine("Current state of the synthesizer: " + e.State);
    }

    // Write a notification to the console when the speak operation starts.
    static void synth_SpeakStarted(object sender, SpeakStartedEventArgs e)
    {
      Console.WriteLine("Speak operation started");
    }

    // Write the current word being spoken to the console.
    static void synth_SpeakProgress(object sender, SpeakProgressEventArgs e)
    {
      Console.WriteLine("Current word being spoken: " + e.Text);
    }

    // Write the name of the new voice to the console.
    static void synth_VoiceChange(object sender, VoiceChangeEventArgs e)
    {
      Console.WriteLine("Name of the new voice: " + e.Voice.Name);
    }

    // Create a SoundPlayer instance and play the output audio file.
    static void synth_SpeakCompleted(object sender, SpeakCompletedEventArgs e)
    {
      // Create a SoundPlayer instance.
      System.Media.SoundPlayer m_SoundPlayer =
        new System.Media.SoundPlayer(@"C:\test\Garden.wav");

      // Play the output file.
      m_SoundPlayer.Play();

      // Write a notification to the console when the speak operation completes.
      Console.WriteLine("Speak operation completed");
    }
  }
}