Creates a new PhonemeElement instance.
The text content to be pronounced. This is the written form that appears in the document. Special XML characters (&, <, >, ", ') are automatically escaped. The actual pronunciation is determined by the ph attribute.
Configuration for phonetic pronunciation
Configuration options for phoneme elements.
Provides exact phonetic pronunciation using standard phonetic alphabets. Essential for proper names, technical terms, or words with ambiguous pronunciation.
Phonetic alphabet used for transcription. (Required)
Available alphabets:
ipa: International Phonetic Alphabet (universal standard)sapi: Microsoft SAPI phonemes (English-focused)ups: Universal Phone Set (Microsoft's unified system)Phonetic transcription of the word. (Required)
The exact phonetic representation in the specified alphabet. Must be valid according to the chosen alphabet's rules.
// IPA for international use
const ipaExample = new PhonemeElement('schedule', {
alphabet: 'ipa',
ph: 'ˈskɛdʒuːl' // American pronunciation
});
// SAPI for Microsoft voices
const sapiExample = new PhonemeElement('SQL', {
alphabet: 'sapi',
ph: 'eh s k y uw eh l'
});
// Technical terms
const techTerm = new PhonemeElement('Kubernetes', {
alphabet: 'ipa',
ph: 'kuːbərˈnetiːz'
});
// Disambiguating homographs
const present = new PhonemeElement('read', {
alphabet: 'ipa',
ph: 'riːd' // Present tense, not past tense 'rɛd'
});
// Foreign names
const name = new PhonemeElement('Nguyen', {
alphabet: 'ipa',
ph: 'ŋwiən'
});
// Company/product names
const product = new PhonemeElement('iPhone', {
alphabet: 'sapi',
ph: 'ay f ow n'
});
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 phoneme element as an SSML XML string.
Generates the <phoneme> element with the alphabet and ph attributes specifying
the phonetic transcription. The text content is automatically escaped to prevent
XML injection and ensure valid output. The rendered element instructs the speech
synthesizer to use the specified phonetic pronunciation instead of its default
text-to-phoneme conversion.
The XML string representation of the phoneme element in the format:
<phoneme alphabet="alphabet" ph="transcription">text</phoneme>
// IPA example
const ipa = new PhonemeElement('schedule', {
alphabet: 'ipa',
ph: 'ˈʃɛdjuːl'
});
console.log(ipa.render());
// Output: <phoneme alphabet="ipa" ph="ˈʃɛdjuːl">schedule</phoneme>
// SAPI example
const sapi = new PhonemeElement('Azure', {
alphabet: 'sapi',
ph: 'ae zh er'
});
console.log(sapi.render());
// Output: <phoneme alphabet="sapi" ph="ae zh er">Azure</phoneme>
// With special characters (automatically escaped)
const special = new PhonemeElement('AT&T', {
alphabet: 'sapi',
ph: 'ey t ih n t ih'
});
console.log(special.render());
// Output: <phoneme alphabet="sapi" ph="ey t ih n t ih">AT&T</phoneme>
// UPS example
const ups = new PhonemeElement('hello', {
alphabet: 'ups',
ph: 'H EH L OW'
});
console.log(ups.render());
// Output: <phoneme alphabet="ups" ph="H EH L OW">hello</phoneme>
SSML element for specifying exact phonetic pronunciation of text.
The
<phoneme>element provides precise control over pronunciation by specifying the phonetic transcription of words using standard phonetic alphabets. This is essential for proper names, technical terms, foreign words, or any text that the speech synthesizer might pronounce incorrectly by default. The element ensures consistent and accurate pronunciation across different voices and languages.The phoneme element supports multiple phonetic alphabets including IPA (International Phonetic Alphabet), SAPI (Microsoft Speech API), and UPS (Universal Phone Set), allowing developers to choose the most appropriate system for their needs.
Example
Remarks
See