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}"
}
}
}
}
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 : 재생 위치 변경 가능 |
파라미터 | 타입 | 필수 여부 | 설명 |
---|---|---|---|
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를 갱신한 시간 |