Alexa.StepSpeaker Interface

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 more information 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 StepSpeaker interface supports, see List of Alexa Interfaces and Supported Languages.

• Utterances
• Discovery
• Directives
  • AdjustVolume
  • SetMute directive

Utterances

When you use the Alexa.StepSpeaker interface, the voice interaction model is already built for you. The following examples show some user utterances:

• English (All)

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

Discovery

You describe endpoints that support Alexa.StepSpeaker 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.

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<message id>"
    },
    "payload": {
      "endpoints": [
        {
          "endpointId": "<unique ID of the endpoint>",
          "manufacturerName": "<the manufacturer name 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

AdjustVolume

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

The following example shows a user utterance:

• English

AdjustVolume directive payload details

AdjustVolume directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.StepSpeaker",
      "name": "AdjustVolume",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "volumeSteps": 20
    }
  }
}

AdjustVolume response event

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.

AdjustVolume response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "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:

• English

SetMute directive payload details

SetMute directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.Speaker",
      "name": "SetMute",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>",
      "cookie": {}
    },
    "payload": {
      "mute": true
    }
  }
}

SetMute response event

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.

SetMute response event example

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "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.