ASR
음성인식 결과를 Play 로 전달하기 위한 규격

Version

최신 버전은 1.6 입니다.
Version
Date
Description
1.0
2019.11.24
규격 추가
1.1
2020.04.29
Recognize directive 에 wakeup, timeout 필드 추가 Recognize directive, ExpechSpeech event 에 asrContext 필 추가
1.2
2020.06.05
Recognize directive, ExpectSpeech event 의 asrContext 에 playServiceId 필드 추가
1.3
2020.06.09
Recognize directive, ExpectSpeech event 의 sessionId 필드 삭제
1.4
2020.11.18
ExpectSpeech directive 에 epd 필드 추가
1.5
2021.03.03
Context 에 state, initiator 필드 추가
1.6
2021.05.31
ASR.ExpectSpeech directive 에 listenTimeoutFailBeep 필드 추가

State Diagram

SDK Interface

ASRAgent 사용

ASR interface 규격에 따른 디바이스의 동작 제어는 ASRAgent 가 처리합니다.
Android
iOS
Linux
NuguAndroidClient instance 를 통해 ASRAgent instance 에 접근할 수 있습니다.
val asrAgent = nuguAndroidClient.asrAgent
Microphone 으로 부터 음성 데이터를 가져오기 위한 AudioSourceManager 를 생성합니다.
val audioSourceManager = AudioSourceManager(AudioRecordSourceFactory())
음성인식에 필요한 학습 모델을 설정합니다.
NuguAndroidClient.Builder(
context,
NuguOAuth.create(context),
audioSourceManager
).endPointDetector(
EndPointDetector(
context.getDir(
"skt_nugu_assets",
Context.MODE_PRIVATE
).absolutePath + File.separator + "skt_epd_model.raw"
)
)
AudioSourceManager, ASRAgent 를 연결해주기 위한 SpeechRecognizerAggregator 를 생성합니다.
speechRecognizerAggregator = SpeechRecognizerAggregator(
null,
SpeechProcessorDelegate(asrAgent),
audioSourceManager,
Handler(Looper.getMainLooper())
)
NuguClient instance 를 통해 ASRAgent instance 에 접근할 수 있습니다.
let asrAgent = nuguClient.asrAgent
Microphone 으로 부터 음성 데이터를 가져오기 위한 MicInputProvider 를 생성합니다.
let micInputProvider = MicInputProvider()
Microphone 으로 부터 가져온 음성 데이터가 NuguClient 로 전달될 수 있도록 합니다.
micInputProvider.delegate = nuguClient
음성인식에 필요한 학습 모델을 설정합니다.
let epdFile = Bundle.main.url(forResource: "skt_epd_model", withExtension: "raw")!
nuguClient.asrAgent.options = ASROptions(endPointing: .client(epdFile: epdFile))
CapabilityFactory::makeCapability 함수로 ASRAgent 를 생성하고 NuguClient 에 추가해 주어야합니다.
auto asr_handler(std::shared_ptr<IASRHandler>(
CapabilityFactory::makeCapability<ASRAgent, IASRHandler>()));
nugu_client->getCapabilityBuilder()
->add(asr_handler.get())
->construct();
음성인식에 필요한 학습 모델을 설정합니다.
asr_handler->setAttribute(ASRAttribute { "/var/lib/nugu/model", "CLIENT", "PARTIAL" });

음성 인식 요청

아리아 발화 또는 NUGU Button 선택 시 Recognize event 를 전달하여 음성인식을 시작할 수 있습니다.
Android
iOS
Linux
speechRecognizerAggregator.startListening(initiator = TAP)
try micInputProvider.start()
asrAgent.startRecognition(initiator: .user)
asr_handler->startRecognition()

음성인식 진행 상태 모니터링

음성인식에 대한 진행 상태를 모니터링 할 수 있습니다.
음성인식에 대한 STT(SpeechToText) 결과가 NotifyResult directive 로 전달됩니다.
Android
iOS
Linux
SpeechRecognizerAggregatorInterface.OnStateChangeListener 를 추가합니다.
val listener = object: SpeechRecognizerAggregatorInterface.OnStateChangeListener {
override fun onStateChanged(state: State) {
...
}
}
speechRecognizerAggregator.addListener(listener)
ASRAgentInterface.OnResultListener 를 추가합니다.
val resultListener = object: ASRAgentInterface.OnResultListener {
fun onPartialResult(result: String, dialogRequestId: String) {
// STT 중간 결과
...
}
fun onCompleteResult(result: String, dialogRequestId: String) {
// STT 최종 결과
...
}
...
}
asrAgent.addOnResultListener(resultListener)
ASRAgentDelegate 를 추가합니다.
class MyASRAgentDelegate: ASRAgentDelegate {
func asrAgentDidChange(state: ASRState) {
...
}
func asrAgentDidReceive(result: ASRResult, dialogRequestId: String) {
// NotifyResult 결과 확인
...
}
}
asrAgent.add(delegate: MyASRAgentDelegate())
음성인식 진행 상태를 모니터링 하려면 IASRListener 를 추가합니다.
class MyASRListener : public IASRListener {
public:
...
void onState(ASRState state, const std::string &dialog_id) override
{
...
}
void onPartial(const std::string &text, const std::string &dialog_id) override
{
// STT 중간 결과
...
}
void onComplete(const std::string &text, const std::string &dialog_id) override
{
// STT 최종 결과
...
}
...
};
auto asr_listener(std::make_shared<MyASRListener>());
CapabilityFactory::makeCapability<ASRAgent, IASRHandler>(asr_listener.get());

음성 인식 중단

사용자가 음성 인식 중단 요청을 StopRecognize event 로 전달할 수 있습니다.
Android
iOS
Linux
speechRecognizerAggregator.stopListening()
asrAgent.stopRecognition()
asr_handler->stopRecognition()

Context

{
"ASR": {
"version": "1.6",
"engine": "{{STRING}}",
"state": "{{STRING}}",
"initiator": "{{STRING}}"
}
}
parameter
type
mandatory
description
engine
string
N
Device 에서 사용하는 음성인식 engine 을 명시 NUGU 음성인식 engine 을 사용하는 경우 "skt" (값을 채우지 않으면 default "skt")
state
string
Y
IDLE, EXPECTING_SPEECH, LISTENING, RECOGNIZING, BUSY State Diagram 참고
initiator
string
N
WAKE_UP_WORD, PRESS_AND_HOLD, TAP, EXPECT_SPEECH, EARSET 마이크 오픈이 어떻게 트리거되었는지 WAKE_UP_WORD - 사용자 발화로 Wakeup PRESS_AND_HOLD - PTT 방식으로 Wakeup TAP - NUGU 버튼 등에 의해서 Wakeup EXPECT_SPEECH - ASR.ExpectSpeech *EARSET - 이어셋 VoiceCommand 등을 통해 Wakeup

Directives

ExpectSpeech

{
"header": {
"namespace": "ASR",
"name": "ExpectSpeech",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"playServiceId": "{{STRING}}",
"domainTypes": ["{{STRING}}"],
"asrContext": {
"task": "{{STRING}}",
"sceneId": "{{STRING}}",
"sceneText": [
"{{STRING}}"
],
"playServiceId" : "playServiceId"
},
"epd": {
"timeoutMilliseconds": {{LONG}},
"silenceIntervalInMilliseconds": {{LONG}},
"maxSpeechDurationMilliseconds": {{LONG}}
},
"listenTimeoutFailBeep": {{BOOLEAN}}
}
}
parameter
type
mandatory
description
playServiceId
string
N
Y : 회신받아야 하는 경우 N : 마이크만 열고 싶은경우 default : N
property
string
N
NORMAL : 일반 발화를 입력으로 받음 DICTATION : dictation 서버로 라우팅하여 처리 필드가 없는 경우 default 값은 NORMAL
domainTypes
array of string
N
ExpectSpeech 의한 발화시에 NLU에서 사용할 domainType 셋팅 정보
asrContext
object
N
-
asrContext.task
string
N
-
asrContext.sceneId
string
N
-
asrContext.sceneText
array of string
N
-
asrContext.playServiceId
string
N
-
epd
object
N
End Point Detection 관련 정보 없으면 device의 default 값을 사용 하위의 3개 파라미터도 optional이기 때문에 존재하는 파라미터만 업데이트하고, 없는 파라미터는 device의 default 값을 사용
epd.timeoutMilliseconds
long
N
Wake up 후 종료까지 대기 시간 (단위: msec) 이 값은 위의 timeoutInMilliseconds와는 다른 epd 전용값
epd.silenceIntervalInMilliseconds
long
N
end point detection 전에 기다리는 묵음 구간 (단위: msec)
epd.maxSpeechDurationMilliseconds
long
N
사용자 발화 최대 녹음 시간 (단위: msec)
listenTimeoutFailBeep
boolean
N
Listening timeout 발생시 beep 재생 여부 (default 값은 true)

NotifyResult

  • 음성 인식 결과 전달
{
"header": {
"namespace": "ASR",
"name": "NotifyResult",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"token": "{{STRING}}",
"result": "{{STRING}}",
"state": "{{STRING}}"
}
}
parameter
type
mandatory
description
token
string
N
Recognize Event에서 사용한 token 값 (어떤 발화에 대한 분석 결과인지 식별하기 위한 용도)
result
string
N
인식 결과를 전송
state
string
Y
PARTIAL : 사용자 발화의 일부분 COMPLETE : 사용자 발화의 전체 문장 NONE : 음성 인식 결과 없음 ERROR : Error 발생 SOS : SOS(Start of Speech) EOS : EOS(End of Speech) FA : Wakeup False Acceptance

CancelRecognize

{
"header": {
"namespace": "ASR",
"name": "CancelRecognize",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"cause": "{{STRING}}"
}
}
parameter
type
mandatory
description
cause
string
Y
WAKEUP_POWER : 다른 wakeup보다 power가 적어서 취소됨

Events

Recognize

{
"header": {
"namespace": "ASR",
"name": "Recognize",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"codec": "{{STRING}}",
"playServiceId": "{{STRING}}",
"domainTypes": ["{{STRING}}"],
"language": "{{STRING}}",
"endpointing": "{{STRING}}",
"encoding": "{{STRING}}",
"wakeup": {
"word": "{{STRING}}",
"boundary": {
"start": {{LONG}},
"end": {{LONG}},
"detection": {{LONG}}
},
"power": {
"noise": {{LONG}},
"speech": {{LONG}}
}
},
"asrContext": {
"task": "{{STRING}}",
"sceneId": "{{STRING}}",
"sceneText": [
"{{STRING}}"
],
"playServiceId" : "playServiceId"
},
"timeout": {
"listen": {{LONG}},
"maxSpeech": {{LONG}},
"response": {{LONG}}
}
}
}
parameter
type
mandatory
description
codec
string
Y
SPEEX
playServiceId
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 playServiceId를 적용
property
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 property를 적용
domainTypes
array of string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 domainTypes를 적용
language
string
N
KOR, ENG, JPN, CHN, ... default 값은 KOR
endpointing
string
Y
CLIENT : 클라이언트 EPD(EndPointDetector) 사용 SERVER : 서버 EPD 사용
encoding
string
N
PARTIAL : 사용자 발화의 일부분 COMPLETE : 사용자 발화의 전체 문장 (default)
wakeup
object
N
서버 EPD 사용시 필수 값. wakeup을 포함해서 서버에 전달하는 경우 포함 wakeup 정보를 전달하는 경우 포함 (전달하는 pcm에 wakeup이 포함되지 않더라도 필요한 경우 전달)
wakeup.word
string
Y
전송하는 stream에 포함된 wakeup word( ex "아리아")
wakeup.boundary
object
N
전송하는 stream에서 wakeup word에 대한 boundary 정보
wakeup.boundary. start
long
Y
wakeup module 에서 얻은 milliseconds 를 sample count 로 변환해서 전송해야 함. sample count for start time
wakeup.boundary. end
long
Y
wakeup module 에서 얻은 milliseconds 를 sample count 로 변환해서 전송해야 함. sample count for end time
wakeup.boundary. detection
long
Y
wakeup module 에서 얻은 milliseconds 를 sample count 로 변환해서 전송해야 함. sample count for detection time
wakeup.boundary. metric
string
N
sample(default) / byte / frame / time 현재 sample 만 지원되며, 추후 byte / frame / time 속성 지원 예정
wakeup.power
object
N
전송하는 stream에 포함된 wakeup pcm의 power값
wakeup.power.noise
float
Y
wakeup pcm의 power중 noise를 의미하는 값 (주로 min값)
wakeup.power.speech
float
Y
wakeup pcm의 power중 speech를 의미하는 값 (주로 max값)
asrContext
object
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 asrContext를 적용
asrContext.task
string
N
-
asrContext.sceneId
string
N
-

ResponseTimeout

  • Recognize Event가 전달되고 사용자 발화도 모두 전달이 완료된 이후 응답을 받지 못한 경우
{
"header": {
"namespace": "ASR",
"name": "ResponseTimeout",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"playServiceId": "{{STRING}}"
}
}
parameter
type
mandatory
description
playServiceId
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 playServiceId를 적용

ListenTimeout

  • Recognize event가 전달되고 사용자 발화가 발화하지 않은 경우
{
"header": {
"namespace": "ASR",
"name": "ListenTimeout",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"playServiceId": "{{STRING}}"
}
}
parameter
type
mandatory
description
playServiceId
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 playServiceId를 적용

StopRecognize

  • Recognize event 취소
{
"header": {
"namespace": "ASR",
"name": "StopRecognize",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"playServiceId": "{{STRING}}"
}
}
parameter
type
mandatory
description
playServiceId
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 playServiceId를 적용

ListenFailed

  • Recognize event 이후 클라이언트에서 에러(마이크를 열지 못하는 등)가 발생한 경우
{
"header": {
"namespace": "ASR",
"name": "ListenFailed",
"messageId": "{{STRING}}",
"dialogRequestId": "{{STRING}}",
"version": "1.6"
},
"payload": {
"playServiceId": "{{STRING}}"
}
}
parameter
type
mandatory
description
playServiceId
string
N
ExpectSpeech에 의한 발화인 경우에만 ExpectSpeech에서 받은 playServiceId를 적용
Last modified 8mo ago