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.