# speechmarkdown-js

> Speech Markdown parser and formatters in TypeScript.

Latest version **2.3.1** (published 2026-03-27) · MIT license · 0 weekly downloads

## Install

```sh
npm install speechmarkdown-js
pnpm add speechmarkdown-js
yarn add speechmarkdown-js
bun add speechmarkdown-js
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 2.3.1 |
| Published | 2026-03-27 |
| First published | 2019-06-24 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >= 22 |
| Dependencies | 2 |
| Unpacked size | 2.6 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 82 |
| Author | Mark Tucker |
| Maintainers | rmtuckerphx, arjanscherpenisse |

## Links

- npm: https://www.npmjs.com/package/speechmarkdown-js
- Repository: https://github.com/speechmarkdown/speechmarkdown-js
- Homepage: https://github.com/speechmarkdown/speechmarkdown-js#readme
- Issues: https://github.com/speechmarkdown/speechmarkdown-js/issues
- npm.io page: https://npm.io/package/speechmarkdown-js

## Dependencies (2)

- [tslib](https://npm.io/package/tslib.md) ^1.10.0
- [myna-parser](https://npm.io/package/myna-parser.md) ^2.5.1

## Recent versions

- 2.3.1 (latest) — 2026-03-27
- 0.8.5-beta.0 (beta) — 2019-10-25
- 0.3.0-alpha.0 (alpha) — 2019-06-30
- 2.3.0 — 2025-11-09
- 2.2.0 — 2025-09-22
- 2.1.1 — 2025-05-30
- 2.1.0 — 2022-12-23
- 2.0.0 — 2021-10-29
- 1.9.0 — 2021-02-21
- 1.8.0 — 2021-01-02
- 1.7.0 — 2021-01-02
- 1.6.0 — 2020-08-12
- 1.5.0 — 2020-08-12
- 1.4.1 — 2020-08-11
- 1.4.0 — 2020-08-11
- … 17 more at https://npm.io/package/speechmarkdown-js/versions

## README

[![TypeScript version][ts-badge]][typescript-34]
[![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](./docs/architecture.md)

Platform-specific SSML notes are tracked in [`docs/platforms`](./docs/platforms/README.md). 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

```js
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:

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

### SSML - Google Assistant

Convert Speech Markdown to SSML for Google Assistant

```js
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:

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

### SSML - Microsoft Azure

Convert Speech Markdown to SSML for Microsoft Azure with automatic MSTTS namespace injection

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

const markdown = `(This is exciting news!)[excited:"1.5"] The new features are here.`;
const options = {
  platform: 'microsoft-azure',
};

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

The resulting SSML is:

```xml
<speak xmlns:mstts="https://www.w3.org/2001/mstts">
<mstts:express-as style="excited" styledegree="1.5">This is exciting news!</mstts:express-as> The new features are here.
</speak>
```

Azure supports 27 express-as styles including emotional styles (excited, disappointed, friendly, cheerful, sad, angry, etc.) and scenario-specific styles (newscaster, customerservice, chat, etc.). See [Azure platform documentation](./docs/platforms/azure.md) for complete details.

### Plain Text

Convert Speech Markdown to Plain Text

```js
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:

```text
Sample speech markdown
```

## More

### Options

You can pass `options` into the constructor:

```js
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`:

```js
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:

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

  ```json
  {
    "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

- [x] break
- [x] emphasis - strong
- [x] emphasis - moderate
- [x] emphasis - none
- [x] emphasis - reduced
- [x] ipa
- [x] 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

- [x] address
- [x] audio
- [x] break (time)
- [x] break (strength)
- [x] characters / chars
- [x] date
- [x] defaults (section)
- [x] disappointed
- [x] disappointed (section)
- [x] dj (section)
- [x] emphasis
- [x] excited
- [x] excited (section)
- [x] expletive / bleep
- [x] fraction
- [x] interjection
- [x] ipa
- [x] lang
- [x] lang (section)
- [x] mark
- [x] newscaster (section)
- [x] number
- [x] ordinal
- [x] telephone / phone
- [x] pitch
- [x] rate
- [x] sub
- [x] time
- [x] unit
- [x] voice
- [x] voice (section)
- [x] volume / vol
- [x] 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](https://github.com/speechmarkdown/speechmarkdown-js/blob/master/LICENSE) file for details.

[ts-badge]: https://img.shields.io/badge/TypeScript-3.4-blue.svg
[typescript]: https://www.typescriptlang.org/
[typescript-34]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-4.html
[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

---
_Source: https://npm.io/package/speechmarkdown-js · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._