Developer Console

Alexa.SeekController Interface (VSK Fire TV)

When users say to skip ahead or rewind by a specific duration (such as "Alexa, fast forward 5 minutes" or "Alexa, skip ahead 60 seconds"), the Alexa.SeekController interface sends an AdjustSeekPosition directive to your app or Lambda.

Note that directives sent by the SeekController interface (such as the AdjustSeekPosition directive) are different from the fast-forward and rewind operations within the PlaybackController Interface because they include a specific duration for the offset.

Utterances for AdjustSeekPosition directives

Alexa sends AdjustSeekPosition directives to your app (for app-only integrations) or to your Lambda (for cloudside integrations) when users say the following utterances.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

Fast forward thirty seconds

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

Rewind forty seconds

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

Avance de trente secondes

Saute trente secondes

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

rebobina treinta segundos

retrocede diez segundos

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

Avance de trente secondes

Saute trente secondes

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

Rembobine de trente secondes

Retour en arrière de trente secondes

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

spul/spring [Duration] lang? vor/vorwärts

spring [Duration] vorwärts auf [AppName]

spul [DeviceBrand] vor

spring [Duration] auf [DeviceBrand] vor

überspring [Duration] auf [DeviceType]

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

spul zurück

spring zurück

spul/spring für? [Duration] lang? zurück

spring nach hinten für [Duration]

spul [AppName] zurück

spul [AppName] [Duration] zurück

spul [Duration] auf [AppName] zurück

spring rückwärts auf [AppName] für [Duration]

spul auf? [DeviceBrand] zurück

spul [DeviceBrand] [Duration] zurück

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

[Duration] के लिए आगे/forward जाओ [Episode] में fast forward Duration कर दें

[Duration] के लिये [Episode] forward कर दें[MediaType] में [Duration] आगे जाओ[AppName] पर [Duration] आगे जाओ

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

1. पीछे जाना दस seconds

2. rewind करो forty seconds

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

manda avanti l' episodio di trenta secondi

vai avanti di trenta secondi

manda avanti di trenta secondi

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

manda indietro di trenta secondi

manda indietro il video di trenta secondi

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

rebobinar/voltar [durastion]

The media rewinds for the requested duration.

Feature Sample Utterances Expected Response
Fast Forward [duration]
Required for certification

adelanta treinta segundos

salta diez minutos en la película

The media fast-forwards for the requested duration.

Rewind [duration]
Required for certification

rebobina treinta segundos

retrocede diez segundos

The media rewinds for the requested duration.

As with other directives, when you receive a Discovery directive, you must specify the SeekController directives that your video skill supports.

Handling AdjustSeekPosition Directives

AdjustSeekPosition directives include a property in the payload called deltaPositionMilliseconds. The value of deltaPositionMilliseconds can be positive (seek forward) or negative (go backwards in the stream).

For example, "Skip 5 minutes" would yield a deltaPositionMilliseconds value of 300000, whereas "Rewind 10 minutes" would yield a deltaPositionMilliseconds value of -600000.

In other words, a negative value indicates rewind, and a positive value indicates fast forward. You must fulfill the user's request by going forward by the specified offset.

Example AdjustSeekPosition Directive

The following is an example AdjustSeekPosition directive:

EXTRA_DIRECTIVE_NAMESPACE: Alexa.SeekController
EXTRA_DIRECTIVE_NAME: AdjustSeekPosition
EXTRA_DIRECTIVE_PAYLOAD_VERSION: 3
EXTRA_DIRECTIVE_PAYLOAD: payload

payload contains the following:

{
    "payload": {
    "experience": {
        "mode": "VOICE_OPTIMIZED",
         },
        "deltaPositionMilliseconds": 300000
    }
}
{
    "directive": {
        "endpoint": {
            "cookie": {},
            "endpointId": "VSKTV",
            "scope": {
                "token": "<an OAuth2 bearer token>",
                "type": "BearerToken"
            }
        },
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "4bef62cc-208d-4382-a43e-ce9e4825c1cb",
            "name": "AdjustSeekPosition",
            "namespace": "Alexa.SeekController",
            "payloadVersion": "3"
        },
        "payload": {
           "experience": {
              "mode": "VOICE_OPTIMIZED",
                  },
            "deltaPositionMilliseconds": 300000
        }
    }
}

Payload Definitions

The following table describes the payload properties.

Payload Descriptions
Field Description Data Type
deltaPositionMilliseconds
required
The relative milliseconds to seek on the playback on a media player. A positive or negative integer value could be used to seek forward or backwards in relation to the current seek position. Accepted values include any integer value between -86400000 and 86400000 (-/+ 24 hrs.). If the required position falls outside the duration of the media item, it should be set to the beginning or the end of it depending on if deltaPositionMilliseconds was negative or positive respectively.

Example: 86400000

integer
experience
optional
An object that optimizes the display of search results. With the experience object, you can change the search results based on the device your customer used to search. See Experience Types for more details about the experience object and its values.

Object containing mode

Experience Types

Use the experience object to optimize the display of search results based on the device used to perform the search. For example, if a customers searches from a Fire TV remote, the experience object shows a large number of search results that the customer can browse through with a remote. However, if the search request is from an Echo paired to Fire TV, the experience object limits the number of results shown, and how they are displayed, allowing the customer to see results without using the remote.

The experience object consists of a mode object, which determines how to display the search results. The mode object takes two values: VOICE_OPTIMIZED and DEFAULT.

  • VOICE_OPTIMIZED: The optimized display of search results for voice-only devices. Provides a list of results that customers can navigate via voice, without the need for a remote.

  • DEFAULT: The default displays of all search results list format, regardless of the device used for the search.

To ensure forward compatibility, fallback to DEFAULT instead of failing if you receive an unknown value in mode.

Response Example

If your app handled the directive successfully, your BroadcastReceiver class should send a success intent back with a success status, like this:

if (response != null && sendResponse) {
  Intent success = new Intent().putExtra(VSKIntentConstants.EXTRA_DIRECTIVE_STATUS, didSucceed);
  try {
    response.send(context, 0, success);
  } catch(PendingIntent.CanceledException e) {
    //we probably took too long to respond, log error
  }
}

For more details, see Step 7: Add a Broadcast Receiver. Also see the AlexaDirectiveReceiver class in the sample app for a more specific code example.

After you receive an AdjustSeekPosition directive and run the request, send a response back to Alexa that indicates the position state in milliseconds. The payload contains a name and value property as shown in the following example. The positionMilliseconds represents the absolute achieved seek position in milli seconds from -86400000 to 86400000.

Example

{
    "context": {
        "properties": []
    },
    "event": {
        "header": {
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "messageId": "eab7fe6e-f65d-4dbb-aeea-5bae61439f4d",
            "name": "Response",
            "namespace": "Alexa",
            "payloadVersion": "3"
        },
        "payload": {}
    }
}

If you cannot complete the customer request for some reason, reply with an error. See Error Handling for more details.

Declaring Capability Support for this Interface

To receive SeekController directives in your app, you must indicate support for this interface when you declare your capabilities. See the following for more information on declaring capabilities with app-only integrations:

To indicate that your video skill supports the Alexa.SeekController interface, you must indicate support for it in your response to the Discover directive sent through the Alexa.Discovery interface. More details are provided in Alexa.Discovery.


Last updated: Jun 09, 2021