Creates a new BookmarkElement instance.
The reference identifier for the bookmark. This should be a unique string within the SSML document that identifies this specific marker position. Used by event handlers to identify which bookmark was reached. Can contain letters, numbers, and underscores. Avoid spaces and special characters for better compatibility.
// Simple identifier
const bookmark1 = new BookmarkElement('start');
// Numbered markers
const bookmark2 = new BookmarkElement('word_1');
const bookmark3 = new BookmarkElement('word_2');
// Hierarchical markers
const chapterStart = new BookmarkElement('chapter_1_start');
const sectionStart = new BookmarkElement('chapter_1_section_2');
// For tracking specific content
const priceBookmark = new BookmarkElement('price_announcement');
const dateBookmark = new BookmarkElement('date_mentioned');
// For animation sync points
const animStart = new BookmarkElement('anim_slide_in');
const animMid = new BookmarkElement('anim_highlight');
const animEnd = new BookmarkElement('anim_slide_out');
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 bookmark element as an SSML XML string.
Generates the <bookmark> element with the mark attribute. This is a self-closing
element that doesn't contain any content or child elements. The mark value is
inserted directly without escaping since it should only contain safe identifier characters.
The XML string representation of the bookmark element in the format:
<bookmark mark="identifier"/>
// Simple bookmark
const bookmark = new BookmarkElement('intro');
console.log(bookmark.render());
// Output: <bookmark mark="intro"/>
// Numbered bookmark
const wordMarker = new BookmarkElement('word_42');
console.log(wordMarker.render());
// Output: <bookmark mark="word_42"/>
// Hierarchical bookmark
const section = new BookmarkElement('chapter2_section3_para1');
console.log(section.render());
// Output: <bookmark mark="chapter2_section3_para1"/>
// Usage in speech synthesis with SDK event handling
// When synthesized, this bookmark will trigger a BookmarkReached event
// with the mark value and audio offset position
SSML element for placing markers in speech synthesis to track progress.
The
<bookmark>element inserts a non-audible marker at a specific location in the synthesized speech stream. These markers generate events that can be tracked by applications to determine exactly when specific points in the text are reached during playback. This is useful for synchronizing visual elements, triggering animations, or tracking reading progress.The bookmark element itself doesn't produce any audio output - it's purely a marker for event generation. Applications can subscribe to the
BookmarkReachedevent using the Speech SDK to receive notifications when each bookmark is encountered during synthesis.Example
Remarks
See