node-ssml
A Node.js library for producing SSML (Speech Synthesis Markup Language) according to specifications.
Currently, this library only implements SSML 1.0. The documentation also assumes that the reader has at least skimmed through the specification.
As of v0.0.2, only the following elements of SSML are supported:
- say-as
- prosody
- audio
- break
- sub
Basic Usage
This library makes use of method chaining for convenience.
var ssml = ;var ssmlDoc = ; ssmlDoc ;
Output:
XML output examples in the later section assume pretty
is set to true for the toString()
function (described later), for easier reading.
Initialization
Simply initialize a document instance as follows:
var ssml = ;...var ssmlDoc =
The document is initialized with the language set to en-US
by default. To use a different language, specify it in the language
parameter:
var ssmlDoc = language: 'fr-FR' ;...ssmlDoc
Output:
Elements
Note that all functions, including elements, are object-based, and not static.
say(text[, options]) / say(options)
Produces basic text output. Usage is as follows:
ssmlDoc;
The text string can also be described by the text
parameter.
interpretAs
can also be specified as an additional parameter, but will encapsulate the text-output into a say-as
element. More parameters can be specified for the say-as
element, only if interpretAs
is used:
format
detail
Their respective purposes can be found in the specification.
Example:
ssmlDoc ;
Output:
break(time[, options]) / break(options)
Represents a pause in the speech. Accepts one of the following parameters:
time
- Can be a string or number. If passed as a number, it will be converted to a string automatically, and appended withms
. Will overridestrength
if defined.strength
- A string value that describes the length of time in a human-readable form i.e.weak
,medium
,strong
.
time
may also be defined as the first parameter of the break
function for convenience, i.e.:
// 500ms
Additional information on these parameters can be found in the specification.
Example:
ssmlDoc ;
Output:
prosody(options)
Represents a speech adjustment. Any element contained in a prosody
element will receive the adjustments described by its parameters.
prosody
also switches the internal context of the SSML document, so that further element calls will render elements within the prosody
element. Use up()
(covered later) to reset the context to the previous level.
Accepts any of the following parameters, alone or in combination:
pitch
- A string or number that controls the pitch of the spoken text. If a number is supplied,Hz
will be appended to the output.rate
- A string or number that controls the speed of the spoken text.range
- A string or number that controls the pitch range of the spoken text. If a number is supplied,Hz
will be appended to the output.volume
- A string or number that controls the volume of the spoken text.contour
- a string containing a set of values to finely tune the pitch of the spoken text.
Additional information on these parameters can be found in the specification.
Example:
// Produce a sarcastic apology.ssmlDoc ;
Output:
audio(src[, options]) / audio(options)
Represents an audio resource. Accepts the following parameters:
src
orsource
- The URI pointing to a valid audio resource. Required.alt
- A string that is rendered by the speech processor if the audio resource cannot be found. Optional.
src
may also be defined as the first parameter of the audio
function for convenience, i.e.:
Additional information on these parameters can be found in the specification.
Example:
// Rickroll the guy.ssmlDoc ;
Output:
Helper functions
up()
This function sets the internal context to the previous level in XML. If there is no previous level, the function does nothing.
Note that as of v0.0.2, this is a mutable operation affecting the SSML document object, and cannot be reversed.
Example:
// Mock the userssmlDoc ;
Output:
clear()
This function clears all elements from the SSML document object.
replace(wordToReplace, replaceWith) / replace(keyValues)
This function replaces all instances of the word(s) with another word/set of words. These can be passed in as the first and second parameters for a single key-value pair, or as an object containing key-value pairs. The words will then be added to an internal dictionary and processed only when toString()
is called.
Note that the replace
function is case-sensitive, and does not modify the original text.
The replaced words will still be rendered, but wrapped in a sub
element. Additional information about this element can be found in the specification.
Example:
ssmlDoc ;
Output:
addReplace(wordToReplace, replaceWith) / replace(keyValues)
Alias for replace
.
removeReplace(key)
This function removes the key from the internal dictionary. If an array of strings is provided, all keys matching the elements in the array will be removed.
clearReplace()
Clears all keys from the internal dictionary.
Output
toString(options)
Renders the SSML document as a string, which can be passed to the speech processor through a suitable medium later.
Accepts the following parameters:
minimal
- setting this to true renders aspeak
XML root element with no properties (including required properties such asxml:lang
) or XML header. Takes priority overfull
.full
- setting this to true renders aspeak
XML root element with required and optional properties.
Additionally, as the xmlbuilder
library is being used, the options object may also contain any parameters suitable for the toString()
method, such as pretty
or indent
. Refer to the xmlbuilder
documentation for details.
Examples:
ssmlDoc;
Output:
ssmlDoc;
Output:
Hello there!
ssmlDoc;
Output: