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.

Install

npm install polly-ssml-builder

Usage

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.")
    .build();

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")
    .build();

PollySsmlBuilder.ALPHABET_IPA specifies the "ipa" language.

Break

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

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

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)
    .build();

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)
    .build();

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

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.")
    .build();

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.")
    .endParagraph()
    .build();

Both of these options produce the same result.

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

Sentences

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

Languages

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.

Authors

• Mark Borner - Initial work - Software By Mark

License

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