Nocturnal Parakeet Monitor


    1.0.1 • Public • Published

    Polly SSML Builder

    A utility for building valid SSML for use with Amazon Web Services Lex and Polly services.

    Amazon Lex & Polly support a subset of the SSML markup tags as defined by Speech Synthesis Markup Language (SSML) Version 1.1, W3C Recommendation.

    Using a Builder Pattern, PollySsmlBuilder allows you to programmatically build up a valid SSML string.


    npm install polly-ssml-builder


    Start by requiring the library.

    const PollySsmlBuilder = require("polly-ssml-builder");

    Then, for each SSML String you want to create, do the following:

    • create a new PollySsmlBuilder
    • call methods to speak text
    • build the String result
    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speak("Don't tell anyone, but ")
        .whisper("I see dead people.")

    This produces the following String:

    <speak>Don't tell anyone, but <amazon:effect name="whispered">I see dead people.</amazon:effect></speak>

    All options are available as constants on the PollySsmlBuilder class. For example:

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speakPhonetically("pecan", pollySsmlBuilder.ALPHABET_IPA, "pɪˈkɑːn")

    PollySsmlBuilder.ALPHABET_IPA specifies the "ipa" language.


    To add a break (pause) into the speech, call addBreak().

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speak("Legen - wait for it.")

    The duration parameter can be one of the following:

    • The number of seconds specified as "10s" for 10 seconds
    • The number of milliseconds specified as "500ms" for 500 milliseconds
    • One of the BREAK_* constants

    Speak with Volume

    To change the volume of speech, call speakWithVolume().

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speakWithVolume("I'm shouting!", pollySsmlBuilder.VOLUME_XTRA_LOUD)

    The volume parameter can be one of the following:

    • An increase in volume as "+5dB" will increase the volume by 5 decibels
    • A decrease in volume as "-3dB" will decrease the volume by 3 decibels
    • One of the VOLUME_* constants

    Speak with Pitch

    To change the pitch of speech, call speakWithPitch().

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speakWithPitch("I'm speaking with a high voice!", pollySsmlBuilder.PITCH_HIGH)

    The pitch parameter can be one of the following:

    • A percent increase in pitch as "+7%" will increase the pitch by 7 percent
    • A percent decrease in pitch as "-5%" will decrease the pitch by 5 percent
    • One of the PITCHE_* constants


    Paragraphs can be spoken with one method call:

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.speakWithParagraph("The quick brown fox jumped over the lazy dog.  It is a sentence that contains all the letters of the alphabet.")

    Or with multiple methods calls:

    let pollySsmlBuilder = new PollySsmlBuilder();
    let ssml = pollySsmlBuilder.startParagraph()
        .speak("The quick brown fox jumped over the lazy dog.  ")
        .speak("It is a sentence that contains all the letters of the alphabet.")

    Both of these options produce the same result.

    If you forget to call endParagraph() before you build(), an Error will be thrown.


    Sentences work similar to paragraphs - they can be spoken with one method call, or multiple method calls.


    Speaking in a language works similar to paragraphs - it can be spoken with one method call, or multiple method calls.

    The language parameter is not defined by a constant. This is to allow new languages to be added by Amazon Web Services without the need to update this utility. A warning will be logged if a language is not recognised.

    See SUPPORTED_LANGUAGES array for a list of currently supported languages.

    Supported Tags

    For a full list of supported SSML tags, see SSML Tags in Amazon Polly

    All tags listed as of July 2017 are supported by this builder.



    This project is licensed under the Apache 2.0 License - see the LICENSE.txt file for details

    Change History

    Release 1.0.0

    • initial release

    Release 1.0.1

    • refactoring to provide extensibility
    • renamed SsmlBuilder to PollySsmlBuilder
    • fixed spelling in Readme


    npm i polly-ssml-builder

    DownloadsWeekly Downloads






    Last publish


    • softwarebymark