Module: Adhearsion::CallController::Output

Extended by:
ActiveSupport::Autoload
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

Instance Method Summary (collapse)

Instance Method Details

- (String?) interruptible_play(*outputs)

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

Examples:

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?

Parameters:

  • The (String, Numeric, Date, Time, RubySpeech::SSML::Speak, Array, Hash) —

    argument to play to the user, or an array of arguments.

  • Additional (Hash) —

    options.

Returns:

  • (String, nil) —

    The single DTMF character entered by the user, or nil if nothing was entered



221
222
223
224
225
226
227
 
# File 'lib/adhearsion/call_controller/output.rb', line 221

def interruptible_play(*outputs)
  options = process_output_options outputs 
  outputs.find do |output|
    digit = stream_file output, '0123456789#*', options
    return digit if digit
  end
end

- (Formatter) output_formatter

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



276
277
278
 
# File 'lib/adhearsion/call_controller/output.rb', line 276

def output_formatter
  Formatter.new
end

- (Object) play(*arguments)

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"


63
64
65
66
67
 
# File 'lib/adhearsion/call_controller/output.rb', line 63

def play(*arguments)
  options = process_output_options arguments
  player.play_ssml output_formatter.ssml_for_collection(arguments), options
  true
end

- (Object) play!(*arguments)

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"


92
93
94
95
 
# File 'lib/adhearsion/call_controller/output.rb', line 92

def play!(*arguments)
  options = process_output_options arguments
  async_player.play_ssml output_formatter.ssml_for_collection(arguments), options
end

- (Object) play_audio(file, options = {})

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.

Parameters:

  • file (String) —

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

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

    Additional options

Options Hash (options):

  • :fallback (String) —

    The text to play if the file is not available

  • :renderer (Symbol) —

    The media engine to use for rendering the file



109
110
111
112
113
 
# File 'lib/adhearsion/call_controller/output.rb', line 109

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

- (Object) play_audio!(file, options = {})

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.

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.

Options Hash (options):

  • :fallback (String) —

    The text to play if the file is not available



127
128
129
130
 
# File 'lib/adhearsion/call_controller/output.rb', line 127

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

- (Object) play_numeric(number)

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:

  • Numeric (Numeric, String) —

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

Raises:

  • (ArgumentError) 


183
184
185
186
187
 
# File 'lib/adhearsion/call_controller/output.rb', line 183

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

- (Object) play_numeric!(number)

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:

  • Numeric (Numeric, String) —

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

Raises:

  • (ArgumentError) 


199
200
201
202
 
# File 'lib/adhearsion/call_controller/output.rb', line 199

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

- (Object) play_time(time, options = {})

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.

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)

See Also:



147
148
149
150
151
 
# File 'lib/adhearsion/call_controller/output.rb', line 147

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)
  true
end

- (Object) play_time!(time, options = {})

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.

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)

See Also:



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

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)
end

- (Object) say(text, options = {}) 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



23
24
25
 
# File 'lib/adhearsion/call_controller/output.rb', line 23

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

- (Object) say!(text, options = {}) 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



36
37
38
 
# File 'lib/adhearsion/call_controller/output.rb', line 36

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