Alexa.PlaybackController Interface

The Alexa.PlaybackController interface describes messages that are used to play, stop, and navigate playback for audio or video content.

For the list of locales that are supported for the PlaybackController interface, see List of Capability Interfaces and Supported Locales.

Discovery

You must specify the directives your endpoint supports when you describe it in your discovery response. You indicate the operations the endpoint supports by including a supportedOperations array.

Supported operations values:

Example discovery response with supportedOperations

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"abc-123-def-456"
    },
    "payload":{
      "endpoints":[
        {
          "capabilities":
          [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.PlaybackController",
              "version": "3",
              "supportedOperations" : ["Play", "Pause", "Stop"]
            }
          ]
        }
      ]
    }
  }
}

Directives

FastForward

Request to fast forward the current content.

English

User: Alexa, fast forward on device

German (Deutsche)

User: Alexa, spule auf dem gerät vor

French (français)

User: Alexa, mets en avance rapide l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "FastForward",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Next

Request to go to the next item in content playback.

English

User: Alexa, next song/video/photo on device
User: Alexa, go forward on device

German (Deutsche)

User: Alexa, nächstes lied/video/foto auf dem gerät
User: Alexa, geh vorwärts auf dem gerät

French (français)

User: Alexa, mets la chanson/la video/la photo suivante sur l'appareil
User: Alexa, mets en avance rapide sur l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Next",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Pause

Request to pause the playback of audio or video content.

English

User: Alexa, pause device

German (Deutsche)

User: Alexa, pausiere gerät

French (français)

User: Alexa, pause l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Pause",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {}
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Play

Request to play or resume play of audio or video content.

English

User: Alexa, resume device
User: Alexa, play device

German (Deutsche)

User: Alexa, gerät fortsetzen
User: Alexa, gerät abspielen

French (français)

User: Alexa, Remets lecture sur l'appareil
User: Alexa, mets lecture sur l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Play",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {
      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Previous

Request to go to the previous item in content playback.

English

User: Alexa, previous on device

German (Deutsche)

User: Alexa, geh zurück auf gerät

French (français)

User: Alexa, chaîne précédente

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Previous",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Rewind

Request to rewind the current content.

English

User: Alexa, rewind on device

German (Deutsche)

User: Alexa, spule auf Gerät zurück

French (français)

User: Alexa, reviens en arrière sur l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Rewind",
      "messageId": "c8d53423-b49b-48ee-9181-f50acedf2870",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

StartOver

A request to start playback from the beginning of the audio or visual content.

English

User: Alexa, start over on device

German (Deutsche)

User: Alexa, gerät neustarten

French (français)

User: Alexa, reprends la lecture sur l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "StartOver",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      },
      "payload": {}
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Stop

Request to stop playback of audio or video content.

English

User: Alexa, stop device

German (Deutsche)

User: Alexa, stoppe gerät

French (français)

User: Alexa, arrête l'appareil

Example request

{
  "directive": {
    "header": {
      "namespace": "Alexa.PlaybackController",
      "name": "Stop",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "device-001",
      "cookie": {

      }
    },
    "payload": {
    }
  }
}

Payload details

Field Description Type Required
None No required or optional fields in the payload. N/A N/A

Properties and Events

For this capability, you must reply:

  • Synchronously, which means you send a Response to Alexa from the Lambda function.

When you send a Response, you should include the state of the interface properties in the context of the message.

Properties

The Alexa.PlaybackController interface doesn't define any reportable properties at this time.

Response

If any of the directives in this interface successfully complete, you should send a response event.

Example Response

{
  "context": {
    "properties": []
  },
  "event": {
    "header": {
      "messageId": "abc-123-def-456",
      "namespace": "Alexa",
      "name": "Response",
      "payloadVersion": "3"
    },
    "endpoint":{
       "endpointId":"appliance-001"
    },
    "payload":{ }
 }
}

ErrorResponse

You should reply with an error if you cannot complete the customer request for some reason. See Alexa.ErrorResponse for more details.

Additional Sample Code

See the sample request and response messages in the Alexa smart home GitHub repo:

PlaybackController

Interface Description
Alexa.RemoteVideoPlayer Provides directives for searching and playing content.
Alexa.PlaybackStateReporter Provides events for reporting the state of playback endpoints.