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

    Class BreakElement

    SSML element for inserting pauses or breaks in synthesized speech.

    The <break> element provides control over pauses between words or sentences in the speech output. It can be used to add natural pauses for better comprehension, create dramatic effects, or override the default pause behavior of the speech synthesizer. Breaks can be specified either semantically (using strength levels) or with explicit durations.

    The Speech service automatically inserts pauses based on punctuation and sentence structure, but the break element allows you to customize this behavior for more natural or expressive speech.

    // Default break (medium strength, 750ms)
    const defaultBreak = new BreakElement();
    defaultBreak.render();
    // Output: <break/>

    // Break with specific duration
    const timedBreak = new BreakElement({ time: '500ms' });
    timedBreak.render();
    // Output: <break time="500ms"/>

    // Break with strength level
    const strongBreak = new BreakElement({ strength: 'strong' });
    strongBreak.render();
    // Output: <break strength="strong"/>

    // Use with SSMLBuilder
    const ssml = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .text('First part')
        .break('2s')  // 2 second pause
        .text('Second part')
      .build();
    • If no options are provided, a default medium-strength break (750ms) is inserted
    • The time attribute takes precedence over strength if both are specified
    • Valid time range is 0-20000ms (20 seconds maximum)
    • Values exceeding 20000ms are automatically capped at 20000ms
    • Breaks can be inserted anywhere within text content
    • Multiple consecutive breaks are additive in duration

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    escapeXml render

    Constructors

    • Creates a new BreakElement instance.

      Parameters

      • Optionaloptions: BreakOptions

        Optional configuration for the break element. If not provided, creates a default break with medium strength (750ms).

        Configuration options for break/pause elements.

        Defines pauses in speech either by strength (semantic) or explicit duration. If both are specified, time takes precedence.

        • Optionalstrength?: BreakStrength

          Semantic strength of the pause.

          Each strength corresponds to a typical pause duration:

          • x-weak: 250ms (very short)
          • weak: 500ms (short, like a comma)
          • medium: 750ms (default, like a period)
          • strong: 1000ms (long, like paragraph break)
          • x-strong: 1250ms (very long, for emphasis)

          Ignored if time is specified.

          "medium"

          "strong"
        • Optionaltime?: string

          Explicit duration of the pause.

          Specified in milliseconds (ms) or seconds (s). Valid range: 0-20000ms (20 seconds max) Values above 20000ms are capped at 20000ms.

          Takes precedence over strength if both are specified.

          "500ms" - Half second

          "2s" - 2 seconds

          "1500ms" - 1.5 seconds

      Returns BreakElement

      // Default break (no options)
      const defaultBreak = new BreakElement();

      // Semantic strength breaks
      const weakBreak = new BreakElement({ strength: 'weak' });      // 500ms
      const mediumBreak = new BreakElement({ strength: 'medium' });  // 750ms
      const strongBreak = new BreakElement({ strength: 'strong' });  // 1000ms

      // Explicit duration breaks
      const halfSecond = new BreakElement({ time: '500ms' });
      const twoSeconds = new BreakElement({ time: '2s' });
      const precise = new BreakElement({ time: '1250ms' });

      // Both specified (time takes precedence)
      const override = new BreakElement({ 
        strength: 'weak',  // Ignored
        time: '3s'         // This is used
      });

      // For dramatic effect
      const dramatic = new BreakElement({ time: '3000ms' });

      // For natural speech flow
      const natural = new BreakElement({ strength: 'medium' });

    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 break element as an SSML XML string.

      Generates the <break> element with appropriate attributes based on the provided options. The element is self-closing and doesn't contain any content. The method handles three cases:

      1. No options: Renders a simple break element with default behavior
      2. With options: Includes strength and/or time attributes as specified
      3. Empty options: Falls back to default break element

      The attributes are only included if their values are defined, keeping the XML clean and avoiding unnecessary attributes.

      Returns string

      The XML string representation of the break element in one of these formats: - <break/> (default, no options) - <break strength="value"/> (with strength only) - <break time="value"/> (with time only) - <break strength="value" time="value"/> (both specified, time takes precedence)

      // Default break
      const break1 = new BreakElement();
      console.log(break1.render());
      // Output: <break/>

      // With strength
      const break2 = new BreakElement({ strength: 'strong' });
      console.log(break2.render());
      // Output: <break strength="strong"/>

      // With time
      const break3 = new BreakElement({ time: '1500ms' });
      console.log(break3.render());
      // Output: <break time="1500ms"/>

      // With both (time takes precedence in synthesis)
      const break4 = new BreakElement({ 
        strength: 'weak', 
        time: '2s' 
      });
      console.log(break4.render());
      // Output: <break strength="weak" time="2s"/>
      // Note: When synthesized, only the time="2s" is used

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods