Skip to content

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