SSML Builder Documentation - v1.0.1
    Preparing search index...

    Class SilenceElement

    SSML element for inserting precise silence/pauses in speech synthesis (Azure-specific).

    The <mstts:silence> element provides fine-grained control over silence placement in synthesized speech. Unlike the break element which can be inserted anywhere, the silence element works specifically at text boundaries: beginning or end of input text, between sentences, or at punctuation marks. This Azure Speech Service specific element allows for both additive silence (adding to natural pauses) and absolute silence (replacing natural pauses) for precise timing control.

    The silence setting is applied to all input text within its enclosing voice element. To reset or change the silence setting, you must use a new voice element with either the same voice or a different voice.

    // Add 200ms between sentences
    const silence = new SilenceElement({
      type: 'Sentenceboundary',
      value: '200ms'
    });
    silence.render();
    // Output: <mstts:silence type="Sentenceboundary" value="200ms"/>

    // Use with SSMLBuilder
    const ssml = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .silence({ type: 'Leading', value: '500ms' })
        .text('This text has extra silence at the beginning.')
      .build();
    • This is an Azure Speech Service specific extension requiring the mstts namespace
    • Silence elements must be direct children of the voice element
    • Absolute silence types (with -exact suffix) replace natural silence completely
    • Non-absolute types add to existing natural silence
    • The WordBoundary event takes precedence over punctuation-related silence settings
    • Multiple silence elements can be used for different types within the same voice
    • Valid duration range is 0-20000ms (values above 20000ms are capped)

    https://docs.microsoft.com/azure/cognitive-services/speech-service/speech-synthesis-markup#add-silence Silence Element Documentation

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    escapeXml render

    Constructors

    • Creates a new SilenceElement instance.

      Parameters

      • options: SilenceOptions

        Configuration for the silence element

        Configuration options for silence elements.

        Provides precise control over silence placement in speech output, with options for various positions and boundary types.

        • type: SilenceType

          Position and type of silence to add. (Required)

          Determines where silence is inserted:

          • Leading types: Beginning of text
          • Tailing types: End of text
          • Boundary types: Between sentences or at punctuation
          • Exact types: Replace natural silence with specified duration
          "Sentenceboundary"

          "Leading-exact"

          "Comma-exact"
        • value: string

          Duration of the silence. (Required)

          Specified in milliseconds (ms) or seconds (s). Valid range: 0-20000ms (20 seconds max)

          For non-exact types, this is added to natural silence. For exact types, this replaces natural silence.

          "200ms" - 200 milliseconds

          "1s" - 1 second

          "500ms" - Half second

      Returns SilenceElement

      // Add extra silence at the beginning
      const leadingSilence = new SilenceElement({
        type: 'Leading',
        value: '1s'
      });

      // Replace natural silence at the beginning
      const exactLeading = new SilenceElement({
        type: 'Leading-exact',
        value: '500ms'
      });

      // Add silence between sentences
      const sentencePause = new SilenceElement({
        type: 'Sentenceboundary',
        value: '300ms'
      });

      // Set exact silence at commas
      const commaPause = new SilenceElement({
        type: 'Comma-exact',
        value: '150ms'
      });

      // For dramatic effect with long pause
      const dramatic = new SilenceElement({
        type: 'Sentenceboundary',
        value: '2000ms'
      });

      // Minimal silence for rapid speech
      const rapid = new SilenceElement({
        type: 'Sentenceboundary-exact',
        value: '50ms'
      });

      // For CJK languages with enumeration comma
      const cjkPause = new SilenceElement({
        type: 'Enumerationcomma-exact',
        value: '200ms'
      });

    Methods

    • Protected

      Escapes 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 &amp; (must be escaped first to avoid double-escaping)
      • < becomes &lt; (prevents opening of unintended tags)
      • > becomes &gt; (prevents closing of unintended tags)
      • " becomes &quot; (prevents breaking out of attribute values)
      • ' becomes &apos; (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.

      Parameters

      • text: string

        The text content to escape

      Returns string

      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 &amp; &quot;world&quot; &lt;script&gt;
          return `<text>${this.escapeXml(this.text)}</text>`;
        }
      }

      // Edge cases handled correctly
      this.escapeXml('5 < 10 & 10 > 5');  
      // Returns: '5 &lt; 10 &amp; 10 &gt; 5'

      this.escapeXml('She said "Hello"');  
      // Returns: 'She said &quot;Hello&quot;'

      this.escapeXml("It's a test");       
      // Returns: 'It&apos;s a test'

      // Prevents XML injection
      this.escapeXml('</voice><voice name="evil">');  
      // Returns: '&lt;/voice&gt;&lt;voice name=&quot;evil&quot;&gt;'

    • Renders the silence element as an SSML XML string.

      Generates the Azure-specific <mstts:silence> element with the type and value attributes. This is a self-closing element that doesn't contain any content or child elements. The element instructs the speech synthesizer to insert or modify silence at the specified positions.

      Returns string

      The XML string representation of the silence element in the format: <mstts:silence type="type" value="duration"/>

      // Sentence boundary silence
      const sentence = new SilenceElement({
        type: 'Sentenceboundary',
        value: '500ms'
      });
      console.log(sentence.render());
      // Output: <mstts:silence type="Sentenceboundary" value="500ms"/>

      // Leading silence
      const leading = new SilenceElement({
        type: 'Leading-exact',
        value: '1s'
      });
      console.log(leading.render());
      // Output: <mstts:silence type="Leading-exact" value="1s"/>

      // Comma pause
      const comma = new SilenceElement({
        type: 'Comma-exact',
        value: '200ms'
      });
      console.log(comma.render());
      // Output: <mstts:silence type="Comma-exact" value="200ms"/>

      // Maximum duration (capped)
      const max = new SilenceElement({
        type: 'Tailing',
        value: '20000ms'
      });
      console.log(max.render());
      // Output: <mstts:silence type="Tailing" value="20000ms"/>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods