lib/adhearsion/call_controller/output.rb in adhearsion-2.5.2 vs lib/adhearsion/call_controller/output.rb in adhearsion-2.5.3

@@ -15,11 +15,11 @@
 
       #
       # 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
+      # @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
       #
       def say(text, options = {})
         return unless text
@@ -29,11 +29,11 @@
 
       #
       # 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
+      # @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
       #
       def say!(text, options = {})
         return unless text
@@ -46,11 +46,11 @@
       #
       # @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
+      # @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
       #
       def say_characters(characters, options = {})
         player.play_ssml output_formatter.ssml_for_characters(characters), options
@@ -61,11 +61,11 @@
       #
       # @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
+      # @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
       #
       def say_characters!(characters, options = {})
         async_player.play_ssml output_formatter.ssml_for_characters(characters), options
@@ -75,10 +75,13 @@
       # 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
@@ -106,10 +109,13 @@
       # 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
@@ -137,45 +143,42 @@
       # 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
+      # @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
-      # @option options [Symbol] :renderer The media engine to use for rendering the file
       #
       # @raise [PlaybackError] if (one of) the given argument(s) could not be played
       #
       def play_audio(file, options = {})
-        renderer = options.delete :renderer
-        player.play_ssml(output_formatter.ssml_for_audio(file, options), renderer: renderer)
+        player.play_ssml(output_formatter.ssml_for_audio(file, options), options)
         true
       end
 
       #
       # 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.
+      # @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]
       #
       def play_audio!(file, options = {})
-        renderer = options.delete :renderer
-        async_player.play_ssml(output_formatter.ssml_for_audio(file, options), renderer: renderer)
+        async_player.play_ssml(output_formatter.ssml_for_audio(file, options), options)
       end
 
       #
       # 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.
+      # @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 http://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.
@@ -183,20 +186,20 @@
       #
       # @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)
-        player.play_ssml output_formatter.ssml_for_time(time, options)
+        player.play_ssml output_formatter.ssml_for_time(time, options), options
         true
       end
 
       #
       # 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.
+      # @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 http://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.
@@ -205,41 +208,43 @@
       # @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)
-        async_player.play_ssml output_formatter.ssml_for_time(time, options)
+        async_player.play_ssml output_formatter.ssml_for_time(time, options), options
       end
 
       #
       # 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
       #
-      def play_numeric(number)
+      def play_numeric(number, options = {})
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
-        player.play_ssml output_formatter.ssml_for_numeric(number)
+        player.play_ssml output_formatter.ssml_for_numeric(number), options
         true
       end
 
       #
       # 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]
       #
-      def play_numeric!(number)
+      def play_numeric!(number, options = {})
         raise ArgumentError unless number.kind_of?(Numeric) || number =~ /^\d+$/
-        async_player.play_ssml output_formatter.ssml_for_numeric(number)
+        async_player.play_ssml output_formatter.ssml_for_numeric(number), options
       end
 
       #
       # 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
@@ -294,15 +299,15 @@
         parse_dtmf result
       end
 
       # @private
       def player
-        @player ||= Player.new(self)
+        Player.new(self)
       end
 
       # @private
       def async_player
-        @async_player ||= AsyncPlayer.new(self)
+        AsyncPlayer.new(self)
       end
 
       # @private
       def process_output_options(outputs, options)
         if options.is_a?(Hash) && outputs.count > 0