feat(speech-to-text-v1): supportedFeatures: customAcousticModel property added & update comments

kevinkowa · kevinkowa · commit c11e92849861 · 2022-03-20T22:28:34.000-05:00
diff --git a/Scripts/Services/SpeechToText/V1/Model/AcousticModel.cs b/Scripts/Services/SpeechToText/V1/Model/AcousticModel.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2019, 2021.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -107,7 +107,7 @@ public class StatusValue
         /// <summary>
         /// A list of the available versions of the custom acoustic model. Each element of the array indicates a version
         /// of the base model with which the custom model can be used. Multiple versions exist only if the custom model
-        /// has been upgraded; otherwise, only a single version is shown.
+        /// has been upgraded to a new version of its base model. Otherwise, only a single version is shown.
         /// </summary>
         [JsonProperty("versions", NullValueHandling = NullValueHandling.Ignore)]
         public List<string> Versions { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/Grammar.cs b/Scripts/Services/SpeechToText/V1/Model/Grammar.cs
@@ -1,5 +1,5 @@
 /**
-* Copyright 2018, 2019 IBM Corp. All Rights Reserved.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -68,7 +68,11 @@ public class StatusValue
         [JsonProperty("name", NullValueHandling = NullValueHandling.Ignore)]
         public string Name { get; set; }
         /// <summary>
-        /// The number of OOV words in the grammar. The value is `0` while the grammar is being processed.
+        /// _For custom models that are based on previous-generation models_, the number of OOV words extracted from the
+        /// grammar. The value is `0` while the grammar is being processed.
+        ///
+        /// _For custom models that are based on next-generation models_, no OOV words are extracted from grammars, so
+        /// the value is always `0`.
         /// </summary>
         [JsonProperty("out_of_vocabulary_words", NullValueHandling = NullValueHandling.Ignore)]
         public long? OutOfVocabularyWords { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/LanguageModel.cs b/Scripts/Services/SpeechToText/V1/Model/LanguageModel.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2019, 2021.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -100,14 +100,18 @@ public class StatusValue
         [JsonProperty("updated", NullValueHandling = NullValueHandling.Ignore)]
         public string Updated { get; set; }
         /// <summary>
-        /// The language identifier of the custom language model (for example, `en-US`).
+        /// The language identifier of the custom language model (for example, `en-US`). The value matches the
+        /// five-character language identifier from the name of the base model for the custom model. This value might be
+        /// different from the value of the `dialect` field.
         /// </summary>
         [JsonProperty("language", NullValueHandling = NullValueHandling.Ignore)]
         public string Language { get; set; }
         /// <summary>
-        /// The dialect of the language for the custom language model. For non-Spanish models, the field matches the
-        /// language of the base model; for example, `en-US` for either of the US English language models. For Spanish
-        /// models, the field indicates the dialect for which the model was created:
+        /// The dialect of the language for the custom language model. _For custom models that are based on non-Spanish
+        /// previous-generation models and on next-generation models,_ the field matches the language of the base model;
+        /// for example, `en-US` for one of the US English models. _For custom models that are based on Spanish
+        /// previous-generation models,_ the field indicates the dialect with which the model was created. The value can
+        /// match the name of the base model or, if it was specified by the user, can be one of the following:
         /// * `es-ES` for Castilian Spanish (`es-ES` models)
         /// * `es-LA` for Latin American Spanish (`es-AR`, `es-CL`, `es-CO`, and `es-PE` models)
         /// * `es-US` for Mexican (North American) Spanish (`es-MX` models)
@@ -117,14 +121,9 @@ public class StatusValue
         [JsonProperty("dialect", NullValueHandling = NullValueHandling.Ignore)]
         public string Dialect { get; set; }
         /// <summary>
-        /// _For custom models that are based on previous-generation models_, a list of the available versions of the
-        /// custom language model. Each element of the array indicates a version of the base model with which the custom
-        /// model can be used. Multiple versions exist only if the custom model has been upgraded; otherwise, only a
-        /// single version is shown.
-        ///
-        /// _For custom models that are based on next-generation models_, a single version of the custom model. Only one
-        /// version of a custom model that is based on a next-generation model is ever available, and upgrading does not
-        /// apply.
+        /// A list of the available versions of the custom language model. Each element of the array indicates a version
+        /// of the base model with which the custom model can be used. Multiple versions exist only if the custom model
+        /// has been upgraded to a new version of its base model. Otherwise, only a single version is shown.
         /// </summary>
         [JsonProperty("versions", NullValueHandling = NullValueHandling.Ignore)]
         public List<string> Versions { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/SpeechModel.cs b/Scripts/Services/SpeechToText/V1/Model/SpeechModel.cs
@@ -1,5 +1,5 @@
 /**
-* Copyright 2018, 2019 IBM Corp. All Rights Reserved.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ public class SpeechModel
         [JsonProperty("url", NullValueHandling = NullValueHandling.Ignore)]
         public string Url { get; set; }
         /// <summary>
-        /// Additional service features that are supported with the model.
+        /// Indicates whether select service features are supported with the model.
         /// </summary>
         [JsonProperty("supported_features", NullValueHandling = NullValueHandling.Ignore)]
         public SupportedFeatures SupportedFeatures { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionAlternative.cs b/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionAlternative.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2019, 2021.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -46,7 +46,7 @@ public class SpeechRecognitionAlternative
         /// <summary>
         /// A confidence score for each word of the transcript as a list of lists. Each inner list consists of two
         /// elements: the word and its confidence score in the range of 0.0 to 1.0, for example:
-        /// `[["hello",0.95],["world",0.866]]`. Confidence scores are returned only for the best alternative and only
+        /// `[["hello",0.95],["world",0.86]]`. Confidence scores are returned only for the best alternative and only
         /// with results marked as final.
         /// </summary>
         [JsonProperty("word_confidence", NullValueHandling = NullValueHandling.Ignore)]
diff --git a/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionResult.cs b/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionResult.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2018, 2020.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -68,9 +68,13 @@ public class EndOfUtteranceValue
         [JsonProperty("end_of_utterance", NullValueHandling = NullValueHandling.Ignore)]
         public string EndOfUtterance { get; set; }
         /// <summary>
-        /// An indication of whether the transcription results are final. If `true`, the results for this utterance are
-        /// not updated further; no additional results are sent for a `result_index` once its results are indicated as
-        /// final.
+        /// An indication of whether the transcription results are final:
+        /// * If `true`, the results for this utterance are final. They are guaranteed not to be updated further.
+        /// * If `false`, the results are interim. They can be updated with further interim results until final results
+        /// are eventually sent.
+        ///
+        /// **Note:** Because `final` is a reserved word in Java and Swift, the field is renamed `xFinal` in Java and is
+        /// escaped with back quotes in Swift.
         /// </summary>
         [JsonProperty("final", NullValueHandling = NullValueHandling.Ignore)]
         public bool? Final { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionResults.cs b/Scripts/Services/SpeechToText/V1/Model/SpeechRecognitionResults.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2019, 2021.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -28,15 +28,22 @@ public class SpeechRecognitionResults
         /// <summary>
         /// An array of `SpeechRecognitionResult` objects that can include interim and final results (interim results
         /// are returned only if supported by the method). Final results are guaranteed not to change; interim results
-        /// might be replaced by further interim results and final results. The service periodically sends updates to
-        /// the results list; the `result_index` is set to the lowest index in the array that has changed; it is
-        /// incremented for new results.
+        /// might be replaced by further interim results and eventually final results.
+        ///
+        /// For the HTTP interfaces, all results arrive at the same time. For the WebSocket interface, results can be
+        /// sent as multiple separate responses. The service periodically sends updates to the results list. The
+        /// `result_index` is incremented to the lowest index in the array that has changed for new results.
+        ///
+        /// For more information, see [Understanding speech recognition
+        /// results](https://cloud.ibm.com/docs/speech-to-text?topic=speech-to-text-basic-response).
         /// </summary>
         [JsonProperty("results", NullValueHandling = NullValueHandling.Ignore)]
         public List<SpeechRecognitionResult> Results { get; set; }
         /// <summary>
-        /// An index that indicates a change point in the `results` array. The service increments the index only for
-        /// additional results that it sends for new audio for the same request.
+        /// An index that indicates a change point in the `results` array. The service increments the index for
+        /// additional results that it sends for new audio for the same request. All results with the same index are
+        /// delivered at the same time. The same index can include multiple final results that are delivered with the
+        /// same response.
         /// </summary>
         [JsonProperty("result_index", NullValueHandling = NullValueHandling.Ignore)]
         public long? ResultIndex { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/Model/SupportedFeatures.cs b/Scripts/Services/SpeechToText/V1/Model/SupportedFeatures.cs
@@ -1,5 +1,5 @@
 /**
-* (C) Copyright IBM Corp. 2019, 2021.
+* (C) Copyright IBM Corp. 2022.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
@@ -20,7 +20,7 @@
 namespace IBM.Watson.SpeechToText.V1.Model
 {
     /// <summary>
-    /// Additional service features that are supported with the model.
+    /// Indicates whether select service features are supported with the model.
     /// </summary>
     public class SupportedFeatures
     {
@@ -31,17 +31,23 @@ public class SupportedFeatures
         [JsonProperty("custom_language_model", NullValueHandling = NullValueHandling.Ignore)]
         public bool? CustomLanguageModel { get; set; }
         /// <summary>
+        /// Indicates whether the customization interface can be used to create a custom acoustic model based on the
+        /// language model.
+        /// </summary>
+        [JsonProperty("custom_acoustic_model", NullValueHandling = NullValueHandling.Ignore)]
+        public bool? CustomAcousticModel { get; set; }
+        /// <summary>
         /// Indicates whether the `speaker_labels` parameter can be used with the language model.
         ///
-        /// **Note:** The field returns `true` for all models. However, speaker labels are supported as beta
-        /// functionality only for the following languages and models:
-        /// * For previous-generation models, the parameter can be used for Australian English, US English, German,
+        /// **Note:** The field returns `true` for all models. However, speaker labels are supported for use only with
+        /// the following languages and models:
+        /// * _For previous-generation models,_ the parameter can be used with Australian English, US English, German,
         /// Japanese, Korean, and Spanish (both broadband and narrowband models) and UK English (narrowband model)
         /// transcription only.
-        /// * For next-generation models, the parameter can be used for English (Australian, Indian, UK, and US),
-        /// German, Japanese, Korean, and Spanish transcription only.
+        /// * _For next-generation models,_ the parameter can be used with Czech, English (Australian, Indian, UK, and
+        /// US), German, Japanese, Korean, and Spanish transcription only.
         ///
-        /// Speaker labels are not supported for any other models.
+        /// Speaker labels are not supported for use with any other languages or models.
         /// </summary>
         [JsonProperty("speaker_labels", NullValueHandling = NullValueHandling.Ignore)]
         public bool? SpeakerLabels { get; set; }
diff --git a/Scripts/Services/SpeechToText/V1/SpeechToTextService.cs b/Scripts/Services/SpeechToText/V1/SpeechToTextService.cs
