Construct a Complex Prompt

Article
01/20/2015

When you create a PromptBuilder instance, it contains an empty Prompt object. You can append text, audio, Speech Synthesis Markup Language (SSML) markup, a bookmark, a break, or an existing PromptBuilder instance to the one you just created. After all of the prompt elements are in place, the prompt can be played.

Append Text to a Prompt

Text in the form of a string can be appended to a prompt in a number of ways, using any of the four AppendText() overloaded methods, the two AppendTextWithHint() overloaded methods, the AppendTextWithAlias(String, String) method, or the AppendTextWithPronunciation(String, String).

All four of the AppendText() methods can be used to append a string to a prompt, but with three of these methods you can specify the emphasis, rate, or volume at which the prompt is played.

The two AppendTextWithHint() methods can be used to provide a hint as to how the specified string should be spoken, using either a value in the SayAs enumerated type or using SSML markup. For more information, see say-as Element.

The AppendTextWithAlias(String, String) method can be used to append text that has substitute text. For example, the text that is appended might be "SAPI" and the alias text that will be spoken might be "Speech Application Programming Interface". For more information, see sub Element.

The AppendTextWithPronunciation(String, String) method can be used to append text and to provide the pronunciation for that text using characters from the International Phonetic Alphabet (IPA).

In the following example, prompts are created in three PromptBuilder instances, pb1, pb2, and pb3. When spoken, the first part of the prompt in pb1 is spoken at low volume, and the second part is spoken at high volume. When spoken, the prompt in pb2 is rendered as the text in the second parameter. When spoken, the prompt in pb3 is rendered as a date in month-day-year order, and the string "19" is rendered as "nineteenth".

PromptBuilder pb1 = new PromptBuilder();
PromptBuilder pb2 = new PromptBuilder();
PromptBuilder pb3 = new PromptBuilder();
pb1.AppendText("Soft", System.Speech.Synthesis.PromptVolume.ExtraSoft);
pb1.AppendText("Loud", System.Speech.Synthesis.PromptVolume.ExtraLoud);

pb2.AppendTextWithAlias("SAPI", "Speech Application Programming Interface"); 

pb3.AppendTextWithHint("2/19/2009", SayAs.MonthDayYear);
pb3.AppendText("February");
pb3.AppendTextWithHint("19", SayAs.NumberOrdinal);

Append Audio to a Prompt

To include audio from a .WAV file in a prompt, use one of the AppendAudio() overloaded methods. With these methods you can specify the location of the audio file as a fully-qualified path or by its Uniform Resource Identifier (URI). Alternatively, you can specify alternate text to be played if the audio file is not available or not playable.

PromptBuilder pb = new PromptBuilder();
pb.AppendText("Now for some music");
pb.AppendAudio(new Uri("https://www.contoso.com/music/song.wav"), 
“Please wait while we get the next song.”);

Append SSML Markup to a Prompt

Speech Synthesis Markup Language (SSML) markup can be appended to a prompt in a number of ways. The AppendSsml() overloaded methods can be used to append a file containing SSML markup at a specified path or at a specified Uniform Resource Identifier (URI) location. The SSML file must be an XML-format file that conforms to the Speech Synthesis Markup Language (SSML) Version 1.0 specification. For more information, see Use SSML to Control Synthesized Speech.

The AppendSsmlMarkup(String) method can be used to append the SSML markup specified in this method’s string argument to the prompt. The prompt in the following example, when spoken, will render as "Today is January the twenty-ninth, two thousand nine."

PromptBuilder pb1 = new PromptBuilder();
string str1 = "<say-as type=\"date:mdy\">1/29/2009</say-as>";
pb1.AppendText("Today is ");
pb1.AppendSsmlMarkup(str1);

Note

The string used as an argument to AppendSsmlMarkup(String) must not include a speak element.

When spoken, the prompt in the next example renders the spelling of the word "chair."

PromptBuilder pb2 = new PromptBuilder();
string str2 = "<say-as interpret-as=\"characters\">chair</say-as>";
pb2.AppendSsmlMarkup(str2);

Append Breaks and Bookmarks to a Prompt

Breaks can be added to a prompt by the use of one of the AppendBreak() overloaded methods. These methods can be used to append a break of default length, append a break with a length specified by a value of the PromptBreak enumeration, or append a break of a specified time duration.

You can insert a bookmark into a prompt using the AppendBookmark(String) method. When a bookmark is reached in a prompt, the SpeechSynthesizer instance raises the BookmarkReached event. For more information about events raised by the SpeechSynthesizer object, see Use Speech Synthesis Events.

PromptBuilder pb = new PromptBuilder();
pb.AppendText("Call me Ishmael.");
pb.AppendBreak();
pb.AppendBookmark("Start");

Change the Style or Voice of a Prompt

You can change the style of a PromptBuilder prompt by changing the emphasis, rate, or volume. These style changes affect the prominence or stress to apply to the spoken prompt (emphasis), the speaking rate to use (rate), and the loudness of the spoken output (volume). To change the style in a prompt, build up the prompt to the point at which you want to change the style, call StartStyle(PromptStyle) on the PromptBuilder instance, append the part of the prompt whose style you are changing, and then call EndStyle() on the PromptBuilder instance.

The following example demonstrates style change in two prompts. In the first prompt, the first two words of the prompt use the default style, and the last two words of the prompt are spoken at reduced volume. In the second prompt, the phrase "hurry, hurry, hurry" is spoken at an increased rate. The variable named synth is a SpeechSynthesizer instance.

PromptBuilder pb = new PromptBuilder();

pb.AppendText("Default volume ");
pb.StartStyle(new PromptStyle(PromptVolume.Soft));
pb.AppendBreak();
pb.AppendText("reduced volume");
pb.EndStyle();
string XMLStr = pb.ToXml();
synth.Speak(pb);
pb.ClearContent();

pb.AppendText("Come into the house");
pb.StartStyle(new PromptStyle(PromptRate.ExtraFast));
pb.AppendBreak();
pb.AppendText("hurry, hurry, hurry");
pb.EndStyle();
XMLStr = pb.ToXml();
synth.Speak(pb);
pb.ClearContent();

Warning

The speech synthesis engines for Windows do not support the settings for emphasis at this time. Using members of the PromptEmphasis enumeration as arguments to the constructor for PromptStyle will produce no change in the synthesized speech output.

The Default setting for PromptVolume is full volume, which is the same as ExtraLoud. You can only decrease the volume of speech output.

Divide Prompts into Sentences and Paragraphs

Long prompts can be rendered more like human speech if they are broken into sentences and paragraphs. The StartParagraph() overloaded methods can be used to start a paragraph in a prompt, and the StartSentence() overloaded methods can be used to start a sentence. To end a sentence, use EndSentence(), and to end a paragraph, use EndParagraph().

PromptBuilder pb = new PromptBuilder();
pb.StartParagraph();
pb.StartSentence();
pb.AppendText("This is the first sentence.");
pb.EndSentence();
pb.StartSentence();
pb.AppendText("This is the second sentence.");
pb.EndSentence();
pb.EndParagraph();