Synthesizer
Synthesizer 인터페이스는 합성된 음성의 재생과 관련된 일련의 Message를 제공합니다.
표Synthesizer 인터페이스Message | 인터페이스 | 설명 |
---|---|---|
Event | SpeakReceived | Speak Instruction을 전달받자마자 KVS에 전송 |
SpeakStarted | Speak Instruction을 처리하고 합성된 음성의 재생을 시작한 후에 KVS에 전송 | |
SpeakFinished | Speak Instruction을 처리하고 합성된 음성의 재생을 마친 후에 KVS에 전송 | |
SpeakStopped | Speak Instruction을 처리하고 합성된 음성의 재생이 완료되기 전에 중단한 경우 KVS에 전송 | |
TextToSpeech | 음성 변환이 필요한 텍스트를 KVS에 전달 - KVS는 Speak Instruction으로 응답 |
|
Instruction | Speak | 음성 응답이 필요할 때마다 Service Agent에 전송 - 대부분의 경우 Recognizer Event와 같은 사용자 요청에 대한 응답이지만, Speak Instruction을 통해 필요한 조치를 취할 수도 있음 |
Stop | 현재 재생 중인 음성 재생을 중지하도록 Service Agent에 지시 - Service Agent는 재생 중지를 수행 후 KVS로 Stopped Event를 전송 |
|
State | SpeakState | 가장 마지막에 발생한 아이템 정보를 KVS에 전달 |
Event
Event Message의 호출 방식은 다음과 같습니다.
표Event Message 호출 방식메서드 | 요청 URL |
---|---|
POST | /{API version}/events |
SpeakReceived
Synthesizer.SpeakReceived는 Service Agent가 Synthesizer.Speak Instruction을 전송받자마자 KVS에 전송하는 Event입니다. 해당 Event는 필수적으로 전송되지 않으며, Service Agent의 필요 여부에 따라 선택적으로 전송됩니다.
Request Syntax
코드예제Synthesizer.SpeakReceived Request Syntax{
"event": {
"header": {
"type": "Synthesizer.SpeakReceived",
"messageId": "{STRING}"
},
"body": {
"token": "{STRING}"
}
}
}
Request Header
표Synthesizer.SpeakReceived Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
Request Body
표Synthesizer.SpeakReceived Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
token | String | 필수 |
Synthesizer.Speak Instruction으로부터 전달받은 토큰 |
SpeakStarted
Synthesizer.SpeakStarted는 Service Agent가 Synthesizer.Speak Instruction을 처리하고 합성된 음성의 재생을 시작한 후에 KVS에 전송하는 Event입니다.
Request Syntax
코드예제Synthesizer.SpeakStarted Request Syntax
{
"event": {
"header": {
"type": "Synthesizer.SpeakStarted",
"messageId": "{STRING}"
},
"body": {
"token": "{STRING}"
}
}
}
Request Header
표Synthesizer.SpeakStarted Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
Request Body
표Synthesizer.SpeakStarted Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
token | String | 필수 |
Synthesizer.Speak Instruction으로부터 전달받은 토큰 |
SpeakFinished
Synthesizer.SpeakFinished는 Service Agent가 Synthesizer.Speak Instruction을 처리하고 합성된 음성 재생을 완료 후 KVS로 전송하는 Event입니다.
Request Syntax
코드예제Synthesizer.SpeakFinished Request Syntax{
"event": {
"header": {
"type": "Synthesizer.SpeakFinished",
"messageId": "{STRING}"
},
"body": {
"token": "{STRING}"
}
}
}
Request Header
표Synthesizer.SpeakFinished Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
Request Body
표Synthesizer.SpeakFinished Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
token | String | 필수 |
Synthesizer.Speak Instruction으로부터 전달받은 토큰 |
SpeakStopped
Synthesizer.SpeakStopped는 Service Agent가 Synthesizer.Speak Instruction을 처리하고 합성된 음성 재생이 완료되기 전에 중단되었을 경우 KVS로 전송하는 Event입니다.
Request Syntax
코드예제Synthesizer.SpeakStopped Request Syntax
{
"event": {
"header": {
"type": "Synthesizer.SpeakStopped",
"messageId": "{STRING}"
},
"body": {
"token": "{STRING}"
}
}
}
Request Header
표Synthesizer.SpeakStopped Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
Request Body
표Synthesizer.SpeakStopped Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
token | String | 필수 |
Synthesizer.Speak Instruction으로부터 전달받은 토큰 |
TextToSpeech
Synthesizer.TextToSpeech는 Service Agent가 음성 변환이 필요한 텍스트를 KVS에 전달하는 Event입니다. KVS는 이에 대한 응답으로 Synthesizer.Speak Instruction을 전송합니다.
Request Syntax
코드예제Synthesizer.TextToSpeech Request Syntax
{
"event": {
"header": {
"type": "Synthesizer.TextToSpeech",
"messageId": "{STRING}"
},
"body": {
"text": "{STRING}"
}
}
}
Request Header
표Synthesizer.TextToSpeech Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
Request Body
표Synthesizer.TextToSpeech Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
text | String | 필수 |
음성 변환이 필요한 텍스트 |
Instruction
Event Message의 응답으로 Instruction Message를 수신할 수도 있습니다. Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.
표Instruction Message 호출 방식메서드 | 요청 URL |
---|---|
GET | /{API version}/instructions |
Speak
Synthesizer.Speak는 MusicRecognizer.Recognize Event와 같이 Service Agent의 요청에 대해 음성 응답이 필요할 경우에 KVS가 Service Agent로 전송하는 Instruction입니다. 음성 응답 외에 Synthesizer.Speak Instruction을 통해 필요한 조치를 취할 수도 있습니다. 예를 들어, 사용자가 타이머 설정을 요청하면 Service Agent는 타이머가 성공적으로 설정되었음을 알려주는 Synthesizer.Speak Instruction을 수신합니다.
코드예제Synthesizer.Speak Request Syntax_The First Part
{
"instruction": {
"header": {
"type": "Synthesizer.Speak",
"messageId": "{STRING}",
"dialogRequestId": "{STRING}"
},
"body": {
"url": "{STRING}",
"format": "{STRING}",
"token": "{STRING}",
"mood": "{STRING}",
"hasWuw": {BOOLEAN},
"text": "{STRING}",
"action": "{STRING}"
}
}
}
코드예제Synthesizer.Speak Request Syntax_The Second Part(Binary Audio 첨부)
Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream
Content-ID: {Audio Item CID}
{BINARY AUDIO ATTACHMENT}
Request Header
표Synthesizer.Speak Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
dialogRequestId | String | 선택 |
Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID - 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의 |
Request Body
표Synthesizer.Speak Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
url | String | 필수 |
audio content의 유니크한 식별자로 URL은 항상 접두사 cid 뒤에 위치 ex) cid: {URL} |
format | String | 필수 |
반환된 오디오 포맷 |
token | String | 필수 |
현재 TTS(Text-To-Speech) 객체를 나타내는 토큰 |
mood | String | 선택 |
KVS가 말할 때의 기분을 색상으로 표현 - 아래 색상 이외의 색상이 필요한 경우, 클라이언트가 자유롭게 구현 가능 |
neutral (기본값): 중립(흰색) |
|||
joy : 기쁨(노란색) |
|||
sadness :슬픔(파란색) |
|||
anger : 화남(빨간색) |
|||
surprise : 놀람(보라색) |
|||
exciting : 신남(하늘색 + 보라색) |
|||
hasWuw | Boolean | 선택 |
TTS(Text-To-Speech) 내의 Wake-up Word 포함 여부 |
false (기본값): 중립(흰색)- Wake-up Word 포함 시 웨이크업 오동작을 예방 |
|||
text | String | 선택 |
합성 텍스트 |
action | String | 선택 |
다음의 action에서 하나를 선택 |
REPLACE_ALL (기본값): Synthesizer.Speak Instruction의 스트림 재생을 즉시 시작하고 현재 스트림과 대기열에 포함된 스트림 변경- 스트림이 재생 중이고 action이 REPLACE_ALL인 AudioPlayer.Play Instruction을 받으면 KVS에 SpeakFinished Event를 보내야 함 |
|||
ENQUEUE : 스트림을 현재 대기열 끝에 추가 |
|||
REPLACE_ENQUEUED : 대기열에 있는 모든 스트림을 변경- 현재 재생 중인 스트림에는 영향을 주지 않음 |
|||
outputSpeaker | String | 선택 |
다음의 값 중, 음성 답변을 재생할 출력 스피커를 명시 - 미지정 시, Service Agent의 출력 정책에 따름 |
SPEAKER (기본값): 본체 |
|||
MiniLink/0001 : 시리얼 번호가 0001인 MiniLink |
Stop
Synthesizer.Stop은 현재 재생 중인 음성 재생을 중지해야 할 때 KVS에서 Service Agent로 전송하는 Instruction입니다. Service Agent는 재생 중지를 수행한 후에 KVS로 Stopped Event를 전송합니다.
주의
Synthesizer.Stop 인터페이스는 1.1 버전부터 지원하고 있습니다.
- 지원하는 버전에 대한 자세한 설명은 Capability를 참고하시기 바랍니다.
Request Syntax
코드예제Synthesizer.Stop Request Syntax
{
"instruction": {
"header": {
"type": "Synthesizer.Stop",
"messageId": "{STRING}",
"dialogRequestId": "{STRING}"
},
"body": {}
}
}
Request Header
표Synthesizer.Stop Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
messageId | String | 필수 |
특정 메시지를 나타내는 고유 ID - 해당 메시지의 생성 주체가 임의의 UUID로 정의 |
dialogRequestId | String | 선택 |
Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID - 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의 |
Request Body
Request Body는 없습니다.
State
State Message는 모든 Event Message를 전송하는 요청(Request)에 항상 포함되어야 합니다.
SpeakState
Synthesizer.SpeakState는 가장 최근에 발생한 아이템에 대한 정보를 전달하는 State입니다. 현재 재생되고 있는 아이템이 없을 경우에는 가장 마지막에 재생된 아이템 정보가 전달됩니다.
안내
이 값은 KVS에서 사용자의 Context를 추적할 때 사용됩니다.
Request Syntax
코드예제Synthesizer.SpeakState Request Syntax
{
"header": {
"type": "Synthesizer.SpeakState"
},
"body": {
"token": "{STRING}",
"state": "{STRING}"
}
}
Request Header
표Synthesizer.SpeakState Request Header파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
type | String | 필수 |
해당 인터페이스 이름 |
Request Body
표Synthesizer.SpeakState Request Body파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
token | String | 필수 |
Synthesizer.Speak Instruction으로부터 전달받은 토큰을 사용 |
state | String | 필수 |
상태 값 |
PLAYING : 스트림이 작동 중인 상태 |
|||
FINISHED : 스트림이 끝까지 재생 완료된 경우 |
|||
STOPPED : 스트림이 재생 완료되지 않고 멈춘 경우 |