Kakao i Agent::Service Agent Interface::Synthesizer

페이지 이동경로

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: 스트림이 재생 완료되지 않고 멈춘 경우
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.