Alexa.SeekController Interface

The Alexa.SeekController interface provides directives to navigate to a specific position in a media item. You should implement this interface for your devices and services that can seek to a specific position. If a device or service can only fast forward or rewind a media item, implement the Alexa.PlaybackController interface instead.

For the list of languages that the SeekController interface supports, see List of Alexa Interfaces and Supported Languages.

Utterances

When you use the Alexa.SeekController interface, the voice interaction model is already built for you. After the customer says one of the following utterances, Alexa sends a corresponding directive to your skill.

The following examples show some customer utterances:

Alexa, skip 30 seconds on device.
Alexa, go back 10 seconds on device.

Alexa, springe dreißig Sekunden auf dem Gerät vor.
Alexa, springe zehn Sekunden auf dem Gerät zurück.

Properties

The positionMilliseconds property

The Alexa.SeekController interface uses the positionMilliseconds property as the primary property. The positionMilliseconds property is an integer that represents the current absolute time position in a media item. The valid range is 0 — 86400000, inclusive.

positionMilliseconds example

{
   "name":"positionMilliseconds",
   "value": 5000
}

Discovery

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

For the Alexa.SeekController interface, include the positionMilliseconds property and set retrievable and proactivelyReported to false.

Discover response example

The following example shows a Discover.Response message for a device that supports the Alexa.SeekController.

Copied to clipboard.

{
  "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": "<a description that is shown in the Alexa app>",
          "friendlyName": "<device name, displayed in the Alexa app>",
          "displayCategories": ["TV"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SeekController",
              "version": "3",
              "properties": {
                  "supported": [
                      {
                          "name": "positionMilliseconds"
                      }
                  ],
                  "proactivelyReported": false,
                  "retrievable": false
              },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

Directives

AdjustSeekPosition directive

You can send the AdjustSeekPosition directive to request a relative adjustment to the playback position of a media item.

AdjustSeekPosition directive payload details

Field Description Type Required

deltaPositionMilliseconds

The number of milliseconds, relative to the current seek position, to move forward or backward in playback in the media item. Use a positive number to seek forward and a negative number to seek backward. If the required position falls outside the duration of the media item, set the position to the beginning if deltaPositionMilliseconds is negative or the end of the item if deltaPositionMilliseconds is positive.
Valid range between –86400000 and 86400000. This range is equivalent to +/- 24 hours.

Integer

Yes

AdjustSeekPosition directive example

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

{
  "directive": {
    "header": {
      "namespace": "Alexa.SeekController",
      "name": "AdjustSeekPosition",
      "messageId": "abc-123-def-456",
      "payloadVersion": "3"
    },
    "endpoint": {
      "endpointId": "videoDevice-001",
      "cookie": {
        "key": "value"
      },
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      }
    },
    "payload": {
      "deltaPositionMilliseconds": -30000
    }
  }
}

AdjustSeekPosition response event

If you handle a AdjustSeekPosition directive successfully, respond with an Alexa.Response event. In the context object, include the value of the positionMilliseconds property.

Apply the deltaPositionMilliseconds, specified in the AdjustSeekPosition directive, to the current playback position and set the results in the positionMilliseconds property. The value of positionMilliseconds should never be negative. If the delta would cause the new playback position to be less than 0, return 0.

For example, if playback is at 00:05:30 (5 minutes and 30 seconds) or 330000 milliseconds and a customer says, "rewind 30 seconds", Alexa sends an AdustSeekPosition directive with a deltapositionMilliseconds value of –30000. The AdjustSeekPosition response includes the positionMilliseconds with a value of 300000, which is equal to the previous position minus the delta.

AdjustSeekPosition response event example

Copied to clipboard.

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<message id>",
      "correlationToken": "<an opaque correlation token>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<an OAuth2 bearer token>"
      },
      "endpointId": "<endpoint id>"
    },
    "payload": {}
  },
  "context": {
      "properties": [
      {
        "namespace": "Alexa.SeekController",
        "name": "positionMilliseconds",
        "value": 300000,
        "timeOfSample": "2017-02-03T16:20:50.52Z",
        "uncertaintyInMilliseconds": 0
      }
    ]
  }
}

AdjustSeekPosition directive error handling

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

StateReport event