Creates a new AudioElement instance.
The URL of the audio file to play. Must be a publicly accessible HTTPS URL. Supported formats include MP3, WAV, and other common audio formats. The URL should be properly encoded if it contains special characters.
OptionalfallbackText: stringOptional text to speak if the audio file is unavailable or cannot be played. This text will be spoken using the current voice settings. Special XML characters in the text will be automatically escaped. If not provided and the audio fails, there will be silence.
// With fallback text for accessibility
const soundEffect = new AudioElement(
'https://cdn.example.com/sounds/notification.mp3',
'Notification sound'
);
// Without fallback (silent if audio fails)
const backgroundMusic = new AudioElement(
'https://cdn.example.com/music/intro.mp3'
);
// With special characters in fallback text (automatically escaped)
const alert = new AudioElement(
'https://example.com/alert.mp3',
'Alert: "System" & security check'
);
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 audio element as an SSML XML string.
Generates the <audio> element with the source URL and optional fallback text.
If fallback text is provided, it is automatically escaped to prevent XML injection
and ensure valid XML output. The fallback text is placed inside the audio element
and will only be spoken if the audio file cannot be loaded or played.
The XML string representation of the audio element in the format:
<audio src="url">fallback text</audio> or
<audio src="url"></audio> if no fallback text is provided
// With fallback text
const audio1 = new AudioElement(
'https://example.com/sound.mp3',
'Ding sound'
);
console.log(audio1.render());
// Output: <audio src="https://example.com/sound.mp3">Ding sound</audio>
// Without fallback text
const audio2 = new AudioElement('https://example.com/music.mp3');
console.log(audio2.render());
// Output: <audio src="https://example.com/music.mp3"></audio>
// With special characters in fallback (automatically escaped)
const audio3 = new AudioElement(
'https://example.com/alert.mp3',
'Alert & "Warning"'
);
console.log(audio3.render());
// Output: <audio src="https://example.com/alert.mp3">Alert & "Warning"</audio>
SSML element for embedding external audio files in speech synthesis.
The
<audio>element allows you to insert pre-recorded audio files into the synthesized speech output. This is useful for adding sound effects, music, pre-recorded messages, or any other audio content that should be played as part of the speech. If the audio file is unavailable or cannot be played, the optional fallback text will be spoken instead.The audio element supports common audio formats like MP3 and WAV. The audio file must be publicly accessible via HTTPS for cloud-based speech services to retrieve and play it.
Example
Remarks
See