.NET Windows용 C#에서 음성 인식 서비스 라이브러리 시작Get started with the speech recognition service library in C# for .NET Windows

서비스 라이브러리는 자신의 클라우드 서비스가 있고 이 서비스에서 Speech Service를 호출하려는 개발자를 위한 것입니다.The service library is for developers who have their own cloud service and want to call Speech Service from their service. 장치에 바인딩된 응용 프로그램에서 음성 인식 서비스를 호출하려면 이 SDK를 사용하지 마세요.If you want to call the speech recognition service from device-bound apps, do not use this SDK. 대신 다른 클라이언트 라이브러리 또는 REST API를 사용합니다.(Use other client libraries or REST APIs for that.)

C# 서비스 라이브러리를 사용하려면 Microsoft.Bing.Speech NuGet 패키지를 설치합니다.To use the C# service library, install the NuGet package Microsoft.Bing.Speech. 라이브러리 API 참조는 Microsoft Speech C# 서비스 라이브러리를 참조하세요.For the library API reference, see the Microsoft Speech C# service library.

다음 섹션에서는 C# 서비스 라이브러리를 사용하여 C# 샘플 응용 프로그램을 설치, 빌드 및 실행하는 방법에 대해 설명합니다.The following sections describe how to install, build, and run the C# sample application by using the C# service library.

필수 조건Prerequisites

플랫폼 요구 사항Platform requirements

다음 예제는 Visual Studio 2015, Community Edition을 사용하여 Windows 8 이상 및 .NET Framework 4.5 이상용으로 개발되었습니다.The following example was developed for Windows 8+ and .NET 4.5+ Framework by using Visual Studio 2015, Community Edition.

샘플 응용 프로그램 가져오기Get the sample application

Speech C# 서비스 라이브러리 샘플 리포지토리에서 샘플을 복제합니다.Clone the sample from the Speech C# service library sample repository.

Speech Recognition API 구독 및 평가판 구독 키 가져오기Subscribe to the Speech Recognition API, and get a free trial subscription key

Speech API는 Cognitive Services(이전의 Project Oxford)의 일부입니다.The Speech API is part of Cognitive Services (previously Project Oxford). Cognitive Services 구독 페이지에서 평가판 구독 키를 가져올 수 있습니다.You can get free trial subscription keys from the Cognitive Services subscription page. Speech API를 선택한 후에 API 키 가져오기를 선택하여 키를 가져옵니다.After you select the Speech API, select Get API Key to get the key. 기본 및 보조 키를 반환합니다.It returns a primary and secondary key. 두 키는 모두 동일한 할당량에 연결되므로 두 키 중 하나를 사용할 수 있습니다.Both keys are tied to the same quota, so you can use either key.

중요

  • 구독 키를 가져오세요.Get a subscription key. Speech 클라이언트 라이브러리를 사용하려면 먼저 구독 키가 있어야 합니다.Before you can use the Speech client libraries, you must have a subscription key.

  • 구독 키를 사용하세요.Use your subscription key. 제공된 C# 서비스 라이브러리 샘플 응용 프로그램을 사용하여 구독 키를 명령줄 매개 변수 중 하나로 제공해야 합니다.With the provided C# service library sample application, you need to provide your subscription key as one of the command-line parameters. 자세한 내용은 샘플 응용 프로그램 실행을 참조하세요.For more information, see Run the sample application.

1단계: 샘플 응용 프로그램 설치Step 1: Install the sample application

  1. Visual Studio 2015를 시작하고, 파일 > 열기 > 프로젝트/솔루션을 차례로 선택합니다.Start Visual Studio 2015, and select File > Open > Project/Solution.

  2. SpeechClient.sln이라는 Visual Studio 2015 솔루션(.sln) 파일을 두 번 클릭하여 엽니다.Double-click to open the Visual Studio 2015 Solution (.sln) file named SpeechClient.sln. 솔루션이 Visual Studio에서 열립니다.The solution opens in Visual Studio.

2단계: 샘플 응용 프로그램 빌드Step 2: Build the sample application

Ctrl+Shift+B를 누르거나 리본 메뉴에서 빌드를 선택합니다.Press Ctrl+Shift+B, or select Build on the ribbon menu. 그런 다음, 솔루션 빌드를 선택합니다.Then select Build Solution.

3단계: 샘플 응용 프로그램 실행Step 3: Run the sample application

  1. 빌드가 완료되면 F5 키를 누르거나 리본 메뉴에서 시작을 선택하여 예제를 실행합니다.After the build is finished, press F5 or select Start on the ribbon menu to run the example.

  2. 샘플에 대한 출력 디렉터리(예: SpeechClientSample\bin\Debug)를 엽니다.Open the output directory for the sample, for example, SpeechClientSample\bin\Debug. Shift+마우스 오른쪽 단추를 클릭하고, 여기서 명령 창 열기를 선택합니다.Press Shift+Right-click, and select Open command window here.

  3. 다음 인수를 사용하여 SpeechClientSample.exe를 실행합니다.Run SpeechClientSample.exe with the following arguments:

    • Arg[0]: 입력 오디오 WAV 파일을 지정합니다.Arg[0]: Specify an input audio WAV file.
    • Arg [1]: 오디오 로캘을 지정합니다.Arg[1]: Specify the audio locale.
    • Arg[2]: 인식 모드를 지정합니다(ShortPhrase 모드의 경우 Short, LongDictation 모드의 경우 Long).Arg[2]: Specify the recognition modes: Short for the ShortPhrase mode and Long for the LongDictation mode.
    • Arg [3]: 음성 인식 서비스에 액세스하기 위한 구독 키를 지정합니다.Arg[3]: Specify the subscription key to access the speech recognition service.

샘플 설명Samples explained

인식 모드Recognition modes

  • ShortPhrase 모드: 최대 15초가 걸리는 발화입니다.ShortPhrase mode: An utterance up to 15 seconds long. 데이터가 서버로 보내지면 클라이언트에서 여러 개의 부분 결과 및 하나의 최종 결과를 받습니다.As data is sent to the server, the client receives multiple partial results and one final best result.
  • LongDictation 모드: 최대 10분이 걸리는 발화입니다.LongDictation mode: An utterance up to 10 minutes long. 데이터가 서버로 보내지면 서버에서 문장 일시 중지를 나타내는 위치에 따라 클라이언트에서 여러 개의 부분 결과 및 여러 개의 최종 결과를 받습니다.As data is sent to the server, the client receives multiple partial results and multiple final results, based on where the server indicates sentence pauses.

지원되는 오디오 형식Supported audio formats

Speech API에서 오디오/WAV를 지원하기 위해 사용하는 코덱은 다음과 같습니다.The Speech API supports audio/WAV by using the following codecs:

  • PCM 단일 채널PCM single channel
  • SirenSiren
  • SirenSRSirenSR

Preferences(기본 설정) 개체Preferences

SpeechClient를 만들려면 먼저 Preferences 개체를 만들어야 합니다.To create a SpeechClient, you need to first create a Preferences object. Preferences 개체는 음성 서비스의 동작을 구성하는 매개 변수의 집합입니다.The Preferences object is a set of parameters that configures the behavior of the speech service. 구성되는 필드는 다음과 같습니다.It consists of the following fields:

  • SpeechLanguage: 음성 서비스로 보내는 오디오의 로캘입니다.SpeechLanguage: The locale of the audio sent to the speech service.
  • ServiceUri: 음성 서비스를 호출하는 데 사용되는 엔드포인트입니다.ServiceUri: The endpoint used to call the speech service.
  • AuthorizationProvider: 음성 서비스에 액세스하기 위해 토큰을 가져오는 데 사용되는 IAuthorizationProvider 구현입니다.AuthorizationProvider: An IAuthorizationProvider implementation used to fetch tokens in order to access the speech service. 샘플에서는 Cognitive Services 권한 부여 공급자를 제공하지만, 토큰 캐싱을 처리할 수 있는 사용자 고유의 구현을 만드는 것이 좋습니다.Although the sample provides a Cognitive Services authorization provider, we highly recommend that you create your own implementation to handle token caching.
  • EnableAudioBuffering: 고급 옵션입니다.EnableAudioBuffering: An advanced option. 연결 관리를 참조하세요.See Connection management.

음성 입력Speech input

SpeechInput 개체는 다음 두 개의 필드로 구성됩니다.The SpeechInput object consists of two fields:

  • Audio: SDK에서 오디오를 끌어오는 스트림 구현입니다.Audio: A stream implementation of your choice from which the SDK pulls audio. 읽기를 지원하는 스트림 중 하나일 수 있습니다.It can be any stream that supports reading.

    참고

    스트림의 읽기에서 0을 반환할 때 SDK에서 스트림의 끝을 감지합니다.The SDK detects the end of the stream when the stream returns 0 in read.

  • RequestMetadata: 음성 요청에 대한 메타데이터입니다.RequestMetadata: Metadata about the speech request. 자세한 내용은 참조를 참조하세요.For more information, see the reference.

음성 요청Speech request

SpeechClient 및 SpeechInput 개체가 인스턴스화되면 RecognizeAsync를 사용하여 Speech Service에 요청합니다.After you have instantiated a SpeechClient and SpeechInput objects, use RecognizeAsync to make a request to Speech Service.

    var task = speechClient.RecognizeAsync(speechInput);

요청이 완료되면 RecognizeAsync에서 반환된 작업이 완료됩니다.After the request finishes, the task returned by RecognizeAsync finishes. 마지막 RecognitionResult는 인식의 끝입니다.The last RecognitionResult is the end of the recognition. 서비스 또는 SDK가 예기치 않게 실패하면 작업이 실패할 수 있습니다.The task can fail if the service or the SDK fails unexpectedly.

음성 인식 이벤트Speech recognition events

부분 결과 이벤트Partial results event

이 이벤트는 말하기를 끝내거나(MicrophoneRecognitionClient를 사용하는 경우) 데이터 보내기를 끝내기(DataRecognitionClient를 사용하는 경우) 전에도 Speech Service에서 사용자가 말할 수 있는 내용을 예측할 때마다 호출됩니다.This event gets called every time Speech Service predicts what you might be saying, even before you finish speaking (if you use MicrophoneRecognitionClient) or finish sending data (if you use DataRecognitionClient). SpeechClient.SubscribeToPartialResult()를 사용하여 이벤트를 구독할 수 있습니다.You can subscribe to the event by using SpeechClient.SubscribeToPartialResult(). 또는 일반 이벤트 구독 메서드인 SpeechClient.SubscribeTo<RecognitionPartialResult>()를 사용할 수 있습니다.Or you can use the generic events subscription method SpeechClient.SubscribeTo<RecognitionPartialResult>().

반환 형식Return format 설명Description
LexicalFormLexicalForm 이 형식은 처리되지 않은 원시 음성 인식 결과가 필요한 응용 프로그램에서 사용하기에 적합합니다.This form is optimal for use by applications that need raw, unprocessed speech recognition results.
DisplayTextDisplayText 역 텍스트 정규화, 대문자 표시, 문장 부호 및 불경한 언어 마스킹이 적용된 인식된 구입니다.The recognized phrase with inverse text normalization, capitalization, punctuation, and profanity masking applied. 불경한 언어는 첫 번째 문자 뒤에 별표로 마스킹됩니다(예: "d***").Profanity is masked with asterisks after the initial character, for example, "d***." 이 형식은 음성 인식 결과를 사용자에게 표시하는 응용 프로그램에서 사용하기에 적합합니다.This form is optimal for use by applications that display the speech recognition results to a user.
신뢰도Confidence 인식된 구가 음성 인식 서버에서 정의한 대로 관련 오디오를 나타내는 신뢰도 수준입니다.The level of confidence the recognized phrase represents for the associated audio as defined by the speech recognition server.
MediaTimeMediaTime 오디오 스트림의 시작을 기준으로 한 현재 시간입니다(100나노초 시간 단위).The current time relative to the start of the audio stream (in 100-nanosecond units of time).
MediaDurationMediaDuration 오디오 세그먼트를 기준으로 한 현재 구의 기간/길이(시간의 100나노초 단위)입니다.The current phrase duration/length relative to the audio segment (in 100-nanosecond units of time).

결과 이벤트Result event

말하기를 끝내면(ShortPhrase 모드에서) 이 이벤트가 호출됩니다.When you finish speaking (in ShortPhrase mode), this event is called. 결과에 대한 N 상위 선택 항목이 제공됩니다.You're provided with n-best choices for the result. LongDictation 모드에서는 서버에서 문장 일시 중지를 나타내는 위치에 따라 이벤트가 여러 번 호출될 수 있습니다.In LongDictation mode, the event can be called multiple times, based on where the server indicates sentence pauses. SpeechClient.SubscribeToRecognitionResult()를 사용하여 이벤트를 구독할 수 있습니다.You can subscribe to the event by using SpeechClient.SubscribeToRecognitionResult(). 또는 일반 이벤트 구독 메서드인 SpeechClient.SubscribeTo<RecognitionResult>()를 사용할 수 있습니다.Or you can use the generic events subscription method SpeechClient.SubscribeTo<RecognitionResult>().

반환 형식Return format 설명Description
RecognitionStatusRecognitionStatus 인식이 생성된 방법에 상태입니다.The status on how the recognition was produced. 예를 들어 성공적인 인식 결과 또는 연결 취소 결과 등으로 생성된 것이 있습니다.For example, was it produced as a result of successful recognition or as a result of canceling the connection, etc.
PhrasesPhrases 인식 신뢰도를 사용하여 인식된 N 상위 구의 집합입니다.The set of n-best recognized phrases with the recognition confidence.

인식 결과에 대한 자세한 내용은 출력 형식을 참조하세요.For more information on recognition results, see Output format.

음성 인식 응답Speech recognition response

음성 응답 예제는 다음과 같습니다.Speech response example:

--- Partial result received by OnPartialResult  
---what  
--- Partial result received by OnPartialResult  
--what's  
--- Partial result received by OnPartialResult  
---what's the web  
--- Partial result received by OnPartialResult   
---what's the weather like  
---***** Phrase Recognition Status = [Success]   
***What's the weather like? (Confidence:High)  
What's the weather like? (Confidence:High) 

연결 관리Connection management

API는 요청당 하나의 WebSocket 연결을 사용합니다.The API utilizes a single WebSocket connection per request. 최적의 사용자 경험을 위해 SDK에서 Speech Service에 다시 연결하고, 마지막으로 받은 RecognitionResult에서 인식을 시작하려고 합니다.For optimal user experience, the SDK attempts to reconnect to Speech Service and start the recognition from the last RecognitionResult that it received. 예를 들어 오디오 요청에 2분이 걸리고, SDK가 1분 표식에서 RecognitionEvent를 받고, 5초 후에 네트워크 오류가 발생한 경우, SDK는 1분 표식부터 시작하는 새 연결을 시작합니다.For example, if the audio request is two minutes long, the SDK received a RecognitionEvent at the one-minute mark, and a network failure occurred after five seconds, the SDK starts a new connection that starts from the one-minute mark.

참고

스트림에서 검색을 지원하지 않을 수 있으므로 SDK는 1분 표식까지 다시 검색하지 않습니다.The SDK doesn't seek back to the one-minute mark because the stream might not support seeking. 대신, SDK는 오디오를 버퍼링하는 데 사용하는 내부 버퍼를 유지하고, RecognitionResult 이벤트를 받을 때 버퍼를 지웁니다.Instead, the SDK keeps an internal buffer that it uses to buffer the audio and clears the buffer as it receives RecognitionResult events.

버퍼링 동작Buffering behavior

기본적으로 SDK는 네트워크 중단 발생 시 복구할 수 있도록 오디오를 버퍼링합니다.By default, the SDK buffers audio so that it can recover when a network interrupt occurs. 네트워크 연결이 끊겨 있는 동안 손실된 오디오를 삭제하고 연결을 다시 시작하는 것이 바람직한 시나리오에서는 Preferences 개체의 EnableAudioBufferingfalse로 설정하여 오디오 버퍼링을 사용하지 않는 것이 가장 좋습니다.In a scenario where it's preferable to discard the audio lost during the network disconnect and restart the connection, it's best to disable audio buffering by setting EnableAudioBuffering in the Preferences object to false.

Microsoft Speech C# 서비스 라이브러리 참조Microsoft Speech C# service library reference