0.7.6 • Published 5 years ago
ssml-gib v0.7.6
ssml-gib
Helper library for generating SSML for use in Alexa Skills.
See also ask-gib for authoring Alexa Skills in TypeScript.
Ssml
class- Factory functions
<phoneme>
<emphasis>
<prosody>
<amazon-effect>
<audio>
<break>
(pause)<sub>
<w>
<sayAs>
<p>
<s>
- (Hmmm, still up-to-date?) Full support for SpeechCons in English (US), English (UK), and German
- Leverage TypeScript auto-complete for each SpeechCon.
- Helper functions
- Wrap/Unwrap
<speak>
- Useful to be able to unwrap as well.
stripSsml(text: string)
- Wrap/Unwrap
- Factory functions
All of the following levels and settings are checked at compile time with TypeScript pseudo-enums (discriminated
unions of string literals), so e.g., you can't typo "low" when you actually meant "slow" when defining a rate.
So instead of trying to remember all the intricacies of the <prosody>
tag in all its
glory, you can just hit ctrl+space and see the options available. This stems from
TypeScript and vscode auto-complete goodness.
Installation
Install with npm:
npm install --save ssml-gib
Import ES6 style:
// for Ssml helper only
import { Ssml } from 'ssml-gib';
// for SpeechCons
import { Ssml, Con } from 'ssml-gib';
Usage
Each function returns a string that contains the SSML, which is especially useful when combined with JavaScript's templated strings.
Phoneme
Ssml.phoneme("functacular", "fʌŋktækjulɝ"); // "ipa" is the default
Ssml.phoneme("functacular", "fʌŋktækjulɝ", "ipa"); // or to be explicit...
Ssml.phoneme("functacular", "fVNkt{kjul@`", "x-sampa"); // x-sampa also supported
let ssml = `The word of the day is ${Ssml.phoneme("functacular", "fʌŋktækjulɝ")}.`;
// The word of the day is <phoneme alphabet="ipa" ph="${funkIPA}">functacular</phoneme>.
Emphasis
Ssml.emphasis("emphasize me"); // defaults to moderate
Ssml.emphasis("emphasize me", "strong"); // explicit strong
let ssml = `This is ${Ssml.emphasis("very")} important.`;
// This is <emphasis level="moderate">very</emphasis> important.
Prosody
Ssml.prosody("say me slowly", {rate: "slow"});
Ssml.prosody("say me like a chipmunk", {pitch: "x-high"}); // preset pitch
Ssml.prosody("say me like a chipmunk", {pitch: 50}); // increase pitch by %50
Ssml.prosody("say me like thunder", {pitch: -30}); // decrease pitch by %30
Ssml.prosody("shout me!", {volume: "loud"}); // preset increase
Ssml.prosody("shout me!", {volume: 4}); // specify in decibels
Ssml.prosody("shout me!", {volume: -12}); // min decibels
// combine them
let ssml = `Well, ${Ssml.prosody("hello there...", { rate: "slow", pitch: "low", volume: "soft" })}`;
// Well, <prosody rate="slow" pitch="low" volume="soft">hello there...</prosody>
SpeechCons
Ssml.speech(Con.arrivederci);
Ssml.speech(Con.bada_bing_bada_boom);
Ssml.speech(ConUK.blimey); // ConUK for English (UK)
Ssml.speech(ConDE.achtung); // ConDE for German (Deutsch)
let ssml = `To open the door, say ${Ssml.speech(Con.abracadabra)}!`;
// To open the door, say <say-as interpret-as="interjection">abracadabra</say-as>!
Amazon Effect
// change the import to include the `Effect` object.
import { Ssml, Effect } from 'ask-gib';
Ssml.amazon(Effect.whispered, "Be vewy, vewy quiet...");
let ssml = `My secret is this: ${Ssml.amazon(Effect.whispered, "I have no secrets.")}`;
// My secret is this: <amazon:effect name="whispered">I have no secrets.</amazon:effect>
Audio
Ssml.audio("https123://x.y.z/audio.mp3");
let ssml = `Welcome! ${Ssml.audio("httpsss://x.y.z/welcome_jingle.mp3")}`;
// Welcome! <audio src="httpsss://x.y.z/welcome_jingle.mp3" />
Break (Pause)
Ssml.break({ strength: "strong" });
Ssml.break({ ms: 500 });
let ssml = `You have three seconds to think about it...${Ssml.break({ s: 3 })}`;
// You have three seconds to think about it...<break time="3s"/>
Sub
Ssml.sub("Mg", "Magnesium");
let ssml = `Bronze is made with ${Ssml.sub("Cu", "copper")} and ${Ssml.sub("Sn", "tin")}.`;
// Bronze is made with <sub alias="copper">Cu</sub> and <sub alias="tin">Sn</sub>.
W (Part of Speech)
Ssml.w("read", PartOfSpeech.past_participle);
Ssml.w("bass", PartOfSpeech.sense1);
let ssml = `Use the 'w' tag to disambiguate how to pronounce words like '${Ssml.w("lead", PartOfSpeech.noun)}'.`;
// Use the 'w' tag to disambiguate how to pronounce words like '<w role="amazon:NN">lead</w>'.
say-as
Ssml.sayAs({ text: "misspelling", interpret: As.characters });
Ssml.sayAs({ text: "misspelling", interpret: As.spell_out });
Ssml.sayAs({ text: "1lb.", interpret: As.unit });
Ssml.sayAs({ text: "5555551234", interpret: As.telephone });
Ssml.sayAs({ text: "1+1/2", interpret: As.fraction });
let ssml = Ssml.sayAs({ text: "frack", interpret: As.expletive });
// <say-as interpret-as="expletive">frack</say-as>
Thanks
- Amazon for creating such good documentation and a good product.
- Up.