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

    Class AudioDurationElement

    SSML element for controlling the total audio duration (Azure-specific).

    The <mstts:audioduration> element adjusts the speech rate to make the audio output fit within a specified duration. This is useful for synchronizing speech with video, animations, or when you need precise timing control. The speech synthesizer will automatically speed up or slow down the speech to match the target duration.

    This is an Azure Speech Service specific extension and requires the mstts namespace. If the specified duration is shorter than the natural speech duration, the speech will be sped up. If longer, the speech will be slowed down.

    // Force speech to last exactly 10 seconds
    const element = new AudioDurationElement('10s');
    element.render();
    // Output: <mstts:audioduration value="10s"/>

    // Use with SSMLBuilder
    const ssml = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .audioDuration('5s')
        .text('This text will be adjusted to last exactly 5 seconds.')
      .build();
    • The audio duration affects all speech content that follows it within the same voice element
    • The speech rate adjustment may affect speech quality if the adjustment is too extreme
    • Consider using prosody rate adjustments for minor timing changes instead
    • This element cannot contain text or other elements

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    escapeXml render

    Constructors

    • Creates a new AudioDurationElement instance.

      Parameters

      • value: string

        The target duration for the audio output. Must be specified in seconds (e.g., '10s') or milliseconds (e.g., '5000ms'). The speech synthesizer will adjust the speaking rate to fit this duration. Valid range typically 0.5x to 2x the natural duration.

      Returns AudioDurationElement

      // Create with seconds
      const duration1 = new AudioDurationElement('10s');

      // Create with milliseconds
      const duration2 = new AudioDurationElement('5000ms');

      // Create for video synchronization
      const videoDuration = new AudioDurationElement('30s');

      Throws an error if value is not provided (compile-time in TypeScript)

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

      Generates the Azure-specific <mstts:audioduration> element with the specified duration value. This element is self-closing and does not contain any child elements.

      Returns string

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

      const element = new AudioDurationElement('15s');
      console.log(element.render());
      // Output: <mstts:audioduration value="15s"/>

      // Different duration formats
      const ms = new AudioDurationElement('10000ms');
      console.log(ms.render());
      // Output: <mstts:audioduration value="10000ms"/>

      const seconds = new AudioDurationElement('7.5s');
      console.log(seconds.render());
      // Output: <mstts:audioduration value="7.5s"/>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods