Creates a new SayAsElement instance.
The text content to be interpreted and spoken. This should be formatted according to the interpretAs type. Special XML characters (&, <, >, ", ') are automatically escaped. Examples: - For dates: "2025-12-31", "12/31/2025", "31.12.2025" - For currency: "42.50", "$100", "€50.00" - For telephone: "1-800-555-1234", "+1 (555) 123-4567" - For numbers: "1234", "42", "3.14159"
Configuration for text interpretation
Configuration options for say-as elements.
Controls interpretation and pronunciation of formatted text like dates, numbers, currency, and other specialized content.
Optionaldetail?: stringAdditional detail for interpretation.
Provides extra context for certain interpretAs types:
Optionalformat?: stringFormat hint for interpretation.
Provides additional formatting information. Available formats depend on interpretAs value:
For dates:
For time:
How to interpret the text content. (Required)
Determines the pronunciation rules applied to the text. Each type has specific formatting requirements.
// Date examples
const usDate = new SayAsElement('03/15/2025', {
interpretAs: 'date',
format: 'mdy'
});
const isoDate = new SayAsElement('2025-03-15', {
interpretAs: 'date',
format: 'ymd'
});
// Currency examples
const usDollars = new SayAsElement('42.50', {
interpretAs: 'currency',
detail: 'USD'
});
const euros = new SayAsElement('100.00', {
interpretAs: 'currency',
detail: 'EUR'
});
// Number examples
const cardinal = new SayAsElement('42', {
interpretAs: 'cardinal' // "forty-two"
});
const ordinal = new SayAsElement('3', {
interpretAs: 'ordinal' // "third"
});
const digits = new SayAsElement('123', {
interpretAs: 'digits' // "one two three"
});
// Phone number
const phone = new SayAsElement('1-800-555-1234', {
interpretAs: 'telephone'
});
// Time
const time = new SayAsElement('14:30:00', {
interpretAs: 'time',
format: 'hms24'
});
// Spell out
const spelled = new SayAsElement('API', {
interpretAs: 'spell-out' // "A P I"
});
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 say-as element as an SSML XML string.
Generates the <say-as> element with the required interpret-as attribute
and optional format and detail attributes. The text content is automatically
escaped to prevent XML injection and ensure valid output. Only includes
optional attributes if their values are defined, keeping the XML clean.
The XML string representation of the say-as element with format:
<say-as interpret-as="type" [format="value"] [detail="value"]>text</say-as>
// Basic interpretation
const cardinal = new SayAsElement('42', { interpretAs: 'cardinal' });
console.log(cardinal.render());
// Output: <say-as interpret-as="cardinal">42</say-as>
// With format
const date = new SayAsElement('2025-12-31', {
interpretAs: 'date',
format: 'ymd'
});
console.log(date.render());
// Output: <say-as interpret-as="date" format="ymd">2025-12-31</say-as>
// With detail
const currency = new SayAsElement('42.50', {
interpretAs: 'currency',
detail: 'USD'
});
console.log(currency.render());
// Output: <say-as interpret-as="currency" detail="USD">42.50</say-as>
// All attributes
const complex = new SayAsElement('3:30:00 PM', {
interpretAs: 'time',
format: 'hms12',
detail: 'EST'
});
console.log(complex.render());
// Output: <say-as interpret-as="time" format="hms12" detail="EST">3:30:00 PM</say-as>
// Special characters escaped
const special = new SayAsElement('A&B', {
interpretAs: 'spell-out'
});
console.log(special.render());
// Output: <say-as interpret-as="spell-out">A&B</say-as>
SSML element for controlling text interpretation and pronunciation.
The
<say-as>element specifies how text should be interpreted and spoken by the text-to-speech engine. This is essential for ensuring correct pronunciation of formatted text such as dates, numbers, currency, telephone numbers, and other specialized content. Without this element, the synthesizer might incorrectly interpret formatted text based on its default rules.The say-as element ensures consistent and accurate pronunciation across different voices and languages by providing explicit interpretation instructions. This is particularly important for content that could be ambiguous, such as "1/2" which could be a date or a fraction.
Example
Remarks
See