adhearsion 2.4.0 → 2.5.0

data/lib/adhearsion/call_controller/output.rb

@@ -11,6 +11,7 @@ module Adhearsion
       autoload :Player
 
       PlaybackError = Class.new Adhearsion::Error # Represents failure to play audio, such as when the sound file cannot be found
+      NoDocError = Class.new Adhearsion::Error # Represents failure to provide documents to playback
 
       #
       # Speak output using text-to-speech (TTS)
@@ -18,9 +19,10 @@ module Adhearsion
       # @param [String, #to_s] text The text to be rendered
       # @param [Hash] options A set of options for output
       #
-      # @raises [PlaybackError] if the given argument could not be played
+      # @raise [PlaybackError] if the given argument could not be played
       #
       def say(text, options = {})
+        return unless text
         player.play_ssml(text, options) || player.output(output_formatter.ssml_for_text(text.to_s), options)
       end
       alias :speak :say
@@ -31,9 +33,10 @@ module Adhearsion
       # @param [String, #to_s] text The text to be rendered
       # @param [Hash] options A set of options for output
       #
-      # @raises [PlaybackError] if the given argument could not be played
+      # @raise [PlaybackError] if the given argument could not be played
       #
       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
       alias :speak! :say!
@@ -47,7 +50,7 @@ module Adhearsion
       # @param [String, #to_s] characters The string of characters to be spoken
       # @param [Hash] options A set of options for output
       #
-      # @raises [PlaybackError] if the given argument could not be played
+      # @raise [PlaybackError] if the given argument could not be played
       #
       def say_characters(characters, options = {})
         player.play_ssml output_formatter.ssml_for_characters(characters), options
@@ -62,7 +65,7 @@ module Adhearsion
       # @param [String, #to_s] characters The string of characters to be spoken
       # @param [Hash] options A set of options for output
       #
-      # @raises [PlaybackError] if the given argument could not be played
+      # @raise [PlaybackError] if the given argument could not be played
       #
       def say_characters!(characters, options = {})
         async_player.play_ssml output_formatter.ssml_for_characters(characters), options
@@ -88,12 +91,15 @@ module Adhearsion
       # @example Play two sound files
       #   play "/path/to/you-sound-cute.mp3", "/path/to/what-are-you-wearing.wav"
       #
-      # @raises [PlaybackError] if (one of) the given argument(s) could not be played
+      # @raise [PlaybackError] if (one of) the given argument(s) could not be played
       #
-      def play(*arguments)
-        options = process_output_options arguments
-        player.play_ssml output_formatter.ssml_for_collection(arguments), options
+      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
 
       #
@@ -116,12 +122,15 @@ module Adhearsion
       # @example Play two sound files
       #   play "/path/to/you-sound-cute.mp3", "/path/to/what-are-you-wearing.wav"
       #
-      # @raises [PlaybackError] if (one of) the given argument(s) could not be played
-      # @returns [Punchblock::Component::Output]
+      # @raise [PlaybackError] if (one of) the given argument(s) could not be played
+      # @return [Punchblock::Component::Output]
       #
-      def play!(*arguments)
-        options = process_output_options arguments
-        async_player.play_ssml output_formatter.ssml_for_collection(arguments), options
+      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
 
       #
@@ -134,7 +143,7 @@ module Adhearsion
       # @option options [String] :fallback The text to play if the file is not available
       # @option options [Symbol] :renderer The media engine to use for rendering the file
       #
-      # @raises [PlaybackError] if (one of) the given argument(s) could not be played
+      # @raise [PlaybackError] if (one of) the given argument(s) could not be played
       #
       def play_audio(file, options = {})
         renderer = options.delete :renderer
@@ -151,8 +160,8 @@ module Adhearsion
       # @param [Hash] options Additional options to specify how exactly to say time specified.
       # @option options [String] :fallback The text to play if the file is not available
       #
-      # @raises [PlaybackError] if (one of) the given argument(s) could not be played
-      # @returns [Punchblock::Component::Output]
+      # @raise [PlaybackError] if (one of) the given argument(s) could not be played
+      # @return [Punchblock::Component::Output]
       #
       def play_audio!(file, options = {})
         renderer = options.delete :renderer
@@ -172,7 +181,7 @@ module Adhearsion
       # @option options [String] :strftime 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
+      # @raise [ArgumentError] if the given argument can not be played
       #
       def play_time(time, options = {})
         raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
@@ -193,8 +202,8 @@ module Adhearsion
       # @option options [String] :strftime 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
-      # @returns [Punchblock::Component::Output]
+      # @raise [ArgumentError] if the given argument can not be played
+      # @return [Punchblock::Component::Output]
       #
       def play_time!(time, options = {})
         raise ArgumentError unless [Date, Time, DateTime].include?(time.class) && options.is_a?(Hash)
@@ -206,9 +215,9 @@ module Adhearsion
       # 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] Numeric or String containing a valid Numeric, like "321".
+      # @param [Numeric, String] number Numeric or String containing a valid Numeric, like "321".
       #
-      # @raises [ArgumentError] if the given argument can not be played
+      # @raise [ArgumentError] if the given argument can not be played
       #
       def play_numeric(number)
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
@@ -221,10 +230,10 @@ module Adhearsion
       # 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] Numeric or String containing a valid Numeric, like "321".
+      # @param [Numeric, String] number Numeric or String containing a valid Numeric, like "321".
       #
-      # @raises [ArgumentError] if the given argument can not be played
-      # @returns [Punchblock::Component::Output]
+      # @raise [ArgumentError] if the given argument can not be played
+      # @return [Punchblock::Component::Output]
       #
       def play_numeric!(number)
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
@@ -242,14 +251,14 @@ module Adhearsion
       #   input = interruptible_play ssml
       #   play input unless input.nil?
       #
-      # @param [String, Numeric, Date, Time, RubySpeech::SSML::Speak, Array, Hash] The argument to play to the user, or an array of arguments.
-      # @param [Hash] Additional options.
+      # @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
-      # @raises [PlaybackError] if (one of) the given argument(s) could not be played
+      # @raise [PlaybackError] if (one of) the given argument(s) could not be played
       #
-      def interruptible_play(*outputs)
-        options = process_output_options outputs
+      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
@@ -259,8 +268,8 @@ module Adhearsion
       #
       # Plays a single output, not only files, accepting interruption by one of the digits specified
       #
-      # @param [Object] String or Hash specifying output and options
-      # @param [String] String with the digits that are allowed to interrupt output
+      # @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
@@ -296,8 +305,13 @@ module Adhearsion
       end
 
       # @private
-      def process_output_options(arguments)
-        arguments.last.is_a?(Hash) && arguments.count > 1 ? arguments.pop : {}
+      def process_output_options(outputs, options)
+        if options.is_a?(Hash) && outputs.count > 0
+          options
+        else
+          outputs << options
+          {}
+        end
       end
 
       #

data/lib/adhearsion/call_controller/output/async_player.rb

@@ -6,14 +6,15 @@ module Adhearsion
       class AsyncPlayer < AbstractPlayer
 
         #
-        # @yields The output component before executing it
-        # @raises [PlaybackError] if (one of) the given argument(s) could not be played
+        # @yield The output component before executing it
+        # @raise [PlaybackError] if (one of) the given argument(s) could not be played
         #
         def output(content, options = {})
           options.merge! :ssml => content
           component = new_output options
           component.register_event_handler Punchblock::Event::Complete do |event|
             controller.logger.error event if event.reason.is_a?(Punchblock::Event::Complete::Error)
+            throw :pass
           end
           controller.write_and_await_response component
           component

data/lib/adhearsion/call_controller/output/formatter.rb

@@ -8,6 +8,9 @@ module Adhearsion
       class Formatter
 
         def ssml_for_collection(collection)
+          collection = collection.compact
+          raise NoDocError if collection.empty?
+
           collection.inject RubySpeech::SSML.draw do |doc, argument|
             doc + case argument
             when Hash
@@ -28,6 +31,8 @@ module Adhearsion
             :time
           when Numeric, /^\d+$/
             :numeric
+          when /^[\d\*\#]+$/
+            :characters
           when /^\//, ->(string) { uri? string }
             :audio
           else
@@ -45,7 +50,7 @@ module Adhearsion
         # Generates SSML for the argument and options passed, using automatic detection
         # Directly returns the argument if it is already an SSML document
         #
-        # @param [String, Hash, RubySpeech::SSML::Speak] the argument with options as accepted by the play_ methods, or an SSML document
+        # @param [String, Hash, RubySpeech::SSML::Speak] args the argument with options as accepted by the play_ methods, or an SSML document
         # @return [RubySpeech::SSML::Speak] an SSML document
         #
         def ssml_for(*args)
@@ -89,7 +94,7 @@ module Adhearsion
           end
         end
 
-        def ssml_for_characters(argument)
+        def ssml_for_characters(argument, options = {})
           RubySpeech::SSML.draw do
             say_as(interpret_as: 'characters') { string argument.to_s }
           end

data/lib/adhearsion/call_controller/output/player.rb

@@ -6,8 +6,8 @@ module Adhearsion
       class Player < AbstractPlayer
 
         #
-        # @yields The output component before executing it
-        # @raises [PlaybackError] if (one of) the given argument(s) could not be played
+        # @yield The output component before executing it
+        # @raise [PlaybackError] if (one of) the given argument(s) could not be played
         #
         def output(content, options = {}, &block)
           options.merge! :ssml => content

data/lib/adhearsion/call_controller/record.rb

@@ -8,20 +8,21 @@ module Adhearsion
       #
       # Handle a recording
       #
-      # @param [Adhearsion::CallController] controller on which to execute the recording
-      # @param [Hash] options
-      # @option options [Boolean, Optional] :async Execute asynchronously. Defaults to false
-      # @option options [Boolean, Optional] :start_beep Indicates whether subsequent record will be preceded with a beep. Default is true.
-      # @option options [Boolean, Optional] :start_paused Whether subsequent record will start in PAUSE mode. Default is false.
-      # @option options [String, Optional] :max_duration Indicates the maximum duration (seconds) for a recording.
-      # @option options [String, Optional] :format File format used during recording.
-      # @option options [String, Optional] :initial_timeout Controls how long (seconds) the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event.
-      # @option options [String, Optional] :final_timeout Controls the length (seconds) of a period of silence after callers have spoken to conclude they finished.
-      # @option options [Boolean, Optional] :interruptible Allows the recording to be terminated by any single DTMF key, default is false
-      #
       class Recorder
         attr_accessor :record_component, :stopper_component
 
+        #
+        # @param [Adhearsion::CallController] controller on which to execute the recording
+        # @param [Hash] options
+        # @option options [Boolean, Optional] :async Execute asynchronously. Defaults to false
+        # @option options [Boolean, Optional] :start_beep Indicates whether subsequent record will be preceded with a beep. Default is true.
+        # @option options [Boolean, Optional] :start_paused Whether subsequent record will start in PAUSE mode. Default is false.
+        # @option options [String, Optional] :max_duration Indicates the maximum duration (seconds) for a recording.
+        # @option options [String, Optional] :format File format used during recording.
+        # @option options [String, Optional] :initial_timeout Controls how long (seconds) the recognizer should wait after the end of the prompt for the caller to speak before sending a Recorder event.
+        # @option options [String, Optional] :final_timeout Controls the length (seconds) of a period of silence after callers have spoken to conclude they finished.
+        # @option options [Boolean, Optional] :interruptible Allows the recording to be terminated by any single DTMF key, default is false
+        #
         def initialize(controller, options = {})
           @controller = controller
 
@@ -98,7 +99,7 @@ module Adhearsion
       # Start a recording
       #
       # @example Record in a blocking way and use result
-      #   record_result = record :start_beep => true, :max_duration => 60_000
+      #   record_result = record :start_beep => true, :max_duration => 60
       #   logger.info "Recording saved to #{record_result.complete_event.recording.uri}"
       # @example Asynchronous recording, execution of the controller will continue
       #   record :async => true do |event|
@@ -106,7 +107,6 @@ module Adhearsion
       #   end
       #
       # @param [Hash] options
-      # @param [Block] block to process result of the record method, it will receive the complete Event for the method.
       # @option options [Boolean, Optional] :async Execute asynchronously. Defaults to false
       # @option options [Boolean, Optional] :start_beep Indicates whether subsequent record will be preceded with a beep. Default is true.
       # @option options [Boolean, Optional] :start_paused Whether subsequent record will start in PAUSE mode. Default is false.
@@ -116,6 +116,9 @@ module Adhearsion
       # @option options [String, Optional] :final_timeout Controls the length (seconds) of a period of silence after callers have spoken to conclude they finished.
       # @option options [Boolean, String, Optional] :interruptible Allows the recording to be terminated by any single DTMF key, default is false
       #
+      # @yield [event] Handle the recording completion event asyncronously.
+      # @yieldparam [Punchblock::Event::Complete] event the complete event for the recording
+      #
       # @return Punchblock::Component::Record
       #
       def record(options = {})

data/lib/adhearsion/call_controller/utility.rb

@@ -8,7 +8,7 @@ module Adhearsion
 
       # Utility method for DTMF GRXML grammars
       #
-      # @param [Integer] Number of digits to accept in the grammar.
+      # @param [Integer] digits Number of digits to accept in the grammar.
       # @return [RubySpeech::GRXML::Grammar] A grammar suitable for use in SSML prompts
       #
       # @private
@@ -27,7 +27,7 @@ module Adhearsion
 
       # Utility method to create a single-digit grammar to accept only some digits
       #
-      # @param [String] String representing the digits to accept
+      # @param [String] digits String representing the digits to accept
       # @return [RubySpeech::GRXML::Grammar] A grammar suitable for use in SSML prompts
       #
       # @private
@@ -48,7 +48,7 @@ module Adhearsion
       #
       # Parses a DTMF tone string
       #
-      # @param [String] the tone string to be parsed
+      # @param [String] dtmf the tone string to be parsed
       # @return [String] the digits/*/# without any separation
       #
       # @private

data/lib/adhearsion/calls.rb

@@ -8,26 +8,25 @@ module Adhearsion
 
     trap_exit :call_died
 
-    def from_offer(offer)
-      Call.new(offer).tap do |call|
-        self << call
-      end
-    end
-
     def <<(call)
       link call
       self[call.id] = call
+      by_uri[call.uri] = call
       current_actor
     end
 
     def remove_inactive_call(call)
-      if call_is_dead?(call) != nil
+      if call_is_dead?(call)
         call_id = key call
         delete call_id if call_id
+
+        remove_call_uri call
       elsif call.respond_to?(:id)
         delete call.id
+        remove_call_uri call
       else
-        delete call
+        call_actor = delete call
+        remove_call_uri call_actor
       end
     end
 
@@ -37,11 +36,25 @@ module Adhearsion
       end
     end
 
+    def with_uri(uri)
+      by_uri[uri]
+    end
+
     private
 
+    def by_uri
+      @by_uri ||= {}
+    end
+
+    def remove_call_uri(call)
+      uri = by_uri.key call
+      by_uri.delete uri if uri
+    end
+
     def call_is_dead?(call)
       !call.alive?
     rescue NoMethodError
+      false
     end
 
     def call_died(call, reason)

data/lib/adhearsion/cli_commands/ahn_command.rb

@@ -16,6 +16,7 @@ module Adhearsion
       end
 
       desc "create /path/to/directory", "Create a new Adhearsion application under the given path"
+      method_option :empty, type: :boolean
       def create(path)
         require 'adhearsion/generators/app/app_generator'
         Generators::AppGenerator.start

data/lib/adhearsion/configuration.rb

@@ -55,8 +55,8 @@ module Adhearsion
           __
         }
 
-        after_hangup_lifetime 30, :transform => Proc.new { |v| v.to_i }, :desc => <<-__
-          Lifetime of a call after it has hung up
+        after_hangup_lifetime 1, :transform => Proc.new { |v| v.to_i }, :desc => <<-__
+          Lifetime of a call after it has hung up. Should be set to the minimum functional value for your application. Call actors (threads) living after hangup consume more system resources and reduce the concurrent call capacity of your application.
         __
 
         desc "Media configuration"

data/lib/adhearsion/console.rb

@@ -1,6 +1,7 @@
 # encoding: utf-8
 
 require 'pry'
+require 'readline'
 
 module Adhearsion
   class Console
@@ -30,9 +31,9 @@ module Adhearsion
     # Start the Adhearsion console
     #
     def run
-      set_prompt
-      Pry.config.command_prefix = "%"
       if jruby? || cruby_with_readline?
+        set_prompt
+        Pry.config.command_prefix = "%"
         logger.info "Launching Adhearsion Console"
         @pry_thread = Thread.current
         pry