Alexa.StepSpeaker Interface 3

Implement the Alexa.StepSpeaker interface in your Alexa skill so that users can control the volume of their entertainment devices that contain audio speakers. For details about entertainment device skills, see Build Smart Home Skills for Entertainment Devices.

Implement this interface for devices that make incremental discrete step adjustments to volume, where the range of volume isn't known. For example, StepSpeaker can increase or decrease the volume by a step of 5, but can't adjust the volume to 50 percent. If your device can set the volume to any integer value in a continuous range of values, implement the Speaker interface instead.

For the list of languages that the Alexa.StepSpeaker interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.

Utterances

The Alexa.StepSpeaker interface uses the pre-built voice interaction model. The following examples show some user utterances:

Alexa, lower the volume on the stereo.
Alexa, volume up twenty on the speakers.

After the user says one of these utterances, Alexa sends a corresponding directive to your skill.

Reportable properties

The Alexa.StepSpeaker interface doesn't define any reportable properties.

Discovery

You describe endpoints that support Alexa.StepSpeaker by using the standard discovery mechanism described in Alexa.Discovery.

Use SPEAKER, TV, STREAMING_DEVICE, GAME_CONSOLE, or other appropriate display category. For the full list of display categories, see display categories.

Discover response example

The following example shows a Discover.Response message for a speaker device that supports the Alexa.StepSpeaker and Alexa.PowerController interfaces. For the full list of recommended interfaces for an entertainment device, see Smart Home Skill Device Templates.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "Unique identifier, preferably a version 4 UUID"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "Unique ID of the endpoint",
          "manufacturerName": "Manufacturer of the endpoint",
          "description": "Smart Speaker by Speaker Maker",
          "friendlyName": "Computer speaker",
          "displayCategories": ["SPEAKER"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.StepSpeaker",
              "version": "3",
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PowerController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "powerState"
                  }
                ],
                "retrievable": true,
                "proactivelyReported": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

Alexa sends the following Alexa.StepSpeaker interface directives to your skill.

AdjustVolume

Support the AdjustVolume directive so that users can adjust the volume on their devices.

The following example shows a user utterance:

Alexa, volume up twenty on Computer Speaker.

AdjustVolume directive example

The following example shows an AdjustVolume directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.StepSpeaker",
      "name": "AdjustVolume",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "volumeSteps": 20
    }
  }
}

AdjustVolume directive payload

The following table shows the payload details for the AdjustVolume directive.

Property Description Type
volumeSteps The amount by which to increase or decrease the volume, relative to the current volume. Valid values are -100 to 100, and positive values increase the volume and negative values decrease the volume. Integer

AdjustVolume response

If you handle an AdjustVolume directive successfully, respond with an Alexa.Response event. The StepSpeaker interface defines no properties, but if you implement other interfaces, include the values of all properties in the context object.

The following example shows an AdjustVolume response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

AdjustVolume directive error handling

If you can't handle an AdjustVolume directive successfully, respond with an Alexa.ErrorResponse event.

SetMute directive

Support the SetMute directive so that users can mute and unmute their devices.

The following example shows a user utterance:

Alexa, mute Computer Speaker.

SetMute directive example

The following example shows a SetMute directive that Alexa sends to your skill.

{
  "directive": {
    "header": {
      "namespace": "Alexa.StepSpeaker",
      "name": "SetMute",
      "messageId": "Unique version 4 UUID",
      "correlationToken": "Opaque correlation token",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "OAuth2.0 bearer token"
      },
      "endpointId": "Endpoint ID",
      "cookie": {}
    },
    "payload": {
      "mute": true
    }
  }
}

SetMute directive payload

The following table shows the payload details for the SetMute directive

Property Description Type
mute True to mute the device, false to unmute the device. Boolean

SetMute response

If you handle a SetMute directive successfully, respond with an Alexa.Response event. The StepSpeaker interface defines no properties, but if you implement other interfaces, include the values of all properties in the context object.

The following example shows a SetMute response.

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "Unique identifier, preferably a version 4 UUID",
      "correlationToken": "Opaque correlation token that matches the request",
      "payloadVersion": "3"
    },
    "endpoint":{
      "endpointId": "Endpoint ID"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.PowerController",
        "name": "powerState",
        "value": "ON",
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 500
      }
    ]
  }
}

SetMute directive error handling

If you can't handle a SetMute directive successfully, respond with an Alexa.ErrorResponse event.