Quickstart: Recognize speech in C++ on macOS by using the Speech SDK

In this article, you create a C++ console application for macOS 10.13 and above. You use the Cognitive Services Speech SDK to transcribe speech to text in real time from your Mac's microphone. The application is built with the Speech SDK for macOS and your Mac's default C++ compiler (for example, g++).


You need a Speech Services subscription key to complete this Quickstart. You can get one for free. See Try the Speech Services for free for details.

Install Speech SDK


By downloading any of the Speech SDK for Azure Cognitive Services components on this page, you acknowledge its license. See the Microsoft Software License Terms for the Speech SDK.

The current version of the Cognitive Services Speech SDK is 1.5.1.

The Speech SDK for macOS can be downloaded as a zipped framework bundle from https://aka.ms/csspeech/macosbinary.

Download and install the SDK as follows:

  1. Choose a directory to which the Speech SDK files should be extracted, and set the SPEECHSDK_ROOT environment variable to point to that directory. This variable makes it easy to refer to the directory in future commands. For example, if you want to use the directory speechsdk in your home directory, use a command like the following:

    export SPEECHSDK_ROOT="$HOME/speechsdk"
  2. Create the directory if it doesn't exist yet.

    mkdir -p "$SPEECHSDK_ROOT"
  3. Download and extract the .zip archive containing the Speech SDK framework:

    wget -O SpeechSDK-macOS.zip https://aka.ms/csspeech/macosbinary
    unzip SpeechSDK-macOS.zip -d "$SPEECHSDK_ROOT"
  4. Validate the contents of the top-level directory of the extracted package:

    ls -l "$SPEECHSDK_ROOT"

    The directory listing should contain the third-party notice and license files, as well as a MicrosoftCognitiveServicesSpeech.framework directory.

Add sample code

  1. Create a C++ source file named helloworld.cpp, and paste the following code into it.

    #include <iostream> // cin, cout
    #include <MicrosoftCognitiveServicesSpeech/speechapi_cxx.h>
    using namespace std;
    using namespace Microsoft::CognitiveServices::Speech;
    void recognizeSpeech() {
        // Creates an instance of a speech config with specified subscription key and service region.
        // Replace with your own subscription key and service region (e.g., "westus").
        auto config = SpeechConfig::FromSubscription("YourSubscriptionKey", "YourServiceRegion");
        // Creates a speech recognizer
        auto recognizer = SpeechRecognizer::FromConfig(config);
        cout << "Say something...\n";
        // Performs recognition. RecognizeOnceAsync() returns when the first utterance has been recognized,
        // so it is suitable only for single shot recognition like command or query. For long-running
        // recognition, use StartContinuousRecognitionAsync() instead.
        auto result = recognizer->RecognizeOnceAsync().get();
        // Checks result.
        if (result->Reason == ResultReason::RecognizedSpeech) {
            cout << "We recognized: " << result->Text << std::endl;
        else if (result->Reason == ResultReason::NoMatch) {
            cout << "NOMATCH: Speech could not be recognized." << std::endl;
        else if (result->Reason == ResultReason::Canceled) {
            auto cancellation = CancellationDetails::FromResult(result);
            cout << "CANCELED: Reason=" << (int)cancellation->Reason << std::endl;
            if (cancellation->Reason == CancellationReason::Error) {
                cout << "CANCELED: ErrorCode= " << (int)cancellation->ErrorCode << std::endl;
                cout << "CANCELED: ErrorDetails=" << cancellation->ErrorDetails << std::endl;
                cout << "CANCELED: Did you update the subscription info?" << std::endl;
    int main(int argc, char **argv) {
        setlocale(LC_ALL, "");
        return 0;
  2. In this new file, replace the string YourSubscriptionKey with your Speech Services subscription key.

  3. Replace the string YourServiceRegion with the region associated with your subscription (for example, westus for the free trial subscription).

Build the app


Make sure to enter the commands below as a single command line. The easiest way to do that is to copy the command by using the Copy button next to each command, and then paste it at your shell prompt.

  • Run the following command to build the application.

    g++ helloworld.cpp -o helloworld --std=c++14 -F${SPEECHSDK_ROOT} -framework MicrosoftCognitiveServicesSpeech

Run the app

  1. Configure the loader's library path to point to the Speech SDK library.

  2. Run the application.

  3. In the console window, a prompt appears, requesting that you say something. Speak an English phrase or sentence. Your speech is transmitted to the Speech Services and transcribed to text, which appears in the same window.

    Say something...
    We recognized: What's the weather like?

Next steps

See also