Kakao i Agent::Service Agent Interface::MusicRecognizer

페이지 이동경로

MusicRecognizer

MusicRecognizer 인터페이스는 음악 인식과 관련된 일련의 Message를 제공합니다.

MusicRecognizer 인터페이스
Message 인터페이스 설명
Event Recognize Service Agent에서 발생한 음악 관련 발화를 KVS에 전달
Instruction StopCapture KVS가 사용자의 의도를 파악했거나 발화가 종료되었을 때, 음성 캡처를 중지하도록 지시

Event

Event Message의 호출 방식은 다음과 같습니다.

Event Message 호출 방식
메서드 요청 URL
POST /{{API version}}/events

Recognize

MusicRecognizer.Recognize는 Service Agent에서 발생한 음악 관련 발화를 KVS에 전달하는 Event로, Multipart Message로 통신합니다.
Multipart의 <The First Part>에는 JSON 형식의 객체가 전달되며, <The Second Part>에는 Service Agent와 KVS 사이에 전송되는 오디오 데이터가 스트리밍 방식으로 배치됩니다. stream에는 320 bytes chunk 단위로 10ms의 캡처된 오디오 파일이 첨부됩니다.

Multipart Message
구분 설명
The First Part JSON 형식의 객체
The Second Part 마이크에서 캡처된 바이너리 오디오 파일

Request Syntax

코드예제MusicRecognizer.Recognize Request Syntax_The First Part
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
	"state": [, , ,],
	"event": {
		"header": {
			"type": "MusicRecognizer.Recognize",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"body": {
			"format": "{{STRING}}",
			"mode": "{{STRING}}"
		}
	}
}
코드예제MusicRecognizer.Recognize Request Syntax_The Second Part (Binary Audio 첨부)
Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream

{{BINARY AUDIO ATTACHMENT}}

Request Header

MusicRecognizer.Recognize Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

MusicRecognizer.Recognize Request Body
파라미터 타입 필수 여부 설명
format String 필수 캡처한 오디오의 형식을 식별
ex) RAWPCM/16/16000/1/_/_
mode String 선택 주변 환경 소음에 따른 설정
clean: 주변이 조용함
noisy(기본값): 주변이 시끄러움

Instruction

Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

Instruction Message 호출 방식
메서드 요청 URL
GET /{{API version}}/instructions

StopCapture

MusicRecognizer.StopCapture는 KVS가 사용자의 의도를 파악했거나 명령어 인식을 종료할 때 음성 캡처를 중지하도록 Service Agent로 지시하는 Instruction입니다. Service Agent는 MusicRecognizer.StopCapture Instruction을 받으면, 즉시 마이크를 닫고 사용자 발화를 더 이상 듣지 않습니다.

Request Syntax

코드예제MusicRecognizer.StopCapture Request Syntax
{
	"header": {
		"type": "MusicRecognizer.StopCapture",
		"messageId": "{{STRING}}",
		"dialogRequestId": "{{STRING}}"
	},
	"body": {}
}

Request Header

MusicRecognizer.StopCapture Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의
dialogRequestId String 선택 Recognizer 인터페이스의 특정 Event에 대한 응답(Instruction)을 상호 연관시키는데 사용되는 고유 ID
- 해당 Event 생성 시점에 Service Agent에서 임의의 UUID로 정의

Request Body

Request Body는 없습니다.

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.