AudioOutput¶

Outgoing Messages¶

GetNumBytesBuffered¶

Returns the amount of audio data buffered.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetNumBytesBuffered"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Resume¶

Notifies the platform implementation to resume an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Resume"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Play¶

Notifies the platform implementation to play an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Play"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source being played.

SetPosition¶

Notifies the platform implementation to set the playback position of the current audio source in the platform media player.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "SetPosition"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}},
        "position": {{Int}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.
position	Int	Yes	The playback position in milliseconds to set in the platform media player.

Prepare¶

Notifies the platform implementation to prepare an audio URL for playback.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Prepare"
        }
    },
    "payload": {
        "channel": {{String}},
        "audioType": {{AudioOutputAudioType}},
        "token": {{String}},
        "source": "URL",
        "url": {{String}},
        "repeating": {{Bool}},
        "playbackContext": {{PlaybackContext}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
audioType	AudioOutputAudioType	Yes	The type of audio data to be played.
token	String	Yes	A unique token for this audio source.
source	String	Yes	Stream source description.
url	String	Yes	The URL audio stream being provided.
repeating	Bool	Yes	True if the platform should loop the audio when playing.
playbackContext	PlaybackContext	Yes	The context related to playback of an audio item.

GetPosition¶

Returns the current playback position of the platform media player. If the audio source is not playing, the most recent position played should be returned.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetPosition"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Pause¶

Notifies the platform implementation to pause an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Pause"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source being paused.

GetDuration¶

Request the duration of the current audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetDuration"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Stop¶

Notifies the platform implementation to stop an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Stop"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Prepare¶

Notifies the platform implementation to prepare an audio stream for playback.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "Prepare"
        }
    },
    "payload": {
        "channel": {{String}},
        "audioType": {{AudioOutputAudioType}},
        "token": {{String}},
        "source": "STREAM",
        "streamId": {{String}},
        "repeating": {{Bool}},
        "encoding": {{AudioStreamEncoding}},
        "properties": {{dict}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
audioType	AudioOutputAudioType	Yes	The type of audio data to be played.
token	String	Yes	A unique token for this audio stream.
source	String	Yes	Stream source description.
streamId	String	Yes	The URL audio stream being provided.
repeating	Bool	Yes	True if the platform should loop the audio when playing.
encoding	AudioStreamEncoding	Yes	The stream encoding format if known.
properties	dict	Yes	List of properties associated with the audio stream.

MutedStateChanged¶

Notifies the platform implementation that the muted state has changed for an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "MutedStateChanged"
        }
    },
    "payload": {
        "channel": {{String}},
        "state": {{MutedState}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
state	MutedState	Yes	The muted state to apply to the audio source.

VolumeChanged¶

Notifies the platform implementation that the volume has changed for an audio source.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "VolumeChanged"
        }
    },
    "payload": {
        "channel": {{String}},
        "volume": {{Float}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
volume	Float	Yes	The volume to set on the audio source. The volume is in the range [0,1].

MayDuck¶

Notifies the platform implementation only if prepared media may duck the volume.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "MayDuck"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

StartDucking¶

Notifies the platform implementation to move the playback in background. If platform implementation supports audio ducking, reduce the media player volume according to platform guidelines.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "StartDucking"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

StopDucking¶

Notifies the platform implementation to move the playback in foreground. If platform implementation supports audio ducking, restore the media player volume to original value.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "StopDucking"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.

Incoming Messages¶

MediaError¶

Notifies the Engine of an error during audio playback.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "MediaError"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}},
        "error": {{MediaError}},
        "description": {{String}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.
error	MediaError	Yes	The error encountered by the platform media player during playback.
description	String	No	A description of the error.

MediaStateChanged¶

Notifies the Engine of an audio playback state change in the platform implementation. Must be called when the platform media player transitions between stopped and playing states.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "MediaStateChanged"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}},
        "state": {{MediaState}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.
state	MediaState	Yes	The new playback state of the platform media player.

AudioFocusEvent¶

Report the engine about the Audio Focus action. Request engine to perform the action mentioned in the parameter.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Publish",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "AudioFocusEvent"
        }
    },
    "payload": {
        "channel": {{String}},
        "token": {{String}},
        "focusAction": {{FocusAction}}        
    }
}

Payload¶

Property	Type	Required	Description
channel	String	Yes	Name of the channel that is providing audio.
token	String	Yes	The unique token of the audio source.
focusAction	FocusAction	Yes	Report the engine what focus action client has taken due to the external audio focus event.

GetNumBytesBufferedReply¶

Reply for GetNumBytesBuffered message.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Reply",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetNumBytesBuffered",
            "replyToId": {{String}}        
        }
    },
    "payload": {
        "bufferedBytes": {{Int}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
bufferedBytes	Int	Yes	The number of bytes of the audio data buffered, or 0 if it's unknown.

GetPositionReply¶

Reply for GetPosition message.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Reply",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetPosition",
            "replyToId": {{String}}        
        }
    },
    "payload": {
        "position": {{Int}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
position	Int	Yes	The platform media player's playback position in milliseconds.

GetDurationReply¶

Reply for GetDuration message.

JSON Structure¶

{
    "header": {
        "version": "4.0",
        "messageType": "Reply",
        "id": {{String}},
        "messageDescription": {
            "topic": "AudioOutput",
            "action": "GetDuration",
            "replyToId": {{String}}        
        }
    },
    "payload": {
        "duration": {{Int}}        
    }
}

Payload¶

Property	Type	Required	Description	Example
duration	Int	Yes	The duration of the current audio source. If the duration is unknown, then -1 should be returned.

Type Definitions¶

AudioStreamProperty¶

JSON Structure¶

{
    "name": {{String}},
    "value": {{String}}        
}

Properties¶

Property	Type	Required	Description	Example
name	String	Yes	Stream property name.
value	String	Yes	Stream property value.

PlaybackContext¶

JSON Structure¶

{
    "keyConfig": {{dict}},
    "manifestConfig": {{dict}},
    "audioSegmentConfig": {{dict}},
    "allConfig": {{dict}}        
}

Properties¶

Property	Type	Required	Description
keyConfig	dict	Yes	Headers to use when fetching encryption keys. The map contains up to 20 pairs of header name and value. Header names may be "Authorization" or strings prefixed with "x-", containing up to 256 characters. Values may contain up to 4096 characters.
manifestConfig	dict	Yes	Headers to use when fetching manifests. The map contains up to 20 pairs of header name and value. Header names may be "Authorization" or strings prefixed with "x-", containing up to 256 characters. Values may contain up to 4096 characters.
audioSegmentConfig	dict	Yes	Headers to use when fetching audio chunks described in the manifest. The map contains up to 20 pairs of header name and value. Header names may be "Authorization" or strings prefixed with "x-", containing up to 256 characters. Values may contain up to 4096 characters.
allConfig	dict	Yes	A catch-all list of headers to use in all URL requests. The map contains up to 20 pairs of header name and value. The headers in keyConfig, manifestConfig, and audioSegmentConfig take priority over the "all" headers, and hence any name-value pairs in the higher priority lists must overwrite any pair with the same name from allConfig. Header names may be "Authorization" or strings prefixed with "x-", containing up to 256 characters. Values may contain up to 4096 characters.

Enums¶

MediaState¶

Values¶

Value	Description
"STOPPED"	The audio source is not currently playing. It may have paused, stopped, or finished.
"PLAYING"	The audio source is currently playing.
"BUFFERING"	The audio source is currently buffering data.

MediaError¶

Values¶

Value	Description
"MEDIA_ERROR_UNKNOWN"	An unknown error occurred.
"MEDIA_ERROR_INVALID_REQUEST"	The server recognized the request as malformed (e.g. bad request, unauthorized, forbidden, not found, etc).
"MEDIA_ERROR_SERVICE_UNAVAILABLE"	The client was unable to reach the service.
"MEDIA_ERROR_INTERNAL_SERVER_ERROR"	The server accepted the request but was unable to process it as expected.
"MEDIA_ERROR_INTERNAL_DEVICE_ERROR"	There was an internal error on the client.

AudioOutputAudioType¶

Values¶

Value	Description
"TTS"	Text-to-Speech audio type.
"MUSIC"	Music audio type.
"NOTIFICATION"	Notification audio type.
"ALARM"	Alarm audio type.
"EARCON"	Earcon audio type.
"COMMUNICATION"	Communication audio type.
"RINGTONE"	Ringtone audio type.

AudioStreamEncoding¶

Values¶

Value	Description
"UNKNOWN"	Unknown encoding type.
"LPCM"	LPCM encoding type.
"MP3"	MP3 encoding type.
"OPUS"	Opus encoding type.

MutedState¶

Values¶

Value	Description
"MUTED"	Muted audio state.
"UNMUTED"	Unmuted audio state.

AudioOutputSourceType¶

Values¶

Value	Description
"URI"	URI source type.
"STREAM"	Stream audio type.

FocusAction¶

Values¶

Value	Description
"REPORT_DUCKING_STARTED"	This action informs Alexa engine that ducking is initiated by platform interface. Highly recommended to provide information so that engine would not override the action.
"REPORT_DUCKING_STOPPED"	This action informs Alexa engine that ducking is stopped by platform interface. Highly recommended to provide information so that engine can duck if required.