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.

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 (Microsoft.Speech).

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 (Microsoft.Speech).

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".

C#

Copy Code

PromptBuilder pb1 = new PromptBuilder(); PromptBuilder pb2 = new PromptBuilder(); PromptBuilder pb3 = new PromptBuilder(); pb1.AppendText("Soft", Microsoft.Speech.Synthesis.PromptVolume.ExtraSoft); pb1.AppendText("Loud", Microsoft.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);

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.

C#	Copy Code
PromptBuilder pb = new PromptBuilder(); pb.AppendText("Now for some music"); pb.AppendAudio(new Uri("http://www.contoso.com/music/song.wav"), "Please wait while we get the next song.");

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 (Microsoft.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."

C#	Copy Code
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."

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

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 (Microsoft.Speech).

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

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. Changing the rate or volume is performed in a similar manner except that the PromptRate and PromptVolume enumerations are used in place of the PromptEmphasis enumeration.

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 emphasis. In the second prompt, the last word of the prompt is spoken with strong emphasis. The variable named synth is a SpeechSynthesizer instance.

C#

Copy Code

PromptBuilder pb = new PromptBuilder(); pb.AppendText("Normal emphasis "); pb.StartStyle(new PromptStyle(PromptEmphasis.Reduced)); pb.AppendText("reduced emphasis"); pb.EndStyle(); string XMLStr = pb.ToXml(); synth.Speak(pb); pb.ClearContent(); pb.AppendText("Come into the house"); pb.StartStyle(new PromptStyle(PromptEmphasis.Strong)); pb.AppendText("now"); pb.EndStyle(); XMLStr = pb.ToXml(); synth.Speak(pb); pb.ClearContent();

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()()()().

C#	Copy Code
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();