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

    SSML Builder Documentation - v1.0.1

    SSML Builder for TypeScript

    npm version License: MIT TypeScript Documentation

    A powerful, type-safe TypeScript library for building Speech Synthesis Markup Language (SSML) documents. Create expressive text-to-speech applications with Azure Speech Service and other SSML-compliant engines.

    • 🎯 Type-safe API - Full TypeScript support with comprehensive type definitions
    • πŸ”— Fluent Interface - Chainable methods for intuitive SSML document creation
    • πŸŽ™οΈ Azure Speech Service Support - Complete support for Azure-specific SSML extensions
    • πŸ“ W3C SSML 1.0 Compliant - Follows the official SSML specification
    • πŸ›‘οΈ Auto-escaping - Automatic XML character escaping for security
    • 🎨 Expressive Speech - Support for emotions, styles, and voice effects
    • πŸ“– Well-documented - Extensive JSDoc documentation with examples
    • ⚑ Zero Dependencies - Lightweight with no external dependencies
    npm install @andresayac/ssml-builder

    or with yarn:

    yarn add @andresayac/ssml-builder

    or with pnpm:

    pnpm add @andresayac/ssml-builder

    import { SSMLBuilder } from '@andresayac/ssml-builder';

    const ssml = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .text('Hello world! ')
        .emphasis('This is important', 'strong')
        .break('500ms')
        .text(' Thank you.')
      .build();

    console.log(ssml);
    // Output: <speak version="1.0" xmlns="http://www.w3.org/2001/10/synthesis" 
    //         xmlns:mstts="https://www.w3.org/2001/mstts" xml:lang="en-US">
    //           <voice name="en-US-AvaNeural">
    //             Hello world! <emphasis level="strong">This is important</emphasis>
    //             <break time="500ms"/> Thank you.
    //           </voice>
    //         </speak>

    Basic Text-to-Speech

    const builder = new SSMLBuilder({ lang: 'en-US' });

    const ssml = builder
      .voice('en-US-AvaNeural')
        .text('Welcome to our service.')
      .build();

    const conversation = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .text('Hello Andrew, how are you?')
      .voice('en-US-AndrewNeural')
        .text('I am doing great, thank you Ava!')
      .build();

    const emotional = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .expressAs('I am so happy to see you!', { 
          style: 'cheerful',
          styledegree: '2'
        })
      .build();

    const pronunciation = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .text('The company ')
        .phoneme('Azure', { 
          alphabet: 'ipa', 
          ph: 'Γ¦Κ’Ι™r' 
        })
        .text(' provides cloud services.')
      .build();

    const prosody = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .prosody('This is spoken slowly and quietly', {
          rate: 'slow',
          volume: 'soft',
          pitch: 'low'
        })
      .build();

    Say-As for Formatted Text

    const formatted = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .text('The date is ')
        .sayAs('2025-12-31', { 
          interpretAs: 'date',
          format: 'ymd'
        })
        .text(' and the amount is ')
        .sayAs('42.50', { 
          interpretAs: 'currency',
          detail: 'USD'
        })
      .build();

    const withMusic = new SSMLBuilder({ lang: 'en-US' })
      .backgroundAudio({
        src: 'https://example.com/music.mp3',
        volume: '0.5',
        fadein: '2000ms',
        fadeout: '1000ms'
      })
      .voice('en-US-AvaNeural')
        .text('This speech has background music.')
      .build();

    Structured Content

    const structured = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .paragraph(p => p
          .sentence(s => s
            .text('First sentence in the paragraph.')
          )
          .sentence(s => s
            .text('Second sentence with ')
            .emphasis('emphasis', 'strong')
            .text('.')
          )
        )
      .build();

    const multilingual = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaMultilingualNeural')
        .text('Hello! ')
        .lang('es-ES', lang => lang
          .text('Β‘Hola! ')
        )
        .lang('fr-FR', lang => lang
          .text('Bonjour!')
        )
      .build();

    The main builder class for creating SSML documents.

    const builder = new SSMLBuilder(options: SSMLOptions);
    • lang (required): Language/locale code (e.g., 'en-US', 'es-ES')
    • version (optional): SSML version (default: '1.0')
    • xmlns (optional): XML namespace
    • xmlnsMstts (optional): Microsoft TTS namespace
    • .voice(name: string, effect?: string) - Add a voice element
    • .backgroundAudio(options: BackgroundAudioOptions) - Add background audio
    • .voiceConversion(url: string) - Add voice conversion (Azure preview)
    • .build() - Generate the final SSML XML string

    Builder for voice elements with various speech modifications.

    • .text(text: string) - Add plain text
    • .audio(src: string, fallback?: string) - Add audio file
    • .bookmark(mark: string) - Add bookmark for tracking
    • .break(options?: BreakOptions | string) - Add pause
    • .emphasis(text: string, level?: EmphasisLevel) - Add emphasis
    • .expressAs(text: string, options: ExpressAsOptions) - Add emotional expression (Azure)
    • .lang(locale: string, callback: Function) - Switch language
    • .lexicon(uri: string) - Reference pronunciation lexicon
    • .paragraph(callback: Function) - Add paragraph
    • .phoneme(text: string, options: PhonemeOptions) - Specify pronunciation
    • .prosody(text: string, options: ProsodyOptions) - Modify speech characteristics
    • .sayAs(text: string, options: SayAsOptions) - Interpret formatted text
    • .sentence(callback: Function) - Add sentence
    • .silence(options: SilenceOptions) - Add silence (Azure)
    • .sub(original: string, alias: string) - Text substitution
    const customVoice = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .ttsEmbedding('custom-profile-id', 'Custom voice text')
      .build();

    const withViseme = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .viseme('redlips_front')
        .text('Text for lip-sync animation')
      .build();

    const timedAudio = new SSMLBuilder({ lang: 'en-US' })
      .voice('en-US-AvaNeural')
        .audioDuration('10s')
        .text('This will be adjusted to last exactly 10 seconds.')
      .build();

    Full API documentation is available at https://andresayac.github.io/ssml-builder

    Generate documentation locally:

    npm run docs

    Run the test suite:

    npm test

    Run tests with coverage:

    npm run test:coverage

    Build the library:

    npm run build

    Contributions are welcome! Please feel free to submit a Pull Request.

    1. Fork the repository
    2. Create your feature branch (git checkout -b feature/AmazingFeature)
    3. Commit your changes (git commit -m 'Add some AmazingFeature')
    4. Push to the branch (git push origin feature/AmazingFeature)
    5. Open a Pull Request

    This project is licensed under the MIT License - see the LICENSE file for details.

    This library is actively maintained. If you encounter any issues or have feature requests, please open an issue on GitHub.

    Made with ❀️ by andresayac

    Settings

    Member Visibility

    On This Page

    SSML Builder for TypeScript