본문 바로가기 메뉴 바로가기

Kakao i Agent::Service Agent Interface::AudioPlayer

페이지 이동경로

AudioPlayer

AudioPlayer 인터페이스는 오디오 스트림의 재생 진행을 관리하고 모니터링하는 작업과 관련된 일련의 Message를 제공합니다.

표AudioPlayer 인터페이스
Message 인터페이스 설명
Event Started 오디오 스트림의 재생 시작을 알리기 위해 KVS에 전송
NearlyFinished 재생 대기열에서 다음 스트림을 버터링/다운로드할 준비가 되면 전송
ProgressReport 재생 지시문에 progressReport가 있는 경우 전송
ProgressReportIntervalElapsed 재생 지시문에 progressReportIntervalInMiliSeconds로 주기값이 설정되어 있고 그 값이 0을 초과할 때 전송
Finished 오디오 스트림의 재생을 완료 후 전송
- 재생이 중지되거나 스트림 간 이동인 경우에는 전달되지 않음
Failed 오디오 스트림의 재생 시도 중 오류가 발생했을 때 KVS에 전송
Stopped 다음 Instruction 중 하나를 수신하고 오디오 스트림의 재생을 중지했을 때 전송
- AudioPlayer.Stop
- REPLACE_ALL의 action이 포함된 AudioPlayer.Play
Paused 우선순위가 높은 입력/출력을 수용하기 위해, 콘텐츠 채널에서 오디오 스트림의 재생을 일시 중지했을 때 전송
Resumed AudioPlayer.Paused Event 수신 이후 재생을 다시 시작 시 전송
Instruction Play 오디오 스트림의 재생을 시작하도록 지시
Stop 오디오 스트림의 재생을 중지하도록 지시
State PlayState 현재 재생 중이거나 가장 마지막 재생 아이템의 정보를 KVS에 전달
ContentState 재생 중이거나 마지막에 재생된 아이템 중, body.playChannel이 content인 아이템에 대한 정보를 KVS에 전달

Event

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

표Event Message 호출 방식
메서드 요청 URL
POST /{API version}/events
안내
AudioPlayer 인터페이스의 각 Event에 포함된 body.token의 경우, 연관된 AudioPlayer.Play Instruction의 token을 그대로 재전송합니다.

Started

AudioPlayer.Started는 Service Agent가 오디오 스트림의 재생 시작을 알리기 위해 KVS에 전송하는 Event입니다.

Request Syntax

코드예제AudioPlayer.Started Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Started",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.Started Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Started Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

NearlyFinished

AudioPlayer.NearlyFinished는 Service Agent가 재생 대기열에서 다음 스트림을 버퍼링 또는 다운로드할 준비가 되면 KVS로 전송하는 Event입니다. Service Agent는 AudioPlayer.Play Instruction이 끝나기 1분 전에 해당 Event를 KVS로 전송합니다. Service Agent는 현재 재생중인 스트림에 대한 Started Event 이후에만 해당 Event가 전송되도록 해야합니다.

  • 원칙은 “Finished Event를 전송하기 전에 NearlyFinished Event를 전송한다”입니다.
  • Play Instruction 중에 body.duration이 20000(20초) 이상인 경우, 클라이언트는 Play가 끝나기 20초 전에 해당 Event를 전송합니다.
  • Play Instruction 중에 body.duration이 20000(20초) 미만인 경우, 클라이언트는 Play하고 1초 후에 해당 Event를 전송합니다.
  • Play Instruction 중에 body.duration 이 1000(1초) 미만인 경우, NearlyFinished Event를 전송하고 Finished Event를 전송합니다.
  • Duration 정보는 서버로부터 전달받은 duration 정보와 Player가 측정한 duration 중 서버 전달 값을 우선으로 합니다.
    • 단, duration이 0 이거나 음수일 경우에는 Player 측정값을 사용합니다.

Request Syntax

코드예제AudioPlayer.NearlyFinished Request Syntax 

{
        "event": {
                "header": {
                        "type": "AudioPlayer.NearlyFinished",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.NearlyFinished Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.NearlyFinished Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

ProgressReport

AudioPlayer.ProgressReport는 재생 지시문에 progressReport가 있는 경우, Service Agent가 KVS로 전송하는 Event입니다.

안내
AudioPlayer.ProgressReport는 offset과 상관없이 실제 자원이 재생된 누적시간을 계산해 해당 시간을 지날 때 Event로 전송해야 합니다.

Request Syntax

코드예제AudioPlayer.ProgressReport Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.ProgressReport",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.ProgressReport Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.ProgressReport Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

ProgressReportIntervalElapsed

AudioPlayer.ProgressReportIntervalElapsed는 재생 지시문에 progressReportIntervalInMiliSeconds로 주기값이 설정되어 있고 그 값이 0을 초과하는 경우에 Service Agent가 KVS로 전송하는 Event입니다.
해당 Event는 아이템의 트랙 시작(audioItem.offset부터가 아님)부터 재생이 종료(명시적 종료, 완료, 에러)되기 전까지 주기값 간격으로 전송하며, offset은 트랙의 실제 재생 위치를 나타냅니다. 예를 들어, audioItem.offset이 10,000ms이고, progressReportIntervalInMiliSeconds이 30,000ms이라면, 첫 Event는 트랙의 시작 지점인 0에서부터 30,000ms 위치인 재생 이후 20,000ms 시점에서 전송되야 합니다.

Request Syntax

코드예제AudioPlayer.ProgressReportIntervalElapsed Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.ProgressReportIntervalElapsed",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.ProgressReportIntervalElapsed Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.ProgressReportIntervalElapsed Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

Finished

AudioPlayer.Finished는 Service Agent가 오디오 스트림의 재생을 완료했을 때 KVS로 전송하는 Event입니다.
재생이 중지되거나 스트림 간 이동인 경우에는 해당 Event를 전송하지 않습니다.

Request Syntax

코드예제AudioPlayer.Finished Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Finished",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}",
                        "buffering": {LONG}
                }
        }
}

Request Header

표AudioPlayer.Finished Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Finished Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달
buffering Long 필수 Audio Player의 버퍼링 시간
- ExoPlayer의 STATE_BUFFERING 상태 시간

Failed

AudioPlayer.Failed는 Service Agent에서 오디오 스트림의 재생 시도 중 오류가 발생했을 때 KVS로 전송하는 Event입니다.

안내
스트림이 재생되고 다음 스트림이 버퍼링되지 않는 경우, currentPlayback의 토큰이 body의 토큰과 다를 수 있습니다.

Request Syntax

코드예제AudioPlayer.Failed Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Failed",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}",
                        "error": {
                                "type": "{STRING}",
                                "message": "{STRING}"
                        }
                }
        }
}

Request Header

표AudioPlayer.Failed Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Failed Request Body
필드 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction 으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 Event가 발생한 사유를 영문 텍스트 형식으로 전달
Object 필수 에러 정보 전달
type String 필수 INTERNAL_ERROR만 사용
message String 필수 예외(Exception) 발생 내용 전달

Stopped

AudioPlayer.Stopped는 Service Agent가 다음 Instruction 중 하나를 수신하고 오디오 스트림의 재생을 중지했을 때 KVS에 전송하는 Event입니다.

  • AudioPlayer.Stop 또는
  • REPLACE_ALL의 action이 포함된 AudioPlayer.Play
안내
AudioPlayer.Stopped는 위에 나열된 지시문 중 하나가 수신된 결과 스트림이 종료된 경우에만 전송됩니다.
이는 일반적으로 사용자 조치의 결과이고, 스트림 재생이 끝나면 Event를 전송하지 않아야 합니다.

Request Syntax

코드예제AudioPlayer.Stopped Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Stopped",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.Stopped Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Stopped Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

Paused

AudioPlayer.Paused는 Service Agent가 우선순위가 높은 입력/출력을 수용하기 위해 콘텐츠 채널에서 오디오 스트림의 재생을 일시 중지했을 때 KVS에 전송하는 Event입니다.

안내
우선순위가 지정된 작업이 완료되면 재생을 다시 시작해야 하며, Service Agent는 AudioPlayer.Resumed Event를 전송해야 합니다.

Request Syntax

코드예제AudioPlayer.Paused Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Paused",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.Paused Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Paused Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

Resumed

AudioPlayer.Resumed는 Service Agent가 AudioPlayer.Paused Event 이후에 재생을 다시 시작했을 때 KVS에 전송하는 Event입니다.

Request Syntax

코드예제AudioPlayer.Resumed Request Syntax 
{
        "event": {
                "header": {
                        "type": "AudioPlayer.Resumed",
                        "messageId": "{STRING}"
                },
                "body": {
                        "token": "{STRING}",
                        "offset": {LONG},
                        "cause": "{STRING}"
                }
        }
}

Request Header

표AudioPlayer.Resumed Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름
messageId String 필수 특정 메시지를 나타내는 고유 ID
- 해당 메시지의 생성 주체가 임의의 UUID로 정의

Request Body

표AudioPlayer.Resumed Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cause String 필수 해당 Event가 발생한 사유를 영문 텍스트 형식으로 전달

Instruction

Event Message의 응답으로 Instruction Message를 수신할 수도 있습니다. Instruction Message 수신을 위한 Down Channel 생성 방식은 다음과 같습니다.

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

Play

KVS는 음원 재생을 지시하기 위해 Service Agent로 AudioPlayer.Play Instruction을 전송하며, 이때 재생 관련 정보와 제어 정보(Play 채널, 제어 가능 목록)를 함께 전달합니다. 제어 정보에는 제어 가능한 콘텐츠 여부(playChannel)와 제어 가능한 명령어(controllable)가 포함됩니다.

안내
음성이 아닌 버튼을 사용한 오디오 재생 제어를 사용하기 위해서는 playChannel 파라미터를 content로 설정해야 합니다. 버튼을 사용한 오디오 재생 제어 시나리오는 오디오 재생 제어를 참고하시기 바랍니다.

Request Syntax

코드예제AudioPlayer.Play Request Syntax_The First Part 
{
        "instruction": {
                "header": {
                        "type": "AudioPlayer.Play",
                        "messageId": "{STRING}",
                        "dialogRequestId": "{STRING}"
                },
                "body": {
                        "action": "{STRING}",
                        "mood": "{STRING}",
                        "audioItem": {
                                "id": "{STRING}",
                                "url": "{STRING}",
                                "ttl": {LONG},
                                "createdAt": {LONG},
                                "format": "{STRING}",
                                "token": "{STRING}",
                                "offset": {LONG},
                                "cunulativeOffset": {LONG},
                                "playInBackground": "{STRING}",
                                "progressReport": {LONG},
                                "progressReportIntervalInMiliseconds": {LONG},
                                "source": "{STRING}",
                                "duration": {LONG},
                                "audioType": "{STRING}",
                                "gain": {DOUBLE},
                                "cacheKey": "{STRING}",
                                "contentMeta": {
                                        "image": "{STRING}",
                                        "title": "{STRING}",
                                        "subtitle": "{STRING}"
                                },
                                "originUrl": "{STRING}",
                                "extraMeta": {
                                        "originChid": "{STRING}",
                                        "originEpid": "{STRING}"
                                }
                        },
                        "playChannel": "{STRING}",
                        "controllable": "[{STRING}]"
                },
                "meta": {
                        "tts": {
                                "engine": "{STRING}"
                        }
                }
        }
}
코드예제AudioPlayer.Play 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

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

Request Body

표AudioPlayer.Play Request Body
파라미터 타입 필수 여부 설명
action String 필수 다음의 action 목록 참고
REPLACE_ALL: Synthesizer.Speak Instruction의 스트림 재생을 즉시 시작하고 현재 스트림과 대기열에 포함된 스트림 변경
- 스트림이 재생 중이고 action이 REPLACE_ALL인 AudioPlayer.Play Instruction을 받으면, Service Agent는 Synthesizer.SpeakFinished Event를 전송
ENQUEUE: 스트림을 현재 대기열 끝에 추가
REPLACE_ENQUEUED: 대기열에 있는 모든 스트림 변경
- 현재 재생 중인 스트림에는 영향 없음
mood String 선택 KVS가 말할 때의 기분을 색상으로 표현
- 다른 색상 필요 시 클라이언트가 구현 가능
neutral(기본값): 중립(흰색)
joy: 기쁨(노란색)
sadness: 슬픔(파란색)
anger: 화남(빨간색)
surprise: 놀람(보라색)
exciting: 신남(하늘색 + 보라색)
Object 필수 audioItem의 키/값 쌍 포함
id String 필수 audioItem 식별
url String 필수 오디오 내용의 위치를 식별(http/https)
ttl Long 필수 audioItem이 유효한 기간을 나타냄
- 리모콘이나 물리적인 Prev, Pause, Next 버튼과 연동되어 다시 복구할 아이템인지 여부 판단
createdAt Long 필수 audioItem이 서버에서 발행된 시간을 나타냄
- audioItem.ttl과 함께 아이템이 언제까지 유효한지 계산하는 데 사용
format String 선택 AudioPlayer.Play Instruction에 연결된 바이너리 오디오 첨부 파일이 있으면 AUDIO_MPEG format 포함
- 연결된 오디오가 스트림인 경우 format은 포함되지 않음
token String 필수 현재의 스트림을 나타내는 불투명한 토큰
offset Long 선택 해당 위치부터 재생을 시작
- 0이 오면 처음부터 시작(ms 단위)
cumulativeOffset Long 선택 정산에 사용되는 총 재생 누적시간
playInBackground String 선택 오디오 채널이 백그라운드 상태에서 재생 여부
- 다음 값 중 하나를 선택
allow: 허용
disallow:허용하지 않음
progressReport Long 선택 AudioPlayer.ProgressReport Event를 KVS로 전송할 누적 재생 지점(ms 단위)을 지정
- AudioPlayer.ProgressReport Event는 offset과 상관없이 실제 자원이 재생된 누적 시간을 계산해 해당 시간을 지날 때 Event로 전송되도록 해야 하며, 한 번만 보내야 함
- 0일 경우 보내지 않음
progressReportIntervalInMiliseconds Long 선택 AudioPlayer.ProgressReportIntervalElapsed Event를 KVS로 전송할 주기(ms 단위)를 지정
- 0일 경우 보내지 않음
source String 선택 정산로그 전송을 위한 source 출처
duration Long 선택 재생시간(ms 단위)
audioType String 필수 오디오의 주요 콘텐츠 유형을 표시
- 다음의 값 중 하나를 선택
music: 음악
speak: 음성
gain Float 선택 상대적인 볼륨 조절
- 기존 볼륨에 대한 weight 값을 제공하는 파라미터로, 볼륨에는 특정 기준값이 적용되지 않아 모든 볼륨을 동일하게 맞출 수 없기 때문에 모든 볼륨에 대한 weight 값을 추가적으로 제공
ex) gain을 -1로 설정 시: 볼륨은 0이며, gain을 1로 설정 시 현재 볼륨에서 2배가 됨
cacheKey String 선택 캐시 키
Object 선택 meta 정보들
image String 선택 이미지 관련 정보
title String 선택 title 정보
subtitle String 선택 subtitle 정보
originUrl String 선택 audioItem의 URL 파라미터의 원본 소스가 존재하는 경우, 해당 원본 소스의 URL을 가리킴
extraMeta Object 선택 audioItem의 원본 소스에 대한 메타 정보를 담을 필드로 임의의 string type의 key와 value로 구성될 수 있음
- 클라이언트에서 미리 사용을 약속하지 않은 경우, 이 필드는 무시해도 됨
playChannel String 선택 채널 유형
dialog:음원의 채널 타입
- TTS 등 대화 성격을 띠는 오디어 아이템으로 Play 채널이지만 Speak 채널처럼 동작
ex) 운세, 어학
content:음원의 재생 제어가 필요한 유형
- 버튼 재생 제어 포함
ex) 음악, 팟캐스트, 뉴스
controllable String[] 선택 playChannel 타입이 content인 경우 전달되는 재생 제어 명령어
PLAY: 재생 가능
STOP:정지 가능
PAUSE:일시 정지 가능
RESUME: 다시 재생 가능
NEXT: 다음 재생 가능
PREV: 이전 재생 가능
SEEK: 재생 위치 변경 가능
표AudioPlayer.Play Meta Parameters
파라미터 타입 필수 여부 설명
Object 필수 body.audioItem.url이 tts:// 포맷일 때 음성 합성을 위해 사용되는 정보
engine String 필수 음성 합성 엔진 종류
plain:기본 음성합성 엔진
deep: 딥보이스 음성 합성 엔진

Stop

AudioPlayer.Stop은 KVS가 Service Agent에 오디오 스트림의 재생을 중지하도록 지시하는 Instruction입니다.

Request Syntax

코드예제AudioPlayer.Stop Request Syntax 
{
  "instruction": {
    "header": {
      "type": "AudioPlayer.Stop",
      "messageId": "{STRING}",
      "dialogRequestId": "{STRING}"
    },
    "body": {}
  }
}

Request Header

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

Request Body

Request Body는 없습니다.

SuggestPlaylist

AudioPlayer.SuggestPlaylist는 KVS가 AI Service Agent에게 오디오 재생을 위한 음원 목록을 전달하는 Instruction입니다. AudioPlayer.Play Instruction과 함께 전달되거나 단독으로 전달될 수 있습니다. Request Body의 audioItem으로 전달되는 URL은 ttl이 존재합니다. AudioPlayer.SuggestPlaylist 전달 시점에 음원 목록에 추가된 이후, 시간이 경과하여 ttl 시간이 만료된 경우에는 더 이상 재생이 되지 않을 수 있습니다.

주의
AudioPlayer.SuggestPlaylist 인터페이스는 1.1 버전부터 지원하고 있습니다.

  • 지원하는 버전에 대한 자세한 설명은 Capability를 참고하시기 바랍니다.

Request Syntax

코드예제AudioPlayer.SuggestPlaylist Request Syntax 

{
        "instruction": {
                "header": {
                        "type": "AudioPlayer.SuggestPlaylist",
                        "messageId": "{STRING}",
                        "dialogRequestId": "{STRING}"
                },
                "body": {
                        "audioItems": [
                                {
                                        "id": "{STRING}",
                                        "url": "{STRING}",
                                        "ttl": {LONG},
                                        "createdAt": {LONG},
                                        "format": "{STRING}",
                                        "token": "{STRING}",
                                        "offset": {LONG},
                                        "cunulativeOffset": {LONG},
                                        "playInBackground": "{STRING}",
                                        "progressReport": {LONG},
                                        "progressReportIntervalInMiliseconds": {LONG},
                                        "source": "{STRING}",
                                        "duration": {LONG},
                                        "audioType": "{STRING}",
                                        "gain": {DOUBLE},
                                        "cacheKey": "{STRING}",
                                        "contentMeta": {
                                                "image": "{STRING}",
                                                "title": "{STRING}",
                                                "subtitle": "{STRING}"
                                        }
                                }
                        ],
                        "playChannel": "{STRING}"
                }
        }
}

Request Header

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

Request Body

표AudioPlayer.SuggestPlaylist Request Body
파라미터 타입 필수 여부 설명
audioItem Array 필수 audioItem을 재생 순서대로 나열한 목록
- AudioPlayer.Play Request Body의 audioItem 구성과 동일
playChannel String 선택 채널 유형
dialog: 음원의 채널 타입
- TTS 등 대화 성격을 띠는 오디어 아이템으로 Play 채널이지만 Speak 채널처럼 동작
ex) 운세, 어학
content: 음원의 재생 제어가 필요한 유형
- 버튼 재생 제어 포함
ex) 음악, 팟캐스트, 뉴스

State

State Message는 모든 Event Message를 전송하는 요청(Request)에 항상 포함되어야 합니다.

PlayState

AudioPlayer.PlayState는 가장 최근에 발생하거나 현재 재생 중인 아이템에 대한 정보를 전달하는 State입니다. 현재 재생되고 있는 아이템이 없으면, 가장 마지막에 재생된 아이템 정보를 전달합니다.

안내
이 값은 KVS에서 사용자의 Context를 추적할 때 사용됩니다.

Request Syntax

코드예제AudioPlayer.PlayState Request Syntax 
{
        "header": {
                "type": "AudioPlayer.PlayState"
        },
        "body": {
                "token": "{STRING}",
                "offset": {LONG},
                "cumulativeOffset": {LONG},
                "state": "{STRING}",
                "createdAt": {LONG},
                "ttl": {LONG},
                "stateUpdateAt": {LONG}
        }
}

Request Header

표AudioPlayer.PlayState Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름

Request Body

표AudioPlayer.PlayState Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond로 표현
cummulativeOffset Long 필수 정산에 사용되는 총 재생 누적 시간
state String 필수 Audio Player의 상세 상태
IDLE: 재생 중 음원이 없고, 대기 중인 항목이 없는 상태
PLAYING: 스트림이 작동 중인 상태
PAUSED: 스트림이 멈춘 상태
BUFFER_UNDERRUN: 버퍼가 돌아가지 않는 상태
FINISHED: 스트림이 끝난 상태
STOPPED: 스트림이 방해된 상태
createdAt Long 필수 AudioItem URL의 생성 시간
ttl Long 필수 AudioItem URL의 유효 시간
stateUpdatedAt Long 필수 Service Agent가 State를 갱신한 시간

ContentState

AudioPlayer.ContentState는 가장 최근에 발생하거나 현재 재생 중인 Play 아이템 중 body.playChannel이 content인 아이템에 대한 정보를 전달하는 State입니다. 현재 재생되고 있는 아이템이 없으면, 가장 마지막에 재생된 아이템 정보를 전달합니다.

안내
이 값은 서버에서 사용자의 Context를 추적하여 Prev, Pause, Next 버튼의 동작을 처리하기 위해 사용됩니다.

Request Syntax

코드예제AudioPlayer.ContentState Request Syntax 
{
        "header": {
                "type": "AudioPlayer.ContentState"
        },
        "body": {
                "token": "{STRING}",
                "offset": {LONG},
                "cumulativeOffset": {LONG},
                "state": "{STRING}",
                "createdAt": {LONG},
                "ttl": {LONG},
                "stateUpdateAt": {LONG}
        }
}

Request Header

표AudioPlayer.ContentState Request Header
파라미터 타입 필수 여부 설명
type String 필수 해당 인터페이스 이름

Request Body

표AudioPlayer.ContentState Request Body
파라미터 타입 필수 여부 설명
token String 필수 AudioPlayer.Play Instruction 으로부터 전달받은 토큰을 사용
offset Long 필수 audioItem의 재생 위치를 millisecond 로 표현
cummulativeOffset Long 필수 정산에 사용되는 총 재생 누적 시간
state String 필수 Audio Player의 상세 상태
IDLE: 재생 중 음원이 없고, 대기 중인 항목이 없는 상태
PLAYING: 스트림이 작동 중인 상태
PAUSED: 스트림이 멈춘 상태
BUFFER_UNDERRUN: 버퍼가 돌아가지 않는 상태
FINISHED: 스트림이 끝난 상태
STOPPED: 스트림이 방해된 상태
createdAt Long 필수 AudioItem URL의 생성 시간
ttl Long 필수 AudioItem URL의 유효 시간
stateUpdatedAt Long 필수 Service Agent가 State를 갱신한 시간
이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

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