com.naver.speech.clientapi

Class SpeechRecognizer

java.lang.Object

com.naver.speech.clientapi.SpeechRecognizer

public class SpeechRecognizer
extends java.lang.Object

이 클래스는 네이버 음성인식 서비스를 사용할 수 있도록 클라이언트 역할을 제공합니다. 네이버 음성인식은 음성인식 서버와 클라이언트 간의 통신으로 구성되어 있고, 클라이언트는 음성 입력을 받아 서버로 전송하고, 서버로부터 인식 결과를 받는 역할을 동시에 수행합니다. 따라서 반드시 현재 어플리케이션이 android.permission.RECORD_AUDIO 와 android.permission.INTERNET 사용 권한을 가지고 있는지 확인해야 합니다.

이 클래스는 실행 전 반드시 initialize() 메소드를 호출하여야 하고, 종료 후 반드시 release() 메소드를 호출하여야 합니다. 이는 음성인식으로 인한 자원을 초기화하거나, 해제함으로써 다른 프로세스에 악영향을 주는 것을 방지하기 위함입니다. 사용 시나리오에 따라서 달라질 수 있지만, 적어도 android.app.Activity#onStart() 콜백이 호출될 때에는 initialize()를, android.app.Activity#onStop() 콜백이 호출될 때에는 release()를 호출하는 것을 권장합니다.

이 클래스는 recognize(SpeechConfig) 메소드를 호출함으로써 음성인식을 시작합니다. 음성인식 수행 과정은 아래와 같은 스테이트머신에 기반합니다. (다이어그램 참고)

각 스테이트로 천이할 때 마다 콜백 메소드가 호출되며, SpeechRecognitionListener 를 상속받아서 콜백 메소드들을 오버라이딩 해야 합니다. 이를 통해서 음성인식 시작, 중간 결과, 최종 결과 등 다양한 동작을 어플리케이션에 이용할 수 있습니다.

Field Summary

Fields

Modifier and Type	Field and Description
static int	ERROR_AUDIO_FINIALIZE 오디오 자원 해제 오류
static int	ERROR_AUDIO_INITIALIZE 오디오 자원 초기화 오류
static int	ERROR_AUDIO_RECORD 음성 입력(녹음) 오류
static int	ERROR_CLIENTINFO 클라이언트 프로퍼티 오류
static int	ERROR_EXCEED_TIME_LIMIT 인증 time stamp 불량
static int	ERROR_INVALID_PACKET 전송/수신 패킷 오류
static int	ERROR_INVALID_RESULT 인식 결과 오류
static int	ERROR_NETWORK_FINALIZE 네트워크 자원 해제 오류
static int	ERROR_NETWORK_INITIALIZE 네트워크 자원 초기화 오류
static int	ERROR_NETWORK_NACK 인식 서버 오류
static int	ERROR_NETWORK_READ 네트워크 데이터 수신 오류
static int	ERROR_NETWORK_WRITE 네트워크 데이터 전송 오류
static int	ERROR_NO_CLIENT_RUNNING 클라이언트가 음성인식을 수행하고 있지 않는 상황에서, 특정 음성인식 관련 이벤트가 감지되었음
static int	ERROR_OPENAPI_AUTH OpenAPI 인증 에러(Client ID 또는 AndroidManifest.xml의 package가 개발자센터에 등록한 값과 다름)
static int	ERROR_QUOTA_OVERFLOW 정해진 Quota를 다 소진함
static int	ERROR_SECURITY 인증 권한 오류
static int	ERROR_SERVER_POOL 음성인식 서버의 가용 풀(pool) 부족
static int	ERROR_SESSION_EXPIRED 음성인식 서버 세션 만료
static int	ERROR_SPEECH_SIZE_EXCEEDED 음성 패킷 사이즈 초과
static int	ERROR_TIMEOUT 일정 시간 이상 인식 서버로 음성을 전송하지 못하거나, 인식 결과를 받지 못하였음
static int	ERROR_UNKOWN_EVENT 클라이언트 내부에 규정되어 있지 않은 이벤트가 감지되었음
static int	ERROR_VERSION 프로토콜 버전 오류
static int	ERROR_WRONG_LANGUAGE_TYPE 올바른 Language Type이 아님
static int	ERROR_WRONG_SERVICE_TYPE 올바른 Service Type이 아님
protected SpeechRecognitionListener	speechRecognitionListener

Constructor Summary

Constructors

Constructor and Description
SpeechRecognizer(android.content.Context context, java.lang.String clientId) 음성인식 클라이언트 인스턴스를 생성하고, OpenAPI 인증 작업을 수행합니다.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	cancel() 이 함수를 호출하는 즉시 음성인식의 모든 동작을 즉시 정지하는 이벤트를 발생시킵니다.
void	initialize() 음성인식 자원을 초기화해줍니다.
boolean	isRunning() 현재 음성인식의 수행 여부를 반환합니다.
protected void	onEndPointDetected() SpeechRecognitionListener.onEndPointDetected() 참고
protected void	onEndPointDetectTypeSelected(int epdType) SpeechRecognitionListener#onEndPointDetectTypeSelected(EndPointDetectType) 참고
protected void	onError(int errorCode) SpeechRecognitionListener.onError(int) 참고
protected void	onInactive() SpeechRecognitionListener.onInactive() 참고
protected void	onPartialResult(java.lang.String partialResult) SpeechRecognitionListener.onPartialResult(String) 참고
protected void	onReady() SpeechRecognitionListener.onReady() 참고
protected void	onRecord(short[] speech) SpeechRecognitionListener.onRecord(short[]) 참고
protected void	onResult(java.lang.Object[] finalResult) SpeechRecognitionListener.onResult(SpeechRecognitionResult) 참고
boolean	recognize(SpeechConfig config) 음성인식을 시작하는 이벤트를 발생시킵니다.
void	release() 음성인식 자원을 해제해줍니다.
boolean	selectEPDTypeInHybrid(SpeechConfig.EndPointDetectType epdType) 음성인식의 EPD(end point detecion) 종류를 선택합니다.
void	setSpeechRecognitionListener(SpeechRecognitionListener callback) 음성인식의 각종 콜백 함수를 정의할 리스너를 등록합니다.
boolean	stop() 이 함수를 호출하는 즉시 onEndPointDetected()로 천이됩니다.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

speechRecognitionListener

protected SpeechRecognitionListener speechRecognitionListener

ERROR_NETWORK_INITIALIZE

public static final int ERROR_NETWORK_INITIALIZE

네트워크 자원 초기화 오류

See Also:

Constant Field Values

ERROR_NETWORK_FINALIZE

public static final int ERROR_NETWORK_FINALIZE

네트워크 자원 해제 오류

See Also:

Constant Field Values

ERROR_NETWORK_READ

public static final int ERROR_NETWORK_READ

네트워크 데이터 수신 오류

See Also:

Constant Field Values

ERROR_NETWORK_WRITE

public static final int ERROR_NETWORK_WRITE

네트워크 데이터 전송 오류

See Also:

Constant Field Values

ERROR_NETWORK_NACK

public static final int ERROR_NETWORK_NACK

인식 서버 오류

See Also:

Constant Field Values

ERROR_INVALID_PACKET

public static final int ERROR_INVALID_PACKET

전송/수신 패킷 오류

See Also:

Constant Field Values

ERROR_AUDIO_INITIALIZE

public static final int ERROR_AUDIO_INITIALIZE

오디오 자원 초기화 오류

See Also:

AudioRecord, Constant Field Values

ERROR_AUDIO_FINIALIZE

public static final int ERROR_AUDIO_FINIALIZE

오디오 자원 해제 오류

See Also:

AudioRecord, Constant Field Values

ERROR_AUDIO_RECORD

public static final int ERROR_AUDIO_RECORD

음성 입력(녹음) 오류

See Also:

Constant Field Values

ERROR_SECURITY

public static final int ERROR_SECURITY

인증 권한 오류

See Also:

Constant Field Values

ERROR_INVALID_RESULT

public static final int ERROR_INVALID_RESULT

인식 결과 오류

See Also:

Constant Field Values

ERROR_TIMEOUT

public static final int ERROR_TIMEOUT

일정 시간 이상 인식 서버로 음성을 전송하지 못하거나, 인식 결과를 받지 못하였음

See Also:

Constant Field Values

ERROR_NO_CLIENT_RUNNING

public static final int ERROR_NO_CLIENT_RUNNING

클라이언트가 음성인식을 수행하고 있지 않는 상황에서, 특정 음성인식 관련 이벤트가 감지되었음

See Also:

Constant Field Values

ERROR_UNKOWN_EVENT

public static final int ERROR_UNKOWN_EVENT

클라이언트 내부에 규정되어 있지 않은 이벤트가 감지되었음

See Also:

Constant Field Values

ERROR_VERSION

public static final int ERROR_VERSION

프로토콜 버전 오류

See Also:

Constant Field Values

ERROR_CLIENTINFO

public static final int ERROR_CLIENTINFO

클라이언트 프로퍼티 오류

See Also:

Constant Field Values

ERROR_SERVER_POOL

public static final int ERROR_SERVER_POOL

음성인식 서버의 가용 풀(pool) 부족

See Also:

Constant Field Values

ERROR_SESSION_EXPIRED

public static final int ERROR_SESSION_EXPIRED

음성인식 서버 세션 만료

See Also:

Constant Field Values

ERROR_SPEECH_SIZE_EXCEEDED

public static final int ERROR_SPEECH_SIZE_EXCEEDED

음성 패킷 사이즈 초과

See Also:

Constant Field Values

ERROR_EXCEED_TIME_LIMIT

public static final int ERROR_EXCEED_TIME_LIMIT

인증 time stamp 불량

See Also:

Constant Field Values

ERROR_WRONG_SERVICE_TYPE

public static final int ERROR_WRONG_SERVICE_TYPE

올바른 Service Type이 아님

See Also:

Constant Field Values

ERROR_WRONG_LANGUAGE_TYPE

public static final int ERROR_WRONG_LANGUAGE_TYPE

올바른 Language Type이 아님

See Also:

Constant Field Values

ERROR_OPENAPI_AUTH

public static final int ERROR_OPENAPI_AUTH

OpenAPI 인증 에러(Client ID 또는 AndroidManifest.xml의 package가 개발자센터에 등록한 값과 다름)

See Also:

Constant Field Values

ERROR_QUOTA_OVERFLOW

public static final int ERROR_QUOTA_OVERFLOW

정해진 Quota를 다 소진함

See Also:

Constant Field Values

Constructor Detail

SpeechRecognizer

public SpeechRecognizer(android.content.Context context,
                java.lang.String clientId)
                 throws SpeechRecognitionException

음성인식 클라이언트 인스턴스를 생성하고, OpenAPI 인증 작업을 수행합니다.

Parameters:

context - 메인 액티비티의 context

clientId - 개발자센터에서 "내 애플리케이션"을 등록할 때 발급받은 Client ID

Throws:

SpeechRecognitionException - 예외가 발생하는 경우는 아래와 같습니다.
1. context 파라미터가 올바른 메인 액티비티의 context가 아님
2. AndroidManifest.xml에서 package 이름을 올바르게 등록하지 않았음
3. package 이름을 올바르게 등록했지만 과도하게 긴 경우(256바이트 이하를 권장)
4. clientId 파라미터가 null인 경우
개발하면서 예외가 발생하지 않았다면 실서비스에서도 예외는 발생하지 않습니다. 개발 초기에만 주의하시면 됩니다.

Method Detail

initialize

public void initialize()

음성인식 자원을 초기화해줍니다. android.app.Activity#onStart() 콜백 시점에 호출되는 것을 권장합니다.

release

public void release()

음성인식 자원을 해제해줍니다. android.app.Activity#onStop() 콜백 시점에 호출되는 것을 권장합니다.

setSpeechRecognitionListener

public void setSpeechRecognitionListener(SpeechRecognitionListener callback)

음성인식의 각종 콜백 함수를 정의할 리스너를 등록합니다.

Parameters:

callback - 콜백 리스너

See Also:

SpeechRecognitionListener

selectEPDTypeInHybrid

public boolean selectEPDTypeInHybrid(SpeechConfig.EndPointDetectType epdType)

음성인식의 EPD(end point detecion) 종류를 선택합니다.
이 함수는 hybrid EPD 모드에서만 동작합니다. 그 외의 EPD 모드에서 호출할 경우, 동작하지 않고 false를 반환합니다. EPD 종류를 선택, 결정되면 onEndPointDetectTypeSelected(int) 콜백 함수가 호출됩니다.

Parameters:

epdType - EPD 종류(AUTO, MANUAL 중 하나를 선택)

Returns:

EPD 종류 선택 동작이 완료되면 true를 반환합니다. hybrid EPD 모드가 아닌 상태에서 호출하거나, 클라이언트가 음성인식을 수행 중이지 않는 상태에서 호출하면 false를 반환합니다.

See Also:

SpeechConfig.EndPointDetectType.AUTO, SpeechConfig.EndPointDetectType.MANUAL, SpeechConfig.EndPointDetectType.HYBRID

stop

public boolean stop()

이 함수를 호출하는 즉시 onEndPointDetected()로 천이됩니다.
즉, 이 함수를 호출하는 즉시 음성인식 서버로부터 최종 결과를 받은 후 종료됩니다. 네트워크 환경에 따라 최종 결과 수신 및 종료가 지연될 수 있습니다.

Returns:

onEndPointDetected()로 천이가 완료되면 true를 반환합니다. 해당 동작 중에 오류가 발생하면, 동작을 완료하지 못하고 false를 반환합니다.

cancel

public boolean cancel()

이 함수를 호출하는 즉시 음성인식의 모든 동작을 즉시 정지하는 이벤트를 발생시킵니다.

Returns:

즉시 정지 이벤트를 발생시킨 후, true를 반환합니다. 해당 동작 중에 오류가 발생하면, 이벤트를 발생시키지 못하고 false를 반환합니다.

isRunning

public boolean isRunning()

현재 음성인식의 수행 여부를 반환합니다.

Returns:

음성인식이 수행 중일 경우 true를 반환합니다.

recognize

public boolean recognize(SpeechConfig config)
                  throws SpeechRecognitionException

음성인식을 시작하는 이벤트를 발생시킵니다. SpeechRecognizer는 시작 이벤트가 발생하면, 백그라운드로 오디오 자원 할당 및 네트워크 연결을 시도합니다. 그리고 이어서 발생하는 이벤트에 따라 콜백 함수를 호출하면서 음성인식을 수행하게 됩니다. 이 함수는 오직 시작 이벤트를 발생시키는 동작만 수행한 후, 종료됩니다.

Parameters:

config - 음성인식 서비스 종류, 언어 종류, EPD(end point detection)모드 종류 등 설정값을 포함

Returns:

시작 이벤트를 발생시킨 후, true를 반환합니다. 해당 동작 중에 오류가 발생하면, 이벤트를 발생시키지 못하고 false를 반환합니다.

Throws:

SpeechRecognitionException - config의 값이 null이거나 이미 음성인식이 동작 중임

See Also:

SpeechRecognitionListener

onInactive

protected void onInactive()

SpeechRecognitionListener.onInactive() 참고

onReady

protected void onReady()

SpeechRecognitionListener.onReady() 참고

onRecord

protected void onRecord(short[] speech)

SpeechRecognitionListener.onRecord(short[]) 참고

Parameters:

speech - speech

onPartialResult

protected void onPartialResult(java.lang.String partialResult)

SpeechRecognitionListener.onPartialResult(String) 참고

Parameters:

partialResult - partial result

onEndPointDetected

protected void onEndPointDetected()

SpeechRecognitionListener.onEndPointDetected() 참고

onResult

protected void onResult(java.lang.Object[] finalResult)

SpeechRecognitionListener.onResult(SpeechRecognitionResult) 참고

Parameters:

finalResult - final result

onError

protected void onError(int errorCode)

SpeechRecognitionListener.onError(int) 참고

Parameters:

errorCode - error code

onEndPointDetectTypeSelected

protected void onEndPointDetectTypeSelected(int epdType)

SpeechRecognitionListener#onEndPointDetectTypeSelected(EndPointDetectType) 참고

Parameters:

epdType - EPD(end point detection) type