Module: Adhearsion::CallController::Output

Included in:
Adhearsion::CallController
Defined in:
lib/adhearsion/call_controller/output.rb,
lib/adhearsion/call_controller/output/player.rb,
lib/adhearsion/call_controller/output/formatter.rb,
lib/adhearsion/call_controller/output/async_player.rb,
lib/adhearsion/call_controller/output/abstract_player.rb

Defined Under Namespace

Classes: AbstractPlayer, AsyncPlayer, Formatter, Player

Constant Summary

PlaybackError =

Represents failure to play audio, such as when the sound file cannot be found

Class.new Adhearsion::Error
NoDocError =

Represents failure to provide documents to playback

Class.new Adhearsion::Error

Instance Method Summary collapse

Instance Method Details

#localeObject



304
305
306
# File 'lib/adhearsion/call_controller/output.rb', line 304

def locale
  call[:locale] || I18n.default_locale
end

#locale=(l) ⇒ Object



308
309
310
# File 'lib/adhearsion/call_controller/output.rb', line 308

def locale=(l)
  call[:locale] = l
end

#output_formatterFormatter

Returns an output formatter for the preparation of SSML documents for submission to the engine

Returns:

  • (Formatter)

    an output formatter for the preparation of SSML documents for submission to the engine



335
336
337
# File 'lib/adhearsion/call_controller/output.rb', line 335

def output_formatter
  Formatter.new
end

#play(*outputs, options) ⇒ Object

Plays the specified sound file names. This method will handle Time/DateTime objects (e.g. Time.now), Fixnums (e.g. 1000), Strings which are valid Fixnums (e.g “123”), and direct sound files. To specify how the Date/Time objects are said pass in as an array with the first parameter as the Date/Time/DateTime object along with a hash with the additional options. See play_time for more information.

Examples:

Play file hello-world

play 'http://www.example.com/hello-world.mp3'
play '/path/on/disk/hello-world.wav'

Speak current time

play Time.now

Speak today's date

play Date.today

Speak today's date in a specific format

play Date.today, :strftime => "%d/%m/%Y", :format => "dmy"

Play sound file, speak number, play two more sound files

play %w"http://www.example.com/a-connect-charge-of.wav 22 /path/to/cents-per-minute.wav /path/to/will-apply.mp3"

Play two sound files

play "/path/to/you-sound-cute.mp3", "/path/to/what-are-you-wearing.wav"

Parameters:

  • outputs (Array<String, Fixnum, Time, Date>, String, Fixnum, Time, Date)

    A collection of outputs to render.

  • options (Hash)

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Raises:

  • (PlaybackError)

    if (one of) the given argument(s) could not be played



101
102
103
104
105
106
107
108
# File 'lib/adhearsion/call_controller/output.rb', line 101

def play(*outputs, options)
  options = process_output_options outputs, options
  ssml = output_formatter.ssml_for_collection(outputs) || return
  player.play_ssml ssml, options
  true
rescue NoDocError
  false
end

#play!(*outputs, options) ⇒ Adhearsion::Rayo::Component::Output

Plays the specified sound file names and returns as soon as it begins. This method will handle Time/DateTime objects (e.g. Time.now), Fixnums (e.g. 1000), Strings which are valid Fixnums (e.g “123”), and direct sound files. To specify how the Date/Time objects are said pass in as an array with the first parameter as the Date/Time/DateTime object along with a hash with the additional options. See play_time for more information.

Examples:

Play file hello-world

play 'http://www.example.com/hello-world.mp3'
play '/path/on/disk/hello-world.wav'

Speak current time

play Time.now

Speak today's date

play Date.today

Speak today's date in a specific format

play Date.today, :strftime => "%d/%m/%Y", :format => "dmy"

Play sound file, speak number, play two more sound files

play %w"http://www.example.com/a-connect-charge-of.wav 22 /path/to/cents-per-minute.wav /path/to/will-apply.mp3"

Play two sound files

play "/path/to/you-sound-cute.mp3", "/path/to/what-are-you-wearing.wav"

Parameters:

  • outputs (Array<String, Fixnum, Time, Date>, String, Fixnum, Time, Date)

    A collection of outputs to render.

  • options (Hash)

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Returns:

Raises:

  • (PlaybackError)

    if (one of) the given argument(s) could not be played



136
137
138
139
140
141
142
# File 'lib/adhearsion/call_controller/output.rb', line 136

def play!(*outputs, options)
  options = process_output_options outputs, options
  ssml = output_formatter.ssml_for_collection(outputs) || return
  async_player.play_ssml ssml, options
rescue NoDocError
  false
end

#play_audio(file, options = {}) ⇒ Object

Plays the given audio file. SSML supports http:// paths and full disk paths.

Parameters:

  • file (String)

    http:// URL or full disk path to the sound file

  • options (Hash) (defaults to: {})

    Additional options Includes everything in Adhearsion::Rayo::Component::Output.new.

Options Hash (options):

  • :fallback (String)

    The text to play if the file is not available

Raises:

  • (PlaybackError)

    if (one of) the given argument(s) could not be played



154
155
156
157
# File 'lib/adhearsion/call_controller/output.rb', line 154

def play_audio(file, options = {})
  player.play_ssml(output_formatter.ssml_for_audio(file, options), options)
  true
end

#play_audio!(file, options = {}) ⇒ Adhearsion::Rayo::Component::Output

Plays the given audio file and returns as soon as it begins. SSML supports http:// paths and full disk paths.

Parameters:

  • file (String)

    http:// URL or full disk path to the sound file

  • options (Hash) (defaults to: {})

    Additional options to specify how exactly to say time specified. Includes everything in Adhearsion::Rayo::Component::Output.new.

Options Hash (options):

  • :fallback (String)

    The text to play if the file is not available

Returns:

Raises:

  • (PlaybackError)

    if (one of) the given argument(s) could not be played



170
171
172
# File 'lib/adhearsion/call_controller/output.rb', line 170

def play_audio!(file, options = {})
  async_player.play_ssml(output_formatter.ssml_for_audio(file, options), options)
end

#play_document(url, options = {}) ⇒ Object

Plays the given SSML document from a URL.

Parameters:

  • url (String)

    String containing a valid URL, like “example.com/document.ssml”.

  • options (Hash) (defaults to: {})

    A set of options for output. See Adhearsion::Rayo::Component::Output.new for details.

Raises:

  • (ArgumentError)

    if the given argument can not be played



256
257
258
259
260
# File 'lib/adhearsion/call_controller/output.rb', line 256

def play_document(url, options = {})
  raise ArgumentError unless url =~ URI::regexp
  player.play_url url, options
  true
end

#play_document!(url, options = {}) ⇒ Adhearsion::Rayo::Component::Output

Plays the given SSML document from a URL and returns as soon as it begins.

Parameters:

  • url (String)

    String containing a valid URL, like “example.com/document.ssml”.

  • options (Hash) (defaults to: {})

    A set of options for output. See Adhearsion::Rayo::Component::Output.new for details.

Returns:

Raises:

  • (ArgumentError)

    if the given argument can not be played



271
272
273
274
# File 'lib/adhearsion/call_controller/output.rb', line 271

def play_document!(url, options = {})
  raise ArgumentError unless url =~ URI::regexp
  async_player.play_url url, options
end

#play_numeric(number, options = {}) ⇒ Object

Plays the given Numeric argument or string representing a decimal number. When playing numbers, Adhearsion assumes you're saying the number, not the digits. For example, play(“100”) is pronounced as “one hundred” instead of “one zero zero”.

Parameters:

  • number (Numeric, String)

    Numeric or String containing a valid Numeric, like “321”.

  • options (Hash) (defaults to: {})

    A set of options for output. See Adhearsion::Rayo::Component::Output.new for details.

Raises:

  • (ArgumentError)

    if the given argument can not be played



226
227
228
229
230
# File 'lib/adhearsion/call_controller/output.rb', line 226

def play_numeric(number, options = {})
  raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
  player.play_ssml output_formatter.ssml_for_numeric(number), options
  true
end

#play_numeric!(number, options = {}) ⇒ Adhearsion::Rayo::Component::Output

Plays the given Numeric argument or string representing a decimal number and returns as soon as it begins. When playing numbers, Adhearsion assumes you're saying the number, not the digits. For example, play(“100”) is pronounced as “one hundred” instead of “one zero zero”.

Parameters:

  • number (Numeric, String)

    Numeric or String containing a valid Numeric, like “321”.

  • options (Hash) (defaults to: {})

    A set of options for output. See Adhearsion::Rayo::Component::Output.new for details.

Returns:

Raises:

  • (ArgumentError)

    if the given argument can not be played



243
244
245
246
# File 'lib/adhearsion/call_controller/output.rb', line 243

def play_numeric!(number, options = {})
  raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
  async_player.play_ssml output_formatter.ssml_for_numeric(number), options
end

#play_time(time, options = {}) ⇒ Object

Plays the given Date, Time, or Integer (seconds since epoch) using the given timezone and format.

Parameters:

  • time (Date, Time, DateTime)

    Time to be said.

  • options (Hash) (defaults to: {})

    Additional options to specify how exactly to say time specified. Includes everything in Adhearsion::Rayo::Component::Output.new.

Options Hash (options):

  • :format (String)

    This format is used only to disambiguate times that could be interpreted in different ways. For example, 01/06/2011 could mean either the 1st of June or the 6th of January. Please refer to the SSML specification.

  • :strftime (String)

    This format is what defines the string that is sent to the Speech Synthesis Engine. It uses Time::strftime symbols.

Raises:

  • (ArgumentError)

    if the given argument can not be played

See Also:



189
190
191
192
193
# File 'lib/adhearsion/call_controller/output.rb', line 189

def play_time(time, options = {})
  raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
  player.play_ssml output_formatter.ssml_for_time(time, options), options
  true
end

#play_time!(time, options = {}) ⇒ Adhearsion::Rayo::Component::Output

Plays the given Date, Time, or Integer (seconds since epoch) using the given timezone and format and returns as soon as it begins.

Parameters:

  • time (Date, Time, DateTime)

    Time to be said.

  • options (Hash) (defaults to: {})

    Additional options to specify how exactly to say time specified. Includes everything in Adhearsion::Rayo::Component::Output.new.

Options Hash (options):

  • :format (String)

    This format is used only to disambiguate times that could be interpreted in different ways. For example, 01/06/2011 could mean either the 1st of June or the 6th of January. Please refer to the SSML specification.

  • :strftime (String)

    This format is what defines the string that is sent to the Speech Synthesis Engine. It uses Time::strftime symbols.

Returns:

Raises:

  • (ArgumentError)

    if the given argument can not be played

See Also:



211
212
213
214
# File 'lib/adhearsion/call_controller/output.rb', line 211

def play_time!(time, options = {})
  raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
  async_player.play_ssml output_formatter.ssml_for_time(time, options), options
end

#say(text, options = {}) ⇒ Object Also known as: speak

Speak output using text-to-speech (TTS)

Parameters:

  • text (String, #to_s)

    The text to be rendered

  • options (Hash) (defaults to: {})

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Raises:



26
27
28
29
# File 'lib/adhearsion/call_controller/output.rb', line 26

def say(text, options = {})
  return unless text
  player.play_ssml(text, options) || player.output(output_formatter.ssml_for_text(text.to_s), options)
end

#say!(text, options = {}) ⇒ Object Also known as: speak!

Speak output using text-to-speech (TTS) and return as soon as it begins

Parameters:

  • text (String, #to_s)

    The text to be rendered

  • options (Hash) (defaults to: {})

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Raises:



40
41
42
43
# File 'lib/adhearsion/call_controller/output.rb', line 40

def say!(text, options = {})
  return unless text
  async_player.play_ssml(text, options) || async_player.output(output_formatter.ssml_for_text(text.to_s), options)
end

#say_characters(characters, options = {}) ⇒ Object

Speak characters using text-to-speech (TTS)

Examples:

Speak 'abc123' as 'ay bee cee one two three'

say_characters('abc123')

Parameters:

  • characters (String, #to_s)

    The string of characters to be spoken

  • options (Hash) (defaults to: {})

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Raises:



57
58
59
60
# File 'lib/adhearsion/call_controller/output.rb', line 57

def say_characters(characters, options = {})
  player.play_ssml output_formatter.ssml_for_characters(characters), options
  true
end

#say_characters!(characters, options = {}) ⇒ Object

Speak characters using text-to-speech (TTS) and return as soon as it begins

Examples:

Speak 'abc123' as 'ay bee cee one two three'

say_characters!('abc123')

Parameters:

  • characters (String, #to_s)

    The string of characters to be spoken

  • options (Hash) (defaults to: {})

    A set of options for output. Includes everything in Adhearsion::Rayo::Component::Output.new.

Raises:



72
73
74
# File 'lib/adhearsion/call_controller/output.rb', line 72

def say_characters!(characters, options = {})
  async_player.play_ssml output_formatter.ssml_for_characters(characters), options
end

#t(key, options = {}) ⇒ Object



276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
# File 'lib/adhearsion/call_controller/output.rb', line 276

def t(key, options = {})
  this_locale = options[:locale] || locale
  options = {default: '', locale: locale}.merge(options)
  prompt = ::I18n.t "#{key}.audio", options
  text   = ::I18n.t "#{key}.text", options

  if prompt.empty? && text.empty?
    # Look for a translation key that doesn't follow the Adhearsion-I18n structure
    text = ::I18n.t key, options
  end

  unless prompt.empty?
    prompt = "file://#{Adhearsion.root + "/" unless Adhearsion.config.core.i18n.audio_path.start_with?("/")}#{Adhearsion.config.core.i18n.audio_path}/#{this_locale}/#{prompt}"
  end

  RubySpeech::SSML.draw language: this_locale do
    if prompt.empty?
      string text
    else
      if Adhearsion.config.core.i18n.fallback
        audio(src: prompt) { string text }
      else
        audio(src: prompt)
      end
    end
  end
end