LocalMediaSource

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": "LocalMediaSource",
            "action": "PlayControl"
        }
    },
    "payload": {
        "source": {{Source}},
        "controlType": {{PlayControlType}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
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": "LocalMediaSource",
            "action": "Seek"
        }
    },
    "payload": {
        "source": {{Source}},
        "offset": {{Int}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
offset	Int	Yes	Offset position within media item, in milliseconds.

Play

Called when the user calls play with a content selection type.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "Play"
        }
    },
    "payload": {
        "source": {{Source}},
        "contentSelectorType": {{ContentSelector}},
        "payload": {{String}},
        "sessionId": {{String}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
contentSelectorType	ContentSelector	Yes	Content selection type.
payload	String	Yes	Content selector payload.
sessionId	String	Yes	Universally unique identifier (UUID) generated according to the RFC 4122 specification. Since Alexa is starting the session here, use this session Id for further events and errors.

GetState

Must provide the local media source @PlaybackState, and @SessionState information to maintain cloud sync.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "GetState"
        }
    },
    "payload": {
        "source": {{Source}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.

AdjustSeek

Called when the user invokes media seek adjustment via speech.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "AdjustSeek"
        }
    },
    "payload": {
        "source": {{Source}},
        "deltaOffset": {{Int}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
deltaOffset	Int	Yes	Change in offset position within media item, in milliseconds.

MutedStateChanged

Notifies the platform implementation to apply a muted state has changed for the output channel.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "MutedStateChanged"
        }
    },
    "payload": {
        "source": {{Source}},
        "state": {{MutedState}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
state	MutedState	Yes	The muted state to apply to the output channel.

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": "LocalMediaSource",
            "action": "VolumeChanged"
        }
    },
    "payload": {
        "source": {{Source}},
        "volume": {{Float}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
volume	Float	Yes	The volume to set on the output channel.

Incoming Messages

PlayerEvent

Should be called on a local media source player event. This will sync the context with AVS.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "PlayerEvent"
        }
    },
    "payload": {
        "source": {{Source}},
        "eventName": {{String}},
        "sessionId": {{String}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
eventName	String	Yes	Canonical event name.
sessionId	String	No	Universally unique identifier (UUID) generated according to the RFC 4122 specification. If playback session is started because of 'Play', use the same session Id. If the session is started due to any other reason, generate unique UUID and use it as a session ID until session is not ended.

SetFocus

Should be called on local media source player events. This will switch the media focus to that context.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "SetFocus"
        }
    },
    "payload": {
        "source": {{Source}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.

PlayerError

Should be called on a local media source player error.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "PlayerError"
        }
    },
    "payload": {
        "source": {{Source}},
        "errorName": {{String}},
        "code": {{Int}},
        "description": {{String}},
        "fatal": {{Bool}},
        "sessionId": {{String}}        
    }
}

Payload

Property	Type	Required	Description	Example
source	Source	Yes	LocalMediaSource source type.
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.
sessionId	String	No	Universally unique identifier (UUID) generated according to the RFC 4122 specification. If playback session is started because of 'Play', use the same session Id. If the session is started due to any other reason, generate unique UUID and use it as a session ID until session is not ended.

GetStateReply

Reply for GetState message.

JSON Structure

{
    "header": {
        "version": "4.0",
        "messageType": "Reply",
        "id": {{String}},
        "messageDescription": {
            "topic": "LocalMediaSource",
            "action": "GetState",
            "replyToId": {{String}}        
        }
    },
    "payload": {
        "state": {{LocalMediaSourceState}}        
    }
}

Payload

Property	Type	Required	Description	Example
state	LocalMediaSourceState	Yes	state description.

Type Definitions

LocalMediaSourceState

JSON Structure

{
    "sessionState": {{SessionState}},
    "playbackState": {{PlaybackState}}        
}

Properties

Property	Type	Required	Description	Example
sessionState	SessionState	Yes	Variable to hold the session state.
playbackState	PlaybackState	Yes	Variable to hold the playback state.

PlaybackState

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/PAUSED/PLAYING/FINISHED/FAST_FORWARDING/REWINDING/BUFFER_UNDERRUN.
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.
repeatEnabled	Bool	Yes	Bool to identify if looping of songs is enabled.
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.

SessionState

JSON Structure

{
    "endpointId": {{String}},
    "loggedIn": {{Bool}},
    "userName": {{String}},
    "isGuest": {{Bool}},
    "launched": {{Bool}},
    "active": {{Bool}},
    "accessToken": {{String}},
    "tokenRefreshInterval": {{int64}},
    "supportedContentSelectors": [{{ContentSelector}}],
    "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.
supportedContentSelectors	ContentSelector[]	Yes	Array of content selector types supported by the player.
spiVersion	String	Yes	The only spiVersion that currently exists is '1.0'.

Enums

Source

Values

Value	Description
"BLUETOOTH"	bluetooth source.
"USB"	USB source.
"FM_RADIO"	FM radio source.
"AM_RADIO"	AM radio source.
"SATELLITE_RADIO"	satellite radio source.
"LINE_IN"	audio line source.
"COMPACT_DISC"	CD player source.
"SIRIUS_XM"	SIRIUS XM source.
"DAB"	DAB source.
"DEFAULT"	DEFAULT source.

ContentSelector

Values

Value	Description
"FREQUENCY"	radio station selection.
"CHANNEL"	radio channel selection.
"PRESET"	preset selection.