Creates a new SubElement instance.
The original text as it appears in the document. This is the written form that will be displayed but not spoken. Special XML characters (&, <, >, ", ') are automatically escaped to ensure valid XML output and prevent injection attacks. Examples: - Abbreviations: "Dr.", "Mr.", "Ms.", "Inc.", "Ltd." - Acronyms: "NASA", "WHO", "API", "HTML", "SQL" - Technical terms: "www", "etc.", "vs." - Company names: "AT&T", "P&G"
The text that should be spoken instead of the original. This is the pronunciation or expanded form of the original text. Should be written exactly as it should be pronounced. Examples: - For "Dr.": "Doctor" - For "NASA": "National Aeronautics and Space Administration" - For "www": "world wide web" - For "etc.": "et cetera" - For "&": "and"
// Common abbreviations
const doctor = new SubElement('Dr.', 'Doctor');
const mister = new SubElement('Mr.', 'Mister');
const incorporated = new SubElement('Inc.', 'Incorporated');
// Acronyms
const api = new SubElement('API', 'Application Programming Interface');
const html = new SubElement('HTML', 'HyperText Markup Language');
const sql = new SubElement('SQL', 'Structured Query Language');
// Technical terms
const website = new SubElement('www.example.com', 'w w w dot example dot com');
const versus = new SubElement('vs.', 'versus');
const etcetera = new SubElement('etc.', 'et cetera');
// Company names with special characters
const att = new SubElement('AT&T', 'A T and T');
const pandg = new SubElement('P&G', 'P and G');
// Chemical formulas
const water = new SubElement('H2O', 'H two O');
const co2 = new SubElement('CO2', 'C O two');
// Units and measurements
const kilometers = new SubElement('km', 'kilometers');
const fahrenheit = new SubElement('°F', 'degrees Fahrenheit');
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 sub element as an SSML XML string.
Generates the <sub> element with the alias attribute specifying the text to be spoken
and the original text as the element's content. The original text is automatically escaped
to prevent XML injection and ensure valid output. The rendered element instructs the speech
synthesizer to speak the alias text instead of the original content.
The XML string representation of the sub element in the format:
<sub alias="pronunciation">original text</sub>
// Simple abbreviation
const dr = new SubElement('Dr.', 'Doctor');
console.log(dr.render());
// Output: <sub alias="Doctor">Dr.</sub>
// Acronym
const who = new SubElement('WHO', 'World Health Organization');
console.log(who.render());
// Output: <sub alias="World Health Organization">WHO</sub>
// With special characters (automatically escaped in original)
const att = new SubElement('AT&T', 'A T and T');
console.log(att.render());
// Output: <sub alias="A T and T">AT&T</sub>
// Technical notation
const squared = new SubElement('m²', 'meters squared');
console.log(squared.render());
// Output: <sub alias="meters squared">m²</sub>
// URL
const url = new SubElement('example.com', 'example dot com');
console.log(url.render());
// Output: <sub alias="example dot com">example.com</sub>
SSML element for text substitution and pronunciation aliases.
The
<sub>element allows you to specify an alternative pronunciation for text by providing an alias that should be spoken instead of the written text. This is essential for acronyms, abbreviations, technical terms, or any text where the written form differs from how it should be pronounced. The visual representation remains unchanged while the speech output uses the alias.The sub element is particularly useful for maintaining readable text while ensuring correct pronunciation, such as expanding abbreviations like "Dr." to "Doctor" or providing phonetic pronunciations for company names or technical terms that might be mispronounced by default.
Example
Remarks
See