ASR
음성인식 결과를 Play 로 전달하기 위한 규격
최신 버전은 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 필드 추가 |
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))
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" });
Android
iOS
Linux
speechRecognizerAggregator.startListening(initiator = TAP)
try micInputProvider.start()
asrAgent.startRecognition(initiator: .user)
asr_handler->startRecognition()
음성인식에 대한 진행 상태를 모니터링 할 수 있습니다.
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())
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());
Android
iOS
Linux
speechRecognizerAggregator.stopListening()
asrAgent.stopRecognition()
asr_handler->stopRecognition()
{
"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 | |
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 |
{
"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) |
- 음성 인식 결과 전달
{
"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 |
{
"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가 적어서 취소됨 |
{
"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 | - |
asrContext.sceneText | array of string | N | - |
asrContext.playServiceId | string | N | - |
timeout | object | N | Server EPD 사용시 필수 값. |
timeout.listen | long | Y | SOS 를 기다리는 시간 (milliseconds) |
timeout.maxSpeech | long | Y | SOS이후 EOS를 기다리는 시간 (milliseconds) |
timeout.response | long | Y | EOS 이후 응답을 기다리는 시간 (milliseconds) |
- 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를 적용 |
- 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를 적용 |
- 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를 적용 |
- 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 1yr ago