|
| 1 | +--- |
| 2 | +author: IEvangelist |
| 3 | +ms.service: cognitive-services |
| 4 | +ms.topic: include |
| 5 | +ms.date: 03/06/2020 |
| 6 | +ms.author: dapine |
| 7 | +--- |
| 8 | + |
| 9 | +## Prerequisites |
| 10 | + |
| 11 | +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). |
| 12 | + |
| 13 | +## Install the Speech SDK |
| 14 | + |
| 15 | +Before you can do anything, you'll need to install the Speech SDK. Depending on your platform, use the following instructions: |
| 16 | + |
| 17 | +* <a href="https://docs.microsoft.com/azure/cognitive-services/speech-service/quickstarts/setup-platform?tabs=linux&pivots=programming-language-cpp" target="_blank">Linux <span class="docon docon-navigate-external x-hidden-focus"></span></a> |
| 18 | +* <a href="https://docs.microsoft.com/azure/cognitive-services/speech-service/quickstarts/setup-platform?tabs=macos&pivots=programming-language-cpp" target="_blank">macOS <span class="docon docon-navigate-external x-hidden-focus"></span></a> |
| 19 | +* <a href="https://docs.microsoft.com/azure/cognitive-services/speech-service/quickstarts/setup-platform?tabs=windows&pivots=programming-language-cpp" target="_blank">Windows <span class="docon docon-navigate-external x-hidden-focus"></span></a> |
| 20 | + |
| 21 | +## Create a speech configuration |
| 22 | + |
| 23 | +To call the Speech service using the Speech SDK, you need to create a [`SpeechConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig). This class includes information about your subscription, like your key and associated region, endpoint, host, or authorization token. |
| 24 | + |
| 25 | +> [!NOTE] |
| 26 | +> Regardless of whether you're performing speech recognition, speech synthesis, translation, or intent recognition, you'll always create a configuration. |
| 27 | +
|
| 28 | +There are a few ways that you can initialize a [`SpeechConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig): |
| 29 | + |
| 30 | +* With a subscription: pass in a key and the associated region. |
| 31 | +* With an endpoint: pass in a Speech service endpoint. A key or authorization token is optional. |
| 32 | +* With a host: pass in a host address. A key or authorization token is optional. |
| 33 | +* With an authorization token: pass in an authorization token and the associated region. |
| 34 | + |
| 35 | +Let's take a look at how a [`SpeechConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig) is created using a key and region. |
| 36 | + |
| 37 | +```cpp |
| 38 | +auto config = SpeechConfig::FromSubscription("YourSubscriptionKey", "YourServiceRegion"); |
| 39 | +``` |
| 40 | + |
| 41 | +## Initialize a recognizer |
| 42 | + |
| 43 | +After you've created a [`SpeechConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig), the next step is to initialize a [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer). When you initialize a [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer), you'll need to pass it your `speech_config`. This provides the credentials that the speech service requires to validate your request. |
| 44 | + |
| 45 | +If you're recognizing speech using your device's default microphone, here's what the [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer) should look like: |
| 46 | + |
| 47 | +```cpp |
| 48 | +auto recognizer = SpeechRecognizer::FromConfig(config); |
| 49 | +``` |
| 50 | + |
| 51 | +If you want to specify the audio input device, then you'll need to create an [`AudioConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/audio-audioconfig) and provide the `audioConfig` parameter when initializing your [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer). |
| 52 | + |
| 53 | +> [!TIP] |
| 54 | +> [Learn how to get the device ID for your audio input device](../../../how-to-select-audio-input-devices.md). |
| 55 | +
|
| 56 | +First, add the following `using namespace` statement after your `#include` definitions. |
| 57 | + |
| 58 | +```cpp |
| 59 | +using namespace Microsoft::CognitiveServices::Speech::Audio; |
| 60 | +``` |
| 61 | +
|
| 62 | +Next, you'll be able to reference the `AudioConfig` object as follows: |
| 63 | +
|
| 64 | +```cpp |
| 65 | +auto audioConfig = AudioConfig::FromDefaultMicrophoneInput(); |
| 66 | +auto recognizer = SpeechRecognizer::FromConfig(config, audioConfig); |
| 67 | +``` |
| 68 | + |
| 69 | +If you want to provide an audio file instead of using a microphone, 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. |
| 70 | + |
| 71 | +```cpp |
| 72 | +auto audioInput = AudioConfig::FromWavFileInput("YourAudioFile.wav"); |
| 73 | +auto recognizer = SpeechRecognizer::FromConfig(config, audioInput); |
| 74 | +``` |
| 75 | + |
| 76 | +## Recognize speech |
| 77 | + |
| 78 | +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. |
| 79 | + |
| 80 | +* 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. |
| 81 | +* 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). |
| 82 | + |
| 83 | +> [!NOTE] |
| 84 | +> Learn more about how to [choose a speech recognition mode](../../../how-to-choose-recognition-mode.md). |
| 85 | + |
| 86 | +### Single-shot recognition |
| 87 | + |
| 88 | +Here's an example of asynchronous single-shot recognition using [`RecognizeOnceAsync`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#recognizeonceasync): |
| 89 | +
|
| 90 | +```cpp |
| 91 | +auto result = recognizer->RecognizeOnceAsync().get(); |
| 92 | +``` |
| 93 | +
|
| 94 | +You'll need to write some code to handle the result. This sample evaluates the [`result->Reason`](https://docs.microsoft.com/cpp/cognitive-services/speech/recognitionresult#reason): |
| 95 | + |
| 96 | +* Prints the recognition result: `ResultReason::RecognizedSpeech` |
| 97 | +* If there is no recognition match, inform the user: `ResultReason::NoMatch` |
| 98 | +* If an error is encountered, print the error message: `ResultReason::Canceled` |
| 99 | + |
| 100 | +```cpp |
| 101 | +switch (result->Reason) |
| 102 | +{ |
| 103 | + case ResultReason::RecognizedSpeech: |
| 104 | + cout << "We recognized: " << result->Text << std::endl; |
| 105 | + break; |
| 106 | + case ResultReason::NoMatch: |
| 107 | + cout << "NOMATCH: Speech could not be recognized." << std::endl; |
| 108 | + break; |
| 109 | + case ResultReason::Canceled: |
| 110 | + { |
| 111 | + auto cancellation = CancellationDetails::FromResult(result); |
| 112 | + cout << "CANCELED: Reason=" << (int)cancellation->Reason << std::endl; |
| 113 | + |
| 114 | + if (cancellation->Reason == CancellationReason::Error) { |
| 115 | + cout << "CANCELED: ErrorCode= " << (int)cancellation->ErrorCode << std::endl; |
| 116 | + cout << "CANCELED: ErrorDetails=" << cancellation->ErrorDetails << std::endl; |
| 117 | + cout << "CANCELED: Did you update the subscription info?" << std::endl; |
| 118 | + } |
| 119 | + } |
| 120 | + break; |
| 121 | + default: |
| 122 | + break; |
| 123 | +} |
| 124 | +``` |
| 125 | + |
| 126 | +### Continuous recognition |
| 127 | + |
| 128 | +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/cpp/cognitive-services/speech/speechrecognizer#stopcontinuousrecognitionasync). Here's an example of how continuous recognition is performed on an audio input file. |
| 129 | + |
| 130 | +Let's start by defining the input and initializing a [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer): |
| 131 | + |
| 132 | +```cpp |
| 133 | +auto audioInput = AudioConfig::FromWavFileInput("YourAudioFile.wav"); |
| 134 | +auto recognizer = SpeechRecognizer::FromConfig(config, audioInput); |
| 135 | +``` |
| 136 | + |
| 137 | +Next, let's create a variable to manage the state of speech recognition. To start, we'll declare a `promise<void>`, since at the start of recognition we can safely assume that it's not finished. |
| 138 | + |
| 139 | +```cpp |
| 140 | +promise<void> recognitionEnd; |
| 141 | +``` |
| 142 | + |
| 143 | +We'll subscribe to the events sent from the [`SpeechRecognizer`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer). |
| 144 | + |
| 145 | +* [`Recognizing`](https://docs.microsoft.com/cpp/cognitive-services/speech/asyncrecognizer#recognizing): Signal for events containing intermediate recognition results. |
| 146 | +* [`Recognized`](https://docs.microsoft.com/cpp/cognitive-services/speech/asyncrecognizer#recognized): Signal for events containing final recognition results (indicating a successful recognition attempt). |
| 147 | +* [`SessionStopped`](https://docs.microsoft.com/cpp/cognitive-services/speech/asyncrecognizer#sessionstopped): Signal for events indicating the end of a recognition session (operation). |
| 148 | +* [`Canceled`](https://docs.microsoft.com/cpp/cognitive-services/speech/asyncrecognizer#canceled): 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). |
| 149 | + |
| 150 | +```cpp |
| 151 | +recognizer->Recognizing.Connect([](const SpeechRecognitionEventArgs& e) |
| 152 | + { |
| 153 | + cout << "Recognizing:" << e.Result->Text << std::endl; |
| 154 | + }); |
| 155 | + |
| 156 | +recognizer->Recognized.Connect([](const SpeechRecognitionEventArgs& e) |
| 157 | + { |
| 158 | + if (e.Result->Reason == ResultReason::RecognizedSpeech) |
| 159 | + { |
| 160 | + cout << "RECOGNIZED: Text=" << e.Result->Text |
| 161 | + << " (text could not be translated)" << std::endl; |
| 162 | + } |
| 163 | + else if (e.Result->Reason == ResultReason::NoMatch) |
| 164 | + { |
| 165 | + cout << "NOMATCH: Speech could not be recognized." << std::endl; |
| 166 | + } |
| 167 | + }); |
| 168 | + |
| 169 | +recognizer->Canceled.Connect([&recognitionEnd](const SpeechRecognitionCanceledEventArgs& e) |
| 170 | + { |
| 171 | + cout << "CANCELED: Reason=" << (int)e.Reason << std::endl; |
| 172 | + if (e.Reason == CancellationReason::Error) |
| 173 | + { |
| 174 | + cout << "CANCELED: ErrorCode=" << (int)e.ErrorCode << "\n" |
| 175 | + << "CANCELED: ErrorDetails=" << e.ErrorDetails << "\n" |
| 176 | + << "CANCELED: Did you update the subscription info?" << std::endl; |
| 177 | + |
| 178 | + recognitionEnd.set_value(); // Notify to stop recognition. |
| 179 | + } |
| 180 | + }); |
| 181 | + |
| 182 | +recognizer->SessionStopped.Connect([&recognitionEnd](const SessionEventArgs& e) |
| 183 | + { |
| 184 | + cout << "Session stopped."; |
| 185 | + recognitionEnd.set_value(); // Notify to stop recognition. |
| 186 | + }); |
| 187 | +``` |
| 188 | +
|
| 189 | +With everything set up, we can call [`StopContinuousRecognitionAsync`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechrecognizer#startcontinuousrecognitionasync). |
| 190 | +
|
| 191 | +```cpp |
| 192 | +// Starts continuous recognition. Uses StopContinuousRecognitionAsync() to stop recognition. |
| 193 | +recognizer->StartContinuousRecognitionAsync().get(); |
| 194 | +
|
| 195 | +// Waits for recognition end. |
| 196 | +recognitionEnd.get_future().get(); |
| 197 | +
|
| 198 | +// Stops recognition. |
| 199 | +recognizer->StopContinuousRecognitionAsync().get(); |
| 200 | +``` |
| 201 | + |
| 202 | +### Dictation mode |
| 203 | + |
| 204 | +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?". |
| 205 | + |
| 206 | +To enable dictation mode, use the [`EnableDictation`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig#enabledictation) method on your [`SpeechConfig`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig). |
| 207 | + |
| 208 | +```cpp |
| 209 | +config->EnableDictation(); |
| 210 | +``` |
| 211 | + |
| 212 | +## Change source language |
| 213 | + |
| 214 | +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/cpp/cognitive-services/speech/speechconfig), then add this line directly below it. |
| 215 | + |
| 216 | +```cpp |
| 217 | +config->SetSpeechRecognitionLanguage("fr-FR"); |
| 218 | +``` |
| 219 | +
|
| 220 | +[`SetSpeechRecognitionLanguage`](https://docs.microsoft.com/cpp/cognitive-services/speech/speechconfig#setspeechrecognitionlanguage) 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). |
| 221 | +
|
| 222 | +## Improve recognition accuracy |
| 223 | +
|
| 224 | +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. |
| 225 | +
|
| 226 | +> [!IMPORTANT] |
| 227 | +> The Phrase List feature is only available in English. |
| 228 | +
|
| 229 | +To use a phrase list, first create a [`PhraseListGrammar`](https://docs.microsoft.com/cpp/cognitive-services/speech/phraselistgrammar) object, then add specific words and phrases with [`AddPhrase`](https://docs.microsoft.com/cpp/cognitive-services/speech/phraselistgrammar#addphrase). |
| 230 | +
|
| 231 | +Any changes to [`PhraseListGrammar`](https://docs.microsoft.com/cpp/cognitive-services/speech/phraselistgrammar) take effect on the next recognition or after a reconnection to the Speech service. |
| 232 | +
|
| 233 | +```cpp |
| 234 | +auto phraseListGrammar = PhraseListGrammar::FromRecognizer(recognizer); |
| 235 | +phraseListGrammar->AddPhrase("Supercalifragilisticexpialidocious"); |
| 236 | +``` |
| 237 | + |
| 238 | +If you need to clear your phrase list: |
| 239 | + |
| 240 | +```cpp |
| 241 | +phraseListGrammar->Clear(); |
| 242 | +``` |
| 243 | + |
| 244 | +### Other options to improve recognition accuracy |
| 245 | + |
| 246 | +Phrase lists are only one option to improve recognition accuracy. You can also: |
| 247 | + |
| 248 | +* [Improve accuracy with Custom Speech](../../../how-to-custom-speech.md) |
| 249 | +* [Improve accuracy with tenant models](../../../tutorial-tenant-model.md) |
0 commit comments