Microphone Capability Interface

The Microphone capability comprises the mechanics that enable a device to send the user's speech to AIA.

It defines messages on the directive and event topics, as well as sending binary audio data on the microphone topic.

• Getting Started
  • AIA Envelope
  • Topic Management
  • Capability Assertion
• directive Topic
  • OpenMicrophone
  • CloseMicrophone
• event Topic
  • MicrophoneOpened
  • MicrophoneClosed
  • OpenMicrophoneTimedOut
• microphone Topic
  • Audio Data

Getting Started

AIA Envelope

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

Topic Management

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

Capability Assertion

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

Sample Object

{
  "type": "AisInterface",
  "interface": "Microphone",
  "version": "1.0",
  "configurations": {
    "audioEncoder": {
      "format": "{{STRING}}"
    }
  }
}

directive Topic

OpenMicrophone

The OpenMicrophone directive instructs the device to open the microphone and prepare to send the audio stream in subsequent messages on the microphone topic.

The device must respond with a MicrophoneOpened event, unless the microphone was already open (in which case the directive may be ignored).

The device must continue sending audio data on the microphone topic until the device receives a CloseMicrophone directive or the device detects the end of the user's speech. When the device closes the microphone, it must send the MicrophoneClosed event.

Note: If the device is unable to open the microphone before the given timeoutInMilliseconds elapses, it must send the OpenMicrophoneTimedOut event. In that case, it must not send the MicrophoneOpened event.

Sample Message

{
  "header": {
    "name": "OpenMicrophone",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "timeoutInMilliseconds": {{LONG}},
    "initiator": {{OBJECT}}
    }
  }
}

Payload Parameters

CloseMicrophone

The CloseMicrophone directive instructs the device to stop sending audio through the microphone topic and close the microphone.

The device must respond with a MicrophoneClosed event, unless the microphone was already closed.

Note: There will be no payload object in this directive.

Sample Message

{
  "header": {
    "name": "CloseMicrophone",
    "messageId": "{{STRING}}"
  }
}

event Topic

MicrophoneOpened

The device must send the MicrophoneOpened event both

• in response to the OpenMicrophone directive and
• when the user initiates a voice interaction, such as through an on-device wake word detection or a push-to-talk button press.

The device must send the event as soon as it starts streaming audio on the microphone topic.

Notes:

• The device must continue streaming audio on the microphone topic until it receives a CloseMicrophone directive or detects the end of the user's speech.
• If the microphone is already open from a previous MicrophoneOpened event, this event must not be sent again until a MicrophoneClosed event has been sent.
• If audio is actively playing from the speaker topic when the device detects a new microphone interaction, the device may optionally stop playing the audio. If it does so, it must send a SpeakerClosed event before sending this MicrophoneOpened event.

Sample Message

{
  "header": {
    "name": "MicrophoneOpened",
    "messageId": "{{STRING}}"
  },
  "payload": {
    "profile": "{{STRING}}",
    "initiator": {
      "type": "{{STRING}}",
      "payload": {
        "wakeWord": "{{STRING}}",
        "wakeWordIndices": {
          "beginOffset": {{LONG}},
          "endOffset": {{LONG}}
        }
      }
    },
    "offset": {{LONG}}
  }
}

Payload Parameters

MicrophoneClosed

The device must send the MicrophoneClosed event whenever it closes the microphone and stops sending an audio stream on the microphone topic.

The device may have closed the microphone as a result of receiving the CloseMicrophone directive, because it detected the end of the user's speech, or because the microphone button was released in a PRESS_AND_HOLD interaction.

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

Sample Message

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

Payload Parameters

OpenMicrophoneTimedOut

The device must send the OpenMicrophoneTimedOut event if the user did not activate the microphone before the timeoutInMilliseconds elapsed in an OpenMicrophone directive. In this case, the device must not send the MicrophoneOpened event.

This is only applicable on push-to-talk and similar devices that require the user's interaction to open the microphone.

Note: There will be no payload object in this directive.

Sample Message

{
  "header": {
    "name": "OpenMicrophoneTimedOut",
    "messageId": "{{STRING}}"
  }
}

microphone Topic

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

An ongoing stream of sequential audio segments is published to this topic, with each message containing raw linear PCM samples without framing.

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 Microphone interface's capability assertion.

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

Audio Data

The device should publish microphone data in relatively small chunks to reduce the latency of Alexa's response. The device's available memory and latency goals will determine the precise sizes, but the general recommendation is send messages on the microphone topic no more frequently than every 50 milliseconds, consistent with the MQTT publishing rate. This will typically result in audio chunks of about 1.6 KiB in size.