Added Java bits to basics

Author: IEvangelist

articles/cognitive-services/Speech-Service/includes/how-to/speech-to-text-basics/speech-to-text-basics-cpp.md

@@ -12,7 +12,11 @@ This article assumes that you have an Azure account and Speech service subscript
 
 ## Install the Speech SDK
 
-Before you can do anything, you'll need to install the Speech SDK. Run `Install-Package Microsoft.CognitiveServices.Speech` in the NuGet console from Visual Studio.
+Before you can do anything, you'll need to install the Speech SDK. Depending on your platform, use the following instructions:
+
+* <a href="../../../quickstarts/setup-platform.md?tabs=linux&pivots=programming-language-cpp" target="_blank">Linux <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+* <a href="../../../quickstarts/setup-platform.md?tabs=macos&pivots=programming-language-cpp" target="_blank">macOS <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+* <a href="../../../quickstarts/setup-platform.md?tabs=windows&pivots=programming-language-cpp" target="_blank">Windows <span class="docon docon-navigate-external x-hidden-focus"></span></a>
 
 ## Create a speech configuration
 
@@ -65,7 +69,7 @@ auto recognizer = SpeechRecognizer::FromConfig(config, audioConfig);
 If you don't want to use a microphone, and want to provide an audio file, you'll still need to provide an `audioConfig`. However, when you create an [`AudioConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/audio-audioconfig), instead of calling `FromDefaultMicrophoneInput`, you'll call `FromWavFileOutput` and pass the `filename` parameter.
 
 ```cpp
-auto audioInput = AudioConfig::FromWavFileInput("whatstheweatherlike.wav");
+auto audioInput = AudioConfig::FromWavFileInput("YourAudioFile.wav");
 auto recognizer = SpeechRecognizer::FromConfig(config, audioInput);
 ```
 
@@ -74,7 +78,7 @@ auto recognizer = SpeechRecognizer::FromConfig(config, audioInput);
 The [Recognizer class](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer) for the Speech SDK for C++ exposes a few methods that you can use for speech recognition.
 
 * Single-shot recognition (async) - Performs recognition in a non-blocking (asynchronous) mode. This will recognize a single utterance. The end of a single utterance is determined by listening for silence at the end or until a maximum of 15 seconds of audio is processed.
-* Continuous recognition (async) - Asynchronously initiates continuous recognition operation. User has to connect to EventSignal to receive recognition results. To stop asynchronous continuous recognition, call [StopContinuousRecognitionAsync](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#stopcontinuousrecognitionasync).
+* Continuous recognition (async) - Asynchronously initiates continuous recognition operation. The user has to connect to handle event to receive recognition results. To stop asynchronous continuous recognition, call [`StopContinuousRecognitionAsync`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#stopcontinuousrecognitionasync).
 
 > [!NOTE]
 > Learn more about how to [choose a speech recognition mode](../../../how-to-choose-recognition-mode.md).
@@ -126,7 +130,7 @@ Continuous recognition is a bit more involved than single-shot recognition. It r
 Let's start by defining the input and initializing a [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer):
 
 ```cpp
-auto audioInput = AudioConfig::FromWavFileInput("whatstheweatherlike.wav");
+auto audioInput = AudioConfig::FromWavFileInput("YourAudioFile.wav");
 auto recognizer = SpeechRecognizer::FromConfig(config, audioInput);
 ```
 
@@ -182,7 +186,7 @@ recognizer->SessionStopped.Connect([&recognitionEnd](const SessionEventArgs& e)
     });
 ```
 
-With everything set up, we can call [StopContinuousRecognitionAsync](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#startcontinuousrecognitionasync).
+With everything set up, we can call [`StopContinuousRecognitionAsync`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#startcontinuousrecognitionasync).
 
 ```cpp
 // Starts continuous recognition. Uses StopContinuousRecognitionAsync() to stop recognition.

articles/cognitive-services/Speech-Service/includes/how-to/speech-to-text-basics/speech-to-text-basics-java.md

@@ -2,7 +2,242 @@
 author: IEvangelist
 ms.service: cognitive-services
 ms.topic: include
-ms.date: 03/02/2020
+ms.date: 03/06/2020
 ms.author: dapine
 ---
 
+## Prerequisites
+
+This article assumes that you have an Azure account and Speech service subscription. If you don't have an account and subscription, [try the Speech service for free](../../../get-started.md).
+
+## Install the Speech SDK
+
+Before you can do anything, you'll need to install the Speech SDK. Depending on your platform, use the following instructions:
+
+* <a href="../../../quickstarts/setup-platform.md?tabs=jre&pivots=programming-language-java" target="_blank">Java Runtime <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+* <a href="../../../quickstarts/setup-platform.md?tabs=android&pivots=programming-language-java" target="_blank">Android <span class="docon docon-navigate-external x-hidden-focus"></span></a>
+
+## Create a speech configuration
+
+To call the Speech service using the Speech SDK, you need to create a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable). This class includes information about your subscription, like your key and associated region, endpoint, host, or authorization token.
+
+> [!NOTE]
+> Regardless of whether you're performing speech recognition, speech synthesis, translation, or intent recognition, you'll always create a configuration.
+
+There are a few ways that you can initialize a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable):
+
+* With a subscription: pass in a key and the associated region.
+* With an endpoint: pass in a Speech service endpoint. A key or authorization token is optional.
+* With a host: pass in a host address. A key or authorization token is optional.
+* With an authorization token: pass in an authorization token and the associated region.
+
+Let's take a look at how a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable) is created using a key and region.
+
+```java
+SpeechConfig config = SpeechConfig.fromSubscription("YourSubscriptionKey", "YourServiceRegion");
+```
+
+## Initialize a recognizer
+
+After you've created a [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable), the next step is to initialize a [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable). When you initialize a [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable), you'll need to pass it your `speech_config`. This ensures that the credentials that the service requires to validate your request are provided.
+
+If you're recognizing speech using your device's default microphone, here's what the [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable) should look like:
+
+```java
+SpeechRecognizer recognizer = new SpeechRecognizer(config);
+```
+
+If you want to specify the audio input device, then you'll need to create an [`AudioConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.audio.audioconfig?view=azure-java-stable) and provide the `audioConfig` parameter when initializing your [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable).
+
+> [!TIP]
+> [Learn how to get the device ID for your audio input device](../../../how-to-select-audio-input-devices.md).
+
+First, add the following `import` statements.
+
+```java
+import java.util.concurrent.Future;
+import com.microsoft.cognitiveservices.speech.*;
+```
+
+Next, you'll be able to reference the `AudioConfig` object as follows:
+
+```java
+AudioConfig audioConfig = AudioConfig.fromDefaultMicrophoneInput();
+SpeechRecognizer recognizer = new SpeechRecognizer(config, audioConfig);
+```
+
+If you don't want to use a microphone, and want to provide an audio file, you'll still need to provide an `audioConfig`. However, when you create an [`AudioConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.audio.audioconfig?view=azure-java-stable), instead of calling `fromDefaultMicrophoneInput`, you'll call `fromWavFileOutput` and pass the `filename` parameter.
+
+```java
+AudioConfig audioConfig = AudioConfig.fromWavFileInput("YourAudioFile.wav");
+SpeechRecognizer recognizer = new SpeechRecognizer(config, audioConfig);
+```
+
+## Recognize speech
+
+The [Recognizer class](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable) for the Speech SDK for Java exposes a few methods that you can use for speech recognition.
+
+* Single-shot recognition (async) - Performs recognition in a non-blocking (asynchronous) mode. This will recognize a single utterance. The end of a single utterance is determined by listening for silence at the end or until a maximum of 15 seconds of audio is processed.
+* Continuous recognition (async) - Asynchronously initiates continuous recognition operation. The user has to handle event to receive recognition results. To stop asynchronous continuous recognition, call [stopContinuousRecognitionAsync](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable#stopcontinuousrecognitionasync).
+
+> [!NOTE]
+> Learn more about how to [choose a speech recognition mode](../../../how-to-choose-recognition-mode.md).
+
+### Single-shot recognition
+
+Here's an example of asynchronous single-shot recognition using [`recognizeOnceAsync`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer.recognizeonceasync?view=azure-java-stable):
+
+```java
+Future<SpeechRecognitionResult> task = recognizer.recognizeOnceAsync();
+SpeechRecognitionResult result = task.get();
+```
+
+You'll need to write some code to handle the result. This sample does a few things with the [`result.getReason()`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.resultreason?view=azure-java-stable):
+
+* Prints the recognition result: `ResultReason.RecognizedSpeech`
+* If there is no recognition match, inform the user: `ResultReason.NoMatch`
+* If an error is encountered, print the error message: `ResultReason.Canceled`
+
+```java
+switch (result.getReason()) {
+    case ResultReason.RecognizedSpeech:
+        System.out.println("We recognized: " + result.getText());
+        exitCode = 0;
+        break;
+    case ResultReason.NoMatch:
+        System.out.println("NOMATCH: Speech could not be recognized.");
+        break;
+    case ResultReason.Canceled: {
+            CancellationDetails cancellation = CancellationDetails.fromResult(result);
+            System.out.println("CANCELED: Reason=" + cancellation.getReason());
+
+            if (cancellation.getReason() == CancellationReason.Error) {
+                System.out.println("CANCELED: ErrorCode=" + cancellation.getErrorCode());
+                System.out.println("CANCELED: ErrorDetails=" + cancellation.getErrorDetails());
+                System.out.println("CANCELED: Did you update the subscription info?");
+            }
+        }
+        break;
+}
+```
+
+### Continuous recognition
+
+Continuous recognition is a bit more involved than single-shot recognition. It requires you to subscribe to the `recognizing`, `recognized`, and `canceled` events to get the recognition results. To stop recognition, you must call [`stopContinuousRecognitionAsync`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable#stopcontinuousrecognitionasync). Here's an example of how continuous recognition is performed on an audio input file.
+
+Let's start by defining the input and initializing a [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable):
+
+```java
+AudioConfig audioConfig = AudioConfig.fromWavFileInput("YourAudioFile.wav");
+SpeechRecognizer recognizer = new SpeechRecognizer(config, audioConfig);
+```
+
+Next, let's create a variable to manage the state of speech recognition. To start, we'll declare a `Semaphore` at the class scope.
+
+```java
+private static Semaphore stopTranslationWithFileSemaphore;
+```
+
+Next, we'll subscribe to the events sent from the [`SpeechRecognizer`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable).
+
+* [`recognizing`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer.recognizing?view=azure-java-stable): Signal for events containing intermediate recognition results.
+* [`recognized`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer.recognized?view=azure-java-stable): Signal for events containing final recognition results (indicating a successful recognition attempt).
+* [`sessionStopped`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.recognizer.sessionstopped?view=azure-java-stable): Signal for events indicating the end of a recognition session (operation).
+* [`canceled`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer.canceled?view=azure-java-stable): Signal for events containing canceled recognition results (indicating a recognition attempt that was canceled as a result or a direct cancellation request or, alternatively, a transport or protocol failure).
+
+```java
+// First initialize the semaphore.
+stopTranslationWithFileSemaphore = new Semaphore(0);
+
+recognizer.recognizing.addEventListener((s, e) -> {
+    System.out.println("RECOGNIZING: Text=" + e.getResult().getText());
+});
+
+recognizer.recognized.addEventListener((s, e) -> {
+    if (e.getResult().getReason() == ResultReason.RecognizedSpeech) {
+        System.out.println("RECOGNIZED: Text=" + e.getResult().getText());
+    }
+    else if (e.getResult().getReason() == ResultReason.NoMatch) {
+        System.out.println("NOMATCH: Speech could not be recognized.");
+    }
+});
+
+recognizer.canceled.addEventListener((s, e) -> {
+    System.out.println("CANCELED: Reason=" + e.getReason());
+
+    if (e.getReason() == CancellationReason.Error) {
+        System.out.println("CANCELED: ErrorCode=" + e.getErrorCode());
+        System.out.println("CANCELED: ErrorDetails=" + e.getErrorDetails());
+        System.out.println("CANCELED: Did you update the subscription info?");
+    }
+
+    stopTranslationWithFileSemaphore.release();
+});
+
+recognizer.sessionStopped.addEventListener((s, e) -> {
+    System.out.println("\n    Session stopped event.");
+    stopTranslationWithFileSemaphore.release();
+});
+```
+
+With everything set up, we can call [`stopContinuousRecognitionAsync`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechrecognizer?view=azure-java-stable#startcontinuousrecognitionasync).
+
+```java
+// Starts continuous recognition. Uses StopContinuousRecognitionAsync() to stop recognition.
+recognizer.startContinuousRecognitionAsync().get();
+
+// Waits for completion.
+stopTranslationWithFileSemaphore.acquire();
+
+// Stops recognition.
+recognizer.stopContinuousRecognitionAsync().get();
+```
+
+### Dictation mode
+
+When using continuous recognition, you can enable dictation processing by using the corresponding "enable dictation" function. This mode will cause the speech config instance to interpret word descriptions of sentence structures such as punctuation. For example, the utterance "Do you live in town question mark" would be interpreted as the text "Do you live in town?".
+
+To enable dictation mode, use the [`enableDictation`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig.enabledictation?view=azure-java-stable) method on your [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable).
+
+```java
+config.enableDictation();
+```
+
+## Change source language
+
+A common task for speech recognition is specifying the input (or source) language. Let's take a look at how you would change the input language to German. In your code, find your [`SpeechConfig`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig?view=azure-java-stable), then add this line directly below it.
+
+```java
+config.setSpeechRecognitionLanguage("fr-FR");
+```
+
+[`setSpeechRecognitionLanguage`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.speechconfig.setspeechrecognitionlanguage?view=azure-java-stable) is a parameter that takes a string as an argument. You can provide any value in the list of supported [locales/languages](../../../language-support.md).
+
+## Improve recognition accuracy
+
+There are a few ways to improve recognition accuracy with the Speech SDK. Let's take a look at Phrase Lists. Phrase Lists are used to identify known phrases in audio data, like a person's name or a specific location. Single words or complete phrases can be added to a Phrase List. During recognition, an entry in a phrase list is used if an exact match for the entire phrase is included in the audio. If an exact match to the phrase is not found, recognition is not assisted.
+
+> [!IMPORTANT]
+> The Phrase List feature is only available in English.
+
+To use a phrase list, first create a [`PhraseListGrammar`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.phraselistgrammar?view=azure-java-stable) object, then add specific words and phrases with [`AddPhrase`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.phraselistgrammar.addphrase?view=azure-java-stable#com_microsoft_cognitiveservices_speech_PhraseListGrammar_addPhrase_String_).
+
+Any changes to [`PhraseListGrammar`](https://docs.microsoft.com/java/api/com.microsoft.cognitiveservices.speech.phraselistgrammar?view=azure-java-stable) take effect on the next recognition or after a reconnection to the Speech service.
+
+```java
+PhraseListGrammar phraseList = PhraseListGrammar.fromRecognizer(recognizer);
+phraseList.addPhrase("Supercalifragilisticexpialidocious");
+```
+
+If you need to clear your phrase list: 
+
+```java
+phraseList.clear();
+```
+
+### Other options to improve recognition accuracy
+
+Phrase lists are only one option to improve recognition accuracy. You can also: 
+
+* [Improve accuracy with Custom Speech](../../../how-to-custom-speech.md)
+* [Improve accuracy with tenant models](../../../tutorial-tenant-model.md)