AudioOutput¶

Outgoing Messages¶

Prepare¶

Requests the application to prepare audio from the specified URL for playback. Do not begin playback until receiving a Play message.

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	The name of the audio channel that provides this audio item.
audioType	AudioOutputAudioType	Yes	The type of audio data to be played.
token	String	Yes	The token to uniquely identifies the requested audio item. All further messages for the same audio item use the same `token` and `channel` name.
source	String	Yes	The source type of the audio data to download.
url	String	Yes	The URL of the audio to download.
repeating	Bool	Yes	Whether the application should repeat playback of the audio once it finishes.
playbackContext	PlaybackContext	Yes	Additional context related to playback of the audio item.

Prepare¶

Requests the application to prepare audio from a stream. Open the stream in the Engine by calling MessageBroker::openStream(), specifying the streamId and the operation mode MessageStream::Mode::READ. To retrieve the audio data for your buffer, repeatedly call MessageStream::read() on the stream object until MessageStream::isClosed() returns true. Do not begin playback until receiving a Play message.

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	The name of the audio channel that provides this audio item.
audioType	AudioOutputAudioType	Yes	The type of audio data to be played.
token	String	Yes	A unique token for this audio stream.
source	String	Yes	The source type of the audio data to download.
streamId	String	Yes	The ID of the stream in the Engine. Use the ID when invoking `MessageBroker` for the stream's data.
repeating	Bool	Yes	Whether the application should repeat playback of the audio once it finishes.
encoding	AudioStreamEncoding	Yes	The stream encoding format, if known.
properties	dict	Yes	A list of properties associated with the audio stream.

MayDuck¶

Notifies the application if the specified audio item is allowed to attenuate and play concurrently alongside a higher priority channel.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

Play¶

Requests the application to play the specified audio item. The application is required to respond with either a MediaStateChanged message with state PLAYING when the playback starts or a MediaError message if playback is not possible.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

Pause¶

Requests the application to pause the specified audio item. The application is required to respond with either a MediaStateChanged message with state STOPPED when the playback pauses or a MediaError message if pausing is not possible.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The unique token of the audio source being paused.

Resume¶

Requests the application to resume the specified audio item. The application is required to respond with either a MediaStateChanged message with state PLAYING when the playback resumes or a MediaError message if resuming is not possible.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

Stop¶

Notifies the application to stop the specified audio item. The application is required to respond with either a MediaStateChanged message with state STOPPED when the playback stops or a MediaError message if stopping is not possible.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

SetPosition¶

Requests the application to seek to a specific offset in the specified audio item.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.
position	Int	Yes	The playback position in milliseconds to set in the media player.

GetPosition¶

Requests the current playback position of the specified audio item. Respond with the synchronous-style reply message. If the specififed audio source is not playing, use the most recent position.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

GetDuration¶

Requests the duration of the specified audio item. Respond with the synchronous-style reply message.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

GetNumBytesBuffered¶

Requests the total number of bytes buffered for the specified audio item. Respond to the message with its synchronous-style reply.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

VolumeChanged¶

Notifies the application that the volume has changed for the specified audio item.

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	The name of the audio channel that provides this audio item.
volume	Float	Yes	The volume to set on the audio channel. The volume is in the range [0,1] and should be used as a multiplier for the platform-specific player's actual volume range.

MutedStateChanged¶

Notifies the application that the mute state has changed for the specified audio item.

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	The name of the audio channel that provides this audio item.
state	MutedState	Yes	The muted state to apply to the audio channel.

StartDucking¶

Notifies the application to attenuate playback for the specified audio item. The ducking implementation the application should may be platform-specific.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

StopDucking¶

Notifies the application to restore the playback of the specified audio item to a non-attenuated state.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.

Incoming Messages¶

MediaStateChanged¶

Notifies the Engine of an audio playback state change in the application. Play, Pause, Stop, and Resume messages all require a MediaStateChanged or MediaError response. MediaStateChanged with state STOPPED that is not in response to Pause or Stop is treated as playback finishing, so media may advance to the next item in a playlist if applicable.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.
state	MediaState	Yes	The new playback state of the media player.

MediaError¶

Notifies the Engine of an error during audio playback. Use this message if playback encounters a fatal error that stops playback such that it cannot resume or in place of a MediaStateChanged message if a requested operation like Pause or Play cannot be performed.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.
error	MediaError	Yes	The type of error.
description	String	No	A brief description of the error.

AudioFocusEvent¶

Notify the Engine of an audio focus event affecting the application's playback.

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	The name of the audio channel that provides this audio item.
token	String	Yes	The token that uniquely identifies the requested audio item.
focusAction	FocusAction	Yes	The type of the focus event.

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 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 audio item. If the duration is unknown due to an error, reply with -1.

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 total number of bytes of audio data buffered. Use 0 if there is no audio buffered yet or the number is unknown.

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¶

Describes the state of the audio item in the media player.

Values¶

Value	Description
"STOPPED"	The media player has stopped playing the audio item. The playback may have paused, stopped, or finished, and the interpretation by the Engine depends on whether the Engine has requested a playback-controlling operation.
"PLAYING"	The media player has started playing the audio item. The playback may be starting for the first time, resuming from pause, or recovering from a buffer underrun.
"BUFFERING"	The media player encountered a buffer underrun that prevents normal playback.

MediaError¶

Describes an error encountered by the media player related to playback for the audio item.

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 device.

AudioOutputAudioType¶

Values¶

Value	Description
"TTS"	Text-to-Speech audio type. E.g., Alexa's response as part of a dialog with the user.
"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"	Notifies the Engine that the application has attenuated the audio playback.
"REPORT_DUCKING_STOPPED"	Notifies the Engine that the application has restored the audio playback from the attenuated state.