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

Package Sidebar


npm i polly-ssml-builder

Weekly Downloads






Last publish


  • softwarebymark