module Adhearsion::CallController::Output

Constants

NoDocError
PlaybackError

Public Instance Methods

async_player() click to toggle source

@private

# File lib/adhearsion/call_controller/output.rb, line 337
def async_player
  AsyncPlayer.new(self)
end
interruptible_play(*outputs, options) click to toggle source

Plays the given output, allowing for DTMF input of a single digit from the user At the end of the played file it returns nil

@example Ask the user for a number, then play it back

ssml = RubySpeech::SSML.draw do
  "Please press a button"
end
input = interruptible_play ssml
play input unless input.nil?

@param [String, Numeric, Date, Time, RubySpeech::SSML::Speak, Array, Hash] outputs The argument to play to the user, or an array of arguments. @param [Hash] options Additional options.

@return [String, nil] The single DTMF character entered by the user, or nil if nothing was entered @raise [PlaybackError] if (one of) the given argument(s) could not be played

# File lib/adhearsion/call_controller/output.rb, line 294
def interruptible_play(*outputs, options)
  options = process_output_options outputs, options
  outputs.find do |output|
    digit = stream_file output, '0123456789#*', options
    return digit if digit
  end
end
output_formatter() click to toggle source

@return [Formatter] an output formatter for the preparation of SSML documents for submission to the engine

# File lib/adhearsion/call_controller/output.rb, line 354
def output_formatter
  Formatter.new
end
play(*outputs, options) click to toggle source

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.

@param [Array<String, Fixnum, Time, Date>, String, Fixnum, Time, Date] outputs A collection of outputs to render. @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@example Play file hello-world

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

@example Speak current time

play Time.now

@example Speak today's date

play Date.today

@example Speak today's date in a specific format

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

@example 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"

@example Play two sound files

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

@raise [PlaybackError] if (one of) the given argument(s) could not be played

# File lib/adhearsion/call_controller/output.rb, line 100
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) click to toggle source

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.

@param [Array<String, Fixnum, Time, Date>, String, Fixnum, Time, Date] outputs A collection of outputs to render. @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@example Play file hello-world

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

@example Speak current time

play Time.now

@example Speak today's date

play Date.today

@example Speak today's date in a specific format

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

@example 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"

@example Play two sound files

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

@raise [PlaybackError] if (one of) the given argument(s) could not be played @return [Punchblock::Component::Output]

# File lib/adhearsion/call_controller/output.rb, line 135
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 = {}) click to toggle source

Plays the given audio file. SSML supports http:// paths and full disk paths. The Punchblock backend will have to handle cases like Asterisk where there is a fixed sounds directory.

@param [String] file http:// URL or full disk path to the sound file @param [Hash] options Additional options Includes everything in Punchblock::Component::Output.new. @option options [String] :fallback The text to play if the file is not available

@raise [PlaybackError] if (one of) the given argument(s) could not be played

# 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 = {}) click to toggle source

Plays the given audio file and returns as soon as it begins. SSML supports http:// paths and full disk paths. The Punchblock backend will have to handle cases like Asterisk where there is a fixed sounds directory.

@param [String] file http:// URL or full disk path to the sound file @param [Hash] options Additional options to specify how exactly to say time specified. Includes everything in Punchblock::Component::Output.new. @option options [String] :fallback The text to play if the file is not available

@raise [PlaybackError] if (one of) the given argument(s) could not be played @return [Punchblock::Component::Output]

# File lib/adhearsion/call_controller/output.rb, line 171
def play_audio!(file, options = {})
  async_player.play_ssml(output_formatter.ssml_for_audio(file, options), options)
end
play_document(url, options = {}) click to toggle source

Plays the given SSML document from a URL.

@param [String] url String containing a valid URL, like “example.com/document.ssml”. @param [Hash] options A set of options for output. See Punchblock::Component::Output.new for details.

@raise [ArgumentError] if the given argument can not be played

# File lib/adhearsion/call_controller/output.rb, line 257
def play_document(url, options = {})
  raise ArgumentError unless url =~ URI::regexp
  player.play_url url, options
  true
end
play_document!(url, options = {}) click to toggle source

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

@param [String] url String containing a valid URL, like “example.com/document.ssml”. @param [Hash] options A set of options for output. See Punchblock::Component::Output.new for details.

@raise [ArgumentError] if the given argument can not be played @return [Punchblock::Component::Output]

# File lib/adhearsion/call_controller/output.rb, line 272
def play_document!(url, options = {})
  raise ArgumentError unless url =~ URI::regexp
  async_player.play_url url, options
end
play_numeric(number, options = {}) click to toggle source

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”.

@param [Numeric, String] number Numeric or String containing a valid Numeric, like “321”. @param [Hash] options A set of options for output. See Punchblock::Component::Output.new for details.

@raise [ArgumentError] if the given argument can not be played

# File lib/adhearsion/call_controller/output.rb, line 227
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 = {}) click to toggle source

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”.

@param [Numeric, String] number Numeric or String containing a valid Numeric, like “321”. @param [Hash] options A set of options for output. See Punchblock::Component::Output.new for details.

@raise [ArgumentError] if the given argument can not be played @return [Punchblock::Component::Output]

# File lib/adhearsion/call_controller/output.rb, line 244
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 = {}) click to toggle source

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

@param [Date, Time, DateTime] time Time to be said. @param [Hash] options Additional options to specify how exactly to say time specified. Includes everything in Punchblock::Component::Output.new. @option options [String] :format 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.

@see www.w3.org/TR/ssml-sayas/#S3.1 @option options [String] :strftime This format is what defines the string that is sent to the Speech Synthesis Engine.

It uses Time::strftime symbols.

@raise [ArgumentError] if the given argument can not be played

# File lib/adhearsion/call_controller/output.rb, line 190
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 = {}) click to toggle source

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

@param [Date, Time, DateTime] time Time to be said. @param [Hash] options Additional options to specify how exactly to say time specified. Includes everything in Punchblock::Component::Output.new. @option options [String] :format 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.

@see www.w3.org/TR/ssml-sayas/#S3.1 @option options [String] :strftime This format is what defines the string that is sent to the Speech Synthesis Engine.

It uses Time::strftime symbols.

@raise [ArgumentError] if the given argument can not be played @return [Punchblock::Component::Output]

# File lib/adhearsion/call_controller/output.rb, line 212
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
player() click to toggle source

@private

# File lib/adhearsion/call_controller/output.rb, line 332
def player
  Player.new(self)
end
process_output_options(outputs, options) click to toggle source

@private

# File lib/adhearsion/call_controller/output.rb, line 342
def process_output_options(outputs, options)
  if options.is_a?(Hash) && outputs.count > 0
    options
  else
    outputs << options
    {}
  end
end
say(text, options = {}) click to toggle source

Speak output using text-to-speech (TTS)

@param [String, to_s] text The text to be rendered @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@raise [PlaybackError] if the given argument could not be played

# File lib/adhearsion/call_controller/output.rb, line 25
def say(text, options = {})
  return unless text
  player.play_ssml(text, options) || player.output(output_formatter.ssml_for_text(text.to_s), options)
end
Also aliased as: speak
say!(text, options = {}) click to toggle source

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

@param [String, to_s] text The text to be rendered @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@raise [PlaybackError] if the given argument could not be played

# File lib/adhearsion/call_controller/output.rb, line 39
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
Also aliased as: speak!
say_characters(characters, options = {}) click to toggle source

Speak characters using text-to-speech (TTS)

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

say_characters('abc123')

@param [String, to_s] characters The string of characters to be spoken @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@raise [PlaybackError] if the given argument could not be played

# File lib/adhearsion/call_controller/output.rb, line 56
def say_characters(characters, options = {})
  player.play_ssml output_formatter.ssml_for_characters(characters), options
  true
end
say_characters!(characters, options = {}) click to toggle source

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

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

say_characters!('abc123')

@param [String, to_s] characters The string of characters to be spoken @param [Hash] options A set of options for output. Includes everything in Punchblock::Component::Output.new.

@raise [PlaybackError] if the given argument could not be played

# File lib/adhearsion/call_controller/output.rb, line 71
def say_characters!(characters, options = {})
  async_player.play_ssml output_formatter.ssml_for_characters(characters), options
end
speak(text, options = {})
Alias for: say
speak!(text, options = {})
Alias for: say!
stream_file(argument, digits = '0123456789 click to toggle source

Plays a single output, not only files, accepting interruption by one of the digits specified

@param [Object] argument String or Hash specifying output and options @param [String] digits String with the digits that are allowed to interrupt output

@return [String, nil] The pressed digit, or nil if nothing was pressed @private

# File lib/adhearsion/call_controller/output.rb, line 311
def stream_file(argument, digits = '0123456789#*', output_options = {})
  result = nil
  stopper = Punchblock::Component::Input.new :mode => :dtmf,
    :grammar => {
      :value => grammar_accept(digits)
    }

  player.output output_formatter.ssml_for(argument), output_options do |output_component|
    stopper.register_event_handler Punchblock::Event::Complete do |event|
      output_component.stop! unless output_component.complete?
    end
    write_and_await_response stopper
  end

  stopper.stop! if stopper.executing?
  reason = stopper.complete_event.reason
  result = reason.respond_to?(:utterance) ? reason.utterance : nil
  parse_dtmf result
end