Speaker Capability Interface

The Speaker capability comprises the mechanics that enable a device to output audio through a speaker.

It defines messages on the directive and event topics, as well as receipt of binary data on the speaker topic.

• Getting Started
  • AIA Envelope
  • Topic Management
  • Capability Assertion
• directive Topic
  • OpenSpeaker
  • CloseSpeaker
  • SetVolume
• event Topic
  • ButtonCommandIssued
  • SpeakerOpened
  • SpeakerClosed
  • SpeakerMarkerEncountered
  • VolumeChanged
• speaker Topic
  • Audio Data
  • Marker Data
  • Full MQTT Payload Structure Example

Getting Started

AIA Envelope

This capability interface is compatible with v1 of the AIA envelope.

Topic Management

To support Speaker 1.0 messages, the device must participate in the directive, event, and speaker MQTT topics.

Capability Assertion

To use the Speaker 1.0 interface, the device must assert support through the Publish message on the capabilities topic.

Sample Object

{
  "type": "AisInterface",
  "interface": "Speaker",
  "version": "1.0",
  "configurations": {
    "audioBuffer": {
      "sizeInBytes": {{LONG}},
      "reporting": {
        "overrunWarningthreshold": {{LONG}},
        "underrunWarningThreshold": {{LONG}}
      }
    },
    "audioDecoder": {
      "format": "{{STRING}}",
      "bitrate": {
        "type": "{{STRING}}",
        "bitsPerSecond": {{LONG}}
      },
      "numberOfChannels": {{LONG}}
    }
  }
}

directive Topic

OpenSpeaker

The OpenSpeaker directive instructs the device to open the speaker and prepare to play an audio stream sent in subsequent messages on the speaker topic.

The device must respond with a SpeakerOpened event.

Subsequent audio data sent on the speaker topic must be played until the device receives a CloseSpeaker directive or the user initiates a stop locally via a physical or GUI button or barge-in. After audio playback is stopped through any of these means, the device must send the SpeakerClosed event.

Note: When the device first opens the speaker, its audio buffer may be empty. In this case, the device does not need to send a BufferStateChanged event indicating UNDERRUN. However, if the device does not receive audio data on the speaker topic within 10 seconds of receiving this directive, it should close the AIA connection.

Sample Message

{
  "header": {
    "name": "OpenSpeaker",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "offset": {{LONG}}
  }
}

Payload Parameters

CloseSpeaker

The CloseSpeaker directive instructs the device to stop playing audio through the speaker topic and close the speaker.

The device must respond with a SpeakerClosed event.

Note: If the speaker is already closed due to a local stop (eg, caused by MicrophoneOpened or ButtonCommandIssued), the speaker should remain closed, and the device should not send the SpeakerClosed event.

Sample Message

{
  "header": {
    "name": "CloseSpeaker",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "offset": {{LONG}}
  }
}

Payload Parameters

SetVolume

The SetVolume directive instructs the device to adjust its speaker volume. This applies to the binary audio sent over the speaker topic.

The device must respond with a VolumeChanged event.

Note: AIA manages muting and unmuting through this directive, persisting previous volume levels in the cloud service and restoring them as appropriate. There are no separate messages for muting functionality.

Sample Message

{
  "header": {
    "name": "SetVolume",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "volume": {{LONG}}
    "offset": {{LONG}}
  }
}

Payload Parameters

event Topic

ButtonCommandIssued

The device sends the ButtonCommandIssued event to inform AIA of a user-initiated action related to audio playback control. For example, if a user presses a physical or GUI button to stop audio playback, the device should send this event with the correlative payload.

For button presses that stop or pause audio playback, the device may optionally run that action immediately, rather than waiting for a CloseSpeaker directive. In that case, the device must also immediately send the SpeakerClosed event and report the last offset played from the audio stream on the speaker topic.

Sample Message

{
  "header": {
    "name": "ButtonCommandIssued",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "command": "{{STRING}}"
  }
}

Payload Parameters

SpeakerOpened

The device must send the SpeakerOpened event in response to the OpenSpeaker directive, as soon as it begins playing an audio stream from the speaker topic.

Sample Message

{
  "header": {
    "name": "SpeakerOpened",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "offset": {{LONG}}
  }
}

Payload Parameters

SpeakerClosed

The device must send the SpeakerClosed event whenever it closes the speaker, as soon as it stops playing an audio stream from the speaker topic.

The device may have closed the speaker as a result of receiving the CloseSpeaker directive or a local trigger, such as a button press (see the ButtonCommandIssued directive) or a user barge-in (see the MicrophoneOpened event).

If the speaker was already closed and this event was already sent, it should not be sent again in response to a subsequent CloseSpeaker directive.

Note: If the audio buffer underruns, the device should send a BufferStateChanged event with the UNDERRUN state, not a SpeakerClosed event.

Sample Message

{
  "header": {
    "name": "SpeakerClosed",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "offset": {{LONG}}
  }
}

Payload Parameters

SpeakerMarkerEncountered

The device must send the SpeakerMarkerEncountered event for each marker it encounters in the audio stream of the speaker topic. The event must not be sent until all the audio preceding that marker has been played to the user.

If the marker is the first message in the speaker audio stream, the device must send the SpeakerMarkerEncountered event at the same time it begins playing audio to the user.

These markers and this event give Alexa updated information about audio playback progress.

Sample Message

{
  "header": {
    "name": "SpeakerMarkerEncountered",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "marker": {{LONG}}
  }
}

Payload Parameters

VolumeChanged

The device must send the VolumeChanged event whenever its volume has changed and in response to the SetVolume directive.

The device may have changed its volume as a result of receiving the SetVolume directive or a local trigger, such as a physical or GUI button.

This event must always be sent in response to the SetVolume directive, even if the volume is the same as the previously set value.

Sample Message

{
  "header": {
    "name": "VolumeChanged",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "volume": {{LONG}},
    "offset": {{LONG}}
  }
}

Payload Parameters

speaker Topic

AIA sends binary audio data in the binary stream format to the device using the speaker topic.

An ongoing stream of sequential audio segments is published to this topic, with each message containing one or more audio frames.

Control messages for audio output to the user are communicated through events and directives on the event and directive topics, respectively. The audio data format is specified on the capabilities topic through the Speaker interface's capability assertion.

After the common header that is a part of every message using the v1 envelope format, messages on the speaker topic will include a binary stream header with the values specified below.

Audio Data

Marker Data

Periodically, AIA will send a marker message to your device on the speaker topic, instead of audio stream data. The device must respond with the SpeakerMarkerEncountered event. These markers and the SpeakerMarkerEncountered event give Alexa updated information about audio playback progress.

Full MQTT Payload Structure Example

The following is an example of the structure of a full MQTT payload on the speaker topic, containing two marker messages and two audio messages, each audio message containing more than one frame. For convenience in offset calculations, it is presented as the first MQTT message on the speaker topic since the last connection was established: all offsets start at 0.

Notes:

• The example payload in this section is the entire AIA message, which is the payload of the general AWS IoT MQTT message.
• The index specified in the "Message" column of the table indicates the value used by the index field in control plane messages, such as ExceptionEncountered. Each index number represents a separate binary stream message within the MQTT message.