AudioPlayer

Play 에서 전달하는 음원을 재생하기 위한 규격

Version

최신 버전은 1.7 입니다.

Version Date Description
1.0 2019.11.13 규격 추가
1.1 2020.03.03 lyric, favorite, repeat, shuffle, template.settings 관련 directive/event 추가
AudioPlayer.Template1 에 lyrics, settings, badge 관련 필드 추가
AudioPlayer.Play 에 cacheKey 필드 추가
AudioPlayer.UpdateMetadata directive 추가
AudioPlayer.Template1의 content.imageUrl을 Mandatory로 수정
1.2 2020.03.12 Request{Play/Resume/Next/Previous/Pause/Stop}
Command Directive Request{Play/Resume/Next/Previous/Pause/Stop}CommandIssued Event 추가.
1.3 2020.06.05 PlaybackStopped event 에 reason 필드 추가.
RequestCommandFailed event 추가.
1.4 2020.08.12 Context 에 playServiceId 추가
1.5 2020.12.09 PlaybackStopped event 의 reason 필드 값에 대한 조건 수정
1.6 2021.03.05 AudioPlayer.Template1 의 lyrics 에 showButton 필드 추가
AudioPlayer.Template2 에 lyrics 필드 추가
AudioPlayer.Template2 에 subtitle1 필드 추가
1.7 2023.04.05 context 에 playlistToken 필드 추가
UpdateMetadata 에 playlist 필드 추가

State Diagram

SDK Interface

AudioPlayerAgent 사용

AudioPlayer interface 규격에 따른 디바이스의 동작 제어는 AudioPlayerAgent 가 처리합니다.

  • Android
  • iOS
  • Linux

NuguAndroidClient instance 를 통해 AudioPlayerAgent instance 에 접근할 수 있습니다.

복사성공!
1
val audioPlayerAgent = nuguAndroidClient.audioPlayerAgent

NuguClient instance 를 통해 AudioPlayerAgent instance 에 접근할 수 있습니다.

복사성공!
1
let audioPlayerAgent = nuguClient.audioPlayerAgent

CapabilityFactory::makeCapability 함수로 AudioPlayerAgent 를 생성하고 NuguClient 에 추가해 주어야합니다.

복사성공!
1
2
3
4
5
6
auto audio_player_handler(std::shared_ptr<IAudioPlayerHandler>(
        CapabilityFactory::makeCapability<AudioPlayerAgent, IAudioPlayerHandler>()));

nugu_client->getCapabilityBuilder()
    ->add(audio_player_handler.get())
    ->construct();

재생 상태 모니터링

Play directive 로 전달된 음원에 대한 재생 상태를 모니터링 할 수 있습니다.

  • Android
  • iOS
  • Linux

AudioPlayerAgentInterface.Listener 를 추가합니다.

복사성공!
1
2
3
4
5
6
val listener = object: AudioPlayerAgentInterface.Listener {
    override fun onStateChanged(activity: State, context: Context) {
        ...
    }
}
audioPlayerAgent.addListener(listener)

AudioPlayerAgentDelegate 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
class MyAudioPlayerAgentDelegate: AudioPlayerAgentDelegate {
    func audioPlayerAgentDidChange(state: AudioPlayerState, dialogRequestId: String) {
        ...
    }
}

audioPlayerAgent.add(delegate: MyAudioPlayerAgentDelegate())

IAudioPlayerListener 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
class MyAudioPlayerListener : public IAudioPlayerListener {
public:
    ...

    void mediaStateChanged (AudioPlayerState state, const std::string &dialog_id) override
    {
        ...
    }

    ...
};
auto audio_player_listener(std::make_shared<MyAudioPlayerListener>());
CapabilityFactory::makeCapability<AudioPlayerAgent, IAudioPlayerHandler>(audio_player_listener.get());

UI 구성 및 제어

AudioPlayer 로 음원을 재생할 때 화면을 구성하기 위해 필요한 데이터는 Play directive 의 audioItem.metadata.template 에 포함되어 전달됩니다.

Stop directive 또는 SDK 내부 timer 등에 의해 종료될 수 있으며, UpdateMetadata directive 에 의해 변경될 수 있습니다.

AudioPlayer.Template1 에 포함된 가사의 화면은 사용자 발화 에 따라 ShowLyrics, HideLyrics, ControlLyricsPage directive 로 제어될 수 있습니다.

  • Android
  • iOS
  • Linux

DisplayAggregatorInterface.Renderer 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
8
val renderer = object: DisplayAggregatorInterface.Renderer {
    override fun render(templateId: String, templateType: String, templateContent: String, dialogRequestId: String, displayType: Type): Boolean {
        ...
    }

    ...
}
nuguAndroidClient.setDisplayRenderer(renderer)

UI 제어 요청을 처리하려면 LyricsPresenter 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
val presenter = object: LyricsPresenter {
    override fun show(): Boolean {
        ...
    }

    override fun hide(): Boolean {
        ...
    }

    ...
}
audioPlayerAgent.setLyricsPresenter(presenter)

AudioPlayerDisplayDelegate 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
class MyAudioPlayerDisplayDelegate: AudioPlayerDisplayDelegate {
    func audioPlayerDisplayShouldRender(template: AudioPlayerDisplayTemplate, completion: @escaping (AnyObject?) -> Void) {
        ...
    }

    func audioPlayerDisplayShouldShowLyrics(completion: @escaping (Bool) -> Void) {
        ...
    }

    func audioPlayerDisplayShouldHideLyrics(completion: @escaping (Bool) -> Void) {
        ...
    }

    ...
}

audioPlayerAgent.displayDelegate = MyAudioPlayerDisplayDelegate()

IAudioPlayerListener 를 추가합니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
class MyAudioPlayerListener : public IAudioPlayerListener {
public:
    ...

    void renderDisplay(const std::string& id, const std::string& type, const std::string& json_payload, const std::string& dialog_id) override
    {
        ...
    }

    bool showLyrics(const std::string& id) override
    {
        ...
    }

    bool hideLyrics(const std::string& id) override
    {
        ...
    }

    ...
};
auto audio_player_listener(std::make_shared<MyAudioPlayerListener>());
CapabilityFactory::makeCapability<AudioPlayerAgent, IAudioPlayerHandler>(audio_player_listener.get());

제어 명령

PUI, GUI 등으로 사용자가 다음/이전/즐겨찾기/반복/셔플 요청을 event 로 전달할 수 있습니다.

  • Android
  • iOS
  • Linux
복사성공!
1
2
3
4
5
6
7
8
9
10
// 다음
audioPlayerAgent.next()
// 이전
audioPlayerAgent.prev()
// 즐겨찾기
audioPlayerAgent.requestFavoriteCommand(false)
// 반복
audioPlayerAgent.requestRepeatCommand(RepeatMode.NONE)
// 셔플
audioPlayerAgent.requestShuffleCommand(false)
복사성공!
1
2
3
4
5
6
7
8
9
10
// 다음 
audioPlayerAgent.next()
// 이전
audioPlayerAgent.prev()
// 즐겨찾기
audioPlayerAgent.requestFavoriteCommand(false)
// 반복
audioPlayerAgent.requestRepeatCommand(.none)
// 셔플
audioPlayerAgent.requestShuffleCommand(false)
복사성공!
1
2
3
4
5
6
7
8
9
10
// 다음
audio_player_handler->next()
// 이전
audio_player_handler->prev()
// 즐겨찾기
audio_player_handler->requestFavoriteCommand(false)
// 반복
audio_player_handler->requestRepeatCommand(RepeatType.NONE)
// 셔플
audio_player_handler->requestShuffleCommand(false)

Context

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "AudioPlayer": {
    "version": "1.7",
    "playServiceId": "{{STRING}}",
    "playerActivity": "{{STRING}}",
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "durationInMilliseconds": {{LONG}},
    "lyricsVisible": {{BOOLEAN}},
    "playlistToken": "{{STRING}}"
  }
}
parameter type mandatory description
playServiceId string N 현재 사용 중인 음원의 playServiceId
playerActivity string Y 현재 state
token string N 현재 사용 중인 음원의 토큰
offsetInMilliseconds long Y 현재 사용 중인 음원의 offset
durationInMilliseconds long N 현재 사용 중인 음원의 전체 재생시간(알수 없으면 보내주지 않음)
lyricsVisible boolean N AudioPlayer에서 가사 화면이 보여지고 있는지 여부
가사를 보여줄 수 없는 Device에서는 lyricsVisible를 보내지 않음
playlistToken string N 디바이스가 가지고 있는 playlist의 token
(playlist를 사용할 수 없는 Device에서는 playlistToken를 보내지 않음)

Directives

Play

새로운 음원 또는 현재 음원 재생 요청입니다.(Play, Resume, Seek 요청이 포함되어 있습니다.)

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "Play",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "sourceType": "{{STRING}}",
    "cacheKey": "{{STRING}}",
    "audioItem": {
      "stream": {
        "url": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "progressReport": {
          "progressReportDelayInMilliseconds": {{LONG}},
          "progressReportIntervalInMilliseconds": {{LONG}}
        },
        "token": "{{STRING}}",
        "expectedPreviousToken": "{{STRING}}"
      },
      "metadata": {
        "template": {}
      }
    }
  }
}
parameter type mandatory description
sourceType string N URL or ATTACHMENT(default 는 URL)
- ATTACHMENT 일 경우 stream에 url이 존재 하지 않음
cacheKey string N 디바이스에서 미디어 캐시를 위한 unique key(디바이스 캐시 기능은 필수가 아님)
캐시가 불가능한 미디어 이면 디바이스로 내려주지 않음
audioItem.stream object Y -
audioItem.stream.url string N 오디오 컨텐츠의 URL (URL에 의한 streaming만 지원)
sourceType 이 ATTACHMENT일 경우 없음
audioItem.stream.offsetInMilliseconds long Y 시작부터 얼마만큼의 offset부터 재생할지 설정.
0이면 처음부터 재생
audioItem.stream.progressReport.progressReportDelayInMilliseconds long N 재생을 시작해서 지정된 시간 뒤에 한 번 progressReportDelayElapsed Event가 발생
(offsetInMilliseconds 값과는 무관하게 컨텐츠 시작 시간 기준으로 절대값을 의미)
audioItem.stream.progressReport.progressReportIntervalInMilliseconds long N 재생을 시작해서 지정된 주기마다 progressReportIntervalElapsed Event가 발생
(offsetInMilliseconds 값과는 무관하게 컨텐츠 시작 시간 기준으로 절대값을 의미)
audioItem.stream.token string Y 현재 stream을 나타내는 token Resume 을 판단하기 위한 key 값으로 사용되기 때문에, Play 에서 제공하는 미디어 내에서 unique 함이 보장되어야 함.
audioItem.stream.expectedPreviousToken string N 이전 stream을 나타내는 token
audioItem.metadata object N -
audioItem.metadata.template object N 각 type별 포맷은 아래에 기술 template이 정의되지 않은 경우 Display를 포함하는 디바이스는 Default 화면을 보여주어야 함

audioItem.metadata.template - AudioPlayer.Template1

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
{
  "metadata": {
    "disableTemplate": {{BOOLEAN}},
    "template": {
      "type": "AudioPlayer.Template1",
      "title": {
        "iconUrl": "{{STRING}}",
        "text": "{{STRING}}"
      },
      "grammarGuide": ["{{STRING}}"],
      "content": {
        "title": "{{STRING}}",
        "subtitle1": "{{STRING}}",
        "subtitle2": "{{STRING}}",
        "imageUrl": "{{STRING}}",
        "durationSec": "{{STRING}}",
        "backgroundImageUrl": "{{STRING}}",
        "backgroundColor": "{{STRING}}",
        "badgeImageUrl": "{{String}}",
        "badgeMessage": "{{String}}",
        "lyrics": {
          "title": "{{String}}",
          "lyricsType": "{{String}}",
          "lyricsInfoList": [
            {
              "time": {{Integer}},
              "text": "{{String}}"
            }
          ],
          "showButton": {
            "text": "{{String}}"
          }
        },
        "settings": {
          "favorite": {{BOOLEAN}},
          "repeat": "{{String}}",
          "shuffle": {{BOOLEAN}}
        }
      },
      "playlist": PlaylistObject
    }
  }
}
parameter type mandatory description
disableTemplate bool N true면 스크린을 가진 디바이스에서 AudioPlayer 재생 시 template을 display하지 않음
default - false
template.type string Y AudioPlayer template type
- AudioPlayer.Template1
- AudioPlayer.Template2
template.title object Y title object
template.title.iconUrl string N icon image url
template.title.text string Y title text
template.content object Y content object
template.content.title string Y content 영역의 title
template.content.subtitle1 string Y subtitle1
template.content.subtitle2 string N subtitle2
template.content.imageUrl string Y image url
template.content.durationSec string N content duration in sec
없거나 0, 음수, null이면 progress를 disabled 처리
template.content.backgroundImageUrl string N background image url
template.content.backgroundColor string N background color
default - “#000”
template.content.badgeImageUrl string N 이미지(content.imageUrl)의 오른쪽 상단에 표시될 Badge Image의 URL
template.content.badgeMessage string N 이미지(content.imageUrl)의 왼쪽 하단에 표시될 Badge Message
template.content.lyrics obejct N 가사 화면을 표시하기 위한 정보
template.content.lyrics.title string Y 가사 화면에서 보여질 제목
template.content.lyrics.lyricsType string Y 가사의 종류
- NONE : 자막 없음
- SYNC : 자막 동기화
- NON_SYNC : 자막 동기화 없음
template.content.lyrics.lyricsInfoList array of lyricsInfo Y 가사 내용(lyricsInfo)의 목록 기본 값은 빈 배열
template.content.lyrics.lyricsInfoList.time integer N lyricsTyps 이 SYNC 이면 mandatory lyricsInfo가 보여지는 시점의 millisecond 단위의 시간 정보
template.content.lyrics.lyricsInfoList.text string Y lyricsInfo가 보여지는 시점의 가사 내용
content.lyrics.showButton object N 가사 화면을 표시하기 위한 버튼
content.lyrics.showButton.text string Y 버튼 text
template.content.settings object N 사용자가 설정한 정보를 표시함
- Play에서는 표시할 하위 field를 설정할 수 있음
- 설정한 field에 대한 Event와 Directive를 사용할 수 있음
template.content.settings.favorite boolean N 재생 중인 음원에 대한 좋아요 여부
template.content.settings.repeat string N 재생 목록에 대한 반복 설정
- ALL : 전곡 반복
- ONE : 한곡 반복
- NONE : 반복 없음
template.content.settings.shuffle boolean N 재생 목록의 음원을 임의의 순서로 재생할지 여부
template.grammarGuide list of string N 발화 도움말
template.floatingBanner FloatingBannerObject N display interface 규격의 floatingBanner 참고
template.playlist playlist object N 재생목록

audioItem.metadata.template - AudioPlayer.Template2

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
  "metadata": {
    "disableTemplate": {{BOOLEAN}},
    "template": {
      "type": "AudioPlayer.Template2",
      "title": {
        "iconUrl": "{{STRING}}",
        "text": "{{STRING}}"
      },
      "grammarGuide": ["{{STRING}}"],
      "content": {
        "title": "{{STRING}}",
        "subtitle": "{{STRING}}",
        "subtitle1": "{{STRING}}",
        "imageUrl": "{{STRING}}",
        "durationSec": "{{STRING}}",
        "backgroundColor": "{{STRING}}",
        "lyrics" : {
          "title" : "{{String}}",
          "lyricsType" : "{{String}}",
          "lyricsInfoList" : [
            {"time":"{{Integer}}","text": "{{String}}"}
          ],
          "showButton": {
            "text": "{{String}}"
          }
        }
      }
    }
  }
}
parameter type mandatory description
disableTemplate bool N true면 스크린을 가진 디바이스에서 AudioPlayer 재생 시 template을 display하지 않음 default : false
template.type string Y AudioPlayer template type
- AudioPlayer.Template1
- AudioPlayer.Template2
template.title object Y title object
template.title.iconUrl string N icon image url
template.title.text string Y title text
template.content object Y content object
template.content.title string Y content 영역의 title
template.content.subtitle string Y subtitle
template.content.subtitle1 string Y lyrics가 있는 경우, 가사화면 제목 우측의 소제목
template.content.imageUrl string N background image url
template.content.durationSec string N content duration in sec
없거나 0, 음수, null이면 progress를 화면에서 disabled 처리
template.content.backgroundColor string N background color
default : “#000”
template.content.lyrics obejct N 가사 화면을 표시하기 위한 정보
template.content.lyrics.title string Y 가사 화면에서 보여질 제목
template.content.lyrics.lyricsType string Y 가사의 종류
- NONE : 자막 없음
- SYNC : 자막 동기화
- NON_SYNC : 자막 동기화 없음
template.content.lyrics.lyricsInfoList array of lyricsInfo Y 가사 내용(lyricsInfo)의 목록 기본 값은 빈 배열
template.content.lyrics.lyricsInfoList.time integer N lyricsTyps 이 SYNC 이면 mandatory lyricsInfo가 보여지는 시점의 millisecond 단위의 시간 정보
template.content.lyrics.lyricsInfoList.text string Y lyricsInfo가 보여지는 시점의 가사 내용
content.lyrics.showButton object N 가사 화면을 표시하기 위한 버튼
content.lyrics.showButton.text string Y 버튼 text
template.grammarGuide list of string N 발화 도움말

Stop

음원 재생 중지 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "Stop",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

Pause

음원 일시정지 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "Pause",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

UpdateMetadata

음원의 Metadata UI 설정 정보를 갱신 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "UpdateMetadata",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "metadata": {
      "template": {
        "content": {
          "settings": {
            "favorite": {{BOOLEAN}},
            "repeat": "{{STRING}}",
            "shuffle": {{BOOLEAN}}
          }
        },
        "playlist": PlaylistObject
      }
    }
  }
}
parameter type mandatory description
metadata.template.content.settings.favorite boolean N AudioPlayer.Template1의 settings.favorite 와 연동
metadata.template.content.settings.repeat string N AudioPlayer.Template1의 settings.repeat 과 연동
- ALL : 전곡 반복
- ONE : 한곡 반복
- NONE : 반복 없음
metadata.template.content.settings.shuffle boolean N AudioPlayer.Template1의 settings.shuffle 과 연동
metadata.template.playlist Playlist Object N PlaylistTemplate1
playlist.type은 수정 불가하며, 나머지 field들은 수정 가능

ShowLyrics

가사화면 표시 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ShowLyrics",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

HideLyrics

가사화면 닫기 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "HideLyrics",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

ControlLyricsPage

가사화면 스크롤 위치 이동 요청입니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ControlLyricsPage",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "direction": "{{STRING}}"
  }
}
parameter type mandatory description
direction string Y 이전과 다음 PREVIOUS, NEXT

RequestPlayCommand

  • Nugu mobile application 에서 새로운 곡 재생을 요청하기 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPlayCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}
parameter type mandatory description
payload object Y Play 에서 곡 재생을 위해 필요한 정보

RequestResumeCommand

  • Nugu mobile application 에서 현재 재생중인 play 에 대한 제어를 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestResumeCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}

RequestNextCommand

  • Nugu mobile application 에서 현재 재생중인 play 에 대한 제어를 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestNextCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}

RequestPreviousCommand

  • Nugu mobile application 에서 현재 재생중인 play 에 대한 제어를 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPreviousCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}

RequestPauseCommand

  • Nugu mobile application 에서 현재 재생중인 play 에 대한 제어를 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPauseCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}

RequestStopCommand

  • Nugu mobile application 에서 현재 재생중인 play 에 대한 제어를 위한 Directive.
복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestStopCommand",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}

Events

PlaybackStarted

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackStarted",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

PlaybackPaused

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackPaused",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

PlaybackResumed

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackResumed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

PlaybackFinished

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackFinished",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

PlaybackStopped

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackStopped",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}",
    "reason": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값
reason string N 이 이벤트가 만들어진 이유를 명시하기 위한 객체 STOP, PLAY_ANOTHER 중 하나.
- PLAY_ANOTHER : 동일 play 내에서 다른 곡 재생을 위해 이전에 재생하던 곡을 정지했을 때 올려주는 값.
- STOP : 그 외 정지의 경우.

PlaybackFailed

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PlaybackFailed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "error": {
      "type": "{{STRING}}",
      "message": "{{STRING}}"
    },
    "currentPlaybackState": {
      "token": "{{STRING}}",
      "offsetInMilliseconds": {{LONG}},
      "playerActivity": "{{STRING}}"
    },
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 재생에 실패한 stream의 token
offsetInMilliseconds long Y PlaybackFailed를 보낼 때 재생 중인 stream의 offset 값
error.type string Y MEDIA_ERROR_UNKNOWN
MEDIA_ERROR_INVALID_REQUEST
MEDIA_ERROR_SERVICE_UNAVAILABLE
MEDIA_ERROR_INTERNAL_SERVER_ERROR
MEDIA_ERROR_INTERNAL_DEVICE_ERROR
error.message string Y 에러에 대해 자세히 기술
currentPlaybackState.token string Y 현재 재생 중인 stream의 token으로 위에 있는 token과 다를 수 있음
currentPlaybackState.offsetInMilliseconds long Y 에러가 발생했을 때 현재 재생 중인 stream의 offset 값
currentPlaybackState.playActivity string Y player의 상태
PLAYING, PAUSED, FINISHED, IDLE

ProgressReportDelayElapsed

  • Play directive로 전달된 stream이 재생을 시작한 뒤 progressReportDelayInMilliseconds
  • offsetInMilliseconds는 stream의 시작을 기준으로 offset을 의미 (컨텐츠 재생 시간 0부터 절대값을 의미)
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ProgressReportDelayElapsed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

ProgressReportIntervalElapsed

  • Play directive로 전달된 stream이 재생을 시작한 뒤 progressIntervalDelayInMilliseconds 주기마다 Event 전달
  • offsetInMilliseconds는 stream의 시작을 기준으로 offset을 의미 (컨텐츠 재생 시간 0부터 절대값을 의미)
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ProgressReportIntervalElapsed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

NextCommandIssued

사용자가 다음 음원 재생을 요청하면 전송됩니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "NextCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}}
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

PreviousCommandIssued

사용자가 이전 음원 재생을 요청하면 전송됩니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "PreviousCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}}
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

FavoriteCommandIssued

사용자가 현재 음원 즐겨찾기(좋아요 포함)를 요청하면 전송됩니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "FavoriteCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "favorite": {{BOOLEAN}}
  }
}
parameter type mandatory description
favorite boolean Y 재생 중인 음원에 대한 좋아요 여부

RepeatCommandIssued

사용자가 현재 음원 반복 재생을 요청하면 전송됩니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RepeatCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "repeat": {{BOOLEAN}}
  }
}
parameter type mandatory description
repeat boolean Y 재생 목록에 대한 반복 설정 - ALL : 전곡 반복 - ONE : 한곡 반복 - NONE : 반복 없음

ShuffleCommandIssued

사용자가 셔플 재생을 요청하면 전송됩니다.

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ShuffleCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "shuffle": {{BOOLEAN}}
  }
}
parameter type mandatory description
shuffle boolean Y 재생 목록의 음원을 임의의 순서로 재생할지 여부

ShowLyricsSucceeded

  • ShowLyrics Directive가 발생하여 가사화면을 성공적으로 띄운다음 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ShowLyricsSucceeded",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

ShowLyricsFailed

  • ShowLyrics Directive가 발생하였는데 가사화면을 띄우지 못한 경우 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ShowLyricsFailed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

HideLyricsSucceeded

  • HideLyrics Directive가 발생하여 가사화면을 성공적으로 닫은 다음 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "HideLyricsSucceeded",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

HideLyricsFailed

  • HideLyrics Directive가 발생하였는데 가사화면을 닫지 못한 경우 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "HideLyricsFailed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}"
  }
}

ControlLyricsPageSucceeded

  • ControlLyricsPage Directive가 발생하여 가사화면을 성공적으로 이동한 다음 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ControlLyricsPageSucceeded",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "direction": "{{STRING}}"
  }
}
parameter type mandatory description
direction string Y 이전과 다음을 수행한 결과
PREVIOUS, NEXT

ControlLyricsPageFailed

  • ControlLyricsPage Directive가 발생하였는데 가사화면을 이동하지 못한 경우 발생되는 Event
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "ControlLyricsPageFailed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "playServiceId": "{{STRING}}",
    "direction": "{{STRING}}"
  }
}
parameter type mandatory description
direction string Y 이전과 다음을 수행한 결과
PREVIOUS, NEXT

RequestPlayCommandIssued

복사성공!
1
2
3
4
5
6
7
8
9
10
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPlayCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {}
}
parameter type mandatory description
payload string Y RequestPlayCommand Directive 에 포함되어 있는 payload 를 그대로 포함.

RequestResumeCommandIssued

  • RequestResumeCommand Directive 를 받은 디바이스가 발생시키는 Event.
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestResumeCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

RequestNextCommandIssued

  • RequestNextCommand Directive 를 받은 디바이스가 발생시키는 Event.
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestNextCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

RequestPreviousCommandIssued

  • RequestPreviousCommand Directive 를 받은 디바이스가 발생시키는 Event.
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPreviousCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

RequestPauseCommandIssued

  • RequestPauseCommand Directive 를 받은 디바이스가 발생시키는 Event.
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestPauseCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

RequestStop CommandIssued

  • RequestStopCommand Directive 를 받은 디바이스가 발생시키는 Event.
복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestStopCommandIssued",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "token": "{{STRING}}",
    "offsetInMilliseconds": {{LONG}},
    "playServiceId": "{{STRING}}"
  }
}
parameter type mandatory description
token string Y 현재 재생 중인 stream의 token
offsetInMilliseconds long Y 현재 재생 중인 stream의 offset 값

RequestCommandFailed

복사성공!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "header": {
    "namespace": "AudioPlayer",
    "name": "RequestCommandFailed",
    "messageId": "{{STRING}}",
    "dialogRequestId": "{{STRING}}",
    "version": "1.7"
  },
  "payload": {
    "error": {
      "type": "{{STRING}}",
      "message": "{{STRING}}"
    }
  }
}
parameter type mandatory description
error.type string Y 에러 타입 코드
- INVALID_COMMAND : IDLE/STOP 상태일때 Request Pause/Resume/Next/Previous/Stop Command Directive 수신한 경우 (STOP/IDLE 일때 RequestPlayCommand 는 정상요청이므로 제외에 유의)
- UNKNOWN_ERROR : 그 이외에 처리중 에러난 경우
error.message string Y STOP/IDLE 상태에서는 Request XXX Command 를 처리할 수 없음.