[![Node.js version][nodejs-badge]][nodejs] [![MIT][license-badge]][license]

speechmarkdown-js

Speech Markdown grammar, parser, and formatters for use with JavaScript.

Supported platforms:

amazon-alexa
amazon-polly
amazon-polly-neural
apple-avspeechsynthesizer
google-assistant
ibm-watson
microsoft-azure
microsoft-sapi
w3c
samsung-bixby
elevenlabs

Find the architecture here

Platform-specific SSML notes are tracked in docs/platforms. Use npm run docs:update-voices to refresh the auto-generated voice maps in src/formatters/data when vendor credentials are available.

Quick start

SSML - Amazon Alexa

Convert Speech Markdown to SSML for Amazon Alexa

const smd = require('speechmarkdown-js');

const markdown = `Sample [3s] speech [250ms] markdown`;
const options = {
  platform: 'amazon-alexa',
};

const speech = new smd.SpeechMarkdown();
const ssml = speech.toSSML(markdown, options);

The resulting SSML is:

<speak>
Sample <break time="3s"/> speech <break time="250ms"/> markdown
</speak>

SSML - Google Assistant

Convert Speech Markdown to SSML for Google Assistant

const smd = require('speechmarkdown-js');

const markdown = `Sample [3s] speech [250ms] markdown`;
const options = {
  platform: 'google-assistant',
};

const speech = new smd.SpeechMarkdown();
const ssml = speech.toSSML(markdown, options);

The resulting SSML is:

<speak>
Sample <break time="3s"/> speech <break time="250ms"/> markdown
</speak>

Plain Text

Convert Speech Markdown to Plain Text

const smd = require('speechmarkdown-js');

const markdown = `Sample [3s] speech [250ms] markdown`;
const options = {};

const speech = new smd.SpeechMarkdown();
const text = speech.toText(markdown, options);

The resulting text is:

Sample speech markdown

Options

You can pass options into the constructor:

const smd = require('speechmarkdown-js');

const markdown = `Sample [3s] speech [250ms] markdown`;
const options = {
  platform: 'amazon-alexa',
};

const speech = new smd.SpeechMarkdown(options);
const ssml = speech.toSSML(markdown);

Or in the methods toSSML and toText:

const smd = require('speechmarkdown-js');

const markdown = `Sample [3s] speech [250ms] markdown`;
const options = {
  platform: 'amazon-alexa',
};

const speech = new smd.SpeechMarkdown();
const ssml = speech.toSSML(markdown, options);

Available options are:

platform (string) - Determines the formatter to use to render SSML. Valid values are:
- "amazon-alexa"
- "amazon-polly"
- "amazon-polly-neural"
- "apple-avspeechsynthesizer"
- "google-assistant"
- "ibm-watson"
- "microsoft-azure"
- "microsoft-sapi"
- "w3c"
- "samsung-bixby"
- "elevenlabs"
includeFormatterComment (boolean) - Adds an XML comment to the SSML output indicating the formatter used. Default is false.
includeSpeakTag (boolean) - Determines if the <speak> tag will be rendered in the SSML output. Default is true.
includeParagraphTag (boolean) - Determines if the <p> tag will be rendered in the SSML output. Default is false.
preserveEmptyLines (boolean) - keep empty lines in markdown in SSML. Default is true.
escapeXmlSymbols (boolean) - Currently only for amazon-alexa and microsoft-azure. Escape XML text. Default is false.

voices (object) - give custom names to voices and use that in your markdown:

{
  "platform": "amazon-alexa",
  "voices": {
    "Scott": { "voice": { "name": "Brian" } },
    "Sarah": { "voice": { "name": "Kendra" } }
  }
}

{
  "platform": "google-assistant",
  "voices": {
    "Brian": {
      "voice": { "gender": "male", "variant": 1, "language": "en-US" }
    },
    "Sarah": {
      "voice": { "gender": "female", "variant": 3, "language": "en-US" }
    }
  }
}

Working on this project?

Grammar

The biggest place we need help right now is with the completion of the grammar and formatters.

Short Format

<input checked="" disabled="" type="checkbox"> break
<input checked="" disabled="" type="checkbox"> emphasis - strong
<input checked="" disabled="" type="checkbox"> emphasis - moderate
<input checked="" disabled="" type="checkbox"> emphasis - none
<input checked="" disabled="" type="checkbox"> emphasis - reduced
<input checked="" disabled="" type="checkbox"> ipa
<input checked="" disabled="" type="checkbox"> sub

Short-form examples:

(pecan)/'pi.kæn/ → <phoneme alphabet="ipa" ph="'pi.kæn">pecan</phoneme>
(Al){aluminum} → <sub alias="aluminum">Al</sub>
/ˈdeɪtə/ → <phoneme alphabet="ipa" ph="ˈdeɪtə">ipa</phoneme>

Standard Format

<input checked="" disabled="" type="checkbox"> address
<input checked="" disabled="" type="checkbox"> audio
<input checked="" disabled="" type="checkbox"> break (time)
<input checked="" disabled="" type="checkbox"> break (strength)
<input checked="" disabled="" type="checkbox"> characters / chars
<input checked="" disabled="" type="checkbox"> date
<input checked="" disabled="" type="checkbox"> defaults (section)
<input checked="" disabled="" type="checkbox"> disappointed
<input checked="" disabled="" type="checkbox"> disappointed (section)
<input checked="" disabled="" type="checkbox"> dj (section)
<input checked="" disabled="" type="checkbox"> emphasis
<input checked="" disabled="" type="checkbox"> excited
<input checked="" disabled="" type="checkbox"> excited (section)
<input checked="" disabled="" type="checkbox"> expletive / bleep
<input checked="" disabled="" type="checkbox"> fraction
<input checked="" disabled="" type="checkbox"> interjection
<input checked="" disabled="" type="checkbox"> ipa
<input checked="" disabled="" type="checkbox"> lang
<input checked="" disabled="" type="checkbox"> lang (section)
<input checked="" disabled="" type="checkbox"> mark
<input checked="" disabled="" type="checkbox"> newscaster (section)
<input checked="" disabled="" type="checkbox"> number
<input checked="" disabled="" type="checkbox"> ordinal
<input checked="" disabled="" type="checkbox"> telephone / phone
<input checked="" disabled="" type="checkbox"> pitch
<input checked="" disabled="" type="checkbox"> rate
<input checked="" disabled="" type="checkbox"> sub
<input checked="" disabled="" type="checkbox"> time
<input checked="" disabled="" type="checkbox"> unit
<input checked="" disabled="" type="checkbox"> voice
<input checked="" disabled="" type="checkbox"> voice (section)
<input checked="" disabled="" type="checkbox"> volume / vol
<input checked="" disabled="" type="checkbox"> whisper

Available scripts

clean - remove coverage data, Jest cache and transpiled files,
build - perform all build tasks
build:ts - transpile TypeScript to ES5
build:browser - creates single file ./dist.browser/speechmarkdown.js file for use in browser,
build:minify - creates single file ./dist.browser/speechmarkdown.min.js file for use in browser,
watch - interactive watch mode to automatically transpile source files,
lint - lint source files and tests,
test - run tests,
test:watch - interactive watch mode to automatically re-run tests

License

Licensed under the MIT. See the LICENSE file for details.

[nodejs-badge]: https://img.shields.io/badge/Node.js->=%2010.13-blue.svg [nodejs]: https://nodejs.org/dist/latest-v10.x/docs/api/ [license-badge]: https://img.shields.io/badge/license-MIT-blue.svg [license]: https://github.com/speechmarkdown/speechmarkdown-js/blob/master/LICENSE

Package detail