Creates a new EmphasisElement instance.
The text content to emphasize. This text will be spoken with the specified emphasis level. Special XML characters (&, <, >, ", ') are automatically escaped to ensure valid XML output and prevent injection attacks.
Optionallevel: EmphasisLevelOptional emphasis level to apply to the text.
Available levels:
- strong: High emphasis with significant pitch increase and slower speech.
Used for critical information or strong contrast.
- moderate: Medium emphasis (default if not specified).
Standard emphasis for important information.
- reduced: De-emphasis with lower pitch and faster speech.
Used for parenthetical or less important information.
// Default emphasis (moderate)
const normal = new EmphasisElement('important information');
// Strong emphasis for warnings
const warning = new EmphasisElement('WARNING', 'strong');
// Reduced emphasis for side notes
const sideNote = new EmphasisElement('(optional)', 'reduced');
// With special characters (automatically escaped)
const special = new EmphasisElement('Terms & Conditions', 'strong');
// For highlighting key points
const keyPoint = new EmphasisElement('Remember this', 'strong');
// For de-emphasizing disclaimers
const disclaimer = new EmphasisElement('results may vary', 'reduced');
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 emphasis element as an SSML XML string.
Generates the <emphasis> element with optional level attribute and properly
escaped text content. The level attribute is only included if explicitly specified;
otherwise, the default 'moderate' level is implied. Text content is automatically
escaped to prevent XML injection and ensure valid output.
The XML string representation of the emphasis element in one of these formats:
- <emphasis>text</emphasis> (default moderate level)
- <emphasis level="strong">text</emphasis> (explicit level)
// Default emphasis (no level attribute)
const emphasis1 = new EmphasisElement('important');
console.log(emphasis1.render());
// Output: <emphasis>important</emphasis>
// With strong level
const emphasis2 = new EmphasisElement('critical', 'strong');
console.log(emphasis2.render());
// Output: <emphasis level="strong">critical</emphasis>
// With reduced level
const emphasis3 = new EmphasisElement('minor detail', 'reduced');
console.log(emphasis3.render());
// Output: <emphasis level="reduced">minor detail</emphasis>
// Special characters are escaped
const emphasis4 = new EmphasisElement('A & B are "important"', 'strong');
console.log(emphasis4.render());
// Output: <emphasis level="strong">A & B are "important"</emphasis>
SSML element for applying emphasis to text in synthesized speech.
The
<emphasis>element modifies the speaking style to emphasize or de-emphasize words or phrases within the speech output. This is achieved through changes in pitch, timing, and vocal stress. Emphasis helps convey importance, create contrast, or indicate parenthetical information in a natural way.The emphasis level affects how the text is spoken relative to the surrounding content. Strong emphasis makes text stand out prominently, while reduced emphasis makes it less prominent, useful for side notes or less important information.
Example
Remarks
See