Quickstart: Recognize speech with the Speech SDK for .NET Core

Quickstarts are also available for text-to-speech and speech-translation.

If desired, choose a different programming language and/or environment:

In this article, you create a C# console application for .NET Core on Windows or macOS by using the Cognitive Services Speech SDK. You transcribe speech to text in real time from your PC's microphone. The application is built with the Speech SDK NuGet package and Microsoft Visual Studio 2017 or later (any edition).


.NET Core is an open-source, cross-platform .NET platform that implements the .NET Standard specification.

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.


This quickstart requires:

Create a Visual Studio project

  1. Start Visual Studio 2019.

  2. Make sure the .NET cross-platform development workload is available. Choose Tools > Get Tools and Features from the Visual Studio menu bar to open the Visual Studio installer. If this workload is already enabled, close the dialog box.

    Screenshot of Visual Studio installer, with Workloads tab highlighted

    Otherwise, select the box next to .NET Core cross-platform development, and select Modify at the lower right corner of the dialog box. Installation of the new feature will take a moment.

  3. Create a new Visual C# .NET Core Console App. In the New Project dialog box, from the left pane, expand Installed > Visual C# > .NET Core. Then select Console App (.NET Core). For the project name, enter helloworld.

    Screenshot of New Project dialog box

  4. Install and reference the Speech SDK NuGet package. In Solution Explorer, right-click the solution and select Manage NuGet Packages for Solution.

    Screenshot of Solution Explorer, with Manage NuGet Packages for Solution highlighted

  5. In the upper-right corner, in the Package Source field, select nuget.org. Search for the Microsoft.CognitiveServices.Speech package, and install it into the helloworld project.

    Screenshot of Manage Packages for Solution dialog box

  6. Accept the displayed license to begin installation of the NuGet package.

    Screenshot of License Acceptance dialog box

After the package is installed, a confirmation appears in the Package Manager console.

Add sample code

  1. Open Program.cs, and replace all the code in it with the following.

    using System;
    using System.Threading.Tasks;
    using Microsoft.CognitiveServices.Speech;
    namespace helloworld
        class Program
            public static async Task RecognizeSpeechAsync()
                // 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").
                var config = SpeechConfig.FromSubscription("YourSubscriptionKey", "YourServiceRegion");
                // Creates a speech recognizer.
                using (var recognizer = new SpeechRecognizer(config))
                    Console.WriteLine("Say something...");
                    // Starts speech recognition, and returns after a single utterance is recognized. 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.  The task returns the recognition text as result. 
                    // Note: Since RecognizeOnceAsync() returns only a single utterance, it is suitable only for single
                    // shot recognition like command or query. 
                    // For long-running multi-utterance recognition, use StartContinuousRecognitionAsync() instead.
                    var result = await recognizer.RecognizeOnceAsync();
                    // Checks result.
                    if (result.Reason == ResultReason.RecognizedSpeech)
                        Console.WriteLine($"We recognized: {result.Text}");
                    else if (result.Reason == ResultReason.NoMatch)
                        Console.WriteLine($"NOMATCH: Speech could not be recognized.");
                    else if (result.Reason == ResultReason.Canceled)
                        var cancellation = CancellationDetails.FromResult(result);
                        Console.WriteLine($"CANCELED: Reason={cancellation.Reason}");
                        if (cancellation.Reason == CancellationReason.Error)
                            Console.WriteLine($"CANCELED: ErrorCode={cancellation.ErrorCode}");
                            Console.WriteLine($"CANCELED: ErrorDetails={cancellation.ErrorDetails}");
                            Console.WriteLine($"CANCELED: Did you update the subscription info?");
            static void Main()
                Console.WriteLine("Please press a key to continue.");
  2. In the same file, replace the string YourSubscriptionKey with your subscription key.

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

  4. Save changes to the project.

Build and run the app

  1. Build the application. From the menu bar, choose Build > Build Solution. The code should compile without errors.

    Screenshot of Visual Studio application, with Build Solution option highlighted

  2. Start the application. From the menu bar, choose Debug > Start Debugging, or press F5.

    Screenshot of Visual Studio application, with Start Debugging option highlighted

  3. A console window appears, prompting you to 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.

    Screenshot of console output after successful recognition

Next steps

Additional samples, such as how to read speech from an audio file, are available on GitHub.

See also