{"id":28383952,"url":"https://github.com/calvinalvin/alexa-speechlet","last_synced_at":"2025-06-25T22:31:42.199Z","repository":{"id":57154257,"uuid":"100540495","full_name":"calvinalvin/alexa-speechlet","owner":"calvinalvin","description":"Alex Speech Synthesis Markup language generator. Makes it easy to do all the things","archived":false,"fork":false,"pushed_at":"2020-06-22T21:00:28.000Z","size":42,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-30T08:15:34.601Z","etag":null,"topics":["alexa","alexa-custom-skill","alexa-sdk","alexa-skill","alexa-skill-setup","alexa-skills-kit","alexa-voice-service","aws-lambda","markup","markup-language","ssml"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/calvinalvin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-08-16T23:16:32.000Z","updated_at":"2023-09-12T01:15:34.000Z","dependencies_parsed_at":"2022-09-06T13:12:13.210Z","dependency_job_id":null,"html_url":"https://github.com/calvinalvin/alexa-speechlet","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/calvinalvin/alexa-speechlet","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinalvin%2Falexa-speechlet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinalvin%2Falexa-speechlet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinalvin%2Falexa-speechlet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinalvin%2Falexa-speechlet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/calvinalvin","download_url":"https://codeload.github.com/calvinalvin/alexa-speechlet/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/calvinalvin%2Falexa-speechlet/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261962429,"owners_count":23236945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alexa","alexa-custom-skill","alexa-sdk","alexa-skill","alexa-skill-setup","alexa-skills-kit","alexa-voice-service","aws-lambda","markup","markup-language","ssml"],"created_at":"2025-05-30T07:38:21.188Z","updated_at":"2025-06-25T22:31:42.190Z","avatar_url":"https://github.com/calvinalvin.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Alexa Speechlet  \n##### Speech Synthesis Markup generator that makes it easy to do all the things\n\n------\n\nTo install:\n`npm install alexa-speechlet --save`\n\nexample usage\n```js\nconst Speechlet = require(\"alexa-speechlet\");\n\nlet speech = new Speechlet();\nlet todoList = ['buy shampoo', 'book flight to Seattle', 'make dinner reservations'];\nlet ssml = speech.sentence(\"This is your todo list\")\n                 .readAsOrdinalList(todoList, { pause: \"0.4s\" })\n                 .output();\n\n// outputs:\n// \u003cs\u003eThis is your todo list\u003c/s\u003efirst, buy shampoo\u003cbreak time=\"0.4s\" /\u003esecond, book flight to Seattle\u003cbreak time=\"0.4s\" /\u003ethird, make dinner reservations\n\n// then emit with alexa-sdk\n// this.emit(':tell', ssml);\n```\n\n##### Remember to call output()\n\nYou must execute the `output()` method on the speechlet instance in order to get the markup string. output() will not wrap the output in `\u003cspeak\u003e\u003c/speak\u003e` nodes. If you are working with `alexa-sdk` the sdk will do that for you in the final output. If you, however, do want the output markup to be wrapped with the 'speak' nodes then you can use `outputWithRootNode()`,\n\n##### Automatic special character escaping\n\nSpeechlet will automatically escape the special characters `\u0026`, `\u003c` and `\u003e` for you. (Except in the `say()` method, which will not modify any inputs since it allows raw xml inputs)\n\n### Methods\n\n---\n#### say(text)\n- `text` | {String} - What Alexa says\n\nAdds text to the markup without modifying or adding anything. It will spit out exactly what you enter as is. This is useful for generating complex nested markup that you cannot achieve through the other methods.\n\n```js\nlet simpleSpeech = new Speechlet();\nlet simpleSSML = simpleSpeech.say(\"Hi. This is a simple sentence.\").output();\n\n// simpleSSML outputs\n// Hi. This is a simple sentence.\n\nlet complexSpeech = new Speechlet();\nlet complexSSML = complexSpeech.say('\u003cs\u003eWhen \u003cemphasis level=\"strong\"\u003eI\u003c/emphasis\u003e wake up, \u003cprosody rate=\"x-slow\"\u003eI speak quite slowly\u003c/prosody\u003e\u003c/s\u003e').output();\n// complexSSML outputs\n// \u003cs\u003eWhen \u003cemphasis level=\"strong\"\u003eI\u003c/emphasis\u003e wake up, \u003cprosody rate=\"x-slow\"\u003eI speak quite slowly\u003c/prosody\u003e\u003c/s\u003e\n\n```\n\n---\n#### raw(text)\n- `text` | {String} - What Alexa says\n\nFor convenience and code readability. Exactly the same as `say()`\n\n---\n#### sentence(text)\n- `text` | {String} - What Alexa says\n\nWraps your text with `\u003cs\u003e\u003c/s\u003e` tags.\n\n```js\nlet ssml = new Speechlet().sentence(\"Hi, my name is Alexa\").output();\n// outputs:\n// \u003cs\u003eHi, my name is Alexa\u003c/s\u003e\n```\n\n---\n#### sayAs(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.interpretAs` adds 'interpret-as' attr to the markup. Such as `\u003csay-as interpret-as=\"spell-out\"\u003e`\n\nWraps your text with `\u003csay-as\u003e` tags\n\n```js\nlet ssml = new Speechlet(\"I can count.\").pause().sayAs(\"12345\", {interpretAs: \"digits\"}).output();\n// outputs:\n// I can count.\u003cbreak strength=\"strong\" /\u003e\u003csay-as interpret-as=\"digits\"\u003e12345\u003c/say-as\u003e\n```\n\nWe also expose convenience methods for the sayAs method for each interpretation. For instance instead of calling `speechlet.sayAs(\"12345\", {interpretAs: \"digits\"});` you can do `speechlet.sayAsDigits(\"12345\");`.\n\nWe do this for the following interpretations:\n - characters\n - spell-out\n - cardinal\n - ordinal\n - digits\n - fraction\n - unit\n - date\n - time\n - telephone\n - address\n - interjection (Useful for [speechcons](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speechcon-reference) Bazinga!)\n\n\nNote: The convenience fn are named `sayAs` + the capitalized version of the interpretation with dashes removed. So the convenience fn for \"spell-out\" would be `sayAsSpellout(text)`\n\n\nSee [here](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speech-synthesis-markup-language-ssml-reference#say-as) for the Alexa documentation for say-as. If I am missing anything feel free to make a PR.\n\n---\n\n#### sayAsDate(text, format)\n- `text` | {String} - What Alexa says\n- `format` | {String} - The format of the date Alexa will read it as. For example \"mdy\". Read the  [Alexa docs](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speech-synthesis-markup-language-ssml-reference#say-as) for explanation\n\nConvenience for `sayAs(text, {interpretAs: \"date\", format: \"mdy\"})`. sayAsDate accepts an extra \"format\" param.\n\n```js\nlet ssml = new Speechlet().sayAsDate(\"September 22, 2015\", \"mdy\").output();\n// outputs:\n// \u003csay-as interpret-as=\"date\" format=\"mdy\"\u003eSeptember 22, 2015\u003c/say-as\u003e\n```\n---\n\n#### sayAsVerb(text)\n- `text` | {String} - What Alexa says\n\nConvenience for `w(text, {role:\"amazon:VB\"})`. Pronounces the word as a verb.\n\n```js\nlet ssml = new Speechlet().sayAsVerb(\"read\").output();\n// outputs:\n// \u003cw role=\"amazon:VB\"\u003eread\u003c/w\u003e\n```\n---\n\n#### sayAsNoun(text)\n- `text` | {String} - What Alexa says\n\nConvenience for `w(text, {role:\"amazon:NN\"})`. Pronounces the word as a noun.\n\n```js\nlet ssml = new Speechlet().sayAsVerb(\"read\").output();\n// outputs:\n// \u003cw role=\"amazon:NN\"\u003eread\u003c/w\u003e\n```\n\n---\n\n#### sayAsPastParticiple(text)\n- `text` | {String} - What Alexa says\n\nConvenience for `w(text, {role:\"amazon:VBD\"})`. Pronounces the word in past tense.\n\n```js\nlet ssml = new Speechlet().sayAsVerb(\"read\").output();\n// outputs:\n// \u003cw role=\"amazon:VBD\"\u003eread\u003c/w\u003e\n```\n\n---\n#### amazonEffect(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.name` - The name of the effect. eg. \"whispered\"\n\nWraps text with `\u003camazon:effect\u003e` tags. Applies Amazon-specific effects to the speech.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.amazonEffect(\"I'm going to whisper this.\", { name: \"whispered\" }).output();\n\n// outputs:\n// \u003camazon:effect name=\"whispered\"\u003eI'm going to whisper this.\u003c/amazon:effect\u003e\n```\n\n---\n#### whisper(text)\n- `text` | {String} - What Alexa says\n\nConvenience fn for `amazonEffect(text, { name: \"whispered\" })`. Applies a whisper to the markup.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.whisper(\"I'm going to whisper this.\").output();\n\n// outputs:\n// \u003camazon:effect name=\"whispered\"\u003eI'm going to whisper this.\u003c/amazon:effect\u003e\n```\n\n---\n#### prosody(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.rate` - Modify the rate of the speech. eg. \"x-slow\", \"slow\", \"fast\", \"80%\"\n  - `options.pitch` - Raise or lower the tone (pitch) of the speech. eg \"high\", \"x-high\", \"low\", \"-50%\"\"\n  - `options.volume` - Change the volume for the speech. eg. \"silent\", \"high\", \"loud\", \"+4.08dB\"\n\nModifies the volume, pitch, and rate of the tagged speech.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"I'm going to say this really loud. Are you ready?\")\n                 .pause('1s')\n                 .prosody(\"AAHHH\", { volume: \"x-loud\" });\n                 .output();\n\n// outputs:\n// I'm going to say this really loud. Are you ready?\u003cbreak time=\"1s\" /\u003e\u003cprosody volume=\"x-loud\"\u003eAAHHH\u003c/prosody\u003e\n```\n\n---\n#### phoneme(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.alphabet` - Set to the phonetic alphabet to use eg. \"ipa\" or \"x-sampa\"\n  - `options.ph` - The phonetic pronunciation to speak. eg. \"pɪˈkɑːn\" for the word \"pecan\"\n\nWraps text in `\u003cphoneme\u003e` tags. See docs on [phonemes and supported symbols here](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speech-synthesis-markup-language-ssml-reference#phoneme). Phonemes provides a phonemic/phonetic pronunciation for the contained text. For example, people may pronounce words like “pecan” differently.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"You say, \")\n                 .phoneme(\"pecan\", { alphabet: \"ipa\", ph=\"pɪˈkɑːn\" })\n                 .say(\".I say, \")\n                 .phoneme(\"pecan\", { alphabet: \"ipa\", ph=\"ˈpi.kæn\" });\n                 .output();\n\n// outputs:\n// You say, \u003cphoneme alphabet=\"ipa\" ph=\"pɪˈkɑːn\"\u003epecan\u003c/phoneme\u003e.I say, \u003cphoneme alphabet=\"ipa\" ph=\"ˈpi.kæn\"\u003epecan\u003c/phoneme\u003e.\n```\n---\n#### break(options)\n- `options` | {Object}\n  - `options.strength` - \"none\", \"x-weak\", \"weak\", \"medium\", \"strong\", \"x-strong\"\n  - `options.time` - Duration of the pause; up to 10 seconds (10s) or 10000 milliseconds (10000ms). Include the unit with the time (s or ms).\nRepresents a pause in the speech. Set the length of the pause with the strength or time attributes.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"Let's see here\")\n  .break({ strength: \"x-strong\" })\n  .say(\"Oh here it is\")\n  .output();\n\n// outputs:\n// Let's see here\u003cbreak strength=\"x-strong\"\u003eOh here it is\n```\n\n---\n\n#### emphasis(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.level` - \"strong\", \"moderate\", \"reduced\"\n\nWraps the text with `\u003cemphasis\u003e` tags. Emphasize the tagged words or phrases. Emphasis changes rate and volume of the speech. More emphasis is spoken louder and slower. Less emphasis is quieter and faster. See [docs](https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/speech-synthesis-markup-language-ssml-reference#emphasis)\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"I already told you I\")\n                 .emphasis(\"really like\", { level: \"strong\" })\n                 .say(\"that person\")\n                 .output();\n\n// outputs:\n// I already told you I\u003cemphasis level=\"strong\"\u003ereally like\u003c/emphasis\u003ethat person\n```\n\n---\n\n#### pause(time=\"0.8s\")\n- `time` | {String} - The time value you want to pause. Defaults to \"0.8s\"\n\nConvenience method for break. Adds `\u003cbreak\u003e` markup to your text with a time value. If you want more flexibility, use the `break()` fn. Represents a pause in the speech. Set the length of the pause with the time attribute.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"Hmm let me think for a sec\")\n                 .pause(\"3s\")\n                 .say(\"Ok I think I figured it out\")\n                 .output();\n\n// outputs:\n// Hmm let me think for a sec\u003cbreak time=\"3s\"\u003eOk I think I figured it out\n```\n\n---\n\n#### audio(src)\n- `src` | {String} - The source url of the audio file\n\nThe audio tag lets you provide the URL for an MP3 file that the Alexa service can play while rendering a response. You can use this to embed short, pre-recorded audio within your service’s response. For example, you could include sound effects alongside your text-to-speech responses, or provide responses using a voice associated with your brand. For more information, see Including Short Pre-Recorded Audio in your Response.\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.audio(\"http://example.com/audio_file.mp3\")\n                 .output();\n\n// outputs:\n// \u003caudio src=\"http://example.com/audio_file.mp3\" /\u003e\n```\n\n---\n\n#### sub(text, options)\n- `text` | {String} - What Alexa says\n- `options` | {Object}\n  - `options.alias` - The url of the audio file\n\nThe word or phrase to speak in place of the tagged text.\n\n\n```js\nlet speech = new Speechlet();\nlet ssml = speech.say(\"My favorite chemical element is \")\n                 .sub(\"Al\", { alias: \"aluminum\" })\n                 .output();\n\n// outputs:\n// My favorite chemical element is \u003csub alias=\"aluminum\"\u003eAl\u003c/sub\u003e\n```\n\n---\n\n#### readAsList(list, options={})\n- `list` | {Array\u003cString\u003e} - Array of string items\n- `options` | {Object}\n  - `options.separator` {String} - separator between list items, default is \"and\"\n  - `options.lastSeparator` {String} - a string value to use for the last separator. For instance when reading a list, naturally you read the last item with a different conjunction. For instance. \"These are your books. Book 1, Book 2 and Book 3\" Notice that you say \"and Book 3\" for the last item.\n  - `options.pauseBeforeSeparator` {String} - adds a pause before separator, eg \"2s\"\n  - `options.pauseAfterSeparator` {String} - adds a pause after separator\n\nPass an array of strings that will be read as a list. The options allow for flexibility in controlling the dictation speed.\n\n```js\nlet speech = new Speechlet();\nlet list = ['dogs', 'cats', 'lions'];\nlet ssml = speech.sentence(\"I own lots of different types of animals.\")\n                 .readAsList(list, { separator: \"I have\", pauseBeforeSeperator: \"0.2s\", lastSeparator: 'and also' })\n                 .output();\n\n// outputs:\n// \u003cs\u003eI own lots of different types of animals.\u003c/s\u003eI have dogs \u003cbreak time=\"0.2s\" /\u003eI have cats \u003cbreak time=\"0.2s\" /\u003eand also lions\n```\n\n---\n\n#### readAsNumberedList(list, options={})\n- `list` | {Array\u003cString\u003e} - Array of string items\n- `options` | {Object}\n  - `options.pause` - adds a pause before seperator, default \"0.2s\"\n\nPass an array of strings that will be read as a numbered list.\n\n\n```js\nlet speech = new Speechlet();\nlet todoList = ['buy shampoo', 'book flight to Seattle', 'make dinner reservations'];\nlet ssml = speech.sentence(\"This is your todo list\")\n                 .readAsNumberedList(todoList, { pause: \"0.4s\" })\n                 .output();\n\n// outputs:\n// \u003cs\u003eThis is your todo list\u003c/s\u003e1, buy shampoo\u003cbreak time=\"0.4s\" /\u003e2, book flight to Seattle\u003cbreak time=\"0.4s\" /\u003e3, make dinner reservations\n```\n\n---\n\n#### readAsOrdinalList(list, options={})\n- `list` | {Array\u003cString\u003e} - Array of string items\n- `options` | {Object}\n  - `options.pause` - adds a pause before seperator, default \"0.2s\"\n\nPass an array of strings that will be read as an ordinal list. The numbered items are read in ordinal form (first, second, third etc...)\n\n\n```js\nlet speech = new Speechlet();\nlet todoList = ['buy shampoo', 'book flight to Seattle', 'make dinner reservations'];\nlet ssml = speech.sentence(\"This is your todo list\")\n                 .readAsOrdinalList(todoList, { pause: \"0.4s\" })\n                 .output();\n\n// outputs:\n// \u003cs\u003eThis is your todo list\u003c/s\u003efirst, buy shampoo\u003cbreak time=\"0.4s\" /\u003esecond, book flight to Seattle\u003cbreak time=\"0.4s\" /\u003ethird, make dinner reservations\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalvinalvin%2Falexa-speechlet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcalvinalvin%2Falexa-speechlet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcalvinalvin%2Falexa-speechlet/lists"}