Pug SSML

Pug SSML is a library for easily generating SSML speech text using the pug templating language.

Introduction

I started generating a good amount of SSML speech text while writing Alexa skills. I found it tedious and clumsy to do so with vanilla JavaScript. I did find a few libraries for generating SSML though most of them utilize function chaining in order to create speech text. While this can be effective I found it problematic when generating nested speech tags. I felt like the Pug templating language is an easy solution for generating SSML speech text. While I sure this will not be preferable to everyone I found it very easy to work with.

Simple Example

A simple example. All three variations generate roughly the same output.

s This is a template for a simple sentence.
s.
  This is a template for a simple sentence.
s
  | This is a template for a simple sentence.

Output:

<s>This is a template for a simple sentence.</s>

Better Example

s
  | This is a sentence with
  prosody volume("loud") loud
  | text embedded within it.

Output:

<s>This is a sentence with<prosody volume="loud">loud</prosody>text embedded within it.</s>

Hierarchical Example using Provided Mixins.

Here is an example with loud/fast speech embedded in it. This example utilizes nesting of ssml elements. The ssml elements are generated using mixins provided by this library to make templates easier to write.

s
  | This is a sentence with
  +loud
    +fast
      | loud and fast
  | speech embedded within in.

Output:

<s>
    This is a sentence with
    <prosody volume="loud"><prosody rate="fast">loua and fast</prosody></prosody>
    speech embedded within it.
</s>

Kitchen Sink

Here is a complex usage. Refer to the Pug documentation for additional details.

// This is a comment.

//- This is a comment that won't show up in the template.

//- This is an example logic usage based on a template context.
if someVar
  s Some variable was true: #{someVar}.
else
  s Some variable was false: #{someVar}.
  
//- This is an example of nesting mixins.
s
  +loud
    +fast
      +high
        | This is some loud, fast, and high speech!
        
s
  | You can also pass in #{helper()} functions in the template context.

Usage

Install

Install the library as a development dependency.

npm install pug-ssml --save-dev

After installing you can use the library to compile Pug templates into a standard Node module. For example...

Create Templates

Create Pug templates in a ./templates folder.

//- ./templates/mytemplate.pug
s
  | This is a simple template.

Compile Templates

Compile the templates into a node module using one of the options below. Both options will generate a ssml-speech.js file that can be imported into your project.

There is currently a version of the cli being tested. It can be downloaded at the following url.

https://github.com/blueshirts/pug-ssml-cli

If the cli is not working for you or is no preferable you can create a simple script that can be run to compile templates to a Node module. For my current use I use a Makefile with a simple .js script. You could also easily run it from Grunt or a similar tool.

// Require the tool.
const pug = require('pug-ssml')

// Compile the templates into a Node module.
pug.precompile('./templates', {
    basedir: './node_modules/pug-ssml',
    file: 'ssml-speech.js',
    pretty: false
})

Require the Module

Require the ssml-speech.js file like any other module.

const templates = require('./ssml-speech')

Run the Template

Invoke a template function.

// A template with no context parameters.
templates.mytemplate()

// A template with context parameters.
const context = {
  someValue: 'A value to pass in.',
  'helper': function() {
    return 'Some helper value!'
  }
}
templates.mytemplate(context)

Use the Output

Use the result text to generate speech.

// Send the text to a speech engine.
const text = templates.mytemplate()
this.response.speak(text).listen(text)

Compiler Options

You can pass user options to the precompile function.

pug.precompile(template, options)

Output

The output parameter specifies where the generated module will be created.

{
  output: './dist'
} 

File

The file parameter specifies the name of the generated module.

{
  file: 'ssml-speech.js'
}

compileDebug

If you are concerned about the size of the output module disable debug. Note that the error messages you will receive may not be helpful with this option off. compileDebug is a standard Pug option.

const options = {
  compileDebug: false
}

Other Options

The Pug library which this pug-ssml is built on top of has many available options. See the pug reference the other available options.

https://pugjs.org/api/reference.html

Available Mixins

There are many defined that are automatically available to your templates. Below is an example of using loud. Note that there is no space after the plus symbol.

//  Loud speech sentence.
s This is some
  +loud loud speech!

Tags and plugins can be nested to form unqiue speech sounds.

// Loud and fast speech sentance.
s This is some
  +loud
    +fast
      loud and fast speech!

See the following file for the supported Mixin definitions.

Pug SSML Mixins

The templates generally follow the Amazon SSML definitions.

Template Names

Templates with dashes in the names are automatically converted to underscores in the JavaScript output.

Template Spacing

Pug ignores much of the whitespace within templates. See the following link for more details.

https://pugjs.org/language/plain-text.html#whitespace-control

The safest way to ensure a space is added within your template is to add a newline using a pipe.

p Paragraph one text.
|
p Paragraph two text.

Note that in this case the space was not needed because each of the paragraphs is embedded within an element.

In most cases this is not an issue because spaces are assumed by SSML in many cases.

A simple English example is "cupboard"; outside the token and w elements, the synthesis processor will treat this as the two tokens "cup" and "board" rather than as one token (word) with a pause in the middle. Breaking one token into multiple tokens this way will likely affect how the processor treats it.

See the following link for additional details.

https://www.w3.org/TR/speech-synthesis11/

Caveats

The current code base relies on an internal absolute template include. Because of this dependency this module expects to find the pug-ssml-mixins.pug in the absolute template directory (i.e. pug basedir). If you are not using absolute template includes (or using relative includes) then this issue will not effect you. If you are using absolute includes then you may need to copy the pug-ssml-mixins.pug file into your absolute include directory. This directory is specified using the options.basedir property. In this module it defaults to '.'. Note that that default may not be the case for derived modules such as the pug-ssml-cli.

ToDo

Global include issue

• Document the global include issue, find an alternative.
• If the current approach is not preferable the mixins file can be copied in your absolute basedir instead.

Alexa

• Add Alexa examples.

Lint

• Look into using pug lint.