ibm_watson 0.9.2 → 0.10.0

data/lib/ibm_watson/text_to_speech_v1.rb

@@ -104,7 +104,9 @@ module IBMWatson
     def list_voices
       headers = {
       }
+
       method_url = "/v1/voices"
+
       response = request(
         method: "GET",
         url: method_url,
@@ -131,14 +133,17 @@ module IBMWatson
     #   information about the specified voice with no customization.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_voice(voice:, customization_id: nil)
-      raise ArgumentError("voice must be provided") if voice.nil?
+      raise ArgumentError.new("voice must be provided") if voice.nil?
 
       headers = {
       }
+
       params = {
         "customization_id" => customization_id
       }
+
       method_url = "/v1/voices/%s" % [ERB::Util.url_encode(voice)]
+
       response = request(
         method: "GET",
         url: method_url,
@@ -155,28 +160,99 @@ module IBMWatson
     ##
     # @!method synthesize(text:, accept: nil, voice: nil, customization_id: nil)
     # Synthesize audio.
-    # Synthesizes text to spoken audio, returning the synthesized audio stream as an
-    #   array of bytes. You can pass a maximum of 5 KB of text.  Use the `Accept` header
-    #   or the `accept` query parameter to specify the requested format (MIME type) of the
-    #   response audio. By default, the service uses `audio/ogg;codecs=opus`.
+    # Synthesizes text to audio that is spoken in the specified voice. The service bases
+    #   its understanding of the language for the input text on the specified voice. Use a
+    #   voice that matches the language of the input text.
     #
-    #   If a request includes invalid query parameters, the service returns a `Warnings`
-    #   response header that provides messages about the invalid parameters. The warning
-    #   includes a descriptive message and a list of invalid argument strings. For
-    #   example, a message such as `\"Unknown arguments:\"` or `\"Unknown url query
-    #   arguments:\"` followed by a list of the form `\"invalid_arg_1, invalid_arg_2.\"`
-    #   The request succeeds despite the warnings.
+    #   The service returns the synthesized audio stream as an array of bytes. You can
+    #   pass a maximum of 5 KB of text to the service.
     #
     #   **See also:** [Synthesizing text to
     #   audio](https://console.bluemix.net/docs/services/text-to-speech/http.html#synthesize).
-    # @param text [String] The text to synthesize.
-    # @param accept [String] The requested audio format (MIME type) of the audio. You can use the `Accept`
-    #   header or the `accept` query parameter to specify the audio format. (For the
-    #   `audio/l16` format, you can optionally specify `endianness=big-endian` or
-    #   `endianness=little-endian`; the default is little endian.) For detailed
-    #   information about the supported audio formats and sampling rates, see [Specifying
-    #   an audio
+    #
+    #   ### Audio formats (accept types)
+    #
+    #    The service can return audio in the following formats (MIME types).
+    #   * Where indicated, you can optionally specify the sampling rate (`rate`) of the
+    #   audio. You must specify a sampling rate for the `audio/l16` and `audio/mulaw`
+    #   formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz.
+    #   * For the `audio/l16` format, you can optionally specify the endianness
+    #   (`endianness`) of the audio: `endianness=big-endian` or
+    #   `endianness=little-endian`.
+    #
+    #   Use the `Accept` header or the `accept` parameter to specify the requested format
+    #   of the response audio. If you omit an audio format altogether, the service returns
+    #   the audio in Ogg format with the Opus codec (`audio/ogg;codecs=opus`). The service
+    #   always returns single-channel audio.
+    #   * `audio/basic`
+    #
+    #     The service returns audio with a sampling rate of 8000 Hz.
+    #   * `audio/flac`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/l16`
+    #
+    #     You must specify the `rate` of the audio. You can optionally specify the
+    #   `endianness` of the audio. The default endianness is `little-endian`.
+    #   * `audio/mp3`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/mpeg`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/mulaw`
+    #
+    #     You must specify the `rate` of the audio.
+    #   * `audio/ogg`
+    #
+    #     The service returns the audio in the `vorbis` codec. You can optionally specify
+    #   the `rate` of the audio. The default sampling rate is 22,050 Hz.
+    #   * `audio/ogg;codecs=opus`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/ogg;codecs=vorbis`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/wav`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #   * `audio/webm`
+    #
+    #     The service returns the audio in the `opus` codec. The service returns audio
+    #   with a sampling rate of 48,000 Hz.
+    #   * `audio/webm;codecs=opus`
+    #
+    #     The service returns audio with a sampling rate of 48,000 Hz.
+    #   * `audio/webm;codecs=vorbis`
+    #
+    #     You can optionally specify the `rate` of the audio. The default sampling rate is
+    #   22,050 Hz.
+    #
+    #   For more information about specifying an audio format, including additional
+    #   details about some of the formats, see [Specifying an audio
     #   format](https://console.bluemix.net/docs/services/text-to-speech/http.html#format).
+    #
+    #   ### Warning messages
+    #
+    #    If a request includes invalid query parameters, the service returns a `Warnings`
+    #   response header that provides messages about the invalid parameters. The warning
+    #   includes a descriptive message and a list of invalid argument strings. For
+    #   example, a message such as `\"Unknown arguments:\"` or `\"Unknown url query
+    #   arguments:\"` followed by a list of the form `\"{invalid_arg_1},
+    #   {invalid_arg_2}.\"` The request succeeds despite the warnings.
+    # @param text [String] The text to synthesize.
+    # @param accept [String] The requested format (MIME type) of the audio. You can use the `Accept` header or
+    #   the `accept` parameter to specify the audio format. For more information about
+    #   specifying an audio format, see **Audio formats (accept types)** in the method
+    #   description.
+    #
+    #   Default: `audio/ogg;codecs=opus`.
     # @param voice [String] The voice to use for synthesis.
     # @param customization_id [String] The customization ID (GUID) of a custom voice model to use for the synthesis. If a
     #   custom voice model is specified, it is guaranteed to work only if it matches the
@@ -185,19 +261,23 @@ module IBMWatson
     #   Omit the parameter to use the specified voice with no customization.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def synthesize(text:, accept: nil, voice: nil, customization_id: nil)
-      raise ArgumentError("text must be provided") if text.nil?
+      raise ArgumentError.new("text must be provided") if text.nil?
 
       headers = {
         "Accept" => accept
       }
+
       params = {
         "voice" => voice,
         "customization_id" => customization_id
       }
+
       data = {
         "text" => text
       }
+
       method_url = "/v1/synthesize"
+
       response = request(
         method: "POST",
         url: method_url,
@@ -239,17 +319,20 @@ module IBMWatson
     #   the specified voice with no customization.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_pronunciation(text:, voice: nil, format: nil, customization_id: nil)
-      raise ArgumentError("text must be provided") if text.nil?
+      raise ArgumentError.new("text must be provided") if text.nil?
 
       headers = {
       }
+
       params = {
         "text" => text,
         "voice" => voice,
         "format" => format,
         "customization_id" => customization_id
       }
+
       method_url = "/v1/pronunciation"
+
       response = request(
         method: "GET",
         url: method_url,
@@ -282,16 +365,19 @@ module IBMWatson
     #   recommended.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def create_voice_model(name:, language: nil, description: nil)
-      raise ArgumentError("name must be provided") if name.nil?
+      raise ArgumentError.new("name must be provided") if name.nil?
 
       headers = {
       }
+
       data = {
         "name" => name,
         "language" => language,
         "description" => description
       }
+
       method_url = "/v1/customizations"
+
       response = request(
         method: "POST",
         url: method_url,
@@ -323,10 +409,13 @@ module IBMWatson
     def list_voice_models(language: nil)
       headers = {
       }
+
       params = {
         "language" => language
       }
+
       method_url = "/v1/customizations"
+
       response = request(
         method: "GET",
         url: method_url,
@@ -368,8 +457,7 @@ module IBMWatson
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-models.html#cuModelsUpdate)
     #   * [Adding words to a Japanese custom
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-entries.html#cuJapaneseAdd)
-    #   * [Understanding
-    #   customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
+    #   * [Understanding customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with service credentials created for the instance of the service that owns the
     #   custom model.
@@ -380,16 +468,19 @@ module IBMWatson
     #   additions or updates.
     # @return [nil]
     def update_voice_model(customization_id:, name: nil, description: nil, words: nil)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
       headers = {
       }
+
       data = {
         "name" => name,
         "description" => description,
         "words" => words
       }
+
       method_url = "/v1/customizations/%s" % [ERB::Util.url_encode(customization_id)]
+
       request(
         method: "POST",
         url: method_url,
@@ -417,11 +508,13 @@ module IBMWatson
     #   custom model.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_voice_model(customization_id:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
       headers = {
       }
+
       method_url = "/v1/customizations/%s" % [ERB::Util.url_encode(customization_id)]
+
       response = request(
         method: "GET",
         url: method_url,
@@ -446,11 +539,13 @@ module IBMWatson
     #   custom model.
     # @return [nil]
     def delete_voice_model(customization_id:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
       headers = {
       }
+
       method_url = "/v1/customizations/%s" % [ERB::Util.url_encode(customization_id)]
+
       request(
         method: "DELETE",
         url: method_url,
@@ -493,8 +588,7 @@ module IBMWatson
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-entries.html#cuWordsAdd)
     #   * [Adding words to a Japanese custom
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-entries.html#cuJapaneseAdd)
-    #   * [Understanding
-    #   customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
+    #   * [Understanding customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with service credentials created for the instance of the service that owns the
     #   custom model.
@@ -508,16 +602,19 @@ module IBMWatson
     #   array is empty if the custom model contains no words.
     # @return [nil]
     def add_words(customization_id:, words:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
-      raise ArgumentError("words must be provided") if words.nil?
+      raise ArgumentError.new("words must be provided") if words.nil?
 
       headers = {
       }
+
       data = {
         "words" => words
       }
+
       method_url = "/v1/customizations/%s/words" % [ERB::Util.url_encode(customization_id)]
+
       request(
         method: "POST",
         url: method_url,
@@ -545,11 +642,13 @@ module IBMWatson
     #   custom model.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def list_words(customization_id:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
       headers = {
       }
+
       method_url = "/v1/customizations/%s/words" % [ERB::Util.url_encode(customization_id)]
+
       response = request(
         method: "GET",
         url: method_url,
@@ -589,8 +688,7 @@ module IBMWatson
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-entries.html#cuWordAdd)
     #   * [Adding words to a Japanese custom
     #   model](https://console.bluemix.net/docs/services/text-to-speech/custom-entries.html#cuJapaneseAdd)
-    #   * [Understanding
-    #   customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
+    #   * [Understanding customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html).
     # @param customization_id [String] The customization ID (GUID) of the custom voice model. You must make the request
     #   with service credentials created for the instance of the service that owns the
     #   custom model.
@@ -607,19 +705,22 @@ module IBMWatson
     #   entries](https://console.bluemix.net/docs/services/text-to-speech/custom-rules.html#jaNotes).
     # @return [nil]
     def add_word(customization_id:, word:, translation:, part_of_speech: nil)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
-      raise ArgumentError("word must be provided") if word.nil?
+      raise ArgumentError.new("word must be provided") if word.nil?
 
-      raise ArgumentError("translation must be provided") if translation.nil?
+      raise ArgumentError.new("translation must be provided") if translation.nil?
 
       headers = {
       }
+
       data = {
         "translation" => translation,
         "part_of_speech" => part_of_speech
       }
+
       method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word)]
+
       request(
         method: "PUT",
         url: method_url,
@@ -647,13 +748,15 @@ module IBMWatson
     # @param word [String] The word that is to be queried from the custom voice model.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def get_word(customization_id:, word:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
-      raise ArgumentError("word must be provided") if word.nil?
+      raise ArgumentError.new("word must be provided") if word.nil?
 
       headers = {
       }
+
       method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word)]
+
       response = request(
         method: "GET",
         url: method_url,
@@ -680,13 +783,15 @@ module IBMWatson
     # @param word [String] The word that is to be deleted from the custom voice model.
     # @return [nil]
     def delete_word(customization_id:, word:)
-      raise ArgumentError("customization_id must be provided") if customization_id.nil?
+      raise ArgumentError.new("customization_id must be provided") if customization_id.nil?
 
-      raise ArgumentError("word must be provided") if word.nil?
+      raise ArgumentError.new("word must be provided") if word.nil?
 
       headers = {
       }
+
       method_url = "/v1/customizations/%s/words/%s" % [ERB::Util.url_encode(customization_id), ERB::Util.url_encode(word)]
+
       request(
         method: "DELETE",
         url: method_url,
@@ -716,14 +821,17 @@ module IBMWatson
     # @param customer_id [String] The customer ID for which all data is to be deleted.
     # @return [nil]
     def delete_user_data(customer_id:)
-      raise ArgumentError("customer_id must be provided") if customer_id.nil?
+      raise ArgumentError.new("customer_id must be provided") if customer_id.nil?
 
       headers = {
       }
+
       params = {
         "customer_id" => customer_id
       }
+
       method_url = "/v1/user_data"
+
       request(
         method: "DELETE",
         url: method_url,

data/lib/ibm_watson/tone_analyzer_v3.rb

@@ -22,9 +22,9 @@
 # to respond to each customer appropriately, or to understand and improve their customer
 # conversations.
 #
-# **Note:** Request logging is disabled for the Tone Analyzer service. The service neither
-# logs nor retains data from requests and responses, regardless of whether the
-# `X-Watson-Learning-Opt-Out` request header is set.
+# **Note:** Request logging is disabled for the Tone Analyzer service. Regardless of
+# whether you set the `X-Watson-Learning-Opt-Out` request header, the service does not log
+# or retain data from requests and responses.
 
 require "concurrent"
 require "erb"
@@ -97,7 +97,7 @@ module IBMWatson
     #########################
 
     ##
-    # @!method tone(tone_input:, content_type:, sentences: nil, tones: nil, content_language: nil, accept_language: nil)
+    # @!method tone(tone_input:, content_type: nil, sentences: nil, tones: nil, content_language: nil, accept_language: nil)
     # Analyze general tone.
     # Use the general purpose endpoint to analyze the tone of your input content. The
     #   service analyzes the content for emotional and language tones. The method always
@@ -145,27 +145,29 @@ module IBMWatson
     #   as `en`. You can use different languages for **Content-Language** and
     #   **Accept-Language**.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
-    def tone(tone_input:, content_type:, sentences: nil, tones: nil, content_language: nil, accept_language: nil)
-      raise ArgumentError("tone_input must be provided") if tone_input.nil?
-
-      raise ArgumentError("content_type must be provided") if content_type.nil?
+    def tone(tone_input:, content_type: nil, sentences: nil, tones: nil, content_language: nil, accept_language: nil)
+      raise ArgumentError.new("tone_input must be provided") if tone_input.nil?
 
       headers = {
         "Content-Type" => content_type,
         "Content-Language" => content_language,
         "Accept-Language" => accept_language
       }
+
       params = {
         "version" => @version,
         "sentences" => sentences,
         "tones" => tones.to_a
       }
+
       if content_type.start_with?("application/json") && tone_input.instance_of?(Hash)
         data = tone_input.to_json
       else
         data = tone_input
       end
+
       method_url = "/v3/tone"
+
       response = request(
         method: "POST",
         url: method_url,
@@ -209,19 +211,23 @@ module IBMWatson
     #   **Accept-Language**.
     # @return [DetailedResponse] A `DetailedResponse` object representing the response.
     def tone_chat(utterances:, content_language: nil, accept_language: nil)
-      raise ArgumentError("utterances must be provided") if utterances.nil?
+      raise ArgumentError.new("utterances must be provided") if utterances.nil?
 
       headers = {
         "Content-Language" => content_language,
         "Accept-Language" => accept_language
       }
+
       params = {
         "version" => @version
       }
+
       data = {
         "utterances" => utterances
       }
+
       method_url = "/v3/tone_chat"
+
       response = request(
         method: "POST",
         url: method_url,