ExternalMediaAdapter¶
Outgoing Messages¶
PlayControl¶
Occurs during playback control via voice interaction or PlaybackController interface.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "PlayControl"
}
},
"payload": {
"localPlayerId": {{String}},
"controlType": {{PlayControlType}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
controlType | PlayControlType | Yes | Playback control type being invoked. |
Seek¶
Called when the user invokes media seek via speech.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "Seek"
}
},
"payload": {
"localPlayerId": {{String}},
"offset": {{Int}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
offset | Int | Yes | Offset position within media item, in milliseconds. |
Logout¶
Directive called after a discovered player initiates the logoutComplete event.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "Logout"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. |
Play¶
Called when the user first calls play for the external media via voice control.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "Play"
}
},
"payload": {
"localPlayerId": {{String}},
"playContextToken": {{String}},
"index": {{Int}},
"offset": {{Int}},
"preload": {{Bool}},
"navigation": {{Navigation}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
playContextToken | String | Yes | Track/playlist/album/artist/station/podcast context identifier. | |
index | Int | Yes | If the playback context is an indexable container like a playlist, the index of the media item in the container. | |
offset | Int | Yes | Offset position within media item, in milliseconds. | |
preload | Bool | Yes | Whether the media item should preload or not. | |
navigation | Navigation | Yes | The app transition behavior. |
GetState¶
Must provide the local external media player apps @PlaybackStateExternal, and @SessionStateExternal information to maintain cloud sync.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "GetState"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. |
Login¶
Directive called after a discovered player initiates the loginComplete event.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "Login"
}
},
"payload": {
"localPlayerId": {{String}},
"accessToken": {{String}},
"userName": {{String}},
"forceLogin": {{Bool}},
"tokenRefreshInterval": {{Int}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
accessToken | String | Yes | The handshake token between AVS, and the external media player app session. | |
userName | String | Yes | The username provided by the external media player app, if available. | |
forceLogin | Bool | Yes | True if no handshake is needed, and login is simply assumed. | |
tokenRefreshInterval | Int | Yes | refresh interval of the accessToken, if available. |
AdjustSeek¶
Called when the user invokes media seek adjustment via speech.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "AdjustSeek"
}
},
"payload": {
"localPlayerId": {{String}},
"deltaOffset": {{Int}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
deltaOffset | Int | Yes | Change in offset position within media item, in milliseconds. |
MutedStateChanged¶
Notifies the platform implementation to apply a mute state change to the output channel.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "MutedStateChanged"
}
},
"payload": {
"state": {{MutedState}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
state | MutedState | Yes | The muted state to apply to the output channel. MUTED when the output channel be muted, UNMUTED when unmuted. | |
VolumeChanged¶
Notifies the platform implementation to set the volume of the output channel. The volume value should be scaled to fit the needs of the platform.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "VolumeChanged"
}
},
"payload": {
"volume": {{Float}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
volume | Float | Yes | The volume to set on the output channel. volume is in the range [0,1]. |
Authorize¶
Called after discovered media players have been reported. Returns a list of reported players and whether they have been authorized for use with Alexa.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "Authorize"
}
},
"payload": {
"authorizedPlayers": [{{AuthorizedPlayerInfo}}]
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
authorizedPlayers | AuthorizedPlayerInfo[] | Yes | A list of discovered players with their status of authorization for use with Alexa. |
Incoming Messages¶
PlayerEvent¶
Should be called on a local external media player event. This will sync the context with AVS.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "PlayerEvent"
}
},
"payload": {
"localPlayerId": {{String}},
"eventName": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
eventName | String | Yes | Canonical event name. |
LogoutComplete¶
Should be called on a local external media player logout. This will unset authorization of the app with AVS.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "LogoutComplete"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. |
LoginComplete¶
Should be called on a local external media player login. This will set authorization of the app with AVS.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "LoginComplete"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | Should be called on a local external media player login. This will set authorization of the app with AVS. | |
SetFocus¶
Should be called on local external media player events. This will switch the media focus to that context.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "SetFocus"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. |
ReportDiscoveredPlayers¶
Should be called on startup in order to notify AVS of the local external media players.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "ReportDiscoveredPlayers"
}
},
"payload": {
"discoveredPlayers": [{{DiscoveredPlayerInfo}}]
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
discoveredPlayers | DiscoveredPlayerInfo[] | Yes | The List of discovered players. |
RemoveDiscoveredPlayer¶
RemoveDiscoveredPlayer description.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "RemoveDiscoveredPlayer"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | localPlayerId description. |
RequestToken¶
The device is responsible for requesting an access token when needed. This is typically done immediately upon connection to AVS.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "RequestToken"
}
},
"payload": {
"localPlayerId": {{String}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. |
PlayerError¶
Should be called on a player error.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Publish",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "PlayerError"
}
},
"payload": {
"localPlayerId": {{String}},
"errorName": {{String}},
"code": {{Int}},
"description": {{String}},
"fatal": {{Bool}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
errorName | String | Yes | The name of the error. | |
code | Int | Yes | The error code. | |
description | String | Yes | The detailed error description. | |
fatal | Bool | Yes | true if the error is fatal. |
GetStateReply¶
Reply for GetState message.
JSON Structure¶
{
"header": {
"version": "4.0",
"messageType": "Reply",
"id": {{String}},
"messageDescription": {
"topic": "ExternalMediaAdapter",
"action": "GetState",
"replyToId": {{String}}
}
},
"payload": {
"state": {{ExternalMediaAdapterState}}
}
}
Payload¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
state | ExternalMediaAdapterState | Yes | The ExternalMediaAdapterState to be initialized by the platform. |
Type Definitions¶
ExternalMediaAdapterState¶
JSON Structure¶
{
"sessionState": {{SessionStateExternal}},
"playbackState": {{PlaybackStateExternal}}
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
sessionState | SessionStateExternal | Yes | Variable to hold the session state. | |
playbackState | PlaybackStateExternal | Yes | Variable to hold the playback state. |
SessionStateExternal¶
JSON Structure¶
{
"endpointId": {{String}},
"loggedIn": {{Bool}},
"userName": {{String}},
"isGuest": {{Bool}},
"launched": {{Bool}},
"active": {{Bool}},
"accessToken": {{String}},
"tokenRefreshInterval": {{int64}},
"playerCookie": {{String}},
"spiVersion": {{String}}
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
endpointId | String | Yes | The unique device endpoint. | |
loggedIn | Bool | Yes | Flag that identifies if a user is currently logged in or not. | |
userName | String | Yes | The userName of the user currently logged in via a Login directive from the AVS. | |
isGuest | Bool | Yes | Flag that identifies if the user currently logged in is a guest or not. | |
launched | Bool | Yes | Flag that identifies if an application has been launched or not. | |
active | Bool | Yes | Flag that identifies if the application is currently active or not. This could mean different things for different applications. | |
accessToken | String | Yes | The accessToken used to login a user. The access token may also be used as a bearer token if the adapter makes an authenticated Web API to the music provider. | |
tokenRefreshInterval | int64 | Yes | The validity period of the token in milliseconds. | |
playerCookie | String | Yes | A player may declare arbitrary information for itself. | |
spiVersion | String | Yes | The only spiVersion that currently exists is "1.0". |
PlaybackStateExternal¶
JSON Structure¶
{
"state": {{String}},
"supportedOperations": [{{SupportedPlaybackOperation}}],
"trackOffset": {{Int}},
"shuffleEnabled": {{Bool}},
"repeatEnabled": {{Bool}},
"favorites": {{Favorites}},
"type": {{String}},
"playbackSource": {{String}},
"playbackSourceId": {{String}},
"trackName": {{String}},
"trackId": {{String}},
"trackNumber": {{String}},
"artistName": {{String}},
"artistId": {{String}},
"albumName": {{String}},
"albumId": {{String}},
"tinyURL": {{String}},
"smallURL": {{String}},
"mediumURL": {{String}},
"largeURL": {{String}},
"coverId": {{String}},
"mediaProvider": {{String}},
"mediaType": {{MediaType}},
"duration": {{Int}}
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
state | String | Yes | The state of the default player - IDLE/STOPPED/PLAYING. | |
supportedOperations | SupportedPlaybackOperation[] | Yes | The set of states the default player can move into from its current state. | |
trackOffset | Int | Yes | The offset of the track in milliseconds. | |
shuffleEnabled | Bool | Yes | Bool to identify if shuffling is enabled or not. | |
repeatEnabled | Bool | Yes | Bool to identify if looping of songs is enabled or not. | |
favorites | Favorites | Yes | The favorite status {"FAVORITED"/"UNFAVORITED"/"NOT_RATED"}. | |
type | String | Yes | The type of the media item. For now hard-coded to ExternalMediaAdapterMusicItem. | |
playbackSource | String | Yes | The display name for current playback context, e.g. playlist name. | |
playbackSourceId | String | Yes | An arbitrary identifier for current playback context as per the music provider, e.g. a URI that can be saved as a preset or queried to Music Service Provider services for additional info. | |
trackName | String | Yes | The display name for the currently playing trackname of the track. | |
trackId | String | Yes | The arbitrary identifier for currently playing trackid of the track as per the music provider. | |
trackNumber | String | Yes | The display value for the number or abstract position of the currently playing track in the album or context trackNumber of the track. | |
artistName | String | Yes | The display name for the currently playing artist. | |
artistId | String | Yes | An arbitrary identifier for currently playing artist as per the music provider, e.g. a URI that can be queried to MSP services for additional info. | |
albumName | String | Yes | The display name of the currently playing album. | |
albumId | String | Yes | Arbitrary identifier for currently playing album specific to the music provider, e.g. a URI that can be queried to MSP services for additional info. | |
tinyURL | String | Yes | The URL for tiny cover art image resource. | |
smallURL | String | Yes | The URL for small cover art image resource. | |
mediumURL | String | Yes | The URL for medium cover art image resource. | |
largeURL | String | Yes | The URL for large cover art image resource. | |
coverId | String | Yes | The Arbitrary identifier for cover art image resource specific to the music provider, for retrieval from an MSP API. | |
mediaProvider | String | Yes | Music Service Provider name for the currently playing media item; distinct from the application identity although the two may be the same. | |
mediaType | MediaType | Yes | The Media type enum value from {TRACK, PODCAST, STATION, AD, SAMPLE, OTHER} type of the media. | |
duration | Int | Yes | Media item duration in milliseconds. |
AuthorizedPlayerInfo¶
JSON Structure¶
{
"localPlayerId": {{String}},
"authorized": {{Bool}}
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
authorized | Bool | Yes | Authorization status. |
ValidationData¶
JSON Structure¶
{
"certificate": {{String}}
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
certificate | String | Yes | Validation data. |
DiscoveredPlayerInfo¶
JSON Structure¶
{
"localPlayerId": {{String}},
"spiVersion": {{String}},
"validationMethod": {{ValidationMethod}},
"validationData": [{{ValidationData}}]
}
Properties¶
Property | Type | Required | Description | Example |
---|---|---|---|---|
localPlayerId | String | Yes | The opaque token that uniquely identifies the local external player app. | |
spiVersion | String | Yes | The only spiVersion that currently exists is '1.0'. | |
validationMethod | ValidationMethod | Yes | Validation methods. | |
validationData | ValidationData[] | Yes | Validation data: | |
1. Device platform issued app signing certificate. A List of certificates may be attached. | ||||
2. In some cases validation is performed locally. The certificate is trasmitted as validationData | ||||
during discovery to announce the activated app's identity in order to allow app activation to | ||||
be revoked. | ||||
3. empty. | ||||
Enums¶
SupportedPlaybackOperation¶
Values¶
Value | Description |
---|---|
"PLAY" | Play is supported (voice only). |
"PAUSE" | Pause is supported. |
"STOP" | Stop is supported. |
"NEXT" | Next is supported. |
"PREVIOUS" | Previous is supported. |
"START_OVER" | Start Over is supported. |
"FAST_FORWARD" | Fast Forward is supported. |
"REWIND" | Rewind is supported. |
"ENABLE_REPEAT" | Enable Repeat is supported. |
"ENABLE_REPEAT_ONE" | Enable Repeat One is supported. |
"DISABLE_REPEAT" | Disbale Repeat is supported. |
"ENABLE_SHUFFLE" | Enable Shuffle is supported. |
"DISABLE_SHUFFLE" | Disable Shuffle is supported. |
"FAVORITE" | Favorite is supported. |
"UNFAVORITE" | Unfavorite is supported. |
"SEEK" | Seek is supported. |
"ADJUST_SEEK" | Adjust Seek is supported. |
PlayControlType¶
Values¶
Value | Description |
---|---|
"PAUSE" | pause playback. |
"RESUME" | resume playback. |
"STOP" | stop playback. |
"NEXT" | next song. |
"PREVIOUS" | previous playback. |
"START_OVER" | start playback over. |
"FAST_FORWARD" | fast forward external media described time. |
"REWIND" | rewind external media described time. |
"ENABLE_REPEAT_ONE" | enable repeat current song. |
"ENABLE_REPEAT" | enable playlist looping. |
"DISABLE_REPEAT" | disable playlist looping. |
"ENABLE_SHUFFLE" | enable playlist shuffling. |
"DISABLE_SHUFFLE" | disable playlist shuffling. |
"FAVORITE" | favorite song. |
"UNFAVORITE" | unfavorite song. |
ValidationMethod¶
Values¶
Value | Description |
---|---|
"SIGNING_CERTIFICATE" | description for SIGNING_CERTIFICATE. |
"GENERATED_CERTIFICATE" | description for GENERATED_CERTIFICATE. |
"NONE" | description for NONE. |
Favorites¶
Values¶
Value | Description |
---|---|
"FAVORITED" | song is favorited. |
"UNFAVORITED" | song is unfavorited. |
"NOT_RATED" | song is not rated. |
MutedState¶
Values¶
Value | Description |
---|---|
"MUTED" | The audio channel state id muted. |
"UNMUTED" | The audio channel state id unmuted. |
Navigation¶
Values¶
Value | Description |
---|---|
"DEFAULT" | Source dependant behavior. |
"NONE" | No navigation should occur. |
"FOREGROUND" | External app should take foreground. |
MediaType¶
Values¶
Value | Description |
---|---|
"TRACK" | A single song source. |
"PODCAST" | A podcast source. |
"STATION" | A station source. |
"AD" | An advertisement source. |
"SAMPLE" | A sample source. |
"OTHER" | A miscellaneous source. |