Adds an SSML element as a child of this sentence.
This method allows adding valid SSML elements that can be contained within a sentence according to the SSML specification. This enables complex sentence structures with various speech modifications while maintaining sentence boundaries.
An SSML element to add to the sentence. Must be one of the allowed child elements for sentences: audio, break, phoneme, prosody, say-as, mstts:express-as, or sub [[11]].
This SentenceElement instance for method chaining
const sentence = new SentenceElement();
// Add emphasis element
const emphasis = new EmphasisElement('important', 'strong');
sentence
.text('This is ')
.addElement(emphasis)
.text(' information.');
// Add break element
const pause = new BreakElement({ time: '500ms' });
sentence
.text('Wait for it')
.addElement(pause)
.text('here it comes!');
// Add say-as element for proper pronunciation
const date = new SayAsElement('2025-12-31', {
interpretAs: 'date',
format: 'ymd'
});
sentence
.text('The deadline is ')
.addElement(date)
.text('.');
// Complex sentence with multiple elements
const phoneme = new PhonemeElement('Azure', {
alphabet: 'ipa',
ph: 'æʒər'
});
sentence
.text('We use ')
.addElement(phoneme)
.text(' for cloud services.');
ProtectedescapeProtectedEscapes special XML characters in text content to ensure valid XML output.
This method replaces XML special characters with their corresponding entity references to prevent XML parsing errors and potential security issues (XML injection). It should be used whenever inserting user-provided or dynamic text content into XML elements.
The following characters are escaped:
& becomes & (must be escaped first to avoid double-escaping)< becomes < (prevents opening of unintended tags)> becomes > (prevents closing of unintended tags)" becomes " (prevents breaking out of attribute values)' becomes ' (prevents breaking out of attribute values)This method is marked as protected so it's only accessible to classes that extend
SSMLElement, ensuring proper encapsulation while allowing all element implementations
to use this essential functionality.
The text content to escape
The text with all special XML characters properly escaped
// In a render method implementation
class TextElement extends SSMLElement {
private text: string = 'Hello & "world" <script>';
render(): string {
// Escapes to: Hello & "world" <script>
return `<text>${this.escapeXml(this.text)}</text>`;
}
}
// Edge cases handled correctly
this.escapeXml('5 < 10 & 10 > 5');
// Returns: '5 < 10 & 10 > 5'
this.escapeXml('She said "Hello"');
// Returns: 'She said "Hello"'
this.escapeXml("It's a test");
// Returns: 'It's a test'
// Prevents XML injection
this.escapeXml('</voice><voice name="evil">');
// Returns: '</voice><voice name="evil">'
Renders the sentence element as an SSML XML string.
Generates the <s> element containing all child content. Text content is
automatically escaped to prevent XML injection, while child elements are
rendered recursively to build the complete sentence structure. The rendered
sentence will be processed by the speech synthesizer with appropriate
intonation patterns and timing for sentence boundaries.
The XML string representation of the sentence element in the format:
<s>content</s> where content can be text and/or child elements
// Simple text sentence
const simple = new SentenceElement();
simple.text('This is a sentence.');
console.log(simple.render());
// Output: <s>This is a sentence.</s>
// Sentence with mixed content
const mixed = new SentenceElement();
mixed
.text('The price is ')
.addElement(new SayAsElement('42.50', {
interpretAs: 'currency',
detail: 'USD'
}));
console.log(mixed.render());
// Output: <s>The price is <say-as interpret-as="currency" detail="USD">42.50</say-as></s>
// Multiple text segments
const multi = new SentenceElement();
multi.text('First part ').text('second part ').text('final part.');
console.log(multi.render());
// Output: <s>First part second part final part.</s>
// With escaped special characters
const special = new SentenceElement();
special.text('Terms & "conditions" apply.');
console.log(special.render());
// Output: <s>Terms & "conditions" apply.</s>
Adds plain text content to the sentence.
The text will be spoken as part of the sentence with appropriate intonation and prosody for sentence context. Special XML characters are automatically escaped to ensure valid XML output and prevent injection attacks.
The text content to add to the sentence. Will be spoken with sentence-appropriate prosody and intonation. Multiple calls append text sequentially within the same sentence.
This SentenceElement instance for method chaining
const sentence = new SentenceElement();
sentence.text('This is the beginning ');
sentence.text('and this is the end.');
// Result: <s>This is the beginning and this is the end.</s>
// With special characters (automatically escaped)
sentence.text('She said "Hello" & goodbye.');
// Result: <s>She said "Hello" & goodbye.</s>
// Building a question
const question = new SentenceElement();
question.text('Are you coming to the meeting?');
// The synthesizer will apply rising intonation for the question
SSML element for explicitly marking sentence boundaries in speech synthesis.
The
<s>element denotes a sentence within the synthesized speech output. While the speech synthesizer automatically detects sentence boundaries based on punctuation and context, the sentence element allows for explicit control over sentence structure. This is particularly useful when automatic detection might be incorrect or when you need precise control over intonation patterns and pauses between sentences.Sentences help the synthesizer apply appropriate prosody, including natural intonation patterns for statements, questions, and exclamations. They also ensure proper pauses between sentences for better comprehension.
Example
Remarks
See