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

    Class VoiceConversionElementExperimental

    SSML element for voice conversion/transformation (Azure-specific, Preview).

    The <mstts:voiceconversion> element enables voice conversion, which transforms the characteristics of the synthesized voice using a pre-trained voice conversion model. This Azure Speech Service specific feature (currently in preview) allows you to modify voice output to match different voice characteristics while maintaining the original text and language. The element references a voice conversion model via URL that contains the transformation parameters.

    Voice conversion is useful for creating consistent voice experiences across different speakers, adapting voices for specific scenarios, or creating unique voice personalities. The conversion applies to all voices in the SSML document and must be placed as a direct child of the speak element, before any voice elements.

    // Basic voice conversion
    const conversion = new VoiceConversionElement('https://example.com/voice-model.json');
    conversion.render();
    // Output: <mstts:voiceconversion url="https://example.com/voice-model.json"/>

    // Use with SSMLBuilder
    const ssml = new SSMLBuilder({ lang: 'en-US' })
      .voiceConversion('https://example.com/custom-voice-transform.json')
      .voice('en-US-AvaNeural')
        .text('This voice will be transformed using the conversion model.')
      .build();
    • This is an Azure Speech Service specific extension requiring the mstts namespace
    • The feature is currently in preview and may change in future releases
    • The voiceconversion element is self-closing and cannot contain text or other elements [[11]]
    • Must be a direct child of the speak element, placed before voice elements [[11]]
    • Only one voice conversion element is allowed per SSML document
    • The URL must point to a valid voice conversion model accessible by the service
    • The conversion affects all voices in the document
    • Voice conversion models must be created and trained separately

    This feature is in preview and subject to change

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Methods

    escapeXml render

    Constructors

    • Experimental

      Creates a new VoiceConversionElement instance.

      Parameters

      • url: string

        The URL of the voice conversion model. Must be a publicly accessible HTTPS URL pointing to a valid voice conversion model file. The model contains the transformation parameters that will be applied to the voice output. The URL should point to a model that has been: - Pre-trained using Azure's voice conversion service - Hosted in a location accessible by the Speech service - Compatible with the current version of the voice conversion API Common formats include JSON configuration files or binary model files.

      Returns VoiceConversionElement

      // Standard voice conversion model
      const standard = new VoiceConversionElement(
        'https://models.example.com/voice-transform-v1.json'
      );

      // Custom trained model
      const custom = new VoiceConversionElement(
        'https://company.com/models/brand-voice-conversion.json'
      );

      // Regional model
      const regional = new VoiceConversionElement(
        'https://cdn.example.com/models/uk-accent-transform.json'
      );

      // Character voice transformation
      const character = new VoiceConversionElement(
        'https://game-assets.com/voices/character-transform.json'
      );

      // Age transformation model
      const ageTransform = new VoiceConversionElement(
        'https://models.example.com/young-to-elderly-voice.json'
      );

    Methods

    • Protected Experimental

      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;'
    • Experimental

      Renders the voice conversion element as an SSML XML string.

      Generates the Azure-specific <mstts:voiceconversion> element with the url attribute pointing to the voice conversion model. This is a self-closing element that doesn't contain any content or child elements. The element instructs the speech synthesizer to apply voice conversion transformation to all voices in the document using the specified model.

      Returns string

      The XML string representation of the voice conversion element in the format: <mstts:voiceconversion url="url"/>

      // Simple model URL
      const simple = new VoiceConversionElement(
        'https://example.com/model.json'
      );
      console.log(simple.render());
      // Output: <mstts:voiceconversion url="https://example.com/model.json"/>

      // Complex URL with path
      const complex = new VoiceConversionElement(
        'https://cdn.example.com/models/v2/transform-config.json'
      );
      console.log(complex.render());
      // Output: <mstts:voiceconversion url="https://cdn.example.com/models/v2/transform-config.json"/>

      // With query parameters
      const withParams = new VoiceConversionElement(
        'https://api.example.com/voice-model?version=2&type=standard'
      );
      console.log(withParams.render());
      // Output: <mstts:voiceconversion url="https://api.example.com/voice-model?version=2&type=standard"/>

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods