Creates a new LexiconElement instance.
The URI of the pronunciation lexicon file. Must be a publicly accessible HTTPS URL pointing to a valid PLS XML file. The file should contain pronunciation definitions in the W3C PLS format. Common use cases include: - Technical terminology specific to your domain - Company or product names with non-standard pronunciations - Acronyms that should be expanded or pronounced differently - Foreign words that need specific pronunciation rules
// Reference a general pronunciation lexicon
const generalLexicon = new LexiconElement(
'https://cdn.example.com/lexicons/general.xml'
);
// Reference domain-specific lexicons
const medicalLexicon = new LexiconElement(
'https://example.com/lexicons/medical-terms.xml'
);
const techLexicon = new LexiconElement(
'https://example.com/lexicons/tech-acronyms.xml'
);
// Reference a company-specific lexicon
const companyLexicon = new LexiconElement(
'https://company.com/assets/brand-pronunciations.xml'
);
Example PLS file structure:
<?xml version="1.0" encoding="UTF-8"?>
<lexicon version="1.0"
xmlns="http://www.w3.org/2005/01/pronunciation-lexicon"
alphabet="ipa" xml:lang="en-US">
<lexeme>
<grapheme>SQL</grapheme>
<phoneme>ˈɛs kjuː ˈɛl</phoneme>
</lexeme>
<lexeme>
<grapheme>Azure</grapheme>
<phoneme>ˈæʒər</phoneme>
</lexeme>
</lexicon>
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 lexicon element as an SSML XML string.
Generates the <lexicon> element with the uri attribute pointing to the external
pronunciation lexicon file. This is a self-closing element that doesn't contain
any content or child elements. The URI value is inserted directly without escaping
as it should be a valid URL.
The XML string representation of the lexicon element in the format:
<lexicon uri="url"/>
// Simple lexicon reference
const lexicon = new LexiconElement('https://example.com/lexicon.xml');
console.log(lexicon.render());
// Output: <lexicon uri="https://example.com/lexicon.xml"/>
// With specific path
const techLexicon = new LexiconElement(
'https://cdn.example.com/lexicons/v2/technical.xml'
);
console.log(techLexicon.render());
// Output: <lexicon uri="https://cdn.example.com/lexicons/v2/technical.xml"/>
// Company lexicon
const brandLexicon = new LexiconElement(
'https://assets.company.com/speech/brand-terms.pls'
);
console.log(brandLexicon.render());
// Output: <lexicon uri="https://assets.company.com/speech/brand-terms.pls"/>
SSML element for referencing external pronunciation lexicon files.
The
<lexicon>element allows you to reference an external Pronunciation Lexicon Specification (PLS) file that contains custom pronunciations for words and phrases. This is useful for defining consistent pronunciations for technical terms, brand names, acronyms, or any words that the text-to-speech engine might pronounce incorrectly by default. The lexicon provides a way to specify phonetic pronunciations without embedding them directly in the SSML document.The lexicon file must be in the W3C Pronunciation Lexicon Specification (PLS) format and accessible via HTTPS. Multiple lexicon elements can be used to reference different lexicon files, and they are processed in the order they appear in the document.
Example
Remarks
See