SSML Builder (for Amazon Alexa)
This gem implements a full suite of tools for working with SSML particularly with Amazon's Alexa. For full SSML documentation, please see: Amazon SSML Reference
Installation
For Ruby Projects:
Add this line to your application's Gemfile:
gem 'ssml_builder'
And then execute:
$ bundle
Or install it yourself as:
$ gem install ssml_builder
Usage
This Gem provides methods to generate ssml strings using the core Builder module as well as providing an extension of the string class if that usage is preferred.
SsmlBuilder::Builder
Basic Usage
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.say("Hello, how are you today?")
ssml_builder.pause("1s")
ssml_builder.p("This is a new paragraph.")
ssml_buider.ssml
# Output: "<speak>Hello, how are you today? <break time=\"1s\"/><p>This is a new paragraph.</p></speak>"
Available Commands
- say
- paragraph
- p
- sentence
- rate
- pitch
- volume
- pause
- break
- emphasis
- audio
- spell_out
- characters
- cardinal
- number
- ordinal
- digits
- fraction
- unit
- date
- time
- telephone
- phone
- address
- interjection
- expletive
- sub
- whisper
- amazon_verb
- amazon_participle
- amazon_noun
- amazon_sense
- phoneme
say
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.say("Hello, how are you today?")
ssml_buider.ssml
# Output: "<speak>Hello, how are you today?</speak>"
paragraph
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.paragraph("Hello, how are you today?")
ssml_buider.ssml
# Output: "<speak><p>Hello, how are you today?</p></speak>"
p
Alias for paragraph
sentence
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.sentence("Hello, how are you today?")
ssml_buider.ssml
# Output: "<speak><s>Hello, how are you today?</s></speak>"
rate
parameters
- string
- rate
- optional, default: "medium"
- can be integer or string
- valid text inputs: "x-slow", "slow", "medium", "fast", "x-fast"
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.rate("Text",90)
ssml_buider.ssml
# Output: "<speak><prosody rate=\"90%\">Text</prosody></speak>"
pitch
parameters
- string
- pitch
- optional, default: "medium"
- can be integer, float, or string
- minimum -33.3
- maximum 50
- valid text inputs: "x-low", "low", "medium", "high", "x-high"
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.pitch("Text",50)
ssml_buider.ssml
# Output: "<speak><prosody pitch=\"+50%\">Text</prosody></speak>"
volume
parameters
- string
- volume
- optional, default: "medium"
- can be integer, float, or string
- maximum 4.08
- valid text inputs: "silent", "x-soft", "soft", "medium", "loud", "x-loud"
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.volume("Text",2.3)
ssml_buider.ssml
# Output: "<speak><prosody volume=\"+2.3dB\">Text</prosody></speak>"
pause
parameters
- string
- optional, default: "medium"
- can be text time such as: "1s", "100ms", etc.
- valid text inputs: "none", "x-weak", "weak", "medium", "strong", "x-strong"
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.pause("1s")
ssml_buider.ssml
# Output: "<speak><break time=\"1s\"/></speak>"
break
Alias for pause
emphasis
parameters
- string
- emphasis
- optional, default: "moderate"
- valid text inputs: "reduced", "moderate", "strong"
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.emphasis("Text","strong")
ssml_buider.ssml
# Output: "<speak><emphasis level=\"strong\">Text</emphasis></speak>"
audio
parameters
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.audio("http://s3.audio.file.com/audio.mp3")
ssml_buider.ssml
# Output: "<speak><audio src=\"http://s3.audio.file.com/audio.mp3\"/></speak>"
spell_out
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.spell_out("Spelling")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"spell-out\">Spelling</say-as></speak>"
characters
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.characters("Spelling")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"characters\">Spelling</say-as></speak>"
cardinal
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.cardinal("10")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"cardinal\">10</say-as></speak>"
number
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.number("10")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"number\">10</say-as></speak>"
ordinal
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.ordinal("10")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"ordinal\">10</say-as></speak>"
digits
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.digits("10")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"digits\">10</say-as></speak>"
fraction
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.fraction("3/20")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"fraction\">3/20</say-as></speak>"
unit
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.unit("10 meters")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"unit\">10meters</say-as></speak>"
date
parameters
- year
- string or integer
- nil to leave out
- month
- string or integer
- nil to leave out
- day
- string or integer
- nil to leave out
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.date("2017",nil,10)
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"date\">2017??10</say-as></speak>"
time
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.time("2'")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"time\">2'</say-as></speak>"
telephone
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.telephone("1234567890")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"telephone\">1234567890</say-as></speak>"
phone
Alias for telephone
address
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.address("342 W 1st St")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"address\">342 W 1st St</say-as></speak>"
interjection
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.interjection("Wow!")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"interjection\">Wow!</say-as></speak>"
expletive
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.expletive("Curse Word")
ssml_buider.ssml
# Output: "<speak><say-as interpret-as=\"expletive\">Curse Word</say-as></speak>"
sub
parameters
- string
- alias
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.sub("Al","aluminum")
ssml_buider.ssml
# Output: "<speak><sub alias=\"aluminum\">Al</sub></speak>"
whisper
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.whisper("Be very quiet")
ssml_buider.ssml
# Output: "<speak><amazon:effect name=\"whispered\">Be very quiet</amazon:effect></speak>"
amazon_verb
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.amazon_verb("read")
ssml_buider.ssml
# Output: "<speak><w role=\"amazon:VB\">read</w></speak>"
amazon_participle
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.amazon_participle("read")
ssml_buider.ssml
# Output: "<speak><w role=\"amazon:VBD\">read</w></speak>"
amazon_noun
parameters
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.amazon_noun("bath")
ssml_buider.ssml
# Output: "<speak><w role=\"amazon:NN\">bath</w></speak>"
amazon_sense
parameters
- string
- sense
- integer
- Sense Documentation
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.amazon_sense("bass",1)
ssml_buider.ssml
# Output: "<speak><w role=\"SENSE_1\">bass</w></speak>"
phoneme
parameters
- string
- alphabet
- string
- ph
- string
require 'ssml_builder'
ssml_builder = SsmlBuilder::Builder.new
ssml_builder.phoneme("pecan","ipa","pɪˈkɑːn")
ssml_buider.ssml
# Output: "<speak><phoneme alphabet=\"ipa\" ph=\"pɪˈkɑːn\">pecan</phoneme></speak>"
String
Troubleshooting
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature) - Commit your changes (
git commit -am 'Add some feature') - Push to the branch (
git push origin my-new-feature) - Create a new Pull Request
Please make sure to write specs for any new features!
Team Members
- "Paul McMahon"
- Email: [email protected]
- Twitter: @colpanius